@garygentry/feature-forge 0.3.6 → 0.3.8

package/adapters/gemini/skills/forge-verify/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/pi/.feature-forge-bundle.json

@@ -1,6 +1,6 @@
 {
   "name": "feature-forge",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "agent": "pi",
   "generatedBy": "python3 scripts/build-adapters.py"
 }

package/adapters/pi/agents/forge-verifier.md

@@ -28,10 +28,11 @@ You have READ-ONLY access. You cannot and should not modify any files. Your outp
 ## How You Work
 
 1. Read the pipeline state file to understand what stage the feature is at
-2. Load all relevant artifacts for the current verification mode
-3. Read **only your dispatched mode's checklist** — `references/verification-checklists/{mode}.md` (the parent's dispatch prompt names your `{mode}`) — and execute every check in it. Do **not** read the other five mode files or `references/findings-template.md`; those are for other modes and for the parent orchestrator respectively.
-4. Return structured findings as your response in the Output Format specified below
-5. Generate a fix plan suitable for a fresh agent to execute
+2. Read the shipped verifier-patterns index — `references/verifier-patterns/MEMORY.md` — and open the patterns your dispatched mode makes relevant. These are the versioned, reviewed heuristics that ship with the pipeline (see "Using Your Memory" for how they relate to your per-project memory).
+3. Load all relevant artifacts for the current verification mode
+4. Read **only your dispatched mode's checklist** — `references/verification-checklists/{mode}.md` (the parent's dispatch prompt names your `{mode}`) — and execute every check in it. Do **not** read the other five mode files or `references/findings-template.md`; those are for other modes and for the parent orchestrator respectively.
+5. Return structured findings as your response in the Output Format specified below
+6. Generate a fix plan suitable for a fresh agent to execute
 
 ## Scoped / Parallel Operation
 
@@ -47,7 +48,17 @@ For large spec suites (>8 documents), process verification in phases: load share
 
 ## Using Your Memory
 
-You have persistent memory in your `MEMORY.md` file. Use it to track:
+You draw on two distinct layers, and they must not be confused:
+
+- **Shipped verifier patterns** (`references/verifier-patterns/`) — versioned, reviewed
+  heuristics that ship with the pipeline to every project. Read the index
+  (`references/verifier-patterns/MEMORY.md`) on start. **Treat these as read-only** — they
+  are canon, not your scratch memory; a genuinely new, general heuristic worth shipping is
+  a change proposed in review, not something you write here at run time.
+- **Per-project memory** (`memory: project`, below) — your own accumulating notes about
+  *this* project's specific blind spots, conventions, and confirmed false positives.
+
+You have persistent per-project memory in your `MEMORY.md` file. Use it to track:
 
 - **Recurring patterns**: If you keep finding the same type of gap across features, note it. Over time you'll learn this project's blind spots.
 - **Project conventions**: As you review more specs, capture conventions that should be consistent (naming patterns, error handling approaches, test strategies).

package/adapters/pi/extensions/forge-invocation-args/README.md

