guardian-framework 0.1.156 → 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.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.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.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.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.156",
+	"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:26:44Z",
+  "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 ;;
@@ -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)."