@jaybeeuu/agent-cortex 2.5.0 → 2.5.1

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 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

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

@@ -120,8 +120,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 +147,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaybeeuu/agent-cortex",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "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/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.