guardian-framework 0.1.155 → 0.1.157

package/dist/cli.js

@@ -3206,7 +3206,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.155", 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.157", 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.155", 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.157", 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.155",
+	"version": "0.1.157",
 	"description": "Token-optimized agentic framework scaffolder with pi-first architecture",
 	"type": "module",
 	"main": "dist/exports.js",

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:15:30Z",
+  "timestamp": "2026-11-13T17:52:57Z",
   "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 ;;
@@ -58,6 +70,16 @@ RUNNER="$ROOT/.pi/scripts/epic-runner.mjs"
 [ -f "$RUNNER" ] || { echo "missing $RUNNER — run guardian update" >&2; exit 1; }
 
 # The runner is a Node script; bun also executes it.
+# The project directory is the one that owns .pi/ (this script lives in
+# <project>/.pi/scripts). It is NOT necessarily the git top level: a monorepo
+# often keeps the app in <repo>/backend with .pi/ inside it. Agents must run in
+# the project dir, otherwise pi finds no extensions and /architect is not a
+# command at all.
+PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+GIT_TOP="$(git -C "$PROJECT_DIR" rev-parse --show-toplevel 2>/dev/null || echo "$PROJECT_DIR")"
+PROJECT_REL="${PROJECT_DIR#"$GIT_TOP"}"
+PROJECT_REL="${PROJECT_REL#/}"
+
 NODE_BIN="$(command -v node || command -v bun || true)"
 if [ -z "$NODE_BIN" ]; then
 	echo "neither node nor bun found — required to spawn headless agents" >&2
@@ -158,6 +180,30 @@ 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.
+if [ "$NO_SPAWN" -eq 0 ] && [ "$DRY_RUN" -eq 0 ]; then
+	if [ ! -d "$PROJECT_DIR/.pi/extensions" ]; then
+		echo "⛔ $PROJECT_DIR/.pi/extensions is missing — the agent would have no /architect command." >&2
+		echo "   Run guardian update in $PROJECT_DIR, or use --no-spawn." >&2
+		exit 1
+	fi
+fi
+
 echo "============================================"
 echo "  Parallel epic fan-out"
 echo "============================================"
@@ -346,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/-+$//')"
@@ -356,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=()
@@ -368,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)"
@@ -387,16 +491,27 @@ for m in ${MODULES[@]+"${MODULES[@]}"}; do
 	fi
 	echo "  ✓ worktree $WT"
 
-	if [ "$NO_SPAWN" -eq 1 ]; then
-		echo "  → run:  cd \"$WT\" && /architect --epic \"$m\"$( [ "$TDD" -eq 1 ] && echo " --tdd")"
+	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
 	fi
 
 	# 3. spawn one headless agent in the worktree (RPC mode dispatches the command)
+	#    cwd must be the PROJECT dir inside the worktree (where .pi/ lives).
+	SPAWN_CWD="$WT"
+	[ -n "$PROJECT_REL" ] && SPAWN_CWD="$WT/$PROJECT_REL"
+	if [ ! -d "$SPAWN_CWD/.pi/extensions" ]; then
+		echo "  ✗ $SPAWN_CWD/.pi/extensions missing — refusing to spawn a blind agent"
+		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 "$WT" --log "$log" ${TIMEOUT_MS:+--timeout-ms "$TIMEOUT_MS"} \
+		--cwd "$SPAWN_CWD" --log "$log" ${TIMEOUT_MS:+--timeout-ms "$TIMEOUT_MS"} \
 		>/dev/null 2>&1 &
 	PID=$!
 	bash "$REGISTRY" set "$m" "pid=$PID" "log=$log" "spawnedAt=$(date -u +%Y-%m-%dT%H:%M:%SZ)" >/dev/null 2>&1
@@ -408,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

@@ -115,9 +115,32 @@ function handleLine(line) {
 	// The prompt was accepted by an extension command?
 	if (msg.type === "response" && msg.command === "prompt" && msg.success === true) {
 		const d = msg.data?.disposition;
-		if (d === "handled") handled = true;
-		else if (d === "started" || d === "queued") handled = true;
-		if (handled) armGrace();
+		// "handled" = an extension command consumed it (what we need).
+		// "started"/"queued" = it went to the MODEL. For a /command that means
+		// the extension was not loaded (wrong cwd, missing .pi/extensions) — the
+		// model then improvises the workflow, which looks like success and burns
+		// tokens. Treat that as a hard error.
+		const isCommand = opts.command.startsWith("/");
+		if (d === "handled") {
+			handled = true;
+			armGrace();
+		} else if (isCommand) {
+			emit(
+				JSON.stringify({
+					type: "runner_error",
+					reason: "command_not_dispatched",
+					detail:
+						`'${opts.command.split(/\s+/)[0]}' was routed to the model ` +
+						`(disposition "${d}") — the extension is not loaded in ${opts.cwd}. ` +
+						"Check that .pi/extensions exists in that directory.",
+				}),
+			);
+			failed = true;
+			finish(3);
+		} else {
+			handled = true;
+			armGrace();
+		}
 	}
 	if (msg.type === "response" && msg.command === "prompt" && msg.success === false) {
 		emit(JSON.stringify({ type: "runner_error", reason: "prompt rejected" }));