@jaybeeuu/agent-cortex 2.4.2 → 2.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaybeeuu/agent-cortex",
-  "version": "2.4.2",
+  "version": "2.5.1",
   "description": "Personal PI package with custom agents, skills, and extensions",
   "keywords": [
     "pi-package"
@@ -11,7 +11,9 @@
     "url": "https://github.com/jaybeeuu/agent-cortex"
   },
   "bin": {
-    "agent-cortex": "./bin/agent-cortex.mjs"
+    "agent-cortex": "./bin/agent-cortex.mjs",
+    "cortex": "./bin/agent-cortex.mjs",
+    "ctx": "./bin/agent-cortex.mjs"
   },
   "files": [
     "bin/",

package/scripts/lib/migrate.mjs

@@ -40,6 +40,15 @@ const EXECUTION_LABEL_PREFIX = "execution:";
  */
 const V1_LABEL_VALUES = ["afk", "hitl"];
 
+/**
+ * Ids per `bd label add` / `bd label remove` call. bd applies a label change id
+ * by id, so one call carrying every id in a large workspace takes minutes and
+ * can report success having persisted only part of the list — which is how a
+ * 710-bead rename silently left 280 beads unrenamed. A chunk keeps each call
+ * small enough to apply in full.
+ */
+const LABEL_BATCH_SIZE = 20;
+
 /**
  * Where loose idea records live, relative to the working directory. This is the
  * one path the command assumes, and it is deliberately the directory every
@@ -262,9 +271,27 @@ async function findLegacyLabelBeads({ bd }) {
   return pending.sort((a, b) => a.id.localeCompare(b.id));
 }
 
+/**
+ * Split `items` into consecutive runs of at most `size` — one `bd` call's worth.
+ *
+ * `size` must be positive: a size of 0 never advances the loop.
+ *
+ * @template T
+ * @param {T[]} items
+ * @param {number} size
+ * @returns {T[][]}
+ */
+function chunkItems(items, size) {
+  /** @type {T[][]} */
+  const chunks = [];
+  for (let start = 0; start < items.length; start += size) chunks.push(items.slice(start, start + size));
+  return chunks;
+}
+
 /**
  * Apply the label rename in batches: add the target label for a group of beads,
  * then remove the legacy one, so a bead is never left without its axis label.
+ * Both writes carry one chunk of ids, never the whole workspace.
  *
  * @param {StepContext} ctx
  * @param {Pending[]} pending
@@ -283,8 +310,10 @@ async function renameLegacyLabels({ bd }, pending) {
 
   for (const from of [...groups.keys()].sort()) {
     const { to, ids } = /** @type {{ to: string, ids: string[] }} */ (groups.get(from));
-    await bd(["label", "add", ...ids, to]);
-    await bd(["label", "remove", ...ids, from]);
+    for (const chunk of chunkItems(ids, LABEL_BATCH_SIZE)) {
+      await bd(["label", "add", ...chunk, to]);
+      await bd(["label", "remove", ...chunk, from]);
+    }
   }
 }
 

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

@@ -10,7 +10,9 @@ node <skill-scripts>/create-chores.mjs --parent <bead-id> [--priority <0-4>]
 
 - Reads `<skill>/pipeline.json`; creates each stage chore via `bd create` and wires dependencies via `bd dep add`.
 - Prints a JSON object mapping each stage ID to its chore bead ID, plus `featurePrReview` for the PR gate.
