@garygentry/feature-forge 0.3.5 → 0.3.7

package/README.md

@@ -74,7 +74,7 @@ Claude Code users can alternatively install via the plugin marketplace:
 
 The default loop runner is [**rauf**](https://github.com/garygentry/rauf), published as
 [`@garygentry/rauf`](https://www.npmjs.com/package/@garygentry/rauf). The installer runs a
-read-only resolvability preflight on the pin (`@garygentry/rauf@0.14.0`) and records it; pass
+read-only resolvability preflight on the pin (`@garygentry/rauf@0.16.0`) and records it; pass
 `--skip-rauf` to defer the check (e.g. offline installs). Install the rauf CLI itself with
 `npx @garygentry/rauf` or its
 [binary script](https://github.com/garygentry/rauf#install). See the

package/adapters/GENERATION-REPORT.md

@@ -32,8 +32,12 @@ _No dropped constructs — every canonical construct is representable in this ag
 | `skills/forge-5-loop/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
 | `skills/forge-6-docs/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
 | `skills/forge-bootstrap/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
+| `skills/forge-bootstrap/SKILL.md` | `disable-model-invocation` | no Codex skill-frontmatter skill-governance field (TQ-1) |
 | `skills/forge-fix/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
+| `skills/forge-guide/SKILL.md` | `allowed-tools` | no Codex skill-frontmatter skill-governance field (TQ-1) |
 | `skills/forge-guide/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
+| `skills/forge-guide/SKILL.md` | `disallowed-tools` | no Codex skill-frontmatter skill-governance field (TQ-1) |
+| `skills/forge-init/SKILL.md` | `disable-model-invocation` | no Codex skill-frontmatter skill-governance field (TQ-1) |
 | `skills/forge-verify/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
 | `skills/forge/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
 
@@ -61,8 +65,12 @@ _No dropped constructs — every canonical construct is representable in this ag
 | `skills/forge-5-loop/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
 | `skills/forge-6-docs/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
 | `skills/forge-bootstrap/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
+| `skills/forge-bootstrap/SKILL.md` | `disable-model-invocation` | no Copilot skill-frontmatter skill-governance field (TQ-1) |
 | `skills/forge-fix/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
+| `skills/forge-guide/SKILL.md` | `allowed-tools` | no Copilot skill-frontmatter skill-governance field (TQ-1) |
 | `skills/forge-guide/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
+| `skills/forge-guide/SKILL.md` | `disallowed-tools` | no Copilot skill-frontmatter skill-governance field (TQ-1) |
+| `skills/forge-init/SKILL.md` | `disable-model-invocation` | no Copilot skill-frontmatter skill-governance field (TQ-1) |
 | `skills/forge-verify/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
 | `skills/forge/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
 
@@ -90,8 +98,12 @@ _No dropped constructs — every canonical construct is representable in this ag
 | `skills/forge-5-loop/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
 | `skills/forge-6-docs/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
 | `skills/forge-bootstrap/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
+| `skills/forge-bootstrap/SKILL.md` | `disable-model-invocation` | no Cursor .mdc skill-governance field |
 | `skills/forge-fix/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
+| `skills/forge-guide/SKILL.md` | `allowed-tools` | no Cursor .mdc skill-governance field |
 | `skills/forge-guide/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
+| `skills/forge-guide/SKILL.md` | `disallowed-tools` | no Cursor .mdc skill-governance field |
+| `skills/forge-init/SKILL.md` | `disable-model-invocation` | no Cursor .mdc skill-governance field |
 | `skills/forge-verify/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
 | `skills/forge/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
 
@@ -119,8 +131,12 @@ _No dropped constructs — every canonical construct is representable in this ag
 | `skills/forge-5-loop/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
 | `skills/forge-6-docs/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
 | `skills/forge-bootstrap/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
+| `skills/forge-bootstrap/SKILL.md` | `disable-model-invocation` | no Gemini skill-frontmatter skill-governance field (TQ-1) |
 | `skills/forge-fix/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
+| `skills/forge-guide/SKILL.md` | `allowed-tools` | no Gemini skill-frontmatter skill-governance field (TQ-1) |
 | `skills/forge-guide/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
+| `skills/forge-guide/SKILL.md` | `disallowed-tools` | no Gemini skill-frontmatter skill-governance field (TQ-1) |
+| `skills/forge-init/SKILL.md` | `disable-model-invocation` | no Gemini skill-frontmatter skill-governance field (TQ-1) |
 | `skills/forge-verify/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
 | `skills/forge/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
 
@@ -139,8 +155,12 @@ _No dropped constructs — every canonical construct is representable in this ag
 | `skills/forge-5-loop/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
 | `skills/forge-6-docs/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
 | `skills/forge-bootstrap/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge-bootstrap/SKILL.md` | `disable-model-invocation` | no Pi skill-frontmatter skill-governance field |
 | `skills/forge-fix/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge-guide/SKILL.md` | `allowed-tools` | no Pi skill-frontmatter skill-governance field |
 | `skills/forge-guide/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge-guide/SKILL.md` | `disallowed-tools` | no Pi skill-frontmatter skill-governance field |
+| `skills/forge-init/SKILL.md` | `disable-model-invocation` | no Pi skill-frontmatter skill-governance field |
 | `skills/forge-verify/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
 | `skills/forge/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
 

package/adapters/claude/.claude-plugin/plugin.json

@@ -0,0 +1,16 @@
+{
+  "name": "feature-forge",
+  "version": "0.20.0",
+  "description": "End-to-end feature development pipeline: PRD → tech spec → implementation specs → backlog → documentation, with verification gates, pipeline state tracking, and specialized subagents for verification and codebase research.",
+  "author": {
+    "name": "Gary Gentry"
+  },
+  "keywords": [
+    "pipeline",
+    "prd",
+    "specs",
+    "backlog",
+    "documentation",
+    "verification"
+  ]
+}

package/adapters/claude/.feature-forge-bundle.json

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

package/adapters/claude/agents/forge-verifier.md

@@ -25,10 +25,11 @@ You have READ-ONLY access. You cannot and should not modify any files. Your outp
 ## How You Work
 
 1. Read the pipeline state file to understand what stage the feature is at
-2. Load all relevant artifacts for the current verification mode
-3. Read **only your dispatched mode's checklist** — `references/verification-checklists/{mode}.md` (the parent's dispatch prompt names your `{mode}`) — and execute every check in it. Do **not** read the other five mode files or `references/findings-template.md`; those are for other modes and for the parent orchestrator respectively.
-4. Return structured findings as your response in the Output Format specified below
-5. Generate a fix plan suitable for a fresh agent to execute
+2. Read the shipped verifier-patterns index — `references/verifier-patterns/MEMORY.md` — and open the patterns your dispatched mode makes relevant. These are the versioned, reviewed heuristics that ship with the pipeline (see "Using Your Memory" for how they relate to your per-project memory).
+3. Load all relevant artifacts for the current verification mode
+4. Read **only your dispatched mode's checklist** — `references/verification-checklists/{mode}.md` (the parent's dispatch prompt names your `{mode}`) — and execute every check in it. Do **not** read the other five mode files or `references/findings-template.md`; those are for other modes and for the parent orchestrator respectively.
+5. Return structured findings as your response in the Output Format specified below
+6. Generate a fix plan suitable for a fresh agent to execute
 
 ## Scoped / Parallel Operation
 
@@ -44,7 +45,17 @@ For large spec suites (>8 documents), process verification in phases: load share
 
 ## Using Your Memory
 
-You have persistent memory in your `MEMORY.md` file. Use it to track:
+You draw on two distinct layers, and they must not be confused:
+
+- **Shipped verifier patterns** (`references/verifier-patterns/`) — versioned, reviewed
+  heuristics that ship with the pipeline to every project. Read the index
+  (`references/verifier-patterns/MEMORY.md`) on start. **Treat these as read-only** — they
+  are canon, not your scratch memory; a genuinely new, general heuristic worth shipping is
+  a change proposed in review, not something you write here at run time.
+- **Per-project memory** (`memory: project`, below) — your own accumulating notes about
+  *this* project's specific blind spots, conventions, and confirmed false positives.
+
+You have persistent per-project memory in your `MEMORY.md` file. Use it to track:
 
 - **Recurring patterns**: If you keep finding the same type of gap across features, note it. Over time you'll learn this project's blind spots.
 - **Project conventions**: As you review more specs, capture conventions that should be consistent (naming patterns, error handling approaches, test strategies).

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

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Feature Forge Configuration",
-  "description": "Project-level configuration for the feature-forge plugin. Place as forge.config.json in your project root.",
+  "description": "Project-level configuration for the feature-forge plugin. Place as forge.config.json in your project root. An optional gitignored forge.config.local.json alongside it is deep-merged over the committed file (local wins) so machine-local facts — e.g. loopRunner.bin, contextWindowTokens — live outside version control; FEATURE_FORGE_LOOP_RUNNER_BIN overrides loopRunner.bin above both.",
   "type": "object",
   "properties": {
     "specsDir": {
@@ -235,8 +235,8 @@
         },
         "installHint": {
           "type": "string",
-          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.14.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.14.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
-          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.14.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
+          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.16.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.16.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
+          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.16.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
         },
         "schemaVersion": {
           "type": "string",
@@ -245,8 +245,8 @@
         },
         "minRunnerVersion": {
           "type": "string",
-          "default": "0.6.0",
-          "description": "Minimum runner version (semver). 0.6.0 is the AGENT-SURFACE FLOOR: the rauf version that ships the coding-agent selection surface (the --agent flag, the `agents` availability probe, and the preset agent registry) that this config's agentArgument/agentsProbeCommand consume. Flooring here guarantees a successful gate implies those surfaces exist. (0.5.0 was the prior grammar/contract-flip floor — unified exit codes, `loop run --detached`, explicit `review` signal, versioned events.ndjson — which predates the agent surface and so could not guarantee it.) forge-5 enforces this via versionCommand before any loop side-effects."
+          "default": "0.14.0",
+          "description": "Minimum runner version (semver). 0.14.0 is the CAPABILITY FLOOR the shipped stage actually depends on — it is the version needed for full post-run needs-human recovery: rauf 0.14's `backlog answer` injects a recorded answer into the next iteration (RECOVERY_MIN_RUNNER_VERSION in forge-session.py). Below it, recovery silently degrades to `backlog unblock` (answer not injected) and large Codex prompts retain the pre-0.14 argv-size (E2BIG) failure mode. Earlier surfaces are subsumed: 0.6.0 first shipped the coding-agent selection surface (--agent flag, `agents` availability probe, preset registry consumed by agentArgument/agentsProbeCommand); 0.5.0 added unified exit codes, `loop run --detached`, the explicit `review` signal, and versioned events.ndjson. Flooring at 0.14.0 guarantees a successful gate implies the recovery + agent surfaces both exist. The floor is distinct from the installer's `RAUF_PIN` (installHint) — the pin may sit ahead of the floor when a newer rauf ships nothing this floor's dependents need; it only rises when rauf ships a surface a shipped stage actually depends on. forge-5 enforces the floor via versionCommand before any loop side-effects."
         }
       }
     }

