@jaybeeuu/agent-cortex 2.1.0 → 2.2.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) via its playbook and dispatch rules, 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) via its playbook and read-only routing, reporting the outcome in a fixed REPORT shape. Use when you want to "work through beads inline", "pick up a specific stage bead", or run one stage "without the full ralph orchestrator".
 ---
 
 # Run Pipeline Stage
 
-Stage beads (`stage:code`, `stage:verify`, `stage:review`, `stage:document`, `stage:fix`) are created by the `create-task` skill from the pipeline definition in `skills/planning/create-task/pipeline.json`. This skill executes one stage at a time and reports the outcome.
+Stage beads (`stage:code`, `stage:verify`, `stage:review`, `stage:document`, `stage:fix`) come from the pipeline definition in `skills/planning/create-task/pipeline.json`. This skill executes one stage and owns that bead's lifecycle: the runner that does the work appends its own notes, closes its own leaf execution bead on **both** outcomes, and builds its own remediation children when the stage fails. The orchestrator dispatches and routes — it never edits or closes a leaf bead.
 
 ## When to use
 
@@ -20,65 +20,66 @@ Stage beads (`stage:code`, `stage:verify`, `stage:review`, `stage:document`, `st
 - Creating or planning beads — use `create-task` or `plan`.
 - Exploratory bead bookkeeping without a stage — that is `bd-tool`.
 
+## Ownership split
+
+| Actor | Owns |
+|---|---|
+| Stage runner (worker) | Milestone notes, progress-log lines, closing its leaf bead on both outcomes, 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.
+
 ## Workflow
 
 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_).
 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`), populate `<stage>`, and read the matching playbook (`skills/workflow/run-pipeline-stage/playbooks/<stage>.md`) for stage-specific rules.
-6. Tag the stage and regenerate the progress doc so pairing sessions stay current:
+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:
 
 ```bash
 bd tag <id> stage:<stage>
-# workspace must be the absolute path of the worktree — never . or $(pwd)
-workspace="/absolute/path/to/worktree"
-pnpm --prefix skills/workflow/run-pipeline-stage/scripts exec tsx generate-progress.ts --workspace "$workspace" > "$workspace/.agent-cortex/ralph/progress.md"
 ```
 
-7. Dispatch one subagent per stage with the composed prompt — spawn it with {{TOOL:task}} and end the prompt with the REPORT contract below. A session with no subagent tool cannot dispatch: stop and say so rather than substituting a backgrounded CLI run, which has no completion signal.
+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.
-9. Route the REPORT through the Dispatch Rules: advance to the next stage, create a feedback bead, or close the parent.
+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, a regenerated progress doc, a verified commit, and a REPORT that drives the next action.
+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.
 
-## Dispatch Rules
+## Routing (read-only)
 
-| Stage complete | Condition | Next action |
-|---|---|---|
-| `code` | — | Run **verify** |
-| `verify` | `OUTCOME: SUCCESS` | Run **review** |
-| `verify` | `OUTCOME: BLOCKED` | Create a `stage:fix` chore (see _Feedback Beads_) |
-| `review` | `OUTCOME: SUCCESS` | Run **document** |
-| `review` | `OUTCOME: BLOCKED` and fixRounds < maxFixRounds | Create a `stage:fix` chore; increment fixRounds |
-| `review` | `OUTCOME: BLOCKED` and fixRounds ≥ maxFixRounds | `bd update <parent-id> --status blocked --notes "max fix rounds reached"`; record for shutdown |
-| `document` | — | `bd close <id>` — done |
-
-`maxFixRounds` is read from `skills/planning/create-task/pipeline.json` (currently `4`). A fix chore re-runs the stage that failed — fix after verify → verify; fix after review → review.
+The worker built anything this stage needed; routing picks up whatever `bd ready` returns.
 
-## Feedback Beads
+| Stage complete | Condition | Next action |
+| `code` | `OUTCOME: SUCCESS` | Dispatch the ready `stage:verify` chore |
+| `verify` | `OUTCOME: SUCCESS` | Dispatch the ready `stage:review` chore |
+| `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 |
+| `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 |
+| any | parent status `blocked` | Nothing — the worker or the cap backstop blocked it; record it for shutdown |
 
