@jaybeeuu/agent-cortex 2.7.0 → 2.8.0

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, 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".
+description: Execute a single pipeline stage for a bead (code, verify, review, document, post-merge, 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: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.
+Stage beads (`stage:code`, `stage:verify`, `stage:review`, `stage:document`, `stage:post-merge`, `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` and `post-merge` are the exceptions: `housekeeping` never closes its bead over a worktree the pruner did not remove, `post-merge` leaves its bead open when the merge's CI run failed or the check was inconclusive, and neither builds 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 (`housekeeping` excepted: it leaves its bead open), remediation children, the REPORT |
+| Stage runner (worker) | Trail entries through `scripts/trail-entry.mjs`, closing its leaf bead on both outcomes (`housekeeping` and `post-merge` excepted: each may leave 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.
@@ -33,7 +33,7 @@ A leaf bead is the worker's record of what happened. The orchestrator reads it;
 
 1. Run `bd prime` and hold the output; subagents can run it themselves if they need context.
 2. If no bead was specified, run `bd ready` and ask the user which to work on.
-3. Claim the bead with `bd update <id> --claim` — the bead, not the prompt, is the source of truth. Append a stage-start note immediately (see _Milestone Notes_).
+3. Claim the bead with `bd update <id> --claim` — the bead, not the prompt, is the source of truth. Record a stage-start trail entry immediately (see _Trail Entries_).
 4. Read the bead's `stage:*` label — it names the stage to execute.
 5. Load the universal stage-runner prompt (`skills/workflow/run-pipeline-stage/prompts/stage-runner.md`) — it carries the lifecycle, remediation, and REPORT contract — populate `<stage>`, and read the matching playbook (`playbooks/<stage>.md`) for stage-specific rules.
 6. Tag the stage — beads are the only status view:
@@ -43,7 +43,7 @@ bd tag <id> stage:<stage>
 ```
 
 7. Dispatch one subagent per stage with the composed prompt — spawn it with {{TOOL:task}}. The prompt already ends with the REPORT contract; never compose one without it. A session with no subagent tool cannot dispatch: stop and say so rather than substituting a backgrounded CLI run, which has no completion signal.
-8. Verify the delivery against the worktree — `node scripts/lib/verify-worker-tree.mjs --worktree <abs-worktree> --base <base>` exits 0 only for a clean tree with a commit ahead of base. A worker whose REPORT claims `OUTCOME: SUCCESS` over a dirty tree has not delivered; re-dispatch it instead of advancing.
+8. Verify the delivery against the worktree — `node scripts/lib/verify-worker-tree.mjs --worktree <abs-worktree> --base <base>` exits 0 only for a clean tree with a commit ahead of base. A worker whose REPORT claims `OUTCOME: SUCCESS` over a dirty tree has not delivered; re-dispatch it instead of advancing. `post-merge` and `housekeeping` change no files and deliver no commit, so skip this check for those two stages.
 9. On the REPORT: route forward per _Routing_ below. Do **not** close the leaf bead — the worker closed it before reporting.
 
 Each step leaves observable state — a claimed bead, a `stage:` tag, worker notes and a closed bead, a verified commit, and a REPORT that drives the next action.
@@ -58,8 +58,10 @@ 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 |
+| `post-merge` | `OUTCOME: SUCCESS` | Create nothing — the merge commit's CI run is green; the closed chore is the record |
 | `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 |
+| `post-merge` | `OUTCOME: BLOCKED` | Create nothing — the worker left its chore **open** and the check filed one P1 escalation bead; report the escalation id and the run URL, and do not re-dispatch |
 | `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 |
 
@@ -81,32 +83,46 @@ On `OUTCOME: BLOCKED` the worker creates its own chain — a `stage:fix` chore c
 | `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 |
+| `post-merge` | none — the worker leaves its chore open, reports `BLOCKED`, and names the escalation bead the check filed. No `stage:fix` and no fresh `stage:post-merge`, because no fix round repairs a commit that already merged |
 
 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.
 
-## Progress Logging
+## Trail Entries
 
-Inside the ralph orchestrator, write one structured line per transition or key event to `.agent-cortex/ralph/ralph-{bead-id}.log`:
+One script writes the bead trail: `scripts/trail-entry.mjs`, run by the worker at each transition. It appends one checkpoint to the bead's notes with `bd note`, and records any refs the caller names as provenance events.
 
-```
-[ISO-timestamp] [bead-id] [stage] message
+```bash
+node <run-pipeline-stage-scripts>/trail-entry.mjs \
+  --bead <id> --stage <stage> --outcome <done|blocked|partial> \
+  --evidence "<test or lint result, commit, command output>" \
+  --remaining "<what is left, or none>" \
+  [--commit <ref>] [--branch <branch>] [--pr <url>] [--work-id <worktree-id>]
 ```
 
-Log stage starts and completes, test/lint/build/security results, blockers, and decisions — not file reads or minor actions.
+Three fields are mandatory, and the script refuses an entry without them:
 
-```bash
-mkdir -p .agent-cortex/ralph && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [bead-id] [stage] message" >> .agent-cortex/ralph/ralph-bead-id.log
-```
+- **Outcome** — `done`, `blocked` or `partial`, a fixed vocabulary rather than prose.
+- **Evidence** — the result that proves it: a test or lint outcome, the commit SHA, command output.
+- **What is left** — the next concrete action, or `none`.
 
-## Milestone Notes
+`--commit` accepts any ref and is resolved through `git rev-parse` to the full 40-character lowercase SHA, because `bd provenance record --ref-kind git-sha` refuses an abbreviated one. A ref that does not resolve to 40 lowercase hex characters records nothing at all.
 
-The bead's notes are the recovery contract: if a session dies mid-stage, a fresh agent must resume from `bd show <id>` alone. Append a short checkpoint at stage start and at each milestone — never on every tool call.
+Recording is safe to repeat. The entry carries a fingerprint of its own content, so a repeated fire — a second run after the first finished — finds it present and appends nothing; provenance recording is idempotent in `bd` itself. That holds for one writer at a time: `bd note` has no conditional append, so two writers that read the bead before either appends both write, and the duplicate entries carry the same fingerprint and are deduplicable — fire each transition from one worker. A transient database failure — `failed to open database ... context canceled`, the shape two concurrent writers produce — is retried with bounded backoff, and each retry re-reads the bead first, so a write that landed before its call reported failure is never duplicated. A permanent failure reports on stderr with a non-zero exit and appends nothing twice.
+
+Resume with the recovery brief below; reach for `bd show <id>` (entries) or `bd provenance log <id>` (refs) only to widen what it printed. A note appended by hand with `bd note` prints in the brief wherever it lands, so the trail count includes it. There is no progress file: beads stay the single source of truth, and no stage writes a log.
+
+### Reading the trail
+
+Run `scripts/recover-brief.mjs` first. One call prints what a session needs to continue: status and state labels, the newest trail entries with their Evidence and What is left, provenance refs, blocking dependencies, and the acceptance criteria. `bd show` on a bare bead carrying 20 entries prints 89 lines and about 6.5 KB, and on a realistic one — 21 entries with acceptance criteria, a blocker, provenance refs and a description — about 120 lines and about 8 KB, most of it history the reader does not need; the brief stays inside a line budget (default 40) that the script enforces on its own output.
 
 ```bash
-bd update <id> --append-notes "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [<stage>] <what changed / what's next>"
+node <run-pipeline-stage-scripts>/recover-brief.mjs --bead <id> \
+  [--trail 3] [--provenance 4] [--max-lines 40]
 ```
 
-`--append-notes` preserves the trail; plain `--notes` overwrites it. Record the start (stage, worktree, first action), milestones (completed chunks, tests green, files changed), decisions and rejected options, blocks, and discoveries. One or two lines per entry — a scan-friendly checkpoint trail, not a transcript. No new scratch files; beads stay the single source of truth.
+`bd` returns the whole note — there is no way to ask it for the last few entries — so the brief prints the newest `--trail` entries and summarises the rest by count. It reads only: every `bd` call is a read subcommand carrying `--readonly`, so it cannot write to the tracker, and it never records a note or a provenance event. Its sections state plainly when a bead has no trail, no refs, no acceptance criteria or no blockers, rather than printing an empty heading.
+
+Read the whole note with `bd show <id>` only when you need an entry the window left out, and the full event history with `bd provenance log <id>` only when the brief's four events are not enough.
 
 ## Report Format
 
@@ -115,7 +131,7 @@ Every stage-runner prompt ends with the literal REPORT instruction (see `prompts
 ```
 ---REPORT---
 BEAD_ID: <id>
-STAGE_COMPLETED: <code|verify|review|document|housekeeping|fix>
+STAGE_COMPLETED: <code|verify|review|document|post-merge|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">
@@ -154,9 +170,9 @@ stage: the commit is the evidence, the report is the claim.
 
 - [create-task](../../planning/create-task/SKILL.md) — owns `pipeline.json`: stages, `maxFixRounds`, and the stage templates.
 - [bd-tool](../../productivity/bd-tool/SKILL.md) — bead mechanics beyond the commands used here.
-- [ralph](../ralph/SKILL.md) — runs many stage beads concurrently and consumes this skill's log and REPORT contracts.
+- [ralph](../ralph/SKILL.md) — runs many stage beads concurrently and consumes this skill's trail and REPORT contracts.
 
-Each playbook delegates to a stage skill: `tdd`/`style-code`/`style-tests` (code, fix), `review-security` (review), `style-documentation` (document).
+Each playbook delegates to a stage skill: `tdd`/`style-code`/`style-tests` (code, fix), `review-security` (review), `style-documentation` (document). `housekeeping` and `post-merge` delegate to no stage skill — each runs one deterministic script and reports what it printed.
 
 ## Examples
 
@@ -175,6 +191,5 @@ Each playbook delegates to a stage skill: `tdd`/`style-code`/`style-tests` (code
 - [ ] `bd tag <id> stage:<stage>` run before dispatch.
 - [ ] Correct playbook read and followed for the stage; stage skills invoked where the playbook says.
 - [ ] Composed prompt carries the lifecycle, remediation, and REPORT contract from `prompts/stage-runner.md`.
-- [ ] Progress log lines written for every stage transition and key result.
-- [ ] Milestone notes appended at stage start and each milestone with `--append-notes` (not `--notes`).
+- [ ] A trail entry written at every stage transition, through `trail-entry.mjs`, with Outcome, Evidence and What is left.
 - [ ] The orchestrator closed no leaf bead and created no fix bead; the cap backstop ran before any dispatch.

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

@@ -2,12 +2,18 @@
 
 ## Stage Instructions
 
-1. Invoke `style-tests` before writing tests.
-2. Invoke `tdd` for the red-green-refactor implementation loop.
-3. Invoke `style-code` before making code changes.
-4. Do not add speculative code — only what is required by current tests/requirements.
-5. Make only task-scoped changes; avoid unrelated refactors.
-6. Use context7 for third-party libraries when API/version details matter.
+1. Invoke `implement-task` first. It reads the parent's `## Acceptance Criteria`, writes the
+   criteria → evidence table before any code is touched, and holds the scope, boy-scout and
+   mutation-check rules for the rest of the stage. A criterion with no check is a blocker: report
+   `OUTCOME: BLOCKED` rather than guessing a proof.
+2. It routes to `style-tests` before writing tests.
+3. It routes to `tdd` for the red-green-refactor loop, one criterion at a time.
+4. It routes to `style-code` before making code changes.
+5. Do not add speculative code — only what is required by current tests/requirements.
+6. Make only task-scoped changes; record out-of-scope findings as beads instead of editing them.
+7. Use context7 for third-party libraries when API/version details matter.
+8. Report the filled criteria → evidence table; the stage's requirements are the rows, not the
+   diff.
 
 ## Stage Outcome
 
@@ -19,8 +25,8 @@
 
 ## Remediation and close
 
-- You own this leaf bead: append notes, write the progress log, and `bd close <id> --reason=...`
-  on both outcomes (see `prompts/stage-runner.md`).
+- You own this leaf bead: record the trail entry through `scripts/trail-entry.mjs`, then
+  `bd close <id> --reason=...` on both outcomes (see `prompts/stage-runner.md`, _Trail entries_).
 - `OUTCOME: SUCCESS` — create nothing; the orchestrator routes to `verify`.
 - `OUTCOME: BLOCKED` — count the parent's existing `stage:fix` children against
   `maxFixRounds` in `skills/planning/create-task/pipeline.json`. Under cap, create a

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

@@ -21,8 +21,8 @@
 
 ## Remediation and close
 
-- You own this leaf bead: append notes, write the progress log, and `bd close <id> --reason=...`
-  on both outcomes (see `prompts/stage-runner.md`).
+- You own this leaf bead: record the trail entry through `scripts/trail-entry.mjs`, then
+  `bd close <id> --reason=...` on both outcomes (see `prompts/stage-runner.md`, _Trail entries_).
 - `OUTCOME: SUCCESS` — create nothing; the orchestrator opens the feature PR and updates the
   HITL gate bead.
 - `OUTCOME: BLOCKED` — count the parent's existing `stage:fix` children against

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

@@ -19,8 +19,8 @@
 
 ## Remediation and close
 
-- You own this leaf bead: append notes, write the progress log, and `bd close <id> --reason=...`
-  on both outcomes (see `prompts/stage-runner.md`).
+- You own this leaf bead: record the trail entry through `scripts/trail-entry.mjs`, then
+  `bd close <id> --reason=...` on both outcomes (see `prompts/stage-runner.md`, _Trail entries_).
 - `OUTCOME: SUCCESS` — create nothing; closing this bead unblocks the fresh stage chore that
   was wired behind it.
 - `OUTCOME: BLOCKED` — count the parent's existing `stage:fix` children against

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

@@ -46,7 +46,7 @@ closed beads and changes no files.
 
 - **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
+- `OUTCOME: SUCCESS` — record the trail entry, 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

package/skills/workflow/run-pipeline-stage/playbooks/post-merge.md

@@ -0,0 +1,54 @@
+# Stage Playbook: post-merge
+
+## Stage Instructions
+
+1. Run the check once from the **main checkout** — never from the bead worktree, because the commit
+   under test landed on the base branch:
+   ```bash
+   node <ralph-scripts>/post-merge-check.mjs
+   ```
+   It prints a JSON report and exits `0` passed, `1` failed, `2` inconclusive.
+2. Read the exit status as the verdict. `--base <branch>` overrides the base branch (default: the
+   repository's default branch). `--commit <sha>` overrides the merge commit (default: the base
+   branch's tip). `--wait <seconds>` changes the wait window; the default is 300.
+3. On `0` — report the run URLs and close the chore. On `1` — the script filed one P1 escalation
+   bead carrying the run URL and the failing job; report the bead id and the run URL, and leave the
+   chore **open**. On `2` — report the printed `reason` and leave the chore **open**.
+4. Never retry the check for a different answer, never re-run the GitHub workflow, never revert the
+   merge, and never reopen the parent feature bead.
+5. The check reads `gh run list` for the base branch: GitHub-only in v1. A repository `gh` cannot
+   resolve to GitHub, or a commit with no run, is `inconclusive` — reported, never escalated.
+
+## Watch transport
+
+The check waits `--wait` seconds (default 300) for the run to settle. A run still in flight at that
+window is exit `2` with a still-running reason: a report, not a verdict, and never something to page
+a human for.
+
+The wait past that window belongs to the harness, so never write a poll loop of your own — no
+`sleep` and re-run. Poll with {{TOOL:post_merge_watch}} and end the turn. The session resumes when a
+verdict may exist; run the check again then, and apply step 3 unchanged.
+
+Running the check again on a resume is the watch continuing, not the retry step 4 forbids: you read
+the same run's verdict, never ask for a different one. A failure still reaches a human through the
+escalation bead the script files, and this stage still repairs nothing.
+
+No harness is assumed to have a watcher. A session with no such mechanism runs the check once with
+a longer window instead — `node <ralph-scripts>/post-merge-check.mjs --wait 1800` — and reports what
+it printed. The verdicts, the escalation rule and the close rule do not change.
+
+## Stage Outcome
+
+- `OUTCOME: SUCCESS` only on exit `0`.
+- `OUTCOME: BLOCKED` on exit `1` or `2`, with the report's `reason` under `BLOCKING_ISSUES`.
+- This stage changes no files: report `FILES_CHANGED: none`, `COMMIT: none`, `PUSHED: no`.
+
+## Remediation and close
+
+- `OUTCOME: SUCCESS` — close the chore with the run URLs in the close reason. Create nothing.
+- `OUTCOME: BLOCKED` — leave the chore **open**, report the exit status, the reason, and the
+  escalation bead id when the script filed one. Build no remediation chain: there is no `stage:fix`
+  round that repairs a commit which already merged, and nothing downstream waits on this chore.
+- The escalation bead is the script's to file: one **open** bead per failing run, because the
+  `bd list` search behind its marker does not see closed beads, so a run a human already resolved
+  can be escalated again. Never file a second one yourself, and never edit or close the one it filed.

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

@@ -9,7 +9,14 @@
    - stop further review.
 3. Invoke `style-code` and `style-tests` for code and test review criteria.
 4. Review for correctness, requirement alignment, and material quality issues.
-5. Do not request changes for stylistic preferences alone.
+5. Read the name of every changed test, then find the assertion that proves each clause of it. A
+   count in the name needs a count assertion, a state needs that state, and a "not" needs the
+   absence. Reject the test when any clause has no assertion, and name the missing clause under
+   `BLOCKING_ISSUES`.
+6. Say in the `SUMMARY` whether the mutation check from `style-tests` was run. A branch that adds
+   or changes a test owes that check whether or not the bead asked for it. Block when the branch
+   shows no evidence that it ran.
+7. Do not request changes for stylistic preferences alone.
 
 ## Stage Outcome
 
@@ -18,10 +25,34 @@
 - If blocked, enumerate required changes under `BLOCKING_ISSUES`.
 - `FILES_CHANGED` should be `none`.
 
+## One defect class per rejection
+
+A rejection carries exactly one `defect:<class>` label, from the closed list in the
+`review-defects` skill, plus the specific reason in the rejection text. The label names the kind;
+`BLOCKING_ISSUES` names this instance.
+
+```bash
+bd update <id> --add-label defect:test-unproven
+```
+
+- Apply it to the bead whose work you reject. That bead is normally the code chore, which the
+  code stage already closed; the label attaches to it all the same, so the queries in
+  `review-defects` pass `--all` and a query without the flag finds nothing. Two findings of
+  different kinds are two `BLOCKING_ISSUES` entries and one label: the class of the finding that
+  must be fixed first.
+- A class that is not on the closed list is a review defect in itself. Say so under
+  `BLOCKING_ISSUES` and use the nearest real class — never invent a `defect:` label.
+- The review that confirms the fix removes the label
+  (`bd update <id> --remove-label defect:test-unproven`) and records the removal in its trail
+  entry. A closed defect is a trail fact, never a second class.
+
+A test whose name outruns its assertions is `defect:test-unproven`; a test that would pass against
+a broken implementation is `defect:test-cannot-fail`.
+
 ## Remediation and close
 
-- You own this leaf bead: append notes, write the progress log, and `bd close <id> --reason=...`
-  on both outcomes (see `prompts/stage-runner.md`).
+- You own this leaf bead: record the trail entry through `scripts/trail-entry.mjs`, then
+  `bd close <id> --reason=...` on both outcomes (see `prompts/stage-runner.md`, _Trail entries_).
 - `OUTCOME: SUCCESS` — create nothing; the orchestrator routes to `document`.
 - `OUTCOME: BLOCKED` — count the parent's existing `stage:fix` children against
   `maxFixRounds` in `skills/planning/create-task/pipeline.json`. Under cap, create a

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

@@ -15,8 +15,8 @@
 
 ## Remediation and close
 
-- You own this leaf bead: append notes, write the progress log, and `bd close <id> --reason=...`
-  on both outcomes (see `prompts/stage-runner.md`). This is the stage that most often fails —
+- You own this leaf bead: record the trail entry through `scripts/trail-entry.mjs`, then
+  `bd close <id> --reason=...` on both outcomes (see `prompts/stage-runner.md`, _Trail entries_). This is the stage that most often fails —
   closing it is not a failure of the pipeline.
 - `OUTCOME: SUCCESS` — create nothing; the orchestrator routes to `review`.
 - `OUTCOME: BLOCKED` — count the parent's existing `stage:fix` children against

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

@@ -13,20 +13,56 @@ Run `bd prime` if you need project-level context (conventions, tech stack, goals
 ## Prior stage context (if any)
 <prior REPORT fields, dependency context, and relevant files>
 
-## Progress log
-Write progress to: `.agent-cortex/ralph/ralph-<bead-id>.log`
-
-## Milestone notes
+## Trail entries
 The bead's notes are the recovery contract — a fresh session must be able to resume from
-`bd show <id>` alone. Append a short checkpoint before starting and at each milestone:
+`bd show <id>` alone. One script writes that trail: run it at stage start, at each milestone, and
+at stage close.
+
+```bash
+node <run-pipeline-stage-scripts>/trail-entry.mjs \
+  --bead <id> --stage <stage> --outcome <done|blocked|partial> \
+  --evidence "<test or lint result, commit, command output>" \
+  --remaining "<what is left, or none>" \
+  [--commit <ref>] [--branch <branch>] [--pr <url>] [--work-id <worktree-id>]
+```
+
+`<run-pipeline-stage-scripts>` is the absolute path to
+`skills/workflow/run-pipeline-stage/scripts/`, resolved from wherever that skill was loaded — never
+hardcode one harness's install path.
+
+Every entry carries three mandatory fields:
+
+- **Outcome** — `done`, `blocked` or `partial`. A fixed vocabulary, never prose.
+- **Evidence** — what proves it: a test or lint result, the commit SHA, or command output.
+- **What is left** — the next concrete action, or `none`.
+
+`--commit` takes any ref — `HEAD`, a short SHA, a branch — and the script resolves it to the full
+40-character lowercase SHA before recording, because `bd provenance record --ref-kind git-sha`
+refuses anything else. Refs you pass are also recorded as provenance events, visible with
+`bd provenance log <id>`.
+
+Run it at each transition instead of writing notes by hand: one entry per transition, decisions and
+blocks included. Recording is idempotent for one worker, so a repeated fire appends nothing
+twice, and a transient database failure is retried. It is not safe under concurrent writers —
+`bd note` has no conditional append — so one worker fires each transition. There is no progress
+file: the bead is the only trail.
+
+### Reading the trail
+
+To pick up a bead you did not write — a resumed session, a handoff, a fix round — run the recovery
+brief before anything else:
 
 ```bash
-bd update <id> --append-notes "[<ISO-timestamp>] [<stage>] <what changed / what's next>"
+node <run-pipeline-stage-scripts>/recover-brief.mjs --bead <id>
 ```
 
-Use `--append-notes` — plain `--notes` overwrites the trail. Record start, milestones, decisions
-(with rejected options), blocks, and discoveries. One or two lines per entry: a checkpoint trail,
-not a transcript.
+It prints status and state labels, the newest trail entries with their Evidence and What is left,
+the provenance refs, the blocking dependencies, and the acceptance criteria, bounded to about 40
+lines. `bd show` prints the whole note — 89 lines and about 6.5 KB for a bare bead carrying 20
+entries, about 120 lines and about 8 KB for a realistic one with acceptance criteria, a blocker,
+provenance refs and a description — so reach for it only when you need an entry the brief's window
+left out. The brief only reads: every `bd` call is a read subcommand carrying `--readonly`, so it
+never writes to the tracker.
 
 ## Leaf bead lifecycle (yours to close)
 
@@ -41,7 +77,8 @@ not a transcript.
 
    **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).
+   _Remediation_ below). **Exception — `post-merge`.** It closes its bead on exit `0` and leaves it
+   **open** on exit `1` or `2`, where the check reported a failed or inconclusive run.
 3. **Do not create the next stage on success.** Routing forward is the orchestrator's job.
 
 ## Remediation (only when your outcome is BLOCKED)
@@ -51,6 +88,11 @@ not a transcript.
 bead open, reports `OUTCOME: BLOCKED` with the surviving worktrees, and hands the chore to a human.
 Every step below applies to every other stage.
 
+**Exception — `post-merge` builds nothing.** It verified a commit that already merged, so a fix
+round has nothing to repair and no later stage to re-block. It leaves its chore open, reports
+`OUTCOME: BLOCKED` with the check's reason, and names the P1 escalation bead the check filed when
+the run failed. 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
@@ -100,6 +142,8 @@ dirty worktree counts as a failed stage whatever the outcome line claims.
 
 **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.
+**Exception — `post-merge`.** It changes no files either: always report `COMMIT: none` and
+`PUSHED: no`, whatever the check's exit status.
 
 ## Instructions
 1. Read and follow the playbook file listed above.
@@ -113,7 +157,7 @@ End your response with a `---REPORT---` block in exactly this format:
 ```
 ---REPORT---
 BEAD_ID: <id>
-STAGE_COMPLETED: <code|verify|review|document|housekeeping|fix>
+STAGE_COMPLETED: <code|verify|review|document|post-merge|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">