@garygentry/feature-forge 0.3.1 → 0.3.4

package/adapters/pi/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:** `AskUserQuestion` (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
+  `/skill: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:** `AskUserQuestion` (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 `AskUserQuestion` 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`) |

package/adapters/pi/skills/forge-5-loop/references/result-reporting.md

@@ -1,32 +1,31 @@
-# forge-5-loop — Step 4b Result-Report Templates
+# forge-5-loop — Result Reports and Loop-Outcome Selection
 
-These are the five verbatim result-report output templates for **Step 4b** of
-`forge-5-loop/SKILL.md`. Pick **every** branch that applies (a run can be both
-blocked and needs-human) and render its report.
+This file carries two things for `forge-5-loop/SKILL.md`:
 
-**All items done.** Print the completion summary, then close with the **warm-acceptable
-variant** of the Stage Exit Protocol (single-sourced in
-`references/stage-exit-protocol.md`) — the `forge-5-loop → forge-6-docs` boundary is the
-one place where clearing before the next stage is optional:
-```
-Loop completed for {feature}. All {N} items implemented successfully.
-```
+1. the verbatim **result-report templates** for **Step 4b** — factual counts only; and
+2. the deterministic **`LoopOutcome` ladder** for **Step 7**, which picks the single
+   value the scripted stage exit is invoked with.
 
-**The loop is complete — this is the one boundary where clearing before the next stage is optional.**
+The reports describe what the run did. They never carry a next command, a retry
+command, or a "continue to docs" suggestion: routing is the scripted stage exit's
+job, and a loop run emits exactly **one** `stage-exit` invocation and **one**
+terminal block.
 
-1. **Verify is already offered above.** Impl-verify is offered interactively right after this report (Step 5b for a standalone feature, Step 6.1 for an epic member) — run it there rather than as a second gate. It runs clean-room, so it needs no fresh session.
-2. **Clearing is optional here — warm is fine.** `forge-6-docs` benefits from the still-warm context of what the loop actually did, so continuing in this same session is the easy default. A cold start also works — every artifact is on disk — but there is no need to force it.
-3. **Then run the next command** — in this warm session, or a fresh one if you prefer:
+## Result reports (Step 4b)
 
