@garygentry/feature-forge 0.3.6 → 0.3.7

package/adapters/gemini/skills/forge-guide/forge-guide.md

@@ -17,7 +17,7 @@ run pipeline stages; when the user is ready to act, point them at the right skil
 2. **Ground yourself in the canonical source before answering** — read the mapped
    reference file(s) below rather than answering from memory. These are the source
    of truth and stay current as the pipeline evolves.
-3. Answer concisely, then end with the concrete next command (`/feature-forge:forge-*`)
+3. Answer concisely, then end with the concrete next command (`forge-*`)
    or doc pointer the user should go to.
 
 | Topic | Read first |
@@ -28,6 +28,7 @@ run pipeline stages; when the user is ready to act, point them at the right skil
 | Stack detection / language profiles | `references/stack-resolution.md`, `references/stacks/*.md` |
 | Loop runner interface, signals & version gate | `references/ralph-loop-contract.md` |
 | Deep dives, glossary, troubleshooting | `references/process-overview.md`, `references/shared-conventions.md` |
+| Environment health / repair (`--doctor`) | `references/preflight-and-self-heal.md` |
 
 Those `references/` files are the guaranteed grounding path — they ship in every install.
 The project's `README.md`, `COMPATIBILITY.md`, and the hosted docs site are richer but are
@@ -36,6 +37,7 @@ URL to a human) and never block an answer on opening them — fall back to the `
 files and your own knowledge.
 
 Do NOT actually invoke stage skills or write files — this skill only explains and directs.
+The single carve-out is `--doctor` mode below, and it narrows rather than lifts the rule.
 
 ## What feature-forge is
 
@@ -85,13 +87,13 @@ carry context across stages instead of reading upstream artifacts.
 | any | `forge-verify` → `forge-fix` | findings report → applied fixes |
 | any | `forge` | status dashboard / navigator |
 
-Drive the whole thing with the **navigator**: `/feature-forge:forge <feature>` shows the
+Drive the whole thing with the **navigator**: `forge <feature>` shows the
 current stage and offers the next; with `autoInvokeNextStage` it launches it directly.
 
 ## Setup & configuration
 
-**First-time setup:** `/feature-forge:forge-init` (existing repo) creates `forge.config.json`
-with defaults. `/feature-forge:forge-bootstrap` scaffolds a *greenfield* (empty) repo to a
+**First-time setup:** `forge-init` (existing repo) creates `forge.config.json`
+with defaults. `forge-bootstrap` scaffolds a *greenfield* (empty) repo to a
 green baseline. On non-Claude agents, install via `npx @garygentry/feature-forge install`.
 
 **Key `forge.config.json` knobs** (authoritative list: `references/forge-config-schema.json`):
@@ -165,16 +167,91 @@ a minimum runner version (the version gate is described in `references/ralph-loo
 - Re-running an upstream stage marks downstream stages **stale** — re-run them rather than
   reaching for `--force`, which skips prerequisite checks and should be rare.
 - Specs are pre-implementation artifacts, not living docs — don't cite them from generated code.
