@jaybeeuu/agent-cortex 2.5.1 → 2.7.0

package/lib/harness-versions.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaybeeuu/agent-cortex",
-  "version": "2.5.1",
+  "version": "2.7.0",
   "description": "Personal PI package with custom agents, skills, and extensions",
   "keywords": [
     "pi-package"
@@ -21,6 +21,7 @@
     "scripts/",
     "skills/",
     "agents/",
+    "docs/skills/skill-anatomy.md",
     "extensions/*.ts",
     "extensions/lib/",
     "extensions/*/*.ts",

package/scripts/lib/docs.mjs

@@ -0,0 +1,67 @@
+// Documentation a staged install ships.
+//
+// Skills are installed onto machines that have no copy of this checkout, so a
+// skill that reads a repository document — write-a-skill and refactor-skill both
+// read docs/skills/skill-anatomy.md — needs that document inside the install.
+// The list is derived from token-map.json rather than declared again here: a
+// `paths` entry whose relative path sits under `docs/` is a document skills
+// reference by install-relative path, so the token map stays the single source
+// of where the install puts it.
+//
+// The copies are verbatim, and no token substitution runs over them. A shipped doc
+// therefore must not print a substitution token: one that needs to teach the
+// syntax describes the wrapper in words (see the tool-reference section of the
+// anatomy guide). test/installed-docs.test.mjs fails when a shipped doc carries
+// one, because the materialised plugin must contain no literal token.
+//
+// Zero dependencies so it runs on the CI Node (20) and local Node alike.
+
+import { copyFile, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { isFile } from "./fs.mjs";
+
+/**
+ * Package-relative paths of the docs an install ships, sorted.
+ * @param {import("./compose-agent.mjs").TokenMap} tokenMap
+ * @returns {string[]}
+ */
+export function shippedDocs(tokenMap) {
+  const docs = new Set();
+  for (const entry of Object.values(tokenMap.paths ?? {})) {
+    if (entry === null || typeof entry !== "object") continue;
+    for (const spec of Object.values(entry)) {
+      if (spec === null || typeof spec !== "object") continue;
+      const { relative } = /** @type {{ relative?: unknown }} */ (spec);
+      if (typeof relative === "string" && relative.startsWith("docs/")) docs.add(relative);
+    }
+  }
+  return [...docs].sort();
+}
+
+/**
+ * Copy every shipped doc from the package root into the staged tree, at the same
+ * relative path. A missing source is a hard error: the token map points a skill
+ * at a document the install would otherwise not contain.
+ * @param {{ root: string, output: string, dryRun?: boolean,
+ *           tokenMap: import("./compose-agent.mjs").TokenMap }} options
+ * @returns {Promise<{ files: string[], dir: string }>}
+ */
+export async function installDocs({ root, output, dryRun = false, tokenMap }) {
+  /** @type {string[]} */
+  const files = [];
+  for (const relative of shippedDocs(tokenMap)) {
+    const from = join(root, relative);
+    if (!(await isFile(from))) {
+      throw new Error(
+        `token-map.json points a skill at ${relative}, but ${from} does not exist — ship the document or drop the path entry`,
+      );
+    }
+    if (!dryRun) {
+      const to = join(output, relative);
+      await mkdir(dirname(to), { recursive: true });
+      await copyFile(from, to);
+    }
+    files.push(relative);
+  }
+  return { files, dir: join(output, "docs") };
+}

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

@@ -16,12 +16,19 @@ node <skill-scripts>/create-chores.mjs --parent <bead-id> [--priority <0-4>]
 
 ## Stage chore beads
 
-One per stage in `pipeline.json` (currently `code`, `verify`, `review`, `document`):
+One per stage in `pipeline.json` (currently `code`, `verify`, `review`, `document`, `housekeeping`):
 
 - **Type**: `chore`
 - **Title**: `[<parent-id>] <stage title>` (e.g. `[abc-123] Code`)
-- **Labels**: `stage:<id>` (e.g. `stage:code`, `stage:verify`)
-- **Dependencies**: `parent-child` to the parent bead; `blocks` between stages per each stage's `dependsOn` (the script requires `dependsOn` targets to appear earlier in `pipeline.json`).
+- **Labels**: `stage:<id>` (e.g. `stage:code`, `stage:verify`), plus any `labels` the stage declares — `housekeeping` adds `lifecycle:housekeeping`
+- **Dependencies**: `parent-child` to the parent bead; `blocks` between stages per each stage's `dependsOn` (the script requires `dependsOn` targets to appear earlier in `pipeline.json`)
+
+**A stage may wait on the gate instead of a stage.** The reserved `dependsOn` target
+`featurePrReview` means "blocked behind the PR gate bead". The gate is not a stage — it is created
+after them — so the script wires those stages to it in a second pass, once the gate exists. The
+`housekeeping` stage uses it: its chore must not become ready until a human has merged the PR and
+closed the gate, and the `blocks` edge keeps it out of `bd ready` while the feature is in flight.
+The gate itself still waits on the last stage that does not wait on the gate (`document`).
 
 ## PR gate bead (`featurePrReview`)
 
@@ -87,6 +94,7 @@ The deliverable this feature produces and the problem it solves.
 | verify | Verify | code |
 | review | Review | verify |
 | document | Document | review |
+| housekeeping | Housekeeping | `featurePrReview` — the PR gate bead, not a stage |
 
 `maxFixRounds: 4` — the maximum fix-retry rounds allowed for a stage's verify loop before the PR gate. Adjust stages only in `pipeline.json`; the script and templates follow it.
 

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

@@ -141,7 +141,7 @@ Steps 2–6 create beads; step 7 expands one. A bead that already exists but has
 Input: title `Add export API to invoices`, description `…`, priority `2`, parent `feature-456`. Output: the bead ID plus the script's JSON mapping stage IDs → chore bead IDs, with `featurePrReview` as the HITL PR gate:
 
 ```json
-{"code": "abc123", "verify": "def456", "review": "ghi789", "document": "jkl012", "featurePrReview": "bd-mno345"}
+{"code": "abc123", "verify": "def456", "review": "ghi789", "document": "jkl012", "housekeeping": "mno345", "featurePrReview": "bd-pqr678"}
 ```
 
 Feature path input: "several endpoints, a UI, and a migration". Output: `feature-456` (`execution:hitl`), `plan-457` ("Plan: …", `execution:hitl`, owned by the feature, blocking every child), and one `execution:afk` impl child per deliverable, each expanded into its own stage chores plus PR gate.

package/skills/planning/create-task/pipeline.json

@@ -28,6 +28,14 @@
       "description": "Review changes and update documentation if key decisions, behaviour changes, or constraints were introduced.",
       "template": "templates/document.md",
       "dependsOn": ["review"]
+    },
+    {
+      "id": "housekeeping",
+      "title": "Housekeeping",
+      "description": "Remove the worktrees of closed beads. Run `node <ralph-scripts>/prune-worktrees.mjs` from the main checkout and retry once if it exits non-zero. The exit status is 1 whenever any worktree survives — an open bead counts as survival — so fail this chore only when a closed-bead worktree is still refused after the retry, and leave it open. Never close it over a worktree the script did not remove.",
+      "template": "templates/housekeeping.md",
+      "labels": ["lifecycle:housekeeping"],
+      "dependsOn": ["featurePrReview"]
     }
   ]
 }

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

