npm - @garygentry/feature-forge - Versions diffs - 0.3.2 → 0.3.5 - Mend

@garygentry/feature-forge 0.3.2 → 0.3.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (389) hide show

package/adapters/pi/skills/forge-guide/references/shared-conventions.md CHANGED Viewed

@@ -36,7 +36,7 @@ I found that the codebase uses React and TanStack Router.
 ### Decision Support: Help the User Choose
-When an `AskUserQuestion` carries substantive options (a real choice — not a trivial yes/no confirmation), do not just list them. The interview stages have already done codebase research and integration analysis; surfacing that synthesis at the decision moment is the whole point. For every such question:
+When a question posed through `AskUserQuestion` carries substantive options (a real choice — not a trivial yes/no confirmation), do not just list them. The interview stages have already done codebase research and integration analysis; surfacing that synthesis at the decision moment is the whole point. For every such question:
 - **Lead with a recommended option.** Place it first and label it `(recommended)` (matching the `AskUserQuestion` "(Recommended)" convention).
 - **Put the trade-off in each option's `description`.** Say why you'd pick it and what you give up versus the alternatives — the cost, not just the benefit.
@@ -53,6 +53,17 @@ 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.
+## 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):
+- **Blocking review (gate).** The stage presents the artifact and collects feedback through `AskUserQuestion`; it does **not** proceed until the user answers, iterating until they confirm. Stages: **forge-1-prd** (Step 5), **forge-2-tech** (Step 6), **forge-3-specs** (Step 6).
+- **Non-blocking review (invitation).** The stage states the artifact is ready and invites adjustments **as a statement, not a question** — and then **proceeds to the next step in the same turn unless the user asks for changes**. The invitation obliges the agent to *continue*: emitting the invitation sentence and stopping treats the non-gate as a gate and strands the stage `in-progress` with its completion step unrun — a defect, not caution. Stage: **forge-4-backlog** (Step 6).
+**Why the shapes differ.** A blocking review guards an artifact whose content was just authored from open-ended interview or synthesis — the user is the only authority on "complete", so the stage must wait. forge-4's backlog is *derived* from specs the user already approved, was planned interactively in its Step 3, and is machine-validated in its Step 5; a second hard gate would re-ask a settled question, and the loop never launches without forge-5-loop's own Step 2d confirmation anyway. The invitation is a courtesy checkpoint, not an approval gate (removed deliberately in #78's consistency sweep).
+A stage that changes shape changes it **in this block first**; the per-stage pointer stays a pointer.
 ## Configuration Reading
 Read `forge.config.json` from the project root. If it doesn't exist, use defaults.
@@ -68,10 +79,10 @@ Extract these config values (use defaults if not present):
 - `branchPerFeature` (default: true)
 - `branchPrefix` (default: `forge/`)
 - `loopIterationMultiplier` (default: `1.5`)
-- `autoInvokeNextStage` (default: `true` — the `/skill:forge` navigator auto-invokes the next stage via the `Skill` tool after the user confirms; `false` keeps copy-paste behavior. Navigator-only.)
+- `autoInvokeNextStage` (default: `true` — the `/skill:forge` navigator auto-invokes the next stage via the host's skill-invocation mechanism after the user confirms; `false` keeps copy-paste behavior. Navigator-only.)
 - `contextWindowTokens` (default: `null` — context window used by the navigator's context-usage check; `null` infers from the session model and falls back to 200000. Set to the model's window, e.g. `1000000` on a 1M model. Navigator-only.)
 - `contextWarnThreshold` (default: `0.7` — fraction of the window past which the navigator recommends a clean session. Navigator-only.)
-- `autoVerify` (default: `false` — when `true`, `forge-verify` runs automatically after a stage completes, no prompt. **In-stage-primary:** the just-completed authoring stage runs it itself, in-session, before the exit block (honoring the verify-before-clear principle). The navigator runs it only as a **catch-up** when verify is still pending (a host that could not dispatch a clean-room subagent, or a stage run before this behavior landed). Either way it runs in a fresh clean-room subagent, so it never needs a `/clear` and costs only a compact digest.)
+- `autoVerify` (default: `false` — when `true`, `forge-verify` runs automatically after a stage completes, no prompt. **In-stage-primary:** the just-completed authoring stage runs it itself, in-session, before the exit block (honoring the verify-before-clear principle). The navigator runs it only as a **catch-up** when verify is still pending (a host that could not dispatch a clean-room subagent, or a stage run before this behavior landed). Either way it runs in a fresh clean-room subagent, so it never needs a `/new` and costs only a compact digest.)
 - `autoVerifyStages` (default: `{}` — per-stage overrides for `autoVerify`, e.g. `{"forge-1-prd": false}`. Effective value = `autoVerifyStages[stage]` if present, else `autoVerify`. Keys are constrained to the five verify-capable stages; a typo is a config error surfaced as `invalidAutoVerifyKeys`. Both the in-stage run and the navigator catch-up read this same effective value.)
 - `autoFix` (default: `false` — when `true`, `forge-fix` is chained after an auto-verify that finds issues — by the in-stage run (primary) or the navigator catch-up — but only when auto-verify is on for that stage AND preconditions hold (zero unresolved decisions, clean tree, passing re-verify); otherwise a digest is surfaced and the gate is presented.)
 - `loopRunner` (optional object — the loop runner to drive; **defaults to rauf** when absent, with every command templated. See `references/forge-config-schema.json` and `references/ralph-loop-contract.md`.)
@@ -81,7 +92,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 'for d in "${FEATURE_FORGE_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>")
@@ -96,7 +107,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 'for d in "${FEATURE_FORGE_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
 ```
@@ -124,16 +135,16 @@ 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 'for d in "${FEATURE_FORGE_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 `AskUserQuestion` tool is available), also ensure the Claude-framed variant:
+If the host is Claude (the Claude-native question tool is available), 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 'for d in "${FEATURE_FORGE_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"
 ```
@@ -153,7 +164,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 'for d in "${FEATURE_FORGE_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
@@ -168,7 +179,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 'for d in "${FEATURE_FORGE_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
 ```
@@ -191,7 +202,7 @@ Pipeline state is written by the `state-*` verbs of `scripts/forge-session.py`
 If a `state-*` verb exits 2, surface the plain `Error:` line from stderr verbatim, do **not** proceed to the next step of the surrounding protocol, and do **not** hand-author the JSON as a workaround. The stage remains resumable because the entry stamp is already on disk — re-run the verb once the cause is fixed.
-**The eight `state-*` verbs.** `state-enter` (Stage-Entry Guard), `state-artifact` (incremental artifact tracking), `state-complete` (Git Commit Protocol), `state-branch` (Branch Setup and Branch Reconciliation), `state-note` (the Immediate Downstream Note below, and the optional completion note at stage closure), `state-decision` (deferred decisions), `state-ecr` (epic change requests), and `state-verify` (one `forge-verify-*` verification transition — below). The `--epic` member requirement and the exit-2 failure protocol above apply to **every** one of them, `state-verify` included; no verify entry is ever hand-authored.
+**The nine `state-*` verbs.** `state-enter` (Stage-Entry Guard), `state-artifact` (incremental artifact tracking), `state-complete` (Git Commit Protocol), `state-skip` (the deliberate forge-6-docs documentation skip — scoped to that one stage; writes `status: "skipped"` + `skippedAt`, refuses to erase a record of docs that exist, and is the only sanctioned writer of a skipped docs stage), `state-branch` (Branch Setup and Branch Reconciliation), `state-note` (the Immediate Downstream Note below, and the optional completion note at stage closure), `state-decision` (deferred decisions), `state-ecr` (epic change requests), and `state-verify` (one `forge-verify-*` verification transition — below). The `--epic` member requirement and the exit-2 failure protocol above apply to **every** one of them, `state-verify` included; no verify entry is ever hand-authored.
 ### `state-verify` — verification results and provenance
@@ -200,7 +211,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 'for d in "${FEATURE_FORGE_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>" \
@@ -210,7 +221,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 'for d in "${FEATURE_FORGE_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}" \
@@ -220,7 +231,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 'for d in "${FEATURE_FORGE_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>" \
@@ -242,7 +253,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 'for d in "${FEATURE_FORGE_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>" \
@@ -286,7 +297,7 @@ Invoke this block at the **very start** of a pipeline entry point — `forge-1-p
 **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 'for d in "${FEATURE_FORGE_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}"
@@ -299,7 +310,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 'for d in "${FEATURE_FORGE_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
 ```
@@ -312,7 +323,7 @@ Act on the emitted `action` (source of truth is where the state actually resolve
 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 'for d in "${FEATURE_FORGE_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}"
@@ -338,7 +349,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 'for d in "${FEATURE_FORGE_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 \
@@ -368,7 +379,7 @@ Invoke this block at the **start of an authoring stage** (`forge-1-prd`..`forge-
 **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 'for d in "${FEATURE_FORGE_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}"
@@ -381,7 +392,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 'for d in "${FEATURE_FORGE_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}"
@@ -395,7 +406,7 @@ Invoke this block **at the head of any post-entry step that writes a stage artif
 1. **Proceed** when `stages.{stage}.status` is `"in-progress"` (this session's Entry Stamp — you are finishing the run you started) or absent/`pending`. Run the write / exit normally.
-2. **Detect-and-refuse** when ALL of these hold: `stages.{stage}.status ∈ {"complete", "stale"}` **AND** the stage's artifacts (incl. `TRACEABILITY.md` for forge-3-specs) exist on disk **AND** a `commitHash` is recorded for the stage **AND** you did **not** author this stage earlier in the current session. This is a stale/replayed continuation of an already-finished, committed stage. Do **not** overwrite the artifact or re-run the exit. Route instead to the **Stage-Entry Guard**'s *Re-authoring* path: surface the same `AskUserQuestion` warning ("A completed {stage} artifact already exists for '{feature}' (v{n}{, marked stale}). Continuing will create a new version. Proceed?"). Only on explicit confirmation re-enter from the Entry Stamp (the version bumps at exit); otherwise **stop** and report that the stage is already complete — cite the recorded `commitHash` and offer `/skill:forge {feature}` to see true state.
+2. **Detect-and-refuse** when ALL of these hold: `stages.{stage}.status ∈ {"complete", "stale"}` **AND** the stage's artifacts (incl. `TRACEABILITY.md` for forge-3-specs) exist on disk **AND** a `commitHash` is recorded for the stage **AND** you did **not** author this stage earlier in the current session. This is a stale/replayed continuation of an already-finished, committed stage. Do **not** overwrite the artifact or re-run the exit. Route instead to the **Stage-Entry Guard**'s *Re-authoring* path: surface the same warning via `AskUserQuestion` ("A completed {stage} artifact already exists for '{feature}' (v{n}{, marked stale}). Continuing will create a new version. Proceed?"). Only on explicit confirmation re-enter from the Entry Stamp (the version bumps at exit); otherwise **stop** and report that the stage is already complete — cite the recorded `commitHash` and offer `/skill:forge {feature}` to see true state.
 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).

package/adapters/pi/skills/forge-verify/SKILL.md CHANGED Viewed

@@ -29,7 +29,7 @@ Pick based on how many checks the mode carries (see the per-mode totals in Step
 - **Small modes (prd 15, tech 17): single verifier.** Use the host's subagent mechanism once with
   `the forge-verifier custom agent`, passing the feature name and mode. It runs all
   checks and returns findings.
-- **Large modes (specs 38, backlog 27, impl 23): parallel dimensioned fan-out.**
+- **Large modes (specs 39, backlog 29, impl 25): parallel dimensioned fan-out.**
   Split the mode's checklist into **dimension groups** and dispatch **one
   `forge-verifier` per group, in parallel — a single message with multiple subagent
   calls** (the `superpowers:dispatching-parallel-agents` pattern). Each instance owns a
@@ -37,14 +37,14 @@ Pick based on how many checks the mode carries (see the per-mode totals in Step
   run concurrently. Suggested groups (map to the category clusters in that mode's own
   checklist file):
   - **specs** (`references/verification-checklists/specs.md`): (1) types/contracts,
-    (2) architecture/layout, (3) cross-reference &
-    traceability, (4) testing strategy, (5) integration.
+    (2) architecture/layout, (3) cross-reference & traceability (owns CHECK-S39),
+    (4) testing strategy, (5) integration.
   - **backlog** (`references/verification-checklists/backlog.md`): (1) item scoping &
     acceptance criteria, (2) dependency/ordering sanity,
-    (3) spec coverage & traceability, (4) schema/enum correctness.
-  - **impl** (`references/verification-checklists/impl.md`): (1) requirement coverage vs specs, (2) integration correctness,
-    (3) testing, (4) code-quality/conventions, (5) runnability (owns CHECK-I21/I22 —
-    the smoke command and the non-test-caller heuristic).
+    (3) spec coverage & traceability (owns CHECK-B29), (4) schema/enum correctness.
+  - **impl** (`references/verification-checklists/impl.md`): (1) requirement coverage vs specs (owns CHECK-I24/I25),
+    (2) integration correctness, (3) testing, (4) code-quality/conventions,
+    (5) runnability (owns CHECK-I21/I22 — the smoke command and the non-test-caller heuristic).
   In each parallel instance's prompt, pass: the feature, the mode, the **dimension
   label**, the **exact CHECK-IDs it owns**, and a note that **it is one of several
@@ -55,8 +55,7 @@ Pick based on how many checks the mode carries (see the per-mode totals in Step
 ### Synthesize (parent session)
-The verifier(s) are read-only — they return findings as their response; **you** (the
-parent) assemble and write the single document to
+The verifier(s) are read-only — they return findings as their response. **Gate every return first** through "Truncated Verifier Returns" in `references/findings-template.md`: a return without the report structure is a dropped digest (issue #183) — resume the agent via `SendMessage` (or re-dispatch), and never synthesize, write a document, or record a verify result from a truncated return. Then **you** (the parent) assemble and write the single document to
 `{resolvedFeatureDir}/.verification/VERIFY-{mode}-{YYYY-MM-DD}.md`. When you fanned out:
 1. Concatenate all instances' findings and **renumber `V-NNN` IDs uniquely** across the
    merged set.
@@ -168,7 +167,7 @@ Load into context ALL artifacts for this feature based on mode:
 Read `references/verification-checklists/{mode}.md` for the detailed checklist for the mode being verified — one of `references/verification-checklists/prd.md`, `references/verification-checklists/tech.md`, `references/verification-checklists/specs.md`, `references/verification-checklists/backlog.md`, `references/verification-checklists/impl.md`, `references/verification-checklists/epic.md`. Read only that mode's file. Execute every check. Do not skip checks because things "look fine." **Exception — a re-verify is scoped, not a fresh sweep:** when the served stage's verify entry is `findings-applied`, follow "Re-verify scope and convergence" in `references/stage-exit-protocol.md` — confirm the prior report's findings against their acceptance evidence and examine the fix's own delta; only an unresolved prior finding or a new blocking defect the fix itself introduced may block, every other observation is advisory, and a finding with a recorded decision is never re-filed. The orchestrator-only **Findings Document Template (Step 4)**, worked **Example Findings (Step 4)**, and **Epic Mode State Write Detail (Step 6)** sections live in `references/findings-template.md`, read later by the parent role at Steps 4/6.
-Each check in that mode checklist has a unique ID (CHECK-P01, CHECK-T01, CHECK-S01, CHECK-B01, etc.). As you execute each check, record its ID and result (pass/fail/not-applicable). After completing all checks, report the total: "Executed N of M checks. Results: X pass, Y fail, Z not-applicable." If your count is significantly below the expected total for the mode (prd: 15 checks, tech: 17 checks, specs: 38 checks, backlog: 27 checks, impl: 23 checks, epic: 10 checks), you likely skipped checks — go back and complete them.
+Each check in that mode checklist has a unique ID (CHECK-P01, CHECK-T01, CHECK-S01, CHECK-B01, etc.). As you execute each check, record its ID and result (pass/fail/not-applicable). After completing all checks, report the total: "Executed N of M checks. Results: X pass, Y fail, Z not-applicable." If your count is significantly below the expected total for the mode (prd: 15 checks, tech: 17 checks, specs: 39 checks, backlog: 29 checks, impl: 25 checks, epic: 10 checks), you likely skipped checks — go back and complete them.
 **Epic mode dispatch.** Epic mode is a small (10-check) checklist, so per the single-vs-parallel rule above, dispatch a **single `forge-verifier`** via the host's subagent mechanism, passing the epic name and `mode=epic`. The verifier runs CHECK-E01..E10 from the `## Epic Mode Checklist` in `references/verification-checklists/epic.md` (E01/E02/E03/E08 are delegated to `epic-manifest.py validate`/`check-name`; E04–E07, E09, and E10 are verifier judgment) and returns its findings.
@@ -183,7 +182,7 @@ Every finding must include:
    **Severity floor (anti-churn).** An inaccuracy confined to comments, docstrings, or test narration — prose no runtime path executes and no decision consumes — caps at `inconsistency`, never `error`. It is worth recording, but a wrong sentence beside correct code does not block a stage the way wrong behavior does. **Routing consequence:** `error` and `gap` are the two **blocking** severities; `inconsistency` and `improvement` are **advisory**. A report with at least one blocking finding records `findings-reported` and routes to forge-fix. A report whose findings are all advisory records `passed` **with the report still attached** (Step 6) and the pipeline advances — an advisory-only report never fences a fix round. A **meta-guard** (a test protecting other tests or prose) is judged against its declared protection set: guard-incompleteness against a declared non-goal is never a finding (`references/stage-exit-protocol.md` § Re-verify scope).
-   **A checklist item with no PRD position behind it is a PRD gap, not a design to invent.** Several checks are deliberately conditional — `CHECK-S27` ("Concurrent access scenarios are addressed **if relevant**") is the clearest, and the same shape appears for performance, observability, and security checks that defer to the PRD. When such a check fires and the PRD takes **no position** on the concern, the finding is that the *requirements* are silent. Report it as an `improvement` (or a `gap` against the PRD, in `prd` mode) whose suggested fix is to **record the position** — including "out of scope, single writer assumed", which is a complete answer. Do **not** specify a mechanism to satisfy the check: a verifier that answers an open requirements question by designing a protocol converts a one-sentence PRD amendment into a foundational change that no requirement asked for, at the stage where it is least visible. Precedent both ways: `epic-orchestration` V-008 raised `CHECK-S27` against a PRD that *had* scoped concurrency out and correctly cost one sentence at `improvement`; `stage-exit-coverage` V-006 raised the same check against a silent PRD, was filed as a `gap`, and induced a full locking protocol that was later removed.
+   **A checklist item with no PRD position behind it is a PRD gap, not a design to invent.** Several checks are deliberately conditional — `CHECK-S27` ("Concurrent access scenarios are addressed **if relevant**") is the clearest, and the same shape appears for performance, observability, and security checks that defer to the PRD. When such a check fires and the PRD takes **no position** on the concern, the finding is that the *requirements* are silent. Report it as an `improvement` (or a `gap` against the PRD, in `prd` mode) whose suggested fix is to **record the position** — including "out of scope, single writer assumed", which is a complete answer. Do **not** specify a mechanism to satisfy the check: a verifier that answers an open requirements question by designing a protocol converts a one-sentence PRD amendment into a foundational change that no requirement asked for, at the stage where it is least visible. Precedent both ways: `epic-orchestration` V-008 raised `CHECK-S27` against a PRD that *had* scoped concurrency out and correctly cost one sentence at `improvement`; `stage-exit-coverage` V-006 raised the same check against a silent PRD, was filed as a `gap`, and induced a full locking protocol that was later removed. For **forge state writes** specifically, the standing owner decision is recorded in `references/decisions/single-writer-threat-model.md` (issue #180): single writer assumed, detection-not-locking — answer `CHECK-S27` by citing it (or the per-feature requirement restating it), never by designing a mechanism.
    Relatedly, **do not let `improvement` fall out of use.** A report containing only `gap`/`error`/`inconsistency` usually means observations that should have been `improvement` were promoted into must-fix findings. If a finding would not block implementation, it is an `improvement` — say so.
 3. Exact location (file + section)

package/adapters/pi/skills/forge-verify/references/decisions/single-writer-threat-model.md ADDED Viewed

@@ -0,0 +1,53 @@
+# Decision: single-writer state model — detection welcome, locking out of scope
+**Decided:** 2026-08-08 · **Issue:** [#180](https://github.com/garygentry/feature-forge/issues/180) · **Owner:** repository owner
+## The decision
+Concurrent multi-session mutation of forge state is **out of scope**. Every forge state
+writer — `forge-session.py` (`.pipeline-state.json`) and `epic-manifest.py`
+(`epic-manifest.json`, `.epic-state.json`) — assumes a **single writer**. Atomicity
+(sibling temp file → flush/fsync → `os.replace`) protects against an *interrupted* write;
+it is not, and is not intended to be, mutual exclusion between simultaneous writers.
+The standing posture is **detection, not locking**:
+- **No locking mechanism will be added on the authority of a verification finding or a
+  single feature's spec.** If concurrent multi-session use ever becomes a supported
+  workflow, that is a product decision needing its own PRD — and a state lock alone would
+  be false comfort, because git operations, the two-commit provenance protocol, and
+  adapter regeneration are equally unsynchronized.
+- **Cheap, opportunistic detection is welcome if someone proposes it** — e.g. an
+  epic-root writer re-reading and failing loudly on an unexpected `revision` before
+  `os.replace`. It is an explicitly optional hardening, not a requirement, and nothing is
+  scheduled.
+## Accepted residual risk
+Everything in-session is sequential, and member `.pipeline-state.json` files are
+disjoint. The one real exposure: two sessions working **different members of one epic**
+share two epic-root files, `epic-manifest.json` and `.epic-state.json`. A lost
+read-modify-write increment of the manifest's `revision` can leave it unchanged after a
+semantic mutation landed, and the freshness comparison then classifies a **stale epic
+verification as `fresh`** — a correctness consequence, not just a lost edit.
+This is **accepted and documented**, not mitigated. Anyone who hits it has this document
+to cite; do not run two concurrent sessions against members of the same epic.
+## What this means for verification (CHECK-S27)
+When `CHECK-S27` ("Concurrent access scenarios are addressed if relevant") fires against
+forge state writes, the answer is a **citation, not a design**: cite this document (or
+the per-feature requirement restating it, e.g. `stage-exit-coverage` `REQ-REL-04`,
+`epic-orchestration` `REQ-ROBUST-03`). A PRD silent on concurrency gets a one-sentence
+position recorded; a verifier must never answer the silence by specifying a mechanism.
+## Provenance
+Both precedents ran the same check; the only variable was whether the PRD had a position:
+- `stage-exit-coverage` V-006 raised CHECK-S27 against a silent PRD, was filed as a
+  `gap`, and induced a ~140-line portable lock protocol answering no requirement. It was
+  removed (`302c93f`), and the PRD now records the position as `REQ-REL-04`.
+- `epic-orchestration` V-008 raised the same check against a PRD that had scoped
+  concurrency out (`REQ-ROBUST-03`), was filed as an `improvement`, and cost one sentence.

package/adapters/pi/skills/forge-verify/references/findings-template.md CHANGED Viewed

@@ -2,6 +2,36 @@
 Loaded by the **parent orchestrator** role of `forge-verify` at Step 4 (write the findings document) and Step 6 (epic-mode state write). The `forge-verifier` leaf subagent MUST NOT load this file — it holds only orchestrator-facing material (see `SKILL.md` → "Which role are you?").
+## Truncated Verifier Returns (Synthesize gate)
+The host's subagent mechanism hands the parent **only the verifier's final message**. A verifier that
+ends its run on a status line instead of the report returns *that line* as the entire
+result — the digest it built exists in its transcript but never reaches you. Observed
+in the wild (issue #183): two ~130k-token, 40+-tool-call runs each returned a single
+plausible-sounding opening sentence ("I'll start by loading the pipeline state…") while
+the recovered digest contained two BLOCKER findings. The failure is quiet precisely
+because the returned line reads like progress, not like an error.
+**Gate every verifier return before using it.** A return is a **non-answer** when it
+lacks the report structure — no `# Verification Report:` header, no `## Findings`
+section, no `Checks Executed:` line (for a skeptic dispatch: no per-finding
+CONFIRMED/REFUTED verdicts). Length is the tell: a real report is rarely under ~20
+lines; a one-or-two-sentence return from a run that did real work is a dropped digest,
+not a clean result.
+On a non-answer:
+1. **Resume, don't re-run.** `SendMessage` to the returned agent id: *"Your run ended
+   without returning the report. Return your FINAL report now, from the work you
+   already did, in the Output Format — your final message is the only thing I
+   receive."* The agent replays from its transcript and typically returns the full
+   digest with zero further tool calls.
+2. **Re-dispatch** the same prompt only if the resume also fails or the id is gone.
+3. **Never** synthesize findings from a truncated return, write a findings document
+   around it, record a verify result (`state-verify`) from it, or present it to the
+   user as the verification outcome. A gate decision made on a dropped digest is the
+   #183 failure mode: BLOCKER findings silently converted into a pass.
 ## Findings Document Template (Step 4)
 Write findings to `{specsDir}/{feature}/.verification/VERIFY-{mode}-{YYYY-MM-DD}.md`
@@ -115,7 +145,7 @@ This is the one `state-*` call site where the member `--epic` rule does **not**
 version — which is what keeps the result reading fresh rather than stale.
 ```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 'for d in "${FEATURE_FORGE_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 \