@jaybeeuu/agent-cortex 2.5.0 → 2.6.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 2.6.0
+
+### Minor Changes
+
+- c14bf85: `ctx version` now reports the installed harness versions beside the running CLI version: one line per installed harness read from the fingerprint its installer wrote (`~/.agent-cortex/pi/package.json`, `~/.agent-cortex/claude/.claude-plugin/plugin.json`), marked `current`, `stale`, `ahead` when the installed copy is newer, or `unknown` when the fingerprint is missing or unreadable. `ctx version --json` prints the same data as records. The command is read-only — no install, no network, no writes — and `--version` still prints the bare CLI version.
+
+### Patch Changes
+
+- ccb1788: Add `skills/workflow/ralph/scripts/prune-worktrees.mjs`, the deterministic pass that converges the
+  ralph worktree set with bead state. It scans `.agent-cortex/worktrees/*`, classifies each directory
+  by its bead as a closed-bead worktree, an open-bead worktree, or an orphan, and removes a
+  closed-bead worktree with its local and remote branch. A dirty tree, a locked worktree, or an
+  unpushed branch refuses that worktree with the reason. Orphans are reported only, and
+  `--remove-orphans` is the single path that removes one.
+
+## 2.5.1
+
+### Patch Changes
+
+- e87b2d0: Align the code, verify, document, and fix REPORT templates on the authoritative
+  `run-pipeline-stage` contract. Each template now emits `STAGE_COMPLETED` with its stage name
+  (`code`, `verify`, `document`, `fix`) plus `COMMIT`, `PUSHED`, `PR`, and
+  `OUTCOME: SUCCESS|BLOCKED`, and lists blocked work under `BLOCKING_ISSUES`. The unparsed
+  `VERIFY_OUTCOME`/`VERIFY_FAILURES` keys are gone, so an orchestrator can route every stage's
+  report.
+- 83ed526: Stop `agent-cortex install claude` erasing Claude Code's `enabledPlugins` entry.
+
+  The settings merge now asserts only the `enabledPlugins` and `extraKnownMarketplaces` entries the
+  committed `claude/settings.json` template declares; entries it does not declare survive, so a
+  same-version re-run keeps the entry Claude Code writes when the plugin is enabled. Registration
+  also reports an installed-but-not-enabled plugin, naming `claude plugin enable <plugin>@<marketplace>`.
+
+- 34bcea7: Type-check the extensions against the pi version that is actually installed.
+
+  The extension workspaces pinned `@earendil-works/pi-coding-agent`, `pi-agent-core`, and `pi-ai` at
+  `^0.78.1` for `import type` only, while `pi --version` reported 1.5.2. `pnpm typecheck` therefore
+  validated against an API that no installed pi provides. The pins now follow the running CLI at
+  `^1.5.2`, and the `agent-modes` `ExtensionAPI` test double gains the members 1.5.x declares:
+  `registerMarkdownTransformer`, `registerEntryRenderer`, `registerToolRenderer`, `registerVirtualModel`,
+  `registerMcpServer`, `unregisterMcpServer`, `getMcpServers`, `unregisterVirtualModel`, and
+  `getSettings`, plus the unsubscribe return value of `on`.
+
+- fa84942: Move the composable agent-directory validator from
+  `skills/productivity/validate-agent-dir/scripts/` to `scripts/validate-agent-dir.mjs`. The
+  directory had no `SKILL.md`, so neither installer shipped it while it still looked like a shipped
+  skill, and the module validates this repository's own `agents/` layout — repo tooling, not a
+  portable skill. Its filesystem probes are now async (`validateAgentDir` returns a promise),
+  matching the no-`*Sync` rule for `scripts/`.
+
+  `agents/README.md` (Validation) and `test/validate-agent-dir.test.mjs` point at the new path. No
+  skill, agent, hook, or installer behaviour changes.
+
 ## 2.5.0
 
 ### Minor Changes

package/README.md

@@ -292,7 +292,8 @@ symlinks), `SessionStart` + `Notification` hooks, and 2 MCP servers — writes a
 manifest at `~/.agent-cortex/.claude-plugin/marketplace.json` exposing `./claude`, and
 registers it with Claude Code, and merges the committed `claude/settings.json` template into
 `~/.claude/settings.json`: the template supplies defaults, personal values win, and the
-installer owns exactly `enabledPlugins` + `extraKnownMarketplaces` — every other key
+installer owns exactly the `enabledPlugins` + `extraKnownMarketplaces` entries the template
+declares — entries it does not declare are left alone — while every other key
 (`permissions`, `hooks`, `env`, `statusLine`, unknown keys) is preserved. It also writes the
 managed section of `~/.claude/CLAUDE.md` — the reply-shape block the pi `output-style`
 extension appends, taken from the same source file — and leaves every other line of that
@@ -360,10 +361,15 @@ agent-cortex install claude --require-register       # register or fail the inst
 
 The install also merges the committed `claude/settings.json` template into
 `~/.claude/settings.json` (the settings file Claude Code reads at user scope). The template
-supplies defaults and personal values win; the installer owns exactly `enabledPlugins` +
-`extraKnownMarketplaces`, so `permissions`, `hooks`, `env`, `statusLine` and unknown keys are
-never touched. A legacy symlinked `settings.json` is replaced with a real file rather than
-written through, and `--output` leaves the user's Claude config alone.
+supplies defaults and personal values win; the installer owns exactly the `enabledPlugins` +
+`extraKnownMarketplaces` entries the template declares, so entries it does not declare (including
+the one Claude Code writes when you enable the plugin) survive, and `permissions`, `hooks`, `env`,
+`statusLine` and unknown keys are never touched. A legacy symlinked `settings.json` is replaced
+with a real file rather than written through, and `--output` leaves the user's Claude config
+alone. When registration finds the plugin installed but the settings do not enable it, the install
+warns and names `claude plugin enable <plugin>@<marketplace>` — a disabled plugin loads nothing.
+That check reads the user-scope file only, so a plugin enabled at project or local scope still
+warns; `claude plugin list` reports the effective state.
 
 It also writes the managed section of `~/.claude/CLAUDE.md` (Claude's user memory), delimited
 by `<!-- BEGIN agent-cortex:output-style -->` / `<!-- END agent-cortex:output-style -->`. The
@@ -472,6 +478,30 @@ re-registers it; `--output <dir>` generates a preview only). The only committed
 so never edit anything under it. CI validates the Claude materialiser (structural checks on
 a temp-dir install) so sources and installer can never silently diverge.
 
+## Checking installed versions (`agent-cortex version`)
+
+`agent-cortex version` prints the running CLI version, then one line for each installed
+harness: its name, the version its installer recorded, and a marker. The fingerprint is the
+manifest the installer already writes — `~/.agent-cortex/pi/package.json` for pi and
+`~/.agent-cortex/claude/.claude-plugin/plugin.json` for Claude Code — so the report needs no
+separate state file.
+
+```sh
+agent-cortex version            # CLI version, then one line per installed harness
+agent-cortex version --json     # the same data as JSON records
+agent-cortex --version          # the bare CLI version, for scripts
+```
+
+The marker is `current` when the installed copy matches the running CLI, `stale` when it is
+older, and `ahead` when it is newer — a downgraded CLI leaves its installs ahead of it. A
+harness root that exists with a missing or broken fingerprint reports `unknown` for both the
+version and the marker, because an install that cannot be read is never reported as `current`.
+Only plain release versions are compared, so a prerelease on either side also reports
+`unknown`. A harness with no installer gets no line.
+
+The command is read-only: it stats and reads those manifests, and never installs, writes, or
+reaches the network.
+
 ## Migrating a beads workspace
 
 `agent-cortex migrate` brings the `.beads` workspace it runs in — any repo, not just this