@@ -27,6 +27,7 @@ import { fileURLToPath } from 'node:url';
  * @property {string} description
  * @property {string} template
  * @property {string[]} dependsOn
+ * @property {string[]} [labels]  Labels beside `stage:<id>`; e.g. `lifecycle:housekeeping`
  */
 
 /**
@@ -136,6 +137,10 @@ function wireBlocks(beadId, dependsOnId, blocks) {
 
 // ─── Main ─────────────────────────────────────────────────────────────────────
 
+// Reserved `dependsOn` target: the PR gate bead. The gate is not a stage — it is
+// created after them — so a stage that waits on it is wired in a second pass.
+const GATE_ROLE = 'featurePrReview';
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
@@ -150,6 +155,10 @@ const adoptable = readAdoptable(parentId);
 /** @type {Map<string, string>} */
 const stageToBeadId = new Map();
 
+/** Stages that wait on the gate rather than on another stage, held until it exists.
+ * @type {Array<{ beadId: string, blocks: Set<string> }>} */
+const gateDependents = [];
+
 for (const stage of pipeline.stages) {
   const adopted = adoptable.get(`stage:${stage.id}`);
 
@@ -160,7 +169,7 @@ for (const stage of pipeline.stages) {
         '--type', 'chore',
         '--description', JSON.stringify(stage.description),
         '--priority', priority,
-        '--labels', `stage:${stage.id}`,
+        '--labels', [`stage:${stage.id}`, ...(stage.labels ?? [])].join(','),
         '--parent', parentId,
         '--silent',
       ]);
