@garygentry/feature-forge 0.3.6 → 0.3.7

package/adapters/codex/skills/forge-verify/references/verifier-patterns/pattern_vacuous_self_reading_tests.md

@@ -0,0 +1,32 @@
+---
+name: pattern-vacuous-self-reading-tests
+description: Tests that read their own source file are near-always vacuous unless they assert absence or scope the read; verify by a PROPERTY-PRESERVING mutation and check WHICH line goes red
+metadata:
+  type: reference
+---
+
+A drift-guard test that does `source = read(Path(__file__).resolve())` and then asserts a
+**positive** substring is almost always vacuous: the searched literal sits on the assert
+line itself, so the whole-file read satisfies it unconditionally.
+
+**Why:** the trap catches even the *fix* for a prior vacuity finding, which often
+reproduces the identical defect while its own inline comment claims "this reads for a
+DIFFERENT string than the one it writes". The fix pass validates it with a mutation that
+changes a second property at the same time — replacing a derived roster with a *shrunken*
+hardcoded list goes red, but at a pre-existing floor assertion (`len(...) >= MIN`), not at
+the assertion under test. Seeing "red" is taken as proof; a roster-**preserving** hardcode
+leaves the test fully green.
+
+**How to apply:**
+
+- Grep every changed test for `read(Path(__file__)` / `inspect.getsource`. For each,
+  locate the searched literal's occurrences in the file. Two occurrences (guarded site +
+  assert line) = vacuous.
+- Never accept "the mutation went red". Demand the **line number** of the failing
+  assertion, and design the mutation to change exactly one property.
+- Acceptable forms: assert **absence** (write the banned tokens without the syntax that
+  makes them live), or scope the read away from the guarding test's own body
+  (`inspect.getsource(<the guarded function>)`). The best form for "this expression is
+  still derived" is an `ast` parse, which the assertion's own text cannot satisfy.
+
+See [[pattern-postfix-reverify]] and [[pattern-mechanical-rewrite-damage]].

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

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

package/adapters/copilot/agents/forge-researcher.md

@@ -1,7 +1,7 @@
 ---
 # GENERATED — DO NOT EDIT. Source: agents/forge-researcher.md. Regenerate: python3 scripts/build-adapters.py
 name: forge-researcher
-description: Explores the codebase to understand package structure, integration points, existing patterns, and conventions. Use during feature planning, especially when running /feature-forge:forge-2-tech. Returns a distilled integration report without polluting the main conversation's context window.
+description: Explores the codebase to understand package structure, integration points, existing patterns, and conventions. Use during feature planning, especially when running forge-2-tech. Returns a distilled integration report without polluting the main conversation's context window.
 ---
 
 You are a codebase research agent for the feature-forge pipeline. Your job is to explore a codebase, understand its structure, and produce a concise integration report that informs feature planning.

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

@@ -1,7 +1,7 @@
 ---
 # GENERATED — DO NOT EDIT. Source: agents/forge-verifier.md. Regenerate: python3 scripts/build-adapters.py
 name: forge-verifier
-description: Verifies feature forge pipeline artifacts for completeness, consistency, and quality. Delegates to this agent when running /feature-forge:forge-verify or when the user asks to check specs, backlog, or implementation for gaps. This agent has read-only tools and persistent memory — it cannot modify files, only analyze and report findings.
+description: Verifies feature forge pipeline artifacts for completeness, consistency, and quality. Delegates to this agent when running forge-verify or when the user asks to check specs, backlog, or implementation for gaps. This agent has read-only tools and persistent memory — it cannot modify files, only analyze and report findings.
 ---
 
 You are a meticulous verification agent for the feature-forge development pipeline. Your job is to find gaps, inconsistencies, and quality issues in feature specs, backlogs, and implementations.
@@ -19,10 +19,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
 
