@jaybeeuu/agent-cortex 2.7.0 → 2.8.0

package/skills/review/review-defects/EXAMPLES.md

@@ -0,0 +1,122 @@
+# Review defects — worked examples
+
+One case per class. Each shows what was observed, the label, and the rejection text to write. Six
+were observed in real review rounds and one in a code stage's check of its own change; `scope-creep`
+is described as a situation, because no recorded case exists, so you can match its shape without
+guessing at history.
+
+## `test-unproven` — the name claims a settle-time cleanup
+
+**Observed.** A test named "… removes it when the watch settles" called `stop()` and asserted the
+entry was gone. It never settled the watch, so the settle path had no assertion. The cleanup on
+settle could have been deleted and the test would still pass.
+
+**Label.** `defect:test-unproven`
+
+**Rejection text.** "Test `…removes it when the watch settles` claims removal at the settle step,
+but the body stops the watch and asserts removal once. Add the settle trigger and assert the entry
+is gone after it. Either the name or the assertion must change."
+
+**Why this class.** Not `test-cannot-fail`: the assertion is genuine and would fail for the bug it
+covers. The defect is narrower — the name promises a path the body never takes.
+
+## `test-cannot-fail` — the concurrent case is never exercised
+
+**Observed.** A note appended "a double fire appends nothing twice". The test fired twice in
+sequence and asserted one entry. Two concurrent fires were never run, so the claim could not fail.
+
+**Label.** `defect:test-cannot-fail`
+
+**Rejection text.** "The claim is about concurrent double fires, but the test fires sequentially.
+Await both fires against the same target and assert one entry, or rename the claim. As written no
+implementation can fail it."
+
+**Why this class.** Not `test-unproven`: the name and the assertion agree on "two fires produce one
+entry". The gap is that the case the claim is about is never constructed.
+
+## `missing-proof` — a report of a demonstration that was stubbed
+
+**Observed.** A stage report stated "end-to-end run verified: the check writes the record and the
+follow-up reads it". The command in the evidence block substituted a stub for the check, so no
+end-to-end path ran.
+
+**Label.** `defect:missing-proof`
+
+**Rejection text.** "`SUMMARY` claims an end-to-end demonstration; the evidence command replaces the
+check with a stub, so the record is written by the test, not by the code under review. Paste the
+real invocation and its output."
+
+**Why this class.** Nothing is missing from the code. The gap is between the claim and the evidence
+for it, which is exactly what this class names.
+
+## `docs-drift` — shipped text that shipped past its change
+
+**Observed.** Two shipped text defects in one round: a token map named an exact harness version, so
+the mapping broke on the next release; and a peer-channel section still said one harness only, after
+the fork had made it both.
+
+**Label.** `defect:docs-drift`
+
+**Rejection text.** "The token map names an exact harness version — it must read the running one or
+a documented default. The peer-channel section says one harness only, but the mapping now covers
+both; update the prose to what ships."
+
+**Why this class.** The shipped artefact and the text describing it disagree. A reviewer reading the
+text would predict behaviour the install does not have.
+
+## `criteria-unmet` — the change breaks the criterion it must satisfy
+
+**Observed.** A criterion said an install leaves one directory free of the tool's own files. The
+change wrote its state record into that very directory, so the reviewer could not affirm the
+criterion at all.
+
+**Label.** `defect:criteria-unmet`
+
+**Rejection text.** "The criterion says that directory holds no file of ours; the new record is
+written into it, so the criterion fails. Move the record under the tool's own state directory,
+keyed by the directory it describes, or amend the criterion in the bead and say why."
+
+**Why this class.** The work is real and the scope is honest — part of what was asked is absent.
+
+## `scope-creep` — unrelated tidying rides along
+
+**Situation.** A change that adds one label also renames three unrelated helpers and reformats a
+neighbouring module.
+
+**Label.** `defect:scope-creep`
+
+**Rejection text.** "The rename and the reformat are outside the criteria. Split them into their own
+change so this one can be reviewed and reverted on its own."
+
+**Why this class.** Every line is defensible in isolation. The defect is that the change is wider
+than its reason, which hides the real diff.
+
+## `style-violation` — a written rule is broken
+
+**Observed.** A change added a new skill and declared a `patch` bump in its changeset. The
+versioning rule says a new skill is a `minor` bump and lists "wrong bump type" as a red flag. The
+reviewer rejected the change citing that rule.
+
+**Label.** `defect:style-violation`
+
+**Rejection text.** "The changeset declares `patch`, but this change adds a skill. The versioning
+rule makes an addition `minor` and calls a wrong bump type a red flag. Bump it to `minor`."
+
+**Why this class.** Cite the rule, not a preference. A reviewer who cannot quote a written rule has
+a preference, and preferences are not rejections.
+
+## `regression` — an existing behaviour breaks
+
+**Observed.** A code stage added a manifest write that assumed its target directory existed. An
+install from a source holding no agents and no skills had worked before; after the change it threw
+`ENOENT` on that write. The stage found it in its own check of the change, reproduced it, added a
+test that failed, then fixed it.
+
+**Label.** `defect:regression`
+
+**Rejection text.** "The manifest write assumes its directory exists, so an install from a source
+with no agents and no skills now throws `ENOENT` where it used to succeed. Create the directory
+before writing, and cover the empty-source case with a test."
+
+**Why this class.** The change may satisfy its own criteria fully. It also breaks behaviour nobody
+asked to change, which is a separate fact from `criteria-unmet`.

