@jaybeeuu/agent-cortex 2.0.0 → 2.2.0

package/skills/workflow/ralph/SKILL.md

@@ -1,18 +1,22 @@
 ---
 name: ralph
-description: "Run all pending beads end-to-end with up to 5 concurrent pipeline-stage chores in dedicated worktrees, opening review-gated PRs immediately and pausing for human merges. Use when you want to \"run the backlog\", \"run all beads\", or \"run ralph\" with human approval gates."
+description: "Run every ready execution:afk bead end-to-end — decomposing features, expanding tasks into pipeline-stage chores, and driving up to 5 concurrent workers in dedicated worktrees while opening review-gated PRs immediately and pausing for human merges. Use when you want to \"run the backlog\", \"run all beads\", or \"run ralph\" with human approval gates."
 ---
 
 # Ralph
 
-Ralph is a parallel orchestration loop. It advances AFK task beads through pipeline-stage chores (`code` → `verify` → `review` → `document`), dispatching each stage as a background subagent in the feature's worktree, then opens review-gated feature and epic PRs and pauses for human merges. Ralph never writes code itself — it dispatches, tracks, and reports.
+Ralph is a parallel orchestration loop. It advances `execution:afk` beads through pipeline-stage chores (`code` → `verify` → `review` → `document`), dispatching each unit as a background subagent in its parent's worktree, then opens review-gated feature and epic PRs and pauses for human merges. Ralph never writes code itself — it dispatches, tracks, and reports.
 
-State model: task state lives in beads (ready/in_progress via `bd`); the only local file is `.agent-cortex/ralph/state.json`, holding the agent-ID→bead mapping. Pipeline configuration comes from `skills/planning/create-task/pipeline.json`, and stage execution belongs to the `run-pipeline-stage` skill.
+One query decides what ralph works on: **`bd ready -l execution:afk`**. Features, tasks and chores all arrive through it, and each bead's *shape* — not a second `bd` filter — decides which procedure carries it: a childless feature is decomposed, a bead with no stage chores is expanded, a stage chore is dispatched. An `execution:afk` bead is therefore never invisible to ralph for lacking a `stage:*` label, and ralph never invents a narrower "only stage chores" predicate that would hide one.
+
+Each leaf execution bead belongs to the worker that ran it: the worker appends its milestone notes, closes the bead on both outcomes, and builds its own `stage:fix` + fresh-stage remediation chain when it fails. Ralph reads beads and routes — it never closes a leaf bead and never creates a fix bead. Its only retry control is a read-only cap backstop.
+
+State model: task state lives in beads (ready/in_progress via `bd`); the only local file is `.agent-cortex/ralph/state.json`, holding the agent-ID→bead mapping. Pipeline configuration comes from `skills/planning/create-task/pipeline.json`, and stage execution belongs to the `run-pipeline-stage` skill. Stage chores are pre-created from that pipeline when a task is expanded — with `blocks` deps encoding the order — so ralph's dispatch is always "claim what `bd ready -l execution:afk` returns"; it never creates a stage chore.
 
 ## When to use
 
 - "Run the backlog", "run all beads", "run ralph", "run everything pending".
-- A planning session has produced classified, unblocked AFK task beads and you want autonomous execution with human review gates.
+- A planning session has produced classified, unblocked `execution:afk` beads and you want autonomous execution with human review gates.
 - You want the full pipeline (implement → verify → review → document) orchestrated concurrently, with fix loops on failure.
 
 ## When NOT to use
@@ -29,61 +33,85 @@ State model: task state lives in beads (ready/in_progress via `bd`); the only lo
 2. Ensure `.agent-cortex/` and `.agent-cortex/worktrees/` are in the project's `.gitignore` (append any that are missing).
 3. Create the workspace: `mkdir -p .agent-cortex/ralph`.
 4. Initialize state: write `.agent-cortex/ralph/state.json` with `{ "inflight": [] }`.
