@garygentry/feature-forge 0.3.0 → 0.3.2

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

@@ -7,24 +7,19 @@ alwaysApply: false
 
 # 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 — there are no hardcoded `rauf …` commands in this skill, and even the human log filename is tokenized as `{loopRunner.logFile}`.
 
 ## Resolve the loop runner
 
-Read `forge.config.json`. Build the effective `loopRunner` by taking its
-`loopRunner` block (if present) and filling any missing field from the defaults
-in `references/forge-config-schema.json`. **If `forge.config.json` has no
-`loopRunner` block at all, state plainly: "No loopRunner configured — defaulting
-to the rauf loop runner."** then proceed with the full default block.
+Resolve the effective `loopRunner` with the command below — it merges this project's `loopRunner` block over the schema defaults deterministically, so do not read the config schema for defaults. **If `forge.config.json` has no `loopRunner` block at all, state plainly: "No loopRunner configured — defaulting to the rauf loop runner."** then proceed with the full default block, which is exactly what the call returns. If the call exits 2, surface the plain `Error:` line from stderr verbatim and fall back to the documented rauf defaults.
+
+```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" effective-config --config ./forge.config.json --json
+```
 
 Token substitution applies to every `*Command` string. Substitute:
 
@@ -33,8 +28,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.
 
@@ -50,9 +44,14 @@ Read `{resolvedFeatureDir}/.pipeline-state.json`. If not in force mode, `stages.
 
 ### 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):
 
-"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**.
+1. **`passed`** — proceed with no prompt.
+2. **`findings-applied`** — fixes were applied but nothing re-verified them: this status deliberately clears freshness, so the backlog's verification is still outstanding, not silently satisfied. Use the host's question mechanism to offer: **Re-verify first (recommended)** (`/feature-forge:forge-verify {feature} backlog`) · **Continue without re-verifying** — an explicit deferral, persisted via `state-verify --status skipped` (never by hand; add `--epic "{epic}"` for members) before the loop starts, so it is a recorded decision and not a walked-past gate.
+3. **`auto-verify-pending`** — automatic verification *was* scheduled for the backlog stage and the debt *was* durably recorded; it simply has not run. Say exactly that, naming the served stage and the retry command: *"{feature}: automatic verification is still pending for forge-4-backlog; run `/feature-forge:forge-verify {feature} backlog` to resolve it."* Then use the host's question mechanism to offer the same two choices as case 4. Never report this as "hasn't been verified yet" — "nobody ever asked for this" and "this was owed and dropped" are different facts and the operator acts on them differently.
+4. **Anything else** (absent, `pending`, `skipped`, `findings-reported`) — use the host's question mechanism to warn with the cost of skipping: "Backlog hasn't been verified yet. Recommended: run `/feature-forge:forge-verify {feature}` first — the loop implements items autonomously and commits as it goes, so a bad item (wrong scope, missing dependency, untestable acceptance criteria) is far cheaper to catch now than after several commits build on it. Continue anyway?"
+
+Cases 3 and 4 offer the same choices: **Verify first (recommended)** · **Continue without verifying**. The proceed-anyway path is unchanged.
 
 ### 1b-epic. Epic Dependency Gate
 
@@ -162,34 +161,34 @@ Backlog summary:
   - Iterations: {iterationCount} ({activeItems} items x {loopIterationMultiplier} multiplier)
 
 For the model-selection precedence (item.model > --model/options > project default >
-provider default) and the full optional-flags catalog, read references/runner-contract.md.
+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.
 
 #### 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/runner-contract.md`; read it. When the gate is on, augment Step 2d in order:
