@jaybeeuu/agent-cortex 2.4.1 → 2.5.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## 2.5.0
+
+### Minor Changes
+
+- 8ca9462: New `cortex` and `ctx` commands: both run the same CLI as `agent-cortex`. The help text and the error hints now name the command that was invoked, so `ctx --help` prints `Usage: ctx <command>`; any other script name falls back to `agent-cortex`.
+- 45992c7: `create-chores.mjs` is now idempotent: a re-run adopts the stage chores and PR gate that already exist under the parent, creates only what is missing, and skips deps that are already wired. Re-running it after a failed chore expansion is now the recovery path, so ralph no longer refuses to re-dispatch an expansion.
+
+### Patch Changes
+
+- 2cab55e: Chunk the `migrate` v1 label rename: each `bd label add` and `bd label remove` call
+  now carries at most 20 bead ids. One call carrying every id in a large workspace
+  applied only part of the list and still reported success, so v1 never converged and a
+  workspace could report itself migrated with hundreds of legacy labels attached.
+- dd4e69c: Fail `agent-cortex install pi` when a skill sits outside `skills/<group>/<name>`.
+
+  pi advertises a skill by the absolute path of its `SKILL.md`, and the installer copies exactly
+  `skills/<group>/<name>`. A skill authored deeper was skipped without a trace, so no session was
+  ever told about it. The install now stops and names the offending path.
+
+  `docs/dev-loop.md` records the related limit that needs no code: a session lists its skills when
+  it starts, so a session already open across a re-stage holds the paths it was given.
+
+## 2.4.2
+
+### Patch Changes
+
+- 015ede5: Stop the Claude install from dropping `{{TOOL:read_agent}}` and `{{TOOL:wait_for_agents}}`
+  into dangling prose. Both tokens are null on the claude column (Claude reports a subagent's
+  result inline, so there is no separate read or wait step), so the installer replaced them with
+  an empty string and warned three times — leaving `Read the completed agent's output with  and
+parse…` and two similar broken sentences in the installed `ralph` and `design-an-interface`
+  skills. Those sentences are now harness-neutral, so both installs read correctly and the
+  installer emits no null-mapping warning. A regression guard fails the installer test if a
+  shipped skill names a tool the claude column cannot map.
+- 199cefe: Point the shipped pi settings at models that still exist. `tinyModel.model` was
+  `opencode/mimo-v2.5-free`, which the provider catalogue has dropped, so the
+  setting resolved to nothing and pi fell back to another free model. That fallback
+  returns `429 FreeUsageLimitError` once the free quota is spent, and the 429 JSON
+  became the entire output of the background call that runs auto-naming and
+  notifications — so a subagent run died at session start while the agent itself was
+  on a paid model. `tinyModel.model` is now `opencode-go/deepseek-v4.1-flash`.
+  `enabledModels` also drops three ids that do not resolve — `opencode-go/deepseek-v4-flash`,
+  `opencode/deepseek-v4-flash` and `opencode/mimo-v2.5-free` — which made pi print a
+  `No models match pattern` warning on every startup.
+- 6b6080b: Stop the test suite from leaking temp workspaces into `/tmp`. Each test file that
+  creates workspaces under the system temp dir now shares one temp root that a
+  file-level `after()` hook removes, so the removal happens whether the tests
+  passed, failed, or threw before reaching their own cleanup — previously a single
+  green run of `test/installer.test.mjs` left 21 workspaces behind (7.4 MB apparent,
+  13 MB on disk: each is a materialised plugin tree of skills, agents and hooks),
+  plus one from `test/cli.test.mjs`'s `install claude --output` case. Repeated runs
+  could fill a small tmpfs and make unrelated tests fail with ENOSPC. A regression
+  guard runs a deliberately failing test file and asserts the run leaves nothing
+  behind.
+
 ## 2.4.1
 
 ### Patch Changes

package/README.md

@@ -151,6 +151,11 @@ long-lived credential in repository secrets to save one click per release.
 
 ## Installation
 
