@garygentry/feature-forge 0.1.0

package/adapters/claude/skills/forge-4-backlog/SKILL.md

@@ -0,0 +1,146 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-4-backlog/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-4-backlog
+description: Generate a structured backlog.json from forge implementation specs, then validate it via the loop runner. Use when user runs /feature-forge:forge-4-backlog or asks to create a backlog for a forge feature after specs are complete. This is the canonical backlog generator for the forge pipeline. Do NOT trigger for standalone backlog creation outside the forge pipeline context.
+argument-hint: <feature-name>
+---
+
+# forge-4-backlog — Backlog Generator (pipeline orchestrator)
+
+Generate a complete, validated `backlog.json` from the implementation spec
+suite, ready for the loop runner.
+
+This skill is a **thin orchestrator**: it owns the *pipeline* concerns
+(prerequisite checks, spec loading, plan review, validation, pipeline-state and
+commit). The actual **authoring craft** — granularity, acceptance criteria,
+`agentDelegation`, the schema, examples — lives in the rauf plugin's
+**`author-backlog`** skill, which this skill delegates to. That keeps a single
+home for backlog-authoring knowledge, shared with the repo-wide ad-hoc flow.
+
+## Prerequisites
+
+Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding. Resolve the feature directory `{resolvedFeatureDir}` via the **Feature Directory Resolution** block in `references/shared-conventions.md` — do not hardcode `{specsDir}/{feature}/` (see Step 1).
+
+Resolve the **backlog directory** `{backlogDir}`:
+- **`backlogDir` unset (default):** the backlog lives at the resolved feature directory — `{resolvedFeatureDir}/backlog.json` — for both flat and nested features, exactly as today.
+- **`backlogDir` configured:** compose a **per-feature subpath** — `{backlogDir}/{feature}/` — so each epic member's backlog stays independent (the authored file lands at `{backlogDir}/{feature}/backlog.json`). A bare shared `backlogDir` would collide across a multi-feature epic and violate REQ-COMPAT-03; the `{feature}` segment prevents that. Standalone features under a configured `backlogDir` likewise resolve to `{backlogDir}/{feature}/`, which is backward-compatible because each standalone feature name is already unique.
+
+This is the **single** place this rule is implemented. forge-5-loop's backlog-file check must read the same composed `{backlogDir}/{feature}/backlog.json` (that matching forge-5-loop edit lands in item 016), and forge-verify's backlog-mode load uses the same path. rauf itself is unchanged: backlogs remain per-feature and rauf is still launched against a single per-feature backlog path — only the *path composition* changes (REQ-COMPAT-03).
+
+**Let `{resolvedBacklogDir}` denote the composed target of this rule** — i.e. `{backlogDir}/{feature}` when a `backlogDir` is configured, else `{resolvedFeatureDir}`. Every downstream step below (authoring, validation) uses `{resolvedBacklogDir}`, never the bare config value, so the per-feature `{feature}` segment is never dropped.
+
+Resolve the **loop runner** from the `loopRunner` block in `forge.config.json`, filling missing fields from the defaults in `references/forge-config-schema.json` (defaults to rauf). You need its `bin`, `validateCommand`, `versionCommand`, `minRunnerVersion`, and `installHint`.
+
+**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
+
+**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 and specs from `{resolvedFeatureDir}/` everywhere this skill previously wrote `{specsDir}/{feature}/`. Standalone features resolve to their flat path exactly as today.
+
+**Prerequisite check:** Read `{resolvedFeatureDir}/.pipeline-state.json`. If not in force mode, stages `forge-1-prd`, `forge-2-tech`, and `forge-3-specs` must all be `complete`. If not, STOP and tell the user which prerequisites are missing.
+
+**Strongly recommended:** Check if specs have been verified. If not, use `AskUserQuestion` to warn: "Specs haven't been verified yet. It's recommended to run `/feature-forge:forge-verify {feature}` first. Continue anyway?"
+
+## Step 2: Load All Specs
+
+Read all spec documents into context:
+- `{resolvedFeatureDir}/PRD.md`
+- `{resolvedFeatureDir}/tech-spec.md`
+- `{resolvedFeatureDir}/##-*.md` (all implementation specs)
+
+If the spec suite is large (8+ documents), focus on loading the architecture layout (01-*), shared types (00-*), and testing strategy documents first. Load individual subsystem specs as needed when writing the corresponding backlog items, rather than loading all specs simultaneously.
+
+## Step 3: Plan the Backlog
+
+Before writing any JSON, walk the specs and create a backlog plan: discrete work items, ordered by dependency (foundation first), with priorities, each scoped for a single loop iteration.
+
+Present the plan as a numbered list:
+```
+Proposed backlog for {feature} ({N} items):
+
+  001 [P1] Scaffold module with project manifest, build config, and entry points
+      Depends on: (none)
+      Specs: 00-core-definitions.md, 01-architecture-layout.md
+
+  002 [P1] Implement shared types and error hierarchy
+      Depends on: 001
+      Specs: 00-core-definitions.md
+  ...
+```
+
+After presenting the plan as text, use `AskUserQuestion` to ask: "Does this breakdown look right? Any items to split, merge, or reorder?" Do NOT include this question in your text output. Wait for the user's response before generating the JSON.
+
+## Step 4: Author backlog.json — delegate to `author-backlog`
+
+**Invoke the rauf plugin's `author-backlog` skill** (via the Skill tool) to write
+`{resolvedBacklogDir}/backlog.json`. Pass it:
+
+- the target backlog directory `{resolvedBacklogDir}`,
+- the approved plan from Step 3,
+- the spec context loaded in Step 2,
+- the project's `typeCheckCommand` / `testCommand` (from `forge.config.json`) so acceptance criteria are concrete and runnable.
+
+`author-backlog` owns all item-quality rules (granularity hard limits, self-contained descriptions, acceptance criteria, `agentDelegation`, the correct `type`/`status` enums, `dependsOn`, `specReferences`, the schema source). Do not re-encode them here — follow whatever it produces.
+
+> **If the rauf plugin / `author-backlog` skill is not available:** fall back to
+> authoring inline using the schema source rule (prefer the project's installed
+> `{stateDir}/backlog.schema.json`, else the published `$id`
+> `https://raw.githubusercontent.com/garygentry/rauf/main/schemas/backlog.schema.json`),
+> and tell the user the rauf plugin provides richer authoring guidance.
+
+**Forge-specific item requirements** layered on top of `author-backlog`'s output:
+- `specReferences` must be paths **relative to the project root** (e.g. `specs/auth/00-core-definitions.md`), NOT relative to the backlog file. The validator resolves them from the project root (not from `--specs-dir`, which only gates the check).
+
+> **Backlog schema & rauf contract are unchanged (REQ-COMPAT-03).** Epic membership adds **no** fields to backlog items — dependency edges live in the epic manifest, never in any backlog item. The JSON written here is byte-for-byte the same shape as a pre-epic standalone feature's backlog, and rauf is still launched against a single per-feature backlog path. Only the *path composition* changes (the `{feature}` segment in the backlog-directory rule above), not the schema or rauf's CLI surface.
+
+## Step 5: Validate via the loop runner
+
+Validate the generated backlog by running the runner's **validate command**
+(`loopRunner.validateCommand`), rendered with `{resolvedBacklogDir}` and `{specsDir}`
+substituted — the rauf default:
+
+```bash
+rauf backlog validate . --backlog {resolvedBacklogDir} --specs-dir {specsDir} --json
+```
+
+Interpret the result:
+- **exit 0** → valid (warnings allowed). Proceed.
+- **exit 1** → validation findings. Parse `{ valid, findings[] }`, fix the items, re-run. Do NOT present the backlog to the user until it validates.
+- **exit 2** → usage/IO error (unreadable file, bad JSON). Fix and re-run.
+
+> **forge-4 runs before forge-5's install gate**, so the runner may not be set
+> up yet. Degrade gracefully rather than hard-failing:
+> 1. First run `loopRunner.versionCommand` (`rauf version --json`). If the
+>    binary is **missing**, or its version is **< `minRunnerVersion`**
+>    (semver-compare), do NOT block authoring: keep the authored backlog, emit a
+>    loud warning with `loopRunner.installHint`, mark validation as skipped, and
+>    continue to Step 6. forge-5 will enforce the gate before running.
+> 2. If the binary is present and new enough but the project isn't set up
+>    (`validate` reports the project marker missing), likewise warn and continue
+>    — validation will run cleanly once `rauf install .` has been done.
+
+## Step 6: Review with User
+
+Present a summary: total items N, dependency-chain depth, estimated loop iterations (`ceil(pendingItems * loopIterationMultiplier)`). Note whether validation passed or was skipped (runner not yet available).
+
+Use `AskUserQuestion` to ask: "Ready to proceed, or any adjustments needed?"
+
+## Step 7: Update Pipeline State and Commit
+
+Write pipeline state conforming to `references/pipeline-state-schema.json`. Follow the Git Commit Protocol in `references/shared-conventions.md`.
+
+1. Update `{resolvedFeatureDir}/.pipeline-state.json`:
+   - Record `artifacts` (path to backlog.json)
+   - Set `stages.forge-4-backlog.basedOnVersions` to `{"forge-1-prd": <current version>, "forge-2-tech": <current version>, "forge-3-specs": <current version>}`
+   - Set `currentStage` to `forge-5-loop`
+   - Check downstream stages (`forge-5-loop`, `forge-6-docs`). If any have `basedOnVersions` referencing an older version of `forge-4-backlog`, set their status to `stale`.
+2. Use `AskUserQuestion` to ask about notes to persist
+3. If `gitCommitAfterStage` is true, follow the Git Commit Protocol: stage files, attempt commit, then set status to `complete` with commit hash only on success. If commit fails, leave status as `in-progress`.
+4. If verification was available but the user chose to skip it, record `stages.forge-verify-backlog.status` as `"skipped"` in pipeline state.
+5. Tell user: "Backlog complete with {N} items. Next steps:\n  - `/feature-forge:forge-verify {feature}` to verify the backlog\n  - `/feature-forge:forge-5-loop {feature}` to run the loop\n  - `/feature-forge:forge {feature}` to see full pipeline status"
+
+## Gotchas
+
+- The loop runs each item in a FRESH context. Every item description must be self-contained — `author-backlog` enforces this, but double-check Step-3 plan items aren't "same as above."
+- Spec references must be project-root-relative paths that actually exist — the validate command enforces this when `--specs-dir` is passed (resolving them from the project root).
+- Don't present a backlog to the user before it validates (or before you've explicitly recorded that validation was skipped because the runner isn't installed yet).

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

@@ -0,0 +1,303 @@
+---
+# 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.
+argument-hint: <feature-name>
+---
+
+# 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/claude/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.
+```