@@ -171,6 +180,7 @@ for (const stage of pipeline.stages) {
   const blocks = adopted ? adopted.blocks : new Set();
 
   for (const depStageId of stage.dependsOn) {
+    if (depStageId === GATE_ROLE) { continue; }
     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.`);
@@ -178,15 +188,17 @@ for (const stage of pipeline.stages) {
     }
     wireBlocks(beadId, depBeadId, blocks);
   }
-}
 
-const finalStageId = pipeline.stages.at(-1)?.id;
-if (!finalStageId) {
-  console.error('No pipeline stages found in pipeline.json.');
-  process.exit(1);
+  if (stage.dependsOn.includes(GATE_ROLE)) { gateDependents.push({ beadId, blocks }); }
 }
 
-const documentStageBeadId = stageToBeadId.get('document') ?? stageToBeadId.get(finalStageId);
+// The gate waits on the last stage that does not itself wait on the gate, so the
+// chain stays acyclic once a stage can follow the gate.
+const chainStageIds = pipeline.stages
+  .filter((stage) => !stage.dependsOn.includes(GATE_ROLE))
+  .map((stage) => stage.id);
+
+const documentStageBeadId = stageToBeadId.get('document') ?? stageToBeadId.get(chainStageIds.at(-1) ?? '');
 if (!documentStageBeadId) {
   console.error('Could not resolve the final stage bead needed for PR gate dependency.');
   process.exit(1);
@@ -220,6 +232,12 @@ const prGateBeadId = adoptedGate
 const gateBlocks = adoptedGate ? adoptedGate.blocks : new Set();
 wireBlocks(prGateBeadId, documentStageBeadId, gateBlocks);
 
+// Second pass: the stages that wait on the gate finally get their dep, now that the
+// gate bead exists.
+for (const { beadId, blocks } of gateDependents) {
+  wireBlocks(beadId, prGateBeadId, blocks);
+}
+
 /** @type {Record<string, string>} */
 const result = {
   ...Object.fromEntries(stageToBeadId),

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

@@ -0,0 +1,65 @@
+## Project context
+<bd prime output — verbatim>
+
+## Task
+<bd show <id> output — verbatim>
+
+## Progress log
+Write progress to: `.agent-cortex/ralph/ralph-<bead-id>.log`
+Log stage start, each pruner run with its exit status, and stage complete (see Progress Logging in
+run-pipeline-stage skill).
+
+## Instructions
+This stage removes worktrees, so **do not work in the bead worktree**. Run every command from the
+repository's main checkout — the directory that holds `.agent-cortex/worktrees/` — because the
+worktree this run may remove can be your own.
+
+1. **Run the pruner once** from the main checkout:
+   ```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 — it lists every scanned worktree,
+   its classification (`closed-bead`, `open-bead`, `orphan`, `unclassified`) and its outcome
+   (`removed`, `kept`, `refused`).
+
+2. **Retry once on a non-zero exit.** Exit status `1` means at least one scanned worktree survived
+   the run, and an open bead counts as survival — a normal run against a live backlog exits `1`. So
+   run the same command a second time when the first run exits non-zero. One retry, never more.
+
+3. **Decide the outcome from the report, not the exit status.** After the retry:
+   - **SUCCESS** — no worktree classified `closed-bead` 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`, 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 the reason printed.
+
+4. **Never close this chore over a worktree the script did not remove.** This stage is the one
+   exception to the close-on-both-outcomes rule, because this stage is last in the chain and nothing
+   waits on its close. Close it only when every `closed-bead` worktree is gone; the worktree removal
+   is the only thing this stage completes.
+
+   On BLOCKED, **do not close the chore**. Leave it open — return it to `open` status if your claim
+   moved it to `in_progress` — report the surviving worktrees with the reasons the pruner printed,
+   and hand the chore back to a human. Create no `stage:fix` chore and no fresh `stage:housekeeping`
+   chore: there is nothing for a fix round to repair, and no later stage to re-block. A `kept` or
+   `refused` entry for an open bead is a normal report, not a failure.
+
+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.
+
+End your response with a ---REPORT--- block. The `run-pipeline-stage` skill's
+`prompts/stage-runner.md` holds the authoritative REPORT contract — if this block and that prompt
+differ, follow the prompt and correct this template.
+---REPORT---
+BEAD_ID: <id>
+STAGE_COMPLETED: housekeeping
+SUMMARY: <2–3 sentences: worktrees removed, worktrees kept and why>
+FILES_CHANGED: none
+COMMIT: none
+PUSHED: no
+PR: none
+OUTCOME: <SUCCESS|BLOCKED>
+BLOCKING_ISSUES:         ← include only if OUTCOME is BLOCKED; one line per issue
+- <worktree path and the reason the pruner printed>
+---

package/skills/productivity/write-a-skill/SKILL.md

@@ -25,7 +25,7 @@ Clarify the skill goal with the user. Ask what triggers users would actually say
 
 ### 2. Draft from the anatomy template
 
-Read `docs/skills/skill-anatomy.md` as the source of truth. Follow the annotated template for section ordering and front-matter fields. Target ~150 lines for `SKILL.md` but stay under the 150-line hard cap. When the workflow branches or has decision points, include one inline ASCII workflow diagram per the anatomy doc's diagram style guide — ASCII only, never Mermaid.
+Read `{{PATH:skill_anatomy}}` as the source of truth. Follow the annotated template for section ordering and front-matter fields. Target ~150 lines for `SKILL.md` but stay under the 150-line hard cap. When the workflow branches or has decision points, include one inline ASCII workflow diagram per the anatomy doc's diagram style guide — ASCII only, never Mermaid.
 
 ### 3. Apply voice and tone rules
 
@@ -62,7 +62,7 @@ Output: A new `skills/review-security/SKILL.md` with front matter, When to use,
 
 ## Verification checklist
 
-- [ ] `docs/skills/skill-anatomy.md` was read before drafting
+- [ ] `{{PATH:skill_anatomy}}` was read before drafting
 - [ ] Required sections present: `## When to use`, `## Workflow`, `## Verification checklist`
 - [ ] Section order follows the anatomy template
 - [ ] Workflow diagram (if present) is ASCII-only and follows the anatomy diagram style guide

package/skills/review/refactor-skill/SKILL.md

@@ -8,7 +8,7 @@ description: Refactor an existing SKILL.md to the canonical anatomy template thr
 ## When to use
 
 - A skill's SKILL.md predates the anatomy template and needs upgrading.
-- You want to align a skill with `docs/skills/skill-anatomy.md` before the refactor wave touches it.
+- You want to align a skill with `{{PATH:skill_anatomy}}` before the refactor wave touches it.
 - You want to compare a skill's structure to the current template standard.
 - Trigger phrases: "refactor this skill", "restructure this skill", "review this skill", "upgrade X to the template", "align with anatomy".
 
@@ -27,7 +27,7 @@ Read the target skill's `skills/<name>/SKILL.md` and the canonical anatomy refer
 
 ```bash
 cat skills/<name>/SKILL.md
-cat docs/skills/skill-anatomy.md
+cat {{PATH:skill_anatomy}}
 ```
 
 If the target has no `SKILL.md` yet, abort — this skill upgrades existing files; use `write-a-skill` for new creation.

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. 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".
+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, plus the `housekeeping` chore blocked behind that 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,7 @@ 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. A bead with a full chain — one `stage:*` chore per stage in `pipeline.json` (four for the
+   status. A bead with a full chain — one `stage:*` chore per stage in `pipeline.json` (five 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
@@ -72,7 +72,7 @@ A ready `execution:afk` task bead with **no** `stage:*` chore children has nothi
    ```json
    { "kind": "expand", "choreId": null, "parentId": "<parent-id>", "title": "<parent title>", "agentId": "<agent-id>", "logLine": 1 }
    ```
-4. **Report the mapping** the worker returns — `code`, `verify`, `review`, `document`, `featurePrReview` — and close nothing. The worker owns no bead on this run; the expansion is bookkeeping, not a stage.
+4. **Report the mapping** the worker returns — `code`, `verify`, `review`, `document`, `housekeeping`, `featurePrReview` — and close nothing. The worker owns no bead on this run; the expansion is bookkeeping, not a stage.
 5. **Dispatch normally.** The next `bd ready -l execution:afk` pass picks up the `stage:code` chore, and the pre-created chain carries the rest.
 6. **Handle the completion as an expansion completion**, not a stage completion — see below.
 
@@ -97,7 +97,7 @@ On completion, remove the entry from `inflight` and confirm the chore tree exist
 bd children <parent-id> --json | grep -c '"stage:'
 ```
 
-Expect one match per `stage:*` label in the chain — four for the shipped `pipeline.json`; the
+Expect one match per `stage:*` label in the chain — five 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
@@ -204,6 +204,37 @@ For each parent task bead (`<parent-id>`):
 
 ---
 
+## Pruning Worktrees
+
+A worktree outlives its bead: ralph leaves the directory behind when a feature closes, and a crashed run leaves one with no bead at all. `skills/workflow/ralph/scripts/prune-worktrees.mjs` converges `.agent-cortex/worktrees/*` with bead state.
+
+```bash
+node skills/workflow/ralph/scripts/prune-worktrees.mjs                  # remove closed-bead worktrees, report the rest
+node skills/workflow/ralph/scripts/prune-worktrees.mjs --remove-orphans # also remove open-bead and missing-bead worktrees
+```
+
+**Candidacy comes from bead state, never from git ancestry.** The repo squash-merges, so every landed branch still reports as unmerged. A directory named after a bead that `bd show` reports `closed` is the only proof that admits removal; an open bead, a missing bead, or a bead `bd` could not answer for is kept unless `--remove-orphans` asks otherwise. A bead `bd` could not read is never removed, whatever the flags say.
+
+**A candidate that fails a guard is refused, and the reason is printed.** The guards are: dirty working tree, `locked` worktree, detached HEAD, directory not registered with git, branch with no upstream, and branch with unpushed commits.
+
+**Removal is three commands.** `git worktree remove <path>`, then `git branch -D <branch>`, then `git push origin --delete <branch>`. The remote branch name is the worktree's own checked-out branch, so ralph's `feature/<parent-id>` deletes `origin/feature/<parent-id>`. A remote ref that git already reports as gone is not a failure.
+
+**Exit status is 1 whenever any scanned worktree survived the run.** An open bead counts as survival, so a normal run against a live backlog exits 1. Read the per-worktree report; do not treat the status as a verdict on the worktree you asked about.
+
+**An unregistered stale directory is refused forever.** Earlier git runs may have dropped its registration, so every scan reports it and never removes it. Clean it up by hand: `git worktree prune`, then `rm -rf <path>`.
+
+### Housekeeping chore
+
+Pruning is a pipeline stage, not a habit: `create-chores.mjs` pre-creates a `stage:housekeeping` chore for every expanded task, carrying `lifecycle:housekeeping` and blocked behind that task's `lifecycle:feature-pr` gate. It stays out of `bd ready` until a human closes the gate, so it never competes with pipeline work.
+
+- **Executor.** A dispatched worker — the `stage:housekeeping` chore in `bd ready -l execution:afk` — runs `prune-worktrees.mjs` from the **main checkout**, never from the feature worktree: the worktree it removes can be the parent's own. Ralph dispatches it with the main checkout as cwd for that reason.
+- **Retry once.** Exit status `1` means some scanned worktree survived, and an open bead counts as survival, so a live backlog always exits non-zero. The worker therefore retries the run once. The retry is the whole allowance — never a third run.
+- **Never close over a worktree the script did not remove.** The outcome comes from the per-worktree report, not the exit status: the chore succeeds when no `closed-bead` worktree is left `refused`. A closed-bead worktree still `refused` after the retry fails the chore, and the chore is left **open** with the printed reasons in its notes. A `kept` or `refused` entry for an open bead is a normal report, not a failure.
+
+Ralph creates nothing for this stage and closes nothing: the worker owns the chore, as it owns every leaf bead.
+
+---
+
 ## Feature PR Gate
 
 When the `document` chore for a parent task completes:
@@ -219,15 +250,15 @@ When the `document` chore for a parent task completes:
 4. Find the child HITL task bead for this parent with label `lifecycle:feature-pr` and `execution:hitl` (created by `create-task`).
 5. Update that HITL bead with the PR URL/status (comment or note) so the reviewer has the link.
 6. Do not schedule new parent features while this gate is **unblocked** — an unblocked gate is a feature genuinely awaiting a human merge (see _Gate predicate_ below).
-7. Once the PR is merged, a human closes the HITL PR gate bead, which unblocks the scheduling brake. After that, close the parent feature bead:
+7. Once the PR is merged, a human closes the HITL PR gate bead, which unblocks the scheduling brake **and** the pre-created `stage:housekeeping` chore. After that, close the parent feature bead:
    ```bash
    bd close <parent-id>
    ```
-   Only then continue with next parent features.
+   The housekeeping run that follows removes the parent's worktree, because its bead now reads `closed`. Only then continue with next parent features.
 
 ### Gate predicate — parked vs pending
 
-Ralph's only scheduling brake is a gate that is **unblocked**. `create-chores` pre-creates a `lifecycle:feature-pr` gate for *every* planned feature, blocked behind that feature's own `document` chore; such a gate is **parked** — the feature has not reached its PR stage — and must never stop dispatch. Only when the `document` chore closes does the gate unblock, and that is the state in which a human must merge.
+Ralph's only scheduling brake is a gate that is **unblocked**. `create-chores` pre-creates a `lifecycle:feature-pr` gate for *every* planned feature, blocked behind that feature's own `document` chore; such a gate is **parked** — the feature has not reached its PR stage — and must never stop dispatch. Only when the `document` chore closes does the gate unblock, and that is the state in which a human must merge. The feature's `stage:housekeeping` chore waits on the gate bead itself, so it becomes ready only after that human closes it.
 
 Resolve the question with one command instead of ad-hoc `bd` queries: