guardian-framework 0.1.145 → 0.1.147

package/dist/cli.js

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

package/templates/pi/extensions/architect-lib/generators.ts

@@ -692,8 +692,15 @@ run_stage "11" "${moduleId}_proofing" \\
  */
 export function moduleHasRuntimeIntegration(cwd: string, moduleId: string): boolean {
 	const doc = readModuleDoc(cwd, moduleId);
-	if (!doc) return false;
-	return /^#{2,3}\s+(Integration|Runtime|Dispatch|Wiring|.*Dispatch.*)/im.test(doc);
+	// Unconditional: every module that ships code must be installed in the
+	// application shell. Previously this was gated on the module doc having an
+	// Integration/Runtime heading, so a doc without that heading silently
+	// skipped wiring — the "implemented but never wired" gap (ADR-009).
+	// Only an explicit opt-out in the doc removes the deliverable.
+	if (doc && /^.{0,80}(not wired by design|bootstrap only|no runtime integration|not part of the runtime)/im.test(doc)) {
+		return false;
+	}
+	return true;
 }
 
 export function generateRuntimeIntegrationMarkdown(

package/templates/pi/extensions/architect.ts

@@ -492,7 +492,7 @@ export default function architectExtension(pi: ExtensionAPI) {
 			const tokens = raw ? parseArgs(raw) : [];
 			if (tokens.length === 0) {
 				ctx.ui.notify(
-					"Usage: /architect [--epic Name] [--tracking-issue N] [--tdd] [--pr-per epic|issue] | --roadmap | --phase \"Phase 1\" | --phase-status | --phase-done <N> | --phase-module-done <N> \"Module\" | status | next-epic | abort",
+					"Usage: /architect [--epic Name] [--tracking-issue N] [--tdd] [--pr-per epic|issue] [--parallel|--worktree] | --roadmap | --phase \"Phase 1\" | --phase-status | --phase-done <N> | --phase-module-done <N> \"Module\" | status | next-epic | abort",
 					"info",
 				);
 				return;
@@ -635,7 +635,7 @@ export default function architectExtension(pi: ExtensionAPI) {
 								items: existingIssues,
 								steps: [
 									{ name: "implement", prompt: ".pi/prompts/issue-implementation-series.md", acceptance: { type: "validator", validators: ["ci"] } },
-									{ name: "validate", acceptance: { type: "validator", validators: ["ci", "tests", "security"] } },
+									{ name: "validate", acceptance: { type: "validator", validators: ["ci", "tests", "security", "wiring"] } },
 									{ name: "create-mr", prompt: ".pi/prompts/epic-closeout.md", acceptance: { type: "none" } },
 									{ name: "merge", prompt: ".pi/prompts/epic-closeout.md", acceptance: { type: "validator", validators: ["ci", "canonical"] } },
 								],
@@ -697,7 +697,7 @@ export default function architectExtension(pi: ExtensionAPI) {
 							items,
 							steps: [
 								{ name: "implement", prompt: ".pi/prompts/issue-implementation-series.md", acceptance: { type: "validator", validators: ["ci"] } },
-								{ name: "validate", acceptance: { type: "validator", validators: ["ci", "tests", "security"] } },
+								{ name: "validate", acceptance: { type: "validator", validators: ["ci", "tests", "security", "wiring"] } },
 								{ name: "create-mr", prompt: ".pi/prompts/epic-closeout.md", acceptance: { type: "none" } },
 								{ name: "merge", prompt: ".pi/prompts/epic-closeout.md", acceptance: { type: "validator", validators: ["ci", "canonical"] } },
 							],
@@ -863,6 +863,8 @@ export default function architectExtension(pi: ExtensionAPI) {
 			// legacy per-issue PR flow.
 			const prPerFlag = (findFlag(tokens, "--pr-per") ?? "epic").toLowerCase();
 			const epicPrStrategy: "issue" | "epic" = prPerFlag === "issue" ? "issue" : "epic";
+			const useWorktree = tokens.includes("--worktree");
+			const parallelFlag = tokens.includes("--parallel");
 			try {
 				const epicStatePath = join(ctx.cwd, ".pi", ".guardian-epic-state.json");
 				const st = existsSync(epicStatePath)
@@ -887,6 +889,44 @@ 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");
+						return;
+					}
+					const prep = runScript(ctx.cwd, `bash .pi/scripts/epic-parallel.sh "${epicName.replace(/"/g, '\\"')}"`);
+					if (prep.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`,
+							"error",
+						);
+						return;
+					}
+					if (prep.exitCode !== 0) {
+						ctx.ui.notify(`Worktree preparation failed: ${String(prep.stdout).slice(0, 300)}`, "error");
+						return;
+					}
+					// Record on the epic 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.parallel = true;
+						st.worktree = String(prep.stdout).match(/worktree:\s*(\S+)/)?.[1] ?? "";
+						writeFileSync(p, JSON.stringify(st, null, 2), "utf-8");
+					} catch {
+						// ignore
+					}
+					ctx.ui.notify(
+						"Parallel epic prepared — worktree + epic branch created (contracts frozen).",
+						"success",
+					);
+				}
+
 				const state = await manager.startEpic(ctx, epicName, trackingIssueId, tddEnabled);
 
 				if (!state?.slices?.length) {
@@ -924,7 +964,7 @@ export default function architectExtension(pi: ExtensionAPI) {
 					items,
 					steps: [
 						{ name: "implement", prompt: ".pi/prompts/issue-implementation-series.md", acceptance: { type: "validator", validators: ["ci"] } },
-						{ name: "validate", acceptance: { type: "validator", validators: ["ci", "tests", "security"] } },
+						{ name: "validate", acceptance: { type: "validator", validators: ["ci", "tests", "security", "wiring"] } },
 						{ name: "create-mr", prompt: ".pi/prompts/epic-closeout.md", acceptance: { type: "none" } },
 						{ name: "merge", prompt: ".pi/prompts/epic-closeout.md", acceptance: { type: "validator", validators: ["ci", "canonical"] } },
 					],

package/templates/pi/extensions/epic.ts

@@ -0,0 +1,113 @@
+// Canonical Reference: .pi/architecture/modules/epic-parallel.md#epic-command
+/**
+ * /epic — parallel epic scale-out (companion to /architect --epic).
+ *
+ * One module -> one epic branch -> one worktree -> one PR. The command shares
+ * the same registry + contract-freeze gate as /architect --parallel so both
+ * entry points behave identically.
+ *
+ *   /epic parallel "<Module>"     create worktree + branch (gated)
+ *   /epic freeze "<Module>"       record that contracts are frozen
+ *   /epic status                  list registered epics (all worktrees)
+ *   /epic prompt                  show the scale-out procedure
+ */
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+type ExtensionContext = { cwd: string; ui: { notify(message: string, level?: string): void } };
+type ExtensionAPI = {
+	registerCommand(
+		name: string,
+		options: { description: string; handler(args: unknown, ctx: ExtensionContext): unknown },
+	): void;
+};
+
+function unquote(s: string): string {
+	return s.trim().replace(/^["']|["']$/g, "");
+}
+
+function run(cwd: string, cmd: string): { code: number; out: string } {
+	try {
+		const out = execSync(cmd, { cwd, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+		return { code: 0, out };
+	} catch (e) {
+		const err = e as { status?: number; stdout?: string; stderr?: string };
+		return { code: err.status ?? 1, out: `${err.stdout ?? ""}${err.stderr ?? ""}` };
+	}
+}
+
+export default function epicExtension(pi: ExtensionAPI) {
+	pi.registerCommand("epic", {
+		description: "Parallel epics: one worktree per module, gated on frozen contracts",
+		handler: async (args: unknown, ctx: ExtensionContext) => {
+			const raw = String(args ?? "").trim();
+			const [action, ...rest] = raw.split(/\s+/);
+			const moduleName = unquote(rest.join(" "));
+
+			if (!action) {
+				ctx.ui.notify(
+					[
+						"Usage:",
+						'  /epic parallel "<Module>"   create worktree + epic branch (requires frozen contracts)',
+						'  /epic freeze "<Module>"     record that shared contracts are frozen',
+						"  /epic status                list registered epics across worktrees",
+						"  /epic prompt                show the scale-out procedure",
+					].join("\n"),
+					"info",
+				);
+				return;
+			}
+
+			if (action === "freeze") {
+				if (!moduleName) {
+					ctx.ui.notify('Usage: /epic freeze "<Module>"', "error");
+					return;
+				}
+				const r = run(ctx.cwd, `bash .pi/scripts/epic-registry.sh freeze "${moduleName}" --frozen`);
+				ctx.ui.notify(r.code === 0 ? `Contracts frozen for "${moduleName}"` : r.out.slice(0, 300), r.code === 0 ? "success" : "error");
+				return;
+			}
+
+			if (action === "parallel") {
+				if (!moduleName) {
+					ctx.ui.notify('Usage: /epic parallel "<Module>"', "error");
+					return;
+				}
+				const r = run(ctx.cwd, `bash .pi/scripts/epic-parallel.sh "${moduleName}"`);
+				if (r.code === 2) {
+					ctx.ui.notify(
+						`Blocked: contracts for "${moduleName}" are not frozen. Merge the Contract Freeze issue, then /epic freeze "${moduleName}".`,
+						"error",
+					);
+					return;
+				}
+				ctx.ui.notify(
+					r.code === 0
+						? `Worktree ready for "${moduleName}". Next: cd into it and run /architect --epic "${moduleName}"`
+						: r.out.slice(0, 400),
+					r.code === 0 ? "success" : "error",
+				);
+				return;
+			}
+
+			if (action === "status") {
+				const r = run(ctx.cwd, "bash .pi/scripts/epic-registry.sh list");
+				ctx.ui.notify(r.out || "(no epics registered)", "info");
+				return;
+			}
+
+			if (action === "prompt") {
+				const p = join(ctx.cwd, ".pi", "prompts", "epic-parallel.md");
+				if (existsSync(p)) {
+					ctx.ui.notify(`Procedure: ${p}`, "info");
+					return readFileSync(p, "utf-8");
+				}
+				ctx.ui.notify("Run `bash .pi/scripts/epic-parallel.sh <Module>` after freezing contracts.", "info");
+				return;
+			}
+
+			ctx.ui.notify(`Unknown /epic action "${action}". Try /epic for usage.`, "error");
+		},
+	});
+}

package/templates/pi/extensions/pipeline.ts

@@ -43,6 +43,8 @@ const VALIDATOR_SCRIPTS: Record<string, string> = {
 	architecture: ".pi/scripts/validate-architecture.sh",
 	canonical: ".pi/scripts/validate-canonical.sh",
 	integration: ".pi/scripts/validate-integration.sh",
+	// ADR-009: implemented modules must be INSTALLED in the composition root
+	wiring: ".pi/scripts/check_composition_root.sh",
 };
 
 // ── Helpers ──
@@ -1443,7 +1445,7 @@ function buildSteps(stepNames: string[]): StepConfig[] {
 		},
 		validate: {
 			name: "validate",
-			acceptance: { type: "validator", validators: ["ci", "tests", "security"] },
+			acceptance: { type: "validator", validators: ["ci", "tests", "security", "wiring"] },
 		},
 		"create-mr": {
 			name: "create-mr",

package/templates/pi/preflight_report.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-11-07T13:17:56Z",
+  "timestamp": "2026-11-07T13:34:25Z",
   "mode": "all",
   "stages_run": [],
   "summary": {

package/templates/pi/prompts/epic-parallel.md

@@ -0,0 +1,54 @@
+# Epic Scale-out — start parallel epics (one worktree per module)
+
+<!--
+Canonical Reference: .pi/prompts/epic-parallel.md
+Implements: parallel epics (/architect --parallel / --worktree and /epic)
+-->
+
+**Purpose:** Run several module epics at the same time without them colliding on
+shared contracts. One module → one epic branch → one worktree → one PR.
+
+---
+
+## Preconditions
+
+1. **Contracts frozen.** The module's shared contracts (ports, DTOs, error envelope,
+   composition-root seam) are merged to the base branch. Parallel epics must never
+   redefine shared contracts — that is what produces merge conflicts and rework.
+2. Clean base: `git status` clean, `main` up to date.
+
+---
+
+## Procedure (per module, can be repeated in parallel)
+
+```bash
+# 1. Record the contract freeze (done once, after the freeze issue merges)
+bash .pi/scripts/epic-registry.sh freeze "<Module>" --frozen
+
+# 2. Create the worktree + epic branch (blocked with exit 2 if not frozen)
+bash .pi/scripts/epic-parallel.sh "<Module>"
+
+# 3. In the new worktree, start the epic (epic mode: one branch, one PR)
+cd ../<repo>-<module>
+/architect --epic "<Module>"
+```
+
+Repeat steps 2–3 for each additional module — the worktrees are isolated, so the
+epics run concurrently. Each epic still commits only to its own `epic/<module>`
+branch and opens exactly one PR at the end (epic mode).
+
+---
+
+## Rules
+
+- **Never** start two epics for the same module in parallel.
+- **Never** bypass the freeze gate; if it blocks, run the Contract Freeze issue first.
+- Register/new worktrees are visible across all worktrees via the shared registry
+  (`.git/guardian/epics.json`):
+
+```bash
+bash .pi/scripts/epic-registry.sh list
+```
+
+- Merge order: freeze branches first, then epics in dependency order (see the
+  roadmap `### Dependencies`). An epic whose dependency is not merged must wait.

package/templates/pi/scripts/check_composition_root.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# ============================================================================
+# check_composition_root.sh — implemented modules must be INSTALLED in the app
+# ============================================================================
+# ADR-009 gap: "referenced outside the module" is not "wired into the runtime".
+# A service can be imported by one stray helper and still never be registered in
+# the composition root — the app boots and the feature does not exist.
+#
+# This check asserts, per implemented module, that the app shell references it:
+#   python  : FastAPI include_router / container build / app.add_*
+#   java    : Spring @Bean / @ComponentScan / new *Configuration / @Import
+#   typescript: app.use( / router registration / createRouter / bootstrap
+#   go      : handler registration / mux.Handle / router.Register
+#   rust    : router/handler registration in main or app module
+#
+# Exemptions: modules whose doc declares "not wired by design" or bootstrap-only.
+# Usage: bash .pi/scripts/check_composition_root.sh [--root <dir>] [--strict]
+# Exit:  0 all implemented modules installed; 1 unwired module(s)
+# ============================================================================
+set -uo pipefail
+ROOT="$(pwd)"
+ARGS=("$@")
+for ((i=0;i<${#ARGS[@]};i++)); do
+	case "${ARGS[$i]}" in
+		--root) ROOT="${ARGS[$((i+1))]:-$ROOT}" ;;
+	esac
+done
+cd "$ROOT" || exit 1
+
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m'
+echo "============================================"
+echo "  Composition Root (implemented = installed)"
+echo "============================================"
+
+# ── language + app shell candidates ──────────────────────────────────────────
+LANG_NAME=""
+[ -f guardian-manifest.json ] && LANG_NAME=$(python3 -c "import json;print(json.load(open('guardian-manifest.json')).get('language',''))" 2>/dev/null || true)
+echo "Language: ${LANG_NAME:-unknown}"
+
+SHALLS=()
+case "$LANG_NAME" in
+	python|nextjs|angular|typescript)
+		while IFS= read -r f; do SHALLS+=("$f"); done < <(find src app -maxdepth 4 -type f \( -name "app.py" -o -name "main.py" -o -name "__main__.py" -o -name "server.ts" -o -name "main.ts" -o -name "index.ts" \) 2>/dev/null | grep -vE "test|spec" | head -6)
+		COVER_PATTERN="include_router|add_router|app\.use\(|createRouter|register_module|build_container|@Module"
+		;;
+	java)
+		while IFS= read -r f; do SHALLS+=("$f"); done < <(find src/main/java -maxdepth 10 -type f \( -name "*Application.java" -o -name "*Configuration.java" -o -name "*Config.java" \) 2>/dev/null | head -8)
+		COVER_PATTERN="@Bean|@ComponentScan|@Import|@EnableAutoConfiguration|@SpringBootApplication"
+		;;
+	go)
+		while IFS= read -r f; do SHALLS+=("$f"); done < <(find . -maxdepth 4 -type f -name "main.go" 2>/dev/null | head -4)
+		COVER_PATTERN="http.Handle|mux.Handle|router.Register|\.Use\(|RegisterRoutes"
+		;;
+	rust)
+		while IFS= read -r f; do SHALLS+=("$f"); done < <(find . -maxdepth 4 -type f -name "main.rs" 2>/dev/null | grep -v target | head -4)
+		COVER_PATTERN="\.route\(|Router::new|add_route|register_handler|\.merge\("
+		;;
+esac
+
+if [ "${#SHALLS[@]}" -eq 0 ]; then
+	echo ""
+	if [ "$LANG_NAME" = "python" ] || [ "$LANG_NAME" = "typescript" ]; then
+		echo -e "${RED}❌ FAIL${NC} no application shell found (expected src/**/app.py|main.py or app.use/bootstrap)"
+		exit 1
+	fi
+	echo "no application shell detected for $LANG_NAME — skipping"
+	exit 0
+fi
+
+echo "App shell(s): ${SHALLS[*]}"
+SHELL_TEXT=$(cat "${SHALLS[@]}" 2>/dev/null)
+
+# ── modules that claim implementation ────────────────────────────────────────
+MODS=()
+if [ -d .pi/architecture/modules ]; then
+	while IFS= read -r f; do
+		b=$(basename "$f" .md)
+		[ "$b" = "module-template" ] && continue
+		# Skip docs that explicitly declare they are not runtime-installed.
+		grep -qiE "not wired by design|bootstrap only|no runtime integration|not part of the runtime" "$f" && continue
+		MODS+=("$b")
+	done < <(find .pi/architecture/modules -name "*.md" -type f | sort)
+fi
+
+if [ "${#MODS[@]}" -eq 0 ]; then
+	echo "no module docs — skipping"
+	exit 0
+fi
+
+UNWIRED=0
+for m in "${MODS[@]}"; do
+	# normalize: identity-access -> identity_access, identityaccess
+	norm=$(echo "$m" | tr -d '_-' )
+	matched=0
+	# 1) shell text mentions the module (router import, container build, bean, etc.)
+	if echo "$SHELL_TEXT" | grep -qiE "(^|[^a-z0-9])${m//-/[-_ ]}($|[^a-z0-9])"; then matched=1; fi
+	if [ "$matched" -eq 0 ] && echo "$SHELL_TEXT" | grep -qi "$norm"; then matched=1; fi
+	# 2) shell imports a file from the module package (language-agnostic)
+	if [ "$matched" -eq 0 ]; then
+		while IFS= read -r sh; do
+			if grep -qE "(from|import)\s+[\"']?${m//-/[_ ]}|${norm}" "$sh" 2>/dev/null; then matched=1; break; fi
+		done < <(printf '%s\n' "${SHALLS[@]}")
+	fi
+	# 3) the shell has at least one registration call AND imports the module (covered above)
+	if [ "$matched" -eq 0 ]; then
+		echo -e "${RED}❌ FAIL${NC} ${m}: implemented but NOT installed in the app shell (${SHALLS[0]})"
+		UNWIRED=$((UNWIRED+1))
+	fi
+done
+
+if [ "$UNWIRED" -eq 0 ]; then
+	echo ""
+	echo -e "${GREEN}✅ PASS${NC} all ${#MODS[@]} module(s) installed in the composition root"
+	exit 0
+fi
+echo ""
+echo -e "${RED}❌ FAIL${NC} ${UNWIRED}/${#MODS[@]} module(s) implemented but never wired into the app"
+echo "   Fix: register the module in ${SHALLS[0]} (router/bean/handler/container) and"
+echo "        add an end-to-end test through the public entrypoint."
+exit 1

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

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# ============================================================================
+# epic-parallel.sh — start an epic in its own git worktree (parallel epics)
+# ============================================================================
+# Parallel epics work when (a) each module is isolated in its own worktree,
+# (b) there is one epic branch per module, and (c) the module's shared
+# contracts are FROZEN (merged) so the parallel work cannot redefine them.
+#
+# Run as: bash .pi/scripts/epic-parallel.sh <module> [--base main] [--dir <path>]
+# Exit:  0 worktree ready · 2 blocked by contract freeze · 1 error
+# ============================================================================
+set -uo pipefail
+
+MODULE="${1:-}"
+shift || true
+BASE="main"; DIR=""
+while [ $# -gt 0 ]; do
+	case "$1" in
+		--base) BASE="${2:-main}"; shift 2 ;;
+		--dir) DIR="${2:-}"; shift 2 ;;
+		*) shift ;;
+	esac
+done
+
+if [ -z "$MODULE" ]; then
+	echo "usage: epic-parallel.sh <module> [--base main] [--dir <path>]" >&2
+	exit 1
+fi
+
+slug() { echo "$1" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//'; }
+BRANCH="epic/$(slug "$MODULE")"
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || { echo "not a git repo" >&2; exit 1; }
+REG="$(git rev-parse --git-common-dir 2>/dev/null || echo "$ROOT/.git")"
+[ -d "$REG" ] || REG="$ROOT/.git"
+REPO_NAME="$(basename "$ROOT")"
+[ -z "$DIR" ] && DIR="$(dirname "$ROOT")/${REPO_NAME}-$(slug "$MODULE")"
+
+echo "============================================"
+echo "  Parallel epic: $MODULE"
+echo "============================================"
+echo "  branch:   $BRANCH"
+echo "  worktree: $DIR"
+echo ""
+
+# ── Contract-freeze gate ────────────────────────────────────────────────────
+# An epic may only run in parallel once its shared contracts are frozen. The
+# registry is the source of truth (set by the contract-freeze issue / a human).
+REG_FILE="$REG/guardian/epics.json"
+FROZEN="unknown"
+if [ -f "$REG_FILE" ]; then
+	FROZEN=$(python3 - "$REG_FILE" "$MODULE" <<'PY' 2>/dev/null || echo unknown
+import json,sys
+d=json.load(open(sys.argv[1]))
+e=d.get("epics",{}).get(sys.argv[2],{})
+print("true" if e.get("contractFrozen") else ("false" if e else "unknown"))
+PY
+)
+fi
+
+if [ "$FROZEN" != "true" ]; 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)."
+	echo ""
+	echo "   Parallel epics must not redefine shared contracts. Freeze first:"
+	echo "     1. run the epic's Contract Freeze issue and merge it to $BASE"
+	echo "     2. record it:  bash .pi/scripts/epic-registry.sh freeze \"$MODULE\" --frozen"
+	echo ""
+	echo "   (single-epic work does not need this gate)"
+	exit 2
+fi
+
+# ── Worktree creation ───────────────────────────────────────────────────────
+if [ -e "$DIR" ]; then
+	echo "worktree path already exists: $DIR"
+elif git show-ref --verify --quiet "refs/heads/$BRANCH"; then
+	echo "branch exists — attaching worktree"
+	git worktree add "$DIR" "$BRANCH" || exit 1
+else
+	echo "creating branch + worktree from origin/$BASE"
+	git fetch origin "$BASE" --quiet 2>/dev/null || true
+	git worktree add -b "$BRANCH" "$DIR" "origin/$BASE" 2>/dev/null || \
+		git worktree add -b "$BRANCH" "$DIR" "$BASE" || exit 1
+fi
+
+# ── Register in the shared registry ─────────────────────────────────────────
+if [ -x "$ROOT/.pi/scripts/epic-registry.sh" ]; then
+	bash "$ROOT/.pi/scripts/epic-registry.sh" register "$MODULE" --branch "$BRANCH" --worktree "$DIR" --status running
+fi
+
+echo ""
+echo "✅ Worktree ready."
+echo "   Next: cd \"$DIR\" && /architect --epic \"$MODULE\""
+echo "   The epic runs in epic mode: one branch, local CI per issue, one PR at the end."

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

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# ============================================================================
+# epic-registry.sh — project-level epic registry shared across git worktrees
+# ============================================================================
+# Worktrees each have their own .pi/ directory, so epic state is invisible
+# across parallel /architect sessions. The registry lives in the git COMMON
+# dir (shared by all worktrees) and records: module, branch, worktree path,
+# status, contract-freeze state and the shared dependencies the module needs.
+#
+# Run as:
+#   epic-registry.sh register <module> [--branch B] [--worktree P] [--status S]
+#   epic-registry.sh status <module> <status>
+#   epic-registry.sh freeze   <module> [--frozen|--pending]
+#   epic-registry.sh list
+#   epic-registry.sh get <module>
+#   epic-registry.sh path                 # registry file path
+# ============================================================================
+set -uo pipefail
+
+common_dir() {
+	git rev-parse --git-common-dir 2>/dev/null || echo ".git"
+}
+COMMON="$(common_dir)"
+[ -d "$COMMON" ] || COMMON=".git"
+# Absolute path: the registry must be addressable from any worktree/cwd.
+COMMON_ABS="$(cd "$COMMON" 2>/dev/null && pwd || echo "$COMMON")"
+REG="$COMMON_ABS/guardian/epics.json"
+mkdir -p "$(dirname "$REG")" 2>/dev/null || true
+
+now() { date -u +"%Y-%m-%dT%H:%M:%SZ"; }
+
+ensure() {
+	[ -f "$REG" ] || echo '{"version":1,"epics":{}}' > "$REG"
+}
+
+read_epic() {
+	local mod="$1"
+	python3 - "$REG" "$mod" <<'PY' 2>/dev/null || echo "{}"
+import json,sys
+path,mod=sys.argv[1],sys.argv[2]
+try:
+    d=json.load(open(path))
+except Exception:
+    d={"version":1,"epics":{}}
+print(json.dumps(d.get("epics",{}).get(mod,{})))
+PY
+}
+
+write_epic() {
+	local mod="$1"; shift
+	python3 - "$REG" "$mod" "$@" <<'PY'
+import json,sys,os
+path,mod=sys.argv[1],sys.argv[2]
+pairs=sys.argv[3:]
+try:
+    d=json.load(open(path))
+except Exception:
+    d={"version":1,"epics":{}}
+d.setdefault("epics",{})
+e=d["epics"].get(mod,{})
+for p in pairs:
+    k,_,v=p.partition("=")
+    if v in ("true","false"):
+        e[k]=v=="true"
+    else:
+        e[k]=v
+e.setdefault("module",mod)
+d["epics"][mod]=e
+os.makedirs(os.path.dirname(path),exist_ok=True)
+json.dump(d,open(path,"w"),indent=2)
+print(json.dumps(e))
+PY
+}
+
+cmd="${1:-}"; shift || true
+case "$cmd" in
+	path) ensure; echo "$REG" ;;
+	register)
+		MOD="${1:?usage: register <module> [--branch B] [--worktree P]}"; shift || true
+		BRANCH=""; WT=""; STATUS="running"
+		while [ $# -gt 0 ]; do
+			case "$1" in
+				--branch) BRANCH="${2:-}"; shift 2 ;;
+				--worktree) WT="${2:-}"; shift 2 ;;
+				--status) STATUS="${2:-}"; shift 2 ;;
+				*) shift ;;
+			esac
+		done
+		[ -z "$BRANCH" ] && BRANCH="epic/$(echo "$MOD" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//')"
+		[ -z "$WT" ] && WT="$(cd "$(dirname "$0")/../.." 2>/dev/null && git rev-parse --show-toplevel 2>/dev/null || pwd)"
+		FNOW="$(now)"
+		# Preserve an already-frozen contract: re-registering (e.g. a worktree
+		# restarted) must never silently un-freeze a module.
+		PRESENT=$(read_epic "$MOD")
+		KEEP_FROZEN=$(python3 - "$PRESENT" <<'PY' 2>/dev/null || echo ""
+import json,sys
+try:
+    e=json.loads(sys.argv[1])
+except Exception:
+    e={}
+print("true" if e.get("contractFrozen") else "false")
+PY
+)
+		[ -z "$KEEP_FROZEN" ] && KEEP_FROZEN="false"
+		write_epic "$MOD" "branch=$BRANCH" "worktree=$WT" "status=$STATUS" "registeredAt=$FNOW" "updatedAt=$FNOW" "contractFrozen=$KEEP_FROZEN" >/dev/null
+		echo "registered $MOD -> $BRANCH ($WT)"
+		;;
+	status)
+		MOD="${1:?usage: status <module> <status>}"; ST="${2:?}"
+		write_epic "$MOD" "status=$ST" "updatedAt=$(now)" >/dev/null
+		echo "$MOD: $ST"
+		;;
+	freeze)
+		MOD="${1:?usage: freeze <module> [--frozen|--pending]}"; shift || true
+		V="true"; [ "${1:-}" = "--pending" ] && V="false"
+		write_epic "$MOD" "contractFrozen=$V" "updatedAt=$(now)" >/dev/null
+		echo "$MOD: contractFrozen=$V"
+		;;
+	list|get)
+		MOD="${1:-}"
+		ensure
+		python3 - "$REG" "$cmd" "$MOD" <<'PY'
+import json,sys
+path,mode,mod=sys.argv[1],sys.argv[2],sys.argv[3]
+d=json.load(open(path))
+epics=d.get("epics",{})
+if mode=="get":
+    print(json.dumps(epics.get(mod,{}),indent=2))
+else:
+    if not epics: print("(no epics registered)")
+    for m,e in sorted(epics.items()):
+        print(f"{m:32} {e.get('status','?'):12} frozen={'yes' if e.get('contractFrozen') else 'no ':3} branch={e.get('branch','?')} worktree={e.get('worktree','?')}")
+PY
+		;;
+	*)
+		echo "usage: epic-registry.sh register|status|freeze|list|get|path ..." >&2
+		exit 1 ;;
+esac