-5. Read `skills/planning/create-task/pipeline.json` and hold it in memory — you need its `maxFixRounds` for the fix loop.
-6. Run `bd ready` and classify each available bead:
-   - **Chore with a `stage:*` label**: pipeline stage bead — eligible for dispatch.
-   - **Task or other type without an `implementation-type:*` label**: unexpected here — classification happens at planning time via `create-task`. Do not invoke `classify-bead`; treat as needs-refinement and note it for the shutdown summary.
-   - **Task labelled `implementation-type:hitl`**: skip — record the ID for the Pending Human Action summary at shutdown.
-7. For each ready chore bead (up to 5), dispatch it from its parent's feature worktree (see _Dispatching a chore bead_ in REFERENCE.md — create branches/worktrees first).
-8. Hand over to your harness's completion-detection mechanism: PI keeps a {{TOOL:wait_for_agents}} call outstanding over every in-flight agent ID. If no chore was dispatched and HITL gate beads are pending (`bd list -l lifecycle:feature-pr -l implementation-type:hitl` or `bd list -l awaiting-epic-pr-merge`), go straight to HITL Pause (REFERENCE.md).
-9. Regenerate `.agent-cortex/ralph/progress.md`:
-   ```bash
-   # workspace must be the absolute path you cd'd into — 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"
-   ```
-
-### 2. Event loop
+5. Read `skills/planning/create-task/pipeline.json` and hold it in memory — you need its `maxFixRounds` for the read-only cap backstop.
+6. Run **`bd ready -l execution:afk`**. That single query *is* the dispatch predicate — every ready `execution:afk` bead is ralph's work, whether it is a feature, a task or a chore. Classify each result by its shape to decide which procedure carries it:
+   - **`feature` bead with no children**: not dispatchable work yet — decompose it (_Feature decomposition_ below) and re-run the query.
+   - **Bead carrying a `stage:*` label**: a pipeline stage chore — dispatch it (_Event loop_, and _Dispatching a Chore Bead_ in REFERENCE.md).
+   - **`task` or other bead with no `stage:*` chore children**: expand it first (_Expansion guard_ below), then dispatch its ready `stage:code` chore.
+   - **Bead that already has its children** (a decomposed feature, an expanded task parent): skip it — it is not dispatchable itself, and its `stage:*` chore is dispatched on its own.
+   `execution:hitl` beads are not in this query and are not ralph's to touch: record them for the Pending Human Action summary. That includes every feature still at its default `execution:hitl` label.
+7. Dispatch each unit from its parent's worktree, up to 5 in flight: a stage chore via the event loop, a childless feature via a decomposition worker (_Feature decomposition_), a chore-less task via an expansion worker (_Expansion guard_). Create branches and worktrees first (REFERENCE.md, _Feature Branches and Worktrees_).
+8. Hand over to your harness's completion-detection mechanism: PI keeps a {{TOOL:wait_for_agents}} call outstanding over every in-flight agent ID, and Claude re-invokes you as each worker completes. If no **agent work** was dispatched — `state.json`'s `inflight` holds no entries, so no stage, decomposition or expansion worker is running — and `skills/workflow/ralph/scripts/pending-gates.mjs` reports a non-empty `pendingHumanAction` (an unblocked `lifecycle:feature-pr` gate, or an epic tagged `awaiting-epic-pr-merge`), go straight to HITL Pause (REFERENCE.md). A decomposition- or expansion-only init is in flight, not idle: keep the completion mechanism running and continue at the event loop.
+
+### 2. Expansion guard (stage chores are pre-created)
+
+A ready `execution:afk` task bead with no `stage:*` chore children has nothing to dispatch, so it is not dispatched as work. Expand it first: dispatch a worker in the feature worktree that runs `create-chores.mjs --parent <id> --priority <parent-priority>` against the existing bead and reports the returned `code`/`verify`/`review`/`document`/`featurePrReview` mapping — the next `bd ready -l execution:afk` pass then picks up `stage:code` (see REFERENCE.md, _Expansion Guard_).
+
+**Never expand an existing bead with `create-task`.** It creates a bead first and expands second, so the original would stay chore-less and gain a **second parent** beside it. `create-chores.mjs` expands; only `create-task` creates parents.
+
+### 3. Feature decomposition
+
+A ready `execution:afk` bead of type `feature` with no children is not dispatchable work — there is nothing to stage and nothing to expand. Decompose it: dispatch a worker in `.agent-cortex/worktrees/<feature-id>` that turns the feature into one `execution:hitl` planning bead plus `execution:afk` implementation children that depend on it, then continue (REFERENCE.md, _Feature Decomposition_).
+
+A feature carries `execution:hitl` by default, so this only runs when a human has deliberately relabelled a feature `execution:afk` to make its delivery agent-routable. Decomposition is then the last thing ralph does with it for a while: the children depend on the planning bead, so once the worker reports, `bd ready -l execution:afk` returns only the feature itself — no dispatchable child — and skipping that row is the *correct* behaviour, not re-expanding. **Never re-dispatch a decomposition**: the bead creation it runs is not idempotent, so a second run duplicates the whole hierarchy.
+
+### 4. Event loop
 
 On each completion notification (a background agent finished):
 
 1. Poll that parent's log for new lines — `tail -n +<nextLine> .agent-cortex/ralph/ralph-<parent-id>.log` (logs are keyed by parent bead ID, so every stage of a feature shares one file) — and post only new key events (stage transitions, test/lint results), never empty updates.
