@garygentry/feature-forge 0.3.6 → 0.3.7

package/adapters/claude/skills/forge-guide/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
 
@@ -211,7 +334,7 @@ If a `state-*` verb exits 2, surface the plain `Error:` line from stderr verbati
 **`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-guide/references/stack-resolution.md

@@ -50,5 +50,5 @@ Stack detection happens during **forge-2-tech** (the technical specification sta
 If `forge.config.json` has no `stack` field and forge-2-tech hasn't run yet (e.g., when using `--force`), skills should:
 
 1. Attempt basic detection from project files (look for manifest files)
-2. Use `_generic.md` as fallback
+2. Use `stacks/_generic.md` as fallback
 3. Note in the pipeline state that stack detection was skipped

package/adapters/claude/skills/forge-init/SKILL.md

@@ -2,6 +2,7 @@
 # GENERATED — DO NOT EDIT. Source: skills/forge-init/SKILL.md. Regenerate: python3 scripts/build-adapters.py
 name: forge-init
 description: Initialize feature-forge configuration in the current project. Use when user runs /feature-forge:forge-init or asks to set up forge for the first time. Creates forge.config.json with defaults. Do NOT trigger for general project initialization or setup tasks outside the forge pipeline.
+disable-model-invocation: true
 ---
 
 # Initialize Feature Forge
@@ -9,7 +10,7 @@ description: Initialize feature-forge configuration in the current project. Use
 Run the initialization script to create `forge.config.json` with default settings:
 
 ```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; }
 bash "$R/scripts/forge-init.sh"
 ```
@@ -39,7 +40,7 @@ The template writes `autoVerify: false`. After the config is created (and only w
 actually created it — skip this if it reported the file already exists), offer to turn
 auto-verify on, then write the choice back into `forge.config.json`.
 
-If the `AskUserQuestion` tool is available, ask exactly one question:
+If the `AskUserQuestion` is available, ask exactly one question:
 
 > **Enable auto-verify?** Verification runs in a clean-room subagent in-stage after each
 > authoring stage completes — in the same session, before the exit block, so any fix
@@ -52,10 +53,60 @@ Options: **Enable (recommended)** / **Leave off**.
   `forge.config.json` in place, preserving formatting and every other key.
 - On **Leave off**: leave the config as written (`autoVerify: false`).
 
-If the host lacks a structured question tool but can still prompt the user (e.g. Codex asks in
-plain text), use that — ask the one question directly and wait for the reply; it is the same
-choice, just rendered differently. Only when the host has **no** way to ask at all (a fully
-non-interactive / headless run) do you skip the prompt: leave `autoVerify: false` and print the
-one-line note `Set "autoVerify": true in forge.config.json to verify automatically after each stage.`
+This is the run's **first question**, so determine your rung before asking it, per the
+Interaction Capability Ladder (`references/shared-conventions.md`) — **read** the rung from
+`doctor`'s `interaction-mode` record as that section directs; never judge it from your own tool
+surface, which cannot see whether anyone is there to answer:
+
+```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
+```
+
+At rung 1 or 2, ask (structured tool, or the same choice in plain prose — then wait for the
+reply). At rung 3 this question's declared default is the no-write / no-proceed option — skip the
+prompt, leave `autoVerify: false`, state the rung-3 default taken, and print the one-line note
+`Set "autoVerify": true in forge.config.json to verify automatically after each stage.` — then
+**continue with the steps below**; declining this edit never ends the skill. The same rung governs
+every remaining step: never emit a question a rung-3 run cannot answer.
+
+## Preflight the install
+
+Once the config exists, check the tooling this project's pipeline will lean on:
+
+```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 root-version-skew --check gh-available
+```
+
+Follow `references/preflight-and-self-heal.md` with that result: all `ok`/`na` → say nothing and
+move on. Otherwise cluster and report. **Neither check is a stop for `forge-init`** — report and
+continue; a `warn` here never aborts initialization (the procedure returns statuses; the caller
+owns its own gate). `gh-available` matters because the tooling-feedback step below tells agents
+to file issues with `gh issue create`; when `gh` is missing or unauthenticated, say so once — its
+remedies are `global-install`/`network`, so they are **advise-only** and nothing is executed. It
+is **one informational line, never a prompt**: `gh` is optional (every stage degrades to manual
+steps without it), and this check cannot return `na`, so a machine without `gh` must not be
+interrogated about it on every init.
+`root-version-skew` is reported the same way: a second install shadowing this one is worth
+knowing about before the first stage runs.
+
+(`plugin-root` is deliberately **not** in that list. The prelude above already exits 1 when the
+resolver fails, so by the time `doctor` runs the check can only be `ok` — narrowing to checks
+that cannot fire would be theatre.)
+
+## Root hygiene — tooling feedback
+
+Offer the project-root **Tooling feedback** section, per `references/shared-conventions.md`
+§ Root Hygiene (Tooling Feedback) — that block owns the protocol text, the copy commands, the
+three-case analysis, and the never-overwrite rule; do not restate them here. In short: decide
+which variants are **missing** first, ask once as a `local-write` only for those, and stay silent
+about a file that already carries the section. `AGENTS.md` always; `CLAUDE.md` only on Claude,
+read from the bundle's own `agent` field — never from tool availability. **At rung 3 this step
+writes nothing and says so** (that block's declared default). This is what makes the `specs/`
+hygiene files' "see the project-root `AGENTS.md`" pointer resolve.
 
 After initialization, start the pipeline with `/feature-forge:forge-1-prd <feature-name>`.