package/skills/review/review-defects/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: review-defects
+description: The closed vocabulary of `defect:<class>` labels a reviewer applies to a rejected bead, so rejections become countable data. Use when rejecting a change, when deciding which class names a finding, or when querying which defects recur.
+---
+
+# Review defects
+
+A rejection says what is wrong. The class says *which kind* of wrong, in one word, so rejections can
+be counted, compared and trended across tasks instead of re-read one at a time.
+
+## One closed list, one label per rejection
+
+Apply exactly one class from this table. Never invent one.
+
+| Class | The defect | Evidence the rejection must show |
+|---|---|---|
+| `test-unproven` | A test's name claims a requirement its assertions never check. | The named clause, and the assertion that is missing. |
+| `test-cannot-fail` | An assertion passes against a broken implementation. | The case that should fail and does not. |
+| `criteria-unmet` | A criterion from the bead is not delivered. | The criterion, quoted, and what is absent. |
+| `scope-creep` | The change does more than the criteria ask. | The touched behaviour that no criterion names. |
+| `style-violation` | A `style-*` rule is broken. | The rule, quoted, and the line that breaks it. |
+| `missing-proof` | A report claims success with no evidence. | The claim, and the command output that is absent. |
+| `regression` | Behaviour that worked before now breaks. | The old behaviour, and the check that now fails. |
+| `docs-drift` | Shipped text no longer matches what ships. | The text, and the behaviour that contradicts it. |
+
+Two findings of different kinds are two entries in the rejection text and one label: the class of
+the finding that must be fixed first.
+
+## A class is a classification, not a state
+
+The bead's own status still answers "where is this work?". The label answers "what kind of defect
+was this?" — so never use it to mean blocked, in progress or done, and never add a parallel state
+label.
+
+## Apply it
+
+1. Name the class in the rejection text, next to the specific reason.
+2. Apply it to the bead whose work you reject:
+
+   ```bash
+   bd update <id> --add-label defect:test-unproven
+   ```
+
+   That bead is normally already closed — a pipeline closes the chore whose work is rejected before
+   the review runs — and the label attaches to it anyway. So the queries below pass `--all`.
+
+3. Write the specific reason — the file, the line, the missing assertion — in the rejection text.
+   The label is queryable; it is never the whole message.
+
+## Remove it when the fix closes
+
+The review that confirms the fix removes the label, so the vocabulary describes only defects whose
+fix is unconfirmed:
+
+```bash
+bd update <id> --remove-label defect:test-unproven
+```
+
+Record the removal in that review's trail entry ("`defect:test-unproven` cleared"), not as a label.
+A closed defect is a fact in the trail, not a second class.
+
+## An unknown class is itself a defect
+
+A class that is not on the list above is not a label. Applying one is a review defect in itself:
+state it in the rejection text, use the nearest real class for the finding, and raise the gap with
+the owner. Do not extend the list inside a review — a vocabulary that grows per rejection counts
+nothing.
+
+## Query it
+
+```bash
+bd list -l defect:test-unproven --all        # one class, any status
+bd list --label-pattern 'defect:*' --all     # every defect, any class
+```
+
+`--all` is not optional. `bd list` hides closed beads by default, defects are historical data, and
+the bead carrying one is usually closed: drop the flag and the query reports "No issues found" on
+a label that is set.
+
+Count the pattern output per class to see what recurs, and fix the process that produces it — a
+class that keeps appearing is a gap in the stage before this one.
+
+## Worked examples
+
+`EXAMPLES.md` carries one real case per class, with the rejection text a reviewer should write.
+
+## See Also
+
+- [review-security](../review-security/SKILL.md) — the security verdict that precedes any rejection.
+- [run-pipeline-stage](../../workflow/run-pipeline-stage/SKILL.md) — the stage that applies these labels.
+- [bd-tool](../../productivity/bd-tool/SKILL.md) — labels, notes and statuses.

package/skills/style/style-tests/EXAMPLES.md