-2. Read the completed agent's output with {{TOOL:read_agent}} and parse its `---REPORT---` block for `BEAD_ID`, `STAGE_COMPLETED`, and the outcome.
-3. **Verify the delivery, then close the chore bead.** Run `node scripts/lib/verify-worker-tree.mjs --worktree .agent-cortex/worktrees/<parent-id> --base <base>` (REFERENCE.md, _Verified Completion_) and close only when it exits 0: `bd close <bead-id>`.
-4. Advance the parent per the dispatch table:
+2. Read the completed agent's output with {{TOOL:read_agent}} and parse its `---REPORT---` block for `BEAD_ID`, `STAGE_COMPLETED`, and the outcome. A **decomposition** (`kind: "decompose"`) or **expansion** (`kind: "expand"`) worker has no REPORT and no leaf bead to confirm. An **expansion worker** owns no bead — confirm the parent now has `stage:*` chores (`bd children <parent-id> --json | grep -c '"stage:'`) and skip to step 5 to dispatch its ready `stage:code` chore. A **decomposition worker** — confirm the feature now has children (`bd children <feature-id> --json` returns a non-empty list), record that nothing is dispatchable for it until a human closes the planning bead, and skip to step 5; never re-decompose. If either confirmation comes back empty, the worker failed: surface its output, record the parent for the shutdown summary, and do not re-dispatch.
+3. Confirm the stage worker closed its chore bead: `bd show <bead-id>` should read `closed` with the outcome in its close reason. If it is still open the worker died mid-stage — read its notes and re-dispatch; never close it yourself.
+4. Route the parent per the dispatch table — nothing is created here: the pre-created chain already encodes the order, and the worker owns any remediation it needs.
 
    | Stage completed | Condition | Next action |
    |-----------------|-----------|-------------|
