@garygentry/feature-forge 0.3.1 → 0.3.4

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

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

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

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

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

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