@@ -434,6 +434,36 @@ for (const item of cart.items) {
 expect(cart.items.map((item) => item.price)).toStrictEqual([10, 20, 30]);
 ```
 
+### A test name is a claim
+
+The name says what the test proves. Read it as a list of assertions and check that each one
+appears in the body. A clause with no assertion is a requirement the suite never enforces, so the
+test stays green while the behaviour breaks.
+
+```ts
+// ❌ Instead — the name claims one notice; the body only claims that something exists.
+// Remove the notice and this test still passes, because a list is always defined.
+it("sends one notice", async () => {
+  await publishAll(recipients);
+
+  expect(await notices.list()).toBeDefined();
+});
+
+// ✅ Write — the count in the name is asserted, so two notices and no notices both fail
+it("sends one notice", async () => {
+  await publishAll(recipients);
+
+  expect(await notices.list()).toHaveLength(1);
+});
+```
+
+A state in the name works the same way — "returns the cached user" needs an assertion that the
+returned user came from the cache, not that a user came back — and a "not" needs an assertion of
+the absence, such as a call count of zero.
+
+The *Workflow* mutation check catches this at run time: disable the behaviour and the bad form
+above stays green, while the good form goes red.
+
 ## Determinism and async
 
 ```ts

package/skills/style/style-tests/SKILL.md

@@ -25,6 +25,7 @@ description: Defines test-writing conventions — assertion strategy, mock disci
 - **Integration and e2e exercise real services.** Run the genuine collaborator — Postgres, Redis, a queue, object storage via TestContainers or LocalStack — never a fake that drifts from the real contract. Reserve e2e for a small number of smoke tests proving the system hangs together.
 - **No more tests than needed.** Every test earns its cost by pinpointing exactly where a failure lies. A test that cannot localise a fault adds maintenance weight without signal.
 - **One behaviour per test.** A test should fail for exactly one reason; several unrelated assertions turn a failure into a debugging exercise.
+- **A test's name is a claim, and every clause of it is an assertion.** A count in the name — "one notice", "both callers", "no retries" — asserts that count; a state in the name asserts that state; a "not" in the name asserts the absence. A name that outruns its assertions states a requirement the test never proves, so the test cannot fail for the reason its name promises. See _Red Flags_, and the "one notice" pair under _A test name is a claim_ in `EXAMPLES.md`.
 - **Test code is production code.** Linted, typechecked, properly typed — no `any`, no unsafe casts, no shortcuts in constructing data. Tolerate WETness where it leaves tests more descriptive.
 - **All setup and assertion data is visible inline.** Show exactly and only the values that explain the case; a helper with sensible defaults keeps it terse.
 - **Deterministic and performant.** A failing or flaky test is investigated now. Deferring is acceptable only against a top-priority bead.
@@ -71,7 +72,9 @@ Worked examples for each rule are in `EXAMPLES.md` under _Test data_.
 
 5. **Write targeted assertions.** Prefer `toMatchObject` over asserting every property. Multiple assertions are fine when they all verify the same behaviour. Avoid asserting call counts when asserting call arguments already covers the behaviour. Assert behaviour the file participates in, never its static contents.
 
-6. **Review against the checklist below.** Read the test as if you are seeing the codebase for the first time.
+6. **Run the mutation check.** Before you finish, disable or revert each behaviour a test claims, then run the suite. Every test named for that behaviour must fail. A named test that still passes proves nothing about its name: it is the _Red Flags_ row on empty implementations, applied to the whole name. Restore the behaviour and confirm the suite is green again.
+
+7. **Review against the checklist below.** Read the test as if you are seeing the codebase for the first time.
 
 ## Red Flags
 
@@ -80,7 +83,8 @@ Worked examples for each rule are in `EXAMPLES.md` under _Test data_.
 | Asserting static file content — an expected config/markdown/terraform string, or a snapshot of static content | Assert the behaviour the file participates in: data inserted into a template, a header compiled correctly, a deployed service ready to serve traffic |
 | Shared mutable top-level fixture reused across tests | Build fresh data per test via a factory; a module-scope constant only when genuinely immutable and read-only |
 | Repeated full literals for the same shape | A small configurable factory taking partial overrides with sensible defaults |
-| A test with no assertion, or one that cannot fail (`expect(result).toBeDefined()`) | Assert the observable contract — a specific value the code must produce |
+| A test with no assertion, or one that passes against an empty implementation (`expect(result).toBeDefined()`) | Assert the observable contract — a specific value the code must produce |
+| A test name whose claim no assertion mentions — "one notice" proven only by `toBeDefined()`, a count proven by truthiness | Assert every clause of the name: the count (`toHaveLength(1)`), the state, the absence |
 | Computing the expected value with the implementation's own logic | Hard-code the expected value from a known-good case; the test must not share the implementation's bug |
 | Mocking implementation details or internal module structure | Mock the genuine external boundary and test through the public interface |
 | An "integration" test that mocks the collaborator it is meant to integrate with | Run the real collaborator (TestContainers/LocalStack); a fake drifts from the real contract |
@@ -115,9 +119,8 @@ Worked examples for each rule are in `EXAMPLES.md` under _Test data_.
 
 ## Examples
 
-The full `❌ Instead` / `✅ Write` catalogue lives in `EXAMPLES.md`: behaviour over
-implementation, test data, mocking, integration and e2e, targeted assertions, structure and
-naming, determinism and async, isolation, and content assertions. Headline pairs:
+The full `❌ Instead` / `✅ Write` catalogue lives in `EXAMPLES.md` — including _A test name is a
+claim_, with the "one notice" pair. Headline pairs:
 
 | Instead of… | Write… |
 |---|---|
@@ -131,7 +134,8 @@ naming, determinism and async, isolation, and content assertions. Headline pairs
 - [ ] Test verifies behaviour, not implementation structure
 - [ ] Integration tests exercise the real collaborator — no mocking the engine you are integrating with
 - [ ] E2E smoke tests prove wiring, migrations, and the journey — not business rules covered lower down
-- [ ] Each test fails for exactly one reason, and its name states the behaviour
+- [ ] Each test fails for exactly one reason, and its name states only behaviour an assertion proves — count, state, and absence included
+- [ ] Mutation check run: each claimed behaviour was disabled, its named tests failed, and the suite is green again
 - [ ] No mocking of internal module details — only public interfaces
 - [ ] No `before`/`after` hooks for shared test state (infrastructure setup only)
 - [ ] Assertions are targeted — no over-asserting, no tautologies, no assertion-free tests

package/skills/workflow/plan/SKILL.md

@@ -156,7 +156,7 @@ For each task (within each epic), create a bead, classify it, and expand AFK tas
 
 ### Phase 4 — Prepare handoff to ralph
 
-Deliver a handoff bead and instructions for running ralph.
+Deliver a handoff bead, message the running ralph session, and give the instructions for running ralph.
 
 17. Determine the entry point:
 
@@ -188,7 +188,15 @@ Deliver a handoff bead and instructions for running ralph.
     ```
     **Gate on the exit status.** Non-zero: retry once, then stop and report the command, exit code and stderr as a sync blocker — the handoff has not left this machine, so do not present the handoff summary.
 
-20. Present the handoff summary:
+20. Send the handoff to the running ralph session, now that the bead exists:
+    ```
+    handoff <handoff-id> — <one-line scope>
+    ```
+    The peer channel carries it: run {{TOOL:peer_list}} first, because with no reachable ralph there is no receiver — report that in the summary and keep the manual instruction below as the handoff path. When ralph is reachable, send it with {{TOOL:peer_send}}, set the intent to `task` where the transport has an intent, and write the kind as the first word of the text — never type into a busy session's terminal, where stray keystrokes are queued as user prompts. Ralph answers `done`, `blocked` or `failed`; `running` or `queued` means delivered, not done, so never read the send itself as acknowledgement. The full kind table, the acknowledgement rule and the per-session setup live in [ralph's REFERENCE](../ralph/REFERENCE.md) (_Peer messaging (planner ↔ ralph)_).
+
+21. While the planning session stays open, treat ralph's `blocked` messages as your pending-human list: each one names a gate bead awaiting a human, so run `bd show <id>` and surface it together with ralph's `done`, `failed` and `update` reports instead of watching a terminal. Read the same gates from `bd` as well, so a message that never arrived is not mistaken for no gate. A peer message is never human consent and never approval for a gate: confirm the gate in `bd`, and let a person close it.
+
+22. Present the handoff summary:
     ```
     ✅ Plan complete. Ready for ralph.
 
@@ -214,6 +222,7 @@ Deliver a handoff bead and instructions for running ralph.
 - [ ] Every handoff-path bead lints clean (`bd lint`)
 - [ ] Bead state pushed with `bd dolt push`, and the push exited 0 — a non-zero exit was retried once, then surfaced as a blocker (command, exit code, stderr) with no handoff summary presented
 - [ ] Handoff summary presented with the exact instruction to give an agent
+- [ ] Handoff message sent to ralph through {{TOOL:peer_send}} (kind `handoff`, naming the handoff bead), or a missing receiver reported in the summary with the manual instruction kept
 
 ## Phase-gate checklist
 
@@ -228,6 +237,7 @@ Deliver a handoff bead and instructions for running ralph.
 - **Skipping the user interview.** The agent has incomplete context. The interview resolves ambiguities that would otherwise surface mid-execution as rework.
 - **Creating horizontal slices.** "All the DB work first, then all the API work" is not tracer bullets. Every task must deliver end-to-end value.
 - **Moving past Phase 2 without user approval.** The task breakdown shapes the entire execution. Do not create beads until the breakdown is approved.
+- **Treating a sent handoff as an accepted one.** A `handoff` message carries no receipt: ralph's status stays `running` or `queued` until it answers `done`, `blocked` or `failed`, so a send that returned is not proof the work started.
 
 ## Common Rationalizations
 
@@ -251,7 +261,7 @@ Deliver a handoff bead and instructions for running ralph.
 - [prd-to-tasks](../../planning/prd-to-tasks/SKILL.md) — load when the PRD is already written and only decomposition is needed.
 - [spec-to-tickets](../../planning/spec-to-tickets/SKILL.md) — load instead when the PRD must become external tickets rather than beads.
 - [create-task](../../planning/create-task/SKILL.md) — Phase 3's per-task bead creation and pipeline expansion; it invokes `classify-bead` internally, so this skill never classifies directly.
-- [ralph](../ralph/SKILL.md) — the downstream consumer of the handoff bead — hand off by running a separate agent with "Use the ralph skill. Start from bead #<handoff-id>".
+- [ralph](../ralph/SKILL.md) — the downstream consumer of the handoff bead — hand off by sending ralph a `handoff` message naming the bead, with "Use the ralph skill. Start from bead #<handoff-id>" as the manual fallback when no ralph session is online. Its [REFERENCE.md](../ralph/REFERENCE.md) owns the planner ↔ ralph message convention.
 
 ## Examples
 
@@ -293,3 +303,4 @@ Full bead tree:
 - [ ] Handoff bead tagged `workflow:ralph`
 - [ ] Bead state pushed with `bd dolt push`, and the push exited 0 — a non-zero exit was retried once, then surfaced as a blocker (command, exit code, stderr) with no handoff summary presented
 - [ ] Handoff summary includes the exact instruction to give an agent
+- [ ] Handoff message sent to ralph (kind `handoff`, naming the handoff bead) through {{TOOL:peer_send}}; ralph's `done`/`blocked`/`failed` replies were the only evidence of completion, never the send itself

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, 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".
+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 `post-merge` and `housekeeping` chores 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:
 
@@ -70,9 +70,9 @@ A ready `execution:afk` task bead with **no** `stage:*` chore children has nothi
    `<create-task-scripts>` is the absolute path to `skills/planning/create-task/scripts/`, resolved from wherever the skill was loaded — never hardcode one harness's install path. `<parent-priority>` is the parent's own priority from `bd show <parent-id>`, so chores match the task they belong to.
 3. **Record it in `inflight`** so its completion is attributable to the parent and it stays in the wait set — it has no chore, so `choreId` is `null`:
    ```json
-   { "kind": "expand", "choreId": null, "parentId": "<parent-id>", "title": "<parent title>", "agentId": "<agent-id>", "logLine": 1 }
+   { "kind": "expand", "choreId": null, "parentId": "<parent-id>", "title": "<parent title>", "agentId": "<agent-id>" }
    ```
-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.
+4. **Report the mapping** the worker returns — `code`, `verify`, `review`, `document`, `post-merge`, `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 — five for the shipped `pipeline.json`; the
+Expect one match per `stage:*` label in the chain — six 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
@@ -130,7 +130,7 @@ Decompose it:
    This is the shape `create-task` builds on its feature path (`SKILL.md` steps 5–6): an `execution:hitl` planning bead owned by the feature, whose impl children depend on it, so the dependency — not a label — is the readiness gate.
 3. **Record it in `inflight`** so its completion is attributable to the feature and it stays in the wait set — it holds no chore, so `choreId` is `null`:
    ```json
-   { "kind": "decompose", "choreId": null, "parentId": "<feature-id>", "title": "<feature title>", "agentId": "<agent-id>", "logLine": 1 }
+   { "kind": "decompose", "choreId": null, "parentId": "<feature-id>", "title": "<feature title>", "agentId": "<agent-id>" }
    ```
 4. **Confirm the children exist** rather than trusting the report — the worker's IDs are a claim, the bead graph is the evidence:
    ```bash
@@ -157,8 +157,8 @@ Chores already exist, so dispatch never creates one:
    - Parent task description from `bd show <parent-id>`
    - For `fix` stage: `FILES_CHANGED` from the preceding stage's report (the required changes come from the fix bead's own description — read via `bd show <fix-id>`)
    - For `verify`, `review`, `document` stages: `SUMMARY` and `FILES_CHANGED` from the preceding stage's report