-   | `code` | — | Closing the code chore unblocks the verify chore |
-   | `fix` | — | Closing the fix chore unblocks the verify chore |
-   | `verify` | `VERIFY_OUTCOME: PASS` | Closing the verify chore unblocks the review chore |
-   | `verify` | `VERIFY_OUTCOME: FAIL` | Run the fix loop (REFERENCE.md) |
-   | `review` | `REVIEW_OUTCOME: APPROVED` | Closing the review chore unblocks the document chore |
-   | `review` | `REVIEW_OUTCOME: CHANGES_REQUESTED` | Run the fix loop (REFERENCE.md) |
-   | `document` | — | Open/update the feature PR now (`feature/<parent-id>` → its base branch), report the URL, and update the child HITL gate bead (`lifecycle:feature-pr`). Wait for a human to close that bead after merge, then `bd close <parent-id>` |
+   | `code` | — | Closing the code chore unblocks the pre-created verify chore |
+   | `fix` | — | Closing the fix chore unblocks the fresh stage chore it was wired to |
+   | `verify` | `OUTCOME: SUCCESS` | Closing the verify chore unblocks the review chore |
+   | `verify` | `OUTCOME: BLOCKED` | Create nothing — the worker built `stage:fix` + a fresh `stage:verify`; dispatch the ready fix chore |
+   | `review` | `OUTCOME: SUCCESS` | Closing the review chore unblocks the document chore |
+   | `review` | `OUTCOME: BLOCKED` | Create nothing — the worker built `stage:fix` + a fresh `stage:review`; dispatch the ready fix chore |
+   | `document` | `OUTCOME: SUCCESS` | Open/update the feature PR now (`feature/<parent-id>` → its base branch), report the URL, and update the child HITL gate bead (`lifecycle:feature-pr`). Wait for a human to close that bead after merge, then `bd close <parent-id>` |
+   | any | parent status `blocked` | Nothing — the worker hit `maxFixRounds`; record the parent for the shutdown summary |
+
+5. Run `bd ready -l execution:afk` and dispatch new ready work while the in-flight count is under 5 — max 5 parent features, counted from `state.json`'s `inflight` (a parent counts while any of its workers — stage, `kind: "decompose"` or `kind: "expand"` — sits in `inflight`; REFERENCE.md, _State Files_). A ready childless feature is decomposed, not staged, and a ready bead with no chore tree is expanded (see _Feature decomposition_ and _Expansion guard_ above). Before each dispatch run the read-only cap backstop (REFERENCE.md, _Cap Backstop_): at `maxFixRounds` block the parent and create nothing. Do not schedule new parent features while `pending-gates.mjs` reports a non-empty `pendingHumanAction` — that is, while a `lifecycle:feature-pr` gate is **unblocked**. Gates still blocked behind their own pipeline (pre-created for a feature that has not reached its PR stage) are parked and never stop dispatch.
+6. If nothing is in flight (no stage, decomposition or expansion workers) and nothing is dispatchable (`bd ready -l execution:afk` returns no stage chore, no childless feature to decompose, and no ready, claimable chore-less task awaiting expansion — a queued `execution:afk` bead behind an open `lifecycle:feature-pr` HITL gate cannot be claimed, so it is paused work, not dispatchable work), proceed to HITL Pause (REFERENCE.md) when `pendingHumanAction` is non-empty, otherwise to Shutdown (REFERENCE.md).
+
+### 5. Reporting status (beads are the view)
 
-5. Run `bd ready` and dispatch new ready `stage:*` chore beads while the in-flight count (`bd list --status=in_progress --type=chore`) is under 5. Do not schedule new parent features while any `lifecycle:feature-pr` HITL gate bead is open.
-6. If no chores are in-flight and `bd ready` returns no `stage:*` chores, proceed to HITL Pause (REFERENCE.md) when HITL gate beads are pending, otherwise to Shutdown (REFERENCE.md).
-7. Regenerate `.agent-cortex/ralph/progress.md`.
+There is no status document to render. Report status in chat straight from `bd`, and give the human the same copy-paste command when they want the view themselves:
 
-### 3. Branching and review model
+```bash
+bd list --parent <parent-id>   # every chore for a feature, with its state
+bd ready -l execution:afk      # the next dispatchable work
+bd show <id>                   # full detail, including the worker's notes
+```
+
+### 6. Branching and review model
 
 - **Single-feature epics** (exactly one feature task child — count with `bd children <epic-id>`, excluding chores): no epic branch. `feature/<parent-id>` is based directly on `origin/main`, its feature PR targets `main`, and no epic PR is opened.
-- **Multi-feature epics** (two or more feature task children): the epic runs on `epic/<epic-id>`, based on `origin/main` — never local `main`. Each AFK parent task runs on `feature/<parent-id>`, based from its epic branch, in the dedicated worktree `.agent-cortex/worktrees/<parent-id>`.
+- **Multi-feature epics** (two or more feature task children): the epic runs on `epic/<epic-id>`, based on `origin/main` — never local `main`. Each `execution:afk` parent task runs on `feature/<parent-id>`, based from its epic branch, in the dedicated worktree `.agent-cortex/worktrees/<parent-id>`.
 - Feature PR gate: `feature/<parent-id>` → `epic/<epic-id>` (or → `main` for single-feature epics). Epic PR gate: `epic/<epic-id>` → `main`.