-On stage failure, create a chore bead whose description carries the feedback so the orchestrator's dispatch path stays uniform — it just picks up whatever `bd ready` returns:
+Cap backstop (read-only): before dispatching a `stage:*` chore, count the parent's fix rounds and, if already at `maxFixRounds` (`skills/planning/create-task/pipeline.json`, currently `4`), block the parent and create nothing:
 
 ```bash
-new_id=$(bd create "[<parent-id>] <title>" --type chore \
-  --description "Requirements: see <parent-id> acceptance criteria (`bd show <parent-id>`).
-
-<feedback content from REPORT>" --priority <parent-priority> -q)
-bd tag $new_id stage:<next-stage>
-bd tag $new_id workflow:ralph
-bd dep add $new_id <parent-id> --type parent-child
+fix_rounds=$(bd children <parent-id> --json | grep -c '"stage:fix"')
 ```
 
-Chore beads carry no required sections, so the feedback description must point at the
-parent/requirements bead (`<parent-id>`) rather than restating its acceptance criteria.
+## Remediation Children (worker-built)
+
+On `OUTCOME: BLOCKED` the worker creates its own chain — a `stage:fix` chore carrying the feedback, plus a **fresh instance of the stage that failed**, blocked on the fix. A fresh instance is not optional: the failed chore is already closed, so the pre-created chain cannot re-verify a fix.
 
-| Triggering outcome | Suggested title | Next stage tag | Description content |
-|---|---|---|---|
-| `OUTCOME: BLOCKED` from verify | `Fix: verify failures` | `stage:code` | Full BLOCKING_ISSUES list |
-| `OUTCOME: BLOCKED` from review | `Fix: reviewer feedback` | `stage:fix` | Full BLOCKING_ISSUES list |
+| Failed stage | Chain |
+|---|---|
+| `code` | `stage:fix` → fresh `stage:code` |
+| `verify` | `stage:fix` → fresh `stage:verify` |
+| `review` | `stage:fix` → fresh `stage:review` |
+| `document` | `stage:fix` → fresh `stage:document` |
+| `fix` | `stage:fix` → fresh `stage:fix` |
 
-Do not dispatch a new agent right after creating the feedback bead — it appears in `bd ready` on the next cycle and flows through the normal scheduling path.
+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
 
@@ -106,23 +107,21 @@ bd update <id> --append-notes "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [<stage>] <what
 
 ## Report Format
 
-Every subagent prompt must end with the REPORT instruction:
-
-> End your response with a `---REPORT---` block in exactly this format:
-> ```
-> ---REPORT---
-> BEAD_ID: <id>
-> STAGE_COMPLETED: <code|verify|review|document>
-> SUMMARY: <2-3 sentence summary of what was done>
-> FILES_CHANGED: <comma-separated list, or "none">
-> COMMIT: <sha of the stage commit, or "none">
-> PUSHED: <yes|no>
-> PR: <feature PR url, or "none">
-> OUTCOME: <SUCCESS|BLOCKED>
-> BLOCKING_ISSUES:                              ← only if OUTCOME is BLOCKED
-> - <specific blocking issue>
-> ---
-> ```
+Every stage-runner prompt ends with the literal REPORT instruction (see `prompts/stage-runner.md`):
+
+```
+---REPORT---
+BEAD_ID: <id>
+STAGE_COMPLETED: <code|verify|review|document|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">
+PUSHED: <yes|no>
+PR: <feature PR url, or "none">
+OUTCOME: <SUCCESS|BLOCKED>
+BLOCKING_ISSUES:                              ← only if OUTCOME is BLOCKED
+- <specific blocking issue>
+```
 
 Subagents report facts — do not ask them to suggest or predict the next step. A REPORT claiming
 `OUTCOME: SUCCESS` with `PUSHED: no`, or a `COMMIT` that is not on the branch, records a failed
@@ -131,8 +130,9 @@ stage: the commit is the evidence, the report is the claim.
 ## Red Flags
 
 - Dispatching a subagent before tagging the stage — beads are the only source of truth for stage progress.