package/adapters/claude/references/portable-root.md

@@ -12,7 +12,7 @@ against the fenced block here, byte-for-byte.
 ## Canonical bootstrap prelude
 
 ```bash
-R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
 [ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
 ```
 
@@ -24,24 +24,27 @@ makes several calls, add the prelude once and reuse `$R` for each. A fresh block
 prelude (per-block re-resolution). Worked example:
 
 ```bash
-R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
 [ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
 python3 "$R/scripts/epic-manifest.py" render-status "{epic}" --specs-dir "{specsDir}" --json
 ```
 
 ## Invariants (do NOT "fix" these)
 
-1. **First hint is the Claude plugin-root env var; the rest are paths.** The prelude's
-   `for d in …` list leads with the `CLAUDE_PLUGIN_ROOT` env var (in default-empty `:-` form)
-   — the exact bundle dir Claude exports in every marketplace/plugin session — followed by the
-   directory-path candidates. The hint gives exact, glob-free resolution on any current/future
-   Claude layout (no version-skew window); when unset it expands to empty and is harmlessly
-   skipped, so other hosts fall through to the path candidates unchanged. This is the **one
-   sanctioned** appearance of that variable in canonical surfaces: spec-purity rule 3 allows it
-   by stripping the byte-pinned prelude before its residual-var scan (so a stray var anywhere
-   else — including the default-empty form — still fails), and `forge-agent-adapters-build`
-   translates it to `FEATURE_FORGE_ROOT` for non-Claude bundles (which `forge-root.sh` already
-   prefers). The exact literal is shown only in the fenced prelude above and audited in
+1. **Explicit `FEATURE_FORGE_ROOT` override first, then the Claude env hint, then paths.** The
+   prelude opens with a guard: if `FEATURE_FORGE_ROOT` is set but carries no
+   `scripts/forge-root.sh`, it fails loudly (`exit 2`) instead of silently falling back to
+   discovery — an operator override that does not resolve is an error, not a hint (the same rule
+   `forge-root.sh` Step 0 applies). The `for d in …` list then leads with the `FEATURE_FORGE_ROOT`
+   env var in default-empty `:-` form (the host-neutral operator override, honored on every agent)
+   followed by the `CLAUDE_PLUGIN_ROOT` env var in the same form (the exact bundle dir Claude
+   exports in every marketplace/plugin session), then the directory-path candidates. Both env hints
+   give exact, glob-free resolution; when unset each expands to empty and is harmlessly skipped, so
+   other hosts fall through to the path candidates unchanged. `CLAUDE_PLUGIN_ROOT` remains the **one
+   sanctioned** appearance of that vendor variable in canonical surfaces: spec-purity rule 3 allows
+   it by stripping the byte-pinned prelude
+   before its residual-var scan (so a stray var anywhere else — including the default-empty form —
+   still fails). The exact literal is shown only in the fenced prelude above and audited in
    `vendor-construct-inventory.md`.
 2. **First-discoverable-resolver-wins.** The `exec` inside the `$(…)` command substitution means
    the loop stops at the first directory holding an executable `forge-root.sh` and delegates ALL