+- **Never stack branches.** `feature/<parent-id>` is based on `epic/<epic-id>` (or `origin/main`), never on another `feature/*`. A dependency between two tasks lives in the bead graph (`bd dep add <waiting> <blocked-on>`) so the dependent task stays out of `bd ready` until its dependency has merged — stacking the branch defeats that gate by hand and costs a rebase-on-squash later (see `git-workflow` rule 3).
 - Branch/worktree setup and the PR commands live in REFERENCE.md (_Feature branches and worktrees_, _Feature PR gate_).
 
-### 4. HITL pause and shutdown
+### 7. HITL pause and shutdown
+
+Both paths end in a **gated** `bd dolt push`: on a non-zero exit, retry once, then stop and report the command, exit code and stderr as a sync blocker instead of printing any completion or Pending Human Action summary. A sync that never reached the remote is a failed shutdown, not a finished one.
 
-- **HITL Pause** — when no chores are in-flight, none ready, and HITL gate beads are pending: regenerate `progress.md`, open/update epic PRs to `main` for multi-feature epics and tag each epic `awaiting-epic-pr-merge` (single-feature epics need none — their feature PRs already target `main`), run `bd dolt push`, output the Pending Human Action table, then stop completely until re-prompted.
-- **Shutdown** — when all work is complete: regenerate `progress.md`, open/update epic PRs to `main` for multi-feature epics and tag them (single-feature epics need none), run `bd dolt push`, then output the Pending Human Action / Needs Refinement / cap-blocked / Pending Epic Review summaries that apply, or "All beads complete."
+- **HITL Pause** — when nothing is in flight (no stage, decomposition or expansion workers), nothing is dispatchable (nothing returned by `bd ready -l execution:afk`, including no ready, claimable chore-less task awaiting expansion), and `pending-gates.mjs` reports a non-empty `pendingHumanAction` (an unblocked `lifecycle:feature-pr` gate, or an epic tagged `awaiting-epic-pr-merge`; gates still parked behind their own pipeline do not count): open/update epic PRs to `main` for multi-feature epics and tag each epic `awaiting-epic-pr-merge` (single-feature epics need none — their feature PRs already target `main`), run the gated `bd dolt push`, output the Pending Human Action table, then stop completely until re-prompted.
+- **Shutdown** — when all work is complete: open/update epic PRs to `main` for multi-feature epics and tag them (single-feature epics need none), run the gated `bd dolt push`, then output the Pending Human Action / Needs Refinement / cap-blocked / Pending Epic Review summaries that apply, or "All beads complete."
 
 ## Red Flags
 
 - Running as a background or delegated subagent instead of the interactive foreground agent.
 - Spawning a stage runner via {{TOOL:bash}} or running a stage inline instead of {{TOOL:task}}.
-- Substituting a backgrounded CLI run for a missing subagent tool — stop and report instead; that launch has no completion signal.
-- Advancing a parent on a worker's `OUTCOME: SUCCESS` without verifying the worktree — the report is a claim, not evidence.
+- Closing a leaf execution bead, or creating a `stage:fix`/feedback bead — both belong to the worker.
+- Creating a stage chore, or running `create-task` for an existing bead — the chain is pre-created and `create-task` would add a second parent.
+- Re-dispatching a decomposition because "the feature still looks idle" — the children are blocked on the planning bead, which is Q5b working, not a failure. Never re-create the hierarchy.
+- Reaching for a narrower dispatch query (`bd ready -t chore`, "chores with `stage:*`") — an `execution:afk` bead with no stage chores is work waiting for expansion, not work that does not exist.
+- Loop counting from a stage runner's prose when the same fact is queryable from beads.
 - Editing bead files directly instead of using `bd` commands.
 - Auto-merging a PR, or continuing past a feature/epic gate before a human merge.
 