@@ -0,0 +1,106 @@
+# forge-invocation-args (Pi compatibility extension)
+
+First-party feature-forge extension that deterministically preserves the arguments
+supplied to `/skill:forge-*` commands on the Pi host. Fixes
+[issue #303](https://github.com/garygentry/feature-forge/issues/303).
+
+## The problem it works around
+
+Pi expands `/skill:<name> <args>` by appending the raw argument string after the
+skill body. Pi's documentation says arguments arrive as `User: <args>`, but the
+implementation appends them with only a bare `\n\n` separator and **no semantic
+boundary**:
+
+```text
+</skill>
+
+rendered-model-v2
+```
+
+So `/skill:forge-1-prd rendered-model-v2` reaches the model with the feature name
+as unlabeled trailing text. A model can read it as metadata or unrelated prose and
+wrongly trigger feature-forge's canonical "no feature name → STOP and ask" rule
+(`references/shared-conventions.md` § Feature Name Requirement). Because the feature
+name keys **directory resolution**, **branch naming**, and every
+**`.pipeline-state.json`** write, losing it silently is high-impact — not cosmetic.
+
+This is an upstream Pi implementation/documentation mismatch:
+
+- Prior to Pi commit `7868b25a2` (*"make skill invocation messages collapsible"*),
+  expansion used `` `${skillMessage}\n\n---\n\nUser: ${args}` ``.
+- That commit changed it to `` `${skillBlock}\n\n${args}` `` — dropping the `User:`
+  boundary.
+- The behavior began in Pi **v0.50.0** and is still present in
+  `@earendil-works/pi-coding-agent` **0.84.4** (the version this adapter builds
+  against) and **0.85.1** (latest tested).
+
+Restoring `User:` upstream would fix today's formatting, but feature-forge should
+not depend on model inference of an undocumented prompt layout. This extension is
+host-compatibility hardening that remains useful even after an upstream fix.
+
+## How it works
+
+Pi's `input` event fires **before** skill/template expansion (and after
+extension-command dispatch; `/skill:` is not an extension command, so it reaches
+us). The extension registers one `input` handler that, for a `/skill:forge*`
+invocation, rewrites the input to inject a versioned envelope, then lets Pi's
+built-in expansion append it as the skill's arguments:
+
+```xml
+<feature-forge-invocation version="1">
+  <skill>forge-1-prd</skill>
+  <arguments>rendered-model-v2</arguments>
+</feature-forge-invocation>
+```
+
+The forge skill bodies read the feature name from `<arguments>`. An empty element
+means no argument was supplied — for a skill that requires a feature name that means
+STOP and ask; the `forge` navigator (optional argument) proceeds as usual. That
+companion rule lives host-neutrally in `references/shared-conventions.md`.
+
+### Design decisions
+
+- **Inject-into-args, not own-expansion.** The handler returns
+  `{ action: "transform", text: "/skill:<name> <envelope>" }` and lets Pi expand
+  the skill. Verified against Pi's `_expandSkillCommand`
+  (`dist/core/agent-session.js`): the skill name is the text up to the first space,
+  and args are the **entire remainder** (newlines preserved), end-trimmed — so a
+  multiline envelope survives re-parse. This avoids replicating Pi's private
+  skill-block wrapper string, which can drift across versions.
+- **XML entity-escaping** of `&`, `<`, `>` in `<arguments>`. Total, lossless, and
+  collision-proof: a literal `</arguments>` in the raw args becomes
+  `&lt;/arguments&gt;` and cannot close the element. Flags, quotes, and multiline
+  text pass through unchanged.
+- **Always emit the envelope** for a matched command (empty `<arguments>` for zero
+  args) so the contract is uniform and deterministic.
+- **Skip `source: "extension"`.** Messages injected via `sendUserMessage` are
+  dispatched with `expandPromptTemplates: false` and never expand — there is no
+  boundary bug to fix, and rewriting them could corrupt a programmatic message.
+  `"interactive"` and `"rpc"` (including `-p` / `--mode json`) do expand and are
+  normalized.
+- **Fail loudly, never silently.** A thrown input handler makes the Pi runner fall
+  back to the *original untransformed* text — silently reintroducing the bug. On any
+  internal error the handler emits `ctx.ui.notify(..., "error")` and passes the
+  input through unchanged instead of throwing.
+- **Idempotent.** Input handlers chain; an already-enveloped invocation is left
+  untouched (never double-wrapped).
+
+## Supported Pi API / version assumptions
+
+- Requires the documented `input` event with `{ action: "transform" }`
+  (`pi.on("input", …)`), present in the pinned `@earendil-works/pi-coding-agent`
+  `^0.81.1` and confirmed through 0.85.1.
+- Depends only on Pi's **documented** contract that a skill command's arguments are
+  the remainder of the input after the command name — not on the specific
+  (buggy/unstable) way Pi separates them from the skill body. If a future Pi stops
+  treating the remainder as args, switch to owning expansion (replicating the
+  skill-block wrapper); until then, inject-into-args is the smaller-surface choice.
+
+## Tests
+
+`../../test/forge-invocation-args.test.mjs` (run by `npm run verify` in
+`adapter-src/pi`) loads the extension through jiti — the same loader Pi uses —
+asserts it registers exactly one `input` handler, and drives that handler across
+the documented input-before-skill-expansion lifecycle (zero/one/multiple args,
+flags, multiline, XML-special characters, non-forge passthrough, `source`
+routing, and idempotency).