@@ -64,8 +67,9 @@ python3 "$R/scripts/epic-manifest.py" render-status "{epic}" --specs-dir "{specs
 
 The prelude delegates to [`scripts/forge-root.sh`](../scripts/forge-root.sh) — the portable
 skill/plugin-root resolver. It takes no arguments, prints the absolute plugin root to stdout and
-exits `0`, or writes an actionable message to stderr and exits `1`. It resolves the root by
-self-location → candidate-root probe → plugin-root environment-variable fallback → actionable failure,
-and never sources or executes a discovered path — it only ever prints a directory string. The
+exits `0`, or writes an actionable message to stderr and exits non-zero. It resolves the root by
+explicit `FEATURE_FORGE_ROOT` override (Step 0) → self-location → candidate-root probe →
+`CLAUDE_PLUGIN_ROOT` fallback → actionable failure, and never sources or executes a discovered
+path — it only ever prints a directory string. The
 spec-purity checker (rule 5) enforces that every prelude occurrence across the canon is
 byte-identical to the fenced block in this file.

package/adapters/claude/references/preflight-and-self-heal.md

@@ -0,0 +1,183 @@
+# Preflight & Self-Heal Procedure
+
+The named procedure that turns "the environment is missing/stale/misconfigured" into a
+clear stop or a scripted, consented repair — instead of a cryptic mid-run failure or a
+silent unasked mutation. It runs whenever a skill gates on `doctor`'s structured
+`checks[]` (`roadmap/self-healing-resilience.md` §5.2); today that is `forge-5-loop`'s
+gates 1c/1d (`skills/forge-5-loop/SKILL.md`), which resolve the loop runner **before**
+touching it, `forge-init`'s install preflight (`skills/forge-init/SKILL.md`), where
+neither check is a stop, and `forge-guide --doctor` (`skills/forge-guide/SKILL.md`), the
+operator-facing repair surface, which gates nothing at all. All three are callers, not
+the procedure's scope: any skill that gates on `checks[]` follows it in full. Its seven
+ordered steps: **enumerate → cluster → consolidated prompts → record → apply → prove →
+return**.
+
+## 1. Scope and the failure rule
+
+**Input contract:** the caller has already run `doctor --json` narrowed to the `--check`
+ids it cares about (never the full catalog inside a hard gate — an advisory check must
+never block a launch it has no bearing on) and hands this procedure that call's `checks[]`
+and `remedyClusters[]`. The procedure orchestrates that data; it never re-derives it and
+never invents a remedy `doctor` did not emit (INV-4).
+
+**The failure rule (applies to every step).** `doctor` itself never exits non-zero and
+never raises (INV-3) — there is no non-zero exit to catch here. What *can* fail is a
+remedy command: any remedy invocation that exits non-zero, times out, or produces
+output the re-run in step 6 cannot confirm is surfaced **verbatim** and **STOPS** the
+procedure with a **failed preflight** report — never reported as healed. This applies the
+post-run recovery procedure's failure rule, narrowed to remedies (preflight has no
+runner-answer/unblock apply mechanism of its own).
+
+## 2. The seven steps
+
+### Step 1 — Enumerate
+
+- **Input:** the caller's `doctor --json` result (§1).
+- **Decision point:** if every requested check is `ok` or `na`, there is nothing to
+  cluster, prompt, apply, or prove: **skip steps 2–6 and return `ok` with no output and
+  no prompt** (INV-2 — a fully healthy project produces zero new preflight text). This is
+  the only step whose outcome the caller checks before calling the rest of the
+  procedure at all.
+- **Output:** the affected `checks[]` subset (`status` is `warn` or `fail`) with each
+  entry's `remedy` and `severity`.
+
+### Step 2 — Cluster
+
+- **Input:** the affected checks from step 1.
+- **Mechanism:** `remedyClusters[]`, already computed by `doctor_report` (pure
+  `cluster_checks`, `scripts/forge-session.py`) — group by identical `remedy.command`,
+  most-conservative `safety` wins the merge, `remedy: null` checks are **not** clustered
+  (report-only, no prompt to build). Reuse it as-is; do not re-cluster by hand.
+- **Output:** the final cluster set — one entry per distinct runnable remedy, each
+  carrying its `checkIds[]`, `command`, `safety`, and `description` — plus the
+  report-only set (affected checks with no `remedy` or no `remedy.command`).
+
+### Step 3 — Consolidated prompts
+
+- **Input:** the cluster set from step 2.
+- **Mechanism:** one question per cluster (never one per check) via `AskUserQuestion`
+  (rung 1/2) or the ladder's rung-3 default (§4). Name the **exact remedy command**, its
+  **safety tier**, and **every member check id** the cluster covers — e.g. *"`runner-wired`
+  and `runner-legacy-layout` both resolve by running `{bin} migrate .` (local-write).
+  Run it?"*
+- **Per the safety ladder** (`references/shared-conventions.md` § Remedy Safety Ladder):
+  a `read-only` cluster is never prompted (run it and move to step 5); `local-write` asks
+  **once per remedy class per session** — re-affirming the same `remedy.command` string a
+  second time in the same session skips straight to apply; `global-install`/`network` are
+  **never** prompted for execution — surface them as report-only advice (§5's
+  advise-only path) even though `doctor` clustered them.
+- **Report-only set — three shapes, all print once, plainly, with no question:** checks
+  with no `remedy` at all (a corrupt manifest, an unresolvable config); a `remedy` whose
+  `command` is `null` (reinstall-only or config-edit advice with nothing to run — never
+  clustered, since `cluster_checks` skips these); and a `global-install`/`network`
+  remedy (clustered by `doctor`, but never prompted for execution here).
+- **Output:** per cluster, one of {approved, declined, advise-only (tier forbids
+  execution), unaskable→advise-only (genuinely no way to ask and wait, §4)}.
+
+### Step 4 — Record
+
+- **Input:** every outcome from step 3.
+- **Mechanism:** **output only** — a `preflight:` line per cluster, e.g.
+  `preflight: runner-wired,runner-legacy-layout → {bin} migrate . [local-write] — approved+run`.
+  The five outcome tokens are `run` (read-only, no prompt needed), `approved+run`,
+  `declined`, `advise-only` (tier forbids execution — includes the report-only,
+  null-command shape from §2 step 3), `unaskable→advise-only` (rung 3, no default
+  permits the write). **The backlog's item-keyed decision record** (the durable
+  store post-run recovery uses to survive a session boundary) **is NOT used here** — a
+  preflight remedy is environment repair, not a backlog decision, and writing one there
+  would durably attribute an environment fix to a backlog item that never asked for it.
+- **Output:** the stated line, printed before step 5 acts on anything.
+
+### Step 5 — Apply
+
+- **Input:** every cluster whose step-4 outcome is `run` or `approved+run`.
+- **Mechanism:** run `remedy.command` **verbatim** — never edited, never re-templated.
+  `doctor` already rendered every token (`{bin}`, paths) into the command string; the
+  procedure's only job is to execute exactly what was clustered.
+- **Error:** a remedy that exits non-zero, times out, or cannot be run at all (binary
+  vanished between the check and the apply) is surfaced verbatim and **STOPS** the
+  procedure — **failed preflight**, per §1. Declined and advise-only clusters are not
+  applied at all; they proceed straight to step 7's report.
+
+### Step 6 — Prove
+
+- **Input:** every cluster step 5 actually applied.
+- **Mechanism:** re-run the **identical** `doctor --json` invocation the caller made in
+  §1 (same `--check` ids, same flags) and re-read the member check ids' `status`.
+- **Decision point:** **every** member check now `ok` → the cluster is healed, continue.
+  **Any** member still `warn`/`fail` — including a partial move where some member ids
+  flipped and others did not — is a **failed preflight**: report it, naming the healed and
+  still-failing check ids from this re-read, never from the first run's stale statuses.
+  A remedy that ran but did not prove is a failure, not a partial success — the
+  ran-but-nothing-moved shape the post-run recovery procedure also treats as a failure.
+- **Output:** either "all affected checks now `ok` → return" or a failed-preflight report.
+
+### Step 7 — Return
+
+- Return the final per-check statuses (post-prove where a remedy ran, original where
+  declined/advise-only/report-only) to the caller. The procedure never selects the
+  caller's own gate outcome — `forge-5-loop`'s 1c/1d decide HARD GATE FAILURE vs. STOP vs.
+  proceed from these statuses; this reference only guarantees the statuses it returns are
+  either the original `doctor` read (nothing was touched) or a freshly proven re-read
+  (§6) — never a claim this procedure did not verify.
+
+## 3. Safety ladder (pointer)
+
+Every apply/prompt decision above is gated by the four-tier ladder declared once in
+`references/shared-conventions.md` § Remedy Safety Ladder — `read-only` / `local-write` /
+`global-install` / `network`. This reference never restates the tiers; it only names
+which step consults them (§2 steps 3 and 5).
+
+## 4. Rung-3 default
+
+This is the **preflight remedies** class of the canonical Interaction Capability Ladder
+(`references/shared-conventions.md` § Interaction Capability Ladder) — "cannot be asked"
+(§2 step 3) means rung 3: genuinely **no way to ask and wait for a reply at all**, neither
+a structured question tool NOR plain prose with a wait for the answer. It is **not** the
+same as "no structured tool": a host that lacks a structured tool but can still prompt in
+prose and wait (an interactive Codex session, per its own turn-taking rules) is rung 2,
+not rung 3, and Step 3 asks it that way. Rung 3 fires only for a genuinely non-interactive
+invocation (a headless `-p`/`exec`/JSON-mode run with no reply channel). Such a session
+follows the ladder's declared default via the safety ladder's own rule: **degrade one
+tier stricter** — a `local-write` cluster that cannot be asked is treated as
+`advise-only` (print the command, never run it), and the outcome is recorded as
+`unaskable→advise-only` (§2 step 4). Never silently skip the report, and never take an
+unasked write as implied consent.
+
+## 5. Message shapes
+
+- **`runner-binary` / `runner-version` not `ok`** (blocking, no remedy proven) — **HARD
+  GATE FAILURE**: STOP, do not proceed to run the loop, show the failing check's own
+  `remedy.description` (and `remedy.command` when set) plus its raw `detail`/`evidence`
+  for diagnosis. **Never substitute `loopRunner.installHint` for this** — three of
+  `runner-binary`'s four warn shapes and one of `runner-version`'s are a **config fix**
+  (a customized `bin` missing while the default is on PATH points at the config, not the
+  install — G4), and `installHint` only ever describes installing the default package.
+  When the remedy's `command` is `null` (a reinstall-only or config-edit instruction),
+  there is nothing to cluster or apply — print the `remedy.description` as report-only
+  advice (§2 step 3's report-only set) and STOP regardless.
+- **`runner-legacy-layout` warn** — STOP: *"This project is still on the legacy **Ralph**
+  layout. Run {check's `remedy.command`, e.g. `{bin} migrate .`} first (the loop runner
+  only understands `.rauf/` and `RAUF_*` signals), then re-run
+  `/feature-forge:forge-5-loop {feature}`."* Use the check's own `remedy.command` — never
+  a hardcoded `rauf migrate .` — a customized `loopRunner.bin` changes the binary name.
+- **`runner-wired` warn** — STOP and show `loopRunner.setupHint`, e.g. *"The loop runner
+  isn't set up in this project ({preconditionFile} is missing). {setupHint}"*.
+- A STOP lifts **only** after a permitted `local-write` remedy ran (§2 step 5) **and**
+  the re-run (§2 step 6) shows the gating check `ok` — never on the remedy's exit code
+  alone.
+
+## 6. Failure taxonomy
+
+| Failure | When it occurs | Reaches step 6's per-check test? | Report |
+|---|---|---|---|
+| **Failed apply** | A `run`/`approved+run` remedy exits non-zero, times out, or cannot start | No — stops before the test | Verbatim command output + which cluster; **failed preflight**; procedure stops |
+| **Ran-but-not-healed** | The remedy exited 0, but the re-run still shows `warn`/`fail` for a member check | Yes — is the test failing | Healed/still-failing check ids named from the re-read; **failed preflight** |
+| **Declined / advise-only / unaskable** | The operator declined, the tier forbids execution, or the session genuinely had no way to ask and wait (§4) | N/A — no apply attempted | Reported per §2 step 4; **not** a failure — the original `doctor` statuses stand, and the caller's gate (§2 step 7) still applies to them |
+
+Rules: never report healed/succeeded past a failed step; a failed apply stops before the
+per-check test, so a remedy that errored is never conflated with one that ran cleanly but
+fixed nothing; a declined/advise-only/unaskable cluster is a normal outcome, not a
+procedure failure — the caller's own gate still decides what an unhealed `warn`/`fail`
+means for it (a blocking check stays a hard gate failure; an advisory one is just
+reported).

package/adapters/claude/references/process-overview.md

@@ -118,7 +118,7 @@ they track the current model tier automatically.
 
 ### forge-verifier
 - **Purpose:** Read-only verification of pipeline artifacts
-- **Used by:** `forge-verify` skill (delegation via Agent tool)
+- **Used by:** `forge-verify` skill (delegation via `Agent` tool)
 - **Tools:** Read, Glob, Grep, Bash (read-only operations only)
 - **Model:** Opus (judgement-heavy gap/inconsistency analysis)
 - **Memory:** Project-scoped persistent memory — accumulates knowledge about recurring issues and project-specific patterns across sessions

package/adapters/claude/references/ralph-loop-contract.md

@@ -156,11 +156,13 @@ to today. Degradation is **silent, not an error**, keeping alternate (non-rauf)
 runners first-class. The gate condition is owned by
 `02-config-schema-and-gating.md`.
 
-Independently, the **version gate** floors at the runner version that ships the
-agent surface. For rauf that is **0.6.0** (`loopRunner.minRunnerVersion`): the
-`--agent` flag, the `agents` probe, and the preset agent registry are present in
-rauf source at 0.6.0. A successful gate therefore guarantees those surfaces
-exist before any run. See `## Version gating` and
+Independently, the **version gate** floors at the runner version the stage
+depends on. For rauf that is **0.14.0** (`loopRunner.minRunnerVersion`): the
+version the package pins and the floor for full needs-human recovery (0.14's
+`backlog answer`). The agent surface — the `--agent` flag, the `agents` probe,
+and the preset agent registry — has been present since rauf 0.6.0 and is
+subsumed by the higher floor, so a successful gate guarantees both the recovery
+and agent surfaces exist before any run. See `## Version gating` and
 `05-runner-discovery-version-gate.md`.
 
 **This document — the `## Agent selection` section, the `## Per-stage agent
@@ -210,9 +212,11 @@ belongs to execution only. If you find yourself adding `--agent` near a
 
 feature-forge requires a runner exposing `backlog validate` + backlog
 `schemaVersion`, and the unified exit-code/status contract it reads. The floor is
-now the **agent-surface floor**: the runner version that ships the `--agent`
-flag, the `agents` probe, and the preset agent registry. For rauf that is
-**0.6.0** (`loopRunner.minRunnerVersion`).
+now the **capability floor** the stage actually depends on: the version the
+package pins and the floor for full needs-human recovery (0.14's `backlog
+answer`). It subsumes the older agent-surface floor (the `--agent` flag, the
+`agents` probe, and the preset agent registry, present since 0.6.0). For rauf
+that is **0.14.0** (`loopRunner.minRunnerVersion`).
 `forge-5-loop` runs `{bin} version --json`, semver-compares the reported version
 against `minRunnerVersion`, and on a missing-or-too-old runner stops with
 `loopRunner.installHint` (the CLI install/upgrade command) — **before** invoking

package/adapters/claude/references/select-outcome.md

@@ -0,0 +1,138 @@
+# `select-outcome` — deterministic exit-outcome selection
+
+`forge-verify` and `forge-fix` each close a run by choosing exactly one
+`stage-exit --outcome`. That choice used to be model judgment over conversational
+state. `forge-session.py select-outcome` derives it from the authoritative on-disk
+record instead — the same "never eyeball the graph" move `rank-features` makes when
+it derives `verifyGate` for the navigator (issue #276, part of the #265 guard-first
+program).
+
+The verb reads, never writes. It is called at the exit step, **after** the run's
+result has already been persisted by `state-verify` and the findings document has
+been written, so the disk state it reads is the run's own settled record.
+
+## Synopsis
+
+```
+python3 forge-session.py select-outcome \
+  --feature F --served-stage S --skill verify|fix \
+  [--op-failure] [--user-deferred] [--decisions-open] \
+  [--specs-dir DIR] [--epic E] [--json]
+```
+
+`--served-stage` is one of the five verify-token production stages
+(`forge-1-prd`, `forge-2-tech`, `forge-3-specs`, `forge-4-backlog`, `forge-5-loop`).
+`forge-0-epic` (epic-scoped verification lives in `.epic-state.json`) and
+`forge-6-docs` (no verify token) are **out of scope** and rejected.
+
+Output — always `{outcome, reason, evidence: [...]}`:
+
+```json
+{
+  "outcome": "reverify-findings",
+  "reason": "fixes were applied and a re-verify reopened blocking findings for the served stage",
+  "evidence": [
+    "forge-verify-tech status = findings-reported",
+    "latest report .verification/VERIFY-tech-2026-09-07-round2.md (round 2): 2 blocking = 1 error + 1 gap, 3 total finding(s)",
+    "round reports on disk: 2",
+    "fix progress: 1 step(s) applied; sweep 1 fixed / 0 justified / 0 false-positive"
+  ]
+}
+```
+
+## Outcome vocabularies
+
+The verb chooses from exactly the branch skills' `--outcome` domains — the
+`VerifyOutcome` and `FixOutcome` aliases in `forge-session.py`. Those aliases are
+pinned to the tables below by `tests/test_select_outcome.py` (both directions), so the
+enum and this reader-facing mapping can never drift. `forge-verify` and `forge-fix`
+used to carry these tables in their SKILL bodies; issue #278 flipped the bodies to
+call the verb and moved the tables here, their reader-facing home.
+
+### verify
+
+| This run's result | `--outcome` |
+|---|---|
+| Zero findings — the artifacts are clean | `passed` |
+| Advisory-only report (no `error`/`gap`), recorded `passed` with the report attached | `passed` |
+| A report with at least one blocking finding (`error`/`gap`) was written | `findings` |
+| The user explicitly deferred pipeline action and that skip was persisted (`state-verify --status skipped`) | `skipped` |
+| A dispatch, check, or state write failed and needs intervention | `failed` |
+
+### fix
+
+| This run's result | `--outcome` | Authoritative downstream action |
+|---|---|---|
+| No applicable findings document or steps (Step 1.5) | `no-findings` | Re-verify while verification is still owed; otherwise the live production successor |
+| User decisions remain unresolved (Step 3) | `decisions` | Resume `forge-fix` naming the unresolved decisions; no advancement |
+| A fix step, validation, commit, or state write failed (Steps 4–6) | `failed` | Fix/navigator recovery; no advancement |
+| Fixes persisted and re-verify not yet run (nested, or manual capability) | `applied` | Re-run `forge-verify` for the same served stage — re-verification is mandatory |
+| A mandatory re-verify passed | `reverified` | The live production successor |
+| A mandatory re-verify reopened an unresolved prior finding or a new blocking defect (clean-or-advisory-only is `reverified`) | `reverify-findings` | `forge-fix` for the same served stage |
+| The user explicitly deferred the fix pass or the re-verify (Steps 3, 6) | `deferred` | Deterministic `forge-fix`/navigator resume; findings remain unresolved; no advancement |
+
+## Inputs read from disk
+
+- The served stage's `stages.forge-verify-{token}` entry in `.pipeline-state.json` —
+  its `status` is the authoritative signal, written mechanically by `state-verify`.
+- The latest `.verification/VERIFY-{mode}-*.md` report (round-aware: `-round{N}` beats
+  the un-suffixed base file, and the newest day's newest round is "latest"). Blocking
+  counts come from the `## Findings` severities (`error`/`gap`), never from the human
+  `## Summary` line.
+- Each report's `## Fix Progress` section — its `[APPLIED]` steps and the sweep
+  dispositions (`FIXED`/`JUSTIFIED`/`FALSE-POSITIVE`). A report carrying `[APPLIED]`
+  steps is the disk record that a fix pass ran (`fix-applied`).
+
+## Derivation
+
+### verify
+
+1. `--op-failure` → **failed**.
+2. entry `skipped` → **skipped**.
+3. entry `findings-reported` → **findings**.
+4. entry `passed` → **passed** (a clean report, an advisory-only report, or accepted
+   residual findings — all three are recorded `passed`).
+5. otherwise (no terminal result recorded) → **fail closed** (exit 2).
+
+### fix
+
+1. `--op-failure` → **failed**.
+2. `--user-deferred` → **deferred**.
+3. `--decisions-open` → **decisions**.
+4. no report for the mode → **no-findings**.
+5. entry `findings-applied` → **applied** (a re-verify is still owed).
+6. entry `passed` → **reverified**. A forge-fix pass reaches a `passed` served stage
+   only by re-verifying it: forge-fix Step 1.5 resolves its served stage to an
+   *unresolved* verify entry (`findings-reported`, `findings-applied`, or a pending
+   debt), never an already-resolved `passed`, so a `passed` entry at a fix exit is the
+   mandatory re-verify's own passing result. (`fix-applied` is not consulted here — it
+   reads every round on disk and so cannot tell this pass's fixes from an earlier
+   cycle's.)
+7. entry `findings-reported` + a fix ran → **reverify-findings** (a re-verify reopened
+   findings); entry `findings-reported` + no fix ran → **fail closed** (exit 2).
+8. any other resolved/absent entry with no fix → **no-findings**.
+
+Two cases the issue calls out because a model tends to mis-eyeball them, and the verb
+gets right by keying on the entry status rather than the presence of findings text:
+
+- **A sweep whose survivors are all `FALSE-POSITIVE`.** Disposition is not a defect —
+  the entry is still `findings-applied`, so the outcome is **applied**, never `failed`.
+- **A re-verify red on a scoped subset.** The round-2 report reopens blocking findings
+  and the entry returns to `findings-reported`, so the outcome is **reverify-findings**.
+
+## Runtime signals
+
+Three outcomes cannot be read off disk, because the fact that distinguishes each is
+inherently runtime:
+
+- **failed** — an operational failure (a dispatch, step, validation, commit, or state
+  write) leaves *no* state write, so disk shows the prior state.
+- **deferred** — an explicit user deferral of the fix or re-verify is byte-identical on
+  disk to a nested/manual `applied` (both leave the entry at `findings-applied`).
+- **decisions** — unresolved user decisions live in the free-prose "User Decisions
+  Required" section, which has no machine format.
+
+The caller asserts these with `--op-failure` / `--user-deferred` / `--decisions-open`
+(the latter two are `fix`-only). Everything else is pure disk derivation. When the disk
+record names no terminal outcome and no signal was supplied, the verb **fails closed**
+with `Error:` on stderr and exit 2 — it never guesses.