-   - Log file path `.agent-cortex/ralph/ralph-<parent-id>.log` — logs are keyed by **parent** bead ID, so every stage chore of a feature appends to the same file
-7. **Call the {{TOOL:task}} tool** with the filled prompt as `prompt` and the worktree path as `cwd`. Store the returned agentId — you need it for step 8 and for log polling.
+   - The trail pointer: the worker records its own entries with `<run-pipeline-stage-scripts>/trail-entry.mjs`, so the prompt names that script rather than a log file (see _Reading the Trail_ below)
+7. **Call the {{TOOL:task}} tool** with the filled prompt as `prompt` and the worktree path as `cwd`. Store the returned agentId — you need it for step 8 and for correlating the completion to its bead.
 
    If this session has no subagent tool, **stop and say so**. Do not substitute a backgrounded CLI run (`pi -p … &`): that launch has no completion signal, so a finished worker and a killed one look identical, which is how stages came to be reported complete over uncommitted trees. Record the bead for the shutdown summary and tell the human the session needs restarting with the subagent extension loaded.
 8. **Record the base commit** before the worker starts — you verify delivery against it (_Verified Completion_ below):
@@ -175,7 +175,7 @@ A worker's `---REPORT---` is a claim about the worktree, not evidence of it. Ver
 node scripts/lib/verify-worker-tree.mjs --worktree .agent-cortex/worktrees/<parent-id> --base <base>
 ```
 
-Exit code 0 means a clean tree with at least one commit ahead of the recorded base. A non-zero exit reports `worktree is dirty` or `no commit ahead of base`, and the stage did **not** deliver whatever its `OUTCOME` line says. Re-dispatch the same chore, or record the failure for the fix chain — never advance the parent, close the chore, or open a feature PR over uncommitted work.
+Exit code 0 means a clean tree with at least one commit ahead of the recorded base. A non-zero exit reports `worktree is dirty` or `no commit ahead of base`, and the stage did **not** deliver whatever its `OUTCOME` line says. Re-dispatch the same chore, or record the failure for the fix chain — never advance the parent, close the chore, or open a feature PR over uncommitted work. `post-merge` and `housekeeping` deliver no commit, so this check does not apply to them.
 
 ---
 
@@ -204,6 +204,26 @@ For each parent task bead (`<parent-id>`):
 
 ---
 
+## Post-merge Check
+
+A merge is not verified by merging. The `stage:post-merge` chore reads the CI run that GitHub started for the merge commit on the base branch and reports whether it passed. `create-chores.mjs` pre-creates that chore, labelled `lifecycle:post-merge` and blocked behind the same `lifecycle:feature-pr` gate as `stage:housekeeping`, so it stays out of `bd ready` until a human closes the gate.
+
+```bash
+node skills/workflow/ralph/scripts/post-merge-check.mjs
+```
+
+The script is deterministic: no model, no tokens, zero dependencies, async only. It prints a JSON report and exits `0` when every run for the commit passed, `1` when a run failed, and `2` when the result is inconclusive.
+
+- **Executor.** A dispatched worker runs it from the **main checkout**, like the housekeeping stage: the commit it reads landed on the base branch, not on the feature branch. It resolves the repository slug and base branch through `gh repo view`, so nothing about this repo's slug or `main` is baked in. `--base <branch>` and `--commit <sha>` override each; the wait window is `--wait <seconds>`, default 300. Any revision either flag supplies is expanded through `git rev-parse` first, because `gh run list --commit` matches the full 40-character SHA only — a caller that reaches `gh` with a short SHA gets an empty run list, which reads as `inconclusive` rather than as an error.
+- **Exit `1` files one P1 escalation per open bead.** The bead carries the run URL and the failing job name, is labelled `lifecycle:post-merge-escalation` + `execution:hitl`, and carries a `post-merge-run:<id>` marker in its description. A second run finds the open bead carrying that marker and files nothing. The escalation has no parent, so the feature bead is never reopened and never gains a child.
+- **The marker bounds open beads, not runs — a known limitation.** The marker is searched with `bd list`, which omits closed beads. A run id is immutable, so one bead per run forever is the intent, but the code delivers one **open** bead per run: once a human closes the escalation, a later check of the same run files a fresh bead for it. That repeats a page nobody wants; it never drops a signal. Fixing it means searching closed beads too, which is its own change.
+- **Nothing is retried.** The stage never re-runs the workflow, never retries the check for a different answer, never reverts the merge, and builds no `stage:fix` chain — a commit that already merged is not repaired by a fix round. The chore stays **open** on exit `1` and `2`.
+- **GitHub-only in v1.** A repository `gh` cannot resolve to a GitHub host, or a commit with no run on the base branch, is `inconclusive`: reported, never escalated.
+- **A run still in flight is not a verdict.** The wait window belongs to the check; the wait past it belongs to the harness, and the stage playbook's _Watch transport_ section is the single place the per-harness mechanism is named. A session with no watcher runs the check once with a longer window instead — that fallback is prose, so it survives both renders.
+- **Ordering against housekeeping.** The two stages are siblings on the gate and neither waits on the other. Chaining `housekeeping` behind `post-merge` was rejected: an inconclusive check that nobody resolves would 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.
+
+---
+
 ## Pruning Worktrees
 
 A worktree outlives its bead: ralph leaves the directory behind when a feature closes, and a crashed run leaves one with no bead at all. `skills/workflow/ralph/scripts/prune-worktrees.mjs` converges `.agent-cortex/worktrees/*` with bead state.
@@ -250,7 +270,7 @@ 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 **and** the pre-created `stage:housekeeping` chore. 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:post-merge` and `stage:housekeeping` chores. After that, close the parent feature bead:
    ```bash
    bd close <parent-id>
    ```
@@ -300,24 +320,32 @@ Ralph never builds remediation. The worker that fails a stage creates its own `s
 
 ---
 
-## Log Polling
+## Reading the Trail
 
-Run whenever completion handling is triggered (an agent completion):
+Ralph never tails a file. The worker writes its own bead trail at each transition through
+`skills/workflow/run-pipeline-stage/scripts/trail-entry.mjs`, so progress is read from the bead:
 
-1. **Read in-flight entries**: `inflight` in `.agent-cortex/ralph/state.json` — every dispatched worker: stage (`kind: "stage"`), decomposition (`kind: "decompose"`) or expansion (`kind: "expand"`). Each entry carries `parentId` and `logLine`.
-2. For each in-flight entry, read new lines from its **parent's** log file — logs are keyed by **parent** bead ID, so all stages of a feature share one file:
-   ```bash
-   tail -n +<logLine> .agent-cortex/ralph/ralph-<parentId>.log 2>/dev/null
-   ```
-3. For each entry that has new lines:
-   - **Post a chat summary** of new key events (stage transitions and notable events — not every line verbatim):
-     ```
-     📋 [parent-id] <title>
-        coding → verifying  (or whatever transition)
-        Tests: 12 passed, 0 failed
-     ```
-   - Update `logLine` in `state.json` for that entry.
-4. If no entry had new lines, post nothing — do not spam the chat with empty polls.
+```bash
+node <run-pipeline-stage-scripts>/recover-brief.mjs --bead <chore-id>  # status, newest entries, refs, blockers, acceptance — bounded
+bd show <chore-id>              # every checkpoint entry: Outcome, Evidence, What is left
+bd provenance log <chore-id>    # the refs it recorded: git-sha, branch, pr, work-id
+bd children <parent-id>         # the whole chain's state, closed included
+```
+
+The brief is the first read: `bd show` returns 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 — and Ralph reads the tail, not the
+history. Widen the brief's window (`--trail`) only when it left out the entry you need.
+
+There is nothing to flush and no bookmark to keep in `state.json`: the record the orchestrator used
+to poll is now the record the worker writes directly, so the per-parent log file and the line
+counter that fed its tail are gone. On each completion:
+
+1. **Read the completed worker's bead**: `bd show <chore-id>` for its entries, and
+   `bd provenance log <chore-id>` for the commit, branch and PR it recorded.
+2. **Post a chat summary** of what is new since the last report for that bead — the stage
+   transition, the test and lint results, and the close reason. Not the entries verbatim.
+3. **Post nothing when nothing new arrived** — do not spam the chat with empty polls.
 
 ---
 
@@ -389,6 +417,76 @@ When nothing is in flight AND nothing is dispatchable — `inflight` holds no en
 
 ---
 
+## Peer messaging (planner ↔ ralph)
+
+The planner session (`plan` skill) and ralph are separate sessions with no shared terminal. Delivery, discovery, idle wake and the message ledger all belong to the harness's own messaging mechanism — the published **pi-peer** package on PI, a built-in facility on Claude Code. **Never build a registry, inbox, watcher or transport in its place** — this section defines only the message vocabulary and the reply rule that sit on top of it, and it is the single place both skills read.
+
+### Transport
+
+Send with {{TOOL:peer_send}}; list the peers you can reach with {{TOOL:peer_list}}, and address a peer only by the name or address that list reports. Where the mechanism provides a per-message intent, an idle subscription or a reply wait, use it — but never make a send depend on one.
+
+Send from a scripted call, **never** by typing text into a busy terminal session: during the `pi-peer` package's adoption spike, stray keystrokes aimed at a running session were queued as user prompts twice, so the receiving agent read them as new instructions.
+
+A send does not prove receipt. An inbound message may be held for approval before the receiving agent sees it, and delivery stays unconfirmed until the receiver answers.
+
+The mechanism is supplied by the harness, and neither harness is forced into the other's: a PI session takes it from the `pi-peer` package runbook below, and a Claude Code session has it built in. **Only this subsection differs between the two installs** — the message kinds and the acknowledgement rule that follow are the same bytes on both, so a message means the same thing whichever mechanism carries it.
+
+### The `pi-peer` package (PI)
+
+A PI session gets its transport from this package, which a consuming repository installs itself — it is never a dependency of this package. Its `peer_get` and `peer_await` tools have no Claude Code counterpart, so they are named here and nowhere else in this convention.
+
+#### Adoption in a consuming repository
+
+1. **Install once per repository:** `pi install npm:@cryptolibertus/pi-peer`.
+2. **List both roles** in `.pi/peers.json`: `planner` and `ralph`. The peer list is configuration, so both entries are required — see _Discovery is two-way only when both roles are listed_ below.
+3. **Start each session with its own identity:** `PI_PEER_ID=planner pi` for the planning session, `PI_PEER_ID=ralph pi` for ralph. The file holds a default `localPeerId`, and `PI_PEER_ID` overrides it for the session. Confirm with `peer_list` — it reports `1 online - <peer id>` when discovery works.
+4. **Send and read with the package's own tools:** `peer_send` (or `/peer send <id> "<text>" --intent <intent> --no-await`), `peer_list`, `peer_get` for a peer's current state and `peer_await` for a reply.
+5. **Ignore the state files** the package writes — see _Files a consuming repository gains_ below.
+
+#### Discovery is two-way only when both roles are listed
+
+`.pi/peers.json` is a **static peer list, not a live registry**: the runtime merges `.pi/settings.json`, `.pi/peers.json` and the `PI_PEER_*` environment, then polls only the peers the file names. `/peer setup` never overwrites an existing `.pi/peers.json`, so a setup run in the second session leaves the file alone.
+
+A single-entry file therefore makes discovery one-way: the listed peer sees the other as online, while the unlisted peer reports `no peers` and its sends write no message record. That is configuration, not a fault. The missing step is `/peer setup --peer <peer-id>`, which adds a trusted peer to the existing file. Two entries plus `PI_PEER_ID` per session is the whole setup — and because a send is not proof of receipt, a message stays unverified until the receiver answers.
+
+#### Files a consuming repository gains
+
+| File | Purpose | Tracked? |
+|------|---------|----------|
+| `.pi/peers.json` | the peer list plus the default `localPeerId` that `PI_PEER_ID` overrides | no |
+| `.pi/peer-messages.json` | message records with source, target, status and conversation id | no |
+| `.pi/peer-control-ledger.jsonl` | the control ledger | no |
+
+All three are machine state, not tracked content. Tell the consuming repository to gitignore them: ignore `.pi/peers.json` **and** `.pi/peer-*` together. The literal path covers the peer list, which the glob does not match, and the glob covers the message and ledger files plus any further `peer-*.json` the package adds.
+
+### Message kinds
+
+The kinds map **onto** the transport's own intents where it has them (PI's `pi-peer`: `ask`, `review`, `notify`, `coordinate`, `task`); they never replace or re-implement the transport protocol.
+
+| Kind | Carries | Maps to intent | Direction |
+|------|---------|----------------|-----------|
+| `handoff` | bead id + one-line scope | `task` | planner → ralph |
+| `done` | bead id + run summary | `notify` | ralph → planner |
+| `blocked` | gate bead id awaiting a human | `notify` | ralph → planner |
+| `failed` | bead id + reason | `notify` | ralph → planner |
+| `update` | bead id + stage progress | `notify` | ralph → planner |
+| `get` | peer id, asks for current state | `coordinate` | either → either |
+| `ask` | question text, needs an answer | `ask` | either → either |
+
+Write the kind as the first word of the message text, e.g. `handoff agnt-ctx-abc.1 — implement the retry budget`.
+
+### Acknowledgement rule
+
+Statuses stay `running` or `queued` until the receiver answers, so **a sender cannot tell "delivered" from "done"**. Every inbound `handoff`, `get` and `ask` must be answered with exactly one of three reply kinds:
+
+- `done` — carried out; name the bead id and give a one-line result (for `get`, the requested state).
+- `blocked` — cannot proceed; name the gate bead that is waiting for a human.
+- `failed` — could not be carried out; name the bead and the reason.
+
+`update`, `done`, `blocked` and `failed` are reports, so they need no reply. Never leave a `handoff`, `get` or `ask` unanswered — reply that it is queued rather than staying silent.
+
+---
+
 ## State Files
 
 Status is read from beads — there is no rendered status document to build or refresh:
@@ -401,8 +499,7 @@ bd show <id>                   # full detail, including the worker's notes
 
 | File | Purpose |
 |------|---------|
-| `.agent-cortex/ralph/state.json` | Runtime bookkeeping only: the in-flight agent-ID→bead mapping. Shape: `{ "inflight": [ { "kind": "stage", "choreId": "...", "parentId": "...", "title": "...", "agentId": "...", "logLine": 1 } ] }`. A decomposition worker is recorded with `"kind": "decompose"` and an expansion worker with `"kind": "expand"`, both with `"choreId": null` — they hold no chore but still occupy the wait set and the in-flight check. Initialise at startup with `{ "inflight": [] }`. Update after every dispatch and every agent completion. **Never hand-edit.** |
-| `.agent-cortex/ralph/ralph-*.log` | Per-parent log files written by subagents — every stage chore of a feature appends to `.agent-cortex/ralph/ralph-<parent-id>.log` (e.g. `ralph-abc-123.log`). |
+| `.agent-cortex/ralph/state.json` | Runtime bookkeeping only: the in-flight agent-ID→bead mapping. Shape: `{ "inflight": [ { "kind": "stage", "choreId": "...", "parentId": "...", "title": "...", "agentId": "..." } ] }`. A decomposition worker is recorded with `"kind": "decompose"` and an expansion worker with `"kind": "expand"`, both with `"choreId": null` — they hold no chore but still occupy the wait set and the in-flight check. Initialise at startup with `{ "inflight": [] }`. Update after every dispatch and every agent completion. **Never hand-edit.** |
 
 All task state is derived from beads; `state.json` holds only runtime bookkeeping: