@garygentry/feature-forge 0.3.2 → 0.3.5

package/adapters/cursor/skills/forge-5-loop/forge-5-loop.mdc

@@ -9,7 +9,7 @@ alwaysApply: false
 
 Execute the autonomous coding loop against a forge feature's backlog. The loop spawns a fresh agent session per backlog item, implementing each task with full verification.
 
-The loop **runner** is configured, not hardcoded. feature-forge talks to it through the `loopRunner` block in `forge.config.json`; rauf is the default and reference implementation (see `references/ralph-loop-contract.md`). Every command below is rendered from `loopRunner` with token substitution — there are no hardcoded `rauf …` commands in this skill, and even the human log filename is tokenized as `{loopRunner.logFile}`.
+The loop **runner** is configured, not hardcoded. feature-forge talks to it through the `loopRunner` block in `forge.config.json`; rauf is the default and reference implementation (see `references/ralph-loop-contract.md`). Every command below is rendered from `loopRunner` with token substitution — no hardcoded `rauf …` commands; even the human log filename is tokenized (`{loopRunner.logFile}`).
 
 ## Resolve the loop runner
 
@@ -42,13 +42,15 @@ Read and follow `references/shared-conventions.md` for feature name validation,
 
 Read `{resolvedFeatureDir}/.pipeline-state.json`. If not in force mode, `stages.forge-4-backlog` must be `complete`. If not, STOP and tell the user: "Backlog hasn't been created yet. Run `/feature-forge:forge-4-backlog {feature}` first."
 
+If the state's `notes` is non-empty, surface it before proceeding and treat it as run input — often backlog-time constraints; it never overrides specs or config (raise any conflict).
+
 ### 1b. Verification Check
 
 Read `stages.forge-verify-backlog` and branch on its status — **four** cases, in this order (the pending case must be tested *before* the generic one, or owed-and-dropped debt gets reported as never-scheduled):
 
 1. **`passed`** — proceed with no prompt.
