@garygentry/feature-forge 0.3.5 → 0.3.7

package/adapters/cursor/references/verifier-patterns/pattern_spec_literals_are_claims.md

@@ -0,0 +1,45 @@
+---
+name: pattern-spec-literals-are-claims
+description: Every module id, file path, constant and signature written into a spec is a checkable claim about the repo — verify them mechanically, they survive multiple verify rounds otherwise
+metadata:
+  type: reference
+---
+
+Treat every literal a spec writes down as an assertion about the current repository and
+check it against the filesystem, not against the spec's own prose.
+
+**Why:** specs quote "exact existing signatures" and author code constants (allow-lists,
+fixture inventories, helper additions) inline. These read as authoritative and reviewers
+pattern-match them as correct, so a phantom id or a dropped member survives round after
+round untouched. The failure is silent: nothing executes a spec's prose.
+
+**How to apply** (cheap, mechanical, do it every round):
+
+- Module/skill ids in a spec constant → list the real directory and diff the sets both
+  directions. Missing-from-spec and absent-from-repo are different bugs; report both.
+- Quoted "exact current signature" blocks → `grep -n -A12 'def <name>' <file>` for each.
+  When these are usually accurate in a repo, a mismatch is high-signal.
+- Cited file paths (fixtures, tests, references, data) → loop them through `[ -e "$p" ]`.
+  Fast, and it catches placeholder paths a fix pass left behind.
+- Cross-document `<file> §N` citations → script it: build a heading index per file, regex
+  the citations, report misses. Never eyeball, especially after a section was deleted or
+  renumbered.
+- Requirement-id tokens in a coverage table → diff the families against the source doc.
+  Range citations (`REQ-EXIT-01..07`) and pseudo-rows are where phantom and dropped IDs
+  hide.
+- Prose claims about existing behavior ("the field is a single string", "the file is 302
+  lines") → verify. When they are usually correct, the occasional wrong one gets waved
+  through — which is exactly why to check.
+- **A spec's *correction* of an upstream figure is itself an unverified claim — re-derive
+  it, do not credit it.** A supersession arrives framed as research ("exhaustive search
+  found N"), and that framing buys it a pass. Re-derive each superseding number from the
+  files; the correct ones cost seconds and a wrong one is blocking.
+- **Cited *line ranges* into another file drift as a set, not as a number.** "Amend the
+  bullets (lines 43–48)" plus an enumeration of three constructs is two claims; the range
+  is usually copied verbatim from the finding that proposed it, so a wrong range
+  propagates report → spec → implementer. `grep -n` the first token of each named
+  construct and confirm the span contains all of them.
+- **Line-count claims: know what the checker counts.** A body-size gate that measures
+  lines *after* frontmatter disagrees with a raw `wc -l` by the frontmatter block. When a
+  spec's size claim and a passing gate disagree, go read the checker's measurement
+  function before believing either.

package/adapters/cursor/references/verifier-patterns/pattern_stale_counts_after_split.md

@@ -0,0 +1,36 @@
+---
+name: pattern-stale-counts-after-split
+description: Splitting a construct N ways leaves the old number words ("two", "three", "both") scattered through banners, docstrings and prose — grep the number words after any arity change
+metadata:
+  type: reference
+---
+
+When a construct is split — one function into three, two checks into five, "both callers"
+into "all three" — the code is updated and the **number words describing it are not**. They
+survive in module banners, docstrings, comment headers, error messages, and prose that
+narrates the old shape. Nothing fails: the count is not executable, so no test observes it,
+and the reader is told the wrong arity by a file that otherwise looks authoritative.
+
+**Why it survives review:** a diff shows the new Nth item being *added* and gives no signal
+about the sentences elsewhere that quantified the old set. The reviewer checks the new
+member is correct — which it is. The stale count sits in a file the diff never touches.
+
+**How to apply.** After any arity change:
+
+1. **Grep the number words, not the identifiers:**
+   `\b(one|two|three|four|five|both|either|neither)\b` across the changed construct's own
+   file *and* every file that cites it. `both` and `neither` are the highest-yield needles
+   — they are only correct at exactly two and break silently at three.
+2. **Include the prose surfaces a code grep misses:** module docstrings, comment
+   annotations, assertion messages, reference markdown, skill bodies, and changelog entries
+   that described the old shape.
+3. **Re-read the sentence, do not pattern-match it.** "The two callers" may have become
+   "the two callers and the initializer", which is grammatical, cites three things, and
+   still says two.
+4. A count in an **error message** is worse than one in a docstring: it is read at the
+   moment someone is already confused, and it is quoted into issues.
+
+**Sibling shapes:** [[pattern-sibling-docstring-sweep]] (mirroring a rule into N places
+amends exactly one docstring) and [[pattern-test-count-units]] (a "N tests" claim means
+pytest-collected, not `def` count). All three are the same failure: a number that
+describes code, written in prose, with nothing to keep the two in step.

package/adapters/cursor/references/verifier-patterns/pattern_test_count_units.md

@@ -0,0 +1,20 @@
+---
+name: pattern-test-count-units
+description: A spec's "N tests" claim means pytest-COLLECTED tests, not def count — always --collect-only before calling it wrong
+metadata:
+  type: reference
+---
+
+When an artifact claims a test-file size ("43 tests, 651 lines", "67 mutation
+controls"), resolve the unit with `pytest <file> --collect-only -q` before filing an
+accuracy finding. Parameterization makes `grep -c "def test_"` wildly lower than the
+collected count — a single `@pytest.mark.parametrize` function can collect dozens.
+
+**Why:** grep count and collected count are different units, and a spec that is exactly
+right in the collected unit looks wrong under a naive `def` grep. Filing that is a pure
+false positive, and it burns a fix round on churn the artifact never needed.
+
+**How to apply:** If a spec states a baseline in one unit and a *target* in the other
+("43 tests" → "at most 5 tests"), that unit ambiguity is itself the finding — file it as
+an `improvement` asking for the counting unit to be named, not as a factual `error`.
+See [[pattern-spec-literals-are-claims]].

package/adapters/cursor/references/verifier-patterns/pattern_vacuous_self_reading_tests.md

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

package/adapters/cursor/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 forge-verify auth backlog.",
+  "nextCommand": "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.

package/adapters/cursor/scripts/forge-bootstrap.py

@@ -642,7 +642,28 @@ def _compose_agent_file(answers: Answers, filename: str) -> str:
 
 
 def write_hygiene(answers: Answers, target: Path, sentinel: Sentinel) -> None:
-    """Emit README, LICENSE, and the host agent-instruction file(s) (02 §4.5)."""
+    """Emit README, LICENSE, and the host agent-instruction file(s) (02 §4.5).
+
+    Interop with ``forge-init``'s root hygiene step
+    (``references/shared-conventions.md`` § "Root Hygiene (Tooling Feedback)"), which
+    writes the same "Tooling feedback" section into a root ``AGENTS.md``/``CLAUDE.md``.
+    The two writers cannot duplicate each other, but NOT because of the guard below:
+    a target that ``forge-init`` has touched holds ``forge.config.json`` (and possibly
+    ``AGENTS.md``), neither of which ``ALLOWED_META_FILE_RE`` permits, so ``check()``
+    reports ``eligible: false`` and the greenfield gate refuses the whole bootstrap run
+    before ``scaffold()`` is reached. In the other direction it is ``forge-init``'s own
+    shell ``[ -f … ] ||`` guard that protects this file. ``_write_artifact``'s
+    never-overwrite guard is load-bearing here only for an interrupted-bootstrap resume
+    (REQ-LIFE-02) — worth knowing, since the obvious reading of "never overwrites" is
+    that it is what makes the two writers safe together, and it is not.
+
+    On that one resume path the skip has a cost worth stating: forge-init's template is
+    a stub carrying only the "Tooling feedback" section, so keeping it means the project
+    never receives the rest of THIS template — Project Purpose, Getting Started,
+    Conventions, and "Specs are pre-implementation". Keeping the user's file is still
+    the right call (it is not ours to overwrite), but the two files are not equivalent
+    and the block is a subset, not a superset.
+    """
     _write_artifact(target, "README.md", _compose_readme(answers), sentinel)
     if answers["license"] != "none":
         _write_artifact(target, "LICENSE", _compose_license(answers), sentinel)
@@ -806,7 +827,7 @@ def verify(target: Path, answers: Answers) -> VerifyResult:
     return {"toolchainPresent": True, "lint": lint, "test": test, "green": green}
 
 
-#: mirrors ``load_json_with_duplicates``/``warn_duplicate_keys`` in scripts/forge-session.py
+#: mirrors ``load_json_with_duplicates``/``warn_duplicate_keys`` in scripts/forge_session/_common.py
 def load_json_with_duplicates(path: Path) -> tuple[object, list[str]]:
     """Load JSON with last-key-wins values and ordered duplicate key names.
 

package/adapters/cursor/scripts/forge-root.sh

@@ -12,6 +12,44 @@
 # generator (REQ-RES-05); keep it dependency-free beyond POSIX/Bash + the sentinel files.
 set -euo pipefail
 
+# ── Explain mode (#323; consumed only by doctor — the no-arg stdout contract is unchanged). ──
+# `--explain` prints `channel<TAB>path` for the resolved root instead of the bare path;
+# `--explain --all` prints one `channel<TAB>path` line for EVERY candidate root probed (complete
+# or degraded) WITHOUT stopping at the first, so doctor can enumerate every install on the host.
+# No args → the historic bare-path-to-stdout contract, byte-for-byte.
+EXPLAIN=0
+EXPLAIN_ALL=0
+if [ "${1:-}" = "--explain" ]; then
+  EXPLAIN=1
+  [ "${2:-}" = "--all" ] && EXPLAIN_ALL=1
+fi
+
+# Print a resolved root: `channel<TAB>path` under --explain, else the bare path (the contract
+# every prelude fence and tests/test_forge_root.py depend on).
+emit_root() {  # $1 = channel, $2 = path
+  if [ "$EXPLAIN" -eq 1 ]; then
+    printf '%s\t%s\n' "$1" "$2"
+  else
+    printf '%s\n' "$2"
+  fi
+}
+
+# Classify a resolved path to its install channel — used only by the discovery probe, whose
+# fixed candidate list mixes every agent's layout. The explicit steps pass their own channel.
+classify_channel() {  # $1 = path
+  case "$1" in
+    *"/.claude/plugins/cache/"*) printf 'marketplace-cache' ;;
+    *"/.claude/plugins/"*)       printf 'plugins-dir' ;;
+    *"/.claude/skills/"*)        printf 'skills-dir' ;;
+    *"/.agents/skills/"*)        printf 'agents-skills' ;;
+    *"/.pi"*)                    printf 'pi-dir' ;;
+    *"/.cursor/"*)               printf 'cursor-dir' ;;
+    *"/.gemini/"*)               printf 'gemini-dir' ;;
+    *"/.github/"*)               printf 'copilot-dir' ;;
+    *)                           printf 'discovery' ;;
+  esac
+}
+
 # Sentinel predicate (00-core-definitions.md §2 / SENTINEL_FILES). A directory is a valid
 # feature-forge root iff it carries the neutral bundle sentinel `.feature-forge-bundle.json`
 # (emitted into EVERY per-agent adapter bundle) OR the legacy Claude plugin manifest
@@ -33,12 +71,30 @@ CORE_ASSETS=(
   "references/stage-exit-protocol.md"
 )
 
+# scripts/forge-session.py is a thin shim that imports the sibling scripts/forge_session/
+# package (#279); a bundle that ships the shim but not the package cannot run the CLI, so
+# the package is part of a COMPLETE install. It is enforced only when the shipped
+# forge-session.py is ACTUALLY the shim (its body references `forge_session`): a legacy
+# self-contained forge-session.py that predates the split has no such package and must not
+# be spuriously flagged. This marker file proves the package dir shipped alongside the shim.
+PACKAGE_MARKER="scripts/forge_session/__init__.py"
+
+# Precise proxy for "this forge-session.py actually imports the forge_session package" — an
+# `import forge_session` / `from forge_session… import` STATEMENT at line start (leading
+# whitespace allowed). Anchoring to the statement avoids a bare token match (a comment or an
+# unrelated symbol mentioning `forge_session`) firing the package requirement, and a real
+# import line always satisfies it.
+SHIM_IMPORT_RE='^[[:space:]]*(from|import)[[:space:]]+forge_session([._[:space:]]|$)'
+
 # Echo the first missing core asset (relative path) for $1, or nothing when complete.
 first_missing_asset() {  # $1 = candidate dir
   local a
   for a in "${CORE_ASSETS[@]}"; do
     [ -f "$1/$a" ] || { printf '%s' "$a"; return 0; }
   done
+  if grep -qE "$SHIM_IMPORT_RE" "$1/scripts/forge-session.py" 2>/dev/null; then
+    [ -f "$1/$PACKAGE_MARKER" ] || { printf '%s' "$PACKAGE_MARKER"; return 0; }
+  fi
 }
 
 # A sentinel-bearing candidate that lacks a core asset is remembered here (first one wins)
@@ -47,16 +103,22 @@ first_missing_asset() {  # $1 = candidate dir
 partial_root=""
 partial_missing=""
 
-# Given a candidate that already passed is_root: print + exit 0 if it is complete; otherwise
+# Given a candidate that already passed is_root: emit + exit 0 if it is complete; otherwise
 # record it as the degraded fallback and return so probing continues. Always returns 0 on the
-# fall-through path so `set -e` never aborts the resolver on a partial candidate.
-accept_root() {  # $1 = candidate dir (already is_root)
-  local miss
+# fall-through path so `set -e` never aborts the resolver on a partial candidate. Under
+# --explain --all it emits every candidate (tagged) and never exits, for enumeration.
+accept_root() {  # $1 = candidate dir (already is_root); $2 = channel ("auto" → classify by path)
+  local miss channel
+  channel="$2"
+  [ "$channel" = "auto" ] && channel="$(classify_channel "$1")"
   miss="$(first_missing_asset "$1")"
   if [ -z "$miss" ]; then
-    printf '%s\n' "$1"
-    exit 0
+    emit_root "$channel" "$1"
+    [ "$EXPLAIN_ALL" -eq 1 ] || exit 0
+    return 0
   fi
+  # Degraded candidate: --all reports it tagged so doctor sees the full picture.
+  [ "$EXPLAIN_ALL" -eq 1 ] && emit_root "${channel}(degraded)" "$1"
   if [ -z "$partial_root" ]; then
     partial_root="$1"
     partial_missing="$miss"
@@ -64,13 +126,34 @@ accept_root() {  # $1 = candidate dir (already is_root)
   return 0
 }
 
+# ── Step 0: explicit operator override — FEATURE_FORGE_ROOT is authoritative (#323). ────────
+# A set value MUST resolve here or fail loudly; it never silently falls back to discovery, so a
+# dev-override pointing at the wrong/absent bundle is an actionable error rather than a surprise
+# run of some other install on a multi-install host. (CLAUDE_PLUGIN_ROOT is a host-set fact, not
+# an operator override, so it stays in Step 3.) --explain --all only enumerates, so it neither
+# exits nor fails here.
+if [ -n "${FEATURE_FORGE_ROOT:-}" ]; then
+  if is_root "$FEATURE_FORGE_ROOT"; then
+    accept_root "$FEATURE_FORGE_ROOT" "FEATURE_FORGE_ROOT"
+    # accept_root exited 0 on a complete override. Reaching here means it is DEGRADED (or we are
+    # enumerating): a set-but-incomplete override fails loudly, never falls back.
+    if [ "$EXPLAIN_ALL" -ne 1 ]; then
+      echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT is a degraded install (missing $partial_missing) — reinstall/update it, or unset FEATURE_FORGE_ROOT to fall back to discovery." >&2
+      exit 1
+    fi
+  elif [ "$EXPLAIN_ALL" -ne 1 ]; then
+    echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT is not a feature-forge root (no .feature-forge-bundle.json or .claude-plugin/plugin.json) — fix or unset it; discovery is skipped for an explicit override." >&2
+    exit 1
+  fi
+fi
+
 # ── Step 1: self-location — parent of this script's dir is the install root. ─────────────
 # This is the PRIMARY path: a bundle ships its own scripts/forge-root.sh, so the parent of
 # this script's dir is that bundle's root under any agent's layout.
 self_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
 root="$(cd -- "$self_dir/.." && pwd -P)"
 if is_root "$root"; then
-  accept_root "$root"
+  accept_root "$root" "self-location"
 fi
 
 # ── Step 2a: Claude marketplace-cache installs — ~/.claude/plugins/cache/<mp>/<plugin>/<ver>/.
@@ -84,7 +167,7 @@ fi
 while IFS= read -r manifest; do
   candidate="${manifest%/.claude-plugin/plugin.json}"
   if is_root "$candidate"; then
-    accept_root "$candidate"
+    accept_root "$candidate" "auto"
   fi
 done < <(ls -t "$HOME"/.claude/plugins/cache/*/feature-forge/*/.claude-plugin/plugin.json 2>/dev/null || true)
 
@@ -105,7 +188,7 @@ if [ -n "${PI_CODING_AGENT_DIR:-}" ]; then
     "$PI_CODING_AGENT_DIR"/node_modules/@garygentry/feature-forge/adapters/pi \
   ; do
     if is_root "$candidate"; then
-      accept_root "$candidate"
+      accept_root "$candidate" "auto"
     fi
   done
 fi
@@ -137,7 +220,7 @@ for candidate in \
   "$PWD"/.pi/node_modules/@garygentry/feature-forge/adapters/pi \
 ; do
   if is_root "$candidate"; then
-    accept_root "$candidate"
+    accept_root "$candidate" "auto"
   fi
 done
 
@@ -150,7 +233,7 @@ probe_dir="$PWD"
 while :; do
   candidate="$probe_dir/.pi/skills/feature-forge"
   if is_root "$candidate"; then
-    accept_root "$candidate"
+    accept_root "$candidate" "auto"
   fi
   [ "$probe_dir" = "/" ] && break
   next_probe_dir="$(dirname -- "$probe_dir")"
@@ -158,19 +241,19 @@ while :; do
   probe_dir="$next_probe_dir"
 done
 
-# ── Step 3: env fallback — neutral FEATURE_FORGE_ROOT, then the legacy CLAUDE_PLUGIN_ROOT. ─
-# The neutral override works for every agent; CLAUDE_PLUGIN_ROOT is kept only for backwards
-# compatibility with existing Claude installs (C-4).
-if [ -n "${FEATURE_FORGE_ROOT:-}" ] && is_root "$FEATURE_FORGE_ROOT"; then
-  accept_root "$FEATURE_FORGE_ROOT"
-fi
+# ── Step 3: legacy env fallback — CLAUDE_PLUGIN_ROOT. ────────────────────────────────────
+# The neutral FEATURE_FORGE_ROOT override is handled authoritatively in Step 0 (#323).
+# CLAUDE_PLUGIN_ROOT is a host-set fact (Claude exports it), NOT an operator override, so it
+# stays here as a last discovery hint — kept only for backwards compatibility with existing
+# Claude installs (C-4).
 if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && is_root "$CLAUDE_PLUGIN_ROOT"; then
-  accept_root "$CLAUDE_PLUGIN_ROOT"
+  accept_root "$CLAUDE_PLUGIN_ROOT" "CLAUDE_PLUGIN_ROOT"
 fi
 
-# ── Step 4: failure. A sentinel-bearing but asset-incomplete root found along the way is a
-# DEGRADED install (#152) — report it distinctly and actionably rather than the generic
-# cannot-locate message, so the operator knows to reinstall/update rather than reconfigure. ─
+# ── Step 4: failure (or, under --explain --all, the end of enumeration). A sentinel-bearing but
+# asset-incomplete root found along the way is a DEGRADED install (#152) — report it distinctly
+# and actionably rather than the generic cannot-locate message. ─
+[ "$EXPLAIN_ALL" -eq 1 ] && exit 0  # --all printed every candidate; it is diagnostic, never a failure
 if [ -n "$partial_root" ]; then
   echo "feature-forge: install incomplete/degraded at $partial_root (missing $partial_missing) — reinstall with 'npx @garygentry/feature-forge' (or 'feature-forge update' for a stale install)." >&2
   exit 1