@jaybeeuu/agent-cortex 2.1.0 → 2.2.0

package/skills/workflow/ralph/REFERENCE.md

@@ -4,8 +4,141 @@ Detailed procedures for the ralph orchestration workflow. See [SKILL.md](./SKILL
 
 ---
 
+## The in-flight invariant
+
+Every ralph control-flow predicate — *is any agent work in flight?*, *is there work?*, *is there
+room to dispatch?*, *may we pause?*, *may we shut down?* — is answered from `state.json`'s
+`inflight` list (entries carry `kind: "stage"`, `kind: "decompose"` or `kind: "expand"`) plus
+`bd ready -l execution:afk`. **Never** from a chore-type `bd` query, and never from "was a chore
+dispatched?".
+
+| Question | Derive it from | Never from |
+|----------|----------------|------------|
+| Is any agent work in flight? | `inflight` in `.agent-cortex/ralph/state.json` — stage, decomposition **and** expansion entries | `bd list -t chore`, `bd ready -t chore`, or any "were chores dispatched?" test |
+| Is anything dispatchable? | `bd ready -l execution:afk`: a `stage:*` chore, a childless `execution:afk` `feature` bead to decompose, **or** a ready, claimable chore-less `execution:afk` task bead awaiting expansion | A chore listing alone — a ready, claimable childless feature or chore-less task is work waiting, not idle |
+| Is there room under the 5-feature cap? | Parent count in `inflight` | A count of chore beads |
+| May ralph pause or shut down? | `inflight` empty **and** nothing dispatchable (per the row above) | "No stage worker is running" |
+
+**`execution:afk` is the one dispatch predicate.** It answers *whose work is this* for features,
+tasks and chores alike, and the bead graph answers *when*. Ralph therefore never narrows the query
+— "chores with `stage:*`" would report a ready childless feature or an unexpanded task as idle
+while both are work waiting for a worker.
+
+**Dispatchable means ready *and* claimable.** `bd ready -l execution:afk` decides ready; pending human action
+decides claimable: while `pending-gates.mjs` reports an unblocked `lifecycle:feature-pr` gate, ralph
+schedules no new parent features (_Feature PR gate_, step 6), so a queued unexpanded `execution:afk` bead in
+that state is paused work, not dispatchable work. Scoping the predicate both ways is what makes HITL Pause
+reachable in the canonical post-PR state — gate open, unexpanded `execution:afk` beads queued, `inflight`
+empty, no ready `stage:*` chore — instead of re-arming a PI
+wait over an empty agent set forever on an idle poll.
+
+**Why:** an expansion or decomposition worker claims no chore. A chore-only predicate therefore
+reports "nothing in flight" while an agent is running, which makes ralph pause or shut down
+mid-expansion and leaves the parent's freshly created `stage:*` chain undispatched. The only
+legitimate chore-type control-flow predicate in ralph is the retry counter in _Cap Backstop_
+(`stage:fix` children): it counts remediation history rather than in-flight work, so it may gate a
+dispatch decision but it must never answer *is anything in flight?*. Every other chore-type `bd`
+query used as a control-flow predicate is a bug. Structural checks that ask nothing more than
+*what does this bead already have?* — the _Expansion Guard_'s `grep -c '"stage:'`, the _Cap
+Backstop_'s `stage:fix` count, the _Feature Decomposition_'s child count — are not predicates and
+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 — with `blocks` deps that encode the order, and with the parent's priority and inherited labels. 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:
+
+1. **Confirm it is chore-less** — a bead that already has stage chores is never expanded again:
+   ```bash
+   bd children <parent-id> --json | grep -c '"stage:'
+   ```
+   Expect `0` printed. `grep -c` exits `1` when it counts zero matches, so add `|| true` when the
+   check runs under `set -e` or inside an `&&` chain — the printed count is the answer, not the exit
+   status.
+2. **Dispatch an expansion worker** in the feature worktree (`.agent-cortex/worktrees/<parent-id>`) whose whole job is to run the pre-creator against the existing bead and report the JSON it printed:
+   ```bash
+   node <create-task-scripts>/create-chores.mjs \
+     --parent <parent-id> --priority <parent-priority>
+   ```
+   `<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 }
+   ```
+4. **Report the mapping** the worker returns — `code`, `verify`, `review`, `document`, `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.
+
+**Never expand an existing bead with `create-task`** — or with any other command that creates a bead. `create-task` creates a bead first and expands second, so running it for an existing bead leaves a **second parent** beside the original, which stays chore-less and never gets dispatched. The guard exists so an `execution:afk` task bead always ends with exactly one parent: `create-chores.mjs` expands a bead that already exists; only `create-task` creates parents.
+
+**Labels on the chain.** Stage chores inherit `execution:afk` from their parent task bead, so they surface in ralph's `bd ready -l execution:afk` query without extra tagging — an expanded task never needs its chores relabelled. The `featurePrReview` HITL gate is the one exception: it declares its own `execution:hitl` + `lifecycle:feature-pr` labels and the script passes `--no-inherit-labels` for it, so it never picks up the parent's `execution:afk`.
+
+### Expansion Completion Contract
+
+An expansion worker is dispatched like a stage worker but is **not** one. Nothing downstream of a stage dispatch applies to it:
+
+| Stage worker | Expansion worker |
+|------|------|
+| Correlates to a claimed chore: `kind: "stage"` with a `choreId` | Holds no chore: `kind: "expand"`, `choreId: null` |
+| Emits a `---REPORT---` block | Emits none — it prints the `create-chores.mjs` JSON mapping |
+| Owns its leaf bead, which must read `closed` | Owns nothing — no bead to close, nothing to confirm |
+| Completion advances the parent along the chain | Completion means "chores now exist" — dispatch the ready `stage:code` chore |
+
+On completion, remove the entry from `inflight` and confirm the chore tree exists rather than taking the worker's word for it:
+
+```bash
+bd children <parent-id> --json | grep -c '"stage:'
+```
+
+Expect a non-zero count — one match per `stage:*` label in the chain. A printed `0` means the
+expansion failed. Surface the worker's output in chat and record the parent for the shutdown summary — **never re-dispatch the expansion**, because `create-chores.mjs` is not idempotent and a second run duplicates the chain beside the first. Then continue at the normal dispatch pass: either way nothing is created and nothing is closed by ralph.
+
+---
+
+## Feature Decomposition
+
+Epic Q2 makes ralph responsible for decomposing a feature bead into the hierarchy; Q5 makes a
+feature `execution:hitl` by default. Both hold because the **label**, not the bead type, decides
+routing: a feature is invisible to ralph while it carries `execution:hitl`, and a human exposes it
+to ralph by relabelling it `execution:afk` when its delivery is genuinely agent-routable. Ralph
+then decomposes it once and immediately goes idle behind the planning bead — Q5b's dependency gate
+does the pausing, so no extra "ready to decompose" label is needed.
+
+A ready `execution:afk` bead of type `feature` with **no** children is not dispatchable work.
+Decompose it:
+
+1. **Confirm it is childless** — any existing child means the feature is already decomposed and this
+   procedure does not apply:
+   ```bash
+   bd children <feature-id> --json
+   ```
+   Expect an empty list `[]`. A non-empty list, however few children, means stop here.
+2. **Dispatch a decomposition worker** in the feature worktree (`.agent-cortex/worktrees/<feature-id>`) whose whole job is to run the `create-task` hierarchy flow (`prd-to-tasks` → `create-task`) for that one **existing** feature — its planning bead and impl children only, never a second feature bead — and report the IDs it created. The worker builds the Q5 shape:
+   - a **planning bead** — `--parent <feature-id>`, `execution:hitl` — held for a human to confirm planning is sufficient;
+   - **implementation task children** — `--parent <feature-id>`, `execution:afk`, `--no-inherit-labels` — each wired to wait on the planning bead with `bd dep add <impl-child> <planning-bead>`.
+
+   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 }
+   ```
+4. **Confirm the children exist** rather than trusting the report — the worker's IDs are a claim, the bead graph is the evidence:
+   ```bash
+   bd children <feature-id> --json
+   ```
+   Surface the created IDs in chat. An empty list means the decomposition failed: record the feature for the shutdown summary and continue — do not re-dispatch.
+5. **Never re-dispatch a decomposition.** The bead creation it runs is not idempotent, so a second run duplicates the planning bead and every implementation child beside the first. This is the same hazard as re-running `create-chores.mjs`.
+6. **Go idle.** After decomposition nothing is dispatchable for that feature: `bd ready -l execution:afk` still lists the feature itself (it now has children, so it is skipped — never decomposed again) but none of its children until a human closes the planning bead. Returning to the event loop with *nothing* to dispatch is the correct outcome, not a failure to re-expand — that is Q5b working as designed.
+
+---
+
 ## Dispatching a Chore Bead
 
+Chores already exist, so dispatch never creates one:
+
 1. **Claim** the bead: `bd update <id> --claim`.
 2. **Read its `stage:*` label** from `bd show <id>`.
 3. **Load the universal stage runner prompt** from `skills/workflow/run-pipeline-stage/prompts/stage-runner.md`.
@@ -13,7 +146,7 @@ Detailed procedures for the ralph orchestration workflow. See [SKILL.md](./SKILL
 5. **Ensure branch + worktree exist for this parent task** (see _Feature branches and worktrees_ below), then note the worktree path — you'll pass it as `cwd` to {{TOOL:task}}.
 6. **Fill in the prompt** — replace placeholders with:
    - Stage from bead label (`stage:<stage>`) for `<stage>`
-   - Chore bead ID and its `bd show` output for the bead specification. Do **not** inject `bd prime` output — the stage runner runs `bd prime` itself if it needs project context
+   - The leaf execution bead ID and its `bd show` output for the bead specification. Do **not** inject `bd prime` output — the stage runner runs `bd prime` itself if it needs project context
    - 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
@@ -55,6 +188,10 @@ For each parent task bead (`<parent-id>`):
    # <base> is epic/<epic-id> for multi-feature epics, origin/main for single-feature
    git worktree add .agent-cortex/worktrees/<parent-id> -b feature/<parent-id> <base>
    ```
+   **`<base>` is `epic/<epic-id>` or `origin/main` — never another `feature/*` branch.** If this
+   task depends on another unmerged task, its `blocks` edge already keeps it out of `bd ready`;
+   do not create the worktree early to get ahead, and never reuse a sibling task's worktree — that
+   silently stacks the branches and turns the dependency into a squash-merge conflict later.
    If `.agent-cortex/worktrees/<parent-id>` already exists, reuse it.
 5. All chores for this parent run in `.agent-cortex/worktrees/<parent-id>`. The `feature/<parent-id>` branch is the agent branch for HITL PRs.
 
@@ -64,7 +201,7 @@ For each parent task bead (`<parent-id>`):
 
 When the `document` chore for a parent task completes:
 
-1. Close the `document` chore.
+1. Confirm the document worker closed its own chore (`bd show <id>` reads `closed`); do not close it yourself.
 2. Create or update a feature PR immediately from the agent branch to the feature branch (`feature/<parent-id>` into `epic/<epic-id>`; into `main` for single-feature epics):
    ```bash
    # <base> is epic/<epic-id> for multi-feature epics, main for single-feature
@@ -72,7 +209,7 @@ When the `document` chore for a parent task completes:
    ```
    If an open PR already exists, update it instead of creating a duplicate.
 3. Report the PR URL in chat as soon as it is created.
-4. Find the child HITL task bead for this parent with label `lifecycle:feature-pr` (created by `create-task`).
+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. After that, close the parent feature bead:
@@ -101,40 +238,27 @@ Gate queries match the HITL axis on either `execution:hitl` (current) or `implem
 **Invariant — what may block a gate.** `parked` means "blocked by its own pipeline". A gate blocked by its parent **feature** bead is not parked in any harness: that bead stays open until after the merge, so the gate never reaches `bd ready`, never appears in `pendingHumanAction`, and a human merge is silently never requested. Keep the two shapes apart:
 
 - A `create-chores` gate unblocks exactly once, when its `document` chore closes. Until then it is parked and must not stop dispatch.
-- A gate must never carry a `blocks` dependency onto its own feature bead (the native-Claude shape: `bd create ... --labels ...lifecycle:feature-pr` then dep it to `<id>`). Remove it with `bd dep rm <gate> <id>` if present, so the gate is unblocked while its PR awaits merge.
+- A gate must never carry a `blocks` dependency onto its own feature bead (e.g. `bd create ... --labels ...lifecycle:feature-pr` then dep it to `<id>`). Remove it with `bd dep rm <gate> <id>` if present, so the gate is unblocked while its PR awaits merge.
 
-So the predicate is sensitive to *what* blocks a gate, not only whether something does. `agents-native/ralph.md` (the Claude harness) keeps the open-gate form for this reason: its gates stay blocked by design, and its `document` chores never close; F10 (agnt-ctx-s5xd.10) unifies the two predicates.
+So the predicate is sensitive to *what* blocks a gate, not only whether something does. It is ralph's only gate predicate on every harness: the Claude-native agent file that kept an open-gate form is retired, so nothing else restates a second predicate.
 
 ---
 
-## Fix Loop
+## Cap Backstop (read-only)
 
-When a verify or review stage fails:
-
-1. **Determine the parent task**: look up the chore bead's parent via `bd show <chore-id>` (follow the `parent-child` dependency).
-2. **Count existing fix rounds**: list all chore beads that are children of the parent task with label `stage:fix`. The count of these (including closed ones) is the number of fix rounds already attempted.
-3. **Read `maxFixRounds`** from `skills/planning/create-task/pipeline.json` (held in memory since initialization).
-4. **If fix rounds ≥ maxFixRounds**: close the parent task bead as failed (`bd close <parent-id> --reason "Max fix rounds reached"`). Do not create another fix chore.
-5. **Otherwise, create a fix chore** with the feedback in its description so the fixer agent can read it directly from `bd show`:
-   ```bash
-   fix_id=$(bd create "[<parent-id>] Fix (round <N>)" --type chore \
-     --priority <same as parent> \
-     --description "Requirements: see <parent-id> acceptance criteria (`bd show <parent-id>`).
+Ralph never builds remediation. The worker that fails a stage creates its own `stage:fix` chore, a fresh instance of the failed stage blocked on that fix, and re-blocks the later stages behind the fresh bead (see the `run-pipeline-stage` skill, _Remediation Children_). Ralph only guards the cap, and only reads:
 
-<CHANGES_REQUESTED list or VERIFY_FAILURES list from the triggering REPORT>" -q)
-   bd tag $fix_id stage:fix
-   bd dep add $fix_id <parent-id> --type parent-child   # fix-chore is child of parent
-   ```
-6. **Find the verify chore** for this parent task (the chore with label `stage:verify` and a `parent-child` dep to the parent).
-7. **Block the verify chore** on the new fix chore:
+1. **Read `maxFixRounds`** from `skills/planning/create-task/pipeline.json` (held in memory since initialization).
+2. **Count existing fix rounds** for the parent — closed chores count:
    ```bash
-   bd dep add <verify-id> $fix_id --type blocks          # verify waits for fix
+   fix_rounds=$(bd children <parent-id> --json | grep -c '"stage:fix"')
    ```
-8. **Reopen the verify chore**:
+3. **Before dispatching any `stage:*` chore of that parent**, if `fix_rounds >= maxFixRounds`: create nothing and block the parent, so a human sees it in the shutdown summary:
    ```bash
-   bd reopen <verify-id>
+   bd update <parent-id> --status blocked \
+     --append-notes "[<ISO-timestamp>] max fix rounds reached (<fix_rounds>/<maxFixRounds>)"
    ```
-   This ensures the fix chore runs first, then verify re-runs automatically when the fix closes.
+4. Ralph does **not** close the parent as failed and does **not** reopen or re-wire any chore — the worker already closed the failed leaf bead and the fresh stage bead is already blocked on its fix.
 
 ---
 
@@ -142,43 +266,43 @@ When a verify or review stage fails:
 
 Run whenever completion handling is triggered (an agent completion):
 
-1. **Query in-flight beads**: `bd list --status=in_progress --type=chore`. Extract each bead's ID and title.
-2. For each in-flight bead, 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. Track the next unread line number per parent in memory, starting at 1:
+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 +<lastLine> .agent-cortex/ralph/ralph-<parent-id>.log 2>/dev/null
+   tail -n +<logLine> .agent-cortex/ralph/ralph-<parentId>.log 2>/dev/null
    ```
-3. For each bead that has new lines:
+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):
      ```
-     📋 [bead-id] <title>
+     📋 [parent-id] <title>
         coding → verifying  (or whatever transition)
         Tests: 12 passed, 0 failed
      ```
-   - Update the in-memory line offset for that bead.
-4. If no bead had new lines, post nothing — do not spam the chat with empty polls.
+   - 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.
 
 ---
 
 ## HITL Pause
 
-Proceed here when no chore beads are in-flight, no `stage:*` chore beads are ready, and `pending-gates.mjs` reports a non-empty `pendingHumanAction` — an **unblocked** `lifecycle:feature-pr` gate or an epic tagged `awaiting-epic-pr-merge` (see _Gate predicate_). Gates still parked behind their own pipeline do not count. Ralph stops rather than burning requests on idle polls.
+Proceed here when no agent work is in flight (no stage, decomposition or expansion workers in `inflight`), nothing is dispatchable (`bd ready -l execution:afk` returns no `stage:*` chore, no childless feature to decompose, and no ready, claimable chore-less `execution:afk` task bead 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` (see _Gate predicate_). Gates still parked behind their own pipeline do not count. Ralph stops rather than burning requests on idle polls.
 
-1. Regenerate `.agent-cortex/ralph/progress.md` one final time — do not delete it.
-2. For each **multi-feature** epic whose feature beads are all closed but not yet tagged `awaiting-epic-pr-merge`, open/update an epic PR to main (skip single-feature epics — their feature branch PRs already target `main`):
+1. For each **multi-feature** epic whose feature beads are all closed but not yet tagged `awaiting-epic-pr-merge`, open/update an epic PR to main (skip single-feature epics — their feature branch PRs already target `main`):
    ```bash
    gh pr create --base main --head epic/<epic-id> --title "[<epic-id>] Merge epic into main" --body "<epic summary>"
    ```
    Tag each epic bead with `awaiting-epic-pr-merge` until merged.
-3. Run:
+2. Run:
    ```bash
    bd dolt push
    ```
-4. Collect the table rows from `pendingHumanAction`:
+   **Gate on the exit status.** Non-zero: retry once, then stop and report the command, exit code and stderr as a sync blocker — no Pending Human Action table, and ralph does not claim a clean pause.
+3. Collect the table rows from the script's `pendingHumanAction` list:
    ```bash
    node skills/workflow/ralph/scripts/pending-gates.mjs
    ```
    For each entry, run `bd show <id>` to retrieve the PR URL from bead notes. `kind: "feature-pr"` rows read "review and merge the feature PR"; `kind: "epic-pr"` rows read "review and merge the epic PR into main".
-5. Output the **Pending Human Action** summary:
+4. Output the **Pending Human Action** summary:
    ```
    ⏸️  Ralph is paused — human action required before work can continue.
 
@@ -190,25 +314,25 @@ Proceed here when no chore beads are in-flight, no `stage:*` chore beads are rea
 
    When you've completed the above, prompt me to continue.
    ```
-6. **Stop completely.** Do not continue the event loop. Wait for the user to re-prompt before doing any further work.
+5. **Stop completely.** Stop the wake mechanism as the wake section describes. Do not continue the event loop. Wait for the user to re-prompt before doing any further work.
 
 ---
 
 ## Shutdown
 
-When `bd list --status=in_progress --type=chore` returns no results AND `bd ready` returns no chore beads with `stage:*` labels:
+When nothing is in flight AND nothing is dispatchable — `inflight` holds no entries, `bd ready -l execution:afk` returns nothing (no `stage:*` chore, no childless feature to decompose, no ready, claimable chore-less task bead awaiting expansion) (_The in-flight invariant_ above):
 
-1. Regenerate `.agent-cortex/ralph/progress.md` one final time — do not delete it.
-2. For each **multi-feature** epic whose feature beads are all closed, open/update an epic PR to main (skip single-feature epics — no epic branch exists):
+1. For each **multi-feature** epic whose feature beads are all closed, open/update an epic PR to main (skip single-feature epics — no epic branch exists):
    ```bash
    gh pr create --base main --head epic/<epic-id> --title "[<epic-id>] Merge epic into main" --body "<epic summary>"
    ```
    Tag each epic bead with `awaiting-epic-pr-merge` until merged.
-3. Run:
+2. Run:
    ```bash
    bd dolt push
    ```
-4. If any HITL beads were noted during the session, output:
+   **Gate on the exit status.** Non-zero: retry once, then stop and report the command, exit code and stderr as a sync blocker — no completion summary, no "All beads complete.", and the remaining shutdown steps are not run.
+3. If any HITL beads were noted during the session, output:
    ```
    All agent work is complete. The following steps require human action before work can continue:
 
@@ -229,20 +353,27 @@ When `bd list --status=in_progress --type=chore` returns no results AND `bd read
 
 ## State Files
 
+Status is read from beads — there is no rendered status document to build or refresh:
+
+```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
+```
+
 | File | Purpose |
 |------|---------|
-| `.agent-cortex/ralph/progress.md` | Human-readable snapshot. Regenerate: `workspace="/abs/path"; pnpm --prefix skills/workflow/run-pipeline-stage/scripts exec tsx generate-progress.ts --workspace "$workspace" > "$workspace/.agent-cortex/ralph/progress.md"`. `workspace` must be an **absolute** path — never `.` or `$(pwd)`. **Never hand-edit.** |
-| `.agent-cortex/ralph/state.json` | Runtime bookkeeping only: the in-flight agent-ID→bead mapping. Shape: `{ "inflight": [ { "choreId": "...", "parentId": "...", "title": "...", "agentId": "...", "logLine": 1 } ] }`. Initialise at startup with `{ "inflight": [] }`. Update after every dispatch and every agent completion. **Never hand-edit.** |
+| `.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`). |
 
 All task state is derived from beads; `state.json` holds only runtime bookkeeping:
 
 | Question | How to answer |
 |----------|---------------|
-| What is in-flight? | `bd list --status=in_progress --type=chore` |
-| What is ready? | `bd ready` — filter for chores with `stage:*` labels |
+| What is in-flight? | The `inflight` entries in `.agent-cortex/ralph/state.json` — `kind: "stage"` for a dispatched stage chore, `kind: "decompose"` for a feature-decomposition worker, `kind: "expand"` for an expansion worker. Decomposition and expansion workers hold no chore, so beads alone under-report in-flight work. |
+| What is ready? | `bd ready -l execution:afk` — the single dispatch predicate. Each result is routed by its shape: a childless `feature` bead is decomposed (_Feature Decomposition_), a bead with no `stage:*` children is expanded (_Expansion Guard_), a `stage:*` chore is dispatched. |
 | What stage is a bead in? | Read the `stage:*` label from `bd show <id>` |
 | Which agent-ID maps to which bead? | `inflight` entries in `.agent-cortex/ralph/state.json` |
-| How many fix rounds? | Count chore beads with label `stage:fix` that are children of the parent task. Read `maxFixRounds` from `skills/planning/create-task/pipeline.json`. |
+| How many fix rounds? | Count chore beads with label `stage:fix` that are children of the parent task (`bd children <parent-id> --json | grep -c '"stage:fix"'`). Read `maxFixRounds` from `skills/planning/create-task/pipeline.json`. Read-only: used for the cap backstop, never to build remediation. |
 | Which features are review-gated? | `pendingHumanAction` entries with `kind: "feature-pr"` from `pending-gates.mjs` — unblocked `lifecycle:feature-pr` gates on either HITL axis. A gate in `parked` is pre-created but not yet actionable |
 | Which epics are review-gated? | `bd list -l awaiting-epic-pr-merge` |

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 `execution:hitl`** (or the legacy `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 `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).
-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 `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 no chores are in-flight and `bd ready` returns no `stage:*` chores, proceed to HITL Pause (REFERENCE.md) when `pendingHumanAction` is non-empty, 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 `pending-gates.mjs` reports a non-empty `pendingHumanAction`: 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. `skills/workflow/ralph/scripts/pending-gates.mjs` owns the gate predicate — parked vs pending — and is the only place the gate queries live.
-- 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.