@jaybeeuu/agent-cortex 2.6.0 → 2.8.0

package/skills/engineering/implement-task/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: implement-task
+description: Owns the task itself — read the acceptance criteria, prove each one with evidence, stay in scope, and take only pragmatic boy-scout fixes. Use when implementing a tracked task, bead, or ticket that lists acceptance criteria, or when you must show each criterion is met before reporting done.
+---
+
+# Implement Task
+
+`tdd` owns the red-green loop and the `style-*` skills own the standards. This skill owns the task
+around them: what the criteria are, what you touch, and what you can prove when you finish.
+
+## When to use
+
+- Implementing a tracked task, bead, or ticket that carries acceptance criteria.
+- Picking up a pipeline stage chore that must report against a criteria list.
+- Asked to "implement this task", "work this bead", or "prove the criteria are met".
+
+## When NOT to use
+
+- The loop inside one criterion — use `tdd`, which this skill invokes per criterion.
+- Writing or reviewing a test itself — use `style-tests`.
+- Naming, module boundaries, or refactoring shape — use `style-code`.
+- Deciding what the work should be — use `plan` or `create-task` first.
+
+## Workflow
+
+1. **Read the criteria.** Extract the task's `## Acceptance Criteria` verbatim and complete. A task
+   with no criteria is not implementable: stop, and either ask for them or file the gap as a bead.
+2. **Build the table.** Write the criteria → evidence table before touching code (see
+   _Criteria to evidence_). A criterion you cannot name a check for is a blocker, not a guess.
+3. **Take one criterion at a time.** Drive it through `tdd`, with `style-tests` for the test and
+   `style-code` for the code. Fill its row when it lands, not at the end.
+4. **Hold the scope.** Change only what a criterion needs (see _Scope rule_). Record every
+   out-of-scope finding as a bead and change nothing for it.
+5. **Fix inside touched files only.** Apply the _Boy-scout rule_ to anything you notice outside the
+   criteria.
+6. **Finish.** Re-read the criteria, re-run every check the table names, apply the _Mutation check_
+   to each test that claims a behaviour, and report the filled table.
+
+## Criteria to evidence
+
+The table is the contract between the request and the diff. Write it first, fill it last.
+
+| # | Criterion (quoted from the task) | Check that proves it | Status |
+|---|---|---|---|
+| 1 | <criterion> | <command, test name, or commit> | todo / done / blocked |
+| 2 | <criterion> | <command, test name, or commit> | todo / done / blocked |
+
+- **A criterion with no check is a blocker, not a guess.** An unproven criterion is unfinished.
+  Name the criterion and the reason before writing code, rather than inventing a plausible proof
+  afterwards.
+- **Evidence is observable.** A test named for the behaviour, the command and its result, or a
+  commit for a documentation change. Never "verified manually" or "looks right".
+- **One row per criterion.** Fold a criterion you cannot separate from another into that row
+  instead of splitting it into vague halves.
+- **The filled table is the report.** Hand back one row per criterion with its evidence. A claim
+  with no check in its row does not ship.
+
+## Scope rule
+
+- **Change only what a criterion needs.** Each line in the diff answers a row in the table, or is
+  the smallest thing that lets a row pass.
+- **An out-of-scope finding becomes a bead, not an edit.** Name what you found, where it is, and
+  why the task does not own it. File it, then continue.
+- **A conflict is a stop, not a judgement call.** When a criterion needs a change that contradicts
+  another criterion or an existing rule, report both and stop. Do not pick one silently.
+- **No drive-by refactor.** Rename, restructure, or reformat nothing the task did not require,
+  however tempting the neighbouring code looks.
+
+## Boy-scout rule
+
+A boy-scout fix is allowed only inside a file the task already touches, and only when it serves the
+task:
+
+- **Serves the task** — it makes this criterion's own change correct or readable: a name the change
+  made wrong, a helper the criterion needs, a comment the change invalidated.
+- **Serves nobody** — it improves code the criterion never reaches: an unrelated dead branch, a
+  different module's naming, a missing test elsewhere. File it and leave it.
+- **Cost gate.** A fix must cost less to read in the diff than to follow in a bead. When in doubt,
+  file the bead.
+
+## Mutation check
+
+`style-tests` owns the mutation-check rule; this skill applies it at Finish:
+
+- Apply it to every test the task added or changed that claims a behaviour.
+- Record the outcome in the evidence row of the criterion that test proves — which behaviour you
+  removed, which test failed, and that the suite is green again after restore.
+- A claimed behaviour whose named test still passes under mutation leaves its criterion `blocked`,
+  whatever the suite says.
+
+## Red Flags
+
+- Red flag: writing code before the criteria → evidence table exists.
+- Red flag: a row whose evidence is a restated criterion instead of a check.
+- Red flag: a diff line that no row in the table needs.
+- Red flag: reporting `done` over a table with `todo` rows.
+- Red flag: a "quick tidy" in a file the task never opens.
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+|---|---|
+| "The criteria are obvious, the table is overhead" | The table is the only place the request and the diff meet. Without it, the checklist is memory and the report is opinion. |
+| "This nearby bug is a two-line fix" | Then it is a two-line bead. Fixing it here hides an unrequested change inside a requested one. |
+| "The test passes, so the criterion is proven" | A test that passes under mutation proves nothing. Run the mutation check or say the row is unproven. |
+| "I refactored a little, it is still the same change" | It is a second change wearing the first one's name. Split it. |
+
+## See Also
+
+- [tdd](../tdd/SKILL.md) — the red-green loop you run once per criterion.
+- [style-tests](../../style/style-tests/SKILL.md) — assertion strategy, plus the mutation-check rule this skill applies.
+- [style-code](../../style/style-code/SKILL.md) — the conventions the code under each criterion must meet.
+- [run-pipeline-stage](../../workflow/run-pipeline-stage/SKILL.md) — the stage runner whose `code` playbook invokes this skill first.
+
+## Verification checklist
+
+- [ ] Criteria → evidence table written before the first code change, one row per criterion
+- [ ] No criterion left without a named check; any such gap reported as a blocker instead of guessed
+- [ ] Each criterion taken through `tdd`; test and code conventions delegated to `style-tests` and `style-code`
+- [ ] Every diff line traces to a table row; out-of-scope findings filed as beads, not edited
+- [ ] Boy-scout fixes confined to files the task touches and to what the task needs
+- [ ] Every check in the table re-run at Finish, with its result recorded
+- [ ] Mutation check applied to each test claiming a behaviour, outcome recorded per row
+- [ ] Table reported in full, with evidence per row