+**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).
 - **(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/runner-contract.md`.
-- **(e) Optional-flags line.** Augment the confirmation block's closing flags/precedence pointer to list `--agent <id>` first plus the agent precedence pointer (`item.provider > --agent > project defaultAgent > runner default`) alongside the model precedence.
+- **(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`.
+- **(e) Optional-flags line.** Augment the confirmation block's closing flags/precedence pointer to list `--agent <id>` first plus the agent precedence pointer (`item.provider > --agent > project defaultAgent > runner default`) alongside the model precedence; the full catalog is `## Optional flags catalog (Step 2d, rauf)` in `references/agent-selection.md`.
 - **(f) Resolved-agent line.** Add to the confirmation block: `Agent: {resolved.agent or claude-cli} (source: {sourceLabel})` — `sourceLabel`: `RUN` → `"per-run selection"`, `PROJECT` → `"project default (loopRunner.defaultAgent)"`, `DEFAULT` → `"runner default — claude-cli"`.
 
 ## Step 3: Execute the Loop
 
 ### 3a. Update Pipeline State
 
-Before launching, update `{resolvedFeatureDir}/.pipeline-state.json`:
-- Set `stages.forge-5-loop.status` to `in-progress`
-- Set `stages.forge-5-loop.startedAt` to current ISO timestamp
-- Set `currentStage` to `forge-5-loop`
-- Update `updatedAt`
+Before launching, record the pre-launch marker by running `state-enter` — one atomic write that sets `stages.forge-5-loop.status` to `in-progress`, `stages.forge-5-loop.startedAt` to the current ISO timestamp, `currentStage` to `forge-5-loop`, and refreshes `updatedAt`. Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol in `references/shared-conventions.md`:
+
+```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-enter --feature "{feature}" --stage forge-5-loop --specs-dir "{specsDir}"
+```
 
 Then commit this state write before launching (mandatory). The runner refuses to run with uncommitted changes (*"…pass --force"*), and this marker is itself one — so an otherwise-clean repo fails its first launch unless committed. Commit it via the shared-conventions **Git Commit Protocol** (epic members: stage `{specsDir}/{epic}/`): `{commitPrefix}({feature}): forge-5-loop in-progress` — a launch precondition, required regardless of `gitCommitAfterStage`. Unrelated leftover changes still trip the refusal; surface it, never auto-pass `--force`. See `references/runner-contract.md`.
 
@@ -199,13 +198,7 @@ Launch the loop **backgrounded** (the host's background-execution mechanism) so
 
 ### 3c. Inform User
 
-Tell the user the run has started and that **this session is now actively
-supervising it** — they don't need to babysit a terminal — and surface the rendered
-`loopRunner` monitoring commands (`statusCommand` / `followCommand` / `logCommand` /
-`listCommand`) and the state-file locations under
-`{backlogDir}/{loopRunner.stateDir}/` so they can watch directly if they like. The
-verbatim "Loop started…" inform-user output template is in
-`references/runner-contract.md`.
+Follow the **Inform-user output template (Step 3c)** section of `references/runner-contract.md` — it carries this step's instruction and the verbatim "Loop started…" template.
 
 ### 3d. Arm a Monitor on the event stream, and react to events
 
@@ -228,11 +221,7 @@ rules, read `references/runner-contract.md`.
 
 ### 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
 
@@ -249,49 +238,58 @@ is not configured. You will already have most of this from the live tally in 3e.
 ### 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** (iteration limit reached) — are in `references/result-reporting.md`, together with the Step 7 `LoopOutcome` ladder these same counts feed. The reports are descriptive only: they carry no next command, and the run does not end here. If the authoritative counts cannot be obtained at all (4a failed or its output does not parse), follow **Operational failure before the counts are known** in that same file: surface the failure and its recovery, and close nothing — no outcome, no stage exit, no terminal block.
 
 ## Step 5: Update Pipeline State
 
-Update `{resolvedFeatureDir}/.pipeline-state.json`:
+Record completion by running `state-complete` (below). Evaluate "all backlog items are `done`" yourself and pass the result as `--status`: `complete` if every item is `done`, else `in-progress`. The verb records `completedAt`, the version, `basedOnVersions` and `artifacts`, and refreshes `updatedAt`. Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol.
 
-1. Set `stages.forge-5-loop`: `status` = `"complete"` if all backlog items are `done`, else `"in-progress"`; `completedAt` = current ISO timestamp (only if complete); `basedOnVersions` = `{"forge-4-backlog": <current version from pipeline state>}`; `artifacts` = `["{backlogDir}/{loopRunner.stateDir}/state.json"]`.
-2. If all items complete: set `currentStage` to `"forge-6-docs"`
-3. Update `updatedAt`
+```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-complete --feature "{feature}" --stage forge-5-loop --version {n} --status "<complete|in-progress>" --based-on "forge-4-backlog=<current version from pipeline state>" --artifact "{backlogDir}/{loopRunner.stateDir}/state.json" --specs-dir "{specsDir}"
+```
 
 **No git commit is needed** — the loop runner commits implementation code atomically per completed item during the run. (Step 6's commit, epic members only, is of pipeline state / manifest — a distinct artifact.)
 
 ## 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 rather than via the easily-missed "Next steps" text. Use the host's question mechanism (NOT inline prose) to offer: *"{feature}'s loop is complete. Recommended: run `/feature-forge:forge-verify {feature} impl` to audit the implementation before generating docs. Run it now, or skip to forge-6-docs?"* On **run**, invoke `feature-forge:forge-verify {feature} impl` with the literal `owner: nested` token in the dispatching prompt — this dispatch happens inside the loop stage, so **you** remain the sole terminal owner and the branch skill returns its structured result and prints no terminal block of its own (see "Branch ownership: the `owner:` token" in `references/stage-exit-protocol.md`). On **skip**, persist the skip through `state-verify` using the fence below (mirrors `forge-4-backlog`'s skip handling) — the forge-6-docs backstop re-surfaces the skip. Either way, do **not** name a next command here: Step 7 routes, and it routes differently depending on what this step recorded.
+
+**The skip is written by `state-verify`, never by hand.** Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol in `references/shared-conventions.md`. On exit 2, surface the plain `Error:` line verbatim and stop: the skip is not persisted, so Step 7 would route on state that is not on disk.
+
+```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**, invoke `feature-forge:forge-verify {feature} impl` with the literal `owner: nested` token in the dispatching prompt — this dispatch happens inside the loop stage, so **you** remain the sole terminal owner and the branch skill returns its structured result and prints no terminal block of its own (see "Branch ownership: the `owner:` token" in `references/stage-exit-protocol.md`). On **skip**, persist the skip through `state-verify --status skipped` using Step 5b's fence (add `--epic "{epic}"` — required for members) so the Step 7 exit reads a recorded decision instead of re-asking the question the user just answered; completion is then judged on the §7 rule with impl-verify explicitly skipped.
 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` (`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
 

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

@@ -0,0 +1,116 @@
+# forge-5-loop — Agent Selection (Step 2d, conditional)
+
+The agent-selection surface, its Claude-only model-alias guard, and the optional-
+flags catalog. Loaded ONLY when `loopRunner.agentArgument` is present (the Step 2d
+capability gate); when the gate is off, Step 2d is byte-identical to today and this
+file is never read.
+
+## Agent selection (Step 2d)
+
+This section is **parallel** to `## Model selection precedence` in
+`references/runner-contract.md`: it governs which **coding agent** rauf drives for the
+run. The entire surface is
+**presence-gated** on `loopRunner.agentArgument` — when that field is absent or
+empty, there is no selector, no probe, and no `{agent}` substitution, and Step 2d /
+Step 3c are byte-identical to today (capability gate;
+`02-config-schema-and-gating.md`, REQ-PLUG-02). The rest assumes the gate is on.
+
+**Precedence (highest wins):**
+
+```
+item.provider  >  --agent (run selection)  >  loopRunner.defaultAgent (project)  >  runner default (claude-cli)
+```
+
+**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
+`--agent {agent}` occupying rauf's **run layer only**. rauf alone resolves
+item-vs-run via its own 5-layer resolver, sitting the per-item `BacklogItem.provider`
+**above** forge's run layer — so a run selection can never clobber a deliberate
+per-item agent. forge **never reads, writes, or overrides** `BacklogItem.provider`
+(REQ-AGENT-05). When forge sends nothing (the default path), rauf applies its own
+default `claude-cli`, byte-identical to today. Empty/whitespace selections are
+treated as unset, and an explicit pick of the runner default id collapses to the
+default path (append nothing, run no probe). See
+`03-selection-resolution-observability.md §3–§4`.
+
+**Availability pre-check + disambiguation.** For a **non-default** resolved id only,
+forge runs `loopRunner.agentsProbeCommand` **once** (no retries) and classifies the
+id by **membership** in the advertised set (`{ row.id for row in agents }`), then the
+matching row's `available` flag — **never** by exit code, because `rauf agents
+--json` always exits 0 (an unknown id is simply absent; a known-unavailable one is
+present with `available: false`):
+
+- **UNKNOWN** (`∉` advertised set): hard-reject **before any loop side-effect**,
+  listing the sorted valid ids; **no proceed-anyway**; the value never interpolates
+  into `{agent}` (the advertised set IS the allow-list — REQ-SEC-01).
+- **UNAVAILABLE** (member, `available == False`): warn with the row's `detail`, then
+  offer **proceed-anyway OR choose-another** — never silent.
+- **AVAILABLE** (member, `available == True`): proceed; the validated id fills
+  `{agent}`.
+- **Probe failure** (non-zero exit / unparseable / wrong shape / empty `agents[]` /
+  row missing `id`): surface it and offer **choose-another OR abort**; never launch
+  the non-default agent unvalidated, never silently fall back to the default.
+
+The default / `claude-cli` path runs **no** probe (zero extra cost). See
+`04-availability-precheck.md` for the full pre-check, classification, and allow-list,
+and `02-config-schema-and-gating.md` for the capability gate.
+
+> **Probe false-negative for Claude Code installs (advisory).** `rauf agents` may
+> report `claude-cli` **unavailable** (e.g. *"credentials file not found:
+> ~/.config/claude-code/credentials.json"*) even when a working `claude` CLI
+> authenticates elsewhere — the probe's credential heuristic doesn't cover every
+> install. This is a rauf probe concern, not something forge-5-loop fixes. The
+> **default-agent path skips the probe entirely**, so an ordinary default run is
+> unaffected; only an **explicit** `--agent claude-cli` would be flagged UNAVAILABLE,
+> and the existing **proceed-anyway** path (above) covers it. Do not attempt to
+> patch rauf's probe from here.
+
+### Claude-only model-alias guard (Step 2d, sub-step d-model)
+
+When the resolved agent is **non-default** (not the default / `claude-cli` path),
+forge must guard against a backlog whose items pin **Claude-specific** model aliases.
+forge-4-backlog (via the rauf author-backlog skill) writes Claude tier aliases
+(`opus` / `sonnet`) into each item's `model`. Because rauf's precedence puts
+`item.model` **above** `--agent`, the alias is forwarded verbatim to the selected
+agent; a non-Claude agent (e.g. codex) then 400s — *"The 'sonnet' model is not
+supported when using Codex with a ChatGPT account."* — so **every** spawn exits 1 and
+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**
+(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).
+
+> **Follow-up (out of scope here — rauf repo).** The durable fix would be for the
+> rauf `author-backlog` skill to keep `model` **provider-neutral** by default (or to
+> document that writing a tier alias binds the backlog to Claude agents). That lives
+> in the separate rauf plugin/repo, not feature-forge; tracked as a follow-up.
+>
+> **Follow-up (out of scope here — rauf repo).** The durable fix for the root/sandbox
+> refusal (see "Root/sandbox env guard" under
+> `## Launch detail (Step 3b — background process)` in `references/runner-contract.md`)
+> is for **rauf itself** to honor
+> `IS_SANDBOX` when it launches `claude --dangerously-skip-permissions` as root (or to
+> detect root+flag-refused and emit a clear error instead of an opaque circuit-break).
+> feature-forge's launch-time export is the mitigation; the upstream fix lives in the
+> rauf plugin/repo. Track as a follow-up.
+
+## Optional flags catalog (Step 2d, rauf)
+
+These are the optional flags the user may add to the rendered run command. If the
+user requests additional flags, append them to the rendered run command.
+
+```
+  --agent <id>      Coding agent rauf drives this run (see `## Agent selection` above).
+                    Only the runner's advertised ids are valid; an unknown id is
+                    rejected before launch. Shown only when the runner advertises
+                    an agent surface (loopRunner.agentArgument present).
+  --review          Run a review pass after all iterations (extra agent session)
+  --model <model>   Override the model (see `## Model selection precedence` in
+                    `references/runner-contract.md`)
+  --timeout <min>   Per-session timeout in minutes (default: 60)
+  --retry-blocked   Unblock and retry previously blocked items
+```
+

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

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