@jaybeeuu/agent-cortex 2.5.1 → 2.7.0

package/skills/workflow/ralph/SKILL.md

@@ -9,7 +9,7 @@ Ralph is a parallel orchestration loop. It advances `execution:afk` beads throug
 
 One query decides what ralph works on: **`bd ready -l execution:afk`**. Features, tasks and chores all arrive through it, and each bead's *shape* — not a second `bd` filter — decides which procedure carries it: a childless feature is decomposed, a bead with no stage chores is expanded, a stage chore is dispatched. An `execution:afk` bead is therefore never invisible to ralph for lacking a `stage:*` label, and ralph never invents a narrower "only stage chores" predicate that would hide one.
 
-Each leaf execution bead belongs to the worker that ran it: the worker appends its milestone notes, closes the bead on both outcomes, and builds its own `stage:fix` + fresh-stage remediation chain when it fails. Ralph reads beads and routes — it never closes a leaf bead and never creates a fix bead. Its only retry control is a read-only cap backstop.
+Each leaf execution bead belongs to the worker that ran it: the worker appends its milestone notes, closes the bead on both outcomes, and builds its own `stage:fix` + fresh-stage remediation chain when it fails. The `housekeeping` worker is the exception — it never closes its chore over a worktree the pruner did not remove, and it builds no chain. Ralph reads beads and routes — it never closes a leaf bead and never creates a fix bead. Its only retry control is a read-only cap backstop.
 
 State model: task state lives in beads (ready/in_progress via `bd`); the only local file is `.agent-cortex/ralph/state.json`, holding the agent-ID→bead mapping. Pipeline configuration comes from `skills/planning/create-task/pipeline.json`, and stage execution belongs to the `run-pipeline-stage` skill. Stage chores are pre-created from that pipeline when a task is expanded — with `blocks` deps encoding the order — so ralph's dispatch is always "claim what `bd ready -l execution:afk` returns"; it never creates a stage chore.
 
@@ -45,7 +45,7 @@ State model: task state lives in beads (ready/in_progress via `bd`); the only lo
 
 ### 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_).
+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`/`housekeeping`/`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.
 
@@ -74,7 +74,8 @@ On each completion notification (a background agent finished):
    | `verify` | `OUTCOME: BLOCKED` | Create nothing — the worker built `stage:fix` + a fresh `stage:verify`; dispatch the ready fix chore |
    | `review` | `OUTCOME: SUCCESS` | Closing the review chore unblocks the document chore |
    | `review` | `OUTCOME: BLOCKED` | Create nothing — the worker built `stage:fix` + a fresh `stage:review`; dispatch the ready fix chore |
-   | `document` | `OUTCOME: SUCCESS` | Open/update the feature PR now (`feature/<parent-id>` → its base branch), report the URL, and update the child HITL gate bead (`lifecycle:feature-pr`). Wait for a human to close that bead after merge, then `bd close <parent-id>` |
+   | `document` | `OUTCOME: SUCCESS` | Open/update the feature PR now (`feature/<parent-id>` → its base branch), report the URL, and update the child HITL gate bead (`lifecycle:feature-pr`). Wait for a human to close that bead after merge, then `bd close <parent-id>` — closing the gate unblocks the pre-created `stage:housekeeping` chore, which removes the worktrees of closed beads |
+   | `housekeeping` | `OUTCOME: SUCCESS` | Nothing further — it is the last stage; its closed chore ends the pipeline |
    | any | parent status `blocked` | Nothing — the worker hit `maxFixRounds`; record the parent for the shutdown summary |
 
 5. Run `bd ready -l execution:afk` and dispatch new ready work while the in-flight count is under 5 — max 5 parent features, counted from `state.json`'s `inflight` (a parent counts while any of its workers — stage, `kind: "decompose"` or `kind: "expand"` — sits in `inflight`; REFERENCE.md, _State Files_). A ready childless feature is decomposed, not staged, and a ready bead with no chore tree is expanded (see _Feature decomposition_ and _Expansion guard_ above). Before each dispatch run the read-only cap backstop (REFERENCE.md, _Cap Backstop_): at `maxFixRounds` block the parent and create nothing. Do not schedule new parent features while `pending-gates.mjs` reports a non-empty `pendingHumanAction` — that is, while a `lifecycle:feature-pr` gate is **unblocked**. Gates still blocked behind their own pipeline (pre-created for a feature that has not reached its PR stage) are parked and never stop dispatch.