+- Closing a leaf bead from the orchestrator — the worker closed it; a second close hides who owned the outcome.
+- Creating a feedback or fix bead from the orchestrator — that is the worker's contract and bypasses its cap accounting.
 - Composing a subagent prompt without the REPORT contract — the output cannot be routed.
-- Creating a feedback bead and then dispatching anyway — bypasses the fix-round accounting and parent-child dependency graph.
 - Skipping the playbook "because the stage is simple" — playbooks carry the per-stage discipline the pipeline relies on.
 - Advancing on `OUTCOME: SUCCESS` without verifying the worktree — the commit is the evidence, the report is the claim.
 - Leaving bead notes to the end of the stage — a session that dies mid-stage then loses the whole trail.
@@ -140,34 +140,35 @@ stage: the commit is the evidence, the report is the claim.
 ## Common Rationalizations
 
 | "The stage is small — I'll just run it directly" | The stage skills and playbook keep output conformant; skipping them produces work that loops back as a fix chore. |
-| "I'll dispatch the fix right away — faster than a chore bead" | Feedback beads keep dispatch uniform and durable; direct re-dispatch breaks fix-round accounting and the dependency graph. |
-| "The stage is obvious from the prompt — no tag needed" | Beads are the source of truth; prompt drift desynchronises the progress doc, the log, and downstream dispatch. |
+| "I'll close the chore — the worker forgot" | The worker closing it is the contract; an unclosed bead means the worker died, so read its notes and re-dispatch, do not paper over it. |
+| "I'll wire the fix chain myself — faster" | Two owners of one lifecycle is what this skill exists to remove; worker-built chains keep cap accounting and the dependency graph truthful. |
+| "The stage is obvious from the prompt — no tag needed" | Beads are the source of truth; prompt drift desynchronises the log and downstream dispatch. |
+
+## See Also
 