@@ -38,7 +39,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/copilot/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": {
@@ -65,7 +65,7 @@
     "autoInvokeNextStage": {
       "type": "boolean",
       "default": true,
-      "description": "When true (default), the /feature-forge:forge navigator auto-invokes the next pipeline stage via the Skill tool after the user confirms it, instead of only printing the command to copy. Set false to keep the old copy-paste behavior (the navigator suggests the command but never launches it). Ignored on non-Claude hosts, which always fall back to printing the command."
+      "description": "When true (default), the forge navigator auto-invokes the next pipeline stage via the Skill tool after the user confirms it, instead of only printing the command to copy. Set false to keep the old copy-paste behavior (the navigator suggests the command but never launches it). Ignored on non-Claude hosts, which always fall back to printing the command."
     },
     "docsStage": {
       "type": "string",
@@ -76,7 +76,7 @@
     "autoVerify": {
       "type": "boolean",
       "default": false,
-      "description": "When true, the /feature-forge:forge navigator automatically runs forge-verify after a stage completes, with no prompt. forge-verify runs in a fresh forge-verifier subagent (clean-room), so it never needs a context clear and costs the current session only a compact findings digest. Default false preserves today's manual-gate behavior. Ignored on non-Claude hosts, which always fall back to printing the verify command. Per-stage overrides in autoVerifyStages take precedence."
+      "description": "When true, the forge navigator automatically runs forge-verify after a stage completes, with no prompt. forge-verify runs in a fresh forge-verifier subagent (clean-room), so it never needs a context clear and costs the current session only a compact findings digest. Default false preserves today's manual-gate behavior. Ignored on non-Claude hosts, which always fall back to printing the verify command. Per-stage overrides in autoVerifyStages take precedence."
     },
     "autoVerifyStages": {
       "type": "object",
@@ -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.15.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.15.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.15.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",

package/adapters/copilot/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/copilot/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 host's question mechanism
+  (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
+  `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/copilot/references/process-overview.md

@@ -11,27 +11,27 @@ The pipeline compiles a fuzzy feature idea into a machine-executable `backlog.js
    (optional)
 ```
 
-### Stage 0: Epic (`/feature-forge:forge-0-epic <epic>`), optional
+### Stage 0: Epic (`forge-0-epic <epic>`), optional
 **Input:** A change too large for one feature
 **Output:** `{specsDir}/{epic}/epic-manifest.json` + `EPIC.md` + one member-feature dir per feature
 **Method:** Decomposition interview splitting the change into member features with declared dependencies and `exposes`/`consumes` contracts. Purely additive: single-feature flows are unchanged. See [docs/architecture/epic-orchestration/README.md](../docs/architecture/epic-orchestration/README.md).
 
-### Stage 1: PRD (`/feature-forge:forge-1-prd <feature>`)
+### Stage 1: PRD (`forge-1-prd <feature>`)
 **Input:** User's feature idea and domain knowledge
 **Output:** `{specsDir}/{feature}/PRD.md`
 **Method:** Structured interview focused exclusively on requirements. No technology decisions.
 
-### Stage 2: Tech Spec (`/feature-forge:forge-2-tech <feature>`)
+### Stage 2: Tech Spec (`forge-2-tech <feature>`)
 **Input:** PRD.md
 **Output:** `{specsDir}/{feature}/tech-spec.md`
 **Method:** Structured interview for technology decisions, grounded in PRD requirements.
 
-### Stage 3: Implementation Specs (`/feature-forge:forge-3-specs <feature>`)
+### Stage 3: Implementation Specs (`forge-3-specs <feature>`)
 **Input:** PRD.md + tech-spec.md
 **Output:** `{specsDir}/{feature}/##-<name>.md` (suite of numbered documents)
 **Method:** Generate detailed implementation documents from spec archetypes.
 
-### Verification Gate (`/feature-forge:forge-verify <feature>`)
+### Verification Gate (`forge-verify <feature>`)
 **Input:** All artifacts from current and prior stages
 **Output:** `{specsDir}/{feature}/.verification/VERIFY-<stage>-<timestamp>.md` (includes both findings and a Fix Execution Plan)
 **Method:** Clean-context analysis producing actionable findings with an ordered fix plan.
@@ -47,28 +47,28 @@ also set, which chains `forge-fix` only when preconditions hold (zero unresolved
 tree, passing re-verify). See `references/shared-conventions.md` for the config keys.
 
 After verification, fixes can be applied via:
-- `/feature-forge:forge-fix <feature>` — reads the Fix Execution Plan from the findings document and applies changes (works in any session)
+- `forge-fix <feature>` — reads the Fix Execution Plan from the findings document and applies changes (works in any session)
 - Plan mode workflow — enter plan mode, run verify, review plan, exit and execute
 - Manual — read findings and apply fixes by hand
 
-### Stage 4: Backlog (`/feature-forge:forge-4-backlog <feature>`)
+### Stage 4: Backlog (`forge-4-backlog <feature>`)
 **Input:** Full spec suite
 **Output:** `{specsDir}/{feature}/backlog.json` (or `{backlogDir}/{feature}/backlog.json` if backlogDir is configured)
 **Method:** Generate structured backlog items with spec references, acceptance criteria, and dependencies. Backlog is collocated with feature specs by default.
 
-### Stage 5: Rauf Loop (`/feature-forge:forge-5-loop <feature>`)
+### Stage 5: Rauf Loop (`forge-5-loop <feature>`)
 **Input:** `backlog.json` from Stage 4
 **Output:** Implemented source code (committed per-item by rauf)
 **Method:** Execute the autonomous coding loop against the feature's backlog. Spawns a fresh session per backlog item with full spec context. rauf is the default runner but is swappable via the `loopRunner` block in `forge.config.json`; see [`references/ralph-loop-contract.md`](./ralph-loop-contract.md).
 
-### Stage 6: Documentation (`/feature-forge:forge-6-docs <feature>`)
+### Stage 6: Documentation (`forge-6-docs <feature>`)
 **Input:** Specs + implementation
 **Output:** `{docsDir}/{feature}/` documentation suite
 **Method:** Generate developer-focused architecture documentation.
 
 ## Pipeline State
 
-State is tracked in `{specsDir}/{feature}/.pipeline-state.json` and persists across session clears. The `/feature-forge:forge <feature>` navigator reads this file to show current progress.
+State is tracked in `{specsDir}/{feature}/.pipeline-state.json` and persists across session clears. The `forge <feature>` navigator reads this file to show current progress.
 
 ## Git Discipline
 

package/adapters/copilot/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.