package/skills/engineering/tdd/SKILL.md

@@ -13,6 +13,7 @@ description: Test-driven development with red-green-refactor loop. Use when buil
 
 ## When NOT to use
 
+- Owning the task itself — criteria, scope, and proof of each criterion — is [implement-task](../implement-task/SKILL.md); load it first and return here for the loop inside a criterion.
 - Prototyping, throwaway code, or exploratory spikes where speed of discovery matters more than correctness.
 - Changes so trivial that tests would duplicate type or lint coverage (rename, pure data shuffle).
 - When the test-to-implementation ratio would be absurdly high — a one-line change requiring extensive test setup.
@@ -93,6 +94,7 @@ After all tests pass, run `style-code` to guide the refactoring shape:
 
 ## See Also
 
+- [implement-task](../implement-task/SKILL.md) — it owns the acceptance criteria, the scope and boy-scout rules, and the per-criterion evidence table that this loop fills one row at a time.
 - [style-tests](../../style/style-tests/SKILL.md) — load before writing the first test; it owns assertion strategy, mock discipline, and test-data construction.
 - [style-code](../../style/style-code/SKILL.md) — load at the refactor step for naming and module boundaries.
 - [grill-with-docs](../grill-with-docs/SKILL.md) — load when domain vocabulary is unsettled, so test names and seams use the project's own language.

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