package/agents/README.md

@@ -245,7 +245,9 @@ agents, token-substituted skills, extensions) at `~/.agent-cortex/pi`.
 
 ## Validation
 
-Use the `validate-agent-dir` script to validate agent directories:
+The composable layout is validated by the repo tooling at `scripts/validate-agent-dir.mjs` — a
+module, not a shipped skill, with no CLI. Import `validateAgentDir` to check a directory, or run
+its test suite:
 
 ```bash
 node --test test/validate-agent-dir.test.mjs

package/bin/agent-cortex.mjs

@@ -1,6 +1,11 @@
 #!/usr/bin/env node
 
 import { parseArgs, buildHelpText, resolveProgramName, validateHarness } from "../lib/cli.mjs";
+import {
+  collectVersionReport,
+  formatVersionReport,
+  serialiseVersionReport,
+} from "../lib/harness-versions.mjs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readFile } from "node:fs/promises";
@@ -45,8 +50,22 @@ async function readPackageVersion() {
 }
 
 if (parsed.command === "version") {
+  if (parsed.optionError) {
+    process.stderr.write(`${parsed.optionError}\n`);
+    process.exit(1);
+  }
   try {
-    process.stdout.write(`${await readPackageVersion()}\n`);
+    const cliVersion = await readPackageVersion();
+    // `--version` prints the bare version for scripts; the `version` subcommand
+    // adds one line per installed harness, read from the installers'
+    // fingerprints (read-only — no install, no network, no writes).
+    if (parsed.report === true) {
+      const report = await collectVersionReport({ cli: cliVersion });
+      const output = parsed.json === true ? serialiseVersionReport(report) : formatVersionReport(report);
+      process.stdout.write(`${output}\n`);
+    } else {
+      process.stdout.write(`${cliVersion}\n`);
+    }
   } catch (err) {
     process.stderr.write(`${/** @type {Error} */ (err).message}\n`);
     process.exit(1);
@@ -120,8 +139,8 @@ if (parsed.command === "install") {
   // materialises the plugin into the home install root (~/.agent-cortex/claude)
   // with copied, token-substituted skills, writes the marketplace manifest at
   // ~/.agent-cortex/.claude-plugin/marketplace.json, merges the committed
-  // claude/settings.json template into ~/.claude/settings.json (owning only
-  // enabledPlugins + extraKnownMarketplaces), and registers it with Claude Code
+  // claude/settings.json template into ~/.claude/settings.json (asserting only
+  // the enabledPlugins + extraKnownMarketplaces entries the template declares), and registers it with Claude Code
   // (marketplace add → install → update); `--output <dir>` is the generate-only
   // form (tests/CI validation), and the generated claude/ plugin subtree is
   // never committed — only the settings template is.
@@ -147,6 +166,9 @@ if (parsed.command === "install") {
           root: /** @type {string} */ (result.marketplaceRoot),
           manifest: /** @type {object} */ (result.marketplaceManifest),
           pluginVersion: result.pluginVersion,
+          // The enablement check reads the same file this install just merged:
+          // a plugin Claude Code does not enable loads nothing.
+          ...(result.settings ? { settingsPath: result.settings.path } : {}),
           dryRun: parsed.dryRun ?? false,
           requireRegister: parsed.requireRegister ?? false,
         });

package/bin/installers/claude.mjs

@@ -85,13 +85,16 @@ const PACKAGE_ROOT = join(MODULE_DIR, "..", "..");
  */
 
 /**
- * Registration plan/outcome returned by registerClaude.
+ * Register plan/outcome returned by registerClaude.
  * @typedef {object} RegisterClaudeResult
  * @property {string} marketplace
  * @property {string} plugin
  * @property {string[][]} commands
  * @property {boolean} dryRun
  * @property {boolean} registered
+ * @property {boolean | null} enabled  Whether the user's settings enable the plugin;
+ *                                     null when the settings could not be read or
+ *                                     its state is unconfirmed.
  * @property {string[]} skipped
  */
 
@@ -400,9 +403,13 @@ async function buildHandAuthored(root) {
  *   - template keys fill in defaults the live file lacks; every value already
  *     present in the live file wins (deeply), and unknown keys are preserved,
  *     so personal config survives re-install;
- *   - `enabledPlugins` and `extraKnownMarketplaces` are CLI-owned: they are
- *     rewritten from the template outright. `permissions`, `hooks`, `env`,
- *     `statusLine` and every other key are never touched.
+ *   - `enabledPlugins` and `extraKnownMarketplaces` are CLI-owned in the other
+ *     direction: the entries the template declares are asserted (the template
+ *     value wins for those), and entries it does not declare are kept. A
+ *     template key that is empty or absent declares nothing and therefore owns
+ *     nothing — silence never deletes, so a re-install cannot erase the entry
+ *     Claude Code writes when the user enables the plugin. `permissions`,
+ *     `hooks`, `env`, `statusLine` and every other key are never touched.
  * @param {{ root: string, target: string, dryRun: boolean, warn: Warn }} options
  * @returns {Promise<ManagedFileResult | null>}
  */
@@ -410,16 +417,32 @@ async function installSettings({ root, target, dryRun, warn }) {
   const template = await readTemplateJson(join(root, SETTINGS_TEMPLATE), warn);
   if (template === null) return null;
 
-  const merged = mergeSettings(template, await readJsonObject(target, warn));
+  const existing = await readJsonObject(target, warn);
+  const merged = mergeSettings(template, existing);
   for (const key of SETTINGS_OWNED_KEYS) {
-    if (key in template) merged[key] = template[key];
-    else delete merged[key];
+    const value = mergeOwnedSetting(template[key], existing[key]);
+    if (value === undefined) delete merged[key];
+    else merged[key] = value;
   }
 
   const content = `${JSON.stringify(merged, null, 2)}\n`;
   return writeManagedFile({ target, content, dryRun });
 }
 
+/**
+ * Merge one CLI-owned settings key. The template asserts the entries it
+ * declares — its value wins for exactly those — and every entry it does not
+ * declare survives from the live file. An empty or absent template key declares
+ * nothing, so the live value passes through untouched: silence never deletes.
+ * @param {unknown} template
+ * @param {unknown} existing
+ * @returns {unknown}
+ */
+function mergeOwnedSetting(template, existing) {
+  if (!isPlainObject(template) || !isPlainObject(existing)) return existing === undefined ? template : existing;
+  return { ...existing, ...template };
+}
+
 /**
  * Merge the committed template over the live file. Template keys fill in
  * defaults, live values win (deeply), and keys the template does not know about
@@ -1045,6 +1068,11 @@ async function pluginLoadVerdict(claudeBin, pluginId) {
  * When that list cannot be read, or does not list the plugin, the load state is
  * unconfirmed: the install warns and skips the success line.
  *
+ * A loaded plugin that the user's settings do not enable loads nothing either:
+ * Claude Code reads `enabledPlugins` from that file, and registration skips the
+ * install as "already installed", so the run warns with the command that fixes
+ * it rather than reporting a working install.
+ *
  * @param {object} options
  * @param {string} [options.root]            Marketplace root carrying .claude-plugin/…
  *                                           (defaults to the repo containing this module)
@@ -1052,6 +1080,8 @@ async function pluginLoadVerdict(claudeBin, pluginId) {
  * @param {boolean} [options.dryRun]         Plan and report without running or writing
  * @param {object} [options.manifest]        Pre-parsed marketplace manifest (skips the file read)
  * @param {string} [options.pluginVersion]   Materialised plugin version (default: read from plugin.json)
+ * @param {string} [options.settingsPath]    Claude user settings the enablement check reads
+ *                                           (default ~/.claude/settings.json)
  * @param {boolean} [options.requireRegister] Exit non-zero when registration cannot run
  * @param {(msg: string) => void} [options.warn] Warning sink (default: console.warn)
  * @returns {Promise<RegisterClaudeResult>}
@@ -1062,6 +1092,7 @@ export async function registerClaude({
   dryRun = false,
   manifest,
   pluginVersion,
+  settingsPath = DEFAULT_SETTINGS_PATH,
   requireRegister = false,
   warn = DEFAULT_WARN,
 } = {}) {
@@ -1072,7 +1103,7 @@ export async function registerClaude({
   const version = pluginVersion ?? (await readMaterialisedPluginVersion(root, manifestObj));
   const home = resolve(root);
 
-  const summary = /** @type {RegisterClaudeResult} */ ({ marketplace, plugin, commands: [], dryRun, registered: true, skipped: [] });
+  const summary = /** @type {RegisterClaudeResult} */ ({ marketplace, plugin, commands: [], dryRun, registered: true, enabled: null, skipped: [] });
   console.log(`Registering plugin "${pluginId}" with Claude Code (via ${claudeBin})…`);
 
   const manualCommands = [
@@ -1156,9 +1187,22 @@ export async function registerClaude({
         `verify with "${claudeBin} plugin list" (restart Claude Code to apply)`,
     );
   } else {
-    console.log(
-      `Installed — verify with "claude plugin list" / "claude plugin details ${plugin}" (restart Claude Code to apply).`,
-    );
+    // Installed but disabled is a plugin that loads nothing: Claude Code gates
+    // every skill and agent on the user's enabledPlugins entry, and the install
+    // path above skips a same-version re-install as "already installed", so
+    // this is the only place that state is reported.
+    const enabled = (await readJsonObject(settingsPath, warn)).enabledPlugins?.[pluginId] === true;
+    summary.enabled = enabled;
+    if (enabled) {
+      console.log(
+        `Installed and enabled — verify with "claude plugin list" / "claude plugin details ${plugin}" (restart Claude Code to apply).`,
+      );
+    } else {
+      warn(
+        `"${pluginId}" is installed but not enabled in ${settingsPath} — Claude Code loads nothing from a disabled plugin; ` +
+          `enable it with "${claudeBin} plugin enable ${pluginId}" and restart Claude Code`,
+      );
+    }
   }
   return summary;
 }

package/extensions/agent-guardrails/package.json

@@ -8,7 +8,7 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@earendil-works/pi-coding-agent": "^1.5.2",
     "@types/node": "^22.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"

package/extensions/agent-modes/index.test.ts

@@ -64,6 +64,8 @@ function createFakePi(flagValues: Record<string, boolean | string> = {}): FakePi
       const list = handlers.get(event) ?? [];
       list.push(handler);
       handlers.set(event, list);
+      // `ExtensionAPI.on` returns an unsubscribe function.
+      return () => {};
     },
     registerFlag: (name, options) => {
       flags.push([name, options]);
@@ -77,8 +79,16 @@ function createFakePi(flagValues: Record<string, boolean | string> = {}): FakePi
     registerShortcut: () => {},
     registerTool: () => {},
     registerMessageRenderer: () => {},
+    registerMarkdownTransformer: () => {},
+    registerEntryRenderer: () => {},
+    registerToolRenderer: () => {},
     registerProvider: () => {},
     unregisterProvider: () => {},
+    registerMcpServer: () => {},
+    unregisterMcpServer: () => {},
+    unregisterVirtualModel: () => {},
+    registerVirtualModel: () => {},
+    getMcpServers: () => [],
     sendMessage: () => {},
     sendUserMessage: () => {},
     appendEntry: () => {},
@@ -89,6 +99,9 @@ function createFakePi(flagValues: Record<string, boolean | string> = {}): FakePi
       throw new Error("not implemented");
     },
     getAllTools: () => [],
+    getSettings: () => {
+      throw new Error("not implemented");
+    },
     getCommands: () => [],
     setModel: async () => false,
     getThinkingLevel: () => "off",

package/extensions/agent-modes/package.json

@@ -8,7 +8,7 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@earendil-works/pi-coding-agent": "^1.5.2",
     "@types/node": "^22.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"

package/extensions/lib/tiny-model.ts

@@ -16,12 +16,13 @@
  * The model call itself is gone. It went through pi-ai's `complete()`, a value
  * import of pi's runtime, and that import stopped the extension loading outside
  * the agent-cortex checkout (see test/pi-extensions-load.test.mjs). The
- * ExtensionAPI promises no completion call. Newer hosts (pi 1.4.0) expose
- * `ModelRegistry.complete`, but the installed host (0.73.1) does not. Calling it
- * would need an untyped cast to a method that exists on one version only.
- * Extensions also make no internal LLM calls (AGENTS.md), so this feature stays
- * off. Both callers fall back to the truncation they already used when the model
- * failed. The `model` key is no longer read and is ignored if present.
+ * ExtensionAPI promises no completion call. The installed host (pi 1.5.2) does
+ * expose `ModelRegistry.complete` through `ExtensionContext.modelRegistry`, but
+ * calling it would make the extensions depend on a method that exists on later
+ * hosts only. Extensions also make no internal LLM calls (AGENTS.md), so this
+ * feature stays off. Both callers fall back to the truncation they already used
+ * when the model failed. The `model` key is no longer read and is ignored if
+ * present.
  */
 
 import { homedir } from "node:os";

package/extensions/output-style/package.json

@@ -8,7 +8,7 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@earendil-works/pi-coding-agent": "^1.5.2",
     "@types/node": "^22.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"

package/extensions/session-start/package.json

@@ -8,7 +8,7 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@earendil-works/pi-coding-agent": "^1.5.2",
     "@types/node": "^22.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"

package/extensions/skill-stats/package.json

@@ -8,7 +8,7 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@earendil-works/pi-coding-agent": "^1.5.2",
     "@types/node": "^22.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"

package/extensions/subagent/package.json

@@ -8,9 +8,9 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.78.1",
-    "@earendil-works/pi-ai": "^0.78.1",
-    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@earendil-works/pi-agent-core": "^1.5.2",
+    "@earendil-works/pi-ai": "^1.5.2",
+    "@earendil-works/pi-coding-agent": "^1.5.2",
     "@types/node": "^22.0.0",
     "tsx": "^4.0.0",
     "typebox": "^1.1.38",

package/lib/cli.mjs

@@ -5,6 +5,8 @@ import { basename } from "node:path";
  * populated only for the commands that accept them.
  * @typedef {object} ParsedArgs
  * @property {"help" | "version" | "install" | "migrate" | "unknown"} command
+ * @property {boolean} [report] `version` subcommand: report installed harnesses too
+ * @property {boolean} [json] `version --json`: print the report as JSON
  * @property {string | null} [harness]
  * @property {string} [name]
  * @property {string} [optionError]
@@ -69,6 +71,20 @@ export function parseArgs(argv, programName = DEFAULT_PROGRAM_NAME) {
 
   const [command, ...rest] = argv;
 
+  if (command === "version") {
+    // The `version` subcommand reports the installed harness versions; the
+    // `--version` flag above stays a bare CLI version for scripts.
+    let json = false;
+    for (const arg of rest) {
+      if (arg === "--json") {
+        json = true;
+        continue;
+      }
+      return { command: "version", report: true, optionError: `Unknown option "${arg}". Run "${programName} --help" for usage.` };
+    }
+    return json ? { command: "version", report: true, json } : { command: "version", report: true };
+  }
+
   if (command === "install") {
     let harness = null;
     let i = 0;
@@ -231,6 +247,13 @@ Commands:
                         --apply         Apply every pending step, verifying each
                         --dir <path>    Read idea files from <path> instead of
                                         docs/ideas (step v2's source)
+  version             Print the running CLI version, then one line per installed
+                      harness: its name, the version its installer recorded, and
+                      a marker comparing the two — current, stale, ahead (the
+                      installed copy is newer), or unknown (no readable
+                      fingerprint). Read-only: no install, no network, no writes.
+                      Options:
+                        --json          Print the same data as JSON records
   --help, -h          Show this help text
   --version, -V       Print the package version`;
 }