-- Expands a bead that already exists — it never creates a parent. It is also not idempotent: running it against a bead that already has stage chores creates a second chain, so callers check for existing `stage:*` children first (ralph's expansion guard).
+- Expands a bead that already exists — it never creates a parent.
+- **Idempotent**: it reads that parent's children once (`bd children <parent-id> --json`) and adopts an existing child by its role label — `stage:<id>` for a stage chore, `lifecycle:feature-pr` for the gate — creating only what is missing. Deps that are already wired are skipped. A re-run on an expanded bead creates nothing and prints the same mapping, so re-running after a failed expansion is the recovery path.
+- Adoption ignores bead status and reads only labels: a chore a later stage already closed is still adopted and reprinted in the mapping, which keeps a re-run convergent instead of creating a duplicate. When a role label appears twice under one parent the first-listed child wins. Adoption is scoped to that parent's children and keyed on labels, never titles, so a stray chore from another bead is never adopted.
 
 ## Stage chore beads
 
@@ -86,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/SKILL.md

@@ -81,7 +81,7 @@ Turn a piece of work into a tracked bead, classify it for autonomous (AFK) or hu
 
    The planning bead is cold-start ready — what and why, decisions already made, open questions and risks, references — and needs `## Acceptance Criteria`, which `--validate` requires for type `task` (template in `REFERENCE.md` → Hierarchy). A deliverable that genuinely needs a human — visual sign-off, credentials, hardware — is created `-l execution:hitl` and stops there.
 
-7. **Expand into pipeline stage chores.** Run the `create-chores` script, which reads this skill's `pipeline.json` and deterministically creates all stage chores plus the PR gate bead in one shot:
+7. **Expand into pipeline stage chores.** Run the `create-chores` script, which reads this skill's `pipeline.json` and creates the stage chores plus the PR gate bead — adopting any the parent already has, so a re-run converges on the existing tree instead of duplicating it:
 
    ```bash
    # Run from the TARGET project's directory — bd resolves its beads DB from cwd;
@@ -92,13 +92,15 @@ Turn a piece of work into a tracked bead, classify it for autonomous (AFK) or hu
 
    `<skill-scripts>` is the absolute path to this skill's own `scripts/` directory, resolved from wherever this skill was loaded — it varies by harness and install location, so never hardcode one harness's path.
 
+   The script is idempotent: it adopts an existing child by its `stage:<id>` or `lifecycle:feature-pr` label, creates only what is missing, and skips deps that are already wired. If an expansion fails partway, re-run this command — it completes the partial chain and prints the full mapping.
+
    On the feature path, run it **once per AFK impl child**, with `--parent <impl-task-id>` — never the feature ID: stage chores inherit their parent's labels, the script checks only that it was handed a parent ID (`REFERENCE.md` → PR gate bead), so an `execution:hitl` feature parent yields a chore tree no executor routes. A deliverable created `execution:hitl` in step 6 is not expanded.
 
 8. **Report.** Return the bead ID (or, on the feature path, the feature ID plus every planning and impl child ID), the classification of each expanded bead (`AFK`), and the created stage chore IDs from the script output (including `featurePrReview`) — one mapping per expanded impl child on the feature path.
 
 ### Expanding an existing bead
 
-Steps 2–6 create beads; step 7 expands one. A bead that already exists but has no `stage:*` chore children — an AFK task filed before the pipeline existed, or one ralph found chore-less — is a supported entry point: run step 7's `create-chores.mjs --parent <existing-id> --priority <its-own-priority>` directly, then report the mapping. No create steps, no new description, no re-classification.
+Steps 2–6 create beads; step 7 expands one. A bead that already exists but has no `stage:*` chore children — an AFK task filed before the pipeline existed, or one ralph found chore-less — is a supported entry point: run step 7's `create-chores.mjs --parent <existing-id> --priority <its-own-priority>` directly, then report the mapping. No create steps, no new description, no re-classification. A partial chain from a failed run is repaired the same way: re-running adopts the chores that exist, creates the missing ones, and reparents nothing.
 
 **Never re-run `create-task` for an existing bead.** It creates a bead first and expands second, so the run leaves a **second parent** beside the original, which stays chore-less — the duplicate ralph's expansion guard exists to prevent. `create-chores.mjs` expands a bead that already exists; only step 2 creates a bead.
 
@@ -110,6 +112,7 @@ Steps 2–6 create beads; step 7 expands one. A bead that already exists but has
 - **Skipping the classifier and classifying by hand.** The rubric is a subagent's job; a hand-rolled guess drifts from it.
 - **Expanding an HITL bead.** If classification is HITL, stop — creating a chore tree for human-driven work is wrong.
 - **Expanding an existing bead by re-running `create-task`.** That step creates a bead, so the original stays chore-less and gains a second parent beside it. Run `create-chores.mjs --parent <existing-id>` instead.
+- **Treating a failed expansion as unrecoverable.** `create-chores.mjs` is idempotent: re-run it and it adopts the chores that exist, creates the rest, and reports the whole mapping.
 - **Hardcoding `<skill-scripts>`.** The install path differs per harness (plugin cache, installed-plugins, dev checkout); resolve it at runtime.
 - **Creating a feature with no planning bead.** A feature that goes straight to impl children is a feature nobody designed. The planning bead keeps the children blocked until the design is confirmed.
 - **Expressing ownership as a dependency.** `bd dep add <child> <parent>` mixes hierarchy into the readiness gate; pass `--parent` at create time instead.

package/skills/planning/create-task/scripts/create-chores.mjs

@@ -2,6 +2,11 @@
 // Pre-create the pipeline stage chores for a task bead, plus the feature PR
 // review gate, from `pipeline.json`.
 //
+// Idempotent: a re-run converges on the tree that already exists instead of adding a
+// second chain beside it, so re-running after a failed expansion is the recovery path.
+// Existing children are adopted by their role label (`stage:<id>`, `lifecycle:feature-pr`)
+// under the given parent — never by title, and never across parents.
+//
 // The parent is an `execution:afk` bead. Stage chores inherit that label from it, so
 // create-chores does not classify: a parent that is hitl or unlabelled silently yields
 // a chore tree no executor routes. Check the parent's labels before invoking this.
@@ -69,6 +74,66 @@ function run(args) {
   return execSync(cmd.join(' '), { encoding: 'utf-8' }).trim();
 }
 
+// ─── Existing children ────────────────────────────────────────────────────────
+
+/**
+ * @typedef {object} Dependency
+ * @property {string} depends_on_id
+ * @property {string} type
+ */
+
+/**
+ * A child of the parent that already fills one of this script's roles.
+ * @typedef {object} Adoptable
+ * @property {string} id
+ * @property {Set<string>} blocks  Beads it already depends on with a `blocks` dep
+ */
+
+/**
+ * Read the parent's children once and index the ones this script owns by their role
+ * label. Scoped to that parent's children, so a stray chore belonging to another bead
+ * is never adopted. When a role label appears more than once the first-listed child
+ * wins, so a converged re-run is deterministic.
+ * @param {string} parentId
+ * @returns {Map<string, Adoptable>} Keyed by `stage:<id>` or `lifecycle:feature-pr`
+ */
+function readAdoptable(parentId) {
+  const raw = run(['bd', 'children', parentId, '--json']);
+  /** @type {Array<{ id: string, labels?: string[], dependencies?: Dependency[] }>} */
+  const children = raw === '' ? [] : JSON.parse(raw);
+
+  /** @type {Map<string, Adoptable>} */
+  const adoptable = new Map();
+
+  for (const child of children) {
+    const blocks = new Set(
+      (child.dependencies ?? [])
+        .filter((dep) => dep.type === 'blocks')
+        .map((dep) => dep.depends_on_id),
+    );
+
+    for (const label of child.labels ?? []) {
+      if (label !== 'lifecycle:feature-pr' && !label.startsWith('stage:')) { continue; }
+      if (!adoptable.has(label)) { adoptable.set(label, { id: child.id, blocks }); }
+    }
+  }
+
+  return adoptable;
+}
+
+/**
+ * Wire a `blocks` dependency unless the bead already carries it. Re-adding an existing
+ * dep is the failure mode a re-run must not hit, so existing deps are skipped.
+ * @param {string} beadId
+ * @param {string} dependsOnId
+ * @param {Set<string>} blocks  Dependencies the bead already has; extended in place
+ */
+function wireBlocks(beadId, dependsOnId, blocks) {
+  if (blocks.has(dependsOnId)) { return; }
+  run(['bd', 'dep', 'add', beadId, dependsOnId, '--type', 'blocks']);
+  blocks.add(dependsOnId);
+}
+
 // ─── Main ─────────────────────────────────────────────────────────────────────
 
 const __filename = fileURLToPath(import.meta.url);
@@ -80,31 +145,38 @@ const pipelinePath = resolve(__dirname, '..', 'pipeline.json');
 /** @type {Pipeline} */
 const pipeline = JSON.parse(readFileSync(pipelinePath, 'utf-8'));
 
+const adoptable = readAdoptable(parentId);
+
 /** @type {Map<string, string>} */
 const stageToBeadId = new Map();
 
 for (const stage of pipeline.stages) {
-  const title = `[${parentId}] ${stage.title}`;
-
-  const beadId = run([
-    'bd', 'create', JSON.stringify(title),
-    '--type', 'chore',
-    '--description', JSON.stringify(stage.description),
-    '--priority', priority,
-    '--labels', `stage:${stage.id}`,
-    '--parent', parentId,
-    '--silent',
-  ]);
+  const adopted = adoptable.get(`stage:${stage.id}`);
+
+  const beadId = adopted
+    ? adopted.id
+    : run([
+        'bd', 'create', JSON.stringify(`[${parentId}] ${stage.title}`),
+        '--type', 'chore',
+        '--description', JSON.stringify(stage.description),
+        '--priority', priority,
+        '--labels', `stage:${stage.id}`,
+        '--parent', parentId,
+        '--silent',
+      ]);
 
   stageToBeadId.set(stage.id, beadId);
 
+  /** @type {Set<string>} */
+  const blocks = adopted ? adopted.blocks : new Set();
+
   for (const depStageId of stage.dependsOn) {
     const depBeadId = stageToBeadId.get(depStageId);
     if (!depBeadId) {
       console.error(`Stage '${stage.id}' depends on '${depStageId}', but it has not been created yet. Check dependsOn ordering in pipeline.json.`);
       process.exit(1);
     }
-    run(['bd', 'dep', 'add', beadId, depBeadId, '--type', 'blocks']);
+    wireBlocks(beadId, depBeadId, blocks);
   }
 }
 
@@ -120,26 +192,33 @@ if (!documentStageBeadId) {
   process.exit(1);
 }
 
-const prGateBeadId = run([
-  'bd', 'create', JSON.stringify(`[${parentId}] PR Review and Merge`),
-  '--type', 'task',
-  '--description', JSON.stringify(
-    'Human review gate: review and merge the agent PR into the feature branch before closing this feature.\n\n## Acceptance Criteria\n\n- [ ] Agent PR reviewed and merged into the feature branch.',
-  ),
-  // The gate is type `task`, so `--validate` enforces its `## Acceptance Criteria`
-  // section. Stage chores require no sections and deliberately omit the flag.
-  '--validate',
-  '--priority', priority,
-  '--labels', 'execution:hitl,lifecycle:feature-pr',
-  '--parent', parentId,
-  // The gate declares its own execution class (it is human-owned review work), so opt
-  // out of bd's create-time parent-label inheritance and its explicit :hitl is never
-  // joined by an inherited :afk. Stage chores deliberately keep inheriting the parent's
-  // :afk -- do not add this flag there.
-  '--no-inherit-labels',
-  '--silent',
-]);
-run(['bd', 'dep', 'add', prGateBeadId, documentStageBeadId, '--type', 'blocks']);
+const adoptedGate = adoptable.get('lifecycle:feature-pr');
+
+const prGateBeadId = adoptedGate
+  ? adoptedGate.id
+  : run([
+      'bd', 'create', JSON.stringify(`[${parentId}] PR Review and Merge`),
+      '--type', 'task',
+      '--description', JSON.stringify(
+        'Human review gate: review and merge the agent PR into the feature branch before closing this feature.\n\n## Acceptance Criteria\n\n- [ ] Agent PR reviewed and merged into the feature branch.',
+      ),
+      // The gate is type `task`, so `--validate` enforces its `## Acceptance Criteria`
+      // section. Stage chores require no sections and deliberately omit the flag.
+      '--validate',
+      '--priority', priority,
+      '--labels', 'execution:hitl,lifecycle:feature-pr',
+      '--parent', parentId,
+      // The gate declares its own execution class (it is human-owned review work), so opt
+      // out of bd's create-time parent-label inheritance and its explicit :hitl is never
+      // joined by an inherited :afk. Stage chores deliberately keep inheriting the parent's
+      // :afk -- do not add this flag there.
+      '--no-inherit-labels',
+      '--silent',
+    ]);
+
+/** @type {Set<string>} */
+const gateBlocks = adoptedGate ? adoptedGate.blocks : new Set();
+wireBlocks(prGateBeadId, documentStageBeadId, gateBlocks);
 
 /** @type {Record<string, string>} */
 const result = {

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/productivity/migration/REFERENCE.md

@@ -77,10 +77,16 @@ Mechanics the plan reflects:
 2. Group bead ids by label value. A bead carrying both `afk` and `hitl` appears in both groups;
    that is a data problem worth inspecting, not a conflict the tool resolves for you.
 3. Per group, on `--apply`: `bd label add <ids…> execution:<value>` then
-   `bd label remove <ids…> implementation-type:<value>`. Add-then-remove keeps the routing label
-   present at every instant, so nothing is unroutable mid-flight.
+   `bd label remove <ids…> implementation-type:<value>`, at most 20 ids per call. Add-then-remove
+   keeps the routing label present at every instant, so nothing is unroutable mid-flight.
 4. Re-running after convergence finds zero targets — the no-op that proves idempotence.
 
+The 20-id ceiling is a `bd` limit, not a preference. `bd label add|remove` applies a list id by
+id and exits 0 even when it persisted only a prefix of it: one call carrying 710 ids left 280
+beads unrenamed while reporting success. Every call in this skill therefore carries one chunk of
+20 ids, and the per-step verification re-detects from the export instead of trusting the exit
+code. Any hand-run recipe below needs the same ceiling.
+
 Verification commands:
 
 ```bash
@@ -153,7 +159,8 @@ inversion.
 
 Every `bd label` call in this skill passes issue ids first and the label last, matching the CLI's
 `bd label add [issue-id...] [label[,label...]]`. Reversing that order fails: the ids are resolved
-before the trailing argument is read as a label.
+before the trailing argument is read as a label. Keep each hand-run call to about 20 ids for the
+same reason the command chunks: a longer list exits 0 having applied only part of itself.
 
 ```bash
 # Invert the v1 rename for a specific group

package/skills/workflow/ralph/REFERENCE.md

@@ -47,7 +47,7 @@ are fine.
 
 ## Expansion Guard
 
-Stage chores are pre-created, never created on demand. `create-chores.mjs` (in `skills/planning/create-task/`) reads `pipeline.json` and creates the whole chain in one shot — `code` → `verify` → `review` → `document`, plus the `featurePrReview` HITL gate — with `blocks` deps that encode the order, and with the parent's priority and inherited labels. Ralph's dispatch is therefore always "claim what `bd ready -l execution:afk` returns".
+Stage chores are pre-created, never created on demand. `create-chores.mjs` (in `skills/planning/create-task/`) reads `pipeline.json` and creates the whole chain in one shot — `code` → `verify` → `review` → `document`, plus the `featurePrReview` HITL gate — with `blocks` deps that encode the order, and with the parent's priority and inherited labels. It is idempotent: a re-run adopts the chores that already exist under the parent, creates only the missing ones, and skips deps that are already wired. Ralph's dispatch is therefore always "claim what `bd ready -l execution:afk` returns".
 
 A ready `execution:afk` task bead with **no** `stage:*` chore children has nothing to dispatch. Expand it, then dispatch the resulting `stage:code` chore:
 
@@ -57,7 +57,11 @@ A ready `execution:afk` task bead with **no** `stage:*` chore children has nothi
    ```
    Expect `0` printed. `grep -c` exits `1` when it counts zero matches, so add `|| true` when the
    check runs under `set -e` or inside an `&&` chain — the printed count is the answer, not the exit
-   status.
+   status. A bead with a full chain — one `stage:*` chore per stage in `pipeline.json` (four for the
+   shipped pipeline) plus the `lifecycle:feature-pr` gate — never needs an expansion. The check
+   answers "no chores at all", so a **partial** chain (a lower count from a failed run) passes it
+   and its missing stages never arrive. Nothing detects that automatically: re-run step 2's command
+   against that parent by hand, which is idempotent.
 2. **Dispatch an expansion worker** in the feature worktree (`.agent-cortex/worktrees/<parent-id>`) whose whole job is to run the pre-creator against the existing bead and report the JSON it printed:
    ```bash
    node <create-task-scripts>/create-chores.mjs \
@@ -93,8 +97,11 @@ On completion, remove the entry from `inflight` and confirm the chore tree exist
 bd children <parent-id> --json | grep -c '"stage:'
 ```
 
-Expect a non-zero count — one match per `stage:*` label in the chain. A printed `0` means the
-expansion failed. Surface the worker's output in chat and record the parent for the shutdown summary — **never re-dispatch the expansion**, because `create-chores.mjs` is not idempotent and a second run duplicates the chain beside the first. Then continue at the normal dispatch pass: either way nothing is created and nothing is closed by ralph.
+Expect one match per `stage:*` label in the chain — four for the shipped `pipeline.json`; the
+`featurePrReview` gate carries `lifecycle:feature-pr` instead, so it is not counted. A lower count
+means the expansion did not finish: `0` created nothing, and a partial chain leaves stages that
+will never become ready. Either way, surface the worker's output in chat, record the parent for the
+shutdown summary, and re-dispatch the expansion: `create-chores.mjs` is idempotent, so the second run adopts the chores that already exist, creates only the missing ones, and prints the full mapping — re-running is the recovery path. Then continue at the normal dispatch pass: either way nothing is created and nothing is closed by ralph.
 
 ---
 
@@ -130,7 +137,7 @@ Decompose it:
    bd children <feature-id> --json
    ```
    Surface the created IDs in chat. An empty list means the decomposition failed: record the feature for the shutdown summary and continue — do not re-dispatch.
-5. **Never re-dispatch a decomposition.** The bead creation it runs is not idempotent, so a second run duplicates the planning bead and every implementation child beside the first. This is the same hazard as re-running `create-chores.mjs`.
+5. **Never re-dispatch a decomposition.** The bead creation it runs is not idempotent, so a second run duplicates the planning bead and every implementation child beside the first. This hazard belongs to `create-task`'s bead creation alone — `create-chores.mjs` is idempotent, so re-running an expansion is its recovery path.
 6. **Go idle.** After decomposition nothing is dispatchable for that feature: `bd ready -l execution:afk` still lists the feature itself (it now has children, so it is skipped — never decomposed again) but none of its children until a human closes the planning bead. Returning to the event loop with *nothing* to dispatch is the correct outcome, not a failure to re-expand — that is Q5b working as designed.
 
 ---