@garygentry/feature-forge 0.3.5 → 0.3.7

package/adapters/pi/extensions/forge-loop-supervisor/wiring.ts

@@ -0,0 +1,423 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/forge-loop-supervisor/wiring.ts
+// Regenerate with: python3 scripts/build-adapters.py
+/**
+ * Pi wiring for the forge-loop-supervisor — builds the host, the three tools
+ * (launch / status / stop) and the session-lifecycle hooks on a given
+ * `ExtensionAPI`. Every side-effecting dependency (process spawn, file watch,
+ * clock) is injected so the whole extension is unit-testable with a fake pi and
+ * fake deps, mirroring how the vendored ask-user-question extension is driven
+ * headlessly in its own test.
+ *
+ * pi surface used (resolved against the installed pi types, stable across the
+ * pinned 0.81.x): `pi.registerTool`, `pi.on("session_start"|"session_shutdown")`,
+ * `pi.sendMessage(msg, { triggerTurn })` (wake the session — the file-trigger.ts
+ * pattern), `pi.appendEntry(type, data)` (durable task record), `pi.exec` (run
+ * `rauf status --json` / `rauf loop stop`), and `ctx.ui.notify` (quiet toasts).
+ * rauf's `--detached` loop is server-owned and outlives the session, so cleanup
+ * on shutdown tears down watchers only — never the runner.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { Type } from "typebox";
+
+import { clearMirror, discoverMirrors, readMirror, writeMirror } from "./registry.js";
+import { LoopSupervisor, type TaskHandle } from "./supervisor.js";
+import { NdjsonTailer } from "./tailer.js";
+import type { SupervisorHost, SupervisorTask } from "./types.js";
+
+/** The custom-entry type under which task identity is persisted into the pi
+ *  session (read back on `session_start` for reattach). */
+export const TASK_ENTRY_TYPE = "forge-loop-task";
+/** The custom-message type used to wake the session on exception/terminal. */
+export const WAKE_MESSAGE_TYPE = "forge-loop";
+
+/** A live poll trigger for one watched file: `close()` stops it. The real
+ *  factory wires `fs.watch` on the containing directory (so rotation-by-rename
+ *  is caught) plus a low-frequency backstop; a test injects a manual trigger. */
+export interface WatchHandle {
+	close(): void;
+}
+
+/** Injectable side effects. Production values live in index.ts. */
+export interface Deps {
+	/** Launch the runner DETACHED so it outlives the session. Returns nothing —
+	 *  the loop is owned by the runner's server, not by a tracked child. `onError`
+	 *  reports an ASYNCHRONOUS spawn failure (e.g. ENOENT for a bad bin, which
+	 *  Node surfaces on the child's 'error' event, not as a throw). */
+	spawnDetached(bin: string, args: string[], cwd: string, onError?: (message: string) => void): void;
+	/** Watch `filePath` for changes, calling `onChange` on each (real: fs.watch
+	 *  on its directory + backstop interval). */
+	watch(filePath: string, onChange: () => void): WatchHandle;
+	/** Current time as ISO-8601. */
+	now(): string;
+}
+
+/** Minimal shape of the pi API this wiring needs (kept structural so the fake pi
+ *  in tests satisfies it without importing pi). */
+export interface PiLike {
+	registerTool(def: unknown): void;
+	on(event: string, handler: (event: unknown, ctx: unknown) => void | Promise<void>): void;
+	sendMessage(
+		message: { customType: string; content: string; display?: boolean },
+		options?: { triggerTurn?: boolean },
+	): void;
+	appendEntry(customType: string, data?: unknown): void;
+	exec?(
+		command: string,
+		args: string[],
+		options?: { cwd?: string; timeout?: number },
+	): Promise<{ stdout: string; stderr: string; code: number }>;
+}
+
+interface UiLike {
+	notify?(message: string, level?: "info" | "warning" | "error"): void;
+}
+interface CtxLike {
+	cwd?: string;
+	hasUI?: boolean;
+	ui?: UiLike;
+	sessionManager?: { getEntries?(): Array<{ type?: string; customType?: string; data?: unknown }> };
+}
+
+function textResult(text: string, details: Record<string, unknown>) {
+	return { content: [{ type: "text" as const, text }], details };
+}
+
+/** Best-effort count of backlog items for the `[N/M]` progress line. */
+function countBacklog(cwd: string, backlogDir: string): number | undefined {
+	for (const candidate of [join(cwd, backlogDir, "backlog.json"), join(backlogDir, "backlog.json")]) {
+		try {
+			if (!existsSync(candidate)) continue;
+			const parsed = JSON.parse(readFileSync(candidate, "utf8")) as { items?: unknown[] };
+			if (Array.isArray(parsed.items)) return parsed.items.length;
+		} catch {
+			// unreadable/unparseable backlog → no total, not an error
+		}
+	}
+	return undefined;
+}
+
+/** Resolve `dir` against `cwd` unless it is already absolute. */
+function resolveDir(cwd: string, dir: string): string {
+	return dir.startsWith("/") ? dir : join(cwd, dir);
+}
+
+/**
+ * Register the supervisor's tools and lifecycle hooks on `pi`. Returns a small
+ * control object (used by tests) exposing the live supervisor and watcher map.
+ */
+export function createExtension(pi: PiLike, deps: Deps) {
+	const watchers = new Map<string, { handle: TaskHandle; watch: WatchHandle; backlogDir: string }>();
+	let ui: UiLike | null = null;
+
+	const host: SupervisorHost = {
+		notify(message, level) {
+			try {
+				ui?.notify?.(message, level);
+			} catch {
+				/* headless / no dialog UI */
+			}
+		},
+		wake(message) {
+			try {
+				pi.sendMessage({ customType: WAKE_MESSAGE_TYPE, content: message, display: true }, { triggerTurn: true });
+			} catch {
+				/* sendMessage unavailable — nothing else to do */
+			}
+		},
+		persist(task) {
+			try {
+				pi.appendEntry(TASK_ENTRY_TYPE, task);
+			} catch {
+				/* appendEntry best-effort */
+			}
+			writeMirror(task);
+		},
+		now: () => deps.now(),
+	};
+
+	const supervisor = new LoopSupervisor(host);
+
+	/** Keep the notify target current from whatever ctx we last saw (tool call or
+	 *  session_start). ctx can go stale across a session replacement, so we always
+	 *  prefer the most recent one. */
+	function refreshUi(ctx: CtxLike): void {
+		if (ctx?.ui) ui = ctx.ui;
+	}
+
+	/** Begin watching a task's event file. Idempotent per stateDir (the dedup
+	 *  guard against duplicate watchers). Does an initial poll to replay history. */
+	function startWatch(task: SupervisorTask): void {
+		if (watchers.has(task.stateDir)) return;
+		const handle = supervisor.attach(task, (onRecord, onRotate) =>
+			new NdjsonTailer(task.eventsFile, onRecord, undefined, onRotate, task.eventsIno),
+		);
+		// Poll, then tear the watcher down once a terminal event has closed the task
+		// (its wake was already sent inside poll). This stops the fs.watch + backstop
+		// interval for a finished loop and frees a relaunch on the same backlog — the
+		// detached runner is untouched, exactly as on session end.
+		const pump = () => {
+			handle.poll();
+			if (supervisor.progress(task.stateDir)?.closed) stopWatch(task.stateDir);
+		};
+		const watch = deps.watch(task.eventsFile, pump);
+		watchers.set(task.stateDir, { handle, watch, backlogDir: task.backlogDir });
+		pump();
+	}
+
+	/** Stop watching a task (teardown / stop) WITHOUT touching the runner. */
+	function stopWatch(stateDir: string): void {
+		const w = watchers.get(stateDir);
+		if (!w) return;
+		try {
+			w.watch.close();
+		} catch {
+			/* ignore */
+		}
+		w.handle.close();
+		watchers.delete(stateDir);
+	}
+
+	// ---- Tools -------------------------------------------------------------
+
+	pi.registerTool({
+		name: "forge_loop_launch",
+		label: "Launch forge loop",
+		description:
+			"Launch the forge autonomous coding loop (rauf) DETACHED and supervise it. " +
+			"The loop runs in rauf's server and outlives this session; this tool returns " +
+			"immediately. It then reports each completed backlog item as a quiet line and " +
+			"WAKES this session on needs-human, blocked, stuck, review-failed, error, or " +
+			"completion. Use this for forge-5-loop's loop run on Pi instead of running the " +
+			"runner in the foreground.",
+		promptSnippet:
+			"Start a forge/rauf loop without blocking the session and supervise its events.ndjson.",
+		parameters: Type.Object({
+			backlogDir: Type.String({ description: "Forge backlog directory passed to --backlog (e.g. specs/auth)." }),
+			bin: Type.Optional(Type.String({ description: "Runner binary. Default 'rauf'." })),
+			stateDir: Type.Optional(
+				Type.String({ description: "Runner state dir holding events.ndjson. Default '<backlogDir>/.rauf'." }),
+			),
+			iterations: Type.Optional(Type.Number({ description: "Max iterations (--iterations). Omit for the runner default." })),
+			review: Type.Optional(Type.Boolean({ description: "Append --review to run the loop's review pass." })),
+			agent: Type.Optional(Type.String({ description: "Coding-agent id passed as --agent." })),
+		}),
+		async execute(_id: string, params: unknown, _signal: unknown, _onUpdate: unknown, ctx: CtxLike) {
+			const p = params as {
+				backlogDir: string;
+				bin?: string;
+				stateDir?: string;
+				iterations?: number;
+				review?: boolean;
+				agent?: string;
+			};
+			refreshUi(ctx);
+			const cwd = ctx.cwd ?? process.cwd();
+			const bin = p.bin || "rauf";
+			const stateDir = resolveDir(cwd, p.stateDir || join(p.backlogDir, ".rauf"));
+			const eventsFile = join(stateDir, "events.ndjson");
+
+			if (supervisor.isActive(stateDir)) {
+				return textResult(
+					`A forge loop is already being supervised for ${stateDir}. Use forge_loop_status to check it, or forge_loop_stop first.`,
+					{ launched: false, stateDir },
+				);
+			}
+
+			const args = ["loop", "run", ".", "--backlog", p.backlogDir, "--detached"];
+			if (typeof p.iterations === "number") args.push("--iterations", String(p.iterations));
+			if (p.review) args.push("--review");
+			if (p.agent) args.push("--agent", p.agent);
+
+			try {
+				// A synchronous throw is a definite failure. An ASYNC spawn error
+				// (ENOENT for a bad bin) arrives after this returns, so surface it as
+				// a notification when it fires rather than silently claiming success.
+				deps.spawnDetached(bin, args, cwd, (msg) =>
+					host.notify(`forge loop: failed to launch ${bin} — ${msg}. The loop did not start.`, "error"),
+				);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				return textResult(`Failed to launch ${bin}: ${msg}`, { launched: false, stateDir, error: msg });
+			}
+
+			const task: SupervisorTask = {
+				backlogDir: p.backlogDir,
+				stateDir,
+				eventsFile,
+				launchedAt: host.now(),
+				total: countBacklog(cwd, p.backlogDir),
+				lastSeq: -1,
+				closed: false,
+			};
+			host.persist(task);
+			startWatch(task);
+
+			return textResult(
+				`Launched \`${bin} ${args.join(" ")}\` detached; now supervising ${eventsFile}. ` +
+					"I'll report each completed item and wake this session on needs-human / blocked / " +
+					"stuck / review-failed / error / completion. Run forge_loop_status to confirm it started. " +
+					"Do NOT run the loop in the foreground.",
+				{ launched: true, stateDir, eventsFile },
+			);
+		},
+	});
+
+	pi.registerTool({
+		name: "forge_loop_status",
+		label: "Forge loop status",
+		description:
+			"Report the status of a supervised forge/rauf loop: how many items are done, " +
+			"whether it has finished, and the runner's authoritative counts (via " +
+			"`rauf status --json`). Use to confirm a launch or check progress on demand.",
+		parameters: Type.Object({
+			backlogDir: Type.Optional(Type.String({ description: "Backlog dir of the loop to report. Omit for the only supervised loop." })),
+			stateDir: Type.Optional(Type.String({ description: "State dir of the loop. Overrides backlogDir when set." })),
+			bin: Type.Optional(Type.String({ description: "Runner binary for the status query. Default 'rauf'." })),
+		}),
+		async execute(_id: string, params: unknown, _signal: unknown, _onUpdate: unknown, ctx: CtxLike) {
+			const p = params as { backlogDir?: string; stateDir?: string; bin?: string };
+			refreshUi(ctx);
+			const cwd = ctx.cwd ?? process.cwd();
+			const stateDir = p.stateDir
+				? resolveDir(cwd, p.stateDir)
+				: p.backlogDir
+					? resolveDir(cwd, join(p.backlogDir, ".rauf"))
+					: [...watchers.keys()][0];
+
+			const progress = stateDir ? supervisor.progress(stateDir) : null;
+			// Scope the runner query to the supervised backlog so status reflects the
+			// right loop, not whatever sits at the default project root.
+			const backlogDir = p.backlogDir ?? (stateDir ? watchers.get(stateDir)?.backlogDir : undefined);
+			let runnerLine = "";
+			if (pi.exec) {
+				const statusArgs = ["status", "--json"];
+				if (backlogDir) statusArgs.push("--backlog", backlogDir);
+				try {
+					const res = await pi.exec(p.bin || "rauf", statusArgs, { cwd, timeout: 15000 });
+					runnerLine = res.code === 0 ? ` Runner: ${res.stdout.trim()}` : ` Runner status exited ${res.code}.`;
+				} catch {
+					runnerLine = " (could not query the runner for authoritative status)";
+				}
+			}
+
+			if (!progress) {
+				return textResult(
+					`No forge loop is being supervised in this session${stateDir ? ` for ${stateDir}` : ""}.${runnerLine}`,
+					{ supervised: false, stateDir, runner: runnerLine.trim() },
+				);
+			}
+			const totalPart = typeof progress.total === "number" ? `/${progress.total}` : "";
+			return textResult(
+				`Forge loop ${progress.closed ? "finished" : "running"}: ${progress.done}${totalPart} items completed so far.${runnerLine}`,
+				{ supervised: true, stateDir, done: progress.done, total: progress.total, closed: progress.closed },
+			);
+		},
+	});
+
+	pi.registerTool({
+		name: "forge_loop_stop",
+		label: "Stop forge loop",
+		description:
+			"Stop a supervised forge/rauf loop and stop watching it. This DELIBERATELY " +
+			"terminates the runner (via `rauf loop stop`) — unlike ending the session, " +
+			"which leaves the detached loop running. Use only when the user wants the loop " +
+			"to actually stop.",
+		parameters: Type.Object({
+			backlogDir: Type.Optional(Type.String({ description: "Backlog dir of the loop to stop. Omit for the only supervised loop." })),
+			stateDir: Type.Optional(Type.String({ description: "State dir of the loop. Overrides backlogDir when set." })),
+			bin: Type.Optional(Type.String({ description: "Runner binary. Default 'rauf'." })),
+		}),
+		async execute(_id: string, params: unknown, _signal: unknown, _onUpdate: unknown, ctx: CtxLike) {
+			const p = params as { backlogDir?: string; stateDir?: string; bin?: string };
+			refreshUi(ctx);
+			const cwd = ctx.cwd ?? process.cwd();
+			const stateDir = p.stateDir
+				? resolveDir(cwd, p.stateDir)
+				: p.backlogDir
+					? resolveDir(cwd, join(p.backlogDir, ".rauf"))
+					: [...watchers.keys()][0];
+
+			// Refuse a blind stop: with nothing supervised AND no explicit target we
+			// must NOT run `rauf loop stop`, which would kill whatever loop happens to
+			// be running in this project — one this extension never launched. Require
+			// a supervised task or an explicit backlogDir/stateDir.
+			const watcherRec = stateDir ? watchers.get(stateDir) : undefined;
+			if (!watcherRec && !p.backlogDir && !p.stateDir) {
+				return textResult(
+					"No forge loop is being supervised in this session, and no backlog/stateDir was given — nothing to stop. Ending the session already leaves any detached loop running by design; pass a backlogDir to stop a specific loop.",
+					{ stopped: false },
+				);
+			}
+
+			// Scope the stop to the specific backlog so it targets the intended loop,
+			// not the default project root.
+			const backlogDir = p.backlogDir ?? watcherRec?.backlogDir;
+			let stopLine = "";
+			if (pi.exec) {
+				const stopArgs = ["loop", "stop"];
+				if (backlogDir) stopArgs.push("--backlog", backlogDir);
+				try {
+					const res = await pi.exec(p.bin || "rauf", stopArgs, { cwd, timeout: 30000 });
+					stopLine = res.code === 0 ? "Runner stop requested." : `Runner stop exited ${res.code}: ${res.stderr.trim()}`;
+				} catch (e) {
+					stopLine = `Could not run the stop command: ${e instanceof Error ? e.message : String(e)}`;
+				}
+			}
+			if (stateDir) {
+				stopWatch(stateDir);
+				supervisor.detach(stateDir);
+				clearMirror(stateDir);
+			}
+			return textResult(`Stopped supervising${stateDir ? ` ${stateDir}` : ""}. ${stopLine}`, {
+				stopped: true,
+				stateDir,
+			});
+		},
+	});
+
+	// ---- Lifecycle ---------------------------------------------------------
+
+	// Reattach on every session start (startup / reload / resume / fork): rebuild
+	// the watcher for any loop this session (or a previous one) launched, without
+	// duplicate reporting — the dedup cursor (lastSeq) makes replayed history silent.
+	pi.on("session_start", (_event: unknown, ctx: unknown) => {
+		const c = ctx as CtxLike;
+		ui = c.ui ?? null;
+		const seen = new Set<string>();
+		const consider = (task: SupervisorTask | null) => {
+			if (!task || seen.has(task.stateDir) || watchers.has(task.stateDir)) return;
+			seen.add(task.stateDir);
+			// Prefer the on-disk mirror (most current lastSeq/closed/eventsIno); fall
+			// back to the session entry's own copy.
+			const fresh = readMirror(task.stateDir) ?? task;
+			if (fresh.closed) return; // already surfaced its terminal — nothing to resume
+			startWatch(fresh);
+		};
+		// (1) Session entries carry tasks across reload/resume/fork within a session
+		// lineage (pi.appendEntry survives those).
+		const entries = c.sessionManager?.getEntries?.() ?? [];
+		for (const entry of entries) {
+			if (entry?.type === "custom" && entry?.customType === TASK_ENTRY_TYPE) {
+				consider(entry.data as SupervisorTask);
+			}
+		}
+		// (2) A BRAND-NEW session file has no such entry, so also discover the disk
+		// mirrors under the project root — this is what lets a fresh session reattach
+		// to a loop a previous session launched (issue #236's "reconcile after
+		// session restart"). Bounded scan; `consider` dedups and skips closed tasks.
+		const cwd = c.cwd ?? process.cwd();
+		for (const task of discoverMirrors(cwd)) consider(task);
+	});
+
+	// Cleanup on shutdown: close every watcher, but LEAVE the detached runner
+	// running (it is server-owned and meant to outlive the session) and leave the
+	// mirror in place so the next session reattaches.
+	pi.on("session_shutdown", () => {
+		for (const stateDir of [...watchers.keys()]) stopWatch(stateDir);
+	});
+
+	return { supervisor, watchers, startWatch, stopWatch, host };
+}

package/adapters/pi/package.json

@@ -10,7 +10,9 @@
       "./skills"
     ],
     "extensions": [
-      "./extensions/ask-user-question/index.ts"
+      "./extensions/ask-user-question/index.ts",
+      "./extensions/forge-invocation-args/index.ts",
+      "./extensions/forge-loop-supervisor/index.ts"
     ]
   },
   "pi-subagents": {

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.14.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.14.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.14.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.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.16.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.16.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."
         },
         "schemaVersion": {
           "type": "string",
@@ -245,8 +245,8 @@
         },
         "minRunnerVersion": {
           "type": "string",
-          "default": "0.6.0",
-          "description": "Minimum runner version (semver). 0.6.0 is the AGENT-SURFACE FLOOR: the rauf version that ships the coding-agent selection surface (the --agent flag, the `agents` availability probe, and the preset agent registry) that this config's agentArgument/agentsProbeCommand consume. Flooring here guarantees a successful gate implies those surfaces exist. (0.5.0 was the prior grammar/contract-flip floor — unified exit codes, `loop run --detached`, explicit `review` signal, versioned events.ndjson — which predates the agent surface and so could not guarantee it.) forge-5 enforces this via versionCommand before any loop side-effects."
+          "default": "0.14.0",
+          "description": "Minimum runner version (semver). 0.14.0 is the CAPABILITY FLOOR the shipped stage actually depends on — it is the version needed for full post-run needs-human recovery: rauf 0.14's `backlog answer` injects a recorded answer into the next iteration (RECOVERY_MIN_RUNNER_VERSION in forge-session.py). Below it, recovery silently degrades to `backlog unblock` (answer not injected) and large Codex prompts retain the pre-0.14 argv-size (E2BIG) failure mode. Earlier surfaces are subsumed: 0.6.0 first shipped the coding-agent selection surface (--agent flag, `agents` availability probe, preset registry consumed by agentArgument/agentsProbeCommand); 0.5.0 added unified exit codes, `loop run --detached`, the explicit `review` signal, and versioned events.ndjson. Flooring at 0.14.0 guarantees a successful gate implies the recovery + agent surfaces both exist. The floor is distinct from the installer's `RAUF_PIN` (installHint) — the pin may sit ahead of the floor when a newer rauf ships nothing this floor's dependents need; it only rises when rauf ships a surface a shipped stage actually depends on. forge-5 enforces the floor via versionCommand before any loop side-effects."
         }
       }
     }

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.