@garygentry/feature-forge 0.1.0

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

@@ -0,0 +1,302 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-5-loop/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-5-loop
+description: Execute the autonomous coding loop (rauf by default) against a forge feature's backlog. Use when user runs /feature-forge:forge-5-loop or /feature-forge:forge-5-rauf-loop, or asks to run rauf / run the loop / implement a forge feature after the backlog is created and verified. Do NOT trigger for general rauf usage, standalone loop runs, or implementation tasks outside the forge pipeline.
+---
+
+# 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.
+
+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.
+
+Token substitution applies to every `*Command` string. Substitute:
+
+- `{bin}` → `loopRunner.bin` (default `rauf`)
+- `{backlogDir}` → the resolved backlog directory (Step 1d / 2b), relative to project root
+- `{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`.
+
+**Turn structure reminder:** Output analysis/context as text, then route ALL questions through `AskUserQuestion`. Never embed questions in text output — the user will not be prompted and the session will stall.
+
+## Step 1: Validate Prerequisites
+
+Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling.
+
+### 1a. Pipeline State Check
+
+**Resolve the feature directory first.** Invoke the **Feature Directory Resolution** block in `references/shared-conventions.md` to turn the bare feature name into `{resolvedFeatureDir}` (exit 0 → stdout is the absolute dir; exit ≥ 1 → STOP and surface the finding verbatim). Read state from `{resolvedFeatureDir}/` everywhere this skill previously wrote `{specsDir}/{feature}/` (the 1e backlog path and the Step 3a / Step 5 state writes). Standalone features resolve to their flat path exactly as today.
+
+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."
+
+### 1b. Verification Check
+
+Check if `stages.forge-verify-backlog` exists and has status `passed` or `findings-applied`. If not, use `AskUserQuestion` to warn:
+
+"Backlog hasn't been verified yet. It's recommended to run `/feature-forge:forge-verify {feature}` first to catch issues before implementation. Continue anyway?"
+
+### 1b-epic. Epic Dependency Gate
+
+Read the resolved feature's `.pipeline-state.json`. **If it has no `epic` key, skip this sub-step entirely** (standalone feature — REQ-COMPAT-01; standalone runs are unchanged). Otherwise:
+
+1. Run `render-status "{epic}" --specs-dir "{specsDir}" --json` via the helper:
+
+   ```bash
+R="$(for d in "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/*/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/epic-manifest.py" \
+  render-status "{epic}" --specs-dir "{specsDir}" --json
+   ```
+
+2. Find this feature's entry; read its `unmetDeps` (the direct `dependsOn` not yet complete-for-orchestration per `00-core-definitions.md §7`).
+3. **If `unmetDeps` is empty**, proceed to 1c with no prompt.
+4. **If `unmetDeps` is non-empty**, use `AskUserQuestion` (do NOT inline the question as prose) to warn that the feature depends on the unmet dependencies, which are not yet complete, and that running the loop now means implementing against contracts that may still change:
+
+   > "{feature} depends on {unmetDeps joined}, which are not yet complete. Running the loop now means implementing against contracts that may still change. Proceed anyway, or stop and finish the dependencies first?"
+
+   Require an **explicit "Proceed anyway"** choice to continue (REQ-ORCH-04). "Stop" aborts before any runner setup. `--force` (shared-conventions Force Mode) also bypasses this gate with the standard force warning.
+5. If `render-status` fails, **STOP** — do not silently run a loop whose dependency state is unverifiable (REQ-ROBUST-02). Surface per the exit-1/exit-2 split in the **Feature Directory Resolution** block of `references/shared-conventions.md` (exit 1 → parse `{findings[]}` from stdout; exit 2 → surface the plain `Error:` stderr line verbatim — no findings JSON to parse).
+
+This gate runs **before** the runner version/setup gates (1c/1d) so a blocked feature stops early, before any runner side-effects.
+
+### 1c. Runner Version Gate
+
+Enforce `loopRunner.minRunnerVersion` **before** doing anything else with the runner. This is what turns "the runner is missing or too old" into a clear, actionable stop instead of a cryptic mid-run failure.
+
+1. Run the **version command** (`loopRunner.versionCommand`, default `rauf version --json`) via Bash.
+2. Parse `{ "version": "<semver>" }` from stdout. Do NOT use plain `rauf version` (its human output is `rauf v0.6.0` with a `v` prefix) — always the `--json` form.
+3. **Semver-compare** (NOT string-compare) the reported version against `loopRunner.minRunnerVersion` (default `0.6.0`), numerically by major, then minor, then patch.
+
+**Any of the following is a HARD GATE FAILURE — do NOT proceed to run the loop.** STOP, show `loopRunner.installHint`, and include the raw command output for diagnosis:
+
+- The version command is not found or exits non-zero (the binary isn't installed).
+- Its stdout is not valid JSON, has no `version` field, or `version` is not a valid semver string.
+- The reported version is **< `minRunnerVersion`**.
+
+For the version-too-old case, phrase it concretely, e.g.: "Your rauf is {reported}, but feature-forge needs ≥ {minRunnerVersion} — 0.6.0 is the floor that ships the agent-selection surface (`--agent` / `rauf agents`) the loop relies on. {installHint}". When the gate fails because the output couldn't be parsed, say so and show what the command printed before the `installHint`.
+
+> `installHint` points at the runner **CLI** install/upgrade — distinct from
+> `setupHint` (1d), which installs the runner's per-project artifacts.
+
+### 1d. Runner Setup Check (precondition file)
+
+Check that `loopRunner.preconditionFile` (default `.rauf.json`) exists in the project root. If not:
+
+- **If `loopRunner.name == "rauf"` and a legacy `.ralph.json` (or `.ralph/` directory) exists**, this is an un-migrated Ralph project. STOP and tell the user:
+
+  "This project is still on the legacy **Ralph** layout. Run `rauf migrate .` first (the loop runner only understands `.rauf/` and `RAUF_*` signals), then re-run `/feature-forge:forge-5-loop {feature}`."
+
+- **Otherwise**, STOP and show `loopRunner.setupHint` (default: "Run `rauf install .` …"), e.g.:
+
+  "The loop runner isn't set up in this project ({preconditionFile} is missing). {setupHint}"
+
+### 1e. Backlog File Check
+
+Resolve the backlog file path (matching forge-4-backlog's composition rule, item 015 / §6.2):
+- If `backlogDir` is set in `forge.config.json`: use `{backlogDir}/{feature}/backlog.json` (the per-feature subpath, so each epic member's backlog stays independent — the `{feature}` segment prevents collisions across a multi-feature epic)
+- Otherwise: use `{resolvedFeatureDir}/backlog.json`
+
+Verify the file exists on disk. If not, STOP and tell the user: "No backlog.json found at {path}. Run `/feature-forge:forge-4-backlog {feature}` to generate it."
+
+## 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`.
+
+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.
+
+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."
+
+If there are `blocked` items, note them — the user may want `--retry-blocked`.
+
+### 2b. Resolve Backlog Directory
+
+`{backlogDir}` is a **directory path** (not a file path), relative to the project root.
+
+- 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:
+
+```
+rauf loop run . --backlog specs/auth --iterations 15
+```
+
+### 2d. Confirm with User
+
+Use `AskUserQuestion` to present the rendered run command and options. The following block is the content for `AskUserQuestion` — do NOT output it as text:
+
+```
+Ready to run the loop for {feature}:
+
+  {rendered runCommand}
+
+Backlog summary:
+  - Pending: {pending}
+  - In progress: {in_progress}
+  - Done: {done}
+  - Blocked: {blocked}
+  - Iterations: {iterationCount} ({activeItems} items x {loopIterationMultiplier} multiplier)
+
+Optional flags you can add (rauf): --review, --model <model>, --timeout <min>,
+--retry-blocked. For the full optional-flags catalog and the model-selection
+precedence (item.model > --model/options > project default > provider default),
+read references/runner-contract.md.
+
+Proceed with this command, or would you like to adjust?
+```
+
+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`. If the user requests additional flags, append them to the rendered run command.
+
+#### 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:
+
+- **(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 `AskUserQuestion` 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`, `AskUserQuestion` 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.
+- **(e) Optional-flags line.** Replace the confirmation's optional-flags line with one that lists `--agent <id>` first plus the agent precedence pointer (`item.provider > --agent > project defaultAgent > runner default`) alongside the model precedence.
+- **(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`
+
+### 3b. Launch Background Process
+
+Launch the loop **backgrounded** (`run_in_background: true`) so it survives session end and does not block the session, and prefer the machine-readable event stream (`loopRunner.eventStreamCommand`, default for rauf) redirected to a stable `events.ndjson` so the session can supervise it live; fall back to the plain `runCommand` (tailing the human log) when no `eventStreamCommand` is configured. 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 event-stream vs. log-fallback detail, read `references/runner-contract.md`.
+
+Loop runs can take significant time (minutes to hours depending on backlog size).
+
+### 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`.
+
+### 3d. Arm a Monitor on the event stream, and react to events
+
+Arm the **`Monitor` tool** 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 `Monitor`'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`.
+
+### 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: Check Results
+
+When the background process completes (its exit notification):
+
+### 4a. Get Final Backlog State
+
+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.
+
+### 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`.
+
+## Step 5: Update Pipeline State
+
+Update `{resolvedFeatureDir}/.pipeline-state.json`:
+
+1. Set `stages.forge-5-loop`:
+   - `status`: `"complete"` if all backlog items are `done`, otherwise `"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`
+
+**No git commit is needed** — the loop runner commits atomically per completed item during the run. The implementation code is already committed.
+
+> **Note:** Step 5's "no git commit needed" remark refers to *implementation code*, which the runner commits per-item. The epic handoff's commit in Step 6 below is of *pipeline state / manifest* — a distinct artifact — and applies only to epic members.
+
+## 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 features and partial runs end exactly as today (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 `AskUserQuestion` (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).
+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 (features whose every dependency is now complete and that are not themselves complete) and `nextCommand`.
+   - **None actionable** (everything done, or remaining features still blocked): 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 being reported complete.
+     - Otherwise, list what is still blocked and on which dependencies. End — do not prompt to start a feature that cannot start.
+   - **One or more actionable:** use `AskUserQuestion` 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.** For the picked 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.
+
+## Gotchas
+
+- `{backlogDir}` is a **directory path**, not a file path. Pass `specs/auth`, not `specs/auth/backlog.json`.
+- rauf resolves `RAUF.md` with fallback: checks `{backlogDir}/.rauf/RAUF.md` first, then the project's `.rauf/RAUF.md`. As long as the runner is installed in the project, the prompt template will be found.
+- State files (state.json, {loopRunner.logFile}, etc.) are created at `{backlogDir}/{loopRunner.stateDir}/` — this is within the feature's spec directory and is expected. State is 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.
+- Never run the run command in the foreground (without `run_in_background`) — 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 `Monitor` tool (3d), which is harness-driven, not a sleep loop. Never `sleep`/poll in the foreground to wait for the loop.
+- The `Monitor` 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.
+- If a previous loop run left a stale lock, the user may need to pass `--force` to clear it. rauf will report this error clearly.
+- The version gate (1c) uses the `--json` form on purpose; never parse `rauf version`'s human output.

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

@@ -0,0 +1,63 @@
+# forge-5-loop — Step 4b Result-Report Templates
+
+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.
+
+**All items done:**
+```
+Loop completed for {feature}. All {N} items implemented successfully.
+
+Next steps:
+  - /feature-forge:forge-verify {feature} impl   Verify the implementation
+  - /feature-forge:forge-6-docs {feature}         Generate architecture docs
+```
+
+**Some items need a human:**
+```
+Loop completed for {feature}.
+  Completed:   {done}/{total}
+  Needs human: {needsHuman} items (set aside during the run)
+
+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:**
+```
+Loop completed for {feature}.
+  Completed: {done}/{total}
+  Blocked:   {blocked} items
+
+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
+```
+
+**Some items deferred (runner gave up after retries — "false blocks"):**
+```
+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):**
+```
+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.
+```

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

@@ -0,0 +1,214 @@
+# forge-5-loop — Loop-Runner Contract (launch, supervision, model precedence)
+
+This file holds the detailed loop-runner contract relocated out of
+`forge-5-loop/SKILL.md`: the event-stream vs. log-fallback **launch** detail
+(Steps 3b/3d/3e), the structured-surface **monitoring** caveats, the **model
+precedence** rule, and the **optional-flags catalog** referenced from Step 2d.
+Every command below is rendered from `loopRunner` with token substitution, as in
+the skill body.
+
+## Model selection precedence (Step 2d)
+
+The runner picks the per-iteration model by precedence (highest wins):
+
+```
+item.model  >  --model / options  >  project default  >  provider default
+```
+
+So a backlog item's own `model` field overrides a `--model` flag passed to the
+run, which overrides the project's configured default, which overrides the
+runner/provider default. Pass `--model <model>` (optional flag below) to override
+the project default for the whole run.
+
+## Agent selection (Step 2d)
+
+This section is **parallel** to `## Model selection precedence` above: 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.
+
+## 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 below).
+                    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 precedence above)
+  --timeout <min>   Per-session timeout in minutes (default: 60)
+  --retry-blocked   Unblock and retry previously blocked items
+```
+
+## Launch detail (Step 3b — background process)
+
+Launch the loop **backgrounded** so it survives session end and does not block the
+session, and prefer the machine-readable event stream so the session can supervise
+it live.
+
+- **If `loopRunner.eventStreamCommand` is configured (default for rauf):** render it
+  (it appends `--ndjson` to the run) and launch via the Bash tool with
+  `run_in_background: true`, redirecting stdout to a stable events file:
+
+  ```
+  mkdir -p {backlogDir}/{loopRunner.stateDir} && {rendered eventStreamCommand} > {backlogDir}/{loopRunner.stateDir}/events.ndjson 2>&1
+  ```
+
+  (The `mkdir -p` guards the very first run, before the runner has created its
+  state dir.) This emits one JSON event per line **and** keeps the loop detached. The background
+  task's exit notification remains the single authoritative terminal signal (Step 4).
+- **Fallback (runner has no `eventStreamCommand`):** launch the plain `runCommand`
+  with `run_in_background: true`. The session will then supervise by tailing the
+  human log (3d fallback) instead of the NDJSON file.
+
+Loop runs can take significant time (minutes to hours depending on backlog size).
+
+## Arm a Monitor on the event stream (Step 3d)
+
+Arm the **`Monitor` tool** on the structured event stream so events flow back into
+this session as they happen. Use **`persistent: true`** — runs can exceed `Monitor`'s
+maximum `timeout_ms` (1 hour), and a bounded timeout would silently stop watching a
+still-running loop.
+
+**Coverage-complete filter (silence is not success).** The filter MUST match every
+terminal and exception state, not just the happy path — otherwise a crash or hang
+looks identical to "still running." Monitor command (NDJSON path):
+
+```
+tail -n +1 -f {backlogDir}/{loopRunner.stateDir}/events.ndjson 2>&1 \
+  | jq -rc --unbuffered 'select(.type | test("item_completed|item_blocked|needs_human|signal_parsed|loop_completed|loop_error|loop_cancelled|llm_stuck_warning"))'
+```
+
+- **Fallback (log tail, no NDJSON):** match the runner's **structured prose
+  prefixes**, never the `RAUF_*` tokens (those leak inside agent output and
+  false-match). For rauf:
+
+  ```
+  tail -n +1 -f {backlogDir}/{loopRunner.stateDir}/{loopRunner.logFile} \
+    | grep -E --line-buffered 'Item [^ ]+ (completed|blocked):|Item [^ ]+ needs human input|Loop completed|Loop error:|Circuit breaker:'
+  ```
+
+  (Match `needs human input` **without** a trailing colon — the runner writes
+  `needs human input (set aside):`.)
+
+If the Monitor is ever auto-stopped for event volume, re-arm with a tighter filter
+(drop `item_completed`, keep the exception/terminal events).
+
+## React to events as they land (Step 3e)
+
+Each Monitor event arrives as a message. React per type — but keep the user signal
+high and the noise low:
+
+- **`item_completed`** → increment a running tally. These land minutes apart, so they
+  won't trip the volume auto-stop; still, surface a coalesced milestone ("12/30 done")
+  rather than echoing every line. For an exact breakdown, run the one-shot
+  `{rendered statusJsonCommand}` and report `done/total` from `backlogSummary`.
+- **`needs_human`** (or `signal_parsed` with `signal: "needs_human"`) → **surface
+  immediately** and send a **`PushNotification`** (an hours-long run means the user has
+  likely stepped away). **Important — the loop is NOT paused:** the runner has set that
+  item aside and kept working other items. So report *what* needs a human and *which*
+  item, then either (a) collect the user's answer via `AskUserQuestion` to **stage a
+  post-run retry**, or (b) offer to **cancel the run early** if the answer changes the
+  whole plan. Do not tell the user the loop is waiting on their reply — it isn't.
+- **`item_blocked`** → surface the blocked item + reason now (visibility) and
+  accumulate for the final summary. Use `{rendered statusJsonCommand}` to distinguish a
+  genuine `blocked` from a runner-`deferred` "false block" (`backlogSummary.deferred`).
+- **`loop_error`** → a real failure (this is also what a circuit-breaker halt — too many
+  consecutive infra failures — emits). Surface now and `PushNotification`. Offer
+  inspection / `--force` / re-run as appropriate.
+- **Stall detection** → rauf emits an **`llm_stuck_warning`** event when an iteration
+  stops making progress; the filter above includes it, so surface it live (a hang
+  warning, not yet a failure) and offer `--force` if it persists. If you instead want to
+  probe on quiet, run `{rendered watchCommand}` (or read
+  `{backlogDir}/{loopRunner.stateDir}/iteration-status.json`) and key off its
+  `stuckWarning` flag. Do **not** infer a stall from `state.json.updatedAt` alone — it is
+  not a liveness proof.
+
+## Inform-user output template (Step 3c)
+
+This is the verbatim "Loop started…" output the session shows the user after
+launch. Commands are the rendered `loopRunner` monitoring commands.
+
+When the agent surface is gated on (`loopRunner.agentArgument` present), add the
+`Coding agent:` line shown below immediately after the opening `Loop started …`
+line, using the same `sourceLabel` mapping as the Step 2d confirmation
+(`RUN` → `"per-run selection"`, `PROJECT` →
+`"project default (loopRunner.defaultAgent)"`, `DEFAULT` →
+`"runner default — claude-cli"`). When the gate is off, the line is **absent** and
+the template is byte-identical to today (REQ-PLUG-02). When the launch proceeded via
+the UNAVAILABLE *proceed-anyway* path, use the audit variant instead:
+
+```
+Coding agent: {resolved.agent or claude-cli} (source: {sourceLabel}).
+Coding agent: {resolved.agent} (source: {sourceLabel}; proceeded despite unavailability warning).
+```
+
+(The two lines above are alternatives — the first is the normal line; the second
+replaces it only on the proceed-anyway path. This is session-side prose only; it
+introduces no new event type, so the Step 3d Monitor filter is unchanged.)
+
+```
+Loop started for {feature} ({N} items to process).
+Coding agent: {resolved.agent or claude-cli} (source: {sourceLabel}).   # only when the agent surface is gated on
+This session is now monitoring it live — I'll report milestones and stop you in if
+the loop needs a human. The loop also runs detached and survives this session ending.
+Each item gets a fresh agent session with full context from the backlog and specs.
+
+Watch directly if you like (another terminal or `!` prefix):
+  {rendered statusCommand}              # one-shot status
+  {rendered followCommand}              # stream live events (human)
+  {rendered logCommand}                 # tail log file
+  {rendered listCommand}                # check item statuses
+
+State files are at: {backlogDir}/{loopRunner.stateDir}/
+  - state.json             (loop state)
+  - events.ndjson          (structured event stream this session is watching)
+  - {loopRunner.logFile}   (human event log)
+  - iteration-status.json  (live activity, incl. stuckWarning)
+```