ktx/docs/superpowers/plans/2026-05-11-managed-runtime-prune-smoke-and-docs.md

Managed Runtime Prune Smoke and Docs Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Prove and document ktx runtime prune as part of the npm-managed Python runtime release contract.

Architecture: The prune command already exists in the CLI runtime layer, so this plan adds black-box package smoke coverage and public documentation only. The smoke creates an isolated stale versioned runtime directory, previews it, verifies confirmation is required, and removes it through the installed @kaelio/ktx package.

Tech Stack: Node 22 ESM scripts, node:test, pnpm, Markdown, KTX CLI managed Python runtime.

---

Current state

This plan follows docs/superpowers/specs/2026-05-11-npm-managed-python-runtime-design.md.

The following plan files are based on that spec and are implemented in the current tree:

• docs/superpowers/plans/2026-05-11-bundled-python-runtime-wheel.md
• docs/superpowers/plans/2026-05-11-managed-python-runtime-installer.md
• docs/superpowers/plans/2026-05-11-managed-python-runtime-command-integration.md
• docs/superpowers/plans/2026-05-11-managed-python-runtime-daemon-lifecycle.md
• docs/superpowers/plans/2026-05-11-managed-local-embeddings-runtime.md
• docs/superpowers/plans/2026-05-11-public-kaelio-ktx-npm-package.md
• docs/superpowers/plans/2026-05-11-managed-python-runtime-release-smoke.md
• docs/superpowers/plans/2026-05-11-managed-local-embeddings-release-smoke.md
• docs/superpowers/plans/2026-05-11-managed-agent-mcp-semantic-runtime.md
• docs/superpowers/plans/2026-05-11-managed-local-ingest-daemon-runtime.md
• docs/superpowers/plans/2026-05-11-managed-runtime-docs-and-postgres-smoke-cleanup.md
• docs/superpowers/plans/2026-05-11-published-package-managed-runtime-smoke.md
• docs/superpowers/plans/2026-05-11-public-npm-release-handoff.md

Implementation evidence found before writing this plan includes:

• packages/cli/assets/python/manifest.json and packages/cli/assets/python/kaelio_ktx-0.1.0-py3-none-any.whl.
• packages/cli/src/managed-python-runtime.ts, including installManagedPythonRuntime(), doctorManagedPythonRuntime(), and pruneManagedPythonRuntimes().
• packages/cli/src/runtime.ts, including the install, status, doctor, start, stop, and prune runtime command runner branches.
• packages/cli/src/commands/runtime-commands.ts, including the runtime prune --dry-run and runtime prune --yes Commander wiring.
• scripts/build-public-npm-package.mjs, scripts/package-artifacts.mjs, scripts/published-package-smoke.mjs, scripts/local-embeddings-runtime-smoke.mjs, scripts/publish-public-npm-package.mjs, release-policy.json, and .github/workflows/release.yml.
• README.md and examples/package-artifacts/README.md document the managed runtime but do not mention ktx runtime prune.

The remaining gap is narrow: the spec lists ktx runtime prune as part of the runtime management command family, but public docs and installed package smoke coverage only prove install, status, doctor, start, and stop.

File structure

• Modify scripts/package-artifacts.test.mjs: assert that the generated installed npm smoke covers ktx runtime prune --dry-run, confirmation failure, and confirmed deletion.
• Modify scripts/package-artifacts.mjs: extend npmRuntimeSmokeSource() to create a stale runtime directory and exercise ktx runtime prune.
• Modify scripts/examples-docs.test.mjs: require public docs to mention ktx runtime prune --dry-run and ktx runtime prune --yes.
• Modify README.md: add prune commands and one sentence describing preview and confirmed deletion.
• Modify examples/package-artifacts/README.md: describe prune coverage in the package artifact smoke.

Task 1: Add installed package prune smoke coverage

Files:

• Modify: scripts/package-artifacts.test.mjs

• Modify: scripts/package-artifacts.mjs

• Step 1: Add failing smoke-source assertions