@@ -94,29 +122,40 @@ On each completion notification (a background agent finished):
 | "I'll just run this one stage inline" | An orchestrator that executes stages stops being an orchestrator — the review gates exist to catch exactly that shortcut. |
 | "One more task in flight won't hurt" | The 5-task cap bounds log polling, state bookkeeping, and PR sequencing; exceeding it loses track of in-flight work. |
 | "The review passed, so I can merge" | Feature and epic PR merges are human-controlled; the gate exists so a person sees every change. |
+| "The worker left the chore open — I'll close it" | The worker owns that bead; an open one means it died mid-stage, so read its notes and re-dispatch instead of closing over the missing record. |
+| "This bead has no chores — I'll create them as I go" | The whole chain is pre-created with `blocks` deps; hand-creating stages duplicates chores and loses the order. Expand with `create-chores.mjs` instead. |
+| "That feature came back ready again, so I'll decompose it a second time" | The implementation children depend on the planning bead, so nothing is ready until a human closes it. Re-decomposing duplicates the hierarchy; idling *is* the correct outcome. |
 
 ## Philosophy / rationale
 
 - Orchestration state derives from beads so a crash loses nothing but an in-memory ID mapping: `state.json` holds only the agent-ID→bead mapping, never task state.
-- Classification happens up-front at planning time (`create-task`), so the loop can trust `bd ready` instead of re-interpreting each bead's intent.
+- Every control-flow predicate — is anything in flight, is there work, is there room, may we pause or shut down — derives from `state.json`'s `inflight` (`kind: "stage"`, `kind: "decompose"` or `kind: "expand"`) plus `bd ready -l execution:afk`, never from a chore-type `bd` query: an expansion or decomposition worker owns no stage chore, so a chore-only predicate reports idle while an agent is running (REFERENCE.md, _The in-flight invariant_).
+- One predicate answers both *who runs this* and *when*: `execution:afk` says it is agent work and the bead graph says it is ready, so ralph needs no label that encodes "not really work yet" — a childless feature is routed by its type, not excluded by a filter. Classification happens up-front at planning time (`create-task`), so the loop can trust the query instead of re-interpreting each bead's intent.
 - Human review gates are non-negotiable because agent-authored changes still need a person to merge them.
+- One owner per lifecycle: the actor that did the work records the outcome, so beads never carry an outcome written by someone who was not there.
 
 ## Phase-gate checklists
 
-- [ ] Init complete: `bd prime` held, gitignore entries present, workspace and state.json created, pipeline.json read, first `bd ready` classified, first chores dispatched.
-- [ ] Event loop handed off: completion-detection mechanism running (or HITL Pause/Shutdown started) and `progress.md` regenerated.
+- [ ] Init complete: `bd prime` held, gitignore entries present, workspace and state.json created, pipeline.json read, first `bd ready -l execution:afk` classified, first agent work dispatched (a stage chore, a decomposition worker or an expansion worker).
+- [ ] Event loop handed off: completion-detection mechanism running (or HITL Pause/Shutdown started) — a decomposition- or expansion-only init is in flight, not idle.
+
+## See Also
 
-## Cross-skill references
+- [run-pipeline-stage](../run-pipeline-stage/SKILL.md) — owns the stage-runner prompt, per-stage playbooks, the `---REPORT---` format, and the worker's remediation chain. Read it before dispatching any stage.
+- [create-task](../../planning/create-task/SKILL.md) — owns `pipeline.json` and the HITL gate beads; its `scripts/pending-gates.mjs` is the only home of the gate queries.
+- [prd-to-tasks](../../planning/prd-to-tasks/SKILL.md) — load when the decomposition worker expands a feature into slices.
 
-- The `run-pipeline-stage` skill owns the stage-runner prompt, per-stage playbooks, the `---REPORT---` format, and fix-loop feedback beads — read it before dispatching any stage.
-- The `create-task` skill owns `pipeline.json` and creates the `lifecycle:feature-pr` HITL gate beads.
-- Do not invoke `classify-bead` from this loop — classification was already applied at planning time.
+Do not invoke `classify-bead` from this loop — classification was applied at planning time.
 
 ## Verification checklist
 