-   ```
-   /skill:forge-6-docs {feature}
-   ```
+Pick **every** branch that applies — a run can be both blocked and needs-human — and
+render its report. These are descriptive; none of them ends the turn.
+
+**All items done.**
+```
+Loop completed for {feature}. All {N} items implemented successfully.
+```
 
 **Runner review pass.** A review flag (e.g. rauf's `--review`) makes the runner run
 a post-loop review that **auto-creates and implements fix items** rather than handing
 findings to the user — distinct from `forge-verify impl` (a clean-context audit that
 writes a findings doc). When Step 4a captured a `review_completed` event, add a line
-**above** "Next steps" so the pass's effect is visible and not mistaken for "nothing
+below the counts so the pass's effect is visible and not mistaken for "nothing
 happened":
 ```
 Runner review pass: {itemsCreated} fix item(s) created and implemented.
@@ -43,10 +42,6 @@ Loop completed for {feature}.
 
 These items asked a question the loop couldn't answer:
   - {id}: {title} — {reason}
-
-Resolve, then retry:
-  - Answer the question(s) above, then re-run `/skill:forge-5-loop {feature}`
-    (add --retry-blocked to pick the set-aside items back up).
 ```
 
 **Some items blocked:**
@@ -59,10 +54,7 @@ Blocked items:
   - {id}: {title}
   - {id}: {title}
 
-Options:
-  - Re-run with --retry-blocked to retry blocked items
-  - Review blocked items manually: {bin} backlog show . {id} --backlog {backlogDir}
-  - Continue to docs if blocking items are non-critical
+Inspect one with: {bin} backlog show . {id} --backlog {backlogDir}
 ```
 
 **Some items deferred (runner gave up after retries — "false blocks"):**
@@ -70,16 +62,92 @@ Options:
 Loop completed for {feature}.
   Completed: {done}/{total}
   Deferred:  {deferred} items (no signal after retries — likely just need another pass)
-
-Re-run `/skill:forge-5-loop {feature}` to retry deferred items.
 ```
 
-**Some items still pending (iteration limit reached):**
+**Some items still pending** — the parenthetical cause is chosen, never hardcoded:
 ```
 Loop completed for {feature}.
   Completed: {done}/{total}
-  Pending:   {pending} items (iteration limit reached)
+  Pending:   {pending} items ({cause})
   Blocked:   {blocked} items
-
-Re-run `/skill:forge-5-loop {feature}` to continue with remaining items.
 ```
+Render `{cause}` as "iteration limit reached" **only** when `iteration == maxIterations`
+AND `selectable > 0` — cite the `iteration`/`maxIterations` counters from
+`{loopRunner.stateDir}/state.json` and `selectable` from `backlog-topology --items-stdin
+--json` run over the same authoritative item JSON as the counts above. Otherwise —
+`selectable == 0` with items still pending while `iteration < maxIterations` — the
+iteration limit was NOT the constraint: drop the parenthetical and render this
+dependency-starvation report instead, naming each blocking root and its gated-subtree
+size from `backlog-topology`'s `starvation.blockingRoots[].{id, gatedCount}` and
+`itemCount`, then close the stage with `--cause dependency-starvation` in Step 7:
+```
+Loop stopped for {feature} with {pending} item(s) still pending, but the iteration
+limit was NOT the constraint ({iteration}/{maxIterations} iterations used).
+No pending item was selectable — every one is gated behind unblocked roots:
+  - {rootId}: {rootTitle} — gates {gatedCount}/{itemCount} items
+Unblock these roots (their subtrees free up on the next run), then run the loop again.
+```
+Both branches cite their authoritative source: the iteration-limit branch the
+`state.json` iteration counters, the starvation branch the backlog summary counts plus
+the `backlog-topology` output (`selectable`, `blockingRoots`, `gatedCount`,
+`itemCount`). A cause any of those counters contradicts — e.g. "iteration limit
+reached" while `iteration < maxIterations` — is a reportable defect.
+
+## Selecting the one `LoopOutcome` (Step 7)
+
+After Step 5's `state-complete`, select exactly **one** `LoopOutcome` from Step 4a's
+authoritative final counts. Walk this ladder in order and stop at the first match:
+
+1. **`resolved`** — the Post-Run Recovery Procedure
+   (`references/recovery-procedure.md`) ran this session with a **non-empty**
+   affected-item set and its gate passed: every affected needs-human item has an
+   applied decision record, the working tree is clean, and each affected item left
+   `blocked`/`needsHuman` per the per-item re-read. This outranks `needs-human` so a
+   stop the recovery just cleared is not re-reported as still needing a human. (Step
+   4c runs the procedure on every close, so an empty affected set is the common case —
+   it never selects `resolved`; fall through.)
+2. **`needs-human`** — otherwise, `needsHuman > 0`. This wins even when blocked
+   items also exist: a decision only a human can make outranks work that merely
+   could not proceed.
+3. **`blocked`** — otherwise, genuine `blocked > 0`.
+4. **`deferred`** — otherwise, runner-deferred items exist (the "false blocks" the
+   runner gave up on after retries).
+5. **`partial`** — otherwise, `pending`/`in_progress` items remain because the
+   iteration limit was reached.
+6. **`complete`** — otherwise, and **only** when every item is `done`.
+
+This is a priority order, not a set. A run reporting both a needs-human and a blocked
+count renders both reports above and still exits `needs-human`.
+
+**The runner's process exit code is not the outcome.** A loop runner that exits 0 has
+reported only that its process finished; the final backlog state decides. A clean
+exit 0 that still leaves pending items is `partial`, never `complete` — and
+`complete` is legitimate only when the counts show every item `done`.
+
+**Retrying the non-complete outcomes.** `partial`, `deferred`, and `resolved` fence
+the loop resume; `blocked` and `needs-human` fence the navigator. Whichever you land on, the
+runner's own retry flags still apply to the next run — e.g. rauf's `--retry-blocked`
+picks the set-aside blocked and deferred items back up at Step 2d. Mention that as
+plain prose in the report if it helps; never as a second command block.
+
+## Operational failure before the counts are known
+
+If the run cannot produce authoritative counts at all — the status/list command fails,
+its output does not parse, the state directory is gone, or the process died in a way
+that leaves the backlog unreadable — **do not pick an outcome and do not close the
+stage.** There is nothing to select from, and guessing one would record a pipeline
+position that never happened.
+
+Instead: say plainly what failed, show the command's own output, and name the
+recovery (re-run the status command, or re-run the loop once the runner is healthy).
+Emit no `stage-exit` invocation and no terminal block. The stage stays `in-progress`
+on disk, which is exactly the state the navigator can resume from.
+
+## Closing the stage
+
+Pass the selected value to the single scripted stage exit in **Step 7** of
+`forge-5-loop/SKILL.md` as `--outcome {LoopOutcome}`, and print its NEXT-STEPS block
+verbatim as the absolute last output. Append nothing after it — no summary, no retry
+line, no docs suggestion. For a completed epic member, the exit consumes the epic's
+live status itself, so announce the rollup **before** invoking it and add no
+hand-authored handoff of your own afterwards.

package/adapters/pi/skills/forge-5-loop/references/runner-contract.md

@@ -19,8 +19,10 @@ item.model  >  --model / options  >  project default  >  provider default
 
 So a backlog item's own `model` field overrides a `--model` flag passed to the
 run, which overrides the project's configured default, which overrides the
-runner/provider default. Pass `--model <model>` (optional flag below) to override
-the project default for the whole run.
+runner/provider default. Pass `--model <model>` to override the project default for
+the whole run; it is catalogued with the run's other optional flags under
+`## Optional flags catalog (Step 2d, rauf)` in `references/agent-selection.md` —
+read that file only when Step 2d's `loopRunner.agentArgument` capability gate is on.
 
 ## Run mode (Step 2d, rauf)
 
@@ -29,7 +31,7 @@ pass after all iterations complete (an extra agent session that re-examines the
 finished work and can file follow-up backlog items). feature-forge treats **running
 with review as the recommended default** — a review pass is cheap relative to the
 loop it audits, and catches gaps before the pipeline moves on to docs. So Step 2d
-adds a **"Run mode"** question to the confirmation's `AskUserQuestion` surface with a
+adds a **"Run mode"** question, via `AskUserQuestion`, to the confirmation surface with a
 **fixed, non-improvised option order** (determinism is the point — the option set
 must not vary run-to-run):
 
@@ -45,6 +47,19 @@ Run mode:
      review pass and also unblocks/retries the previously blocked items.
 ```
 
+**`loopRunner.reviewMode` gate (`"prompt"` default | `"always"` | `"never"`).**
+The Run-mode question above is presented only when the effective
+`loopRunner.reviewMode` is `"prompt"` — the default, byte-identical to today.
+`"always"` **skips the question** and appends `--review` unconditionally; the
+confirmation's rendered command line still shows `--review`, so the choice is
+never hidden. `"never"` **skips the question** and launches the bare rendered
+command. Under `"always"`/`"never"`, when — and only when — the Step 2a tally has
+`blocked > 0`, present a **narrower situational question** in the question's
+place offering only the retry-blocked choice (on yes, additionally append
+`--retry-blocked`; the `--review` decision is already fixed by the mode and is
+**not** re-asked); with no blocked items, the Run-mode surface asks nothing. An
+unrecognized value behaves as `"prompt"`.
+
 Notes:
 
 - **Option 1 is the default** and the confirmation's rendered command line shows
@@ -101,7 +116,7 @@ a descriptor on the file the runner immediately rotates away, so the redirected
 rotation timing. So:
 
 - **Self-persisting runner (default — rauf writes `{stateDir}/events.ndjson`):**
-  launch the **plain `runCommand`** with `run_in_background: true` and **no
+  launch the **plain `runCommand`** with the host's background-execution mechanism and **no
   redirect** — the Bash tool already captures the run's stdout/stderr to the
   background task's output file (use it to diagnose a launch refusal). Supervise by
   arming the Monitor on the runner's **native** `{backlogDir}/{stateDir}/events.ndjson`
@@ -127,8 +142,8 @@ backlog size).
 
 ## Arm a Monitor on the event stream (Step 3d)
 
-Arm the **`Monitor` tool** on the structured event stream so events flow back into
-this session as they happen. Use **`persistent: true`** — runs can exceed `Monitor`'s
+Arm the **host's monitoring mechanism** on the structured event stream 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.
 
@@ -177,12 +192,17 @@ high and the noise low:
   immediately** and send a **`PushNotification`** (an hours-long run means the user has
   likely stepped away). **Important — the loop is NOT paused:** the runner has set that
   item aside and kept working other items. So report *what* needs a human and *which*
-  item, then either (a) collect the user's answer via `AskUserQuestion` to **stage a
-  post-run retry**, or (b) offer to **cancel the run early** if the answer changes the
-  whole plan. Do not tell the user the loop is waiting on their reply — it isn't.
+  item, then either (a) collect the user's answer via `AskUserQuestion` and **record it via
+  `decision-record` now** — SKILL Step 4c's unconditional **Post-Run Recovery Procedure**
+  pass (`references/recovery-procedure.md`) applies it after the run ends — or (b) offer
+  to **cancel the run early** (also recorded via `decision-record` — a deferral) if the
+  answer changes the whole plan. Do not tell the user the loop is waiting on their reply
+  — it isn't.
 - **`item_blocked`** → surface the blocked item + reason now (visibility) and
   accumulate for the final summary. Use `{rendered statusJsonCommand}` to distinguish a
   genuine `blocked` from a runner-`deferred` "false block" (`backlogSummary.deferred`).
+  No action is needed now: Step 4c's recovery pass offers the unblock after the run
+  ends — a blocked-only run (no `needs_human` event) still enters it.
 - **`loop_error`** → a real failure (this is also what a circuit-breaker halt — too many
   consecutive infra failures — emits). Surface now and `PushNotification`. Offer
   inspection / `--force` / re-run as appropriate.