@garygentry/feature-forge 0.3.5 → 0.3.7

package/adapters/claude/skills/forge-6-docs/references/shared-conventions.md

@@ -13,11 +13,13 @@ If no feature name is provided:
 4. Do NOT proceed until a feature name is explicitly given
 5. The feature name must be a single kebab-case token. If the user provides multiple words (e.g., "user auth flow"), convert to kebab-case: `user-auth-flow`.
 
+If the invocation includes a `<feature-forge-invocation>` envelope, read the argument string (the feature name and any flags) from its `<arguments>` element, unescaping XML entities (`&amp;`→`&`, `&lt;`→`<`, `&gt;`→`>`) — do not treat the envelope's own tags as part of the argument. An **empty** `<arguments>` element means no argument was supplied: treat it exactly as invoking the skill with no argument — for a skill that requires a feature name, that triggers the STOP-and-ask rule above; for a skill whose argument is optional (e.g. the `forge` navigator), proceed as usual. When no envelope is present, read the first argument as before. (Some hosts append invocation arguments without a semantic boundary; the envelope makes them unambiguous. Read the literal token — never infer the feature name from surrounding phrasing.)
+
 ## User Input Protocol
 
-### CRITICAL GUARDRAIL: Use AskUserQuestion for All Questions
+### CRITICAL GUARDRAIL: Use `AskUserQuestion` for All Questions
 
-You MUST use the `AskUserQuestion` tool whenever you need the user's input before proceeding. This includes yes/no confirmations, choices between options, interview questions, and feedback on artifacts. NEVER output questions as inline prose text — the user may not be prompted and the session will stall.
+You MUST use the `AskUserQuestion` for every question whenever it is present in your tool surface. This includes yes/no confirmations, choices between options, interview questions, and feedback on artifacts. NEVER output questions as inline prose text — the user may not be prompted and the session will stall. When the tool is absent, or you are running non-interactively, follow the **Interaction Capability Ladder** below instead of assuming an answer.
 
 **Required turn structure:** Output your analysis, findings, or context as regular text. Then call `AskUserQuestion` with your questions. Do NOT mix questions into your text output.
 
@@ -31,7 +33,7 @@ I found that the codebase uses React and TanStack Router. Here are my questions:
 **RIGHT — context as text, questions via tool:**
 ```
 I found that the codebase uses React and TanStack Router.
-[then call AskUserQuestion with: "1. Where should this component live? 2. Should we use server-side rendering?"]
+[then call `AskUserQuestion` with: "1. Where should this component live? 2. Should we use server-side rendering?"]
 ```
 
 ### Decision Support: Help the User Choose
@@ -53,6 +55,81 @@ For genuinely comparable artifacts (competing module structures, two code snippe
 
 The **Branch Setup** block below is the reference pattern: a strong recommendation as the first option, rationale inline, the alternative still available, never a hard-stop.
 
+## Interaction Capability Ladder
+
+This is the **one canonical statement** of interaction capability (`roadmap/self-healing-resilience.md` §5.4) — every prompting surface in canon points here **by title** rather than restating it. Written to read correctly **independent of the host name**, including after the build's host-term translation degrades the Claude-native tool name to host-neutral phrasing on non-Claude, non-Pi targets.
+
+```text
+  Rung 1  Structured question tool present   →  use it (the concrete tool name is
+                                                 your host's own — see its overlay
+                                                 notes, e.g. Pi's below).
+  Rung 2  No structured tool, but the host    →  ask in plain prose and wait for the
+          can still prompt and be answered       reply. This IS the sanctioned rung-2
+          (Codex interactive)                    mechanism, not the "never embed a
+                                                 question in text output" violation
+                                                 that guardrail names for rung 1.
+  Rung 3  Genuinely non-interactive           →  take the DECLARED default, STATE that
+          (print/JSON mode, headless CI)          you took it and why, and record it.
+                                                 Never stall.
+```
+
+**Two independent axes.** `--host` is **static** per adapter bundle — the build-substituted `--host` value — and never implies a rung either direction (INV-5): a Claude session can still run non-interactively (`claude -p`), and an interactive Codex session is not rung 3 just because Codex lacks a structured tool. **Rung is dynamic** — determined once per session from the record below, not guessed — and, whenever it is not rung 1, **stated once** in output: `interaction: rung 3 (non-interactive) — declared defaults apply`.
+
+**Determination — read it, never guess it.** The two halves of the ladder are not equally observable. *Rung 1 vs rung 2* is a fact about **you**: whether a structured question tool sits in your surface, which you can see. *Rung 2 vs rung 3* is a fact about the **invocation** — whether anyone is on the other end — and you have no signal for it at all. Measured, not assumed: five headless runs across two hosts every time self-assessed rung 2, emitted a prose question and stalled with the run's remaining steps unreachable. A `codex exec` run, for instance, is rung 3 and looks from the inside exactly like an interactive `codex` session, which is rung 2 — the difference is real but not visible to you. So take that half from `doctor`, which can observe what you cannot:
+
+```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 --check interaction-mode
+```
+
+Read the record's `evidence`:
+
+| `evidence.mode` | Rung |
+|---|---|
+| `non-interactive` (carries `rung: 3`) | **rung 3**, whatever your tool surface suggests |
+| `interactive` | rung 1 with a structured question tool, else rung 2 |
+| `unknown`, or no such check (an older install) | self-assess as before, and prefer rung 2's prose question over assuming an answer |
+
+`unknown` is never "headless": guessing that would make an interactive session silently skip its questions and take no-write defaults, trading a visible stall for a silent behavior change.
+
+The check itself is read-only and spawns nothing — it reads one environment variable and `/proc`. (The surrounding `doctor` run still makes its usual read-only `git` queries to build the report.)
+
+`evidence.hostArg` carries the `--host` value and `evidence.host` the adapter id — the concrete value every "gate on the build-substituted `--host`" instruction in canon asks you to read. Never substitute tool availability for either axis (INV-5): on Pi a compatibility extension registers a structured question tool, so that signal reports "Claude".
+
+**Secondary signal, never a substitute.** A structured question tool that is *registered but fails when called* is itself proof of rung 3: the call returns `Error: UI not available (running in non-interactive mode)`, which is the rung-3 backstop and **never** a user decline. Treat that error as rung 3 wherever you meet it.
+
+Its *absence* proves nothing either way. Pi has that tool **stripped from the tool list** outright in `-p`/`--mode json`, so there is no call to attempt and no error to read — and an absent tool is the rung-1-vs-rung-2 question, not the rung-2-vs-rung-3 one. Reading absence as rung 2 is exactly the stall this block exists to prevent.
+
+**Determine it before your first question, not at the question.** Determining it lazily at the question site is how a run stalls: by then you have already decided to ask. So run the command above **now** unless you already hold a `doctor` report that contains an `interaction-mode` record — a *narrowed* `doctor --json --check …` run (which is what `forge-5-loop`'s gates 1c/1d and `forge-init`'s install preflight both use) does **not** contain one unless it named this check, so it is not a substitute. Reuse the record only if you can see it; otherwise run the command. A launcher that knows the session has no reply channel states so with `FORGE_INTERACTION=non-interactive`, which is how the record answers on hosts where nothing else is observable.
+
+**Rung-3 rule (conservative-only, INV-6).** At a rung-3 site, either:
+- take the declared default — always the **no-write / no-proceed** option: it **never advances a pipeline stage**, launches a loop, applies a remedy, creates a branch, commits, or records a decision — and state that default and why; or
+- when no conservative default exists (an interview question with no sane unattended answer), emit `no-default: abort — <question> requires a human answer` and stop.
+
+"No-proceed" scopes to **the decision in front of you, never to the skill**: it declines *this* action, it does not by itself end the run. So after taking a no-write default, carry on with the remaining steps. A rung-3 site that quietly ends the skill early is indistinguishable from one that finished.
+
+What *does* end the run is a default that says so. `no-default: abort` stops, and so does any site whose class below declares **STOP** — those stop deliberately, and stopping is then the stated outcome, not a silent exit. The rule is: **stop only when your site's declared default is a stop; never as a side effect of the words "no-proceed".**
+
+Either outcome **must be stated in the output** — a rung-3 site that silently proceeds or silently stalls is a defect, not a degraded pass.
+
+**Site classes.** Rather than a per-site declaration (107 sites and rising), every question surface that uses `AskUserQuestion` inherits its rung-3 default from its class — a surface cites this table by title, never restating its own row:
+
+| Class | Rung-3 default |
+|---|---|
+| Verification warnings | STOP; print the verify command |
+| Dependency / epic gates | STOP |
+| Launch / run-mode | STOP; print the rendered command |
+| Preflight remedies | `local-write` degrades to advise-only (§ Remedy Safety Ladder below) |
+| Branch setup / reconcile | never create, switch, or record |
+| Interviews / pickers / blocking gates | `no-default: abort` with a stated reason |
+| Entry / completion guards | STOP |
+| Destructive confirmations | never mutate |
+| Verify-capability determination (stage-exit) | fall back to `--verify-capability manual` |
+| Verify run/skip offers (e.g. forge-5-loop Step 5b/6.1) | STOP; run nothing, persist no skip — the decision stays unrecorded for a human, never guessed as "skip" |
+| Recovery interview | fall through to `needs-human` |
+| Anything not listed above | STOP or skip, and state which |
+
 ## Stage Review Gate
 
 Every authoring stage ends its "Review with User" step in exactly one of two shapes. Which shape a stage uses is declared **here, once** — each stage's review step points at this block by title, and the shape is never re-derived from the surrounding prose or inferred from how sibling stages behave (three stages block and one does not; majority-shape inference is precisely the failure this block exists to prevent):
@@ -92,7 +169,7 @@ Extract these config values (use defaults if not present):
 Before any file I/O against a feature's artifacts, resolve its directory through the deterministic helper rather than hardcoding `{specsDir}/{feature}/`. This makes flat (`{specsDir}/{feature}/`) and nested (`{specsDir}/{epic}/{feature}/`) layouts both resolve from a bare feature name (REQ-DIR-03), with standalone features behaving exactly as today.
 
 ```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; }
 resolvedFeatureDir=$(python3 "$R/scripts/epic-manifest.py" \
   resolve "<feature>" --specs-dir "<specsDir>")
@@ -107,7 +184,7 @@ In both failure cases, do not fall back to a guessed path.
 **On `not-found`, check other branches before stopping.** With `branchPerFeature`, the feature's directory (and its `.pipeline-state.json`) may exist only on its topic branch — invisible from the default branch of a fresh clone. Before concluding the pipeline does not exist, run the read-only cross-branch discovery:
 
 ```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/forge-session.py" discover-feature "<feature>" --specs-dir "<specsDir>" --json
 ```
@@ -115,6 +192,10 @@ python3 "$R/scripts/forge-session.py" discover-feature "<feature>" --specs-dir "
 - **Candidates found** (`candidates` and/or `remoteCandidates` non-empty): summarize them as text (branch, recorded stage, whether the state's own `branch` field matches), then use `AskUserQuestion`: **Switch to `{branch}` (recommended)** — run the candidate's `switchCommand` · **Fetch + switch** — for a `needsFetch` remote candidate, run its `fetchCommand` then `switchCommand` (note its contents were matched by name only, not inspected) · **Treat `{feature}` as new on this branch** · **Stop**. A checkout is a mutation inside an otherwise read-only flow: perform it ONLY on the user's explicit accept AND with a clean working tree (`git status --porcelain` prints nothing) — never auto-switch, never with uncommitted changes. After a successful switch, re-run this Feature Directory Resolution block from the top.
 - **Nothing found** (both lists empty): the pipeline genuinely does not exist anywhere discoverable — STOP and surface the original `not-found` stderr line verbatim (or, where the caller offers to start a new pipeline, offer that).
 
+**Rung-3 default** (Interaction Capability Ladder above, "branch setup / reconcile"
+class): no question mechanism → never switch or fetch; report the candidates found
+and stop, exactly as the "nothing found" branch already does.
+
 **Anti-fabrication guard.** Never describe pipeline state that resolution or discovery did not return: if both come back empty, the pipeline does not exist — say exactly that, and never reconstruct stages, backlogs, or history from conversational memory.
 
 **Resolution algorithm (summary; full spec in `02-manifest-helper-cli.md §4`):**
@@ -135,22 +216,64 @@ Whenever a stage creates the specs tree for the first time (the first PRD or epi
 Run this after creating the feature/epic directory, before the stage's git commit:
 
 ```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; }
 mkdir -p "<specsDir>"
 [ -f "<specsDir>/AGENTS.md" ] || cp "$R/references/templates/specs-hygiene/AGENTS.md" "<specsDir>/AGENTS.md"
 ```
 
-If the host is Claude (the Claude-native question tool is available), also ensure the Claude-framed variant:
+If the host is Claude — the build-substituted `--host` value (§ Interaction Capability Ladder), never inferred from tool availability — also ensure the Claude-framed variant:
 
 ```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; }
 [ -f "<specsDir>/CLAUDE.md" ] || cp "$R/references/templates/specs-hygiene/CLAUDE.md" "<specsDir>/CLAUDE.md"
 ```
 
 Stage any file this writes (`{specsDir}/AGENTS.md`, and `{specsDir}/CLAUDE.md` when written) as part of the stage's existing git commit.
 
+## Root Hygiene (Tooling Feedback)
+
+The **Tooling Feedback Protocol** — how an agent working in a forge-driven project reports friction with feature-forge or rauf — is stated once, here, and shipped as project content in `references/templates/root-hygiene/{AGENTS,CLAUDE}.md`. The protocol: route by tool (feature-forge → <https://github.com/garygentry/feature-forge/issues>, rauf → <https://github.com/garygentry/rauf/issues>); capture it while fresh as *what you ran / what you expected / what actually happened / a fix idea*; file it with `gh issue create` **only on the human's explicit go-ahead, never silently**; and **never file mid-loop** — in an autonomous rauf iteration, append the friction to `progress.md` for later triage. `forge-bootstrap` writes this section into the repos it scaffolds; **`forge-init` writes it for every other project**, which is what makes the `specs/` hygiene files' "see the project-root `AGENTS.md`" pointer resolve.
+
+`forge-init` runs this step after `forge.config.json` exists. **Look before you ask**: work out which variants are missing *first*, and prompt only for the ones you would actually write. A question about a file that already exists spends the operator's attention on a write that cannot happen, and a second `forge-init` run must be silent, not repetitive.
+
+**Which variants apply.** `AGENTS.md` always; `CLAUDE.md` only when the host is Claude — the build-substituted `--host` value (§ Interaction Capability Ladder), exactly as the Specs Directory Hygiene block above resolves the same question, and **never** inferred from which tools this session happens to have (INV-5).
+
+**Then, for each applicable variant, exactly one of three cases:**
+
+1. **The file does not exist.** The only case with anything to write. It is a **`local-write`** (§ Remedy Safety Ladder): ask **once**, as a single consolidated question covering every missing variant — *"Write the feature-forge tooling-feedback section to `AGENTS.md`{ and `CLAUDE.md`}?"* — then run the guarded copy below.
+2. **The file exists and already carries a "Tooling feedback" heading** — any heading level, any capitalization, leading whitespace allowed. Test it that broadly (`grep -qiE '^[[:space:]]*#{1,6}[[:space:]]*Tooling feedback' AGENTS.md`), because a narrower test is not conservative: a file whose heading reads `## Tooling Feedback (feature-forge / rauf)` would fall through to case 3 and be handed the very duplicate this case exists to prevent. Nothing to do, by anyone: `forge-bootstrap` wrote it, an earlier `forge-init` wrote it, or the project wrote its own. **Say nothing and do not prompt** — this is the idempotent case, and printing the block again for the operator to paste is how the section ends up in the file twice.
+3. **The file exists and does not contain that heading.** The project owns that file: never append to it, never overwrite it, and do not prompt — there is no write to consent to. Print the template's "Tooling feedback" section once for the operator to paste, and say that is what you are doing.
+
+**Anchor the write, in the same shell as the copy.** Unlike the Specs sibling, whose target is the config-derived `<specsDir>` path, these targets are bare and `$PWD`-relative — and a shell's cwd persists between calls. `AGENTS.md` written into the wrong directory is not a stray file: it is an agent-instruction file every coding agent in that directory will read as instructions, and `$HOME` is the realistic wrong directory. The `[ -f … ] ||` guard prevents a clobber but not a *creation*.
+
+So the assertion and the copy are **one command block, not two** — a separate assertion block's `exit 1` ends only its own shell and leaves the next block unguarded. Run this in the directory `forge.config.json` was just written to; if the cwd has moved to a nested project with its own config, `cd` back first, because the assertion can only tell you *a* forge project is here, not that it is the one you initialized.
+
+```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; }
+ROOT="$PWD"
+[ -f "$ROOT/forge.config.json" ] || { echo "root hygiene: $ROOT is not the initialized project root — skipping" >&2; exit 1; }
+[ -f "$ROOT/AGENTS.md" ] || cp "$R/references/templates/root-hygiene/AGENTS.md" "$ROOT/AGENTS.md"
+```
+
+If the host is Claude, also — again as one block:
+
+```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; }
+ROOT="$PWD"
+[ -f "$ROOT/forge.config.json" ] || { echo "root hygiene: $ROOT is not the initialized project root — skipping" >&2; exit 1; }
+[ -f "$ROOT/CLAUDE.md" ] || cp "$R/references/templates/root-hygiene/CLAUDE.md" "$ROOT/CLAUDE.md"
+```
+
+The `[ -f … ] ||` guard is the last line of defence, not the case analysis above: even if the cases were misread, the copy cannot overwrite. Case 2 is what keeps a *second* run quiet; the guard is what keeps it safe.
+
+**Staging.** `forge-init` has no git commit step of its own, so a file written here would otherwise sit untracked and be swept into whatever commits next (a stage commit, or a loop iteration's first commit). Name each file written and `git add` it, leaving it staged for the operator rather than loose.
+
+**Rung-3 default — for case 1 only** (§ Interaction Capability Ladder). Cases 2 and 3 write nothing and ask nothing at *any* rung, so the rung never changes them: a rung-3 run still stays silent in case 2 and still prints the paste block in case 3. Reporting "tooling-feedback skipped" for a file that already carries the section would make every headless init noisier than an interactive one, which is backwards. Only case 1's consent-dependent write degrades. This is not a *preflight remedy* — `doctor` emitted no remedy here — so it takes the table's catch-all row, "skip, and state which": write nothing, and state that the tooling-feedback section was skipped and how to get it (re-run `forge-init` from an interactive session, or paste the template). That is the same posture the safety ladder's "degrade one tier stricter" rule produces for an unaskable `local-write`, reached by the ladder rather than by borrowing a row this site does not sit in.
+
 ## Epic Context Injection
 
 After resolving the feature directory, check the feature's `.pipeline-state.json` for an `epic` back-pointer. **If absent, skip this block entirely** (standalone feature — REQ-COMPAT-01; standalone-feature behavior is unchanged). **If present**, load exactly the following context, and nothing transitive (REQ-CTX-01):
@@ -164,7 +287,7 @@ After resolving the feature directory, check the feature's `.pipeline-state.json
 To obtain the manifest contracts and the live completion status of each dependency in one deterministic call, run `render-status` and read the per-feature `status` and the `consumes`/`exposes` arrays rather than re-deriving them:
 
 ```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
@@ -179,7 +302,7 @@ If `render-status` fails, proceed with **only** EPIC.md + charter (a corrupt man
 Defense-in-depth for the split-brain-epic failure (Issue #125). Invoke this block in the authoring stages (`forge-1-prd`..`forge-4-backlog`) once the feature has resolved — right after **Epic Context Injection** for the stages that run it (`forge-1-prd`..`forge-3-specs`), and right after **Feature Directory Resolution** for `forge-4-backlog`. It confirms that a **resolved nested epic member** actually sits on a branch that contains the epic's manifest. Without this, a member reached from a branch cut *before* the epic-manifest commit (or that otherwise lacks it) would author specs against an epic decomposition that is not present — the exact drift that produces a disjoint, split-brain member. **Skip if not a git repo or `branchPerFeature` is false.**
 
 ```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/forge-session.py" check-epic-base --feature "{feature}" --specs-dir "{specsDir}" --json
 ```
@@ -192,7 +315,7 @@ Act on the emitted `action`:
 
   With `--force`, log a one-line warning ("Authoring `{feature}` against a detached epic base — manifest not on this branch") and proceed, consistent with the other guards.
 
-If the helper is unavailable (a non-Claude host without the resolver), skip this block — it is best-effort defense in depth, not a hard prerequisite.
+If `$R` cannot be resolved or `check-epic-base` is unavailable, skip this block — it is best-effort defense in depth, not a hard prerequisite.
 
 ## Pipeline State Protocol
 
@@ -206,12 +329,12 @@ If a `state-*` verb exits 2, surface the plain `Error:` line from stderr verbati
 
 ### `state-verify` — verification results and provenance
 
-`state-verify` writes exactly one `stages.forge-verify-{token}` entry — the verification result for the production stage named by `--stage` — plus the top-level `updatedAt`, and nothing else. `--stage` takes the **served production stage** (`forge-0-epic` through `forge-5-loop`; `forge-6-docs` has no verification token and is rejected). Add `--epic "{epic}"` when the feature is an epic member — required, per the member rule above. Result mode passes `--status` (`auto-verify-pending`, `passed`, `findings-reported`, `findings-applied`, or `skipped`) with whatever `--findings-file`, `--findings-count`, and `--verified-stage-version` that status requires; contradictory metadata is refused before any write. `passed` may additionally carry `--findings-file` + `--findings-count` together for an **advisory-only** report (`inconsistency`/`improvement` findings only, per forge-verify's severity floor) — the stage resolves without a fix round and the report stays attached:
+`state-verify` writes exactly one `stages.forge-verify-{token}` entry — the verification result for the production stage named by `--stage` — plus the top-level `updatedAt`, and nothing else. `--stage` takes the **served production stage** (`forge-0-epic` through `forge-5-loop`; `forge-6-docs` has no verification token and is rejected). Add `--epic "{epic}"` when the feature is an epic member — required, per the member rule above. Result mode passes `--status` (`auto-verify-pending`, `passed`, `findings-reported`, `findings-applied`, or `skipped`) with whatever `--findings-file`, `--findings-count`, and `--verified-stage-version` that status requires; contradictory metadata is refused before any write. `passed` may carry `--findings-file` + `--findings-count` for a clean report (count `0`), an **advisory-only** report (`inconsistency`/`improvement` findings only), or accepted residual findings. The stage resolves without a fix round and the report stays attached, making a completed verification round directly resumable if provenance recording is interrupted. A bare `passed` remains accepted for backward compatibility:
 
 **`auto-verify-pending` is not a skill-facing status.** It is written by `stage-exit`'s scheduling boundary, which records the debt automatically when auto-verify is effective for a stage. The value is accepted on this CLI so the entry stays inspectable and repairable, not so a skill can hand-schedule verification: no skill body and no reference passes it, and none should. Every other status in the list is the recorded *result* of a verification that ran (or was explicitly skipped); this one records that one was *owed*.
 
 ```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/forge-session.py" state-verify \
   --feature "{feature}" --stage "{served-production-stage}" --status "<status>" \
@@ -221,7 +344,7 @@ python3 "$R/scripts/forge-session.py" state-verify \
 Provenance follows the same two-commit sequence as `state-complete`: the result transition above writes `commitHash: null`, Commit 1 records the findings document and the state, and a second `state-verify` call records the full 40-hex hash of Commit 1 and touches nothing else (never `--amend`; an abbreviated hash is refused rather than expanded). Add `--epic "{epic}"` for an epic member — required, per the member rule above:
 
 ```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/forge-session.py" state-verify \
   --feature "{feature}" --stage "{served-production-stage}" \
@@ -231,7 +354,7 @@ python3 "$R/scripts/forge-session.py" state-verify \
 Epic-scoped verification is the single exception to the member rule: with `--stage forge-0-epic`, `--feature` names the **epic** and `--epic` must be absent or exactly equal to it. That call writes `{specsDir}/{epic}/.epic-state.json` and never a member's `.pipeline-state.json`, and its freshness version is the epic manifest's `revision`, never a member's stage version:
 
 ```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/forge-session.py" state-verify \
   --feature "{epic}" --stage forge-0-epic --status "<status>" \
@@ -253,7 +376,7 @@ Frame the choice with its cost: re-running re-derives this stage from the curren
 When an interview raises a concern that belongs to a *later stage of this same feature*, acknowledge it and persist it **immediately, at the moment it is raised** — not at stage closure — by running `state-note` with a concise one-line statement of the concern. Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol above; omitting it for a member is an error and must never be allowed to fall back to a same-named flat feature.
 
 ```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/forge-session.py" state-note \
   --feature "{feature}" --note "<concise downstream concern>" \
@@ -294,10 +417,14 @@ Invoke this block at the **very start** of a pipeline entry point — `forge-1-p
    - **Create** → `git switch -c {branchPrefix}{label}` (or `git checkout -b` if `switch` is unavailable). If the branch already exists, `git switch {branchPrefix}{label}`.
    - **Stay** → proceed on the default branch; note that subsequent commits (and any `forge-5-loop` run) will land directly on `{defaultBranch}`.
 
+   **Rung-3 default** (Interaction Capability Ladder above, "branch setup / reconcile"
+   class): no question mechanism → **Stay** — never create or switch a branch
+   unattended; proceed on the default branch and state that this default was taken.
+
 **Record the branch.** After this block resolves, record the resulting branch name in the feature's top-level `branch` field by running `state-branch` (create/update it when the state file is first written for this stage). Emit the call **once the feature directory exists** — i.e. after Feature Directory Resolution and the Entry Stamp, **not** at this block: Branch Setup runs at the very start of the entry point, before any directory resolution, and a brand-new standalone feature may have no directory yet. Add `--epic "{epic}"` to the call when this feature is an epic member — required, per the Pipeline State Protocol.
 
 ```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/forge-session.py" state-branch \
   --feature "{feature}" --branch "<name>" --specs-dir "{specsDir}"
@@ -310,7 +437,7 @@ Downstream stages and `forge-5-loop` read it to detect drift back onto the defau
 The recorded `branch` is a **self-healing hint, not gospel.** A hosted environment (Claude.ai remote, cloud agents) can impose an arbitrary session branch (e.g. `claude/<slug>`) that Branch Setup silently records; the user may then move the work to the intended topic branch, leaving the recorded field stale. Every branch-aware mechanism (the `forge-5-loop` guard, `discover-feature`) keys off that field, so a stale value actively misleads — the loop would offer to switch you *back* to the imposed branch. Invoke this block from `forge-5-loop`'s pre-flight (and any stage that acts on the recorded branch) to reconcile deterministically. Skip if not a git repo or `branchPerFeature` is false.
 
 ```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/forge-session.py" reconcile-branch --feature "{feature}" --specs-dir "{specsDir}" --json
 ```
@@ -320,16 +447,20 @@ Act on the emitted `action` (source of truth is where the state actually resolve
 - **`warn-drift`** — you are on the **default** branch and the state records a topic branch. Via `AskUserQuestion`, strongly recommend creating/switching to `{branchPrefix}{feature}` (then record it), still allowing **proceed on the default branch**. Never hard-stop.
 - **`none`** / **`not-resolved`** — nothing to do; proceed.
 
+**Rung-3 default** (Interaction Capability Ladder above, "branch setup / reconcile"
+class): no question mechanism on `warn-drift` → proceed on the default branch, exactly
+as the allowed no-prompt option already does; never create or switch unattended.
+
 The `adopt-current` write, with the portable plugin-root prelude. Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol:
 
 ```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/forge-session.py" state-branch \
   --feature "{feature}" --branch "{newBranch}" --specs-dir "{specsDir}"
 ```
 
-If the helper is unavailable (non-Claude host without the resolver), fall back to the manual check: current branch differs from recorded → adopt the current branch unless it is the default, in which case recommend creating `{branchPrefix}{feature}`.
+If `$R` cannot be resolved or `reconcile-branch` is unavailable, fall back to the manual check: current branch differs from recorded → adopt the current branch unless it is the default, in which case recommend creating `{branchPrefix}{feature}`.
 
 ## Git Commit Protocol
 
@@ -349,7 +480,7 @@ When `gitCommitAfterStage` is true, follow this exact order to avoid state incon
 The two `state-complete` calls, with the portable plugin-root prelude. Add `--epic "{epic}"` to each when this feature is an epic member — required, per the Pipeline State Protocol:
 
 ```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; }
 # Commit 1 — before `git commit`
 python3 "$R/scripts/forge-session.py" state-complete \
@@ -376,10 +507,15 @@ Invoke this block at the **start of an authoring stage** (`forge-1-prd`..`forge-
 
 3. **Re-authoring** (`status: "complete"` or `"stale"`) — a finished draft exists. Warn via `AskUserQuestion` before overwriting: "A completed {stage} artifact already exists for '{feature}' (v{n}{, marked stale}). Continuing will create a new version. Proceed?" On confirm, proceed to the Entry Stamp and author a new version (the version increments at exit, per that stage's Update-Pipeline-State step).
 
+**Rung-3 default** (Interaction Capability Ladder above, "entry / completion guards"
+class): no question mechanism at cases 2 or 3 → **STOP** — resume the in-progress draft
+(case 2's non-destructive default) or refuse to overwrite a completed artifact (case 3);
+never start a fresh version or bump it unattended.
+
 **Entry Stamp** (fresh, restart, and re-author paths — NOT the resume path). Before authoring, record the entry stamp by running `state-enter` — one atomic write that sets `stages.{stage}.status` → `"in-progress"`, `stages.{stage}.startedAt` → current ISO-8601 UTC timestamp, top-level `currentStage` → `"{stage}"` (where the pipeline IS, per O1), and refreshes `updatedAt`. Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol:
 
 ```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/forge-session.py" state-enter \
   --feature "{feature}" --stage "{stage}" --specs-dir "{specsDir}"
@@ -392,7 +528,7 @@ This write is **left uncommitted**: it is staged and committed as part of this s
 **Incremental artifact tracking:** When a stage writes multiple files (e.g. forge-3-specs writing a suite of spec documents), run `state-artifact --feature {feature} --stage {stage} --path <file>` after writing each file — not just at stage completion. This is what makes the Interrupted inventory above precise about which files were successfully written. Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol.
 
 ```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/forge-session.py" state-artifact \
   --feature "{feature}" --stage "{stage}" --path "<file>" --specs-dir "{specsDir}"
@@ -410,6 +546,23 @@ Invoke this block **at the head of any post-entry step that writes a stage artif
 
 When you cannot confirm you authored the current run, treat it as a replay and refuse: a false refuse costs one confirmation click; a false proceed overwrites a committed artifact and re-churns a stage version. `--force` follows Force Mode (skip the gate, treat as a deliberate re-author).
 
+## Remedy Safety Ladder
+
+The safety tier every `doctor` check remedy (`{description, command, safety}`,
+`roadmap/self-healing-resilience.md` §5.2) declares, referenced by `safety` value
+wherever a skill or reference applies one — never restated per-site.
+
+| `safety` | Meaning | Prompt? | Execute? |
+|---|---|---|---|
+| `read-only` | Diagnoses only; touches nothing. | Never. | Run freely. |
+| `local-write` | Writes inside the project, idempotent, git-visible (`rauf install .`, writing a detected `testCommand`, copying a hygiene template). | Once per distinct `remedy.command` string per session. | Run after that one consent — never re-prompt the identical command again this session. |
+| `global-install` | Touches the machine outside the project (`npm i -g`, PATH edits). | N/A. | **Never.** Advise-only — print the exact command, never run it. |
+| `network` | Fetches from a remote (registry queries, `curl \| bash`). | N/A. | **Never.** Advise-only — print the exact command, never run it. |
+
+**Degrade one tier stricter when the session cannot ask** (`references/preflight-and-self-heal.md` §4): a `local-write` remedy with no question mechanism runs at the `global-install`/`network` posture instead — advise-only, never unasked. `read-only` is unaffected (it was never gated on asking); `global-install`/`network` are already the floor.
+
+**A remedy that ran but did not prove is a failure, not a partial success.** Executing a `local-write` command is never itself the outcome — the consumer that applied it (`references/preflight-and-self-heal.md` §2 step 6) re-checks the condition the remedy claimed to fix and reports "healed" only when that re-check confirms it.
+
 ## Force Mode
 
 If the user passes `--force` as an argument, skip prerequisite validation with a warning:

package/adapters/claude/skills/forge-6-docs/references/stage-exit-protocol.md

@@ -90,7 +90,7 @@ resolves before running the command, exactly as elsewhere.
 **Close this stage with the Scripted Stage Exit** (contract: `references/stage-exit-protocol.md`; do not improvise a "Next steps" list). Run:
 
 ```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/forge-session.py" stage-exit {stage-exit-args} --specs-dir "{specsDir}" --host claude --verify-capability "{verify-capability}"
 ```
@@ -119,7 +119,12 @@ prose). Nothing else.
 - **(a)** a question mechanism equivalent to `AskUserQuestion` is available, **and**
 - **(b)** a clean-room `forge-verifier` subagent can be dispatched.
 
-If either is absent, or capability cannot be established, pass `manual`.
+If either is absent, or capability cannot be established, pass `manual`. **(a) is rung 1 or
+rung 2** of the Interaction Capability Ladder (`references/shared-conventions.md`); at
+rung 3, (a) is false by definition, so `--verify-capability manual` follows without
+further deliberation — the ladder's "verify-capability determination" class states this
+rung-3 default once
+so it is never re-derived per stage.
 
 **(b) tests PERMISSION, not tool presence.** The question is not "is a subagent-dispatch
 tool listed in my tool surface" but "**may I dispatch `forge-verifier` right now**". A
@@ -420,7 +425,7 @@ a `deferredDecisions[]` entry on this feature's `.pipeline-state.json` by runnin
 epic member — required, per the Pipeline State Protocol in `references/shared-conventions.md`:
 
 ```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/forge-session.py" state-decision \
   --feature "{feature}" --question "<phrased for the target stage>" \
@@ -440,7 +445,17 @@ sentinel `─ forge: end of stage ─`, as the **final line** of `nextSteps`. Pr
 **verbatim as your absolute last output**. Nothing follows the sentinel — no summary, no
 sign-off, no warning, no command result, no acceptance text, no caveat. The block already
 carries the fresh-session recommendation (host-aware wording via `--host`) and the exact
-next command, so trailing prose can only push the user's next action out of view.
+next command — or, at the one terminal state below, the statement that there is none — so
+trailing prose can only push the user's next action out of view.
+
+**A finished epic ends the pipeline, and its block fences nothing.** When
+`primaryCommand` is `null` (`nextCommand` and `nextStage` are `null` too), the epic is
+complete — every member done, or the manifest set to `status: "complete"` — and there is no
+next command at all. Print the block exactly as you would any other; do **not** substitute a
+command, promote `nextCommand`, or append your own "you could now run…" list. The block's own
+prose already names the optional follow-ons (start a new feature, re-open the dashboard to
+inspect state) as inline offers rather than instructions. Re-fencing the epic dashboard here
+is the specific defect this state exists to prevent: running it lands back on this same exit.
 
 **A nested payload** (`terminalOwnedBy: "outer"`) carries `nextSteps: null` and
 `sentinel: null`. It prints **no terminal block at all** — not even an empty one. Return

package/adapters/claude/skills/forge-6-docs/references/verify-state.md

@@ -0,0 +1,98 @@
+# `verify-state` — deterministic upstream-verification classification
+
+`forge-4-backlog`, `forge-5-loop` and `forge-6-docs` each open by reading a served
+stage's `stages.forge-verify-*` entry to answer one question — *has the upstream
+artifact been verified, and what do I say if not?* Each answered it with its own
+hand-rolled branch set: forge-4-backlog a binary verified/not check, forge-5-loop
+four cases, forge-6-docs five. `forge-session.py verify-state` derives that answer
+from the authoritative on-disk entry instead — one case enum, one message table,
+the same "never eyeball the graph" move `select-outcome` makes for the exit outcome
+(issue #277, part of the #265 guard-first program).
+
+The verb reads, never writes. It reads the **raw** `forge-verify-{token}` status the
+gates key on — it does **not** apply the version-aware freshness `verify_state()`
+computes for the navigator's most-recent-stage gate. A `passed` entry classifies
+`passed` regardless of the stage version, because that is exactly what the gates read
+today; layering re-verify-on-revision onto them would be a behaviour change, not an
+additive one.
+
+## Synopsis
+
+```
+python3 forge-session.py verify-state \
+  --feature F --for-stage S [--specs-dir DIR] [--epic E] [--json]
+```
+
+`--for-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`) — the stage whose
+`forge-verify-{token}` entry is classified. `forge-0-epic` (verification lives in
+`.epic-state.json`) and `forge-6-docs` (no verify token) are **out of scope** and
+rejected at parse time.
+
+Output — always `{case, verified, stale, message, nextCommand}`:
+
+```json
+{
+  "case": "findings-applied",
+  "verified": false,
+  "stale": true,
+  "message": "Fixes were applied to auth's forge-4-backlog but nothing re-verified them; re-verification is still outstanding — run /feature-forge:forge-verify auth backlog.",
+  "nextCommand": "/feature-forge:forge-verify auth backlog"
+}
+```
+
+- **`case`** — one `VerifyStateCase`, the union of the cases the three gates spell out.
+- **`verified`** — `true` only for `passed`. An explicit `skipped` is resolved but *not*
+  verified, so it is `false`.
+- **`stale`** — `true` only for `findings-applied`: fixes landed but nothing re-verified
+  them, so a re-verify is still owed.
+- **`message`** — the single canonical operator sentence for the case.
+- **`nextCommand`** — the forge-verify retry for every unresolved case; `null` for
+  `passed`, which needs no action.
+
+## The case enum
+
+`VerifyStateCase` is the union of the raw `forge-verify-*` statuses the three gates
+key on, plus `never` for the absent / `pending` / unrecognized bucket every gate
+folds into "not verified". `tests/test_verify_state.py` pins the enum to the
+enumerating gate bodies, both directions, so a gate cannot grow a seventh case or
+spell an existing one differently.
+
+| `case` | on-disk status | `verified` | `stale` | meaning |
+| --- | --- | :---: | :---: | --- |
+| `passed` | `passed` | ✓ | | verification passed — proceed |
+| `findings-reported` | `findings-reported` | | | blocking findings live and unresolved |
+| `findings-applied` | `findings-applied` | | ✓ | fixes applied, re-verify still owed |
+| `auto-verify-pending` | `auto-verify-pending` | | | scheduled automatic verification, owed but unrun |
+| `skipped` | `skipped` | | | user explicitly proceeded without verifying |
+| `never` | absent / `pending` / unrecognized | | | never verified |
+
+## Classification
+
+The status ordering mirrors `verify_state()` — an explicit `skipped` and recorded
+`auto-verify-pending` debt are tested **before** the generic bucket, so neither can
+fall through to `never`:
+
+1. `skipped` → **skipped**.
+2. `auto-verify-pending` → **auto-verify-pending**. Unusable scheduling metadata
+   (missing/malformed `scheduledStageVersion`) warns once (REQ-DEBT-02) but the debt
+   stays owed — degrading it to `never` is exactly the conflation that requirement
+   forbids.
+3. `findings-reported` → **findings-reported**.
+4. `findings-applied` → **findings-applied**.
+5. `passed` → **passed**.
+6. anything else (absent, `pending`, or an out-of-vocabulary status) → **never**. A
+   present-but-unrecognized status is flagged once (#148) then treated as unverified,
+   the same answer an absent entry gets; a known `pending` (or an absent entry) is
+   quiet.
+
+A missing, unreadable, or torn state file never raises — the entry reads as absent
+and classifies `never`, the same fail-safe the three gates take.
+
+## Messages
+
+`VERIFY_STATE_MESSAGES` holds one canonical sentence per case; the `auto-verify-pending`
+case reuses `AUTO_PENDING_DIAGNOSTIC` — the single normative owed-debt sentence every
+read-side emitter already shares — and appends the revision-advance clause when the
+recorded schedule predates the current artifact. `{subject}` is the feature (or epic
+member), `{stage}` the served production stage, `{command}` the forge-verify retry.