@@ -96,7 +97,7 @@ bd show <id>                   # full detail, including the worker's notes
 - **Multi-feature epics** (two or more feature task children): the epic runs on `epic/<epic-id>`, based on `origin/main` — never local `main`. Each `execution:afk` parent task runs on `feature/<parent-id>`, based from its epic branch, in the dedicated worktree `.agent-cortex/worktrees/<parent-id>`.
 - Feature PR gate: `feature/<parent-id>` → `epic/<epic-id>` (or → `main` for single-feature epics). Epic PR gate: `epic/<epic-id>` → `main`.
 - **Never stack branches.** `feature/<parent-id>` is based on `epic/<epic-id>` (or `origin/main`), never on another `feature/*`. A dependency between two tasks lives in the bead graph (`bd dep add <waiting> <blocked-on>`) so the dependent task stays out of `bd ready` until its dependency has merged — stacking the branch defeats that gate by hand and costs a rebase-on-squash later (see `git-workflow` rule 3).
-- Branch/worktree setup and the PR commands live in REFERENCE.md (_Feature branches and worktrees_, _Feature PR gate_).
+- Branch/worktree setup and the PR commands live in REFERENCE.md (_Feature branches and worktrees_, _Feature PR gate_). Closed-bead worktrees are reclaimed by `skills/workflow/ralph/scripts/prune-worktrees.mjs`, which removes worktrees whose bead is closed, reports the rest, and removes an orphan only with `--remove-orphans` (REFERENCE.md, _Pruning Worktrees_). The `stage:housekeeping` chore runs it: dispatch that chore with the **main checkout** as cwd, not the feature worktree, because the worktree it removes may be the parent's own. A non-zero exit gets one retry; a closed-bead worktree still refused after it fails the chore, which stays open.
 
 ### 7. HITL pause and shutdown
 

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

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

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

@@ -1,11 +1,11 @@
 ---
 name: run-pipeline-stage
-description: Execute a single pipeline stage for a bead (code, verify, review, document) via its playbook and read-only routing, reporting the outcome in a fixed REPORT shape. Use when you want to "work through beads inline", "pick up a specific stage bead", or run one stage "without the full ralph orchestrator".
+description: Execute a single pipeline stage for a bead (code, verify, review, document, housekeeping) via its playbook and read-only routing, reporting the outcome in a fixed REPORT shape. Use when you want to "work through beads inline", "pick up a specific stage bead", or run one stage "without the full ralph orchestrator".
 ---
 
 # Run Pipeline Stage
 
-Stage beads (`stage:code`, `stage:verify`, `stage:review`, `stage:document`, `stage:fix`) come from the pipeline definition in `skills/planning/create-task/pipeline.json`. This skill executes one stage and owns that bead's lifecycle: the runner that does the work appends its own notes, closes its own leaf execution bead on **both** outcomes, and builds its own remediation children when the stage fails. The orchestrator dispatches and routes — it never edits or closes a leaf bead.
+Stage beads (`stage:code`, `stage:verify`, `stage:review`, `stage:document`, `stage:housekeeping`, `stage:fix`) come from the pipeline definition in `skills/planning/create-task/pipeline.json`. This skill executes one stage and owns that bead's lifecycle: the runner that does the work appends its own notes, closes its own leaf execution bead on **both** outcomes, and builds its own remediation children when the stage fails. `housekeeping` is the single exception: it never closes its bead over a worktree the pruner did not remove, and it builds no remediation children. The orchestrator dispatches and routes — it never edits or closes a leaf bead.
 
 ## When to use
 