+The CLI installs under three names — `agent-cortex`, `cortex` and `ctx` — that run the
+same command, and the help and error text names the one you invoked. That naming is POSIX
+only: the npm and pnpm shims on Windows call `bin/agent-cortex.mjs` directly, so the text
+falls back to `agent-cortex` there.
+
 ### Pi package staging (`agent-cortex install pi`)
 
 `agent-cortex install pi` materialises agent-cortex as a self-contained pi
@@ -480,7 +485,8 @@ is an empty legacy namespace, not just a clean live one (see
 A bare `agent-cortex migrate` is a **dry run** — it prints the per-bead plan and writes
 nothing. `--apply` runs every pending step in order and verifies each before moving on. It
 shells out to the `bd` CLI on `PATH` (`BD_PATH` overrides) and fails loudly, rather than
-half-applying, when `bd` is missing or a `bd` subcommand errors.
+half-applying, when `bd` is missing or a `bd` subcommand errors. Label writes carry at most 20
+ids per `bd` call, because `bd` can exit 0 having applied only part of a longer list.
 
 Detection reads `bd export --all` and cross-checks `bd label list-all`, never a
 label-filtered `bd list`: on bd 1.3.1 that query can omit closed beads, which once let a

package/agents/ralph/agent.md

@@ -77,7 +77,7 @@ A feature carries `execution:hitl` by default, so this whole procedure only runs
 
 A ready `execution:afk` task bead with no `stage:*` chore children has nothing to dispatch, so it is not dispatched as work. Expand it first, then let the normal dispatch pick up the resulting `stage:code` chore:
 
-1. Confirm the bead is chore-less: `bd children <parent-id> --json | grep -c '"stage:'` prints `0` — add `|| true` under `set -e` or inside an `&&` chain, since `grep -c` exits `1` on a zero count and the printed number is the answer. A bead that already has stage chores is never expanded again.
+1. Confirm the bead is chore-less: `bd children <parent-id> --json | grep -c '"stage:'` prints `0` — add `|| true` under `set -e` or inside an `&&` chain, since `grep -c` exits `1` on a zero count and the printed number is the answer. A bead with a full chain — one `stage:*` chore per stage in `pipeline.json`, plus the `lifecycle:feature-pr` gate — never needs an expansion. This check only sees a count of zero, so a **partial** chain is not detected here and its missing stages never arrive: 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>`, created per the branching model if it is missing) whose whole job is to run the pre-creator against the existing bead and report the JSON it printed:
 
    ```bash
@@ -86,6 +86,8 @@ A ready `execution:afk` task bead with no `stage:*` chore children has nothing t
    ```
 
    `<create-task-scripts>` is the absolute path to the `create-task` skill's `scripts/` directory, resolved from wherever the skill was loaded. `<parent-priority>` is the parent bead's own priority from `bd show <parent-id>`.
+
+   The command is idempotent: it adopts an existing child by its `stage:<id>` or `lifecycle:feature-pr` label, creates only what is missing, skips deps that are already wired, and prints the resolved mapping either way. Re-running it is the recovery path for a failed expansion.
 3. Record the worker in `inflight` as an **expansion** entry — it has no chore to key on, so `choreId` is `null`:
    ```json
    { "kind": "expand", "choreId": null, "parentId": "<parent-id>", "title": "<parent title>", "agentId": "<agent-id>", "logLine": 1 }
@@ -94,7 +96,7 @@ A ready `execution:afk` task bead with no `stage:*` chore children has nothing t
 4. The worker reports the returned mapping — `code`, `verify`, `review`, `document`, `featurePrReview` — and closes nothing. It emits **no** `---REPORT---` block and owns no bead, so there is nothing to parse and no close to confirm.
 5. Its completion means the parent now has a `stage:*` chain: the event loop's next `bd ready -l execution:afk` pass picks up the `stage:code` chore (event loop step 7).
 
-**Expansion completion contract.** An expansion worker is dispatched like a stage worker but is not one: no chore claim, no `---REPORT---`, no leaf-bead close. Handle its completion with the expansion branch in event-loop step 3, which confirms the chain exists (`bd children <parent-id> --json | grep -c '"stage:'` prints a non-zero count) and dispatches the ready `stage:code` chore. If the parent still has no `stage:*` children the expansion failed: surface the worker's output in chat, **never re-run `create-chores.mjs`** (it is not idempotent — a second run duplicates the chain), and record the parent for the shutdown summary. Either way, create nothing and close nothing.
+**Expansion completion contract.** An expansion worker is dispatched like a stage worker but is not one: no chore claim, no `---REPORT---`, no leaf-bead close. Handle its completion with the expansion branch in event-loop step 3, which confirms the chain exists (`bd children <parent-id> --json | grep -c '"stage:'` prints one match per stage chore — the gate carries `lifecycle:feature-pr` and is not counted) and dispatches the ready `stage:code` chore. A count below the stage total in `pipeline.json` is a partial chain, whose missing stages never arrive, so re-dispatch the expansion instead of dispatching on. If the parent still has no `stage:*` children the expansion failed: 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 a second run adopts the chores that exist, creates only the missing ones, and reports the whole mapping. Either way, create nothing and close nothing yourself.
 
 **Never expand an existing bead by running `create-task`** (or any other command that creates a bead). `create-task` creates a bead first and expands second, so running it for an existing bead leaves a **second parent** beside the original, which stays chore-less and never gets dispatched. `create-chores.mjs` expands a bead that already exists; it never creates parents.
 
@@ -165,8 +167,8 @@ After initialization, Ralph waits for background agents to complete. Completions
 1. **Flush** that bead's log using the procedure in the wake section to pick up any final lines for the chat summary (a mechanism that delivers the log with the completion needs no flush).
 2. **Read** the completed agent's full output the way the wake section describes.
 3. **Re-read** `.agent-cortex/ralph/state.json` to identify the entry for that agent ID, then branch on its `kind`:
-   - **`kind: "expand"` — expansion completion branch.** The worker claimed no chore, emits no `---REPORT---`, and owns no bead to confirm, so steps 4-6 **do not apply**: remove the entry from `inflight`, confirm the parent now has `stage:*` chore children (`bd children <parent-id> --json | grep -c '"stage:'`) and surface the reported mapping in chat, then go straight to step 7 — the new `stage:code` chore is ready to dispatch. If the parent still has no `stage:*` children the expansion failed: surface the worker's output, do **not** re-run `create-chores.mjs` (not idempotent), record the parent for the shutdown summary, remove the entry, and continue at step 7. Never create or close a bead for an expansion.
-   - **`kind: "decompose"` — decomposition completion branch.** Same shape as expansion: no chore, no `---REPORT---`, so steps 4-6 **do not apply**: remove the entry from `inflight`, confirm the feature now has children (`bd children <feature-id> --json` returns a non-empty list) and surface the created IDs in chat, then go straight to step 7. Nothing is dispatchable for that feature until a human closes the planning bead, so finding no ready work for it is the correct outcome — do **not** re-dispatch the decomposition (the bead creation it ran is not idempotent). If the feature still has no children, the worker failed: surface its output, record it for the shutdown summary, remove the entry, and continue at step 7. Never create or close a bead here.
+   - **`kind: "expand"` — expansion completion branch.** The worker claimed no chore, emits no `---REPORT---`, and owns no bead to confirm, so steps 4-6 **do not apply**: remove the entry from `inflight`, confirm the parent now has `stage:*` chore children (`bd children <parent-id> --json | grep -c '"stage:'`) and surface the reported mapping in chat, then go straight to step 7 — the new `stage:code` chore is ready to dispatch. If the count is `0` — or below the stage total, which is a partial chain whose later stages never arrive — the expansion failed: surface the worker's output, record the parent for the shutdown summary, remove the entry, and re-dispatch the expansion — re-running `create-chores.mjs` is idempotent and is the recovery path, so it repairs the tree instead of duplicating it. Never create or close a bead for an expansion.
+   - **`kind: "decompose"` — decomposition completion branch.** Same shape as expansion: no chore, no `---REPORT---`, so steps 4-6 **do not apply**: remove the entry from `inflight`, confirm the feature now has children (`bd children <feature-id> --json` returns a non-empty list) and surface the created IDs in chat, then go straight to step 7. Nothing is dispatchable for that feature until a human closes the planning bead, so finding no ready work for it is the correct outcome — do **not** re-dispatch the decomposition (the bead creation it ran is not idempotent; that hazard is `create-task`'s, not the expansion's). If the feature still has no children, the worker failed: surface its output, record it for the shutdown summary, remove the entry, and continue at step 7. Never create or close a bead here.
    - **`kind: "stage"`** — a stage worker: continue with steps 4-6.
 4. **Parse** the agent's `---REPORT---` block (see report format in the `run-pipeline-stage` skill).
 5. **Confirm** the worker closed its own leaf execution bead: `bd show <chore-id>` should read `closed`. If it is still open the worker died mid-stage — read its notes and re-dispatch. Never close it yourself.

package/bin/agent-cortex.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { parseArgs, buildHelpText, validateHarness } from "../lib/cli.mjs";
+import { parseArgs, buildHelpText, resolveProgramName, validateHarness } from "../lib/cli.mjs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readFile } from "node:fs/promises";
@@ -10,10 +10,12 @@ import { installPi, registerPi, sweepLegacyPiUserDirs } from "./installers/pi.mj
 /** @typedef {import("./installers/pi.mjs").RegisterPiResult} RegisterPiResult */
 
 const argv = process.argv.slice(2);
-const parsed = parseArgs(argv);
+// `agent-cortex`, `cortex` and `ctx` all run this file; the text names the one used.
+const programName = resolveProgramName(process.argv[1]);
+const parsed = parseArgs(argv, programName);
 
 if (parsed.command === "help") {
-  process.stdout.write(buildHelpText() + "\n");
+  process.stdout.write(buildHelpText(programName) + "\n");
   process.exit(0);
 }
 
@@ -53,7 +55,7 @@ if (parsed.command === "version") {
 }
 
 if (parsed.command === "unknown") {
-  process.stderr.write(`Unknown command: ${parsed.name}\nRun "agent-cortex --help" for usage.\n`);
+  process.stderr.write(`Unknown command: ${parsed.name}\nRun "${programName} --help" for usage.\n`);
   process.exit(1);
 }
 
@@ -65,7 +67,7 @@ if (parsed.command === "install") {
 
   const check = validateHarness(parsed.harness);
   if (!check.ok) {
-    process.stderr.write(`${check.error}\nRun "agent-cortex --help" for usage.\n`);
+    process.stderr.write(`${check.error}\nRun "${programName} --help" for usage.\n`);
     process.exit(1);
   }
 

package/bin/installers/pi.mjs

@@ -395,7 +395,19 @@ async function installSkills({ root, skillsDir, dryRun, pluginRoot, tokenMap, wa
     const groupDir = join(skillsSrc, group);
     if (!(await isDirectory(groupDir))) continue;
     for (const name of (await readdir(groupDir)).sort()) {
-      if (!(await isFile(join(groupDir, name, "SKILL.md")))) continue;
+      if (!(await isFile(join(groupDir, name, "SKILL.md")))) {
+        // pi advertises a skill by the absolute path of its SKILL.md, and this
+        // installer carries exactly skills/<group>/<name>. A skill authored
+        // below that depth would be dropped without a trace, so fail instead.
+        const nested = await findSkillFiles(join(groupDir, name));
+        if (nested.length > 0) {
+          throw new Error(
+            `skill "${nested[0]}" is not at skills/<group>/<name>/SKILL.md — ` +
+              "the installer copies exactly that depth, so pi would never advertise this skill",
+          );
+        }
+        continue;
+      }
       skills += 1;
       const stats = await copyTree(join(groupDir, name), join(skillsDir, group, name), { dryRun, transform });
       md += stats.md;
@@ -405,6 +417,28 @@ async function installSkills({ root, skillsDir, dryRun, pluginRoot, tokenMap, wa
   return { skills, md, files, dir: skillsDir };
 }
 
+/**
+ * Every `SKILL.md` below `dir`, recursively — the skills pi would advertise if
+ * its discovery walked the repository tree instead of the staged one.
+ * @param {string} dir
+ * @returns {Promise<string[]>}
+ */
+async function findSkillFiles(dir) {
+  /** @type {string[]} */
+  const found = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return found;
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) found.push(...(await findSkillFiles(join(dir, entry.name))));
+    else if (entry.isFile() && entry.name === "SKILL.md") found.push(join(dir, entry.name));
+  }
+  return found;
+}
+
 // ─── Extensions ──────────────────────────────────────────────────────────────
 
 /**

package/lib/cli.mjs

@@ -1,3 +1,5 @@
+import { basename } from "node:path";
+
 /**
  * Result of parsing the CLI argv. Every branch returns `command`; the rest are
  * populated only for the commands that accept them.
@@ -18,6 +20,24 @@
 
 const SUPPORTED_HARNESSES = ["claude", "pi"];
 
+// The published bin names. `package.json` maps all three onto bin/agent-cortex.mjs,
+// so the help and error text names whichever shim the user typed.
+const PROGRAM_NAMES = ["agent-cortex", "cortex", "ctx"];
+const DEFAULT_PROGRAM_NAME = "agent-cortex";
+
+/**
+ * Resolve the program name to print from the path the CLI was invoked as. Only
+ * the published command names are recognised; anything else (a bare `node
+ * bin/agent-cortex.mjs`, a renamed copy) falls back to `agent-cortex`, so the
+ * text always names a command that exists.
+ * @param {string | undefined} invokedPath `process.argv[1]`, or a bare name in tests
+ * @returns {string}
+ */
+export function resolveProgramName(invokedPath) {
+  const name = basename(invokedPath ?? "");
+  return PROGRAM_NAMES.includes(name) ? name : DEFAULT_PROGRAM_NAME;
+}
+
 // Options accepted by `install <harness>`. `--output`/`--dry-run` are shared by
 // the claude and pi installers; `--plugin-root` is pi-specific. Unknown or
 // malformed options surface as `optionError` on the parsed result; the CLI
@@ -33,9 +53,10 @@ const INSTALL_OPTIONS = {
 /**
  * Parse the CLI argv.
  * @param {string[]} argv
+ * @param {string} [programName] The resolved command name, for usage hints
  * @returns {ParsedArgs}
  */
-export function parseArgs(argv) {
+export function parseArgs(argv, programName = DEFAULT_PROGRAM_NAME) {
   if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
     return { command: "help" };
   }
@@ -64,7 +85,7 @@ export function parseArgs(argv) {
       const inlineValue = arg.startsWith("--output=") ? arg.slice("--output=".length) : null;
       const spec = inlineValue !== null ? INSTALL_OPTIONS["--output"] : INSTALL_OPTIONS[arg];
       if (!spec) {
-        return { command: "install", harness, optionError: `Unknown option "${arg}". Run "agent-cortex --help" for usage.` };
+        return { command: "install", harness, optionError: `Unknown option "${arg}". Run "${programName} --help" for usage.` };
       }
       if (spec.boolean) {
         options[spec.key] = true;
@@ -76,7 +97,7 @@ export function parseArgs(argv) {
       }
       const value = rest[i + 1];
       if (value == null || value.startsWith("--")) {
-        return { command: "install", harness, optionError: `Missing value for "${arg}". Run "agent-cortex --help" for usage.` };
+        return { command: "install", harness, optionError: `Missing value for "${arg}". Run "${programName} --help" for usage.` };
       }
       options[spec.key] = value;
       i += 1;
@@ -116,13 +137,13 @@ export function parseArgs(argv) {
       if (arg === "--dir" || inlineDir !== null) {
         const value = rest[i + 1];
         if (inlineDir !== null || value == null || value.startsWith("--")) {
-          return { command: "migrate", optionError: `Missing value for "--dir". Run "agent-cortex --help" for usage.` };
+          return { command: "migrate", optionError: `Missing value for "--dir". Run "${programName} --help" for usage.` };
         }
         dir = value;
         i += 1;
         continue;
       }
-      return { command: "migrate", optionError: `Unknown option "${arg}". Run "agent-cortex --help" for usage.` };
+      return { command: "migrate", optionError: `Unknown option "${arg}". Run "${programName} --help" for usage.` };
     }
     if (sawApply && sawDryRun) {
       return { command: "migrate", optionError: '"--apply" and "--dry-run" are mutually exclusive.' };
@@ -134,10 +155,11 @@ export function parseArgs(argv) {
 }
 
 /**
+ * @param {string} [programName] The resolved command name, for the usage line
  * @returns {string}
  */
-export function buildHelpText() {
-  return `Usage: agent-cortex <command> [options]
+export function buildHelpText(programName = DEFAULT_PROGRAM_NAME) {
+  return `Usage: ${programName} <command> [options]
 
 Commands:
   install <harness>   Install agent-cortex for a harness

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaybeeuu/agent-cortex",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "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/engineering/design-an-interface/SKILL.md

@@ -55,7 +55,7 @@ description: "Generate multiple radically different interface designs for a modu
    4. Trade-offs of this approach
    ```
 
-   Collect each agent's output with {{TOOL:read_agent}} when it finishes.
+   Collect each agent's output as it finishes.
 
 3. **Present designs.** Show each design sequentially — signature, usage examples, what it hides — so the user absorbs each approach before any comparison happens.
 

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
 

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/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.
 
 ---

package/skills/workflow/ralph/SKILL.md

@@ -41,26 +41,28 @@ State model: task state lives in beads (ready/in_progress via `bd`); the only lo
    - **Bead that already has its children** (a decomposed feature, an expanded task parent): skip it — it is not dispatchable itself, and its `stage:*` chore is dispatched on its own.
    `execution:hitl` beads are not in this query and are not ralph's to touch: record them for the Pending Human Action summary. That includes every feature still at its default `execution:hitl` label.
 7. Dispatch each unit from its parent's worktree, up to 5 in flight: a stage chore via the event loop, a childless feature via a decomposition worker (_Feature decomposition_), a chore-less task via an expansion worker (_Expansion guard_). Create branches and worktrees first (REFERENCE.md, _Feature Branches and Worktrees_).
-8. Hand over to your harness's completion-detection mechanism: PI keeps a {{TOOL:wait_for_agents}} call outstanding over every in-flight agent ID, and Claude re-invokes you as each worker completes. If no **agent work** was dispatched — `state.json`'s `inflight` holds no entries, so no stage, decomposition or expansion worker is running — and `skills/workflow/ralph/scripts/pending-gates.mjs` reports a non-empty `pendingHumanAction` (an unblocked `lifecycle:feature-pr` gate, or an epic tagged `awaiting-epic-pr-merge`), go straight to HITL Pause (REFERENCE.md). A decomposition- or expansion-only init is in flight, not idle: keep the completion mechanism running and continue at the event loop.
+8. Hand over to your harness's completion-detection mechanism: PI keeps a blocking wait outstanding over every in-flight agent ID, and Claude re-invokes you as each worker completes. If no **agent work** was dispatched — `state.json`'s `inflight` holds no entries, so no stage, decomposition or expansion worker is running — and `skills/workflow/ralph/scripts/pending-gates.mjs` reports a non-empty `pendingHumanAction` (an unblocked `lifecycle:feature-pr` gate, or an epic tagged `awaiting-epic-pr-merge`), go straight to HITL Pause (REFERENCE.md). A decomposition- or expansion-only init is in flight, not idle: keep the completion mechanism running and continue at the event loop.
 
 ### 2. Expansion guard (stage chores are pre-created)
 
 A ready `execution:afk` task bead with no `stage:*` chore children has nothing to dispatch, so it is not dispatched as work. Expand it first: dispatch a worker in the feature worktree that runs `create-chores.mjs --parent <id> --priority <parent-priority>` against the existing bead and reports the returned `code`/`verify`/`review`/`document`/`featurePrReview` mapping — the next `bd ready -l execution:afk` pass then picks up `stage:code` (see REFERENCE.md, _Expansion Guard_).
 
+The expansion is idempotent and re-running it is the recovery path: the script adopts the chores that already exist under the parent, creates only the missing ones, and reports the whole mapping. The auto-recovery fires only when a re-check finds no `stage:*` chore at all; a **partial** chain (a count below the stage total) needs a manual re-run of that same command.
+
 **Never expand an existing bead with `create-task`.** It creates a bead first and expands second, so the original would stay chore-less and gain a **second parent** beside it. `create-chores.mjs` expands; only `create-task` creates parents.
 
 ### 3. Feature decomposition
 
 A ready `execution:afk` bead of type `feature` with no children is not dispatchable work — there is nothing to stage and nothing to expand. Decompose it: dispatch a worker in `.agent-cortex/worktrees/<feature-id>` that turns the feature into one `execution:hitl` planning bead plus `execution:afk` implementation children that depend on it, then continue (REFERENCE.md, _Feature Decomposition_).
 
-A feature carries `execution:hitl` by default, so this only runs when a human has deliberately relabelled a feature `execution:afk` to make its delivery agent-routable. Decomposition is then the last thing ralph does with it for a while: the children depend on the planning bead, so once the worker reports, `bd ready -l execution:afk` returns only the feature itself — no dispatchable child — and skipping that row is the *correct* behaviour, not re-expanding. **Never re-dispatch a decomposition**: the bead creation it runs is not idempotent, so a second run duplicates the whole hierarchy.
+A feature carries `execution:hitl` by default, so this only runs when a human has deliberately relabelled a feature `execution:afk` to make its delivery agent-routable. Decomposition is then the last thing ralph does with it for a while: the children depend on the planning bead, so once the worker reports, `bd ready -l execution:afk` returns only the feature itself — no dispatchable child — and skipping that row is the *correct* behaviour, not re-expanding. **Never re-dispatch a decomposition**: the bead creation it runs is not idempotent, so a second run duplicates the whole hierarchy. That hazard is `create-task`'s, not `create-chores.mjs`'s — the expansion is idempotent.
 
 ### 4. Event loop
 
 On each completion notification (a background agent finished):
 
 1. Poll that parent's log for new lines — `tail -n +<nextLine> .agent-cortex/ralph/ralph-<parent-id>.log` (logs are keyed by parent bead ID, so every stage of a feature shares one file) — and post only new key events (stage transitions, test/lint results), never empty updates.
-2. Read the completed agent's output with {{TOOL:read_agent}} and parse its `---REPORT---` block for `BEAD_ID`, `STAGE_COMPLETED`, and the outcome. A **decomposition** (`kind: "decompose"`) or **expansion** (`kind: "expand"`) worker has no REPORT and no leaf bead to confirm. An **expansion worker** owns no bead — confirm the parent now has `stage:*` chores (`bd children <parent-id> --json | grep -c '"stage:'`) and skip to step 5 to dispatch its ready `stage:code` chore. A **decomposition worker** — confirm the feature now has children (`bd children <feature-id> --json` returns a non-empty list), record that nothing is dispatchable for it until a human closes the planning bead, and skip to step 5; never re-decompose. If either confirmation comes back empty, the worker failed: surface its output, record the parent for the shutdown summary, and do not re-dispatch.
+2. Read the completed agent's output and parse its `---REPORT---` block for `BEAD_ID`, `STAGE_COMPLETED`, and the outcome. A **decomposition** (`kind: "decompose"`) or **expansion** (`kind: "expand"`) worker has no REPORT and no leaf bead to confirm. An **expansion worker** owns no bead — confirm the parent now has `stage:*` chores (`bd children <parent-id> --json | grep -c '"stage:'`) and skip to step 5 to dispatch its ready `stage:code` chore. A count of `0` means the expansion produced no chores at all; a count below the stage total means the chain is **partial**. Both are failures: surface the worker's output and re-run `create-chores.mjs --parent <id>`, which adopts the chores already present and creates only the missing ones, so the re-run is the recovery path and it never needs a second chain. A **decomposition worker** — confirm the feature now has children (`bd children <feature-id> --json` returns a non-empty list), record that nothing is dispatchable for it until a human closes the planning bead, and skip to step 5; never re-decompose. If a decomposition's confirmation comes back empty, the worker failed: surface its output, record the parent for the shutdown summary, and do not re-dispatch.
 3. Confirm the stage worker closed its chore bead: `bd show <bead-id>` should read `closed` with the outcome in its close reason. If it is still open the worker died mid-stage — read its notes and re-dispatch; never close it yourself.
 4. Route the parent per the dispatch table — nothing is created here: the pre-created chain already encodes the order, and the worker owns any remediation it needs.
 
@@ -124,6 +126,7 @@ Both paths end in a **gated** `bd dolt push`: on a non-zero exit, retry once, th
 | "The review passed, so I can merge" | Feature and epic PR merges are human-controlled; the gate exists so a person sees every change. |
 | "The worker left the chore open — I'll close it" | The worker owns that bead; an open one means it died mid-stage, so read its notes and re-dispatch instead of closing over the missing record. |
 | "This bead has no chores — I'll create them as I go" | The whole chain is pre-created with `blocks` deps; hand-creating stages duplicates chores and loses the order. Expand with `create-chores.mjs` instead. |
+| "The expansion failed, so I'll build the missing chores by hand" | Re-run `create-chores.mjs --parent <id>`: it is idempotent, so it adopts the chores that exist, creates only the missing ones, and reports the whole mapping. |
 | "That feature came back ready again, so I'll decompose it a second time" | The implementation children depend on the planning bead, so nothing is ready until a human closes it. Re-decomposing duplicates the hierarchy; idling *is* the correct outcome. |
 
 ## Philosophy / rationale
@@ -156,6 +159,6 @@ Do not invoke `classify-bead` from this loop — classification was applied at p
 - [ ] In-flight count never exceeded 5, and the read-only cap backstop ran before every `stage:*` dispatch.
 - [ ] Every in-flight, dispatchable-work, HITL-pause, and shutdown predicate was read from `state.json`'s `inflight` (stage, decomposition **and** expansion workers) plus `bd ready -l execution:afk`, with the ready, claimable scope of a chore-less `execution:afk` task bead — never from a chore-only `bd` query, and never counting a bead an open `lifecycle:feature-pr` gate blocks from being claimed.
 - [ ] Ralph closed no leaf execution bead and created no fix bead; every closed chore carries its worker's close reason.
-- [ ] Any chore-less `execution:afk` task bead was expanded with `create-chores.mjs` (one parent bead), never with `create-task`.
+- [ ] Any chore-less `execution:afk` task bead was expanded with `create-chores.mjs` (one parent bead), never with `create-task`; a failed expansion was recovered by re-running that same idempotent command.
 - [ ] Feature and epic PRs were pushed and reported immediately at their gates, and nothing was auto-merged.
 - [ ] Every `bd dolt push` before HITL Pause/Shutdown exited 0 — a non-zero exit was retried once, then surfaced as a blocker (command, exit code, stderr) with no completion or Pending Human Action summary printed; status was reported from `bd` commands rather than a generated file, and the chat received no empty poll updates.