guardian-framework 0.1.150 → 0.1.151

package/dist/cli.js

@@ -3206,7 +3206,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.150", 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.151", 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 = {
     ".": {
@@ -3217,7 +3217,10 @@ var init_package = __esm(() => {
   bin = {
     "guardian-framework": "dist/cli.js"
   };
-  files = ["dist/", "templates/"];
+  files = [
+    "dist/",
+    "templates/"
+  ];
   engines = {
     bun: ">=1.0.0"
   };
@@ -3235,9 +3238,15 @@ var init_package = __esm(() => {
     access: "public"
   };
   pi = {
-    extensions: ["./templates/pi/extensions"],
-    skills: ["./templates/pi/skills"],
-    prompts: ["./templates/pi/prompts"]
+    extensions: [
+      "./templates/pi/extensions"
+    ],
+    skills: [
+      "./templates/pi/skills"
+    ],
+    prompts: [
+      "./templates/pi/prompts"
+    ]
   };
   repository = {
     type: "git",

package/dist/exports.js

@@ -1991,7 +1991,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.150", 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.151", 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 = {
     ".": {
@@ -2002,7 +2002,10 @@ var init_package = __esm(() => {
   bin = {
     "guardian-framework": "dist/cli.js"
   };
-  files = ["dist/", "templates/"];
+  files = [
+    "dist/",
+    "templates/"
+  ];
   engines = {
     bun: ">=1.0.0"
   };
@@ -2020,9 +2023,15 @@ var init_package = __esm(() => {
     access: "public"
   };
   pi = {
-    extensions: ["./templates/pi/extensions"],
-    skills: ["./templates/pi/skills"],
-    prompts: ["./templates/pi/prompts"]
+    extensions: [
+      "./templates/pi/extensions"
+    ],
+    skills: [
+      "./templates/pi/skills"
+    ],
+    prompts: [
+      "./templates/pi/prompts"
+    ]
   };
   repository = {
     type: "git",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "guardian-framework",
-	"version": "0.1.150",
+	"version": "0.1.151",
 	"description": "Token-optimized agentic framework scaffolder with pi-first architecture",
 	"type": "module",
 	"main": "dist/exports.js",
@@ -14,7 +14,10 @@
 	"bin": {
 		"guardian-framework": "dist/cli.js"
 	},
-	"files": ["dist/", "templates/"],
+	"files": [
+		"dist/",
+		"templates/"
+	],
 	"engines": {
 		"bun": ">=1.0.0"
 	},
@@ -32,9 +35,15 @@
 		"access": "public"
 	},
 	"pi": {
-		"extensions": ["./templates/pi/extensions"],
-		"skills": ["./templates/pi/skills"],
-		"prompts": ["./templates/pi/prompts"]
+		"extensions": [
+			"./templates/pi/extensions"
+		],
+		"skills": [
+			"./templates/pi/skills"
+		],
+		"prompts": [
+			"./templates/pi/prompts"
+		]
 	},
 	"repository": {
 		"type": "git",

package/templates/pi/extensions/architect.ts

@@ -876,6 +876,10 @@ export default function architectExtension(pi: ExtensionAPI) {
 			const epicPrStrategy: "issue" | "epic" = prPerFlag === "issue" ? "issue" : "epic";
 			const useWorktree = tokens.includes("--worktree");
 			const parallelFlag = tokens.includes("--parallel");
+			// --modules a,b,c — which modules to fan out. Optional: without it the
+			// 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)
@@ -889,9 +893,12 @@ export default function architectExtension(pi: ExtensionAPI) {
 			}
 			const tddEnabled = tokens.includes("--tdd");
 
-			if (!epicName) {
+			// A name is required for a single epic; in parallel mode the module
+			// list may come from --modules or the roadmap instead.
+			if (!epicName && !parallelMode) {
 				ctx.ui.notify(
-					'Usage: /architect --epic "Epic Name" [--tracking-issue N] [--tdd] [--pr-per epic|issue] [--parallel|--worktree]',
+					'Usage: /architect --epic "Epic Name" [--tracking-issue N] [--tdd] [--pr-per epic|issue]\n' +
+						"       /architect --epic --parallel [--modules a,b,c] [--tdd] [--max N] [--force-freeze] [--dry-run]",
 					"error",
 				);
 				return;
@@ -906,45 +913,58 @@ export default function architectExtension(pi: ExtensionAPI) {
 					return;
 				}
 
-				// ── Parallel epics (--parallel / --worktree) ───────────────
-				// One module per worktree keeps parallel epics isolated; the
-				// contract-freeze gate refuses to start before shared contracts
-				// are frozen (epic-parallel.sh exits 2 when blocked).
-				if (parallelFlag || useWorktree) {
-					const reg = join(ctx.cwd, ".pi", "scripts", "epic-registry.sh");
-					if (!existsSync(reg)) {
-						ctx.ui.notify("epic-registry.sh not found — run `guardian update` to install parallel-epic scripts.", "error");
+				// ── Parallel epics: delegate the whole fan-out ───────────────
+				// epic-fanout.sh does everything in one pass: resolve the module
+				// list (explicit or roadmap order), check dependencies, freeze the
+				// contracts, create one worktree+branch per module, and spawn one
+				// headless agent per worktree.
+				//
+				// This also fixes the old behaviour where the worktree was created
+				// but the epic was started in the MAIN checkout (duplicate issues).
+				if (parallelMode) {
+					const fanout = join(ctx.cwd, ".pi", "scripts", "epic-fanout.sh");
+					if (!existsSync(fanout)) {
+						ctx.ui.notify("epic-fanout.sh not found — run `guardian update` to install parallel-epic scripts.", "error");
 						return;
 					}
-					const prep = runScript(ctx.cwd, `bash .pi/scripts/epic-parallel.sh "${epicName.replace(/"/g, '\\"')}"`);
-					if (prep.exitCode === 2) {
+					const list = (modulesFlag ?? epicName ?? "").trim();
+					const args = ["bash .pi/scripts/epic-fanout.sh"];
+					if (list) args.push(`--modules "${list.replace(/"/g, '\\"')}"`);
+					if (tddEnabled) args.push("--tdd");
+					if (tokens.includes("--force-freeze")) args.push("--force-freeze");
+					if (tokens.includes("--dry-run")) args.push("--dry-run");
+					const maxFlag = findFlag(tokens, "--max");
+					if (maxFlag) args.push(`--max ${Number(maxFlag) || 0}`);
+
+					const res = runScript(ctx.cwd, args.join(" "));
+					const out = String(res.stdout ?? "");
+					if (res.exitCode === 2) {
 						ctx.ui.notify(
-							`Parallel epic blocked: contracts for "${epicName}" are not frozen. Merge the Contract Freeze issue, then: bash .pi/scripts/epic-registry.sh freeze "${epicName}" --frozen`,
+							`Parallel epic blocked — dependencies are not satisfied.\n${out.trim().slice(-600)}`,
 							"error",
 						);
 						return;
 					}
-					if (prep.exitCode !== 0) {
-						ctx.ui.notify(`Worktree preparation failed: ${String(prep.stdout).slice(0, 300)}`, "error");
+					if (res.exitCode !== 0) {
+						ctx.ui.notify(`Fan-out failed:\n${out.trim().slice(-600)}`, "error");
 						return;
 					}
-					// Record on the epic state so later steps stay consistent.
+					// 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.worktree = String(prep.stdout).match(/worktree:\s*(\S+)/)?.[1] ?? "";
+						st.modules = list || "(roadmap order)";
 						writeFileSync(p, JSON.stringify(st, null, 2), "utf-8");
 					} catch {
 						// ignore
 					}
-					ctx.ui.notify(
-						"Parallel epic prepared — worktree + epic branch created (contracts frozen).",
-						"success",
-					);
+					ctx.ui.notify(out.trim().split("\n").slice(-12).join("\n"), "info");
+					return;
 				}
 
-				const state = await manager.startEpic(ctx, epicName, trackingIssueId, tddEnabled);
+								const state = await manager.startEpic(ctx, epicName, trackingIssueId, tddEnabled);
 
 				if (!state?.slices?.length) {
 					ctx.ui.notify("Failed to discover architecture components. Check .pi/architecture/modules/.", "error");

package/templates/pi/preflight_report.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-11-13T15:22:46Z",
+  "timestamp": "2026-11-13T16:31:02Z",
   "mode": "all",
   "stages_run": [],
   "summary": {

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

@@ -0,0 +1,355 @@
+#!/usr/bin/env bash
+# ============================================================================
+# epic-fanout.sh — start several module epics at once, fully prepared
+# ============================================================================
+# One call does everything needed for parallel epics:
+#
+#   1. resolve the modules   (--modules a,b  OR  roadmap order)
+#   2. check dependencies    (refuse if a dep is not implemented)
+#   3. freezes the contracts (registry: contractFrozen=true)
+#   4. create worktree+branch per module (epic/<module>)
+#   5. spawn one headless pi agent per worktree, logging to
+#      .git/guardian/logs/<module>.log
+#
+# Usage:
+#   epic-fanout.sh [--modules a,b,c] [--tdd] [--max N]
+#                  [--force-freeze] [--dry-run] [--no-spawn]
+#                  [--base main] [--timeout-ms N]
+#
+# Exit: 0 started/prepared · 2 blocked by a dependency · 1 error
+# ============================================================================
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+MODULES_RAW=""
+TDD=0
+MAX=0
+FORCE_FREEZE=0
+DRY_RUN=0
+NO_SPAWN=0
+BASE="main"
+TIMEOUT_MS=0
+
+while [ $# -gt 0 ]; do
+	case "$1" in
+	--modules) MODULES_RAW="${2:-}"; shift 2 ;;
+	--tdd) TDD=1; shift ;;
+	--max) MAX="${2:-0}"; shift 2 ;;
+	--force-freeze) FORCE_FREEZE=1; shift ;;
+	--dry-run) DRY_RUN=1; shift ;;
+	--no-spawn) NO_SPAWN=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 ;;
+	*) echo "unknown argument: $1" >&2; exit 1 ;;
+	esac
+done
+
+COMMON="$(git rev-parse --git-common-dir 2>/dev/null || echo ".git")"
+[ -d "$COMMON" ] || COMMON=".git"
+COMMON_ABS="$(cd "$COMMON" 2>/dev/null && pwd || echo "$COMMON")"
+LOGDIR="$COMMON_ABS/guardian/logs"
+REGISTRY="$ROOT/.pi/scripts/epic-registry.sh"
+PARALLEL="$ROOT/.pi/scripts/epic-parallel.sh"
+RUNNER="$ROOT/.pi/scripts/epic-runner.mjs"
+
+[ -f "$REGISTRY" ] || { echo "missing $REGISTRY — run guardian update" >&2; exit 1; }
+[ -f "$PARALLEL" ] || { echo "missing $PARALLEL — run guardian update" >&2; exit 1; }
+[ -f "$RUNNER" ] || { echo "missing $RUNNER — run guardian update" >&2; exit 1; }
+
+# The runner is a Node script; bun also executes it.
+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
+	exit 1
+fi
+
+# ── Resolve the module list ─────────────────────────────────────────────────
+# Explicit list wins. Otherwise take roadmap order, skipping implemented modules.
+SELECTED="$(
+	python3 - "$ROOT" "$MODULES_RAW" "$MAX" <<'PY'
+import os, re, sys
+
+root, raw, max_n = sys.argv[1], sys.argv[2], int(sys.argv[3] or 0)
+mods_dir = os.path.join(root, ".pi/architecture/modules")
+roadmap = os.path.join(root, ".pi/architecture/implementation-roadmap.md")
+
+def is_implemented(doc_slug):
+    for cand in (f"{doc_slug}.md",):
+        p = os.path.join(mods_dir, cand)
+        if not os.path.exists(p):
+            continue
+        text = open(p, encoding="utf-8", errors="ignore").read()
+        m = re.search(r"\*\*Status:\*\*\s*([A-Za-z ]+)", text)
+        if m and m.group(1).strip().lower().startswith(("implemented", "done", "complete")):
+            return True
+        if len(re.findall(r"status:\s*implemented", text, re.I)) > 0:
+            return True
+    return False
+
+def slugify(name):
+    s = name.lower()
+    s = re.sub(r"[^a-z0-9]+", "-", s).strip("-")
+    return s
+
+if raw.strip():
+    items = [m.strip() for m in raw.split(",") if m.strip()]
+    print("\n".join(items))
+    sys.exit(0)
+
+if not os.path.exists(roadmap):
+    print("__ERROR__no roadmap at .pi/architecture/implementation-roadmap.md", file=sys.stderr)
+    sys.exit(3)
+
+# Walk phases in order; collect modules from each '### Modules' table.
+order, phase = [], None
+in_modules = False
+for line in open(roadmap, encoding="utf-8", errors="ignore"):
+    stripped = line.strip()
+    if stripped.startswith("## "):
+        phase = stripped[3:].strip()
+        in_modules = False
+        continue
+    if stripped.startswith("### "):
+        in_modules = stripped[4:].strip().lower().startswith("modules")
+        continue
+    if not in_modules or not stripped.startswith("|"):
+        continue
+    cells = [c.strip() for c in stripped.strip("|").split("|")]
+    if len(cells) < 3:
+        continue
+    BT = chr(96)
+    name = cells[0].replace(BT, "").strip()
+    if not name or name.lower() in ("module", "modules") or set(name) <= set("-: "):
+        continue
+    if phase and phase.lower().startswith("phase 0"):
+        continue
+    doc = cells[-1].replace(BT, "").strip()
+    slug = os.path.basename(doc)[:-3] if doc.endswith(".md") else slugify(name)
+    order.append((phase or "", name, slug))
+
+selected, seen = [], set()
+for ph, name, slug in order:
+    if slug in seen:
+        continue
+    seen.add(slug)
+    if is_implemented(slug):
+        continue
+    selected.append(slug)
+    if max_n and len(selected) >= max_n:
+        break
+
+print("\n".join(selected))
+PY
+)"
+
+if printf '%s' "$SELECTED" | grep -q "^__ERROR__"; then
+	echo "${SELECTED#__ERROR__}" >&2
+	exit 1
+fi
+if [ -z "$SELECTED" ]; then
+	echo "Nothing to start: no planned modules found (roadmap order, implemented skipped)."
+	echo "  pass --modules a,b to name them explicitly"
+	exit 0
+fi
+
+MODULES=()
+while IFS= read -r _line; do
+	[ -n "$_line" ] && MODULES+=("$_line")
+done <<<"$SELECTED"
+
+echo "============================================"
+echo "  Parallel epic fan-out"
+echo "============================================"
+echo "  modules:  ${MODULES[*]:-}"
+echo "  tdd:      $([ "$TDD" -eq 1 ] && echo enabled || echo disabled)"
+echo "  base:     $BASE"
+[ "$DRY_RUN" -eq 1 ] && echo "  mode:     DRY RUN (nothing is created)"
+echo ""
+
+# ── Dependency gate ─────────────────────────────────────────────────────────
+# A module may only run in parallel once the modules it depends on are
+# implemented. Deps inside this same batch cannot be satisfied yet either.
+DEP_CHECK="$(python3 - "$ROOT" ${MODULES[@]+"${MODULES[@]}"} <<'PY'
+import os, re, sys
+
+root = sys.argv[1]
+batch = sys.argv[2:]
+mods_dir = os.path.join(root, ".pi/architecture/modules")
+
+def doc_path(slug):
+    p = os.path.join(mods_dir, f"{slug}.md")
+    return p if os.path.exists(p) else None
+
+def status_of(slug):
+    p = doc_path(slug)
+    if not p:
+        return "unknown"
+    text = open(p, encoding="utf-8", errors="ignore").read()
+    m = re.search(r"\*\*Status:\*\*\s*([A-Za-z ]+)", text)
+    if m:
+        s = m.group(1).strip().lower()
+        if s.startswith(("implemented", "done", "complete")):
+            return "implemented"
+        if s.startswith(("partial", "in progress", "wip")):
+            return "partial"
+        return "planned"
+    if re.search(r"status:\s*implemented", text, re.I):
+        return "implemented"
+    return "planned"
+
+def deps_of(slug):
+    p = doc_path(slug)
+    if not p:
+        return []
+    text = open(p, encoding="utf-8", errors="ignore").read()
+    m = re.search(r"\*\*Depends On:\*\*(.*?)(?:\n##|\Z)", text, re.S | re.I)
+    if not m:
+        m = re.search(r"##\s*Dependencies(.*?)(?:\n##|\Z)", text, re.S | re.I)
+    if not m:
+        return []
+    block = m.group(1)
+    if re.search(r"\bnone\b", block, re.I):
+        return []
+    found = []
+    # Inline form: '**Depends On:** Alpha, Beta' or 'Alpha' (single line, no table)
+    first = next((ln.strip() for ln in block.splitlines() if ln.strip()), "")
+    if first and not first.startswith("|") and not first.startswith("-"):
+        for part in re.split(r"[,;]", first):
+            nm = part.strip().strip(chr(96) + "* ").rstrip(".")
+            if nm and not nm.lower().startswith("none"):
+                found.append(nm)
+    for line in block.splitlines():
+        line = line.strip()
+        if not line.startswith("|"):
+            continue
+        cells = [c.strip() for c in line.strip("|").split("|")]
+        if not cells:
+            continue
+        name = cells[0].replace(chr(96), "").replace("*", "").strip()
+        if not name or name.lower() in ("module", "modules") or set(name) <= set("-: "):
+            continue
+        found.append(name)
+    # also allow "- Name" bullets
+    for line in block.splitlines():
+        line = line.strip()
+        if line.startswith("- "):
+            name = line[2:].split("—")[0].split(":")[0].strip().strip(chr(96) + "* ")
+            if name and name.lower() != "none":
+                found.append(name)
+    return found
+
+def slugify(name):
+    return re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")
+
+batch_slugs = set(batch)
+problems = []
+for slug in batch:
+    for dep_name in deps_of(slug):
+        dep = slugify(dep_name)
+        st = status_of(dep)
+        if st in ("implemented",):
+            continue
+        if dep in batch_slugs:
+            problems.append(f"{slug}: depends on '{dep_name}' which is in this same batch — start it in an earlier batch")
+        elif st == "unknown":
+            problems.append(f"{slug}: depends on '{dep_name}' which has no module doc under .pi/architecture/modules/")
+        else:
+            problems.append(f"{slug}: depends on '{dep_name}' ({st}) — not implemented yet")
+
+if problems:
+    print("\n".join(problems))
+    sys.exit(1)
+sys.exit(0)
+PY
+)"
+DEP_RC=$?
+
+if [ "$DEP_RC" -ne 0 ]; then
+	echo "⛔ Blocked — dependencies are not satisfied:"
+	echo "$DEP_CHECK" | sed 's/^/   /'
+	echo ""
+	if [ "$FORCE_FREEZE" -ne 1 ]; then
+		echo "   Parallel epics must not build on unfolded contracts."
+		echo "   Finish the dependency first, or re-run with --force-freeze to override."
+		exit 2
+	fi
+	echo "   --force-freeze given — continuing anyway (recorded in the registry)."
+	echo ""
+fi
+
+if [ "$DRY_RUN" -eq 1 ]; then
+	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/-+$//')"
+		echo "  • freeze   $m"
+		echo "  • worktree ../$(basename "$ROOT")-$slug   (branch epic/$slug)"
+		[ "$NO_SPAWN" -eq 0 ] && echo "  • spawn    pi (rpc) → log .git/guardian/logs/$slug.log"
+	done
+	exit 0
+fi
+
+# ── Freeze, create worktrees, spawn ─────────────────────────────────────────
+mkdir -p "$LOGDIR"
+STARTED=()
+FAILED=()
+
+for m in ${MODULES[@]+"${MODULES[@]}"}; do
+	slug="$(echo "$m" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//')"
+	log="$LOGDIR/$slug.log"
+
+	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_RC=$?
+	if [ "$WT_RC" -ne 0 ]; then
+		echo "  ✗ worktree failed (exit $WT_RC)"
+		echo "$WT_OUT" | sed 's/^/    /'
+		FAILED+=("$m")
+		continue
+	fi
+	WT="$(echo "$WT_OUT" | sed -n 's/.*worktree: *//p' | head -1)"
+	if [ -z "$WT" ] || [ ! -d "$WT" ]; then
+		# epic-parallel prints the path; fall back to the conventional name
+		WT="$(dirname "$ROOT")/$(basename "$ROOT")-$slug"
+	fi
+	echo "  ✓ worktree $WT"
+
+	if [ "$NO_SPAWN" -eq 1 ]; then
+		echo "  → run:  cd \"$WT\" && /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)
+	"$NODE_BIN" "$RUNNER" \
+		"/architect --epic \"$m\"$( [ "$TDD" -eq 1 ] && echo " --tdd")" \
+		--cwd "$WT" --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
+	echo "  ✓ spawned pid $PID → $log"
+	STARTED+=("$m")
+done
+
+echo "────────────────────────────────────────────"
+echo ""
+echo "Started ${#STARTED[@]}/${#MODULES[@]} epic(s)."
+[ "${#FAILED[@]}" -gt 0 ] && echo "Failed: ${FAILED[*]:-}"
+
+if [ "${#STARTED[@]}" -gt 0 ]; then
+	echo ""
+	echo "Monitor:"
+	echo "  bash .pi/scripts/epic-registry.sh list"
+	for m in ${STARTED[@]+"${STARTED[@]}"}; do
+		slug="$(echo "$m" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//')"
+		echo "  tail -f \"$LOGDIR/$slug.log\""
+	done
+fi
+[ "${#FAILED[@]}" -gt 0 ] && exit 1
+exit 0

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

@@ -116,6 +116,12 @@ PY
 		write_epic "$MOD" "contractFrozen=$V" "updatedAt=$(now)" >/dev/null
 		echo "$MOD: contractFrozen=$V"
 		;;
+	set)
+		MOD="${1:?usage: set <module> key=value ...}"; shift || true
+		if [ $# -eq 0 ]; then echo "set: need at least one key=value" >&2; exit 1; fi
+		write_epic "$MOD" "$@" >/dev/null
+		echo "$MOD: $*"
+		;;
 	list|get)
 		MOD="${1:-}"
 		ensure
@@ -133,6 +139,6 @@ else:
 PY
 		;;
 	*)
-		echo "usage: epic-registry.sh register|status|freeze|list|get|path ..." >&2
+		echo "usage: epic-registry.sh register|status|freeze|set|list|get|path ..." >&2
 		exit 1 ;;
 esac

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

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+/**
+ * epic-runner.mjs — run one Guardian command in a headless pi session.
+ *
+ * Why this exists: `pi -p "/architect ..."` does NOT dispatch extension
+ * commands (the text is sent to the model instead). RPC mode does — a
+ * `prompt` whose message is an extension command "executes immediately"
+ * (pi docs, rpc-commands.md#prompt), and reports
+ * `data.disposition: "handled"`.
+ *
+ * So we spawn `pi --mode rpc`, send the command as a prompt, mirror every
+ * JSONL event into a log, and exit when pi settles.
+ *
+ * Usage:
+ *   epic-runner.mjs "<command>" [--log <path>] [--cwd <dir>]
+ *                               [--timeout-ms N] [--session <id>]
+ *
+ * Exit codes:
+ *   0  command handled and session settled
+ *   1  failure (spawn error, rejected prompt, aborted, timeout)
+ *   3  command was NOT an extension command (fell through to the model)
+ */
+import { spawn } from "node:child_process";
+import { createWriteStream, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+function parseArgs(argv) {
+	const out = { command: null, log: null, cwd: process.cwd(), timeoutMs: 0, session: null };
+	const rest = [];
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--log") out.log = argv[++i];
+		else if (a === "--cwd") out.cwd = resolve(argv[++i]);
+		else if (a === "--timeout-ms") out.timeoutMs = Number(argv[++i]) || 0;
+		else if (a === "--session") out.session = argv[++i];
+		else rest.push(a);
+	}
+	out.command = rest.join(" ").trim();
+	return out;
+}
+
+const opts = parseArgs(process.argv.slice(2));
+if (!opts.command) {
+	console.error('usage: epic-runner.mjs "<command>" [--log path] [--cwd dir] [--timeout-ms N]');
+	process.exit(1);
+}
+
+let logStream = null;
+if (opts.log) {
+	mkdirSync(dirname(opts.log), { recursive: true });
+	logStream = createWriteStream(opts.log, { flags: "a" });
+}
+
+function emit(line) {
+	if (logStream) logStream.write(`${line}\n`);
+	process.stdout.write(`${line}\n`);
+}
+
+const args = ["--mode", "rpc"];
+// A dedicated session per runner keeps parallel agents isolated; --no-session
+// keeps the repo clean. Prefer a session when one is named.
+if (opts.session) args.push("--session-id", opts.session);
+else args.push("--no-session");
+
+const child = spawn("pi", args, {
+	cwd: opts.cwd,
+	stdio: ["pipe", "pipe", "pipe"],
+	env: process.env,
+});
+
+let settled = false;
+let handled = false;
+let failed = false;
+let buffered = "";
+
+const timer = opts.timeoutMs
+	? setTimeout(() => {
+			emit(JSON.stringify({ type: "runner_timeout", timeoutMs: opts.timeoutMs }));
+			failed = true;
+			finish(1);
+		}, opts.timeoutMs)
+	: null;
+
+function finish(code) {
+	if (settled) return;
+	settled = true;
+	if (timer) clearTimeout(timer);
+	if (typeof cancelGrace === "function") cancelGrace();
+	try {
+		child.stdin.end();
+	} catch {
+		/* ignore */
+	}
+	// give the child a moment to flush, then stop it
+	setTimeout(() => {
+		try {
+			child.kill("SIGTERM");
+		} catch {
+			/* ignore */
+		}
+		logStream?.end();
+		process.exit(code);
+	}, 250);
+}
+
+function handleLine(line) {
+	if (!line.trim()) return;
+	emit(line);
+	let msg;
+	try {
+		msg = JSON.parse(line);
+	} catch {
+		return;
+	}
+	// 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();
+	}
+	if (msg.type === "response" && msg.command === "prompt" && msg.success === false) {
+		emit(JSON.stringify({ type: "runner_error", reason: "prompt rejected" }));
+		failed = true;
+		finish(1);
+	}
+	// A low-level run started: the command is doing real work, so wait for the
+	// settle event instead of using the grace timer.
+	if (msg.type === "agent_start") {
+		sawRun = true;
+		cancelGrace();
+	}
+	if (msg.type === "agent_settled") {
+		finish(msg.aborted ? 1 : 0);
+	}
+}
+
+// A "handled" extension command may start no LLM run at all (e.g. /architect
+// status), in which case `agent_settled` never fires and stdin stays open. If
+// no run activity appears within the grace window, treat the command as done.
+// pi docs (rpc.md#prompt): with disposition "handled", don't wait for
+// agent_settled unless the extension itself starts work.
+const GRACE_MS = Number(process.env.GUARDIAN_RUNNER_GRACE_MS || 5000);
+let graceTimer = null;
+let sawRun = false;
+
+function cancelGrace() {
+	if (graceTimer) {
+		clearTimeout(graceTimer);
+		graceTimer = null;
+	}
+}
+
+function armGrace() {
+	cancelGrace();
+	graceTimer = setTimeout(() => {
+		if (!sawRun) {
+			emit(JSON.stringify({ type: "runner_done", reason: "handled, no run started" }));
+			finish(0);
+		}
+	}, GRACE_MS);
+}
+
+child.stdout.on("data", (buf) => {
+	buffered += buf.toString();
+	let idx = buffered.indexOf("\n");
+	while (idx !== -1) {
+		handleLine(buffered.slice(0, idx));
+		buffered = buffered.slice(idx + 1);
+		idx = buffered.indexOf("\n");
+	}
+});
+
+child.stderr.on("data", (buf) => {
+	for (const line of buf.toString().split("\n")) {
+		if (line.trim()) emit(JSON.stringify({ type: "stderr", line }));
+	}
+});
+
+child.on("error", (err) => {
+	emit(JSON.stringify({ type: "runner_error", reason: String(err) }));
+	failed = true;
+	finish(1);
+});
+
+child.on("exit", (code) => {
+	if (buffered.trim()) handleLine(buffered);
+	if (settled) return;
+	// Settle on exit: a handled command that ended cleanly is a success.
+	finish(failed ? 1 : handled && code === 0 ? 0 : handled ? 0 : 3);
+});
+
+// Send the prompt once the session is up. pi reads JSONL from stdin.
+child.stdin.write(`${JSON.stringify({ id: "1", type: "prompt", message: opts.command })}\n`);