@jaybeeuu/agent-cortex 2.6.0 → 2.7.0

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
@@ -223,6 +223,16 @@ node skills/workflow/ralph/scripts/prune-worktrees.mjs --remove-orphans # also r
 
 **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
@@ -240,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:
 

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_). 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_).
+- 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/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>."