@garygentry/feature-forge 0.3.7 → 0.3.9

package/adapters/pi/scripts/forge_session/exit.py

@@ -329,10 +329,10 @@ def stage_exit(
             capability is permission, not tool presence: a dispatch permitted
             only once the user has asked is still `interactive`, because the
             `standard` gate's own prompt supplies that request.
-        cause: Pending-attribution annotation (`dependency-starvation`), valid
-            only with `--stage forge-5-loop --outcome partial` (REQ-ATTR-04).
-            It swaps the partial next-steps sentence for the starvation variant
-            and changes no routing.
+        cause: Pending-attribution annotation (`dependency-starvation`,
+            `review-pending` or `runner-stopped`), valid only with `--stage forge-5-loop --outcome
+            partial` (REQ-ATTR-04, #339). It swaps the partial next-steps sentence
+            for the matching variant and changes no routing.
 
     Returns:
         A JSON-serializable `StageExitPayload` dictionary.
@@ -486,7 +486,7 @@ def stage_exit(
     # argparse `choices` already restricts the value; this restricts the combination.
     if cause is not None and not (stage == "forge-5-loop" and outcome == "partial"):
         raise UsageError(
-            "--cause dependency-starvation is valid only with "
+            f"--cause {cause} is valid only with "
             "--stage forge-5-loop --outcome partial"
         )
 

package/adapters/pi/scripts/forge_session/routes.py

@@ -799,6 +799,27 @@ _LOOP_PARTIAL_STARVED_TEXT: Final[str] = (
     "resumable and nothing downstream is ready: unblock the roots named in the "
     "starvation report above, then run the loop again below to continue."
 )
+#: The pending-review variant of the `partial` next-steps sentence: every item may be
+#: done, but the runner's review pass failed or was interrupted, so the run is not
+#: complete. Selected only by ``--cause review-pending`` (issue #339); the route is
+#: still the loop resume, whose Step 2a re-runs exactly that review.
+_LOOP_PARTIAL_REVIEW_PENDING_TEXT: Final[str] = (
+    "The loop for {feature} is not finished — its review pass failed or was "
+    "interrupted, so the review is still pending even if every item is done. The "
+    "recorded state is resumable and nothing downstream is ready: run the loop again "
+    "below to re-run the pending review."
+)
+#: The unfinished-runner variant of the `partial` next-steps sentence: the runner's
+#: own terminal state (a crash, a stop, a stale lock, a limit halt) says it did not
+#: finish cleanly, so the run is not complete even when every item reads `done`.
+#: Selected only by ``--cause runner-stopped`` (issue #339); the route is still the
+#: loop resume, whose Step 2a offers the runner's own resume.
+_LOOP_PARTIAL_RUNNER_STOPPED_TEXT: Final[str] = (
+    "The loop runner for {feature} did not reach a clean finish — it crashed, was "
+    "stopped, or halted on a limit — so the run is not complete even if every item "
+    "reads done. The recorded state is resumable and nothing downstream is ready: run "
+    "the loop again below to resume the runner."
+)
 #: The `complete` preamble, selected by where the handoff actually lands. The epic
 #: rows name the epic and its live rollup, so the operator can see WHY the handoff is
 #: this member's own documentation rather than another member (or vice versa).
@@ -956,9 +977,11 @@ def _loop_route(
             handoff: findings already exist at this exact revision, so the fenced
             action is applying them, exactly as on a production re-exit.
         cause: The already-validated attribution annotation — only
-            ``"dependency-starvation"`` with ``outcome == "partial"``, else None.
-            Swaps the partial next-steps sentence for the starvation variant; the
-            route itself is unchanged (partial stays a resume either way).
+            ``"dependency-starvation"``, ``"review-pending"`` or
+            ``"runner-stopped"`` with
+            ``outcome == "partial"``, else None. Swaps the partial next-steps
+            sentence for the matching variant; the route itself is unchanged
+            (partial stays a resume either way).
 
     Returns:
         `(primary_canonical, deferred_canonical, outcome_text, advancing)`, matching
@@ -985,6 +1008,10 @@ def _loop_route(
         )
         if outcome == "partial" and cause == "dependency-starvation":
             text = _LOOP_PARTIAL_STARVED_TEXT.format(feature=feature)
+        elif outcome == "partial" and cause == "review-pending":
+            text = _LOOP_PARTIAL_REVIEW_PENDING_TEXT.format(feature=feature)
+        elif outcome == "partial" and cause == "runner-stopped":
+            text = _LOOP_PARTIAL_RUNNER_STOPPED_TEXT.format(feature=feature)
         else:
             text = _LOOP_OUTCOME_TEXT[outcome].format(feature=feature)
         return primary, None, text, False

package/adapters/pi/skills/forge/references/stage-exit-protocol.md

@@ -47,7 +47,7 @@ an epic member. Only the flags below are stage-specific; pass no others.
 |---|---|---|
 | `forge-0-epic` | `forge-0-epic` | `--next-feature "{member}"` when a concrete member exists |
 | `forge-1-prd` … `forge-4-backlog` | that stage's own id | none beyond identity/capability |
-| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation` with `--outcome partial` |
+| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation`, `review-pending` or `runner-stopped` with `--outcome partial` |
 | `forge-6-docs` | `forge-6-docs` | `--outcome` — `complete`, `blocked`, or `skipped` (deliberate docs skip, persisted via `state-skip` before the exit; routes like `complete` with honest wording) |
 | direct `forge-verify` | `forge-verify` | `--owner direct`, `--outcome` (`passed`, `findings`, `skipped`, `failed`), and served-stage metadata |
 | nested `forge-verify` | `forge-verify` | `--owner nested`, plus the same outcome and served-stage metadata |

package/adapters/pi/skills/forge-0-epic/references/stage-exit-protocol.md

@@ -47,7 +47,7 @@ an epic member. Only the flags below are stage-specific; pass no others.
 |---|---|---|
 | `forge-0-epic` | `forge-0-epic` | `--next-feature "{member}"` when a concrete member exists |
 | `forge-1-prd` … `forge-4-backlog` | that stage's own id | none beyond identity/capability |
-| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation` with `--outcome partial` |
+| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation`, `review-pending` or `runner-stopped` with `--outcome partial` |
 | `forge-6-docs` | `forge-6-docs` | `--outcome` — `complete`, `blocked`, or `skipped` (deliberate docs skip, persisted via `state-skip` before the exit; routes like `complete` with honest wording) |
 | direct `forge-verify` | `forge-verify` | `--owner direct`, `--outcome` (`passed`, `findings`, `skipped`, `failed`), and served-stage metadata |
 | nested `forge-verify` | `forge-verify` | `--owner nested`, plus the same outcome and served-stage metadata |

package/adapters/pi/skills/forge-1-prd/references/stage-exit-protocol.md

@@ -47,7 +47,7 @@ an epic member. Only the flags below are stage-specific; pass no others.
 |---|---|---|
 | `forge-0-epic` | `forge-0-epic` | `--next-feature "{member}"` when a concrete member exists |
 | `forge-1-prd` … `forge-4-backlog` | that stage's own id | none beyond identity/capability |
-| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation` with `--outcome partial` |
+| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation`, `review-pending` or `runner-stopped` with `--outcome partial` |
 | `forge-6-docs` | `forge-6-docs` | `--outcome` — `complete`, `blocked`, or `skipped` (deliberate docs skip, persisted via `state-skip` before the exit; routes like `complete` with honest wording) |
 | direct `forge-verify` | `forge-verify` | `--owner direct`, `--outcome` (`passed`, `findings`, `skipped`, `failed`), and served-stage metadata |
 | nested `forge-verify` | `forge-verify` | `--owner nested`, plus the same outcome and served-stage metadata |

package/adapters/pi/skills/forge-2-tech/references/stage-exit-protocol.md

@@ -47,7 +47,7 @@ an epic member. Only the flags below are stage-specific; pass no others.
 |---|---|---|
 | `forge-0-epic` | `forge-0-epic` | `--next-feature "{member}"` when a concrete member exists |
 | `forge-1-prd` … `forge-4-backlog` | that stage's own id | none beyond identity/capability |
-| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation` with `--outcome partial` |
+| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation`, `review-pending` or `runner-stopped` with `--outcome partial` |
 | `forge-6-docs` | `forge-6-docs` | `--outcome` — `complete`, `blocked`, or `skipped` (deliberate docs skip, persisted via `state-skip` before the exit; routes like `complete` with honest wording) |
 | direct `forge-verify` | `forge-verify` | `--owner direct`, `--outcome` (`passed`, `findings`, `skipped`, `failed`), and served-stage metadata |
 | nested `forge-verify` | `forge-verify` | `--owner nested`, plus the same outcome and served-stage metadata |

package/adapters/pi/skills/forge-3-specs/references/stage-exit-protocol.md

@@ -47,7 +47,7 @@ an epic member. Only the flags below are stage-specific; pass no others.
 |---|---|---|
 | `forge-0-epic` | `forge-0-epic` | `--next-feature "{member}"` when a concrete member exists |
 | `forge-1-prd` … `forge-4-backlog` | that stage's own id | none beyond identity/capability |
-| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation` with `--outcome partial` |
+| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation`, `review-pending` or `runner-stopped` with `--outcome partial` |
 | `forge-6-docs` | `forge-6-docs` | `--outcome` — `complete`, `blocked`, or `skipped` (deliberate docs skip, persisted via `state-skip` before the exit; routes like `complete` with honest wording) |
 | direct `forge-verify` | `forge-verify` | `--owner direct`, `--outcome` (`passed`, `findings`, `skipped`, `failed`), and served-stage metadata |
 | nested `forge-verify` | `forge-verify` | `--owner nested`, plus the same outcome and served-stage metadata |

package/adapters/pi/skills/forge-4-backlog/references/stage-exit-protocol.md

@@ -47,7 +47,7 @@ an epic member. Only the flags below are stage-specific; pass no others.
 |---|---|---|
 | `forge-0-epic` | `forge-0-epic` | `--next-feature "{member}"` when a concrete member exists |
 | `forge-1-prd` … `forge-4-backlog` | that stage's own id | none beyond identity/capability |
-| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation` with `--outcome partial` |
+| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation`, `review-pending` or `runner-stopped` with `--outcome partial` |
 | `forge-6-docs` | `forge-6-docs` | `--outcome` — `complete`, `blocked`, or `skipped` (deliberate docs skip, persisted via `state-skip` before the exit; routes like `complete` with honest wording) |
 | direct `forge-verify` | `forge-verify` | `--owner direct`, `--outcome` (`passed`, `findings`, `skipped`, `failed`), and served-stage metadata |
 | nested `forge-verify` | `forge-verify` | `--owner nested`, plus the same outcome and served-stage metadata |

package/adapters/pi/skills/forge-5-loop/SKILL.md

@@ -109,7 +109,7 @@ The runner commits each item onto the current branch. Skip if not a git repo or
 
 ### 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.
+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.
 
 ## Step 2: Construct the Loop Command
 
@@ -119,7 +119,7 @@ Run the **list command** (`loopRunner.listCommand`, default `rauf backlog list .
 
 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."
+Then, **whatever the counts**, run the **status-json command**: `reviewPending: true` (optional field) means a prior review pass failed or was interrupted — follow **Pending review** in `references/runner-contract.md` before any fresh run (which would drop it). Otherwise, with no pending or in_progress items: a reported `loopState` that is not a clean finish → follow **Unfinished runner** in that file; else STOP and tell the user: "All backlog items are already done or blocked. Nothing to run."
 
 If there are `blocked` items, note them — the user may want `--retry-blocked`.
 
@@ -185,14 +185,14 @@ R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scri
 python3 "$R/scripts/forge-session.py" state-enter --feature "{feature}" --stage forge-5-loop --specs-dir "{specsDir}"
 ```
 
-Then commit this state write before launching (mandatory). The runner refuses to run with uncommitted changes (*"…pass --force"*), and this marker is itself one — so an otherwise-clean repo fails its first launch unless committed. Commit it via the shared-conventions **Git Commit Protocol** (epic members: stage `{specsDir}/{epic}/`): `{commitPrefix}({feature}): forge-5-loop in-progress` — a launch precondition, required regardless of `gitCommitAfterStage`. Unrelated leftover changes still trip the refusal; surface it, never auto-pass `--force`. See `references/runner-contract.md`.
+Then commit this state write before launching (mandatory — the runner refuses a dirty tree, and this marker is itself a change) via the shared-conventions **Git Commit Protocol** (epic members: stage `{specsDir}/{epic}/`): `{commitPrefix}({feature}): forge-5-loop in-progress`, regardless of `gitCommitAfterStage`. Unrelated leftover changes still trip the refusal; surface it, never auto-pass `--force`.
 
 ### 3b. Launch Background Process
 
 > **On Pi, do not perform Steps 3b–3f by hand.** Pi has no background or monitor surface; this bundle's `forge-loop-supervisor` extension IS the "background-execution mechanism" and "monitoring mechanism" these steps name. Call **`forge_loop_launch`** with the backlog dir (plus `review` / `agent` / `iterations` from config) — it launches the loop **detached** and supervises `events.ndjson` for you, reporting each completed item and waking this session on needs-human / blocked / stuck / review-failed / error / completion. **Read the rest of Steps 3b–3f, and the launch/monitor detail in `references/runner-contract.md`, as a description of what that tool does — not as commands to run.** Use `forge_loop_status` to check progress and `forge_loop_stop` only to deliberately stop the runner; full detail is in "Host execution notes (Pi)" at the end of this skill.
 
 
-Launch the loop **backgrounded** (host's background-execution mechanism: true) 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`.
+Launch the loop **backgrounded** (host's background-execution mechanism: true) 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 and rotates `{stateDir}/events.ndjson` natively), launch the **plain `runCommand`** with **no stdout redirect** and supervise that native file; never redirect `--ndjson` into `{stateDir}` (it collides with the runner's own writer). 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
 
@@ -200,21 +200,11 @@ 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) with **a continuous watch**, a coverage-complete filter
-matching every terminal and exception state (silence is not success), and react to
-each event as it arrives. Each NDJSON line is a JSON object whose event kind lives
-under the **`type`** field (rauf's schema — e.g. `{"type":"item_completed",…}`), so
-the filter must select on **`.type`**, **not** `kind`: a `kind`-keyed filter surfaces
-nothing (no `grep` match; `jq` aborts on the null `.kind`), so the watch stays dark. The exact Monitor
-commands, the filter event list, and the full per-event reaction rules (`needs_human`
-/ `loop_error` surfaced immediately with an automatic session wake, `item_completed`
-coalesced into milestones, `llm_stuck_warning` as a hang warning) are in
-`references/runner-contract.md` — follow them verbatim.
+Arm the **host's monitoring mechanism** (a continuous watch) on the structured event stream (the NDJSON file, or the human log as fallback) with a coverage-complete filter matching every terminal and exception state (silence is not success). The filter selects on each NDJSON line's **`.type`** field, **never** `kind` (a `kind`-keyed filter matches nothing and the watch stays dark). The exact commands, the filter list (incl. `review_failed` and usage-limit events), and the per-event reactions (`needs_human` / `loop_error` / `review_failed` surfaced with an automatic session wake, `item_completed` coalesced into milestones, `llm_stuck_warning` reported with its in-flight tool) are in `references/runner-contract.md` — follow them verbatim.
 
 ### 3f. Reach completion
 
-Step 4 is reached when the backgrounded process exits (its completion notification is authoritative); the `loop_completed` / `loop_error` / `loop_cancelled` event is the live heads-up that it's imminent. Stop the Monitor (it ends on its own when `tail` sees the process-ended log, or via the supervisor's own teardown) and proceed to Step 4. Do NOT foreground-sleep or poll — the harness drives both the Monitor events and the completion notification.
+Step 4 is reached when the backgrounded process exits (its completion notification is authoritative; a `loop_completed` / `loop_error` / `loop_cancelled` event is the live heads-up). Stop the Monitor (the supervisor's own teardown if it has not ended) and proceed. Do NOT foreground-sleep or poll — the harness drives both signals.
 
 ## Step 4: Check Results
 
@@ -226,7 +216,7 @@ 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. 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. Also read the optional `loopState`, `reviewPending`, `lock` fields (absent on older runners = unset); **Runner terminal states** in `references/result-reporting.md` maps them. **`reviewPending: true` is never complete, whatever the counts** — offer the resume per **Pending review** in `references/runner-contract.md` before 4b. 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
 
@@ -235,11 +225,11 @@ blocked and needs-human) and render its report. The five verbatim result-report
 
 ### 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.
+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) is **not** the entry condition: a run that emitted no event still enters here, so blocked-only runs reach the unblock. With nothing to decide, its step 1 skips to the §4 tree reconciliation — silent on a clean tree — which also reconciles work a run stranded uncommitted with no signal (1g 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
 
-Record completion by running `state-complete` (below). Evaluate "all backlog items are `done`" yourself and pass the result as `--status`: `complete` if every item is `done`, else `in-progress`. The verb records `completedAt`, the version, `basedOnVersions` and `artifacts`, and refreshes `updatedAt`. Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol.
+Record completion by running `state-complete` (below). Evaluate "all backlog items are `done`" yourself and pass the result as `--status`: `complete` only when Step 7's ladder selects `complete` (every item `done`, `total > 0`, no pending review, a clean runner finish per `references/result-reporting.md`), else `in-progress`. The verb records `completedAt`, the version, `basedOnVersions` and `artifacts`, and refreshes `updatedAt`. Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol.
 
 ```bash
 R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${CLAUDE_PLUGIN_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')"
@@ -274,7 +264,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` (`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.
+First select the single `LoopOutcome` with the ladder in `references/result-reporting.md` (`resolved` → unfinished-runner `partial` → `needs-human` → `blocked` → `deferred` → `partial` → `complete`, first match wins, plus any `--cause` it names), 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,8 +283,8 @@ Add `--epic "{epic}"` when this feature is an epic member — required, per the
 - **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" unless `FEATURE_FORGE_ROOT` points at it (#323). Expected in a dev environment; run the epic-manifest script from the checkout directly (`python3 <checkout>/scripts/epic-manifest.py …`).
 - `{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`). 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 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). 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.
+- If the session disconnects mid-loop, the runner process continues independently — check results later with the status / list commands. A crashed run's stale lock (`PAUSED` + `lock.stale`) is cleared by rauf's `resume`, not `--force` (see `references/result-reporting.md`).
+- Never run the run command in the foreground (without 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). 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.
 - 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** 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/pi/skills/forge-5-loop/references/preflight-and-self-heal.md

@@ -6,7 +6,7 @@ silent unasked mutation. It runs whenever a skill gates on `doctor`'s structured
 `checks[]` (`roadmap/self-healing-resilience.md` §5.2); today that is `forge-5-loop`'s
 gates 1c/1d (`skills/forge-5-loop/SKILL.md`), which resolve the loop runner **before**
 touching it, `forge-init`'s install preflight (`skills/forge-init/SKILL.md`), where
-neither check is a stop, and `forge-guide --doctor` (`skills/forge-guide/SKILL.md`), the
+no check is a stop, and `forge-guide --doctor` (`skills/forge-guide/SKILL.md`), the
 operator-facing repair surface, which gates nothing at all. All three are callers, not
 the procedure's scope: any skill that gates on `checks[]` follows it in full. Its seven
 ordered steps: **enumerate → cluster → consolidated prompts → record → apply → prove →

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

@@ -40,9 +40,11 @@ defined authoritatively in rauf's
 - **A machine-readable event stream** for live supervision (`loopRunner.eventStreamCommand`,
   rauf: `loop run … --ndjson`): one JSON event per line with a stable `type`
   vocabulary — `item_completed` / `item_blocked` / `needs_human` / `signal_parsed`
-  / `loop_completed` / `loop_error` / `loop_cancelled` / `llm_stuck_warning` (a
-  circuit-breaker halt surfaces as `loop_error`) — plus a
-  derived-status JSON (`loopRunner.statusJsonCommand`, rauf: `status … --json`) and
+  / `loop_completed` / `loop_error` / `loop_cancelled` / `review_failed` /
+  `llm_stuck_warning` (a circuit-breaker halt surfaces as `loop_error`) — plus a
+  derived-status JSON (`loopRunner.statusJsonCommand`, rauf: `status … --json`;
+  forge-5-loop also reads its optional `loopState` / `lock` / `sleepUntil` /
+  `reviewPending` fields when present, and degrades to the counts when absent) and
   per-iteration telemetry with a `stuckWarning` flag (`loopRunner.watchCommand`,
   rauf: `status … --json` — the `loop watch` verb was removed in v0.5.0). `forge-5-loop` supervises the run through these,
   **not** by parsing the human log. `followCommand` / `logCommand` are

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

@@ -34,6 +34,16 @@ Runner review pass: {itemsCreated} fix item(s) created and implemented.
 Omit this line when no `review_completed` event was emitted (no review flag passed).
 The created items are already counted in the totals above.
 
+**Review pending** (`reviewPending: true` — the review pass failed or was interrupted,
+and the user chose **Stop here** at the Pending review offer in
+`references/runner-contract.md`). Never render the all-done report for this run, even
+when every item is `done`:
+```
+Loop finished the backlog for {feature}, but its review pass did not complete.
+  Completed:      {done}/{total}
+  Review pending: {reviewItemIds count} item(s) ({reason from the last `review_failed` event, if any})
+```
+
 **Some items need a human:**
 ```
 Loop completed for {feature}.
@@ -71,8 +81,11 @@ Loop completed for {feature}.
   Pending:   {pending} items ({cause})
   Blocked:   {blocked} items
 ```
-Render `{cause}` as "iteration limit reached" **only** when `iteration == maxIterations`
-AND `selectable > 0` — cite the `iteration`/`maxIterations` counters from
+Render `{cause}` from the runner's terminal state first (see **Runner terminal states**
+below): "stopped on request", "the run crashed (stale lock)", or "usage limit — resume
+after {sleepUntil}". Otherwise render it as "iteration limit reached" **only** when
+`loopState` is `ITERATIONS_COMPLETE` (the runner's own attestation, when reported) or
+`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
@@ -93,6 +106,37 @@ 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.
 
+## Runner terminal states (Step 4a)
+
+`status --json` may also carry `loopState`, `lock`, `sleepUntil`, `reviewPending` and
+`reviewItemIds`. All are optional: when a field is absent, skip its row and read the
+counts as before. These mirror the rows of rauf's supervisor decision table
+(`drive-rauf-loop`) that forge-5-loop decides the same way.
+
+**Clean runner finish.** When `loopState` is reported, only `COMPLETE` or `IDLE` is a
+clean terminal success. Every other value — `ERROR`, `PAUSED` (on request or with a
+stale lock), `ITERATIONS_COMPLETE`, `PAUSED_USAGE_LIMIT`, `WEEKLY_LIMIT`,
+`SLEEPING_LIMIT`, `PAUSED_HUMAN`, a still-live `RUNNING`/`REVIEWING`, or anything
+unrecognized — means the runner did **not** finish cleanly, and the run is **never**
+`complete`, even when `done == total > 0` (e.g. a process killed after its last commit
+but before writing its final state reads `PAUSED` + stale lock with every item done).
+The ladder's rung 2 (runner not finished) catches it, above the needs-human / blocked / deferred rungs. When `loopState` is absent (an older or
+non-rauf runner), this gate does not apply and the counts decide, as before.
+
+| Runner state | What it means here |
+|---|---|
+| `backlogSummary.total == 0` (any `loopState`) | Empty **or unreadable** backlog — a read failure reports all-zero counts. Never `complete`: run the **validate command** and treat it as an **operational failure** (below). |
+| `reviewPending: true` | Not complete, whatever the counts: offer the resume (**Pending review**, `references/runner-contract.md`). If the user stops here, ladder rung 2 closes `partial --cause review-pending` — even with blocked, needs-human or deferred items, which are still reported alongside. |
+| `ITERATIONS_COMPLETE` | Iteration budget spent with eligible work left — the "iteration limit reached" `partial` cause. The next loop run gets a fresh budget. |
+| `PAUSED`, `lock.stale` not true | Stopped on request (Ctrl-C, `SIGTERM`, a stop command). Report "stopped on request"; do not offer to relaunch unless the user asks. |
+| `PAUSED`, `lock.stale: true` | The run died mid-iteration and left its lock. rauf's `{bin} resume . --backlog {backlogDir}` clears the stale lock and continues. Never reach for `--force` or `reset` first. |
+| `PAUSED_USAGE_LIMIT` / `WEEKLY_LIMIT` | Halted on a usage limit: "resume after {sleepUntil}". Not a failure. |
+| `ERROR` | Crash or circuit-breaker halt (`loop_error`). Surface the error alongside the count reports; never `complete`. With work left, the next loop run re-runs it; with none, re-entry offers rauf's resume (**Unfinished runner**, `references/runner-contract.md`). |
+| `COMPLETE` with `done < total` | No eligible work left, but items are unfinished (blocked, needs-human, deferred, or pending behind a blocked dependency). The ladder's non-complete rungs apply; never reset the backlog. |
+
+**Exit codes are not the outcome.** rauf exits 1 both for a crash and for a failed review
+pass, and 0 for a requested stop or a spent budget. Read the fields above, never `$?`.
+
 ## Selecting the one `LoopOutcome` (Step 7)
 
 After Step 5's `state-complete`, select exactly **one** `LoopOutcome` from Step 4a's
@@ -106,26 +150,43 @@ authoritative final counts. Walk this ladder in order and stop at the first matc
    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
+2. **`partial` (runner not finished)** — otherwise, `reviewPending` is true, **or**
+   `loopState` is reported and is not a clean finish (**Clean runner finish**, above).
+   Pass `--cause review-pending` when `reviewPending` is true. Otherwise pass
+   `--cause runner-stopped`, except for `ITERATIONS_COMPLETE`, which is the plain
+   iteration-limit `partial` (no `--cause`). This rung fires **whatever the counts
+   say** — including `done == total`, and **above** the needs-human / blocked / deferred
+   rungs, following rauf's supervisor table: a crashed, stopped, limit-halted or
+   budget-spent runner, or an unfinished review, is recovered or resumed first. It does
+   not hide the backlog: the Step 4b needs-human / blocked / deferred reports still
+   render alongside it, so every set-aside item is surfaced in the same close (e.g.
+   **Stop here** on a pending review with blocked items closes `partial --cause
+   review-pending` and still lists the blocked items).
+3. **`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
+4. **`blocked`** — otherwise, genuine `blocked > 0`.
+5. **`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`.
+6. **`partial`** — otherwise, `pending`/`in_progress` items remain (the report above
+   names the cause). Pass `--cause dependency-starvation` only on the starvation report.
+7. **`complete`** — otherwise, and **only** when `total > 0`, every item is `done`, no
+   review is pending, and the runner finished cleanly (or reports no `loopState`).
 
 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`.
+count renders both reports above and still exits `needs-human`; a run whose runner did
+not finish renders every applicable count report and still exits rung 2's `partial`.
 
 **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
+exit 0 that still leaves pending items is `partial`, never `complete`; an exit 1 from a
+failed review with every item `done` is `partial` (`--cause review-pending`), not an
+error; and a crash or stale-lock stop with every item `done` is `partial` (`--cause
+runner-stopped`). `complete` is legitimate only when the counts show every item `done`,
+no review is pending, and the runner finished cleanly.
+
+**Retrying the non-complete outcomes.** `partial` (every cause), `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.
@@ -133,8 +194,9 @@ 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
+its output does not parse, the state directory is gone, the summary reports
+`total == 0` (an empty or unreadable backlog — show the validate command's output), 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.
 

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

@@ -155,12 +155,18 @@ maximum `timeout_ms` (1 hour), and a bounded timeout would silently stop watchin
 still-running loop.
 
 **Coverage-complete filter (silence is not success).** The filter MUST match every
-terminal and exception state, not just the happy path — otherwise a crash or hang
-looks identical to "still running." Monitor command (NDJSON path):
+terminal, exception, and pause/limit event, not just the happy path — otherwise a crash,
+hang, or hours-long usage sleep looks identical to "still running." The list below covers
+every such type in rauf's event schema (terminal: `loop_completed` / `loop_error` /
+`loop_cancelled` / `loop_paused`; exception: `item_blocked` / `needs_human` /
+`review_failed` / `llm_stuck_warning`; pause/limit: `usage_limit_hit` /
+`usage_limit_cleared` / `sleep_start` / `sleep_end`); only per-iteration narration
+(`iteration_start`, `llm_*` activity, `item_selected`, …) is left out. Monitor command
+(NDJSON path):
 
 ```
 tail -n +1 -F {backlogDir}/{loopRunner.stateDir}/events.ndjson 2>/dev/null \
-  | jq -rc --unbuffered 'select(.type | test("item_completed|item_blocked|needs_human|signal_parsed|loop_completed|loop_error|loop_cancelled|llm_stuck_warning"))'
+  | jq -rc --unbuffered 'select(.type | test("item_completed|item_blocked|needs_human|signal_parsed|loop_completed|loop_error|loop_cancelled|loop_paused|review_failed|llm_stuck_warning|usage_limit_hit|usage_limit_cleared|sleep_start|sleep_end"))'
 ```
 
 > **Use `tail -F` (follow by name), not `-f` (follow by descriptor).** The runner
@@ -177,15 +183,20 @@ tail -n +1 -F {backlogDir}/{loopRunner.stateDir}/events.ndjson 2>/dev/null \
 
   ```
   tail -n +1 -F {backlogDir}/{loopRunner.stateDir}/{loopRunner.logFile} 2>/dev/null \
-    | grep -E --line-buffered 'Item [^ ]+ (completed|blocked):|Item [^ ]+ needs human input|Loop completed|Loop error:|Circuit breaker:'
+    | grep -E --line-buffered 'Item [^ ]+ (completed|blocked):|Item [^ ]+ needs human input|Loop completed|Loop error:|Circuit breaker:|Loop cancelled|Review pass (cancelled|stopped)|Review returned unexpected signal|for review:|[Uu]sage limit'
   ```
 
   (Match `needs human input` **without** a trailing colon — the runner writes
-  `needs human input (set aside):`.)
+  `needs human input (set aside):`. `Loop cancelled` also matches *"Loop cancelled during
+  review pass (review pending)"* and the between-iteration / mid-sleep cancels;
+  `[Uu]sage limit` matches the 5-hour sleep, weekly limit, detection and wake lines.)
 
 If the Monitor is ever auto-stopped for event volume, re-arm with a tighter filter
 (drop `item_completed`, keep the exception/terminal events).
 
+An older runner that never emits a listed type (e.g. `review_failed`) simply never
+matches it — the filter needs no version gate.
+
 ## React to events as they land (Step 3e)
 
 Each Monitor event arrives as a message. React per type — but keep the user signal
@@ -213,13 +224,101 @@ high and the noise low:
 - **`loop_error`** → a real failure (this is also what a circuit-breaker halt — too many
   consecutive infra failures — emits). Surface now and an automatic session wake. Offer
   inspection / `--force` / re-run as appropriate.
-- **Stall detection** → rauf emits an **`llm_stuck_warning`** event when an iteration
-  stops making progress; the filter above includes it, so surface it live (a hang
-  warning, not yet a failure) and offer `--force` if it persists. If you instead want to
-  probe on quiet, run `{rendered watchCommand}` (or read
-  `{backlogDir}/{loopRunner.stateDir}/iteration-status.json`) and key off its
-  `stuckWarning` flag. Do **not** infer a stall from `state.json.updatedAt` alone — it is
-  not a liveness proof.
+- **`review_failed`** → the post-loop review pass failed or was stopped by a usage limit
+  (payload `reason`). Surface it now with an automatic session wake. The run is **not**
+  complete: the review stays pending (`status --json` → `reviewPending: true`). A failed
+  review makes `loop run --review` exit **1**; a usage-limit stop is a resumable limit
+  stop, not that exit-1 case. A review **cancelled** mid-pass emits **no**
+  `review_failed` — only `loop_cancelled` (human log: *"Loop cancelled during review pass
+  (review pending)"*) with `reviewPending` still set — so never rely on this event alone.
+  Nothing to do live — Step 4a reads `reviewPending` and offers the resume (**Pending
+  review**, below).
+- **Stall detection** → rauf emits an **`llm_stuck_warning`** event when an iteration's
+  output stream goes silent. Surface it live as a stall warning, not yet a failure. Read
+  its optional `currentTool` / `toolRunningMs` (absent on older runners — then report
+  the plain `silentMs` and treat it as a possible hang):
+  - `currentTool: null` → **the model itself went silent** with no tool in flight — a
+    likely hang. Offer `--force` / re-run if it persists.
+  - `currentTool` set → **a quiet tool call outlived the tool ceiling** — report it as
+    e.g. *"Bash running 31m"* (`toolRunningMs` rounded to minutes). This is usually a
+    slow verification gate, not a hung LLM: say so, and let it run unless it is clearly
+    wedged.
+
+  The thresholds are the runner's `.rauf.json` `options.stuckThresholdMs` (silence
+  before the warning, default 5 min) and `options.toolStuckThresholdMs` (how long a
+  quiet in-flight tool holds the warning off, default 30 min, measured from the tool's
+  start). A repo whose verification gate legitimately runs longer than 30 min should
+  raise `toolStuckThresholdMs` rather than learn to ignore the warning. If you instead
+  want to probe on quiet, run `{rendered watchCommand}` and key off `health.stuckWarning`.
+  Do **not** infer a stall from `state.json.updatedAt` alone — it is not a liveness
+  proof.
+- **Usage-limit waits are not stalls.** `usage_limit_hit` (`limitType`, optional
+  `reason: "usage_api_disagreement"`) followed by `sleep_start` (`sleepUntil`, `reason`)
+  means the runner is sleeping until the limit resets (`SLEEPING_LIMIT`) and will resume
+  on its own: surface it once with its `sleepUntil`, and send an automatic session wake when
+  the sleep is long (a 5-hour window). A `sleep_start` whose `reason` begins *"Usage-limit
+  banner unconfirmed"* is a 30 s / 60 s backoff (`status --json` still `RUNNING` with
+  `sleepUntil`) — narrate it at most briefly. `sleep_end` / `usage_limit_cleared` → the
+  loop is working again. A weekly or no-sleep limit halts the run instead (the process
+  exits; Step 4a reads `WEEKLY_LIMIT` / `PAUSED_USAGE_LIMIT`). None of these is a stall:
+  never offer `--force`.
+- **`loop_paused`** (`reason: "needs_human"`, `itemId`) → the run halted on a needs-human
+  item (only under rauf's opt-in `--pause-on-needs-human`; forge does not pass it by
+  default). Unlike the default set-aside mode, the loop **is** now stopped: surface it
+  with an automatic session wake; the process exits and Step 4c's recovery pass handles the
+  answer.
+
+**Pending review (Steps 2a / 4a, rauf).** A rauf `--review` run whose review pass failed, was cancelled, or was stopped by a usage
+limit leaves `status --json` with `reviewPending: true` and `reviewItemIds` (the review's
+exact scope). The loop state can read `COMPLETE`/`IDLE` with every item `done`, or
+`PAUSED`/`PAUSED_USAGE_LIMIT` — either way the run is **not complete**, and the process
+exit code (1 for a failed review) does not decide it. Both fields are optional: a runner
+that never reports them never takes this path.
+
+rauf's `resume` re-runs exactly that review (`rauf loop review --items <reviewItemIds>`),
+not a fresh loop. So when Step 4a or Step 2a sees `reviewPending: true`:
+
+1. Report it: *"The review pass for {feature} did not finish ({reason from the last
+   `review_failed` event, if any}); it covers {reviewItemIds}."*
+2. Via `AskUserQuestion`, offer **Resume the review now (recommended)** · **Stop here**. On a
+   usage-limit stop (`PAUSED_USAGE_LIMIT` / `WEEKLY_LIMIT`), say the resume only helps
+   once the limit resets (`sleepUntil`). A stop the user requested (`PAUSED`, lock
+   released) is theirs: offer, never auto-resume.
+3. **Resume:** launch `{bin} resume . --backlog {backlogDir}` backgrounded, exactly as a
+   run command (Step 3b launch guards, 3d Monitor, 3f completion), then return to Step 4a.
+   A successful review may file fix items (`review_completed.itemsCreated`); those are
+   ordinary pending work for the next loop run. rauf reviews **before** relaunching: when
+   pending items also remain (the review ran after the iteration budget ran out, or
+   blocked items strand their dependents), `resume` re-runs only the review and the
+   remaining items wait for the next loop run — say so, never launch a fresh `loop run`
+   first (it overwrites the state and drops the pending review).
+4. **Stop here:** Step 7 closes `partial` with `--cause review-pending` (see
+   `references/result-reporting.md`) — a resume route whose Step 2a re-offers this.
+
+At rung 3 (no question mechanism), do not launch: print the rendered resume command and
+close as in 4.
+
+**Unfinished runner (Step 2a re-entry, rauf).** When Step 2a finds no pending or
+in_progress items and no pending review, but `status --json` reports a `loopState` that
+is not a clean finish (**Clean runner finish** in `references/result-reporting.md` —
+e.g. `ERROR`, `PAUSED` with `lock.stale`, `ITERATIONS_COMPLETE`, a usage halt), the
+prior run closed as `partial` with `--cause runner-stopped` (or the plain iteration-limit
+`partial`), and "Nothing to run" would strand it. Instead:
+
+1. Report the state: *"The last run for {feature} did not finish cleanly ({loopState}
+   {— stale lock | — resets {sleepUntil}})."*
+2. Via `AskUserQuestion`, offer **Resume the runner (recommended)** · **Stop here**. For a
+   usage halt, the resume helps only once the limit resets; for `PAUSED` on request
+   (lock released), the stop was the user's — offer, never auto-resume.
+3. **Resume:** launch `{bin} resume . --backlog {backlogDir}` backgrounded exactly as in
+   **Pending review** step 3 (it clears a stale lock and finishes the run's bookkeeping,
+   including any post-loop review), then continue at Step 4a. rauf's recovery for
+   `ERROR` is `resume` or `reset` + re-run — never reach for `reset` or `--force` first.
+4. **Stop here**, or rung 3 (print the rendered command, do not launch): STOP without
+   touching the stage — it is already recorded `in-progress`.
+
+When `loopState` is absent, this never fires: an older or non-rauf runner keeps the
+plain "Nothing to run" stop.
 
 ## Inform-user output template (Step 3c)
 

package/adapters/pi/skills/forge-5-loop/references/stage-exit-protocol.md

@@ -47,7 +47,7 @@ an epic member. Only the flags below are stage-specific; pass no others.
 |---|---|---|
 | `forge-0-epic` | `forge-0-epic` | `--next-feature "{member}"` when a concrete member exists |
 | `forge-1-prd` … `forge-4-backlog` | that stage's own id | none beyond identity/capability |
-| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation` with `--outcome partial` |
+| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation`, `review-pending` or `runner-stopped` with `--outcome partial` |
 | `forge-6-docs` | `forge-6-docs` | `--outcome` — `complete`, `blocked`, or `skipped` (deliberate docs skip, persisted via `state-skip` before the exit; routes like `complete` with honest wording) |
 | direct `forge-verify` | `forge-verify` | `--owner direct`, `--outcome` (`passed`, `findings`, `skipped`, `failed`), and served-stage metadata |
 | nested `forge-verify` | `forge-verify` | `--owner nested`, plus the same outcome and served-stage metadata |