@@ -16,12 +16,20 @@ 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`, `post-merge`, `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`).
+- **Description**: the stage's `description` text, carried verbatim. Expansion stores it and does nothing else with it: it never substitutes the `<ralph-scripts>` placeholder and never runs the backticked `node …` command inside it. Treat a description as text for the stage worker to read, never as something expansion acts on.
+- **Labels**: `stage:<id>` (e.g. `stage:code`, `stage:verify`), plus any `labels` the stage declares — `post-merge` adds `lifecycle:post-merge`, `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. Both
+`post-merge` and `housekeeping` use it: each 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,9 +95,18 @@ The deliverable this feature produces and the problem it solves.
 | verify | Verify | code |
 | review | Review | verify |
 | document | Document | review |
+| post-merge | Post-merge check | `featurePrReview` — the PR gate bead, not a stage |
+| 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.
 
+`post-merge` and `housekeeping` both wait on the gate and on nothing else: they become ready
+together when a human closes it. Neither waits on the other. Chaining housekeeping behind
+`post-merge` was rejected because a post-merge check that stays open — an inconclusive run nobody
+resolves — would then strand the worktree reclamation housekeeping exists to do. Putting
+`post-merge` after `housekeeping` was rejected too: it would make the pruner a dependency of a
+check that reads GitHub state, which no worktree removal can affect.
+
 ## Stage templates
 
 `templates/` holds one prompt skeleton per stage; a dispatcher fills one to compose that stage's

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", "post-merge": "mno345", "housekeeping": "pqr678", "featurePrReview": "bd-stu901"}
 ```
 
 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,22 @@
       "description": "Review changes and update documentation if key decisions, behaviour changes, or constraints were introduced.",
       "template": "templates/document.md",
       "dependsOn": ["review"]
+    },
+    {
+      "id": "post-merge",
+      "title": "Post-merge check",
+      "description": "Run `node <ralph-scripts>/post-merge-check.mjs` from the main checkout. It reads `gh run list` for the base branch's merge commit and exits 0 when every run passed, 1 when a run failed, and 2 when the result is inconclusive. Exit 0: report the run URLs and close. Exit 1: the script has already filed one P1 escalation bead carrying the run URL and the failing job — report its id, leave this chore open, and close nothing else. Exit 2: report the reason it printed and leave this chore open. Never retry, never re-run the workflow, never reopen the parent.",
+      "template": "templates/post-merge.md",
+      "labels": ["lifecycle:post-merge"],
+      "dependsOn": ["featurePrReview"]
+    },
+    {
+      "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

@@ -13,10 +13,11 @@
 //
 // Zero dependencies: run with `node create-chores.mjs --parent <bead-id>`.
 
-import { execSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -27,6 +28,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`
  */
 
 /**
@@ -65,13 +67,20 @@ function parseArgs(args) {
 // Defaults to `bd`, resolved via PATH.
 const BD_PATH = process.env.BD_PATH || 'bd';
 
+const execFileAsync = promisify(execFile);
+
 /**
+ * Run a command with its argv handed straight to the child process. The arguments are
+ * never joined into a command line for a shell: a stage description wraps a real command
+ * in backticks (`node <ralph-scripts>/post-merge-check.mjs`), and a shell would execute it
+ * and splice its output into the description instead of storing the text.
  * @param {string[]} args
- * @returns {string}
+ * @returns {Promise<string>}
  */
