guardian-framework 0.1.156 → 0.1.158

package/dist/cli.js

@@ -3206,7 +3206,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.156", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
+var name = "guardian-framework", version = "0.1.158", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
 var init_package = __esm(() => {
   exports = {
     ".": {

package/dist/exports.js

@@ -1991,7 +1991,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.156", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
+var name = "guardian-framework", version = "0.1.158", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
 var init_package = __esm(() => {
   exports = {
     ".": {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "guardian-framework",
-	"version": "0.1.156",
+	"version": "0.1.158",
 	"description": "Token-optimized agentic framework scaffolder with pi-first architecture",
 	"type": "module",
 	"main": "dist/exports.js",

package/templates/pi/extensions/architect-lib/tdd-generator.ts

@@ -98,6 +98,61 @@ export interface TddGenerateOptions {
  * Generate failing test files for all components in an epic slice.
  * Returns list of generated file paths.
  */
+/**
+ * Identifier builders shared by every language generator.
+ *
+ * Component and module ids are human labels ("aggregate-household",
+ * "payee review & digest", "--bankdigest-"), not identifiers. Interpolating
+ * them raw produced invalid code:
+ *   Python  def test_aggregate-household_is_defined():   -> SyntaxError
+ *   Rust    fn test_aggregate-household_is_defined()     -> will not compile
+ *   Go/Java/CamelCase(...)  names that start with a digit or keep spaces
+ *
+ * Every generated identifier now goes through one of these.
+ */
+
+/** Split a human label into alphanumeric words (never empty). */
+function identWords(raw: string): string[] {
+	const words = (raw ?? "")
+		.replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+		.split(/[^A-Za-z0-9]+/)
+		.filter((w) => w.length > 0);
+	return words.length > 0 ? words : ["component"];
+}
+
+/** `aggregate-household` -> `aggregate_household` (python, rust). */
+export function snakeIdent(raw: string): string {
+	const joined = identWords(raw)
+		.map((w) => w.toLowerCase())
+		.join("_");
+	// Identifiers may not start with a digit.
+	return /^[0-9]/.test(joined) ? `n_${joined}` : joined;
+}
+
+/** `aggregate-household` -> `AggregateHousehold` (java, go, ts types). */
+export function pascalIdent(raw: string): string {
+	const joined = identWords(raw)
+		.map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
+		.join("");
+	return /^[0-9]/.test(joined) ? `N${joined}` : joined;
+}
+
+/** `aggregate-household` -> `aggregateHousehold` (ts values). */
+export function camelIdent(raw: string): string {
+	const p = pascalIdent(raw);
+	return p.charAt(0).toLowerCase() + p.slice(1);
+}
+
+/** Kept for callers/tests that ask for a Python identifier specifically. */
+export function pyIdent(raw: string): string {
+	return snakeIdent(raw);
+}
+
+/** Components are not required to declare dependencies. */
+function depsOf(component: { dependencies?: string[] }): string[] {
+	return component.dependencies ?? [];
+}
+
 export function generateEpicTestFiles(options: TddGenerateOptions): string[] {
 	const {
 		components,
@@ -176,7 +231,7 @@ function getTestFileName(componentId: string, language: string): string {
 		case "go":
 			return `${componentId}_test.go`;
 		case "java":
-			return `${toPascalCase(componentId)}Test.java`;
+			return `${pascalIdent(componentId)}Test.java`;
 		default:
 			return `${componentId}.test.ts`;
 	}
@@ -228,19 +283,19 @@ function generateTypeScript(
 		`it("should be defined", () => {`,
 		`  expect(false).toBe(true);`,
 		`  // TODO: uncomment when ${component.name} is implemented`,
-		`  // const instance = new ${component.name.replace(/[^a-zA-Z0-9]/g, "")}();`,
+		`  // const instance = new ${pascalIdent(component.name)}();`,
 		`  // expect(instance).toBeDefined();`,
 		`});`,
 	], 1));
 
 	// Dependency interaction tests
-	for (const dep of component.dependencies) {
+	for (const dep of depsOf(component)) {
 		lines.push(...indent([
 			`it("should interact with ${dep}", () => {`,
 			`  expect(false).toBe(true);`,
 			`  // TODO: implement dependency test for ${dep}`,
 			`  // const mock = { /* mock ${dep} interface */ };`,
-			`  // const result = new ${component.name.replace(/[^a-zA-Z0-9]/g, "")}(mock);`,
+			`  // const result = new ${pascalIdent(component.name)}(mock);`,
 			`  // expect(result).toBeDefined();`,
 			`});`,
 		], 1));
@@ -268,21 +323,21 @@ function generateRust(
 		`    use super::*;`,
 		``,
 		`    #[test]`,
-		`    fn test_${componentId}_is_defined() {`,
+		`    fn test_${snakeIdent(componentId)}_is_defined() {`,
 		`        // TODO: uncomment when ${component.name} is implemented`,
-		`        // let _instance = ${toPascalCase(componentId)}::new();`,
+		`        // let _instance = ${pascalIdent(componentId)}::new();`,
 		`        assert!(false, "Test not yet implemented");`,
 		`    }`,
 	];
 
-	for (const dep of component.dependencies) {
+	for (const dep of depsOf(component)) {
 		lines.push(...[
 			``,
 			`    #[test]`,
-			`    fn test_${componentId}_interacts_with_${dep.replace(/[^a-z0-9]/gi, "_").toLowerCase()}() {`,
+			`    fn test_${snakeIdent(componentId)}_interacts_with_${snakeIdent(dep)}() {`,
 			`        // TODO: implement dependency test for ${dep}`,
 			`        // let mock = Mock${dep.replace(/[^a-zA-Z0-9]/g, "")}::new();`,
-			`        // let result = ${toPascalCase(componentId)}::new(mock);`,
+			`        // let result = ${pascalIdent(componentId)}::new(mock);`,
 			`        assert!(false, "Dependency test not yet implemented");`,
 			`    }`,
 		]);
@@ -300,7 +355,7 @@ function generatePython(
 	moduleId: string,
 	componentId: string,
 ): string {
-	const clsName = toPascalCase(componentId);
+	const clsName = pascalIdent(componentId);
 	const lines: string[] = [
 		`# Generated by Guardian TDD`,
 		`# From: ${component.name} (${moduleId} module)`,
@@ -312,17 +367,17 @@ function generatePython(
 		`class Test${clsName}:`,
 		`    """Tests for ${component.name}."""`,
 		``,
-		`    def test_${componentId}_is_defined(self):`,
+		`    def test_${snakeIdent(componentId)}_is_defined(self):`,
 		`        """${component.name} should be instantiable."""`,
 		`        assert False, "TODO: uncomment when ${component.name} is implemented"`,
 		`        # instance = ${clsName}()`,
 		`        # assert instance is not None`,
 	];
 
-	for (const dep of component.dependencies) {
+	for (const dep of depsOf(component)) {
 		lines.push(...[
 			``,
-			`    def test_${componentId}_interacts_with_${dep.replace(/[^a-z0-9]/gi, "_").toLowerCase()}(self):`,
+			`    def test_${snakeIdent(componentId)}_interacts_with_${snakeIdent(dep)}(self):`,
 			`        """${component.name} should interact with ${dep}."""`,
 			`        assert False, "TODO: implement dependency test for ${dep}"`,
 			`        # mock = MagicMock(spec=${dep.replace(/[^a-zA-Z0-9]/g, "")})`,
@@ -348,13 +403,13 @@ function generateGo(
 		`// From: ${component.name} (${moduleId} module)`,
 		`// These tests will FAIL until ${component.name} is implemented.`,
 		``,
-		`package ${moduleId.replace(/[^a-zA-Z0-9]/g, "").toLowerCase()}`,
+		`package ${snakeIdent(moduleId).replace(/_/g, "")}`,
 		``,
 		`import "testing"`,
 		``,
-		`func Test${toPascalCase(componentId)}_IsDefined(t *testing.T) {`,
+		`func Test${pascalIdent(componentId)}_IsDefined(t *testing.T) {`,
 		`	// TODO: uncomment when ${component.name} is implemented`,
-		`	// instance := New${toPascalCase(componentId)}()`,
+		`	// instance := New${pascalIdent(componentId)}()`,
 		`	// if instance == nil {`,
 		`	// 	t.Fail()`,
 		`	// }`,
@@ -362,13 +417,13 @@ function generateGo(
 		`}`,
 	];
 
-	for (const dep of component.dependencies) {
+	for (const dep of depsOf(component)) {
 		lines.push(...[
 			``,
-			`func Test${toPascalCase(componentId)}_InteractsWith_${capitalize(dep.replace(/[^a-zA-Z0-9]/g, ""))}(t *testing.T) {`,
+			`func Test${pascalIdent(componentId)}_InteractsWith_${pascalIdent(dep)}(t *testing.T) {`,
 			`	// TODO: implement dependency test for ${dep}`,
-			`	// mock := new(Mock${capitalize(dep.replace(/[^a-zA-Z0-9]/g, ""))})`,
-			`	// instance := New${toPascalCase(componentId)}(mock)`,
+			`	// mock := new(Mock${pascalIdent(dep)})`,
+			`	// instance := New${pascalIdent(componentId)}(mock)`,
 			`	// result := instance.Execute()`,
 			`	t.Fatal("Dependency test not yet implemented")`,
 			`}`,
@@ -387,7 +442,7 @@ function generateJava(
 	componentId: string,
 	javaPackage?: string,
 ): string {
-	const clsName = toPascalCase(componentId);
+	const clsName = pascalIdent(componentId);
 	const lines: string[] = [
 		`// Generated by Guardian TDD`,
 		`// From: ${component.name} (${moduleId} module)`,
@@ -415,13 +470,13 @@ function generateJava(
 		`    }`,
 	);
 
-	for (const dep of component.dependencies) {
+	for (const dep of depsOf(component)) {
 		lines.push(
 			``,
 			`    @Test`,
-			`    void test${clsName}_InteractsWith_${capitalize(dep.replace(/[^a-zA-Z0-9]/g, ""))}() {`,
+			`    void test${clsName}_InteractsWith_${pascalIdent(dep)}() {`,
 			`        // TODO: implement dependency test for ${dep}`,
-			`        // ${capitalize(dep.replace(/[^a-zA-Z0-9]/g, ""))} mock = mock(${capitalize(dep.replace(/[^a-zA-Z0-9]/g, ""))}.class);`,
+			`        // ${pascalIdent(dep)} mock = mock(${pascalIdent(dep)}.class);`,
 			`        // ${clsName} instance = new ${clsName}(mock);`,
 			`        fail("Dependency test not yet implemented");`,
 			`    }`,
@@ -434,14 +489,6 @@ function generateJava(
 
 // ── Utility ──
 
-function capitalize(s: string): string {
-	return s.charAt(0).toUpperCase() + s.slice(1);
-}
-
-function toPascalCase(s: string): string {
-	return s.split("-").map(capitalize).join("");
-}
-
 function indent(lines: string[], level: number): string[] {
 	const pad = "  ".repeat(level);
 	return lines.map((l) => `${pad}${l}`);

package/templates/pi/extensions/architect.ts

@@ -209,7 +209,11 @@ class EpicManager {
 			runScript(this.cwd, 'git commit -m "Initial Guardian scaffold"');
 		}
 
-		const repoTool = readRepoTool(this.cwd);
+		// GUARDIAN_LOCAL_ONLY=1 forces local-only: no remote issues are created.
+		// epic-fanout.sh sets this so an automated run cannot write to a forge
+		// without a human explicitly asking for it.
+		const localOnly = process.env.GUARDIAN_LOCAL_ONLY === "1";
+		const repoTool = localOnly ? "local" : readRepoTool(this.cwd);
 		const repository = readRepository(this.cwd);
 		const targetRepo = repository || slice.module;
 		let hasRemote = false;
@@ -880,16 +884,22 @@ export default function architectExtension(pi: ExtensionAPI) {
 			// roadmap order is used (implemented modules are skipped).
 			const modulesFlag = findFlag(tokens, "--modules");
 			const parallelMode = parallelFlag || useWorktree;
-			try {
-				const epicStatePath = join(ctx.cwd, ".pi", ".guardian-epic-state.json");
-				const st = existsSync(epicStatePath)
-					? (JSON.parse(readFileSync(epicStatePath, "utf-8")) as Record<string, unknown>)
-					: {};
-				st.prStrategy = epicPrStrategy;
-				mkdirSync(join(ctx.cwd, ".pi"), { recursive: true });
-				writeFileSync(epicStatePath, JSON.stringify(st, null, 2), "utf-8");
-			} catch {
-				// ignore — strategy falls back to epic
+			// In parallel mode fan-out owns the state: each spawned agent writes its
+			// own epic state INSIDE its worktree. Writing here would leave a stray
+			// .guardian-epic-state.json in the main checkout that makes
+			// `/architect status` report an epic that does not exist.
+			if (!parallelMode) {
+				try {
+					const epicStatePath = join(ctx.cwd, ".pi", ".guardian-epic-state.json");
+					const st = existsSync(epicStatePath)
+						? (JSON.parse(readFileSync(epicStatePath, "utf-8")) as Record<string, unknown>)
+						: {};
+					st.prStrategy = epicPrStrategy;
+					mkdirSync(join(ctx.cwd, ".pi"), { recursive: true });
+					writeFileSync(epicStatePath, JSON.stringify(st, null, 2), "utf-8");
+				} catch {
+					// ignore — strategy falls back to epic
+				}
 			}
 			const tddEnabled = tokens.includes("--tdd");
 
@@ -953,17 +963,6 @@ export default function architectExtension(pi: ExtensionAPI) {
 						ctx.ui.notify(`Fan-out failed:\n${out.trim().slice(-600)}`, "error");
 						return;
 					}
-					// Record orchestration on the state so later steps stay consistent.
-					try {
-						const p = join(ctx.cwd, ".pi/.guardian-epic-state.json");
-						const st = existsSync(p) ? (JSON.parse(readFileSync(p, "utf-8")) as Record<string, unknown>) : {};
-						st.prStrategy = epicPrStrategy;
-						st.parallel = true;
-						st.modules = list || "(roadmap order)";
-						writeFileSync(p, JSON.stringify(st, null, 2), "utf-8");
-					} catch {
-						// ignore
-					}
 					ctx.ui.notify(out.trim().split("\n").slice(-12).join("\n"), "info");
 					return;
 				}

package/templates/pi/preflight_report.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-11-13T17:26:44Z",
+  "timestamp": "2026-11-13T19:00:09Z",
   "mode": "all",
   "stages_run": [],
   "summary": {

package/templates/pi/scripts/epic-fanout.sh

@@ -13,9 +13,15 @@
 #
 # Usage:
 #   epic-fanout.sh [--modules a,b,c] [--tdd] [--max N]
-#                  [--force-freeze] [--dry-run] [--no-spawn]
+#                  [--spawn] [--dry-run] [--assume-frozen] [--local]
 #                  [--base main] [--timeout-ms N]
 #
+# SAFETY: nothing is spawned without --spawn. The default prepares worktrees
+# and prints the exact commands, so you can inspect before any agent runs.
+# Contracts must ALREADY be frozen in the registry; this script never freezes
+# on your behalf (that made the gate meaningless and started agents on
+# unreviewed contracts).
+#
 # Exit: 0 started/prepared · 2 blocked by a dependency · 1 error
 # ============================================================================
 set -uo pipefail
@@ -27,6 +33,9 @@ MAX=0
 FORCE_FREEZE=0
 DRY_RUN=0
 NO_SPAWN=0
+SPAWN=0
+ASSUME_FROZEN=0
+ALLOW_REMOTE=0
 BASE="main"
 TIMEOUT_MS=0
 
@@ -38,6 +47,9 @@ while [ $# -gt 0 ]; do
 	--force-freeze) FORCE_FREEZE=1; shift ;;
 	--dry-run) DRY_RUN=1; shift ;;
 	--no-spawn) NO_SPAWN=1; shift ;;
+	--spawn) SPAWN=1; shift ;;
+	--assume-frozen) ASSUME_FROZEN=1; shift ;;
+	--allow-remote-issues) ALLOW_REMOTE=1; shift ;;
 	--base) BASE="${2:-main}"; shift 2 ;;
 	--timeout-ms) TIMEOUT_MS="${2:-0}"; shift 2 ;;
 	-h | --help) sed -n '2,24p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
@@ -168,6 +180,19 @@ while IFS= read -r modline; do
 	[ -n "$modline" ] && MODULES+=("$modline")
 done <<<"$SELECTED"
 
+# ── Batch-size guard ────────────────────────────────────────────────────────
+# An unbounded automated batch is how six agents started at once. Spawning
+# requires an explicit bound: --max N, or an explicit --modules list of <= 3.
+if [ "$SPAWN" -eq 1 ] && [ "$MAX" -le 0 ]; then
+	COUNT=${#MODULES[@]}
+	if [ "$COUNT" -gt 3 ]; then
+		echo "⛔ Refusing to spawn ${COUNT} agents unbounded." >&2
+		echo "   Add --max N (recommended 1-3) or pass an explicit --modules list of at most 3." >&2
+		echo "   Nothing was created." >&2
+		exit 1
+	fi
+fi
+
 # ── Pre-flight: the spawned agents inherit THIS project's .pi/ ──────────────
 # Without extensions, /architect is not a command: the prompt falls through to
 # the model, which then improvises (expensive and wrong). Fail before spawning.
@@ -367,6 +392,25 @@ if [ "$DEP_RC" -ne 0 ]; then
 fi
 
 if [ "$DRY_RUN" -eq 1 ]; then
+	echo "Contract freeze status (a real run refuses unfrozen modules):"
+	for m in ${MODULES[@]+"${MODULES[@]}"}; do
+		slug="$(echo "$m" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//')"
+		st="$(python3 - "$COMMON_ABS/guardian/epics.json" "$slug" <<'PY' 2>/dev/null
+import json, re, sys
+try:
+    d = json.load(open(sys.argv[1], encoding="utf-8"))
+except Exception:
+    print("no"); raise SystemExit
+want = sys.argv[2]
+for mod, e in (d.get("epics") or {}).items():
+    if isinstance(e, dict) and re.sub(r"[^a-z0-9]+", "-", mod.lower()).strip("-") == want:
+        print("yes" if e.get("contractFrozen") else "no"); raise SystemExit
+print("no")
+PY
+)"
+		[ "$st" = "yes" ] && echo "  ✓ $m" || echo "  ✗ $m  (not frozen)"
+	done
+	echo ""
 	echo "Would do, per module:"
 	for m in ${MODULES[@]+"${MODULES[@]}"}; do
 		slug="$(echo "$m" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//')"
@@ -377,6 +421,45 @@ if [ "$DRY_RUN" -eq 1 ]; then
 	exit 0
 fi
 
+# ── Contract-freeze gate (the module itself) ────────────────────────────────
+# Freeze is a human act: it asserts the module's public contracts are reviewed
+# and merged. This script must never assert that for you — doing so is what let
+# a fan-out start six agents on unreviewed contracts.
+if [ "$ASSUME_FROZEN" -eq 0 ]; then
+	UNFROZEN="$(python3 - "$COMMON_ABS/guardian/epics.json" ${MODULES[@]+"${MODULES[@]}"} <<'PY'
+import json, re, sys
+
+path, batch = sys.argv[1], sys.argv[2:]
+frozen = set()
+try:
+    for mod, entry in (json.load(open(path, encoding="utf-8")).get("epics") or {}).items():
+        if isinstance(entry, dict) and entry.get("contractFrozen"):
+            frozen.add(re.sub(r"[^a-z0-9]+", "-", mod.lower()).strip("-"))
+except Exception:
+    pass
+
+missing = []
+for m in batch:
+    slug = re.sub(r"[^a-z0-9]+", "-", m.lower()).strip("-")
+    if slug not in frozen:
+        missing.append(m)
+print("\n".join(missing))
+PY
+)"
+	if [ -n "$UNFROZEN" ]; then
+		echo "⛔ Contracts are not frozen for:"
+		echo "$UNFROZEN" | sed 's/^/   - /'
+		echo ""
+		echo "   Freeze is YOUR assertion that the module's public contracts are"
+		echo "   reviewed and merged. Review the module doc, merge its contract"
+		echo "   freeze, then record it:"
+		echo "     bash .pi/scripts/epic-registry.sh freeze \"<Module>\" --frozen"
+		echo ""
+		echo "   Bypass only if you are certain: --assume-frozen"
+		exit 2
+	fi
+fi
+
 # ── Freeze, create worktrees, spawn ─────────────────────────────────────────
 mkdir -p "$LOGDIR"
 STARTED=()
@@ -389,11 +472,11 @@ for m in ${MODULES[@]+"${MODULES[@]}"}; do
 	echo "────────────────────────────────────────────"
 	echo "▶ $m"
 
-	# 1. record the contract freeze (the gate below requires it)
-	bash "$REGISTRY" freeze "$m" --frozen >/dev/null 2>&1
 
 	# 2. worktree + epic branch (gated on the freeze we just recorded)
-	WT_OUT="$(bash "$PARALLEL" "$m" --base "$BASE" 2>&1)"
+	WT_ARGS=("$m" --base "$BASE")
+	[ "$ASSUME_FROZEN" -eq 1 ] && WT_ARGS+=(--assume-frozen)
+	WT_OUT="$(bash "$PARALLEL" "${WT_ARGS[@]}" 2>&1)"
 	WT_RC=$?
 	if [ "$WT_RC" -ne 0 ]; then
 		echo "  ✗ worktree failed (exit $WT_RC)"
@@ -408,7 +491,7 @@ for m in ${MODULES[@]+"${MODULES[@]}"}; do
 	fi
 	echo "  ✓ worktree $WT"
 
-	if [ "$NO_SPAWN" -eq 1 ]; then
+	if [ "$SPAWN" -eq 0 ] || [ "$NO_SPAWN" -eq 1 ]; then
 		echo "  → run:  cd \"$WT${PROJECT_REL:+/$PROJECT_REL}\" && /architect --epic \"$m\"$( [ "$TDD" -eq 1 ] && echo " --tdd")"
 		STARTED+=("$m")
 		continue
@@ -423,6 +506,9 @@ for m in ${MODULES[@]+"${MODULES[@]}"}; do
 		FAILED+=("$m")
 		continue
 	fi
+	# GUARDIAN_LOCAL_ONLY keeps the spawned epic from creating remote issues
+	# unless the caller explicitly allowed it (--allow-remote-issues).
+	export GUARDIAN_LOCAL_ONLY="$([ "$ALLOW_REMOTE" -eq 1 ] && echo 0 || echo 1)"
 	"$NODE_BIN" "$RUNNER" \
 		"/architect --epic \"$m\"$( [ "$TDD" -eq 1 ] && echo " --tdd")" \
 		--cwd "$SPAWN_CWD" --log "$log" ${TIMEOUT_MS:+--timeout-ms "$TIMEOUT_MS"} \
@@ -437,8 +523,13 @@ echo "────────────────────────
 echo ""
 echo "Started ${#STARTED[@]}/${#MODULES[@]} epic(s)."
 [ "${#FAILED[@]}" -gt 0 ] && echo "Failed: ${FAILED[*]:-}"
+if [ "$SPAWN" -eq 0 ] || [ "$NO_SPAWN" -eq 1 ]; then
+	echo ""
+	echo "Nothing was spawned (default). Worktrees are ready and empty."
+	echo "Re-run with --spawn to launch agents, or run the commands above yourself."
+fi
 
-if [ "${#STARTED[@]}" -gt 0 ]; then
+if [ "${#STARTED[@]}" -gt 0 ] && [ "$SPAWN" -eq 1 ] && [ "$NO_SPAWN" -eq 0 ]; then
 	echo ""
 	echo "Monitor:"
 	echo "  bash .pi/scripts/epic-registry.sh list"

package/templates/pi/scripts/epic-parallel.sh

@@ -13,9 +13,10 @@ set -uo pipefail
 
 MODULE="${1:-}"
 shift || true
-BASE="main"; DIR=""
+BASE="main"; DIR=""; ASSUME_FROZEN=0
 while [ $# -gt 0 ]; do
 	case "$1" in
+		--assume-frozen) ASSUME_FROZEN=1; shift ;;
 		--base) BASE="${2:-main}"; shift 2 ;;
 		--dir) DIR="${2:-}"; shift 2 ;;
 		*) shift ;;
@@ -58,7 +59,7 @@ PY
 )
 fi
 
-if [ "$FROZEN" != "true" ]; then
+if [ "$FROZEN" != "true" ] && [ "$ASSUME_FROZEN" -eq 0 ]; then
 	# NOTE: block here (before worktree creation) and exit 2 — a non-zero,
 	# distinguishable code so callers/agents cannot mistake it for success.
 	echo "⛔ Blocked: contracts for '$MODULE' are not frozen (registry: $FROZEN)."

package/templates/pi/scripts/epic-runner.mjs

@@ -62,7 +62,10 @@ const args = ["--mode", "rpc"];
 if (opts.session) args.push("--session-id", opts.session);
 else args.push("--no-session");
 
-const child = spawn("pi", args, {
+// Explicit binary wins: tests and CI set GUARDIAN_PI_BIN so resolution never
+// depends on PATH (a project's node_modules/.bin can contain another `pi`).
+const piBin = process.env.GUARDIAN_PI_BIN || "pi";
+const child = spawn(piBin, args, {
 	cwd: opts.cwd,
 	stdio: ["pipe", "pipe", "pipe"],
 	env: process.env,