package/lib/harness-versions.mjs

@@ -0,0 +1,156 @@
+// The read side of the installers' fingerprints: `ctx version` reports which
+// harnesses are installed and how their version compares with the running CLI.
+//
+// Read-only by construction — the module only stats and reads, so the command
+// path never writes, installs, or reaches the network. A harness with no
+// installer gets no entry in the table, so it can never appear in the report.
+
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { isDirectory } from "../scripts/lib/fs.mjs";
+
+/**
+ * Where one harness records the version it was installed at: an artifact root
+ * under the home install directory, and the version file inside it.
+ * @typedef {object} HarnessFingerprint
+ * @property {"claude" | "pi"} harness
+ * @property {string[]} root Path segments of the artifact root, relative to home
+ * @property {string[]} file Path segments of the version file, relative to the root
+ */
+
+// Ordered as the installers are listed; the report keeps this order.
+/** @type {HarnessFingerprint[]} */
+const HARNESS_FINGERPRINTS = [
+  { harness: "claude", root: [".agent-cortex", "claude"], file: [".claude-plugin", "plugin.json"] },
+  { harness: "pi", root: [".agent-cortex", "pi"], file: ["package.json"] },
+];
+
+/**
+ * How an installed copy relates to the running CLI. `unknown` covers both a
+ * fingerprint that cannot be read and a version that is not a plain release —
+ * an unreadable install is never reported as `current`.
+ * @typedef {"current" | "stale" | "ahead" | "unknown"} Staleness
+ */
+
+/**
+ * One installed harness in the report.
+ * @typedef {object} HarnessVersion
+ * @property {string} harness
+ * @property {string} installed The installed version, or "unknown"
+ * @property {string} cli The running CLI version
+ * @property {Staleness} staleness
+ */
+
+/**
+ * Everything the `version` command reports.
+ * @typedef {object} VersionReport
+ * @property {string} cli The running CLI version
+ * @property {HarnessVersion[]} harnesses One entry per installed harness
+ */
+
+const UNKNOWN = "unknown";
+
+// Only plain releases are compared. A prerelease or a range is not "current"
+// just because its numeric core matches, so it reports unknown instead.
+const PLAIN_RELEASE = /^(\d+)\.(\d+)\.(\d+)$/;
+
+/**
+ * Compare two plain semver releases.
+ * @param {string} a
+ * @param {string} b
+ * @returns {-1 | 0 | 1 | null} The order, or null when either side is not a plain release
+ */
+function compareReleases(a, b) {
+  const left = PLAIN_RELEASE.exec(a);
+  const right = PLAIN_RELEASE.exec(b);
+  if (left === null || right === null) return null;
+  for (let segment = 1; segment <= 3; segment++) {
+    const l = Number(left[segment]);
+    const r = Number(right[segment]);
+    if (l !== r) return l < r ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * @param {string | null} installed null when the fingerprint is unreadable
+ * @param {string} cli
+ * @returns {Staleness}
+ */
+function stalenessOf(installed, cli) {
+  if (installed === null) return "unknown";
+  const order = compareReleases(installed, cli);
+  if (order === null) return "unknown";
+  if (order < 0) return "stale";
+  return order > 0 ? "ahead" : "current";
+}
+
+/**
+ * Read the version one harness recorded at install time.
+ * @param {string} home
+ * @param {HarnessFingerprint} fingerprint
+ * @returns {Promise<{ installed: boolean, version: string | null }>} `installed`
+ *   is false when the artifact root is absent; `version` is null when the
+ *   fingerprint is missing, malformed, or carries no version string
+ */
+async function readInstalledVersion(home, fingerprint) {
+  const root = join(home, ...fingerprint.root);
+  if (!(await isDirectory(root))) return { installed: false, version: null };
+  try {
+    /** @type {{ version?: unknown }} */
+    const manifest = JSON.parse(await readFile(join(root, ...fingerprint.file), "utf-8"));
+    const version = manifest?.version;
+    return { installed: true, version: typeof version === "string" && version !== "" ? version : null };
+  } catch {
+    return { installed: true, version: null };
+  }
+}
+
+/**
+ * Report the running CLI version and the installed version of every harness
+ * whose artifact root exists.
+ * @param {{ cli: string, home?: string }} options `home` defaults to the real
+ *   home directory; tests pass a fixture directory
+ * @returns {Promise<VersionReport>}
+ */
+export async function collectVersionReport({ cli, home = homedir() }) {
+  /** @type {HarnessVersion[]} */
+  const harnesses = [];
+  for (const fingerprint of HARNESS_FINGERPRINTS) {
+    const { installed, version } = await readInstalledVersion(home, fingerprint);
+    if (!installed) continue;
+    harnesses.push({
+      harness: fingerprint.harness,
+      installed: version ?? UNKNOWN,
+      cli,
+      staleness: stalenessOf(version, cli),
+    });
+  }
+  return { cli, harnesses };
+}
+
+/**
+ * Render the report as the default, human-readable output: the CLI version on
+ * the first line, then one line per installed harness. A harness whose version
+ * could not be read prints `unknown` twice — once for the version and once for
+ * the marker, because neither is known.
+ * @param {VersionReport} report
+ * @returns {string} Text without a trailing newline
+ */
+export function formatVersionReport(report) {
+  const lines = [report.cli];
+  for (const entry of report.harnesses) {
+    lines.push(`${entry.harness} ${entry.installed} ${entry.staleness}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Render the report as JSON, one record per installed harness.
+ * @param {VersionReport} report
+ * @returns {string} JSON without a trailing newline
+ */
+export function serialiseVersionReport(report) {
+  return JSON.stringify(report, null, 2);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaybeeuu/agent-cortex",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Personal PI package with custom agents, skills, and extensions",
   "keywords": [
     "pi-package"

package/{skills/productivity/validate-agent-dir/scripts → scripts}/validate-agent-dir.mjs

@@ -2,12 +2,15 @@
 // Validator for the composable agent directory layout: `agent.md` plus at
 // least one harness subdirectory with a valid `frontmatter.json`.
 //
-// Zero dependencies: import the pure functions, or run the test suite at
-// `test/validate-agent-dir.test.mjs`.
+// Repo tooling, not a shipped skill: the composable layout exists only in this
+// repository's `agents/` tree, and installs carry flat rendered agents. Run the
+// test suite at `test/validate-agent-dir.test.mjs`.
 
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 
+import { isDirectory, isFile } from "./lib/fs.mjs";
+
 // ─── Types ────────────────────────────────────────────────────────────────────
 
 /**
@@ -96,28 +99,31 @@ export function validateFrontmatter(fm) {
 
 /**
  * @param {string} agentDirPath
- * @returns {ValidationResult}
+ * @returns {Promise<ValidationResult>}
  */
-export function validateAgentDir(agentDirPath) {
+export async function validateAgentDir(agentDirPath) {
   /** @type {string[]} */
   const errors = [];
 
   // Check agent.md exists
   const agentMdPath = join(agentDirPath, "agent.md");
-  if (!existsSync(agentMdPath)) {
+  if (!(await isFile(agentMdPath))) {
     errors.push("missing agent.md");
   }
 
   // Check for at least one harness subdirectory with frontmatter.json
-  if (!existsSync(agentDirPath)) {
+  if (!(await isDirectory(agentDirPath))) {
     return { ok: false, errors: ["agent directory does not exist"] };
   }
 
-  const entries = readdirSync(agentDirPath);
-  const harnessDirs = entries.filter((entry) => {
-    const fullPath = join(agentDirPath, entry);
-    return statSync(fullPath).isDirectory() && entry !== "node_modules";
-  });
+  const entries = await readdir(agentDirPath);
+  /** @type {string[]} */
+  const harnessDirs = [];
+  for (const entry of entries) {
+    if (entry !== "node_modules" && (await isDirectory(join(agentDirPath, entry)))) {
+      harnessDirs.push(entry);
+    }
+  }
 
   if (harnessDirs.length === 0) {
     errors.push("no harness subdirectories found (need at least one with frontmatter.json)");
@@ -126,12 +132,12 @@ export function validateAgentDir(agentDirPath) {
   // Validate each harness directory
   for (const harnessDir of harnessDirs) {
     const frontmatterPath = join(agentDirPath, harnessDir, "frontmatter.json");
-    if (!existsSync(frontmatterPath)) {
+    if (!(await isFile(frontmatterPath))) {
       continue; // Skip directories without frontmatter.json
     }
 
     try {
-      const content = readFileSync(frontmatterPath, "utf-8");
+      const content = await readFile(frontmatterPath, "utf-8");
       const fm = JSON.parse(content);
       const result = validateFrontmatter(fm);
       if (!result.ok) {

package/skills/planning/create-task/REFERENCE.md

@@ -88,4 +88,15 @@ The deliverable this feature produces and the problem it solves.
 | review | Review | verify |
 | document | Document | review |
 
-`maxFixRounds: 4` — the maximum fix-retry rounds allowed for a stage's verify loop before the PR gate. Adjust stages only in `pipeline.json`; the script and templates follow it.
+`maxFixRounds: 4` — the maximum fix-retry rounds allowed for a stage's verify loop before the PR gate. Adjust stages only in `pipeline.json`; the script and templates follow it.
+
+## Stage templates
+
+`templates/` holds one prompt skeleton per stage; a dispatcher fills one to compose that stage's
+chore prompt. The REPORT contract is not defined here —
+`skills/workflow/run-pipeline-stage/prompts/stage-runner.md` owns it and every template mirrors it.
+Drift between the two fails silently: a worker that follows a drifted template emits a well-formed
+block with keys no one reads, so routing stops at that stage. Drift has already broken routing
+twice. Compare a template with the authority whenever either changes. The intended guard is a lint
+parity check beside `scripts/check-skill-frontmatter.mjs`, not a test — a test here would assert on
+file text, which is a content inventory, and `style-tests` bans that shape.

package/skills/planning/create-task/templates/code.md

@@ -31,10 +31,21 @@ Implement the task described above using a test-driven approach:
 
 Make only the changes required to complete this task — do not refactor unrelated code.
 
-End your response with a ---REPORT--- block:
+Commit and push the stage's work before reporting (see _Deliver before reporting_ in
+`prompts/stage-runner.md`). A dirty worktree counts as a failed stage.
+
+End your response with a ---REPORT--- block. The `run-pipeline-stage` skill's
+`prompts/stage-runner.md` holds the authoritative REPORT contract — if this block and that
+prompt differ, follow the prompt and correct this template.
 ---REPORT---
 BEAD_ID: <id>
-STAGE_COMPLETED: coding
+STAGE_COMPLETED: code
 SUMMARY: <2–3 sentence summary of what was done>
 FILES_CHANGED: <comma-separated list, or "none">
+COMMIT: <sha of the stage commit, or "none">
+PUSHED: <yes|no>
+PR: none
+OUTCOME: <SUCCESS|BLOCKED>
+BLOCKING_ISSUES:         ← include only if OUTCOME is BLOCKED; one line per issue
+- <what blocks the stage and what would unblock it>
 ---

package/skills/planning/create-task/templates/document.md

@@ -31,10 +31,21 @@ Review the changes made and compare them against the existing documentation in t
    when no decisions or macro behaviour changed.
 6. Do not modify source code — documentation only.
 
-End your response with a ---REPORT--- block:
+Commit and push the docs, and open or update the feature PR before reporting (see _Deliver
+before reporting_ in `prompts/stage-runner.md`). A dirty worktree counts as a failed stage.
+
+End your response with a ---REPORT--- block. The `run-pipeline-stage` skill's
+`prompts/stage-runner.md` holds the authoritative REPORT contract — if this block and that
+prompt differ, follow the prompt and correct this template.
 ---REPORT---
 BEAD_ID: <id>
-STAGE_COMPLETED: documenting
+STAGE_COMPLETED: document
 SUMMARY: <2–3 sentence summary of what was documented, or "No documentation changes required">
 FILES_CHANGED: <comma-separated list of docs touched, or "none">
+COMMIT: <sha of the stage commit, or "none">
+PUSHED: <yes|no>
+PR: <feature PR url>
+OUTCOME: <SUCCESS|BLOCKED>
+BLOCKING_ISSUES:         ← include only if OUTCOME is BLOCKED; one line per issue
+- <what blocks the stage and what would unblock it>
 ---

package/skills/planning/create-task/templates/fix.md

@@ -18,10 +18,21 @@ Apply only the changes described in the Task section above. Do not make any othe
 
 **Use context7** when working with any third-party library — fetch live docs to ensure you use the correct, up-to-date API for the version in this project.
 
-End your response with a ---REPORT--- block:
+Commit and push the fix before reporting (see _Deliver before reporting_ in
+`prompts/stage-runner.md`). A dirty worktree counts as a failed stage.
+
+End your response with a ---REPORT--- block. The `run-pipeline-stage` skill's
+`prompts/stage-runner.md` holds the authoritative REPORT contract — if this block and that
+prompt differ, follow the prompt and correct this template.
 ---REPORT---
 BEAD_ID: <id>
-STAGE_COMPLETED: fixing
+STAGE_COMPLETED: fix
 SUMMARY: <2–3 sentence summary of what was changed>
 FILES_CHANGED: <comma-separated list, or "none">
+COMMIT: <sha of the stage commit, or "none">
+PUSHED: <yes|no>
+PR: none
+OUTCOME: <SUCCESS|BLOCKED>
+BLOCKING_ISSUES:         ← include only if OUTCOME is BLOCKED; one line per issue
+- <what remains unresolved and what would unblock it>
 ---

package/skills/planning/create-task/templates/verify.md

@@ -21,23 +21,29 @@ Discover and run the project's test and lint commands, then report the outcome.
 1. `package.json` `scripts` — look for keys named `test`, `lint`, `check`, `typecheck`, or similar.
 2. `Makefile` — look for targets named `test`, `lint`, `check`.
 3. Other well-known config files (e.g. `pyproject.toml`, `Cargo.toml`) — look for test/lint targets.
-4. If no commands are found, report PASS with summary "No test or lint commands found".
+4. If no commands are found, report `OUTCOME: SUCCESS` with summary "No test or lint commands found".
 
 **Step 2 — Run each discovered command** in the project root. Capture stdout and stderr.
 
 **Step 3 — Evaluate**:
-- If all commands exit 0: `VERIFY_OUTCOME: PASS`.
-- If any command exits non-zero: `VERIFY_OUTCOME: FAIL`. List each failure concisely.
+- If all commands exit 0: `OUTCOME: SUCCESS`.
+- If any command exits non-zero: `OUTCOME: BLOCKED`. List each failure concisely under
+  `BLOCKING_ISSUES`.
 
 Do not fix failures — report them only.
 
-End your response with a ---REPORT--- block:
+End your response with a ---REPORT--- block. The `run-pipeline-stage` skill's
+`prompts/stage-runner.md` holds the authoritative REPORT contract — if this block and that
+prompt differ, follow the prompt and correct this template.
 ---REPORT---
 BEAD_ID: <id>
-STAGE_COMPLETED: verifying
+STAGE_COMPLETED: verify
 SUMMARY: <what commands were run and overall outcome>
 FILES_CHANGED: none
-VERIFY_OUTCOME: <PASS|FAIL>
-VERIFY_FAILURES:          ← only if VERIFY_OUTCOME is FAIL
-- <test/lint failure summary>
+COMMIT: <sha, or "none" if this stage added no commit>
+PUSHED: <yes|no>
+PR: none
+OUTCOME: <SUCCESS|BLOCKED>
+BLOCKING_ISSUES:         ← include only if OUTCOME is BLOCKED; one line per failure
+- <command, its exit status, and the failure summary>
 ---

package/skills/workflow/ralph/REFERENCE.md

@@ -204,6 +204,27 @@ For each parent task bead (`<parent-id>`):
 
 ---
 
+## Pruning Worktrees
+
+A worktree outlives its bead: ralph leaves the directory behind when a feature closes, and a crashed run leaves one with no bead at all. `skills/workflow/ralph/scripts/prune-worktrees.mjs` converges `.agent-cortex/worktrees/*` with bead state.
+
+```bash
+node skills/workflow/ralph/scripts/prune-worktrees.mjs                  # remove closed-bead worktrees, report the rest
+node skills/workflow/ralph/scripts/prune-worktrees.mjs --remove-orphans # also remove open-bead and missing-bead worktrees
+```
+
+**Candidacy comes from bead state, never from git ancestry.** The repo squash-merges, so every landed branch still reports as unmerged. A directory named after a bead that `bd show` reports `closed` is the only proof that admits removal; an open bead, a missing bead, or a bead `bd` could not answer for is kept unless `--remove-orphans` asks otherwise. A bead `bd` could not read is never removed, whatever the flags say.
+
+**A candidate that fails a guard is refused, and the reason is printed.** The guards are: dirty working tree, `locked` worktree, detached HEAD, directory not registered with git, branch with no upstream, and branch with unpushed commits.
+
+**Removal is three commands.** `git worktree remove <path>`, then `git branch -D <branch>`, then `git push origin --delete <branch>`. The remote branch name is the worktree's own checked-out branch, so ralph's `feature/<parent-id>` deletes `origin/feature/<parent-id>`. A remote ref that git already reports as gone is not a failure.
+
+**Exit status is 1 whenever any scanned worktree survived the run.** An open bead counts as survival, so a normal run against a live backlog exits 1. Read the per-worktree report; do not treat the status as a verdict on the worktree you asked about.
+
+**An unregistered stale directory is refused forever.** Earlier git runs may have dropped its registration, so every scan reports it and never removes it. Clean it up by hand: `git worktree prune`, then `rm -rf <path>`.
+
+---
+
 ## Feature PR Gate
 
 When the `document` chore for a parent task completes:

package/skills/workflow/ralph/SKILL.md

@@ -96,7 +96,7 @@ bd show <id>                   # full detail, including the worker's notes
 - **Multi-feature epics** (two or more feature task children): the epic runs on `epic/<epic-id>`, based on `origin/main` — never local `main`. Each `execution:afk` parent task runs on `feature/<parent-id>`, based from its epic branch, in the dedicated worktree `.agent-cortex/worktrees/<parent-id>`.
 - Feature PR gate: `feature/<parent-id>` → `epic/<epic-id>` (or → `main` for single-feature epics). Epic PR gate: `epic/<epic-id>` → `main`.
 - **Never stack branches.** `feature/<parent-id>` is based on `epic/<epic-id>` (or `origin/main`), never on another `feature/*`. A dependency between two tasks lives in the bead graph (`bd dep add <waiting> <blocked-on>`) so the dependent task stays out of `bd ready` until its dependency has merged — stacking the branch defeats that gate by hand and costs a rebase-on-squash later (see `git-workflow` rule 3).
-- Branch/worktree setup and the PR commands live in REFERENCE.md (_Feature branches and worktrees_, _Feature PR gate_).
+- Branch/worktree setup and the PR commands live in REFERENCE.md (_Feature branches and worktrees_, _Feature PR gate_). Closed-bead worktrees are reclaimed by `skills/workflow/ralph/scripts/prune-worktrees.mjs`, which removes worktrees whose bead is closed, reports the rest, and removes an orphan only with `--remove-orphans` (REFERENCE.md, _Pruning Worktrees_).
 
 ### 7. HITL pause and shutdown
 

package/skills/workflow/ralph/scripts/prune-worktrees.mjs

@@ -0,0 +1,346 @@
+// Converges the ralph worktree set with bead state.
+//
+// Ralph runs each bead in `.agent-cortex/worktrees/<bead-id>` and leaves the
+// worktree behind after the bead closes; crashed runs leave orphans. This pass
+// reads bead state, not git ancestry: this repo squash-merges, so every ancestry
+// test reports a landed branch as unmerged.
+//
+// Zero dependencies: run with `node prune-worktrees.mjs`.
+
+import { execFile } from 'node:child_process';
+import { readdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+import { pathToFileURL } from 'node:url';
+
+const execFileAsync = promisify(execFile);
+
+// BD_PATH env override lets machines where bd is not on PATH pin a location.
+const BD_PATH = process.env.BD_PATH || 'bd';
+
+/** @typedef {'closed-bead' | 'open-bead' | 'orphan' | 'unclassified'} Classification */
+/** @typedef {'removed' | 'kept' | 'refused'} Outcome */
+
+/**
+ * @typedef {object} WorktreeEntry
+ * @property {string} id                  Bead id, taken from the directory name.
+ * @property {string} path                Absolute path of the worktree.
+ * @property {string | null} branch       Checked-out branch, or null when unknown.
+ * @property {Classification} classification
+ * @property {string} beadStatus          Raw `bd` status, or `'missing'`.
+ * @property {Outcome} outcome
+ * @property {string[]} reasons           Why the worktree was not removed.
+ */
+
+/**
+ * @typedef {object} PruneResult
+ * @property {WorktreeEntry[]} entries
+ * @property {number} exitCode
+ */
+
+/**
+ * The text of a failed child-process call: git's stderr when it has one, the
+ * error message otherwise.
+ * @param {unknown} error
+ * @returns {string}
+ */
+function errorText(error) {
+  if (typeof error === 'object' && error !== null) {
+    const { stderr, message } = /** @type {{ stderr?: unknown, message?: unknown }} */ (error);
+    if (typeof stderr === 'string' && stderr.trim() !== '') return stderr;
+    if (typeof message === 'string') return message;
+  }
+  return String(error);
+}
+
+/**
+ * @param {unknown} error
+ * @returns {boolean} true when the error is a missing path, not a failure.
+ */
+function isMissingPath(error) {
+  return typeof error === 'object' && error !== null && /** @type {{ code?: unknown }} */ (error).code === 'ENOENT';
+}
+
+/** @type {(args: string[]) => Promise<string>} */
+async function runBd(args) {
+  const { stdout } = await execFileAsync(BD_PATH, args, { encoding: 'utf-8' });
+  return stdout;
+}
+
+/**
+ * Run git in `cwd` and report the outcome rather than throwing: a refusal is an
+ * expected domain result here, not an emergency.
+ * @param {string} cwd
+ * @param {string[]} args
+ * @returns {Promise<{ ok: true, stdout: string } | { ok: false, stderr: string }>}
+ */
+async function runGit(cwd, args) {
+  try {
+    const { stdout } = await execFileAsync('git', args, { cwd, encoding: 'utf-8' });
+    return { ok: true, stdout };
+  } catch (error) {
+    return { ok: false, stderr: errorText(error) };
+  }
+}
+
+/**
+ * List the worktree directories under `.agent-cortex/worktrees`, ignoring
+ * everything else on disk. A missing directory means nothing to prune.
+ * @param {string} repoRoot
+ * @returns {Promise<string[]>} absolute paths, sorted for stable output.
+ */
+async function listWorktreePaths(repoRoot) {
+  const worktreesDir = join(repoRoot, '.agent-cortex', 'worktrees');
+  /** @type {import('node:fs').Dirent[]} */
+  let dirents;
+  try {
+    dirents = await readdir(worktreesDir, { withFileTypes: true });
+  } catch (error) {
+    if (isMissingPath(error)) return [];
+    throw error;
+  }
+  return dirents
+    .filter((dirent) => dirent.isDirectory())
+    .map((dirent) => join(worktreesDir, dirent.name))
+    .sort();
+}
+
+/**
+ * Map each registered worktree path to its checked-out branch and lock state.
+ * @param {string} repoRoot
+ * @returns {Promise<Map<string, { branch: string | null, locked: string | null }>>}
+ */
+async function readRegisteredWorktrees(repoRoot) {
+  const result = await runGit(repoRoot, ['worktree', 'list', '--porcelain']);
+  /** @type {Map<string, { branch: string | null, locked: string | null }>} */
+  const registered = new Map();
+  if (!result.ok) return registered;
+
+  for (const block of result.stdout.split('\n\n')) {
+    const lines = block.split('\n');
+    const pathLine = lines.find((line) => line.startsWith('worktree '));
+    if (pathLine === undefined) continue;
+    const branchLine = lines.find((line) => line.startsWith('branch '));
+    const lockedLine = lines.find((line) => line.startsWith('locked'));
+    registered.set(pathLine.slice('worktree '.length), {
+      branch: branchLine === undefined ? null : branchLine.slice('branch refs/heads/'.length),
+      locked: lockedLine === undefined ? null : lockedLine.slice('locked'.length).trim(),
+    });
+  }
+  return registered;
+}
+
+/**
+ * Resolve one worktree's bead and classify it.
+ * @param {string} id
+ * @param {(args: string[]) => Promise<string>} exec
+ * @returns {Promise<{ classification: Classification, beadStatus: string }>}
+ */
+async function classifyBead(id, exec) {
+  let stdout;
+  try {
+    stdout = await exec(['show', id, '--json']);
+  } catch (error) {
+    const message = errorText(error);
+    if (/not found|no issues found/i.test(message)) {
+      return { classification: 'orphan', beadStatus: 'missing' };
+    }
+    return { classification: 'unclassified', beadStatus: `error: ${message.trim()}` };
+  }
+
+  const beads = JSON.parse(stdout);
+  const bead = (Array.isArray(beads) ? beads[0] : beads) ?? {};
+  const status = String(bead.status ?? 'unknown');
+  return { classification: status === 'closed' ? 'closed-bead' : 'open-bead', beadStatus: status };
+}
+
+/**
+ * Reasons git refuses to tear a worktree down. A worktree removed anyway would
+ * throw away uncommitted work or an unpushed branch, so every reason keeps the
+ * worktree in place.
+ * @param {{ path: string, registered: { branch: string | null, locked: string | null } | undefined }} target
+ * @param {(cwd: string, args: string[]) => Promise<{ ok: true, stdout: string } | { ok: false, stderr: string }>} git
+ * @returns {Promise<{ branch: string | null, reasons: string[] }>}
+ */
+async function findRefusals({ path, registered }, git) {
+  /** @type {string[]} */
+  const reasons = [];
+
+  if (registered === undefined) {
+    return { branch: null, reasons: ['not a registered git worktree'] };
+  }
+  if (registered.locked !== null) {
+    reasons.push(registered.locked === '' ? 'worktree is locked' : `worktree is locked: ${registered.locked}`);
+  }
+  if (registered.branch === null) {
+    return { branch: null, reasons: [...reasons, 'worktree is not on a branch'] };
+  }
+
+  const status = await git(path, ['status', '--porcelain']);
+  if (!status.ok) return { branch: registered.branch, reasons: [...reasons, `worktree cannot be read: ${status.stderr.trim()}`] };
+  const dirtyPaths = status.stdout.split('\n').filter((line) => line !== '').length;
+  if (dirtyPaths > 0) reasons.push(`worktree is dirty: ${dirtyPaths} uncommitted path(s)`);
+
+  const upstream = await git(path, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}']);
+  if (!upstream.ok) {
+    reasons.push(`branch ${registered.branch} has no remote-tracking branch`);
+    return { branch: registered.branch, reasons };
+  }
+  const trackingRef = upstream.stdout.trim();
+  const unpushed = await git(path, ['rev-list', '--count', `${trackingRef}..HEAD`]);
+  if (!unpushed.ok) return { branch: registered.branch, reasons: [...reasons, `branch ${registered.branch} cannot be compared with ${trackingRef}: ${unpushed.stderr.trim()}`] };
+  const unpushedCommits = Number.parseInt(unpushed.stdout.trim(), 10);
+  if (unpushedCommits > 0) {
+    reasons.push(`branch ${registered.branch} has ${unpushedCommits} commit(s) not pushed to ${trackingRef}`);
+  }
+
+  return { branch: registered.branch, reasons };
+}
+
+/**
+ * Remove a worktree and its branch, locally and on the remote.
+ * @param {string} repoRoot
+ * @param {{ path: string, branch: string }} target
+ * @param {(cwd: string, args: string[]) => Promise<{ ok: true, stdout: string } | { ok: false, stderr: string }>} git
+ * @returns {Promise<{ ok: true } | { ok: false, reasons: string[] }>}
+ */
+async function removeWorktree(repoRoot, { path, branch }, git) {
+  /** @type {string[]} */
+  const reasons = [];
+
+  const removed = await git(repoRoot, ['worktree', 'remove', path]);
+  if (!removed.ok) {
+    return { ok: false, reasons: [`git worktree remove failed: ${removed.stderr.trim()}`] };
+  }
+
+  const local = await git(repoRoot, ['branch', '-D', branch]);
+  if (!local.ok) reasons.push(`local branch ${branch} could not be deleted: ${local.stderr.trim()}`);
+
+  const remote = await git(repoRoot, ['push', 'origin', '--delete', branch]);
+  const remoteGone = /remote ref does not exist/i.test(remote.ok ? '' : remote.stderr);
+  if (!remote.ok && !remoteGone) {
+    reasons.push(`remote branch ${branch} could not be deleted: ${remote.stderr.trim()}`);
+  }
+
+  return reasons.length === 0 ? { ok: true } : { ok: false, reasons };
+}
+
+/**
+ * Converge `.agent-cortex/worktrees` with bead state: remove closed-bead
+ * worktrees, report everything else.
+ * @param {object} options
+ * @param {string} options.repoRoot                              Repository to prune.
+ * @param {boolean} [options.removeOrphans]                       Also remove worktrees whose bead is open or missing.
+ * @param {(args: string[]) => Promise<string>} [options.exec]    bd runner; injectable for tests.
+ * @param {(cwd: string, args: string[]) => Promise<{ ok: true, stdout: string } | { ok: false, stderr: string }>} [options.git]  git runner; injectable for tests.
+ * @returns {Promise<PruneResult>}
+ */
+export async function pruneWorktrees({ repoRoot, exec = runBd, removeOrphans = false, git = runGit }) {
+  const registered = await readRegisteredWorktrees(repoRoot);
+  /** @type {WorktreeEntry[]} */
+  const entries = [];
+
+  for (const path of await listWorktreePaths(repoRoot)) {
+    const id = path.slice(dirname(path).length + 1);
+    const { classification, beadStatus } = await classifyBead(id, exec);
+
+    /** @type {WorktreeEntry} */
+    const entry = { id, path, branch: registered.get(path)?.branch ?? null, classification, beadStatus, outcome: 'kept', reasons: [] };
+
+    // A closed bead is the proof. Anything else — an open bead, a missing bead,
+    // a bead bd could not answer for — is only removed on explicit request, and
+    // an unreadable bead is never removed at all.
+    const wanted = classification === 'closed-bead' || (classification !== 'unclassified' && removeOrphans);
+    if (wanted) {
+      const { branch, reasons } = await findRefusals({ path, registered: registered.get(path) }, git);
+      entry.branch = branch;
+      if (reasons.length > 0) {
+        entry.outcome = 'refused';
+        entry.reasons = reasons;
+      } else if (branch === null) {
+        entry.outcome = 'refused';
+        entry.reasons = ['worktree is not on a branch'];
+      } else {
+        const removal = await removeWorktree(repoRoot, { path, branch }, git);
+        entry.outcome = removal.ok ? 'removed' : 'refused';
+        if (!removal.ok) entry.reasons = removal.reasons;
+      }
+    }
+
+    entries.push(entry);
+  }
+
+  return { entries, exitCode: entries.some((entry) => entry.outcome !== 'removed') ? 1 : 0 };
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────────
+
+const USAGE = `Usage: node prune-worktrees.mjs [--remove-orphans]
+
+Removes worktrees under .agent-cortex/worktrees whose bead is closed, then
+reports the rest. A worktree whose bead is open or missing is an orphan: it is
+only removed when --remove-orphans is passed. Run from anywhere inside the
+repository.
+`;
+
+/** Every flag the CLI accepts. */
+const REMOVE_ORPHANS_FLAG = '--remove-orphans';
+
+class UsageError extends Error {}
+
+/**
+ * Resolve the repository root from any directory inside it — the main checkout
+ * or a linked worktree. The shared `.git` directory is one level below the root
+ * in both cases.
+ * @param {string} cwd
+ * @returns {Promise<string | null>}
+ */
+async function resolveRepoRoot(cwd) {
+  const result = await runGit(cwd, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  return result.ok ? dirname(result.stdout.trim()) : null;
+}
+
+/**
+ * @param {object} options
+ * @param {string[]} options.argv                                  CLI arguments (without node/script).
+ * @param {string} [options.cwd]                                   Directory the CLI was invoked from. * @param {(args: string[]) => Promise<string>} [options.exec]      bd runner; injectable for tests.
+ * @param {(cwd: string, args: string[]) => Promise<{ ok: true, stdout: string } | { ok: false, stderr: string }>} [options.git]
+ * @param {(chunk: string) => void} [options.write]                  stdout sink; injectable for tests.
+ * @returns {Promise<number>} process exit code.
+ */
+export async function runCli({ argv, cwd = process.cwd(), exec = runBd, git = runGit, write = (chunk) => process.stdout.write(chunk) }) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    write(USAGE);
+    return 0;
+  }
+  const unknown = argv.filter((arg) => arg !== REMOVE_ORPHANS_FLAG);
+  if (unknown.length > 0) throw new UsageError(`unexpected argument: ${unknown[0]}`);
+  const removeOrphans = argv.includes(REMOVE_ORPHANS_FLAG);
+
+  const repoRoot = await resolveRepoRoot(cwd);
+  if (repoRoot === null) throw new Error('not inside a git repository');
+
+  const { entries, exitCode } = await pruneWorktrees({ repoRoot, exec, removeOrphans, git });
+
+  write(`Scanning ${join(repoRoot, '.agent-cortex', 'worktrees')}\n`);
+  for (const entry of entries) {
+    const detail = entry.reasons.length > 0 ? ` — ${entry.reasons.join('; ')}` : '';
+    write(`  ${entry.id.padEnd(24)} ${entry.classification.padEnd(13)} ${entry.outcome}${detail}\n`);
+  }
+  const removed = entries.filter((entry) => entry.outcome === 'removed').length;
+  write(`Removed ${removed} of ${entries.length} worktree(s).\n`);
+
+  return exitCode;
+}
+
+// Only run the CLI when invoked directly, so tests can import the module.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runCli({ argv: process.argv.slice(2) })
+    .then((code) => {
+      process.exitCode = code;
+    })
+    .catch((error) => {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+      process.exitCode = error instanceof UsageError ? 2 : 1;
+    });
+}

package/skills/workflow/run-pipeline-stage/SKILL.md

@@ -123,6 +123,9 @@ BLOCKING_ISSUES:                              ← only if OUTCOME is BLOCKED
 - <specific blocking issue>
 ```
 
+Stage-chore templates under `create-task/templates/` mirror this contract. A template that drifts
+still emits a well-formed block with unread keys, so routing fails silently.
+
 Subagents report facts — do not ask them to suggest or predict the next step. A REPORT claiming
 `OUTCOME: SUCCESS` with `PUSHED: no`, or a `COMMIT` that is not on the branch, records a failed
 stage: the commit is the evidence, the report is the claim.