-- [ ] Init ran once with observable results: `state.json` exists, `bd ready` was parsed, and the first chore beads are claimed.
+- [ ] Init ran once with observable results: `state.json` exists, `bd ready -l execution:afk` was parsed, and agent work is in flight — a stage chore claimed, or a decomposition or expansion worker dispatched for a bead that needed one.
 - [ ] Every stage runner was spawned with {{TOOL:task}} from the parent's feature worktree, with the `---REPORT---` instruction in its prompt.
-- [ ] Every stage delivery was confirmed with `scripts/lib/verify-worker-tree.mjs` before the parent advanced, and no stage was dispatched from a session with no subagent tool.
-- [ ] In-flight count never exceeded 5, and fix loops respect `maxFixRounds` from `pipeline.json`.
+- [ ] Every dispatch came from `bd ready -l execution:afk` — no narrower chore-only filter was used to decide that a bead was not work.
+- [ ] A childless `execution:afk` feature was decomposed exactly once into a planning bead plus `execution:afk` children depending on it, and was not re-decomposed on later idle passes.
+- [ ] In-flight count never exceeded 5, and the read-only cap backstop ran before every `stage:*` dispatch.
+- [ ] Every in-flight, dispatchable-work, HITL-pause, and shutdown predicate was read from `state.json`'s `inflight` (stage, decomposition **and** expansion workers) plus `bd ready -l execution:afk`, with the ready, claimable scope of a chore-less `execution:afk` task bead — never from a chore-only `bd` query, and never counting a bead an open `lifecycle:feature-pr` gate blocks from being claimed.
+- [ ] Ralph closed no leaf execution bead and created no fix bead; every closed chore carries its worker's close reason.
+- [ ] Any chore-less `execution:afk` task bead was expanded with `create-chores.mjs` (one parent bead), never with `create-task`.
 - [ ] Feature and epic PRs were pushed and reported immediately at their gates, and nothing was auto-merged.
-- [ ] `bd dolt push` and a final `progress.md` regeneration ran before HITL Pause/Shutdown, and the chat received no empty poll updates.
+- [ ] Every `bd dolt push` before HITL Pause/Shutdown exited 0 — a non-zero exit was retried once, then surfaced as a blocker (command, exit code, stderr) with no completion or Pending Human Action summary printed; status was reported from `bd` commands rather than a generated file, and the chat received no empty poll updates.

package/skills/workflow/ralph/scripts/pending-gates.mjs