package/adapters/pi/extensions/forge-invocation-args/index.ts

@@ -0,0 +1,31 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/forge-invocation-args/index.ts
+// Regenerate with: python3 scripts/build-adapters.py
+/**
+ * forge-invocation-args — a first-party Pi compatibility extension that gives
+ * `/skill:forge-*` invocation arguments an explicit, versioned semantic boundary
+ * before Pi's skill expansion drops it (issue #303). See wiring.ts for the full
+ * rationale and mechanics.
+ *
+ * The pi-facing glue is thin: all logic lives in the injectable {@link
+ * createExtension} factory (wiring.ts), unit-tested with a fake pi. This file
+ * adapts the real ExtensionAPI to the structural PiLike the wiring consumes — each
+ * member is accessed by name off the concrete `pi`, so a method renamed or removed
+ * in a future pi is a COMPILE error here rather than a silent runtime failure.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { createExtension, type InputResult, type PiLike } from "./wiring.js";
+
+export default function (pi: ExtensionAPI) {
+	const piLike: PiLike = {
+		on: (event, handler) =>
+			(
+				pi.on as unknown as (
+					e: string,
+					h: (ev: unknown, ctx: unknown) => InputResult | Promise<InputResult>,
+				) => void
+			)(event, handler as (ev: unknown, ctx: unknown) => InputResult | Promise<InputResult>),
+	};
+	createExtension(piLike);
+}

package/adapters/pi/extensions/forge-invocation-args/wiring.ts

@@ -0,0 +1,172 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/forge-invocation-args/wiring.ts
+// Regenerate with: python3 scripts/build-adapters.py
+/**
+ * Pi wiring for forge-invocation-args — the injectable, unit-testable core of the
+ * extension. All logic lives here behind a structural {@link PiLike} so the whole
+ * thing is driven by a fake pi in test (mirroring how forge-loop-supervisor is
+ * tested headlessly). index.ts supplies the real ExtensionAPI.
+ *
+ * WHY THIS EXISTS (issue #303): Pi expands `/skill:<name> <args>` by appending the
+ * raw args after the `</skill>` block with only a bare `\n\n` separator — no
+ * semantic boundary. Pi's docs say args arrive as `User: <args>`, but the
+ * implementation has bare-appended since Pi v0.50.0 (commit 7868b25a2), true
+ * through the installed 0.84.4 and tested 0.85.1. With no boundary, a model can
+ * read a forge feature-name argument as trailing prose and wrongly trip
+ * feature-forge's "no feature name → STOP and ask" rule. The feature name keys
+ * directory resolution, branch naming, and every pipeline-state write, so losing
+ * it silently is high-impact.
+ *
+ * THE FIX: hook Pi's `input` event, which fires BEFORE skill/template expansion
+ * (and after extension-command dispatch — `/skill:` is not an extension command,
+ * so it reaches us). For a `/skill:forge*` invocation we rewrite the input to
+ * `/skill:<name> <envelope>`, wrapping the raw argument string in an explicit,
+ * versioned envelope. Pi then expands the skill and appends the envelope as args
+ * — verified against Pi's `_expandSkillCommand`: skill name is the text up to the
+ * first space, args are the ENTIRE remainder (newlines preserved) end-trimmed, so
+ * a multiline entity-escaped envelope survives re-parse. We keep Pi's built-in
+ * expansion rather than replicating its private skill-block wrapper (which would
+ * drift across versions).
+ *
+ * pi surface used: `pi.on("input", handler)` returning an `InputEventResult`
+ * (`continue` | `transform`), and `ctx.ui.notify` for the fail-loud path.
+ */
+
+/** The envelope element name and its schema version. Consumers (the forge skill
+ *  bodies, via references/shared-conventions.md) read the feature name from
+ *  <arguments> and treat an empty element as "no feature name supplied". */
+export const ENVELOPE_TAG = "feature-forge-invocation";
+export const ENVELOPE_VERSION = "1";
+
+/** Pi's skill-command prefix. Pi expands `/skill:<name> <args>` only when the
+ *  text starts with this literal at index 0 (verified in agent-session.js
+ *  `_expandSkillCommand`), and package skills register un-namespaced — the
+ *  command is `/skill:forge-1-prd`, never `/skill:<pkg>:forge-1-prd`. */
+const SKILL_PREFIX = "/skill:";
+
+/** A feature-forge skill NAME (not the whole command): `forge` or `forge-<...>`.
+ *  Applied to the name Pi itself would parse out (text up to the first space), so
+ *  our match set is exactly Pi's expansion set — no more, no less. Anchored end
+ *  (`$`) so `forgery` is not matched. */
+const FORGE_NAME_RE = /^forge(?:-[a-z0-9-]+)?$/;
+
+/** Result subset this extension ever returns (a strict subset of Pi's
+ *  InputEventResult — we never return `handled`, which would skip the agent). */
+export type InputResult = { action: "continue" } | { action: "transform"; text: string };
+
+interface InputEventLike {
+	text: string;
+	source?: string;
+	streamingBehavior?: string;
+}
+interface UiLike {
+	notify?(message: string, level?: "info" | "warning" | "error"): void;
+}
+interface CtxLike {
+	ui?: UiLike;
+}
+
+/** Minimal structural shape of the pi API this wiring needs. Kept loose so the
+ *  fake pi in tests satisfies it without importing pi; index.ts adapts the real
+ *  ExtensionAPI to it (a renamed/removed `on` becomes a compile error there). */
+export interface PiLike {
+	on(
+		event: string,
+		handler: (event: InputEventLike, ctx: CtxLike) => InputResult | Promise<InputResult>,
+	): void;
+}
+
+/** Entity-escape the three XML metacharacters. Total and lossless: every input is
+ *  representable, and a literal `</arguments>` in the raw args becomes
+ *  `&lt;/arguments&gt;`, which cannot close the real element (no injection). `&`
+ *  must be replaced first so already-escaped output is not double-escaped. Flags,
+ *  quotes, and newlines pass through untouched. */
+export function escapeXml(value: string): string {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/** Build the versioned invocation envelope for a matched forge skill. `skillName`
+ *  is a kebab token (no escaping needed); `rawArgs` is entity-escaped. Zero args
+ *  yields an empty <arguments> element — the deterministic "no feature name"
+ *  signal. */
+export function buildEnvelope(skillName: string, rawArgs: string): string {
+	return (
+		`<${ENVELOPE_TAG} version="${ENVELOPE_VERSION}">\n` +
+		`  <skill>${skillName}</skill>\n` +
+		`  <arguments>${escapeXml(rawArgs)}</arguments>\n` +
+		`</${ENVELOPE_TAG}>`
+	);
+}
+
+/** True only for a complete envelope this extension emits (open tag WITH the
+ *  version attribute AND the matching close tag) — not merely any argument that
+ *  happens to begin with the tag name. Keeps the idempotency guard from dropping
+ *  the boundary on a legitimate arg like `<feature-forge-invocation> is a tag`. */
+function isAlreadyEnveloped(rawArgs: string): boolean {
+	return (
+		rawArgs.startsWith(`<${ENVELOPE_TAG} version="`) && rawArgs.trimEnd().endsWith(`</${ENVELOPE_TAG}>`)
+	);
+}
+
+/**
+ * Pure normalization: given raw input text, return the transform (for a
+ * feature-forge skill command) or `continue` (for everything else). Exported for
+ * direct unit testing. The command is parsed EXACTLY as Pi's `_expandSkillCommand`
+ * does — the text must start with `/skill:` at index 0, the name is the text up to
+ * the first space (or the whole remainder if none), and args are the rest, trimmed
+ * — so our match set equals Pi's expansion set and the rewritten text re-expands
+ * identically. A name that is not a forge skill (or a `/skill:`-less prompt) is
+ * left untouched.
+ */
+export function normalizeInput(text: string): InputResult {
+	if (!text.startsWith(SKILL_PREFIX)) return { action: "continue" };
+
+	const spaceIndex = text.indexOf(" ");
+	const skillName =
+		spaceIndex === -1 ? text.slice(SKILL_PREFIX.length) : text.slice(SKILL_PREFIX.length, spaceIndex);
+	if (!FORGE_NAME_RE.test(skillName)) return { action: "continue" };
+
+	const rawArgs = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1).trim();
+
+	// Idempotency: input handlers chain (each sees the prior's output), and a
+	// resend could re-enter here. Never re-wrap an invocation we already enveloped.
+	if (isAlreadyEnveloped(rawArgs)) return { action: "continue" };
+
+	const envelope = buildEnvelope(skillName, rawArgs);
+	return { action: "transform", text: `/skill:${skillName} ${envelope}` };
+}
+
+/**
+ * Register the single `input` handler on `pi`. Returns nothing; all behavior is
+ * in the handler and the pure helpers above.
+ */
+export function createExtension(pi: PiLike): void {
+	pi.on("input", (event, ctx) => {
+		// Only normalize user-typed ("interactive") and API ("rpc") input.
+		// Extension-injected messages ("extension", via sendUserMessage) are
+		// dispatched with expandPromptTemplates:false and never expand, so there is
+		// no boundary bug to fix — and rewriting a programmatic message could corrupt
+		// it. This mirrors Pi's own input-transform example.
+		if (event?.source === "extension") return { action: "continue" };
+
+		try {
+			return normalizeInput(event.text);
+		} catch (error) {
+			// Fail LOUDLY, never silently. A thrown input handler makes the Pi runner
+			// log the error and continue with the ORIGINAL untransformed text — which
+			// would silently reintroduce the dropped-argument bug this extension exists
+			// to prevent. So we surface it via notify and pass the input through
+			// unchanged rather than throwing. (Entity-escaping makes this path
+			// effectively unreachable; it is defense in depth.)
+			const message = error instanceof Error ? error.message : String(error);
+			try {
+				ctx?.ui?.notify?.(
+					`forge-invocation-args: could not normalize a /skill:forge invocation (${message}); passing it through unchanged.`,
+					"error",
+				);
+			} catch {
+				/* headless / no notify surface */
+			}
+			return { action: "continue" };
+		}
+	});
+}