In scripts/package-artifacts.test.mjs, inside it('runs installed CLI commands through the public package runtime', () => { and immediately after the existing assertions for ktx runtime stop, add:

    assert.match(source, /ktx runtime prune dry run/);
    assert.match(source, /0\.0\.0/);
    assert.match(source, /ktx runtime prune needs confirmation/);
    assert.match(source, /Refusing to prune without --yes/);
    assert.match(source, /ktx runtime prune confirmed/);
    assert.match(source, /Removed stale KTX Python runtimes/);
    assert.match(source, /assert\.rejects\(\(\) => access\(staleRuntimeDir\)\)/);

• Step 2: Run the package artifact test and verify failure

Run:

node --test scripts/package-artifacts.test.mjs

Expected: FAIL in the installed CLI smoke source test because npmRuntimeSmokeSource() does not yet contain the prune labels, confirmation guard, or stale runtime removal assertion.

• Step 3: Extend the generated installed CLI smoke

In scripts/package-artifacts.mjs, inside npmRuntimeSmokeSource(), add this block immediately after:

  process.stdout.write('ktx runtime daemon lifecycle verified\n');

Add:

  const staleRuntimeDir = join(process.env.KTX_RUNTIME_ROOT, '0.0.0');
  await mkdir(staleRuntimeDir, { recursive: true });

  const runtimePruneDryRun = await run('pnpm', ['exec', 'ktx', 'runtime', 'prune', '--dry-run']);
  requireSuccess('ktx runtime prune dry run', runtimePruneDryRun);
  requireOutput('ktx runtime prune dry run', runtimePruneDryRun, /Stale KTX Python runtimes/);
  requireOutput('ktx runtime prune dry run', runtimePruneDryRun, /0\.0\.0/);
  await access(staleRuntimeDir);

  const runtimePruneNeedsConfirmation = await run('pnpm', ['exec', 'ktx', 'runtime', 'prune']);
  assert.equal(runtimePruneNeedsConfirmation.code, 1, 'ktx runtime prune without --yes must fail');
  assert.equal(runtimePruneNeedsConfirmation.stdout, '', 'ktx runtime prune confirmation failure wrote stdout');
  assert.match(runtimePruneNeedsConfirmation.stderr, /Refusing to prune without --yes/);

  const runtimePruneConfirmed = await run('pnpm', ['exec', 'ktx', 'runtime', 'prune', '--yes']);
  requireSuccess('ktx runtime prune confirmed', runtimePruneConfirmed);
  requireOutput('ktx runtime prune confirmed', runtimePruneConfirmed, /Removed stale KTX Python runtimes/);
  requireOutput('ktx runtime prune confirmed', runtimePruneConfirmed, /0\.0\.0/);
  await assert.rejects(() => access(staleRuntimeDir));
  process.stdout.write('ktx runtime prune verified\n');

No import changes are needed because the generated smoke already imports assert, access, mkdir, and join.

• Step 4: Run the package artifact test and verify pass

Run:

node --test scripts/package-artifacts.test.mjs

Expected: PASS. The source assertions now find prune dry-run coverage, confirmation failure coverage, confirmed prune coverage, and stale directory deletion verification.

• Step 5: Commit the smoke coverage

Run:

git add scripts/package-artifacts.mjs scripts/package-artifacts.test.mjs
git commit -m "test: cover managed runtime prune in package smoke"

Task 2: Document runtime prune in public docs

Files:

• Modify: scripts/examples-docs.test.mjs

• Modify: README.md

• Modify: examples/package-artifacts/README.md

• Step 1: Add failing docs assertions

In scripts/examples-docs.test.mjs, inside it('documents public npm and managed runtime usage in the README', async () => { and immediately after:

    assert.match(rootReadme, /ktx runtime stop/);

Add:

    assert.match(rootReadme, /ktx runtime prune --dry-run/);
    assert.match(rootReadme, /ktx runtime prune --yes/);

In the same file, inside it('documents the public package artifact smoke shape', async () => { and immediately after:

    assert.match(readme, /ktx runtime doctor/);

Add:

    assert.match(readme, /ktx runtime prune --dry-run/);
    assert.match(readme, /ktx runtime prune --yes/);

• Step 2: Run the docs test and verify failure

Run:

node --test scripts/examples-docs.test.mjs

Expected: FAIL because README.md and examples/package-artifacts/README.md do not yet mention ktx runtime prune.

• Step 3: Update the root README runtime section

In README.md, in the ## Managed Python runtime command block, replace:

npx ktx runtime install --yes
npx ktx runtime status
npx ktx runtime doctor
npx ktx runtime start
npx ktx runtime stop

with:

npx ktx runtime install --yes
npx ktx runtime status
npx ktx runtime doctor
npx ktx runtime start
npx ktx runtime stop
npx ktx runtime prune --dry-run
npx ktx runtime prune --yes

Immediately after that command block, add:

Use `runtime prune --dry-run` to preview stale runtime directories from older
CLI versions. Add `--yes` to remove those stale directories after daemon
processes are stopped.

• Step 4: Update package artifact smoke docs

In examples/package-artifacts/README.md, replace:

The managed Python runtime smoke isolates `KTX_RUNTIME_ROOT`, verifies
`ktx runtime status`, runs `ktx sl query --yes` to install the core runtime from
the bundled wheel, checks `ktx runtime doctor`, starts and reuses the managed
daemon, and stops it.

with:

The managed Python runtime smoke isolates `KTX_RUNTIME_ROOT`, verifies
`ktx runtime status`, runs `ktx sl query --yes` to install the core runtime from
the bundled wheel, checks `ktx runtime doctor`, starts and reuses the managed
daemon, stops it, previews a stale runtime with `ktx runtime prune --dry-run`,
verifies confirmation is required, and removes the stale runtime with
`ktx runtime prune --yes`.

• Step 5: Run the docs test and verify pass

Run:

node --test scripts/examples-docs.test.mjs

Expected: PASS. The public README and package artifact README now document runtime prune alongside the other managed runtime commands.

• Step 6: Commit the docs coverage

Run:

git add scripts/examples-docs.test.mjs README.md examples/package-artifacts/README.md
git commit -m "docs: document managed runtime prune"

Task 3: Verify the completed prune release surface

Files:

• Verify: scripts/package-artifacts.mjs

• Verify: scripts/package-artifacts.test.mjs

• Verify: scripts/examples-docs.test.mjs

• Verify: README.md

• Verify: examples/package-artifacts/README.md

• Step 1: Run focused tests

Run:

node --test scripts/package-artifacts.test.mjs scripts/examples-docs.test.mjs

Expected: PASS. The source-level tests cover generated package smoke behavior and docs assertions.

• Step 2: Run the installed package artifact smoke

Run:

pnpm run artifacts:check

Expected: PASS. The generated installed CLI smoke prints:

ktx runtime prune verified

and removes the temporary 0.0.0 directory from the isolated KTX_RUNTIME_ROOT.

• Step 3: Inspect git status

Run:

git status --short

Expected: only the five planned files are modified before the final commit, or no modified files remain after the task commits.

• Step 4: Commit verification fixes if needed

If verification required small corrections, commit only those intended files:

git add scripts/package-artifacts.mjs scripts/package-artifacts.test.mjs scripts/examples-docs.test.mjs README.md examples/package-artifacts/README.md
git commit -m "test: verify managed runtime prune release surface"

Acceptance criteria

• The generated installed npm package smoke creates a stale versioned runtime directory under the isolated KTX_RUNTIME_ROOT.
• ktx runtime prune --dry-run lists the stale runtime and leaves it on disk.
• ktx runtime prune without --yes exits nonzero and prints the existing confirmation guidance.
• ktx runtime prune --yes removes the stale runtime directory.
• README.md lists ktx runtime prune --dry-run and ktx runtime prune --yes with the other managed runtime commands.
• examples/package-artifacts/README.md describes prune coverage in the package artifact smoke.

Self-review

• Spec coverage: this plan covers the remaining visible gap for the runtime management command family in the npm-managed Python runtime spec. The prune implementation already exists, and this plan adds release smoke and public docs coverage.
• Placeholder scan: no placeholder steps, deferred implementation notes, or unspecified behavior gaps remain.
• Type consistency: the plan uses existing labels and functions: npmRuntimeSmokeSource(), requireSuccess(), requireOutput(), KTX_RUNTIME_ROOT, ktx runtime prune --dry-run, and ktx runtime prune --yes.