@@ -24,7 +24,7 @@ Stage beads (`stage:code`, `stage:verify`, `stage:review`, `stage:document`, `st
 
 | Actor | Owns |
 |---|---|
-| Stage runner (worker) | Milestone notes, progress-log lines, closing its leaf bead on both outcomes, remediation children, the REPORT |
+| Stage runner (worker) | Milestone notes, progress-log lines, closing its leaf bead on both outcomes (`housekeeping` excepted: it leaves its bead open), remediation children, the REPORT |
 | Orchestrator (ralph or you) | Claim, dispatch, forward routing, the read-only cap backstop, the PR gate |
 
 A leaf bead is the worker's record of what happened. The orchestrator reads it; it does not write it.
@@ -58,7 +58,9 @@ The worker built anything this stage needed; routing picks up whatever `bd ready
 | `review` | `OUTCOME: SUCCESS` | Dispatch the ready `stage:document` chore |
 | `fix` | `OUTCOME: SUCCESS` | Dispatch the ready re-run chore that was blocked on the fix |
 | `document` | `OUTCOME: SUCCESS` | Open/update the feature PR and the HITL gate bead |
+| `housekeeping` | `OUTCOME: SUCCESS` | Create nothing — this is the last stage; its closed chore ends the pipeline |
 | `code` / `verify` / `review` / `fix` / `document` | `OUTCOME: BLOCKED` | Create nothing — the worker built `stage:fix` + a fresh instance of its own stage; dispatch the ready fix chore |
+| `housekeeping` | `OUTCOME: BLOCKED` | Create nothing — the worker left its chore **open**; hand the surviving worktrees to a human. Do not re-dispatch it automatically |
 | any | parent status `blocked` | Nothing — the worker or the cap backstop blocked it; record it for shutdown |
 
 Cap backstop (read-only): before dispatching a `stage:*` chore, count the parent's fix rounds and, if already at `maxFixRounds` (`skills/planning/create-task/pipeline.json`, currently `4`), block the parent and create nothing:
@@ -69,7 +71,7 @@ fix_rounds=$(bd children <parent-id> --json | grep -c '"stage:fix"')
 
 ## Remediation Children (worker-built)
 
-On `OUTCOME: BLOCKED` the worker creates its own chain — a `stage:fix` chore carrying the feedback, plus a **fresh instance of the stage that failed**, blocked on the fix. A fresh instance is not optional: the failed chore is already closed, so the pre-created chain cannot re-verify a fix.
+On `OUTCOME: BLOCKED` the worker creates its own chain — a `stage:fix` chore carrying the feedback, plus a **fresh instance of the stage that failed**, blocked on the fix. A fresh instance is not optional: the failed chore is already closed, so the pre-created chain cannot re-verify a fix. `housekeeping` is the exception — it changes no files, its bead stays open, and nothing downstream waits on it, so it builds no chain.
 
 | Failed stage | Chain |
 |---|---|
@@ -78,6 +80,7 @@ On `OUTCOME: BLOCKED` the worker creates its own chain — a `stage:fix` chore c
 | `review` | `stage:fix` → fresh `stage:review` |
 | `document` | `stage:fix` → fresh `stage:document` |
 | `fix` | `stage:fix` → fresh `stage:fix` |
+| `housekeeping` | none — the worker leaves its chore open, reports `BLOCKED`, and hands the surviving worktrees to a human. No `stage:fix` and no fresh `stage:housekeeping`, because the stage repairs no files and sits last in the chain |
 
 Webbing, at cap, and the exact commands live in `prompts/stage-runner.md` and each playbook's _Remediation and close_ section. In short: both beads are children of the parent task (`--parent <parent-id>`), the fresh stage is `bd dep add <fresh> <fix> --type blocks`, and any not-yet-run later stage is re-blocked behind the fresh bead. Chores carry no required sections, so the feedback description points at the parent/requirements bead (`<parent-id>`) rather than restating its acceptance criteria.
 
@@ -112,7 +115,7 @@ Every stage-runner prompt ends with the literal REPORT instruction (see `prompts
 ```
 ---REPORT---
 BEAD_ID: <id>
-STAGE_COMPLETED: <code|verify|review|document|fix>
+STAGE_COMPLETED: <code|verify|review|document|housekeeping|fix>
 SUMMARY: <2-3 sentence summary of what was done>
 FILES_CHANGED: <comma-separated list, or "none">
 COMMIT: <sha of the stage commit, or "none">

package/skills/workflow/run-pipeline-stage/playbooks/housekeeping.md

@@ -0,0 +1,58 @@
+# Stage Playbook: housekeeping
+
+This stage runs after the human merge gate and is last in the chain. It removes the worktrees of
+closed beads and changes no files.
+
+## Stage Instructions
+
+1. **Work from the main checkout.** Run every command from the repository's main checkout — the
+   directory that holds `.agent-cortex/worktrees/` — never from a bead worktree. The worktree this
+   run removes can be the one you are standing in.
+
+2. **Run the pruner once:**
+   ```bash
+   node <ralph-scripts>/prune-worktrees.mjs
+   ```
+   `<ralph-scripts>` is the absolute path to `skills/workflow/ralph/scripts/`, resolved from wherever
+   that skill was loaded. Read the per-worktree report it prints: every scanned worktree, its
+   classification (`closed-bead`, `open-bead`, `orphan`, `unclassified`) and its outcome (`removed`,
+   `kept`, `refused`).
+
+3. **Retry once on a non-zero exit.** Exit status `1` means at least one scanned worktree survived,
+   and an open bead counts as survival, so a normal run against a live backlog exits `1`. Run the
+   same command a second time when the first run exits non-zero. One retry, never more.
+
+4. **Decide from the per-worktree report, not from the exit status.** After the retry:
+   - **SUCCESS** — no `closed-bead` worktree is left in `refused` state. Report every worktree the
+     run removed and every one it kept, with the printed reason.
+   - **BLOCKED** — a `closed-bead` worktree is still `refused` after the retry, or the pruner could
+     not run at all (missing node, unreadable directory). A refused `closed-bead` worktree is a
+     worktree this run did not remove, whatever reason it printed.
+
+5. **Never close over a worktree the script did not remove.** Do not delete a worktree by hand, do
+   not pass `--remove-orphans`, and do not edit the pruner. This stage reports what the script did.
+
+## Stage Outcome
+
+- **No commit and no push.** This stage changes no files, so report `COMMIT: none` and
+  `PUSHED: no` on both outcomes. Do not create an empty commit.
+- Set `OUTCOME: SUCCESS` when every `closed-bead` worktree is gone after the retry. `FILES_CHANGED`
+  is `none`.
+- Set `OUTCOME: BLOCKED` when a `closed-bead` worktree survived the retry, or the pruner could not
+  run. List each surviving worktree with the printed reason under `BLOCKING_ISSUES`.
+- A `kept` or `refused` entry for an open bead is a normal report, not a failure.
+
+## Remediation and close
+
+- **This stage is the exception to close-on-both-outcomes.** Nothing downstream waits on its close,
+  so the bead's own state is the report.
+- `OUTCOME: SUCCESS` — append the notes and the progress log, then
+  `bd close <id> --reason="SUCCESS: <removed/kept summary>"`. Create nothing: this is the last stage
+  and its closed chore ends the pipeline.
+- `OUTCOME: BLOCKED` — **do not close the bead.** Leave it open: return it to `open` status
+  (`bd update <id> --status open`) if your claim moved it to `in_progress`. Report the surviving
+  worktrees and hand the chore back to a human. Create no `stage:fix` chore and no fresh
+  `stage:housekeeping` chore — a fix round repairs files, and this stage repairs none.
+- **No downstream re-block.** This stage sits behind the PR gate rather than behind another stage, so
+  no later stage needs wiring behind a fresh instance.
+- Report `COMMIT: none`, `PUSHED: no`, and `PR: none`.

package/skills/workflow/run-pipeline-stage/prompts/stage-runner.md

@@ -38,10 +38,19 @@ not a transcript.
    ```
    The outcome lives in the close reason, the milestone notes, and the REPORT. A closed bead
    with a `BLOCKED` reason is a completed stage, not abandoned work.
+
+   **Exception — `housekeeping`.** It closes its bead only when the pruner removed every
+   `closed-bead` worktree. On `BLOCKED` it leaves the bead **open** and builds nothing (see
+   _Remediation_ below).
 3. **Do not create the next stage on success.** Routing forward is the orchestrator's job.
 
 ## Remediation (only when your outcome is BLOCKED)
 
+**Exception — `housekeeping` builds nothing.** It changes no files and sits last in the chain, so a
+`stage:fix` chore and a fresh instance have nothing to repair and nothing to re-block. It leaves its
+bead open, reports `OUTCOME: BLOCKED` with the surviving worktrees, and hands the chore to a human.
+Every step below applies to every other stage.
+
 A fresh instance of this stage is required: the bead you are closing cannot re-run itself.
 
 1. **Cap check.** Read `maxFixRounds` from `skills/planning/create-task/pipeline.json` and count
@@ -89,6 +98,9 @@ dirty worktree counts as a failed stage whatever the outcome line claims.
 3. Report `COMMIT`, `PUSHED`, and `PR`. The `document` stage also opens or updates the feature PR
    and reports its URL; every earlier stage reports `PR: none`.
 
+**Exception — `housekeeping`.** It changes no files, so it commits and pushes nothing. Report
+`COMMIT: none` and `PUSHED: no` with `OUTCOME: SUCCESS`; never create an empty commit.
+
 ## Instructions
 1. Read and follow the playbook file listed above.
 2. Treat the bead as the source-of-truth specification (not a prompt script).
@@ -101,7 +113,7 @@ End your response with a `---REPORT---` block in exactly this format:
 ```
 ---REPORT---
 BEAD_ID: <id>
-STAGE_COMPLETED: <code|verify|review|document|fix>
+STAGE_COMPLETED: <code|verify|review|document|housekeeping|fix>
 SUMMARY: <2-3 sentence summary of what was done>
 FILES_CHANGED: <comma-separated list, or "none">
 COMMIT: <sha of the stage commit, or "none">

package/token-map.README.md

@@ -51,10 +51,20 @@ rather than inventing a dotted form:
   `ask_user`) — and `task` / `read_agent` / `wait_for_agents` subagent tools, the last three
   supplied by this repo's own `extensions/subagent` rather than by pi; `skill` maps
   to `read` (skills load by reading the listed SKILL.md path).
-- **`paths`** — `plugin_root`, `agents_dir`, and `skills_dir`. These are the install-time
-  variables that differ per harness. `plugin_root` is the anchor; the other two resolve
-  relative to it (`{base, relative}` specs) so a harness only overrides the single root it
-  actually installs into.
+- **`paths`** — `plugin_root`, `agents_dir`, `skills_dir`, and `skill_anatomy`. These are the
+  install-time variables that differ per harness. `plugin_root` is the anchor; the others
+  resolve relative to it (`{base, relative}` specs) so a harness only overrides the single
+  root it actually installs into.
+  A path entry whose relative path sits under `docs/` names a document the install ships:
+  both installers copy it from the package root into the staged tree at that relative path
+  (`scripts/lib/docs.mjs`), so a skill can read it on a machine with no checkout. One copy
+  per install serves every skill that references it, and the token map decides both the
+  location and the shipment — `skill_anatomy` is read by both `write-a-skill` and
+  `refactor-skill`. The repo's `docs/` stays the single source of truth; the staged file is
+  a verbatim copy, never a second authored version.
+  A second shipped doc is declared twice: the `paths` entry sets its install location, and
+  `package.json` `files` must list the same path. The test stages from the checkout, so only
+  the `files` whitelist catches a doc that the published package omits.
   Claude's `plugin_root` stays the `${CLAUDE_PLUGIN_ROOT}` env-var token, never a literal
   `~/.agent-cortex/claude`: Claude Code **copies** marketplace-installed plugins — including
   local directory sources like `~/.agent-cortex/claude` — into its own cache, so only the

package/token-map.json

@@ -39,6 +39,10 @@
     "skills_dir": {
       "claude": { "base": "plugin_root", "relative": "skills" },
       "pi": { "base": "plugin_root", "relative": "skills" }
+    },
+    "skill_anatomy": {
+      "claude": { "base": "plugin_root", "relative": "docs/skills/skill-anatomy.md" },
+      "pi": { "base": "plugin_root", "relative": "docs/skills/skill-anatomy.md" }
     }
   },
   "agents": {
@@ -75,7 +79,8 @@
     },
     "paths": {
       "pi": "plugin_root is the staged package `agent-cortex install pi` materialises at ~/.agent-cortex/pi; pi loads that directory by path and the shipped extensions resolve their own resources relative to it (agent-modes computes plugin_root from its actual install location). A checkout or symlinked install differs — installers compute plugin_root from the actual resolution and can override it (--plugin-root).",
-      "claude": "plugin_root stays ${CLAUDE_PLUGIN_ROOT} (env var) for the materialised plugin — never a literal ~/.agent-cortex/claude. Claude Code copies marketplace-installed plugins (including local directory sources like ~/.agent-cortex/claude) into its own cache and expands the env var per context, so a literal home path in substituted files would break under cache-copy; the installer passes the env form through verbatim."
+      "claude": "plugin_root stays ${CLAUDE_PLUGIN_ROOT} (env var) for the materialised plugin — never a literal ~/.agent-cortex/claude. Claude Code copies marketplace-installed plugins (including local directory sources like ~/.agent-cortex/claude) into its own cache and expands the env var per context, so a literal home path in substituted files would break under cache-copy; the installer passes the env form through verbatim.",
+      "skill_anatomy": "A path entry whose relative path sits under docs/ names a document the install ships: both installers copy it from the package root into the staged tree at that relative path (scripts/lib/docs.mjs), so a skill can read it on a machine with no checkout. One copy per install serves every skill that references it — write-a-skill and refactor-skill both do. The repo's docs/ stays the single source of truth; the staged copy is a verbatim copy, never a second authored version."
     },
     "agents": {
       "prefix": "Claude strips the agent-cortex: name prefix during conversion (NAME_PREFIX in bin/installers/claude.mjs): pi agents are agent-cortex:<slug>, claude agents are <slug>."