@@ -0,0 +1,134 @@
+// Resolves which beads are waiting on a human, and which are merely parked
+// behind their own pipeline.
+//
+// Ralph schedules new parent features only when nothing is pending human action.
+// The distinction that matters is *unblocked*, not *open*: `create-chores`
+// pre-creates a `lifecycle:feature-pr` gate for every planned feature, blocked
+// behind that feature's own document chore. Such a gate is parked — the feature
+// has not reached its PR stage — and must never stop dispatch. Only once the
+// document chore closes does the gate unblock, and that is the state in which a
+// feature genuinely awaits a human merge.
+//
+// Zero dependencies: run with `node pending-gates.mjs`.
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { pathToFileURL } from 'node:url';
+
+/** The structural label every feature PR gate carries, whatever its axis. */
+export const FEATURE_GATE_LABEL = 'lifecycle:feature-pr';
+
+/** Epics whose PR into `main` awaits a human merge. */
+export const EPIC_GATE_LABEL = 'awaiting-epic-pr-merge';
+
+// Two-axis migration: gates created before the `execution:afk/hitl` migration
+// carry `implementation-type:hitl`, gates created after carry `execution:hitl`.
+// Both mean "a human must act", so the query matches either.
+export const HITL_GATE_LABELS = ['execution:hitl', 'implementation-type:hitl'];
+
+/** @typedef {{ id: string, title?: string }} Bead */
+/** @typedef {{ id: string, title: string, kind: 'feature-pr' | 'epic-pr' }} PendingAction */
+
+/**
+ * @typedef {object} GateState
+ * @property {PendingAction[]} pendingHumanAction  Beads a human must act on now — non-empty means "do not schedule new parent features".
+ * @property {Array<{ id: string, title: string }>} parked  Open gates still blocked behind their own pipeline; informational only.
+ */
+
+/**
+ * Split open gates into those awaiting a human now and those still parked.
+ *
+ * @param {object} input
+ * @param {Bead[]} input.readyGates            Open gates with no active blockers.
+ * @param {Bead[]} input.openGates             Every open gate, blocked or not.
+ * @param {Bead[]} input.epicsAwaitingMerge    Epics tagged `awaiting-epic-pr-merge`.
+ * @returns {GateState}
+ */
+export function resolveGateState({ readyGates, openGates, epicsAwaitingMerge }) {
+  const actionable = new Set(readyGates.map((bead) => bead.id));
+
+  const pendingHumanAction = [
+    ...readyGates.map((bead) => pendingAction(bead, 'feature-pr')),
+    ...epicsAwaitingMerge.map((bead) => pendingAction(bead, 'epic-pr')),
+  ];
+
+  const parked = openGates
+    .filter((bead) => !actionable.has(bead.id))
+    .map((bead) => ({ id: bead.id, title: bead.title ?? '' }));
+
+  return { pendingHumanAction, parked };
+}
+
+/**
+ * @param {Bead} bead
+ * @param {'feature-pr' | 'epic-pr'} kind
+ * @returns {PendingAction}
+ */
+function pendingAction(bead, kind) {
+  return { id: bead.id, title: bead.title ?? '', kind };
+}
+
+// BD_PATH env override lets machines where bd is not on PATH pin a location.
+const BD_PATH = process.env.BD_PATH || 'bd';
+const execFileAsync = promisify(execFile);
+
+/** @type {(args: string[]) => Promise<string>} */
+async function defaultExec(args) {
+  const { stdout } = await execFileAsync(BD_PATH, args, { encoding: 'utf-8' });
+  return stdout;
+}
+
+/**
+ * Query bd for the current gate state.
+ *
+ * @param {object} [options]
+ * @param {(args: string[]) => Promise<string>} [options.exec]  bd runner; injectable for tests.
+ * @returns {Promise<GateState>}
+ */
+export async function fetchGateState({ exec = defaultExec } = {}) {
+  const gateFilter = ['-l', FEATURE_GATE_LABEL, '--label-any', HITL_GATE_LABELS.join(',')];
+
+  // `bd ready` is blocker-aware: it returns only gates whose document chore has
+  // closed, i.e. the ones genuinely awaiting a human merge.
+  const readyGates = JSON.parse(await exec(['ready', '--json', ...gateFilter]));
+  const openGates = JSON.parse(await exec(['list', '--json', '--limit', '0', ...gateFilter]));
+  const epicsAwaitingMerge = JSON.parse(await exec(['list', '--json', '--limit', '0', '-l', EPIC_GATE_LABEL]));
+
+  return resolveGateState({ readyGates, openGates, epicsAwaitingMerge });
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────────
+
+const USAGE = 'Usage: node pending-gates.mjs\n\nPrints { pendingHumanAction, parked } as JSON.\n';
+
+class UsageError extends Error {}
+
+/**
+ * @param {object} options
+ * @param {string[]} options.argv                              CLI arguments (without node/script).
+ * @param {(args: string[]) => Promise<string>} [options.exec]  bd runner; injectable for tests.
+ * @param {(chunk: string) => void} [options.write]             stdout sink; injectable for tests.
+ * @returns {Promise<number>} process exit code.
+ */
+export async function runCli({ argv, exec = defaultExec, write = (chunk) => process.stdout.write(chunk) }) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    write(USAGE);
+    return 0;
+  }
+  if (argv.length > 0) throw new UsageError(`unexpected argument: ${argv[0]}`);
+
+  write(`${JSON.stringify(await fetchGateState({ exec }), null, 2)}\n`);
+  return 0;
+}
+
+// Only run the CLI when invoked directly, so tests can import the pure resolver.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runCli({ argv: process.argv.slice(2) })
+    .then((code) => {
+      process.exitCode = code;
+    })
+    .catch((error) => {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+      process.exitCode = error instanceof UsageError ? 2 : 1;
+    });
+}

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.