-- Use the navigator (`/feature-forge:forge <feature>`) to orient; use `forge-verify` to inspect.
+- Use the navigator (`forge <feature>`) to orient; use `forge-verify` to inspect.
+
+## `--doctor` mode
+
+`forge-guide --doctor` is the **repair surface**: it turns `doctor`'s `checks[]`
+into a readable report and, only on an explicit yes, a scripted repair. Enter this mode **only**
+when the argument is `--doctor`; every other invocation of this skill stays purely advisory.
+
+**The carve-out, stated precisely.** Here — and nowhere else in this skill — you may run
+`doctor` (read-only), run a **`read-only`** remedy unprompted, and apply a **`local-write`**
+remedy after an explicit yes. `global-install` and `network` remedies stay **advise-only**:
+print the command, never run it. This skill still **never invokes stage skills**, never edits
+`.pipeline-state.json` or a backlog, and writes no artifact of its own — step 4's exclusion is
+what keeps the second of those true. Repair here means the environment, not the pipeline.
+
+**1. Read the whole catalog.** Not a narrowed gate: this surface is *about* the environment,
+so the breadth `references/preflight-and-self-heal.md` §1 forbids inside a hard gate (where an
+unrelated advisory must never block a launch) is exactly what belongs here. The `--json`
+payload already carries every record, `ok` and `na` included; `--verbose` changes only the
+human printer, so it is a no-op on this call.
+
+```bash
+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/forge-session.py" doctor --json
+```
+
+**2. Render the summary.** Lead with `checksSummary`, then one row per **`warn` or `fail`**
+check — that is the affected set §2 step 1 defines, and `na` is not a finding (its `detail`
+names the prerequisite that would make it applicable). Blocking rows first. Each row carries
+the check's own `detail`, its `remedy.safety` as the tier, and `remedy.description` **and**
+`remedy.command` verbatim, so the operator sees the exact string before being asked about it;
+render `—` for a null `remedy`. Never invent a remedy `doctor` did not emit.
+
+**3. Take your rung from that same report.** A full-catalog run carries the
+`interaction-mode` record, so read its `evidence.mode` rather than calling again — three
+values, three answers. `non-interactive` (it carries `rung: 3`) → step 5. `interactive` →
+classify yourself against `references/shared-conventions.md` § Interaction Capability Ladder
+as usual. **`unknown`, an `na` record, a `warn` carrying `evidence.conflict`, or no such check
+at all → the report did NOT answer it**: self-assess against that same ladder and prefer its
+prose-question rung over assuming an answer. `unknown` is never rung 3 — reading it that way
+is the silent behavior change the ladder forbids. (An unstamped `codex exec` reports exactly
+this, so the branch is the common case, not the corner.)
+
+**4. Repair,** following `references/preflight-and-self-heal.md` over the `warn`/`fail` set:
+cluster from `remedyClusters[]`, then **partition by tier before asking anything** —
+`read-only` runs unprompted; `local-write` gets **one consolidated question per cluster**
+(never one per check); `global-install`, `network`, and any null-command remedy are
+**advise-only** and are never offered for execution. Print the `preflight:` outcome line before
+acting, run an approved command verbatim, then **prove** by re-running the identical `doctor`
+invocation. A remedy that exited 0 but left a member check not `ok` is a failed preflight, not
+a partial success, and it **stops the repair** — report every remaining cluster as unattempted
+rather than continuing past it.
+
+**Excluded from apply, at every rung:** a remedy that changes which commit is checked out or
+rewrites a feature's `.pipeline-state.json` — today `branch-state`'s `git switch …` and
+`state-branch …`. Print them as advice and let the operator run them. They are pipeline
+bookkeeping rather than environment repair, they are not idempotent the way the `local-write`
+tier assumes, and applying one mid-run would move the tree the prove step re-measures.
+**Consent does not persist across invocations:** the ladder's "ask once per remedy class per
+session" memo covers one run of this mode; a second `--doctor` asks afresh, because its
+advertised output is a report and an operator asking to *look* must never trigger a write.
+
+**5. Rung 3 → report-only.** State `interaction: rung 3 (non-interactive) — declared defaults
+apply`, then take this site's declared default: the ladder's **preflight-remedies** class,
+under which a `local-write` cluster degrades to advise-only and is recorded
+`unaskable→advise-only`. Nothing that needs a yes is applied; a `read-only` cluster still runs,
+as at any rung. The report is the entire deliverable.
+
+**6. Close** with every check still `warn`/`fail`, each next to its own `remedy.command` — or
+the words *no scripted command* where the remedy is null or absent. Do not reduce them to one
+command: several unresolved checks usually need several, and inventing a combined one is
+exactly the fabrication step 2 forbids.
 
 ## Troubleshooting starters
 
+- **Anything environmental:** point the user at `forge-guide --doctor` — it
+  reports every `doctor` check and walks the consented repair. Name it; do not enter that
+  mode from an answer that was not invoked with `--doctor`.
 - **Stage 5 won't start:** backlog exists and is verified? runner installed and ≥ min version?
   working tree clean? See `references/ralph-loop-contract.md` for the runner contract and version gate.
 - **Loop stopped mid-run:** check the signal — `BLOCKED`/`NEEDS_HUMAN` items are set aside, not
   failures; the loop keeps going.
 - **Downstream flagged stale:** an upstream stage was revised; re-run the downstream stage.
-- **Where am I?** `/feature-forge:forge <feature>` renders the full pipeline status.
+- **Where am I?** `forge <feature>` renders the full pipeline status.
 
 For anything deeper, ground yourself in `references/process-overview.md` and
 `references/shared-conventions.md`, and point the *user* at the hosted docs site —
@@ -186,6 +263,6 @@ For anything deeper, ground yourself in `references/process-overview.md` and
 
 This skill was authored Claude-first; the body above refers to "the host's question mechanism", "the host's subagent mechanism", and "the host's background-execution mechanism". Use your runtime's equivalent for each — and if your runtime has no such tool:
 
-- **User input:** ask the question directly and wait for the answer before proceeding. Do not skip a required question or assume an answer.
+- **User input:** ask the question directly and wait for the answer when your runtime can prompt and wait; never assume one. Read whether it can from the Interaction Capability Ladder's `interaction-mode` record rather than judging it. When your runtime is genuinely non-interactive, take the Interaction Capability Ladder's declared conservative default, state it in your output, and use `no-default: abort — <question> requires a human answer` for an interview question with no sane default (`references/shared-conventions.md`).
 - **Subagents:** if your host cannot dispatch the named custom agent, run that step inline yourself.
 - **Background / monitoring:** run long-lived commands in the foreground (or your host's background facility) and report progress as it arrives.

package/adapters/gemini/skills/forge-guide/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/gemini/skills/forge-guide/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/gemini/skills/forge-guide/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