-## Cross-skill references
+- [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.
 
-- `create-task` owns `pipeline.json` — stages, `maxFixRounds`, and the stage templates.
-- `bd-tool` covers bead mechanics beyond the commands in this skill.
-- `ralph` runs many stage beads concurrently and consumes this skill's log and REPORT contracts.
-- Playbooks delegate to stage skills: `tdd`/`style-code`/`style-tests` (code), `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).
 
 ## Examples
 
-- Input: a `stage:verify` bead reporting `OUTCOME: BLOCKED` with two failing tests → Output: a `Fix: verify failures` chore tagged `stage:code` whose description lists both failures; verify closes and the chore is picked up on the next `bd ready` cycle.
-- Input: a `stage:document` bead reporting `OUTCOME: SUCCESS` → Output: the parent bead is closed with `bd close <id>` and that task's pipeline ends.
+- Input: a `stage:verify` runner reporting `OUTCOME: BLOCKED` with two failing tests → Output: a `Fix (round 1)` chore plus a fresh `Verify (re-run 1)` chore blocked on it, `review` re-blocked behind the fresh verify, verify's own bead closed, and one `---REPORT---` block.
+- Input: a `stage:document` runner reporting `OUTCOME: SUCCESS` → Output: document's bead already closed by the runner; the orchestrator opens the feature PR and updates the HITL gate bead.
 
 ## Philosophy / rationale
 
 - Beads hold all orchestration state — there is no separate state file to drift out of sync.
-- Subagents return facts in one fixed REPORT shape so routing stays mechanical across stages and harnesses.
-- Feedback as beads, not direct re-dispatches, puts every agent on a single scheduling path and keeps every decision visible in the dependency graph.
+- Whoever does the work owns the record: a worker that closes its own bead leaves an auditable trail the orchestrator can only read.
+- Self-contained remediation keeps the dependency graph truthful, so `bd ready` alone is enough to schedule the next step.
 
 ## Verification checklist
 
 - [ ] Bead claimed (`bd update <id> --claim`) before any executor works it.
-- [ ] `bd tag <id> stage:<stage>` run and progress doc regenerated before dispatch.
+- [ ] `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 ends with the complete REPORT contract block.
+- [ ] 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`).
-- [ ] REPORT routed per the Dispatch Rules — next stage, feedback bead, or `bd close <id>`.
-- [ ] Feedback beads carry the full BLOCKING_ISSUES content and the parent-child dependency.
+- [ ] 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

@@ -16,4 +16,15 @@
 - Set `OUTCOME: BLOCKED` if tests fail or requirements cannot be met.
 - If blocked, list issues under `BLOCKING_ISSUES`.
 - `FILES_CHANGED` lists all modified source/test files.
+
+## 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`).
+- `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
+  `stage:fix` chore **plus a fresh `stage:code` chore** blocked on it (`bd dep add <fresh>
+  <fix> --type blocks`), and re-block later stages behind the fresh bead. At cap, block the
+  parent and create nothing.
 - Report `COMMIT`, `PUSHED`, and `PR` (`PR: none` outside the document stage).

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

@@ -18,4 +18,16 @@
 - Set `OUTCOME: BLOCKED` if unable to update or content guidance is unclear.
 - If blocked, list issues under `BLOCKING_ISSUES`.
 - `FILES_CHANGED` lists docs touched, or `none` if no doc change is needed.
+
+## 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`).
+- `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
+  `maxFixRounds` in `skills/planning/create-task/pipeline.json`. Under cap, create a
+  `stage:fix` chore **plus a fresh `stage:document` chore** blocked on it
+  (`bd dep add <fresh> <fix> --type blocks`) so documentation is retried after the fix. At cap,
+  block the parent and create nothing.
 - Report `COMMIT`, `PUSHED`, and the feature `PR` URL.

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

@@ -16,4 +16,16 @@
 - Set `OUTCOME: BLOCKED` if unable to apply changes or guidance is unclear.
 - If blocked, list issues under `BLOCKING_ISSUES`.
 - `FILES_CHANGED` lists files updated to address requested changes.
+
+## 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`).
+- `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
+  `maxFixRounds` in `skills/planning/create-task/pipeline.json`. Under cap, create another
+  `stage:fix` chore carrying what remains **plus a fresh `stage:fix` chore** blocked on it
+  (`bd dep add <fresh> <fix> --type blocks`) and leave the downstream re-run chore blocked on
+  the fresh fix. At cap, block the parent and create nothing.
 - Report `COMMIT`, `PUSHED`, and `PR` (`PR: none`).

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

@@ -17,3 +17,14 @@
 - Set `OUTCOME: BLOCKED` if changes are requested.
 - If blocked, enumerate required changes under `BLOCKING_ISSUES`.
 - `FILES_CHANGED` should be `none`.
+
+## 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`).
+- `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
+  `stage:fix` chore carrying the full `BLOCKING_ISSUES` list **plus a fresh `stage:review`
+  chore** blocked on it (`bd dep add <fresh> <fix> --type blocks`), and re-block `document`
+  behind the fresh bead. At cap, block the parent and create nothing.

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

@@ -12,3 +12,16 @@
 - Set `OUTCOME: BLOCKED` when any command fails.
 - If blocked, summarize failures under `BLOCKING_ISSUES`.
 - `FILES_CHANGED` should be `none`.
+
+## 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 —
+  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
+  `maxFixRounds` in `skills/planning/create-task/pipeline.json`. Under cap, create a
+  `stage:fix` chore carrying the failure list **plus a fresh `stage:verify` chore** blocked on
+  it (`bd dep add <fresh> <fix> --type blocks`) — the chore you are closing can never verify
+  the fix — and re-block `review` behind the fresh bead. At cap, block the parent and create
+  nothing.

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

@@ -4,6 +4,8 @@ Run `bd prime` if you need project-level context (conventions, tech stack, goals
 ## Stage metadata
 - Stage: `<stage>`
 - Playbook: `skills/workflow/run-pipeline-stage/playbooks/<stage>.md`
+- Leaf execution bead: `<bead-id>` — **you own its lifecycle**. No orchestrator,
+  dispatcher, or parent agent writes to it or closes it.
 
 ## Bead specification
 <bd show <id> output — verbatim>
@@ -24,7 +26,57 @@ bd update <id> --append-notes "[<ISO-timestamp>] [<stage>] <what changed / what'
 
 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. The REPORT below remains the authoritative stage outcome.
+not a transcript.
+
+## Leaf bead lifecycle (yours to close)
+
+1. **Chain before close.** Build remediation children (below) *before* you close the bead, so
+   the parent never shows a later stage as ready while remediation is outstanding.
+2. **Close on both outcomes** — success and failure alike:
+   ```bash
+   bd close <bead-id> --reason="<SUCCESS|BLOCKED>: <one-line outcome>"
+   ```
+   The outcome lives in the close reason, the milestone notes, and the REPORT. A closed bead
+   with a `BLOCKED` reason is a completed stage, not abandoned work.
+3. **Do not create the next stage on success.** Routing forward is the orchestrator's job.
+
+## Remediation (only when your outcome is BLOCKED)
+
+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
+   the parent's existing fix rounds (closed ones count):
+   ```bash
+   fix_rounds=$(bd children <parent-id> --json | grep -c '"stage:fix"')
+   ```
+2. **At cap** (`fix_rounds >= maxFixRounds`): create **nothing**. Block the parent and record why:
+   ```bash
+   bd update <parent-id> --status blocked \
+     --append-notes "[<ISO-timestamp>] max fix rounds reached (<fix_rounds>/<maxFixRounds>) after <stage> BLOCKED"
+   ```
+   Then close your own bead and report `OUTCOME: BLOCKED`.
+3. **Under cap**: create the fix chore plus the fresh stage, then wire the ordering.
+   `--parent` sets the parent-child dep and inherits the parent's labels.
+   ```bash
+   fix_id=$(bd create "[<parent-id>] Fix (round <fix_rounds + 1>)" \
+     --type chore --priority <parent-priority> --parent <parent-id> \
+     --labels stage:fix \
+     --description "Requirements: see <parent-id> (bd show <parent-id>).
+
+<BLOCKING_ISSUES from your run>" --silent)
+   fresh_id=$(bd create "[<parent-id>] <Stage title> (re-run <fix_rounds + 1>)" \
+     --type chore --priority <parent-priority> --parent <parent-id> \
+     --labels stage:<stage> \
+     --description "<this stage's description from pipeline.json>" --silent)
+   bd dep add $fresh_id $fix_id --type blocks        # fresh stage waits for the fix
+   ```
+4. **Re-block the later stages.** Any not-yet-run stage chore of the same parent is already
+   unblocked by your bead closing. Wire each one behind the fresh stage:
+   ```bash
+   bd dep add <downstream-chore-id> $fresh_id --type blocks
+   ```
+   Skip stages that already ran (closed) and the HITL PR gate bead.
+5. Do **not** dispatch anything yourself — the new beads flow through `bd ready`.
 
 ## Deliver before reporting
 
@@ -41,3 +93,23 @@ dirty worktree counts as a failed stage whatever the outcome line claims.
 1. Read and follow the playbook file listed above.
 2. Treat the bead as the source-of-truth specification (not a prompt script).
 3. Keep output factual and stage-scoped.
+
+## Report
+
+End your response with a `---REPORT---` block in exactly this format:
+
+```
+---REPORT---
+BEAD_ID: <id>
+STAGE_COMPLETED: <code|verify|review|document|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">
+PUSHED: <yes|no>
+PR: <feature PR url, or "none">
+OUTCOME: <SUCCESS|BLOCKED>
+BLOCKING_ISSUES:                              <- only if OUTCOME is BLOCKED
+- <specific blocking issue>
+```
+
+Report facts only — do not suggest or predict the next step.

package/token-map.README.md

@@ -62,10 +62,15 @@ rather than inventing a dotted form:
   actually runs from. A literal home path in substituted files would break under
   cache-copy, so the installer passes the env form through verbatim.
 - **`agents`** — the `agent-cortex:` name-prefix convention per harness (claude strips the
-  prefix during conversion) and the deferred-agent exception (claude's `ralph` is authored
-  natively, never generated). Agent names themselves do not get per-row mappings because
-  the prefix rule covers all of them; the deferred list captures the only structural
-  difference.
+  prefix during conversion). Agent names themselves do not get per-row mappings because
+  the prefix rule covers all of them — every agent is composed from `agents/<name>/` for
+  every harness, so there is no structural exception to record.
+- **`wake`** — the completion mechanism per harness (`pi`: blocking-wait,
+  `claude`: event-driven). Informational only — no installer substitutes a
+  token from it. It records the fact that the shared ralph body deliberately does not
+  state, so `{{SECTION:wake}}` → `agents/ralph/<harness>/wake.md` is the single place
+  harness specifics live, and the mechanism stays checkable instead of being inferred from
+  prose. `agents/README.md` carries the same table for humans.
 - **Deliberately not mapped:** hook patterns, MCP servers, and tool descriptions. Those
   differ *structurally* per harness (different hook event names, different config files),
   not by a single substitutable token; each installer already hardcodes its own shape. The

package/token-map.json

@@ -46,12 +46,20 @@
       "claude": "",
       "pi": "agent-cortex:"
     },
-    "deferred": {
-      "ralph": ["claude"]
-    },
     "sources": {
       "pi": "agents/<name>/ composable dirs (canonical) — composed at runtime by the agent-modes extension",
-      "claude": "agents/<name>/ composable dirs (canonical) — composed by bin/installers/claude.mjs (install-time generator, the only generator — the generated claude/ plugin subtree is not committed), plus agents-native/*.md for deferred agents"
+      "claude": "agents/<name>/ composable dirs (canonical) — composed by bin/installers/claude.mjs (install-time generator, the only generator — the generated claude/ plugin subtree is not committed)"
+    }
+  },
+  "wake": {
+    "description": "How each harness tells ralph that a background worker finished. `{{SECTION:wake}}` in agents/ralph/agent.md resolves to agents/ralph/<harness>/wake.md; this table is the machine-readable form of the same fact, so the mechanism is recorded rather than inferred from prose (see the wake table in agents/README.md).",
+    "mechanism": {
+      "pi": "blocking-wait",
+      "claude": "event-driven"
+    },
+    "notes": {
+      "pi": "Blocking wait: wait_for_agents returns as soon as one worker finishes, carrying its result inline. No timer to start, nothing to kill — there is no poll loop.",
+      "claude": "Event-driven: the harness re-invokes ralph when a worker completes and delivers the result inline. No poll timer, no sleep, no log flush."
     }
   },
   "notes": {
@@ -70,8 +78,7 @@
       "claude": "plugin_root stays ${CLAUDE_PLUGIN_ROOT} (env var) for the materialised plugin — never a literal ~/.agent-cortex/claude. Claude Code copies marketplace-installed plugins (including local directory sources like ~/.agent-cortex/claude) into its own cache and expands the env var per context, so a literal home path in substituted files would break under cache-copy; the installer passes the env form through verbatim."
     },
     "agents": {
-      "prefix": "Claude strips the agent-cortex: name prefix during conversion (NAME_PREFIX in bin/installers/claude.mjs): pi agents are agent-cortex:<slug>, claude agents are <slug>.",
-      "deferred": "ralph has no generated claude counterpart — it is authored natively as agents-native/ralph.md (its event-driven orchestration cannot be produced by section composition from the polling pi source)."
+      "prefix": "Claude strips the agent-cortex: name prefix during conversion (NAME_PREFIX in bin/installers/claude.mjs): pi agents are agent-cortex:<slug>, claude agents are <slug>."
     }
   },
   "contract": {

package/.agents/skills/style-versioning/SKILL.md

@@ -1,172 +0,0 @@
----
-name: style-versioning
-description: Automated release workflow using changesets. Use when completing work that needs a release, asking "how do I version this?", or when any change needs to be shipped to npm.
----
-
-# style-versioning
-
-This repo uses **changesets** for fully automated versioning and publishing. No manual version bumps, no manual releases.
-
-## When to use
-
-Trigger this skill when:
-- Completing work that needs a release
-- Asking "how do I version this change?"
-- Creating a PR that changes shipped behaviour
-
-## Creating a changeset (agent instructions)
-
-**Do NOT run `pnpm changeset`** — it is interactive and will waste tokens on prompts and ANSI codes. Instead, write the changeset file directly.
-
-### File format
-
-A changeset is a markdown file in `.changeset/` with YAML frontmatter:
-
-```markdown
----
-"@jaybeeuu/agent-cortex": <bump>
----
-
-<Short description of the change>
-```
-
-Where `<bump>` is one of: `patch`, `minor`, or `major`.
-
-### How to create one
-
-1. Choose a descriptive kebab-case filename (e.g., `fix-status-bug.md`, `add-webhook-skill.md`)
-2. Choose the bump type:
-   - `patch` — bug fix, clarification, no behaviour change
-   - `minor` — new skill, agent, feature, or meaningful behaviour change
-   - `major` — breaking change (removed skill, renamed agent, incompatible workflow)
-3. Write the file directly using the `write` tool:
-
-```
-write(".changeset/fix-status-bug.md", `---
-"@jaybeeuu/agent-cortex": patch
----
-
-Fix status bead showing wrong priority after update
-`)
-```
-
-4. Commit the changeset file along with the code changes
-
-### Rules
-
-- **Every PR adds a changeset.** CI fails otherwise. The only opt-out is the
-  `no-publish` label (see below).
-- The frontmatter package name must match exactly: `"@jaybeeuu/agent-cortex"`
-- The description should be one or two sentences, user-facing (it goes into CHANGELOG.md)
-- One changeset per PR. If a PR has multiple unrelated changes, use multiple changeset files.
-- The filename doesn't matter to changesets — only the frontmatter and description do.
-
-## The PR gate
-
-`changeset-check` runs on every pull request and fails it unless the PR adds a
-`.changeset/*.md` file. **Publishing is the default; `no-publish` is the only
-opt-out** — skipping a release is an explicit, reviewable decision, never an accident.
-
-| Exemption | Applies to |
-|---|---|
-| `changeset-release/*` head branch, or actor `github-actions[bot]` | the changesets bot's Version Packages PR — it consumes changesets and adds none of its own |
-| `no-publish` label | a PR that genuinely ships nothing |
-
-The `no-publish` label must exist in the repository's label settings — a one-off
-human step (`gh label create no-publish`), not something a PR can ship. If the gate
-fails and the PR really ships nothing, ask for the label; do not manufacture a
-changeset to make it green.
-
-## After merge to main
-
-The `release` job in `.github/workflows/ci.yml` handles everything automatically:
-
-1. **Detects new changesets** on main
-2. **Creates a "Version Packages" PR** — the `version` step runs `pnpm version-packages` (`changeset version`), which bumps `package.json` and rewrites `CHANGELOG.md`. That is the whole release surface: every plugin this package ships is materialised at install time with the package version, so there is no generated output to regenerate and no drift gates to satisfy on a version bump
-3. **When "Version Packages" is merged**:
-   - Creates a git tag
-   - Publishes to npm — `pnpm publish-package` packs with `pnpm pack` and publishes with `npm publish --provenance --access public`. Authenticates via npm Trusted Publishing (OIDC): the release job's `id-token` permission lets npm exchange a GitHub OIDC token for a short-lived npm token at publish time, so no `NPM_TOKEN` secret or `.npmrc` auth config is required — only the one-time npm-side Trusted Publishing setup on npmjs.com (package → Access → Trusted Publishing → GitHub repo `jaybeeuu/agent-cortex` + workflow `.github/workflows/ci.yml`)
-   - Creates a GitHub release automatically
-
-`changesets/action` execs the `version`/`publish` inputs without a shell, so each
-must be a single unquoted command token — keep release logic in pnpm scripts
-(`version-packages`, `publish-package`, `publish-noop`), never inline shell strings.
-
-### Approve CI on the Version Packages PR
-
-The version PR arrives `BLOCKED` with an empty check list, and nothing is broken:
-`changesets/action` pushes that branch with `GITHUB_TOKEN`, so GitHub parks the CI
-run the push creates behind **“Approve workflows to run”** (`action_required`, zero
-jobs). A parked run reports no checks, so the five required contexts are
-unsatisfiable until someone approves it. Approve it from the PR's merge box, or:
-
-```bash
-run=$(gh run list --branch changeset-release/main --limit 20 \
-  --json databaseId,conclusion --jq 'map(select(.conclusion=="action_required"))[0].databaseId')
-gh api -X POST "repos/{owner}/{repo}/actions/runs/$run/approve"
-```
-
-An approval is per head commit. Every merge to `main` force-updates the version
-branch and starts a fresh parked run, so approve immediately before merging the
-version PR — not once per release. Do not reach for a PAT or GitHub App token to
-skip this: one click is cheaper than a long-lived credential in repository
-secrets, and the `GITHUB_TOKEN` the job already holds cannot approve its own run.
-
-Which of the two publish scripts runs is decided per push, not hard-coded: labels are
-invisible on a push event, so the job resolves the PR merged for the pushed commit via
-the GitHub API and reads its labels — `publish-noop` when the PR carried `no-publish`,
-`publish-package` otherwise. That needs no new secret or scope; the job already holds
-`GITHUB_TOKEN` and `pull-requests: write`. A direct push with no merged PR resolves to
-no labels and so publishes, which keeps a genuine publish of an already-published
-version failing loudly — there is deliberately no idempotency guard.
-
-### Merge method and commit signatures
-
-Land a Version Packages PR with `gh pr merge <n> --squash`. Agent and human commits here are
-GPG-signed by the environment and verify as `valid`; the `github-actions[bot]` commit is
-`unsigned` because `GITHUB_TOKEN` cannot sign. The commit that lands is signed by GitHub,
-which is why `main`'s history reads `valid`: PR #161's unsigned head `fe7ef84` landed as
-`dd347471b1` with `committer=GitHub`, `verified=true`.
-
-Squash re-signs the landing commit; it does not escape an enforced signature rule. GitHub
-evaluates a pull request by creating a test merge commit and checking the commits it
-introduces — head-branch commits included — so an enforced `required_signatures` rule blocks
-a squash merge too, and the remedy is then a signed commit on the branch, not another merge
-method. `allow_merge_commit` is off and `required_linear_history` is on, so a merge commit is
-not an option — squash or rebase only, and only squash lands a commit GitHub signs.
-
-See `docs/commit-signing.md` for the evidence, the ruleset reads that show only
-repository-level rules applying to `main` (a read that covers organization rules too), and the
-human-only follow-ups, including the merge probe that closes AC1.
-
-### Version lockstep
-
-Two files carry the version, in lockstep automatically:
-
-1. `package.json` → bumped by changesets
-2. `CHANGELOG.md` → generated by changesets
-
-**Never bump versions manually.** Always create a changeset file.
-
-## Common mistakes
-
-- **Running `pnpm changeset`**: Interactive, wastes tokens. Write the file directly.
-- **Bumping versions manually**: Don't touch `"version"` in `package.json`. Create a changeset.
-- **Omitting the changeset**: CI fails the PR. Publishing is the default; the only
-  opt-out is the `no-publish` label, which must already exist in the repo's settings.
-- **Wrong bump type**: `patch` for fixes, `minor` for additions, `major` for breakage. When in doubt, ask the user.
-- **Wrong package name in frontmatter**: Must be `"@jaybeeuu/agent-cortex"` exactly.
-- **Merging a Version Packages PR with anything but squash**: the bot's commit is unsigned,
-  and squash is the path this repo has landed on (a rebase merge adds the head-branch commit
-  without signature verification).
-  Squash does not, however, bypass an enforced signature rule — if one is confirmed, the
-  branch needs a signed commit. See `docs/commit-signing.md`.
-
-## What changed from the old workflow
-
-| Before (manual) | After (changesets) |
-|---|---|
-| Agent bumps versions locally | Agent writes a changeset file |
-| Manual GitHub release creation | Automated by the `release` job in `ci.yml` |
-| `publish.yml` triggered by release | `ci.yml` release job on push to main |
-| Version files synced by hand | changesets bumps `package.json` + `CHANGELOG.md` |