package/adapters/pi/package.json

@@ -11,6 +11,7 @@
     ],
     "extensions": [
       "./extensions/ask-user-question/index.ts",
+      "./extensions/forge-invocation-args/index.ts",
       "./extensions/forge-loop-supervisor/index.ts"
     ]
   },

package/adapters/pi/references/forge-config-schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Feature Forge Configuration",
-  "description": "Project-level configuration for the feature-forge plugin. Place as forge.config.json in your project root.",
+  "description": "Project-level configuration for the feature-forge plugin. Place as forge.config.json in your project root. An optional gitignored forge.config.local.json alongside it is deep-merged over the committed file (local wins) so machine-local facts — e.g. loopRunner.bin, contextWindowTokens — live outside version control; FEATURE_FORGE_LOOP_RUNNER_BIN overrides loopRunner.bin above both.",
   "type": "object",
   "properties": {
     "specsDir": {
@@ -235,8 +235,8 @@
         },
         "installHint": {
           "type": "string",
-          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.15.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.15.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
-          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.15.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
+          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.16.1 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.16.1 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
+          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.16.1), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
         },
         "schemaVersion": {
           "type": "string",

package/adapters/pi/references/portable-root.md

@@ -12,7 +12,7 @@ against the fenced block here, byte-for-byte.
 ## Canonical bootstrap prelude
 
 ```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; }
 ```
 
@@ -24,24 +24,27 @@ makes several calls, add the prelude once and reuse `$R` for each. A fresh block
 prelude (per-block re-resolution). Worked example:
 
 ```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
 ```
 
 ## Invariants (do NOT "fix" these)
 
-1. **First hint is the Claude plugin-root env var; the rest are paths.** The prelude's
-   `for d in …` list leads with the `CLAUDE_PLUGIN_ROOT` env var (in default-empty `:-` form)
-   — the exact bundle dir Claude exports in every marketplace/plugin session — followed by the
-   directory-path candidates. The hint gives exact, glob-free resolution on any current/future
-   Claude layout (no version-skew window); when unset it expands to empty and is harmlessly
-   skipped, so other hosts fall through to the path candidates unchanged. This is the **one
-   sanctioned** appearance of that variable in canonical surfaces: spec-purity rule 3 allows it
-   by stripping the byte-pinned prelude before its residual-var scan (so a stray var anywhere
-   else — including the default-empty form — still fails), and `forge-agent-adapters-build`
-   translates it to `FEATURE_FORGE_ROOT` for non-Claude bundles (which `forge-root.sh` already
-   prefers). The exact literal is shown only in the fenced prelude above and audited in
+1. **Explicit `FEATURE_FORGE_ROOT` override first, then the Claude env hint, then paths.** The
+   prelude opens with a guard: if `FEATURE_FORGE_ROOT` is set but carries no
+   `scripts/forge-root.sh`, it fails loudly (`exit 2`) instead of silently falling back to
+   discovery — an operator override that does not resolve is an error, not a hint (the same rule
+   `forge-root.sh` Step 0 applies). The `for d in …` list then leads with the `FEATURE_FORGE_ROOT`
+   env var in default-empty `:-` form (the host-neutral operator override, honored on every agent)
+   followed by the `CLAUDE_PLUGIN_ROOT` env var in the same form (the exact bundle dir Claude
+   exports in every marketplace/plugin session), then the directory-path candidates. Both env hints
+   give exact, glob-free resolution; when unset each expands to empty and is harmlessly skipped, so
+   other hosts fall through to the path candidates unchanged. `CLAUDE_PLUGIN_ROOT` remains the **one
+   sanctioned** appearance of that vendor variable in canonical surfaces: spec-purity rule 3 allows
+   it by stripping the byte-pinned prelude
+   before its residual-var scan (so a stray var anywhere else — including the default-empty form —
+   still fails). The exact literal is shown only in the fenced prelude above and audited in
    `vendor-construct-inventory.md`.
 2. **First-discoverable-resolver-wins.** The `exec` inside the `$(…)` command substitution means
    the loop stops at the first directory holding an executable `forge-root.sh` and delegates ALL
@@ -64,8 +67,9 @@ python3 "$R/scripts/epic-manifest.py" render-status "{epic}" --specs-dir "{specs
 
 The prelude delegates to [`scripts/forge-root.sh`](../scripts/forge-root.sh) — the portable
 skill/plugin-root resolver. It takes no arguments, prints the absolute plugin root to stdout and
-exits `0`, or writes an actionable message to stderr and exits `1`. It resolves the root by
-self-location → candidate-root probe → plugin-root environment-variable fallback → actionable failure,
-and never sources or executes a discovered path — it only ever prints a directory string. The
+exits `0`, or writes an actionable message to stderr and exits non-zero. It resolves the root by
+explicit `FEATURE_FORGE_ROOT` override (Step 0) → self-location → candidate-root probe →
+`CLAUDE_PLUGIN_ROOT` fallback → actionable failure, and never sources or executes a discovered
+path — it only ever prints a directory string. The
 spec-purity checker (rule 5) enforces that every prelude occurrence across the canon is
 byte-identical to the fenced block in this file.