-2. **`findings-applied`** — fixes were applied but nothing re-verified them: this status deliberately clears freshness, so the backlog's verification is still outstanding, not silently satisfied. Use the host's question mechanism to offer: **Re-verify first (recommended)** (`/feature-forge:forge-verify {feature} backlog`) · **Continue without re-verifying** — an explicit deferral, persisted via `state-verify --status skipped` (never by hand; add `--epic "{epic}"` for members) before the loop starts, so it is a recorded decision and not a walked-past gate.
-3. **`auto-verify-pending`** — automatic verification *was* scheduled for the backlog stage and the debt *was* durably recorded; it simply has not run. Say exactly that, naming the served stage and the retry command: *"{feature}: automatic verification is still pending for forge-4-backlog; run `/feature-forge:forge-verify {feature} backlog` to resolve it."* Then use the host's question mechanism to offer the same two choices as case 4. Never report this as "hasn't been verified yet" — "nobody ever asked for this" and "this was owed and dropped" are different facts and the operator acts on them differently.
+2. **`findings-applied`** — fixes were applied but nothing re-verified them: this status deliberately clears freshness, so the backlog's verification is still outstanding, not silently satisfied. Use the host's question mechanism to offer: **Re-verify first (recommended)** (`/feature-forge:forge-verify {feature} backlog`) · **Continue without re-verifying**. On continue, write **nothing**: `state-verify` refuses demoting `findings-applied` to `skipped` (#203); the recorded status already says re-verification is outstanding.
+3. **`auto-verify-pending`** — automatic verification *was* scheduled for the backlog stage and the debt *was* durably recorded; it simply has not run. Say exactly that, naming the served stage and the retry command: *"{feature}: automatic verification is still pending for forge-4-backlog; run `/feature-forge:forge-verify {feature} backlog` to resolve it."* Then use the host's question mechanism to offer the same two choices as case 4. Never report this as "hasn't been verified yet" — "nobody ever asked for this" and "this was owed and dropped" are different facts.
 4. **Anything else** (absent, `pending`, `skipped`, `findings-reported`) — use the host's question mechanism to warn with the cost of skipping: "Backlog hasn't been verified yet. Recommended: run `/feature-forge:forge-verify {feature}` first — the loop implements items autonomously and commits as it goes, so a bad item (wrong scope, missing dependency, untestable acceptance criteria) is far cheaper to catch now than after several commits build on it. Continue anyway?"
 
 Cases 3 and 4 offer the same choices: **Verify first (recommended)** · **Continue without verifying**. The proceed-anyway path is unchanged.
@@ -115,13 +117,17 @@ Verify the file exists on disk. If not, STOP and tell the user: "No backlog.json
 
 The runner commits each item onto the current branch. Skip if not a git repo or `branchPerFeature` is false. Otherwise run the **Branch Reconciliation** block in `references/shared-conventions.md` (it runs `reconcile-branch` and, on `warn-drift` — you are on the default branch — strongly recommends creating `{branchPrefix}{feature}` via the host's question mechanism before the loop commits; on `adopt-current` it updates the recorded branch to the current one, never pushing you back to a stale/imposed branch). Never hard-stop.
 
+### 1g. Stranded-Work Pre-flight (if using git)
+
+Run `git status --porcelain`. If it reports changes **and** `{backlogDir}/{loopRunner.stateDir}/state.json` exists from a previous run, **STOP**: name that run (its `startedAt`, `currentItem`, and `blockedItems` from `state.json`) and point the user at the **Post-Run Tree Reconciliation** section of `references/recovery-procedure.md` to commit / stash / discard the stranded work before relaunch — never auto-pass `--force`. If the tree is dirty with **no** prior-run `state.json`, keep today's behavior (surface it; let the user commit/stash or pass `--force`). A clean tree is silent. rauf's own launch refusal remains the backstop.
+
 ## Step 2: Construct the Loop Command
 
 ### 2a. Analyze Backlog
 
-Run the **list command** (`loopRunner.listCommand`, default `rauf backlog list . --backlog {backlogDir} --json`) and count items by status: `pending`, `in_progress`, `done`, `blocked`.
+Run the **list command** (`loopRunner.listCommand`, default `rauf backlog list . --backlog {backlogDir} --json`) and count items by status: `pending`, `in_progress`, `done`, `blocked`. Pipe that same list-command JSON into `backlog-topology --items-stdin --json` (a `forge-session.py` verb — invoke it via Step 3a's `$R` fence) and read `maxChainDepth` to report alongside the iteration count — advisory only: no prompt, no operator decision.
 
-Calculate the iteration count: `ceil((pending + in_progress) * loopIterationMultiplier)` where `loopIterationMultiplier` comes from `forge.config.json` (default: 1.5). This headroom allows retries without exhausting iterations.
+Calculate the iteration count: `ceil((pending + in_progress) * loopIterationMultiplier)` where `loopIterationMultiplier` comes from `forge.config.json` (default: 1.5, headroom for retries).
 
 If there are no pending or in_progress items, STOP and tell the user: "All backlog items are already done or blocked. Nothing to run."
 
@@ -134,8 +140,6 @@ If there are `blocked` items, note them — the user may want `--retry-blocked`.
 - If `backlogDir` is set in config: use the per-feature subpath `{backlogDir}/{feature}` (matching the 1e composition rule and forge-4-backlog §6.2).
 - Otherwise: use `{resolvedFeatureDir}` (the directory containing `backlog.json`).
 
-**Example:** If `specsDir` is `./specs` and feature is `auth`, `{backlogDir}` is `specs/auth`.
-
 ### 2c. Build Command
 
 Render the **run command** (`loopRunner.runCommand`) with token substitution, e.g. the rauf default becomes:
@@ -159,19 +163,20 @@ Backlog summary:
   - Done: {done}
   - Blocked: {blocked}
   - Iterations: {iterationCount} ({activeItems} items x {loopIterationMultiplier} multiplier)
+  - Max chain depth: {maxChainDepth} — depth bounds achievable progress regardless of iteration budget
 
 For the model-selection precedence (item.model > --model/options > project default >
 provider default), read references/runner-contract.md.
 ```
 
-**Run mode and full loop-runner contract:** follow `## Run mode (Step 2d, rauf)` and the remaining sections in `references/runner-contract.md` verbatim.
+**Run mode and full loop-runner contract:** follow `## Run mode (Step 2d, rauf)` and the remaining sections in `references/runner-contract.md` verbatim; `loopRunner.reviewMode` (`"always"`/`"never"`) suppresses the Run-mode question — semantics live there.
 
 #### Agent selection (gated on `loopRunner.agentArgument`)
 
 **Capability gate.** Everything below applies **only when** the effective `loopRunner.agentArgument` is present and non-empty. **When it is absent or empty, Step 2d is exactly the confirmation above — no probe, no agent question, no availability listing, no `Agent:` line — byte-identical to today** (REQ-PLUG-02, REQ-COMPAT-01). The full algorithm, precedence, and verbatim message shapes are in `## Agent selection` of `references/agent-selection.md`; read it. When the gate is on, augment Step 2d in order:
 
 - **(a) Probe once.** Before confirming, run `loopRunner.agentsProbeCommand` (default `{bin} agents --json`) **exactly once** (no retries, no second probe); it exits 0 with `{ agents: [...] }`. Parse `agents[]`; build the advertised set `{ row.id }` — this one parsed array drives (b)–(d).
-- **(b) Agent question.** Add an **"agent"** question to the same the host's question mechanism surface: **one option per advertised row** labelled `"{displayName} ({id}) — available/not found"`, **plus an explicit `"default (claude-cli)"` choice mapping to `run_selection = None`**. Resolve the pick (run > project, empty/whitespace unset, an explicit runner-default pick collapses to the default path) into `{resolved.agent, resolved.source}`. Precedence: `item.provider > --agent > project defaultAgent > runner default` (forge never reads a backlog item's provider).
+- **(b) Agent question.** Add an **"agent"** question to the same the host's question mechanism surface: **one option per advertised row** labelled `"{displayName} ({id}) — available/not found"`, **plus an explicit `"default (claude-cli)"` choice mapping to `run_selection = None`**. Resolve the pick (run > project, empty/whitespace unset, an explicit runner-default pick collapses to the default path) into `{resolved.agent, resolved.source}`. Precedence: `item.provider > --agent > project defaultAgent > runner default` (forge never reads a backlog item's provider). Under `loopRunner.agentMode: "auto"`, skip this question (`run_selection = None`); (a)/(c)/(d)/(d-model) still run — see `references/agent-selection.md`.
 - **(c) Availability listing.** From the **same** parsed `agents[]` (no second probe), list `id` / `displayName` / available (`yes`/`no`, `detail` on unavailable rows).
 - **(d) Verdict** — only for a **non-default** resolved agent (default path `None`/`claude-cli` → no probe, byte-identical to today). Classify by **membership** then `available` (never by exit code): **UNKNOWN** (`∉` set) → **hard-reject BEFORE any loop side-effect**, error lists the **sorted** valid ids, **NO proceed-anyway**; **UNAVAILABLE** (member, `available False`) → warn with `detail`, the host's question mechanism offering **proceed-anyway OR choose-another** (re-presents the same `agents[]`), never silent; **AVAILABLE** → proceed, the validated id fills `{agent}`; **probe failure** (non-zero exit / unparseable / missing or empty `agents[]` / row lacking `id`) → surface it, offer **choose-another OR abort**, **never launch the non-default agent unvalidated** and never silently fall back to the default.
 - **(d-model) Claude-only model-alias guard.** Runs **only** when the resolved agent is **non-default** (not the default / `claude-cli` path). Read the backlog.json (Step 1e path); collect items whose `model` is a **Claude-specific alias** (tier `opus`/`sonnet`/`haiku` or a `claude-*` id). **If none, skip silently.** Otherwise warn before launch via the host's question mechanism (NOT prose): `item.model` outranks `--agent`, so the alias is forwarded verbatim to `{agent}`, which will likely reject it (e.g. codex 400 *"The 'sonnet' model is not supported…"*) — every spawn exits 1 and rauf circuit-breaks (*"3 consecutive infra failures — halting"*) with no hint of the cause. Offer: **(1) Strip `model` for this run (recommended)** — rewrite backlog.json removing the `model` key from each affected item (persistent edit; re-run forge-4-backlog to restore), then proceed; **(2) Proceed as-is** — only safe if `{agent}` understands the pinned ids. forge touches only `model`, never `provider`. Full rationale: `references/agent-selection.md`.
@@ -194,7 +199,7 @@ Then commit this state write before launching (mandatory). The runner refuses to
 
 ### 3b. Launch Background Process
 
-Launch the loop **backgrounded** (the host's background-execution mechanism) so it survives session end and does not block the session. For a runner that **persists its own structured event file** (the default — rauf writes `{stateDir}/events.ndjson` natively and rotates it per run), launch the **plain `runCommand`** with **no stdout redirect** and supervise the runner's **native** `events.ndjson` directly; do **not** redirect `--ndjson` into `{stateDir}` (it is redundant and collides with the runner's own writer — see `references/runner-contract.md`). Only a stdout-only runner (no native event file) uses `eventStreamCommand`, redirected to a file **outside** `{stateDir}`. The background task's exit notification is the single authoritative terminal signal (Step 4). Loop runs can take significant time (minutes to hours depending on backlog size). For the exact launch commands (incl. the `mkdir -p` state-dir guard and the root→`IS_SANDBOX` sandbox guard) and the self-persisting vs. stdout-only detail, read `references/runner-contract.md`.
+Launch the loop **backgrounded** (the host's background-execution mechanism) so it survives session end and does not block the session. For a runner that **persists its own structured event file** (the default — rauf writes `{stateDir}/events.ndjson` natively and rotates it per run), launch the **plain `runCommand`** with **no stdout redirect** and supervise the runner's **native** `events.ndjson` directly; do **not** redirect `--ndjson` into `{stateDir}` (it is redundant and collides with the runner's own writer — see `references/runner-contract.md`). Only a stdout-only runner (no native event file) uses `eventStreamCommand`, redirected to a file **outside** `{stateDir}`. The background task's exit notification is the single authoritative terminal signal (Step 4). For the exact launch commands (incl. the `mkdir -p` state-dir guard and the root→`IS_SANDBOX` sandbox guard) and the self-persisting vs. stdout-only detail, read `references/runner-contract.md`.
 
 ### 3c. Inform User
 
@@ -203,21 +208,12 @@ Follow the **Inform-user output template (Step 3c)** section of `references/runn
 ### 3d. Arm a Monitor on the event stream, and react to events
 
 Arm the **host's monitoring mechanism** on the structured event stream (the NDJSON file, or the
-human log as fallback) so events flow back into this session as they happen. Use
-**`persistent: true`** — runs can exceed the host's monitoring mechanism's maximum `timeout_ms` (1 hour),
-and a bounded timeout would silently stop watching a still-running loop. The filter
-MUST match every terminal and exception state, not just the happy path (silence is
-not success). Monitor the **structured** surface, never raw `RAUF_*` tokens.
-
-Each Monitor event arrives as a message; react per type — surface `needs_human` /
-`loop_error` immediately with a `PushNotification`, coalesce `item_completed` into
-milestones, and treat `llm_stuck_warning` as a hang warning. A `needs_human` /
-`blocked` signal does **not** pause the loop — the runner sets the item aside and
-keeps going.
-
-For the exact Monitor commands (NDJSON `jq` filter and the log-fallback `grep`
-prefixes), the coverage-complete filter event list, and the full per-event reaction
-rules, read `references/runner-contract.md`.
+human log as fallback) with **`persistent: true`**, a coverage-complete filter
+matching every terminal and exception state (silence is not success), and react to
+each event as it arrives. The exact Monitor commands, the filter event list, and the
+full per-event reaction rules (`needs_human` / `loop_error` surfaced immediately with
+a `PushNotification`, `item_completed` coalesced into milestones, `llm_stuck_warning`
+as a hang warning) are in `references/runner-contract.md` — follow them verbatim.
 
 ### 3f. Reach completion
 
@@ -233,12 +229,16 @@ Run the **status-json command** (`loopRunner.statusJsonCommand`) and read
 `backlogSummary` for the authoritative counts — it separates the three non-done
 outcomes: genuine `blocked`, `needsHuman`, and runner-`deferred` ("false blocks").
 Fall back to the **list command** (`loopRunner.listCommand`) if `statusJsonCommand`
-is not configured. You will already have most of this from the live tally in 3e. If the run used a review flag (e.g. rauf's `--review`), also read any `review_completed` event (event stream, or `{loopRunner.stateDir}/events.ndjson`) for its `itemsCreated`/`summary` to surface in 4b — see `references/result-reporting.md`.
+is not configured. If the run used a review flag (e.g. rauf's `--review`), also read any `review_completed` event (event stream, or `{loopRunner.stateDir}/events.ndjson`) for its `itemsCreated`/`summary` to surface in 4b — see `references/result-reporting.md`.
 
 ### 4b. Report Results
 
 Present a summary to the user. Pick **every** branch that applies (a run can be both
-blocked and needs-human) and render its report. The five verbatim result-report output templates — **all-done**, **needs-human**, **blocked**, **deferred**, and **pending** (iteration limit reached) — are in `references/result-reporting.md`, together with the Step 7 `LoopOutcome` ladder these same counts feed. The reports are descriptive only: they carry no next command, and the run does not end here. If the authoritative counts cannot be obtained at all (4a failed or its output does not parse), follow **Operational failure before the counts are known** in that same file: surface the failure and its recovery, and close nothing — no outcome, no stage exit, no terminal block.
+blocked and needs-human) and render its report. The five verbatim result-report output templates — **all-done**, **needs-human**, **blocked**, **deferred**, and **pending** (with a conditional cause) — are in `references/result-reporting.md`, together with the Step 7 `LoopOutcome` ladder these same counts feed. The reports are descriptive only: they carry no next command, and the run does not end here. If the authoritative counts cannot be obtained at all (4a failed or its output does not parse), follow **Operational failure before the counts are known** in that same file: surface the failure and its recovery, and close nothing — no outcome, no stage exit, no terminal block.
+
+### 4c. Post-Run Recovery Pass (unconditional)
+
+Run the **Post-Run Recovery Procedure** (`references/recovery-procedure.md`) now — on **every** run close, before Step 5 writes state, so the tree it inspects is exactly what the run left. The live `needs_human` handler (3d) collects answers early but is **not** the entry condition: a run that emitted no event still enters here — this is what makes the plain-blocked unblock reachable on blocked-only runs. With nothing to decide, its step 1 skips straight to the §4 tree reconciliation — silent on a clean tree. A run can strand uncommitted work with no signal (items failing a shared final acceptance criterion are never committed); this pass reconciles it — 1g's pre-flight is only the next-launch backstop. Its step-7 gate feeds Step 7's `resolved` rung; the stage still closes exactly once, in Step 7.
 
 ## Step 5: Update Pipeline State
 
@@ -254,9 +254,9 @@ python3 "$R/scripts/forge-session.py" state-complete --feature "{feature}" --sta
 
 ## Step 5b: Offer Impl-Verify (standalone path)
 
-**Gate:** run only if (a) the feature's `.pipeline-state.json` has **no** `epic` key **and** (b) Step 5 set `stages.forge-5-loop.status` to `complete`. Otherwise **skip** straight to Step 7 — a non-complete run has nothing to verify yet, and epic members get the equivalent offer in Step 6.1 (do **not** prompt twice). This standalone counterpart to Step 6.1 nudges verification interactively rather than via the easily-missed "Next steps" text. Use the host's question mechanism (NOT inline prose) to offer: *"{feature}'s loop is complete. Recommended: run `/feature-forge:forge-verify {feature} impl` to audit the implementation before generating docs. Run it now, or skip to forge-6-docs?"* On **run**, invoke `feature-forge:forge-verify {feature} impl` with the literal `owner: nested` token in the dispatching prompt — this dispatch happens inside the loop stage, so **you** remain the sole terminal owner and the branch skill returns its structured result and prints no terminal block of its own (see "Branch ownership: the `owner:` token" in `references/stage-exit-protocol.md`). On **skip**, persist the skip through `state-verify` using the fence below (mirrors `forge-4-backlog`'s skip handling) — the forge-6-docs backstop re-surfaces the skip. Either way, do **not** name a next command here: Step 7 routes, and it routes differently depending on what this step recorded.
+**Gate:** run only if (a) the feature's `.pipeline-state.json` has **no** `epic` key **and** (b) Step 5 set `stages.forge-5-loop.status` to `complete`. Otherwise **skip** straight to Step 7 — a non-complete run has nothing to verify yet, and epic members get the equivalent offer in Step 6.1 (do **not** prompt twice). This standalone counterpart to Step 6.1 nudges verification interactively. Use the host's question mechanism (NOT inline prose) to offer: *"{feature}'s loop is complete. Recommended: run `/feature-forge:forge-verify {feature} impl` to audit the implementation before generating docs. Run it now, or skip to forge-6-docs?"* On **run**, invoke `feature-forge:forge-verify {feature} impl` with the literal `owner: nested` token in the dispatching prompt — this dispatch happens inside the loop stage, so **you** remain the sole terminal owner and the branch skill returns its structured result and prints no terminal block of its own (see "Branch ownership" and "Caller-side resumption" in `references/stage-exit-protocol.md`; a delegate-and-resume site — on return, control resumes here). A verifier return without its report structure is a dropped digest, not a result (issue #183) — apply "Truncated Verifier Returns" in forge-verify's `findings-template.md` reference (resume or re-dispatch) before recording anything. On **skip**, persist the skip through `state-verify` using the fence below (mirrors `forge-4-backlog`'s skip handling) — the forge-6-docs backstop re-surfaces the skip. Either way, do **not** name a next command here: Step 7 routes, and it routes differently depending on what this step recorded.
 
-**The skip is written by `state-verify`, never by hand.** Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol in `references/shared-conventions.md`. On exit 2, surface the plain `Error:` line verbatim and stop: the skip is not persisted, so Step 7 would route on state that is not on disk.
+**The skip is written by `state-verify`, never by hand — and never over a resolved entry** (`passed`/`findings-applied`: the verb refuses that demotion, #203 — skip the fence and continue). Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol in `references/shared-conventions.md`. On exit 2, surface the plain `Error:` line verbatim and stop: the skip is not persisted, so Step 7 would route on state that is not on disk.
 
 ```bash
 R="$(bash -c 'for d in "${FEATURE_FORGE_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
@@ -268,7 +268,7 @@ python3 "$R/scripts/forge-session.py" state-verify --feature "{feature}" --stage
 
 **Gate:** only run this step if (a) the resolved feature's `.pipeline-state.json` has an `epic` key **and** (b) Step 5 set `stages.forge-5-loop.status` to `complete` (all backlog items done). If either is false, **skip** straight to Step 7 — standalone completed features are handled by Step 5b, and a non-complete run has no handoff to make (REQ-COMPAT-01).
 
-1. **Offer impl-verify first (recommended, skippable).** Per the completion rule (`00-core-definitions.md §7`), a feature whose `forge-verify-impl.status == findings-reported` does **not** unblock dependents. Use the host's question mechanism (NOT inline prose) to offer: *"{feature}'s loop is done. Recommended: run `/feature-forge:forge-verify {feature} impl` before unblocking dependents. Run it now, or skip and continue the handoff?"* On **run**, invoke `feature-forge:forge-verify {feature} impl` with the literal `owner: nested` token in the dispatching prompt — this dispatch happens inside the loop stage, so **you** remain the sole terminal owner and the branch skill returns its structured result and prints no terminal block of its own (see "Branch ownership: the `owner:` token" in `references/stage-exit-protocol.md`). On **skip**, persist the skip through `state-verify --status skipped` using Step 5b's fence (add `--epic "{epic}"` — required for members) so the Step 7 exit reads a recorded decision instead of re-asking the question the user just answered; completion is then judged on the §7 rule with impl-verify explicitly skipped.
+1. **Offer impl-verify first (recommended, skippable).** Per the completion rule (`00-core-definitions.md §7`), a feature whose `forge-verify-impl.status == findings-reported` does **not** unblock dependents. Use the host's question mechanism (NOT inline prose) to offer: *"{feature}'s loop is done. Recommended: run `/feature-forge:forge-verify {feature} impl` before unblocking dependents. Run it now, or skip and continue the handoff?"* On **run**, dispatch exactly as Step 5b does — the same literal `owner: nested` token in the dispatching prompt (you remain the sole terminal owner), the same truncated-return guard before recording anything, and the same declared resume (control returns here; the handoff continues at 2). On **skip**, persist the skip through `state-verify --status skipped` using Step 5b's fence (add `--epic "{epic}"` — required for members) so the Step 7 exit reads a recorded decision instead of re-asking the question the user just answered; completion is then judged on the §7 rule with impl-verify explicitly skipped.
 2. **Recompute and announce.** Run `render-status "{epic}" --specs-dir "{specsDir}" --json`. Announce the feature's completion and the epic rollup (e.g. "2/4 features complete") — derived live from disk, never re-computed in prose.
 3. **Announce what is actionable — do not route.** Read `render-status`'s `actionable` set (every dependency now complete, not itself complete) and say plainly which members can start now, or which are still blocked and on which dependencies. This is context for the user, not a handoff: the Step 7 exit consumes the same live payload and fences the one authoritative next command itself, so do **not** present a next-feature picker, offer to author a member's PRD, or repeat a member's `nextCommand` here. Two competing actions is exactly the ambiguity the scripted exit removes.
 4. **Commit (REQ-OBS-01).** When `gitCommitAfterStage` is true, commit the Step 5 completion write (and any manifest `updatedAt` bump) via the shared-conventions **Git Commit Protocol**, staging the epic subtree so the member state change commits atomically: `git add {specsDir}/{epic}/` then `{commitPrefix}({feature}): complete loop`. If `gitCommitAfterStage` is false, skip the commit. Then fall through to Step 7 — the epic handoff closes there, once, like every other path.
@@ -277,7 +277,7 @@ python3 "$R/scripts/forge-session.py" state-verify --feature "{feature}" --stage
 
 Every loop run ends here, and ends here **exactly once** — standalone or epic member, complete or not.
 
-First select the single `LoopOutcome` with the ladder in `references/result-reporting.md` (`needs-human` → `blocked` → `deferred` → `partial` → `complete`, first match wins), reading it from Step 4a's authoritative counts and never from the runner's process exit code. If those counts were never obtained, follow that file's operational-failure rule instead: report the failure and its recovery and run no exit at all.
+First select the single `LoopOutcome` with the ladder in `references/result-reporting.md` (`resolved` → `needs-human` → `blocked` → `deferred` → `partial` → `complete`, first match wins), reading it from Step 4a's authoritative counts and never from the runner's process exit code. If those counts were never obtained, follow that file's operational-failure rule instead: report the failure and its recovery and run no exit at all.
 
 **Close this stage with the Scripted Stage Exit** (contract: `references/stage-exit-protocol.md`; do not improvise a "Next steps" list). Run:
 
@@ -293,13 +293,13 @@ Add `--epic "{epic}"` when this feature is an epic member — required, per the
 
 ## Gotchas
 
-- **Plugin-root discovery (1b-epic helper) covers installed paths, not workspace-dev checkouts.** The `forge-root.sh` search in 1b-epic probes `~/.claude/skills/feature-forge`, `~/.claude/plugins/cache/*/feature-forge/*` (marketplace-cache installs), `~/.claude/plugins/*/feature-forge`, and `./.agents/skills/feature-forge` — the locations of an **installed** plugin. A feature-forge **source checkout** (e.g. `~/workspace/feature-forge`) is not on that list, so the helper exits "cannot locate plugin root." That is expected in a dev environment, not a bug; run the epic-manifest script from the checkout directly (`python3 <checkout>/scripts/epic-manifest.py …`). The bootstrap prelude wraps its candidate loop in `bash -c` so the `~/.claude/plugins/*/feature-forge` glob is zsh-safe: an empty expansion no longer aborts the loop under zsh's `nomatch`.
+- **Plugin-root discovery (1b-epic helper) covers installed paths, not workspace-dev checkouts.** The `forge-root.sh` search probes the locations of an **installed** plugin only, so a feature-forge **source checkout** (e.g. `~/workspace/feature-forge`) exits "cannot locate plugin root." Expected in a dev environment; run the epic-manifest script from the checkout directly (`python3 <checkout>/scripts/epic-manifest.py …`). The bootstrap prelude wraps its candidate loop in `bash -c` so the `~/.claude/plugins/*/feature-forge` glob is zsh-safe: an empty expansion no longer aborts the loop under zsh's `nomatch`.
 - `{backlogDir}` is a **directory path**, not a file path. Pass `specs/auth`, not `specs/auth/backlog.json`.
-- rauf resolves `RAUF.md` with fallback (`{backlogDir}/.rauf/RAUF.md` first, then the project's `.rauf/RAUF.md`) — found as long as the runner is installed in the project. State files (state.json, {loopRunner.logFile}, etc.) are created at `{backlogDir}/{loopRunner.stateDir}/`, within the feature's spec directory (expected) and isolated per backlog dir, so concurrent features don't collide.
-- If the session disconnects during a long-running loop, the runner process continues independently — the user can check results later with the status / list commands. If a previous run left a stale lock, the user may need to pass `--force` to clear it (rauf reports this error clearly).
-- Never run the run command in the foreground (without the host's background-execution mechanism) — it blocks and will hit the Bash tool timeout for any non-trivial backlog. "Don't block the foreground" is NOT "stay silent": supervise via the host's monitoring mechanism (3d), never `sleep`/poll in the foreground. The host's monitoring mechanism must use `persistent: true` (not a bounded `timeout_ms`), watch the **structured** surface (`events.ndjson`), and never filter on raw `RAUF_*` tokens — they appear in agent prose and false-match. A `needs_human`/`blocked`/`review` signal does **not** pause the loop — the runner sets the item aside and keeps going; surface it live but don't tell the user the loop is waiting. See `references/runner-contract.md` for the full monitoring rules.
+- rauf resolves `RAUF.md` with fallback (`{backlogDir}/.rauf/RAUF.md` first, then the project's `.rauf/RAUF.md`). State files (state.json, {loopRunner.logFile}, etc.) land at `{backlogDir}/{loopRunner.stateDir}/`, isolated per backlog dir, so concurrent features don't collide.
+- If the session disconnects mid-loop, the runner process continues independently — check results later with the status / list commands. A stale lock from a previous run may need `--force` to clear.
+- Never run the run command in the foreground (without the host's background-execution mechanism) — it blocks and will hit the Bash tool timeout for any non-trivial backlog. "Don't block the foreground" is NOT "stay silent": supervise via the host's monitoring mechanism (3d) — `persistent: true`, the **structured** surface (`events.ndjson`), never raw `RAUF_*` tokens (they false-match in agent prose). A `needs_human`/`blocked`/`review` signal does **not** pause the loop — the runner sets the item aside and keeps going; surface it live but don't tell the user the loop is waiting. See `references/runner-contract.md` for the full monitoring rules.
 - The version gate (1c) uses the `--json` form on purpose; never parse `rauf version`'s human output.
-- **Implementation artifacts must not cite specs.** The loop should **read** the specs and `backlog.json` freely — they are the source of truth for what to build, and the backlog rightly references specs for provenance. But the artifacts the loop **writes into the target repo** (source code, generated `SKILL.md`/agent files, configs, code comments) must be **self-contained**: they must NOT reference feature-forge spec files (no `See specs/{feature}/NN-*.md`, no "source spec" provenance notes in shipped output). Specs are pre-implementation inputs that may be archived or deleted once the feature ships; the implementation must stand on its own. This applies only to shipped implementation output — never to the backlog or spec documents, which should keep citing specs.
+- **Implementation artifacts must not cite specs.** The loop should **read** specs and `backlog.json` freely — they are the source of truth, and the backlog rightly cites specs for provenance. But artifacts the loop **writes into the target repo** (source code, generated `SKILL.md`/agent files, configs, code comments) must be **self-contained**: no references to feature-forge spec files (no `See specs/{feature}/NN-*.md`, no "source spec" provenance notes) — specs are pre-implementation inputs that may be archived or deleted once the feature ships. This applies only to shipped implementation output, never to the backlog or spec documents, which keep citing specs.
 
 ---
 

package/adapters/cursor/skills/forge-5-loop/references/agent-selection.md

@@ -21,6 +21,22 @@ Step 3c are byte-identical to today (capability gate;
 item.provider  >  --agent (run selection)  >  loopRunner.defaultAgent (project)  >  runner default (claude-cli)
 ```
 
+**`loopRunner.agentMode` gate (`"prompt"` default | `"auto"`).** `"prompt"`
+presents the Step 2d agent question (SKILL sub-step b) — byte-identical to today.
+`"auto"` suppresses **only the interactive pick**: skip the agent question and
+resolve as if the user made no per-run selection (`run_selection = None`, so
+`defaultAgent` — or the runner default when unset — applies). Everything else on
+this surface **still runs under `"auto"`**: the single probe, the availability
+listing, the verdict classification below (UNKNOWN hard-reject before any loop
+side-effect, UNAVAILABLE with its proceed-anyway/choose-another question,
+probe-failure handling), and the Claude-only model-alias guard — those questions
+are safety surfaces, not the pick, and are never suppressed. The resolved
+`Agent: {id} (source: …)` line still shows in the confirmation and the Step 3c
+template, so the choice is never hidden. Meaningless when
+`loopRunner.agentArgument` is absent — the capability gate above already removes
+the entire surface, and `agentMode` adds no second gate. An unrecognized value
+behaves as `"prompt"`.
+
 **Run-layer mapping — why forge never re-implements rauf's resolver.** forge owns
 **only** its run and project layers and collapses them into **one** value
 (`resolve()`: `run_selection or defaultAgent or none`), which it emits as a single
@@ -78,7 +94,7 @@ supported when using Codex with a ChatGPT account."* — so **every** spawn exit
 rauf reports *"Circuit breaker: 3 consecutive infra failures — halting"* with no hint
 of the real cause. forge-5-loop therefore detects Claude-specific `model` aliases in
 the backlog (tier aliases `opus`/`sonnet`/`haiku` or `claude-*` ids) and, before
-launch, **warns** and offers (via `AskUserQuestion`) to **strip `model` for this run**
+launch, **warns** and offers (via the host's question mechanism) to **strip `model` for this run**
 (remove the key from each affected item so each spawn uses the agent's own default) or
 **proceed as-is**. forge only ever touches the `model` field — never `provider`. The
 default / `claude-cli` path skips this guard (the aliases are valid there).

package/adapters/cursor/skills/forge-5-loop/references/ralph-loop-contract.md

@@ -58,9 +58,12 @@ defined authoritatively in rauf's
 > item aside and **keeps working other runnable items to completion** (rauf:
 > `runner.ts` needs_human handler). So a supervising session can surface those
 > events live (visibility) and cancel early, but it cannot inject an answer and
-> resume the set-aside item mid-run — resolution is a follow-up retry pass. A
-> first-class pause/resume-with-answer capability is a desirable runner
-> enhancement (see `plans/rauf-enhancement-recommendations.md`).
+> resume the set-aside item mid-run — resolution is the **Post-Run Recovery
+> Procedure** (`skills/forge-5-loop/references/recovery-procedure.md`): record the
+> answer via `decision-record` at the moment of collection, then drive recovery
+> from the record after the run ends. A first-class pause/resume-with-answer
+> capability is a desirable runner enhancement (see
+> `plans/rauf-enhancement-recommendations.md`).
 
 ## rauf is the default and reference implementation
 

package/adapters/cursor/skills/forge-5-loop/references/recovery-procedure.md

@@ -0,0 +1,349 @@
+# forge-5-loop — Post-Run Recovery Procedure
+
+The named procedure that turns a needs-human / blocked loop stop into a resumable backlog
+without losing the operator's decision. It runs **after** a loop run ends — entered
+**unconditionally** from SKILL Step 4c on every run close, whatever the counts say (the
+`needs_human` / `item_blocked` live-event handling in `runner-contract.md` collects
+answers early for it, but is **not** the entry condition) — and it runs again as the
+**re-entry point** on a fresh session (§3).
+Its seven ordered steps: **enumerate → cluster → consolidated prompts →
+record-at-collection → apply → prove → gate & exit**.
+
+Notation: `{backlogDir}` is the resolved backlog directory (SKILL Step 2b);
+`{stateDir}` is the effective-config `loopRunner.stateDir` (default `.rauf`); `$R` is the
+plugin root the SKILL's bootstrap prelude resolves; runner commands are the substituted
+`loopRunner.*Command` forms with the SKILL's token substitution (`{bin}` etc.).
+
+## 1. Scope and the failure rule
+
+The procedure orchestrates scripted substrate; it never improvises state. Decisions live
+in `{backlogDir}/{stateDir}/forge-decisions.json` — append-only, written **only** by the
+`decision-record` / `decision-list` / `decision-apply` verbs of
+`scripts/forge-session.py` (schema: `references/forge-decisions-schema.json`), never by
+hand. Being under the git-ignored state dir, the record survives session end and context
+clear but never dirties the working tree that §4 inspects.
+
+**The failure rule (applies to every step).** Any scripted step that exits non-zero, and
+any runner invocation that errors or returns unparseable output, is surfaced **verbatim**
+and **STOPS** the procedure with a **failed recovery** report — never reported as
+recorded/succeeded. A failed *apply* (step 5) is distinguishable from a
+ran-but-nothing-moved *proof* failure (step 6) because the former never reaches step 6
+(§6).
+
+## 2. The seven steps
+
+### Step 1 — Enumerate
+
+- **Input:** `{backlogDir}`; the runner's authoritative item list.
+- **CLI:**
+  ```
+  python3 "$R/scripts/forge-session.py" decision-list --backlog-dir {backlogDir} --unapplied --json
+  {bin} backlog list . --backlog {backlogDir} --json      # the substituted listCommand
+  ```
+  The unapplied set is the **latest entry per `itemId` with `appliedAt == null`** —
+  deferrals included, applied items excluded.
+- **Decision point:** if the unapplied set is **empty** and no item is
+  `blocked`/`needsHuman`, there is nothing to decide or apply: **skip steps 2–6 and go
+  straight to step 7 — never exit around it.** Step 7's §4 tree reconciliation still
+  runs (it is what catches work stranded without any signal), and its `resolved` gate
+  does not apply — **an empty affected set never selects `resolved`**; the SKILL Step 7
+  ladder falls through to its count-based rungs. Combined with the clean-tree silence
+  of §4.1, this keeps a happy-path run free of any new prompt; the only new happy-path
+  output is the Step 2a depth line.
+- **Output:** the unapplied-decision set (each entry's `itemId`, `question`,
+  `answer|null`, `deferred`, `clusterId?`), and the live blocked/needs-human item set.
+- **Error:** a `decision-list` exit 2 (unknown dir, unparseable record) stops the
+  procedure. A failed `listCommand` read stops it as a failed recovery.
+
+### Step 2 — Cluster
+
+- **Input:** the blocked/needs-human items from step 1, each carrying its
+  `blockedReason` (where the runner lands the `RAUF_NEEDS_HUMAN:<reason>` text).
+- **CLI:**
+  ```
+  python3 "$R/scripts/forge-session.py" backlog-topology --items-stdin --cluster --json  < items.json
+  ```
+  fed the **same** `listCommand` JSON already obtained (single data source — never a
+  `backlog.json` path). Returns `clusters[]`: each with `memberIds`, `memberReasons`,
+  `sharedTokens`, and the **union** of members' gated subtrees (`gatedIds` +
+  `gatedCount`).
+- **Decision point:** you **may merge or refine** candidate clusters by judgment —
+  under-clustering is the deliberately-chosen failure direction of the scripted helper,
+  so its clusters are a floor, not a ceiling. You have no scripted *split* authority.
+- **Output:** the final cluster set (scripted candidates ± your merges), each with its
+  member ids and blast-radius numbers.
+- **Error:** a `backlog-topology` exit 2 stops the procedure.
+
+### Step 3 — Consolidated prompts
+
+- **Input:** the final cluster set from step 2.
+- **Mechanism:** the host's question mechanism (never inline prose).
+  - For any cluster of **two or more** items: emit **exactly one** consolidated question
+    that **names every affected item id** and states the **full gated subtree** the
+    cluster gates. Frame it by **blast radius** — e.g. *"This one decision gates 13 of
+    16 backlog items (items 2, 3, …). Answer it once."* — never one prompt per member.
+  - Singleton clusters prompt per item (today's per-item shape).
+- **Security:** prompts **MUST NOT solicit secrets**. Ask for the *decision* (which
+  path, which policy), never a credential/token/key value. The decision record has no
+  credential-shaped field and is treated as repo-visible content.
+- **Decision point:** the operator may **answer**, **defer** the decision, or request
+  **cancel the run early** — all three branches proceed to step 4 (nothing is acted on
+  before it is recorded).
+- **Output:** per cluster/item, one of {answer text, deferral, cancel-early}.
+- **Citation:** the blast-radius framing is derived from `backlog-topology --cluster`
+  gated-subtree output (member ids + counts) — the prompt cites that source; a
+  "gates N/M" claim the topology output contradicts is a defect.
+
+### Step 4 — Record at collection
+
+- **Input:** every branch outcome from step 3.
+- **CLI (one call per decision, BEFORE anything is applied):**
+  ```
+  # answered singleton
+  python3 "$R/scripts/forge-session.py" decision-record --backlog-dir {backlogDir} \
+      --item ID --question "Q" --answer "A"
+  # deferred, or cancel-early (both record a deferral: no --answer)
+  python3 "$R/scripts/forge-session.py" decision-record --backlog-dir {backlogDir} \
+      --item ID --question "Q" --deferred
+  # consolidated answer: one entry per affected item, shared clusterId
+  python3 "$R/scripts/forge-session.py" decision-record --backlog-dir {backlogDir} \
+      --item ID1 --item ID2 --item ID3 --question "Q" --answer "A" --cluster c1
+  ```
+  (`--actor` defaults to `forge-5-loop@<host>` — a machine label, never user identity.)
+- **Decision point:** a decision is recorded on **every** branch — answered, deferred,
+  **and** cancel-early — and it is recorded **before** step 5 acts on anything. A
+  cancel-early is recorded as a **deferral** (`answer: null`, `deferred: true`,
+  `question` carrying the original needs-human text) — there is no third entry form. A
+  recorded-but-unapplied entry (`appliedAt == null`) is exactly what step 1 re-surfaces
+  on the next launch (§3).
+- **Consolidated:** one entry per affected item, all sharing one `clusterId` (minted
+  `c` + lowest member id). Items stay **independently re-decidable**: a later per-item
+  entry supersedes the cluster entry for that item only.
+- **Output:** durable append-only entries in `forge-decisions.json`; the write is
+  atomic.
+- **Error:** any `decision-record` exit 2 (both/neither of `--answer`/`--deferred`,
+  unknown dir, failed atomic write) is surfaced verbatim and stops the procedure. The
+  answer is **not** applied if it was not recorded.
+
+### Step 5 — Apply
+
+- **Version probe (once, at the start of this step):** run the substituted
+  `loopRunner.versionCommand` (default `{bin} version --json`), parse
+  `{ "version": "<semver>" }`, and numerically semver-compare it against
+  `RECOVERY_MIN_RUNNER_VERSION` (a `scripts/forge-session.py` module constant, `0.14.0`
+  — the capability threshold for `{bin} backlog answer`; **not**
+  `loopRunner.minRunnerVersion`, which stays the launch floor). A probe miss
+  (missing/old/unparseable version) is **never** a hard failure — it selects the
+  degraded path and is reported with `loopRunner.installHint`.
+- **Apply per item** (full dispatch table in §5):
+  - needs-human item, runner **≥** threshold →
+    `{bin} backlog answer . {id} "{answer}" --backlog {backlogDir} --json`
+    (the answer text is threaded into the next iteration's prompt).
+  - needs-human item, runner **<** threshold → **degraded path:**
+    `{bin} backlog unblock . {id} --backlog {backlogDir} --json` — the item is genuinely
+    unblocked and the answer stays durable in `forge-decisions.json`, but the recovery
+    report **must state explicitly** that the answer was **not** injected into the next
+    iteration's prompt, with the `installHint` upgrade hint attached.
+  - plain (non-needs-human) blocked item → `{bin} backlog unblock` at **every** runner
+    version.
+- **Stamp:** after each runner apply **succeeds**, run
+  ```
+  python3 "$R/scripts/forge-session.py" decision-apply --backlog-dir {backlogDir} --item ID
+  ```
+  which stamps `appliedAt`/`appliedBy` on the item's latest entry. `decision-apply` is
+  called **only after** the runner apply returned success — a stamped record means the
+  runner actually accepted the change.
+- **Error:** a runner apply that **errors** (non-zero exit — item missing, not
+  `blocked`, or any failure) is a **failed apply**: surface it verbatim, do **not** call
+  `decision-apply`, stop the procedure, report failed recovery. This is distinct from a
+  version-probe miss (which routes to the degraded path, not a failure) and from step
+  6's ran-but-nothing-moved failure (§6).
+
+### Step 6 — Prove
+
+- **Input:** the affected item set that step 5 applied.
+- **CLI:** re-read per-item state via the substituted `loopRunner.listCommand`
+  (`{bin} backlog list . --backlog {backlogDir} --json`) and test **each** affected
+  item: `status != "blocked"` — which, per the runner's derivation
+  (needs-human ⇔ `status=="blocked" && needsHuman==true`), also removes it from the
+  needs-human count, so the single test covers both flags. Aggregate `backlogSummary`
+  counts are **never** the test. An affected item **missing** from the re-read counts
+  as a non-mover.
+- **Decision point:** **all** affected items moved → proceed to step 7. **Any**
+  non-mover — including a partial move where some items moved and others did not — is a
+  **failed recovery**: report it, **naming the movers and the non-movers** from their
+  item `status` fields.
+- **Output:** either "all moved → continue" or a failed-recovery report.
+- **Citation:** the movers/non-movers are named from the per-item `listCommand` re-read
+  (`status` fields), never from aggregate counts — a report that contradicts the
+  per-item read is a defect.
+
+### Step 7 — Gate & exit
+
+- **Tree reconciliation first.** Before any outcome is selected, run the **Post-Run
+  Tree Reconciliation** section (§4). It runs on every recovery pass — including passes
+  with no needs-human items — and is silent on a clean tree.
+- **Evaluate the `resolved` gate — all three must hold:**
+  1. `decision-list --unapplied` is **empty for the affected items**. The verb returns
+     the **global** latest-unapplied-per-item set, so **intersect** that payload's
+     entries (each carries `itemId`) with this session's affected-item set and test
+     only that intersection for emptiness — an unrelated item's stray deferral must not
+     suppress a legitimate `resolved`.
+  2. `git status --porcelain` is **clean** (git-ignored `{stateDir}` artifacts are
+     invisible to porcelain — the exclusion holds by construction).
+  3. the per-item re-read (step 6) shows **every** affected item left
+     `blocked`/`needsHuman`.
+- **Select the outcome:** on all-three-pass, select `resolved` — the first rung of the
+  ladder in `result-reporting.md`, so a resolved stop never re-triggers the needs-human
+  branch its own recovery just cleared. **Any one gate failing falls the ladder
+  through** to `needs-human` / `blocked` / `deferred` / `partial` / `complete` exactly
+  as today. `resolved` routes **resume** — its NEXT-STEPS block fences
+  `/feature-forge:forge-5-loop {feature}`, never the navigator.
+- **CLI:** the close runs through the Scripted Stage Exit (SKILL Step 7):
+  `stage-exit … --outcome resolved …`. `stage-exit` does **not** re-verify the gate
+  server-side (it has no runner access) — enforcement is procedural: this step.
+- **Citation:** the `resolved` outcome text cites the three gate evaluations
+  (`decision-list --unapplied` empty, porcelain empty, per-item re-read all-moved).
+  Claiming `resolved` without those preconditions is a reportable defect.
+
+## 3. Fresh-session re-entry
+
+The procedure is the **re-entry point** on a fresh session / next launch — this is what
+makes a decision survive session end and context clear.
+
+On a new session, **step 1** enumerates every entry with `appliedAt == null` from a
+*previous* session — answered-but-not-yet-applied decisions, deferrals, and cancel-early
+deferrals alike. Those entries are re-surfaced:
+
+- An entry that already carries an **answer** (`answer != null`, `deferred == false`,
+  `appliedAt == null`) **skips step 3's prompt** for that item — the operator already
+  decided; the procedure proceeds straight to step 5 (apply) and step 6 (prove). The
+  answer collected last session is applied this session without re-asking.
+- A **deferral** (`deferred == true`) re-surfaces through step 3 as an open decision —
+  the operator is asked again, and their new answer appends a **new** entry
+  (append-only); the deferral's audit fields are never destroyed.
+
+Because entries are durable and untracked, a session boundary, crash, or context clear
+between "operator answered" and "answer applied" never costs the decision — step 1 of
+the next launch finds it.
+
+## 4. Post-Run Tree Reconciliation
+
+Invoked from step 7 after the run ends and **before** any outcome is selected. It runs
+on **every** recovery pass — including passes with no needs-human items, which step 1
+routes here directly, and SKILL Step 4c enters the procedure on every run close —
+because it is the "tree" half of recovery. Four sub-steps.
+
+### 4.1 Detect
+
+- **CLI:** `git status --porcelain`.
+- **Clean tree → SILENT.** Empty output ⇒ no prompt, no output, no operator decision.
+  The decision record and all runner state under `{stateDir}` are git-ignored and
+  therefore never appear in porcelain output — decision writes never dirty the tree
+  this step inspects.
+- **Dirty tree → proceed to 4.2.**
+- **Error:** a `git status` failure (not a git repo, git error) is surfaced verbatim;
+  reconciliation is skipped (there is nothing git-native to reconcile), the rest of the
+  procedure continues.
+
+### 4.2 Attribute (best-effort, runner-native)
+
+Best-effort attribution of dirty paths to the backlog item(s) that produced them, from
+runner-native evidence — reliable per-item provenance is **not** a prerequisite.
+
+- **Read `{backlogDir}/{stateDir}/state.json`** (the runner's loop state):
+  `baseCommitHash` (the HEAD captured at run start — the baseline for
+  `git log {baseCommitHash}..HEAD`), `completedItems` / `blockedItems` (item ids that
+  finished / blocked), `currentItem` (the item in flight when the run stopped — a
+  strong candidate for uncommitted changes), `startedAt` and
+  `iteration`/`maxIterations` (run identity + budget).
+- **Read `{backlogDir}/{stateDir}/events.ndjson`** — one JSON object per line; parse
+  line-by-line (there is **no** runner CLI for events; the file is read directly). The
+  per-iteration `item_selected`, `llm_spawned`, and `llm_exited` records — each
+  carrying an `itemId` and a `timestamp` — name which items ran during the window and
+  in what order.
+- **Map dirty paths → candidate items:** the `currentItem` and the most recent
+  `item_selected`/`llm_spawned` without a matching clean `llm_exited` are the items "in
+  flight when the run died"; `git log {baseCommitHash}..HEAD` names what was already
+  committed for which item (the runner commits `[rauf] <id>: <title>`). Present the
+  mapping as **CANDIDATES, never asserted**.
+- **Degradation (detection never aborts):** if `state.json` or `events.ndjson` is
+  missing, unreadable, or unparseable, **degrade** to the fully-unattributed path —
+  everything goes into 4.3's single consolidated decision. Detection (4.1) is never
+  aborted by an evidence-parse failure.
+- **Citation:** the presentation cites `git status --porcelain` paths +
+  `{stateDir}/state.json` / `events.ndjson` run evidence, with every attribution
+  explicitly labelled a **candidate**.
+
+### 4.3 Decide
+
+- **Mechanism:** the host's question mechanism (never inline prose).
+  - **One question per attributed item-group:** for each candidate item-group from 4.2,
+    offer **commit-for-that-item** / **stash** / **discard**.
+  - **Unattributable changes → ONE consolidated decision:** everything that could not
+    be attributed is presented as a single grouped question, not dropped.
+- **Discard guard:** **discard is NEVER the default** and requires its **own explicit
+  confirmation** — a second, dedicated question via the host's question mechanism confirming the specific paths
+  to be discarded before any `git checkout`/`git restore`/`git clean` runs. No path is
+  discarded on a single click.
+- **Output:** per group, an executed reconciliation (commit / stash / confirmed
+  discard) or a deferral the operator can revisit.
+
+### 4.4 Launch blocker
+
+The next launch's `### 1g. Stranded-Work Pre-flight` (SKILL Step 1) STOPS on a dirty
+tree when a prior run's `{backlogDir}/{stateDir}/state.json` exists, names that run
+(its `startedAt`, `currentItem`, `blockedItems`), and points at this section to
+commit / stash / discard the stranded work before relaunch. The runner's own
+uncommitted-changes launch refusal remains the backstop for a dirty tree with no
+prior-run state.
+
+## 5. Apply-mechanism dispatch (version gate & the degraded path)
+
+| Runner version | Item kind | Apply mechanism | What the report says |
+|---|---|---|---|
+| `≥ RECOVERY_MIN_RUNNER_VERSION` | needs-human (has an answer) | `{bin} backlog answer . {id} "{answer}" --backlog {backlogDir} --json` | Answer applied and threaded into the next iteration's prompt. |
+| `≥ RECOVERY_MIN_RUNNER_VERSION` | plain blocked | `{bin} backlog unblock . {id} --backlog {backlogDir} --json` | Item unblocked. |
+| `< RECOVERY_MIN_RUNNER_VERSION` (or probe miss) | needs-human | **DEGRADE:** `{bin} backlog unblock . {id} --backlog {backlogDir} --json` | Item unblocked; **answer was NOT injected into the next prompt** (durable in `forge-decisions.json`); `{installHint}` — upgrade to a runner that ships `backlog answer` to thread it. |
+| any version (incl. probe miss) | plain blocked | `{bin} backlog unblock . {id} --backlog {backlogDir} --json` | Item unblocked. |
+
+Key properties:
+
+- **Plain blocked items always use `unblock`, at every version** — they carry no answer
+  to thread. The version gate only ever changes the needs-human path.
+- **The degraded needs-human path genuinely unblocks** (the runner clears
+  `status`/`blockedReason`/`needsHuman`/`deferred`), so recovery works across the whole
+  supported runner floor. The only capability lost below the threshold is
+  prompt-threading — the answer remains durable in the decision record and re-surfaces
+  via `decision-list --unapplied` if re-decided.
+- **The report is honest either way:** the degraded path states explicitly that the
+  answer was not threaded, with the upgrade hint.
+
+## 6. Failure taxonomy
+
+| Failure | When it occurs | Reaches the step-6 per-item test? | Report |
+|---|---|---|---|
+| **Failed apply** | `{bin} backlog answer` / `unblock` exits non-zero (corrupt backlog, I/O error, not-blocked/not-found refusal); or the post-apply re-read is unparseable | **No** — stops *before* the test | Verbatim runner error + which item; **failed recovery**; procedure stops; never claimed succeeded |
+| **Ran-but-nothing-moved** | Every apply exited 0, but the step-6 per-item test finds a non-mover | **Yes** — *is* the test failing | Movers/non-movers named from `status` fields; **failed recovery** |
+| **Version-probe miss** | `versionCommand` missing/unparseable, or version `< RECOVERY_MIN_RUNNER_VERSION` | N/A — selects the degraded path (§5) | Degraded path proceeds; not-threaded caveat + `installHint`; **not** a failed recovery |
+
+Rules: never report recorded/succeeded past a failed step; a failed apply stops before
+the per-item test, so a runner that errored is never conflated with a runner that ran
+cleanly but moved nothing; `decision-apply` is not called for a failed item — the record
+stays unapplied and re-surfaces next launch; a probe miss degrades, it never fails
+recovery.
+
+## 7. Report citations (REQ-OBS-01)
+
+Every report surface this procedure produces names the authoritative source it derived
+its claims from; a claim that source contradicts is a reportable defect. Each report
+surface names the authoritative source it derives its claims from:
+
+| Report surface | Authoritative citation basis |
+|---|---|
+| Pending / starvation template | `backlogSummary` counts + `backlog-topology` output over `listCommand` JSON; iteration counters from `state.json` (`iteration`/`maxIterations`) |
+| Failed-recovery report (§2 step 6) | The per-item `listCommand` re-read — movers/non-movers named from item `status`, never aggregate counts |
+| `resolved` outcome text | The three gate evaluations: `decision-list --unapplied` (empty), `git status --porcelain` (empty), per-item re-read (all affected left `blocked`) |
+| Consolidated blast-radius prompt (§2 step 3) | `backlog-topology --cluster` gated-subtree output (member ids + counts) |
+| Tree-reconciliation presentation (§4) | `git status --porcelain` paths + `state.json`/`events.ndjson` run evidence, attributions explicitly presented as **candidates** |
+| Step 2a depth line | The same `backlog-topology` output (`maxChainDepth`) |