@garygentry/feature-forge 0.3.7 → 0.3.9

package/adapters/gemini/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/gemini/skills/forge-5-loop/references/runner-contract.md

@@ -152,12 +152,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
@@ -174,15 +180,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
@@ -210,13 +221,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 `PushNotification`. 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 a `PushNotification`. 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 a `PushNotification` 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 a `PushNotification`; 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 host's question mechanism, 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 host's question mechanism, 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/gemini/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 |

package/adapters/gemini/skills/forge-6-docs/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/gemini/skills/forge-fix/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/gemini/skills/forge-guide/references/forge-config-schema.json

@@ -235,8 +235,8 @@
         },
         "installHint": {
           "type": "string",
-          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.16.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.16.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
-          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.16.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
+          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.17.1 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.17.1 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
+          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.17.1), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
         },
         "schemaVersion": {
           "type": "string",

package/adapters/gemini/skills/forge-guide/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/gemini/skills/forge-guide/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/gemini/skills/forge-init/forge-init.md

@@ -78,11 +78,11 @@ Once the config exists, check the tooling this project's pipeline will lean on:
 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')"
 [ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
 python3 "$R/scripts/forge-session.py" doctor --json \
-  --check root-version-skew --check gh-available
+  --check plugin-root --check root-version-skew --check gh-available
 ```
 
 Follow `references/preflight-and-self-heal.md` with that result: all `ok`/`na` → say nothing and
-move on. Otherwise cluster and report. **Neither check is a stop for `forge-init`** — report and
+move on. Otherwise cluster and report. **No check here is a stop for `forge-init`** — report and
 continue; a `warn` here never aborts initialization (the procedure returns statuses; the caller
 owns its own gate). `gh-available` matters because the tooling-feedback step below tells agents
 to file issues with `gh issue create`; when `gh` is missing or unauthenticated, say so once — its
@@ -93,9 +93,11 @@ interrogated about it on every init.
 `root-version-skew` is reported the same way: a second install shadowing this one is worth
 knowing about before the first stage runs.
 
-(`plugin-root` is deliberately **not** in that list. The prelude above already exits 1 when the
-resolver fails, so by the time `doctor` runs the check can only be `ok` — narrowing to checks
-that cannot fire would be theatre.)
+`plugin-root` is reported the same way, **advisory here despite its `blocking` severity**. The
+prelude above already exits 1 when the resolver fails, so below it the check warns only when the
+resolved root is un-built canon (no `.feature-forge-bundle.json` — a repo checkout loaded
+directly): its skills cannot read their shared references and will break mid-stage. Say so once
+with the check's `remedy.description` (advise-only, `network`) and continue.
 
 ## Root hygiene — tooling feedback
 

package/adapters/gemini/skills/forge-init/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/gemini/skills/forge-verify/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/.feature-forge-bundle.json

@@ -1,6 +1,6 @@
 {
   "name": "feature-forge",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "agent": "pi",
   "generatedBy": "python3 scripts/build-adapters.py"
 }

package/adapters/pi/references/forge-config-schema.json

@@ -235,8 +235,8 @@
         },
         "installHint": {
           "type": "string",
-          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.16.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.16.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
-          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.16.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
+          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.17.1 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.17.1 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
+          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.17.1), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
         },
         "schemaVersion": {
           "type": "string",

package/adapters/pi/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/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/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/references/vendor-construct-inventory.md

@@ -27,7 +27,7 @@ vocabulary defined in `00-core-definitions.md` §8. No free-form values are perm
 | `${CLAUDE_PLUGIN_ROOT}` — sanctioned residual | 1 occurrence in `scripts/forge-root.sh` (env-fallback, REQ-RES-02 step 3) | `preserved-as-spec-allowed` | The single sanctioned residual: the resolver's documented Claude-compat fallback (REQ-RES-03 / REQ-RES-05). Exempt from the residual-var scan (`00-core-definitions.md` §6 `RESIDUAL_VAR_EXEMPT`). |
 | `${CLAUDE_PLUGIN_ROOT:-}` — bootstrap-prelude first-hint (Chunk 2b) | 1 occurrence per prelude across every canonical stamp site (the byte-pinned `BOOTSTRAP_PRELUDE`) | `preserved-as-spec-allowed` | The prelude's first resolver candidate — exact, glob-free root resolution on any Claude layout; expands to empty and is skipped when unset. Rule 3 allows it by stripping the byte-pinned prelude before its scan (detection is by `${CLAUDE_PLUGIN_ROOT` prefix, so the `:-}` default form is not an escape hatch elsewhere). `forge-agent-adapters-build` translates it to `${FEATURE_FORGE_ROOT:-}` in non-Claude bundles. |
 | `${CLAUDE_PLUGIN_ROOT}` — in `hooks/hooks.json` | 1 occurrence in `hooks/hooks.json` | `out-of-canon` | Non-canonical Claude artifact (REQ-VND-04). Not a canonical surface; exempt from the REQ-RES-03 scan. Left in place. |
-| `hooks/hooks.json` SessionStart wiring | 1 file (`hooks/hooks.json`) — Claude `SessionStart` → `bash ${CLAUDE_PLUGIN_ROOT}/scripts/session-check.sh` | `out-of-canon` | Claude-specific plugin hook wiring (REQ-VND-04, decision D3). Preserved + documented so `forge-agent-adapters-build` treats it as a Claude artifact, not portable canon. |
+| `hooks/hooks.json` SessionStart wiring | 1 file (`hooks/hooks.json`) — Claude `SessionStart` → `bash "${CLAUDE_PLUGIN_ROOT}/scripts/session-check.sh"` | `out-of-canon` | Claude-specific plugin hook wiring (REQ-VND-04, decision D3). Preserved + documented so `forge-agent-adapters-build` treats it as a Claude artifact, not portable canon. |
 | (contingency) any other vendor invocation directive | none found in the audit | — | REQ-VND-02 contingency did not fire (see Notes). If one is later surfaced, add a row with `removed` or `out-of-canon` per `02-frontmatter-purity-and-inventory.md` §3. |
 
 ## Notes

package/adapters/pi/scripts/forge-session.py

@@ -14,7 +14,8 @@ root navigator:
     python3 forge-session.py check-epic-base --feature F [--specs-dir DIR] \
         [--config FILE] [--epic E] [--json]
     python3 forge-session.py stage-exit --feature F --stage S [--owner direct|nested] \
-        [--outcome O] [--cause dependency-starvation] [--verify-mode M] \
+        [--outcome O] [--cause dependency-starvation|review-pending|runner-stopped] \
+        [--verify-mode M] \
         [--served-stage S] [--verify-capability interactive|manual] [--specs-dir DIR] \
         [--config FILE] [--epic E] [--next-feature N] [--host claude|generic|pi] [--json]
     python3 forge-session.py select-outcome --feature F --served-stage S \
@@ -470,6 +471,8 @@ from forge_session.routes import (  # noqa: E402
     _LOOP_COMPLETE_SETTLED,
     _LOOP_COMPLETE_TEXT,
     _LOOP_OUTCOME_TEXT,
+    _LOOP_PARTIAL_REVIEW_PENDING_TEXT,
+    _LOOP_PARTIAL_RUNNER_STOPPED_TEXT,
     _LOOP_PARTIAL_STARVED_TEXT,
     _LOOP_ROUTE_KIND,
     _NO_FINDINGS_RESOLVED_TEXT,
@@ -767,6 +770,8 @@ __all__ = [
     "_LOOP_COMPLETE_SETTLED",
     "_LOOP_COMPLETE_TEXT",
     "_LOOP_OUTCOME_TEXT",
+    "_LOOP_PARTIAL_REVIEW_PENDING_TEXT",
+    "_LOOP_PARTIAL_RUNNER_STOPPED_TEXT",
     "_LOOP_PARTIAL_STARVED_TEXT",
     "_LOOP_ROUTE_KIND",
     "_NO_FINDINGS_RESOLVED_TEXT",

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

@@ -467,7 +467,8 @@ def main() -> int:
     p_exit.add_argument("--outcome", default=None,
                         help="Stage-specific outcome (loop/docs/verify/fix only)")
     p_exit.add_argument(
-        "--cause", default=None, dest="cause", choices=("dependency-starvation",),
+        "--cause", default=None, dest="cause",
+        choices=("dependency-starvation", "review-pending", "runner-stopped"),
         help="Pending-attribution cause; valid only with "
              "--stage forge-5-loop --outcome partial",
     )

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

@@ -686,8 +686,37 @@ def _feature_label(feat: dict) -> str:
     return feat["name"] + (f" [{feat['epic']}]" if feat.get("epic") else "")
 
 
+#: Remedy for a resolved root that is un-built canon. Every route loads a BUILT bundle and names
+#: what it writes (#283/#317) — the npx installer's writes mirror ``installer/src`` (the sibling
+#: ``manifestPath`` manifest + every ``resolvePlacements`` destination, both scopes), pinned by
+#: ``installer/test/doctor-canon-remedy.test.ts`` against the installer's typed contract.
+#: Tier = the most conservative route (``network``: the marketplace and npm fetch).
+_CANON_ROOT_REMEDY: Final[str] = (
+    "Load a built bundle, not the repo checkout. Install: the Claude marketplace "
+    "(`/plugin install feature-forge@feature-forge`, ships ./adapters/claude; writes under "
+    "~/.claude/plugins and enables it in ~/.claude/settings.json) or "
+    "`npx @garygentry/feature-forge install` (under the install scope's root — the project, or ~ "
+    "for a global install — writes the host's bundle dir, e.g. .claude/skills/feature-forge, plus "
+    "a sibling .feature-forge.<scope>.json manifest; also Codex agent files in .codex/agents, a "
+    "managed block in .github/copilot-instructions.md for Copilot, Pi agent files in .pi/agents "
+    "(global: ~/.pi/agent/agents)). Source dogfood: rebuild with "
+    "`python3 scripts/build-adapters.py` (rewrites adapters/), then `claude --plugin-dir "
+    "adapters/claude` or FEATURE_FORGE_ROOT=adapters/<host> (neither writes files), "
+    "`pi install ./adapters/pi -l` (writes .pi/settings.json), or `scripts/dev-plugin.sh` "
+    "(writes an out-of-repo plugin dir, default ~/.cache/feature-forge-dev/claude) — see "
+    "docs/DOGFOODING.md"
+)
+
+
 def _check_plugin_root(ctx: _CheckContext) -> dict:
-    """The sibling ``forge-root.sh`` resolves an install root (never ``na``)."""
+    """The sibling ``forge-root.sh`` resolves an install root (never ``na``).
+
+    A resolved root without the neutral ``.feature-forge-bundle.json`` sentinel is
+    un-built canon (the repo checkout): its skills' prose ``Read references/X`` resolves
+    skill-local, where canon carries none of the shared refs the build fans in, so they
+    dead-reference mid-stage (#122/#305/#314). That warns — never fails (#244 policy), and
+    doctor still exits 0 (INV-3), so the repo's own ``doctor --json`` smoke stays green.
+    """
     root = ctx.plugin_root
     evidence = dict(root)
     if root.get("resolved"):
@@ -695,7 +724,18 @@ def _check_plugin_root(ctx: _CheckContext) -> dict:
         channel = root.get("channel")
         suffix = f" (version {version})" if version else " (no version manifest)"
         chan = f" via {channel}" if channel else ""
-        return _result("ok", f"resolved {root.get('root')}{chan}{suffix}", evidence)
+        built = (Path(str(root.get("root"))) / ".feature-forge-bundle.json").is_file()
+        evidence["bundleSentinel"] = built
+        if built:
+            return _result("ok", f"resolved {root.get('root')}{chan}{suffix}", evidence)
+        return _result(
+            "warn",
+            f"resolved {root.get('root')}{chan}{suffix} is un-built canon (no "
+            ".feature-forge-bundle.json): skills loaded from it cannot Read their shared "
+            "references (references/shared-conventions.md, …) skill-local (#305/#314)",
+            evidence,
+            _remedy(_CANON_ROOT_REMEDY, None, "network"),
+        )
     return _result(
         "warn",
         f"plugin root unresolved: {root.get('error', 'unknown')}",