-function run(args) {
-  const cmd = args[0] === 'bd' ? [BD_PATH, ...args.slice(1)] : args;
-  return execSync(cmd.join(' '), { encoding: 'utf-8' }).trim();
+async function run(args) {
+  const [command, ...rest] = args[0] === 'bd' ? [BD_PATH, ...args.slice(1)] : args;
+  const { stdout } = await execFileAsync(command, rest, { encoding: 'utf-8' });
+  return stdout.trim();
 }
 
 // ─── Existing children ────────────────────────────────────────────────────────
@@ -95,10 +104,10 @@ function run(args) {
  * is never adopted. When a role label appears more than once the first-listed child
  * wins, so a converged re-run is deterministic.
  * @param {string} parentId
- * @returns {Map<string, Adoptable>} Keyed by `stage:<id>` or `lifecycle:feature-pr`
+ * @returns {Promise<Map<string, Adoptable>>} Keyed by `stage:<id>` or `lifecycle:feature-pr`
  */
-function readAdoptable(parentId) {
-  const raw = run(['bd', 'children', parentId, '--json']);
+async function readAdoptable(parentId) {
+  const raw = await run(['bd', 'children', parentId, '--json']);
   /** @type {Array<{ id: string, labels?: string[], dependencies?: Dependency[] }>} */
   const children = raw === '' ? [] : JSON.parse(raw);
 
@@ -127,15 +136,20 @@ function readAdoptable(parentId) {
  * @param {string} beadId
  * @param {string} dependsOnId
  * @param {Set<string>} blocks  Dependencies the bead already has; extended in place
+ * @returns {Promise<void>}
  */
-function wireBlocks(beadId, dependsOnId, blocks) {
+async function wireBlocks(beadId, dependsOnId, blocks) {
   if (blocks.has(dependsOnId)) { return; }
-  run(['bd', 'dep', 'add', beadId, dependsOnId, '--type', 'blocks']);
+  await run(['bd', 'dep', 'add', beadId, dependsOnId, '--type', 'blocks']);
   blocks.add(dependsOnId);
 }
 
 // ─── 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);
 
@@ -143,24 +157,28 @@ const { parentId, priority } = parseArgs(process.argv.slice(2));
 
 const pipelinePath = resolve(__dirname, '..', 'pipeline.json');
 /** @type {Pipeline} */
-const pipeline = JSON.parse(readFileSync(pipelinePath, 'utf-8'));
+const pipeline = JSON.parse(await readFile(pipelinePath, 'utf-8'));
 
-const adoptable = readAdoptable(parentId);
+const adoptable = await 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}`);
 
   const beadId = adopted
     ? adopted.id
-    : run([
+    : await run([
         'bd', 'create', JSON.stringify(`[${parentId}] ${stage.title}`),
         '--type', 'chore',
         '--description', JSON.stringify(stage.description),
         '--priority', priority,
-        '--labels', `stage:${stage.id}`,
+        '--labels', [`stage:${stage.id}`, ...(stage.labels ?? [])].join(','),
         '--parent', parentId,
         '--silent',
       ]);
@@ -171,22 +189,25 @@ 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.`);
       process.exit(1);
     }
-    wireBlocks(beadId, depBeadId, blocks);
+    await 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);
@@ -196,7 +217,7 @@ const adoptedGate = adoptable.get('lifecycle:feature-pr');
 
 const prGateBeadId = adoptedGate
   ? adoptedGate.id
-  : run([
+  : await run([
       'bd', 'create', JSON.stringify(`[${parentId}] PR Review and Merge`),
       '--type', 'task',
       '--description', JSON.stringify(
@@ -218,7 +239,13 @@ const prGateBeadId = adoptedGate
 
 /** @type {Set<string>} */
 const gateBlocks = adoptedGate ? adoptedGate.blocks : new Set();
-wireBlocks(prGateBeadId, documentStageBeadId, gateBlocks);
+await 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) {
+  await wireBlocks(beadId, prGateBeadId, blocks);
+}
 
 /** @type {Record<string, string>} */
 const result = {

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

@@ -10,9 +10,14 @@
 ## Relevant files
 <list source files you read during context gathering>
 
-## Progress log
-Write progress to: `.agent-cortex/ralph/ralph-<bead-id>.log`
-Log stage start, test results, build errors, and stage complete (see Progress Logging in run-pipeline-stage skill).
+## Trail entry
+Record one entry at stage start and one at stage close through the shared writer (see Trail Entries in the `run-pipeline-stage` skill):
+```bash
+node <run-pipeline-stage-scripts>/trail-entry.mjs \
+  --bead <bead-id> --stage code --outcome <done|blocked|partial> \
+  --evidence "<evidence>" --remaining "<what is left, or none>"
+```
+Evidence for a code stage: the test and lint result, the stage commit, and any build error.
 
 ## Instructions
 Invoke the `style-code` skill before making any code changes.

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

@@ -10,9 +10,14 @@
 ## Files changed
 <FILES_CHANGED from the final coder/fixer REPORT>
 
-## Progress log
-Write progress to: `.agent-cortex/ralph/ralph-<bead-id>.log`
-Log stage start and stage complete (see Progress Logging in run-pipeline-stage skill).
+## Trail entry
+Record one entry at stage start and one at stage close through the shared writer (see Trail Entries in the `run-pipeline-stage` skill):
+```bash
+node <run-pipeline-stage-scripts>/trail-entry.mjs \
+  --bead <bead-id> --stage document --outcome <done|blocked|partial> \
+  --evidence "<evidence>" --remaining "<what is left, or none>"
+```
+Evidence for a document stage: the files updated and the stage commit.
 
 ## Instructions
 Invoke the `style-documentation` skill before making any documentation changes.

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

@@ -7,9 +7,14 @@
 ## Files to update
 <FILES_CHANGED from the previous coder/fixer's REPORT>
 
-## Progress log
-Write progress to: `.agent-cortex/ralph/ralph-<bead-id>.log`
-Log stage start, test results, build errors, and stage complete (see Progress Logging in run-pipeline-stage skill).
+## Trail entry
+Record one entry at stage start and one at stage close through the shared writer (see Trail Entries in the `run-pipeline-stage` skill):
+```bash
+node <run-pipeline-stage-scripts>/trail-entry.mjs \
+  --bead <bead-id> --stage fix --outcome <done|blocked|partial> \
+  --evidence "<evidence>" --remaining "<what is left, or none>"
+```
+Evidence for a fix stage: the test result after the repair, and the commit.
 
 ## Instructions
 Invoke the `style-code` skill before making any code changes.

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

@@ -0,0 +1,69 @@
+## Project context
+<bd prime output — verbatim>
+
+## Task
+<bd show <id> output — verbatim>
+
+## Trail entry
+Record one entry at stage start and one at stage close through the shared writer (see Trail Entries in the `run-pipeline-stage` skill):
+```bash
+node <run-pipeline-stage-scripts>/trail-entry.mjs \
+  --bead <bead-id> --stage housekeeping --outcome <done|blocked|partial> \
+  --evidence "<evidence>" --remaining "<what is left, or none>"
+```
+Evidence for a housekeeping stage: each pruner run, with its exit status.
+
+## 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/planning/create-task/templates/post-merge.md

@@ -0,0 +1,67 @@
+## Project context
+<bd prime output — verbatim>
+
+## Task
+<bd show <id> output — verbatim>
+
+## Trail entry
+Record one entry at stage start and one at stage close through the shared writer (see Trail Entries in the `run-pipeline-stage` skill):
+```bash
+node <run-pipeline-stage-scripts>/trail-entry.mjs \
+  --bead <bead-id> --stage post-merge --outcome <done|blocked|partial> \
+  --evidence "<evidence>" --remaining "<what is left, or none>"
+```
+Evidence for a post-merge stage: the check exit status, the commit, and the escalation bead id when one was filed.
+
+## Instructions
+This stage verifies the merge, so **do not work in the bead worktree**. Run the check from the
+repository's main checkout — the directory that holds `.agent-cortex/worktrees/` — because the
+commit it reads landed on the base branch, not on the feature branch.
+
+1. **Run the check once** from the main checkout:
+   ```bash
+   node <ralph-scripts>/post-merge-check.mjs
+   ```
+   `<ralph-scripts>` is the absolute path to `skills/workflow/ralph/scripts/`, resolved from wherever
+   that skill was loaded. It prints a JSON report and exits `0`, `1`, or `2`. Pass `--base <branch>`
+   only when the base branch is not the repository's default branch, and `--commit <sha>` only when
+   the merge commit is not the base branch's tip. A run still in flight when the wait window closes
+   is a report, not a verdict: the playbook's _Watch transport_ section says how to wait for it, and
+   which mechanism your harness supplies.
+
+2. **Act on the exit status alone.** The status *is* the verdict; do not re-run the check to get a
+   different answer, do not retry the workflow, and never re-run the GitHub workflow yourself.
+
+   | Exit | Meaning | What you do |
+   |---|---|---|
+   | `0` | Every run for the merge commit passed | Report the run URLs and **close** this chore as `SUCCESS` |
+   | `1` | A run for the merge commit failed | The script has already filed **one** P1 escalation bead carrying the run URL and the failing job. Report its id and the run URL, leave this chore **open**, and close nothing else |
+   | `2` | Inconclusive: no run for the commit, a run still in flight past the wait window, a conclusion that is neither pass nor failure, or a repository `gh` cannot see as GitHub | Report the `reason` the report printed and leave this chore **open**. Nothing was filed and nothing needs filing |
+
+3. **Never repair the merge from here.** Reverting, re-running a workflow, editing the merged
+   commit, and reopening the parent feature bead are all outside this stage. Exit `1` hands the
+   failure to a human through the escalation bead; the pipeline fixes nothing it did not build.
+
+4. **Build no remediation chain.** A failure here is evidence about a commit that already landed,
+   not a fault in a file a `stage:fix` round can repair. Create no `stage:fix` chore and no fresh
+   stage chore on any exit status, and re-block no later stage.
+
+5. **Close only on `0`.** On `1` and `2` leave the chore open — return it to `open` status if your
+   claim moved it to `in_progress` — so the open chore is the record that the merge is unresolved.
+   Do not close the parent feature bead and do not edit the escalation bead the script filed.
+
+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: post-merge
+SUMMARY: <2–3 sentences: the exit status, the runs read, and what was filed or left open>
+FILES_CHANGED: none
+COMMIT: none
+PUSHED: no
+PR: none
+OUTCOME: <SUCCESS on exit 0; BLOCKED on exit 1 or 2>
+BLOCKING_ISSUES:         ← include only if OUTCOME is BLOCKED; one line per reason
+- <exit status, the report's reason, and the run URL or the surviving uncertainty>
+---

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

@@ -10,9 +10,14 @@
 ## Files changed
 <FILES_CHANGED from the coder/fixer's REPORT block>
 
-## Progress log
-Write progress to: `.agent-cortex/ralph/ralph-<bead-id>.log`
-Log stage start, security scan result, review outcome, and stage complete (see Progress Logging in run-pipeline-stage skill).
+## Trail entry
+Record one entry at stage start and one at stage close through the shared writer (see Trail Entries in the `run-pipeline-stage` skill):
+```bash
+node <run-pipeline-stage-scripts>/trail-entry.mjs \
+  --bead <bead-id> --stage review --outcome <done|blocked|partial> \
+  --evidence "<evidence>" --remaining "<what is left, or none>"
+```
+Evidence for a review stage: the security scan result and the review outcome.
 
 ## Instructions
 **First**, invoke the `review-security` skill and run the scan against the changes. If the

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

@@ -10,9 +10,14 @@
 ## Files changed
 <FILES_CHANGED from the coder/fixer's REPORT block>
 
-## Progress log
-Write progress to: `.agent-cortex/ralph/ralph-<bead-id>.log`
-Log stage start, each command run, test/lint result, and stage complete (see Progress Logging in run-pipeline-stage skill).
+## Trail entry
+Record one entry at stage start and one at stage close through the shared writer (see Trail Entries in the `run-pipeline-stage` skill):
+```bash
+node <run-pipeline-stage-scripts>/trail-entry.mjs \
+  --bead <bead-id> --stage verify --outcome <done|blocked|partial> \
+  --evidence "<evidence>" --remaining "<what is left, or none>"
+```
+Evidence for a verify stage: each command run, with its test and lint result.
 
 ## Instructions
 Discover and run the project's test and lint commands, then report the outcome.