guardian-framework 0.1.7 → 0.1.9

package/README.md

@@ -314,6 +314,11 @@ guardian update --regenerate   # Update and regenerate exports
 | `/architect status` | Current epic progress |
 | `/architect next-epic` | Find next logical slice |
 | `/architect abort` | Cancel epic |
+| `/architect --roadmap` | Show all roadmap phases with status |
+| `/architect --phase "Phase 1"` | Start a roadmap phase — creates epics for all modules |
+| `/architect --phase-status` | Show current/next pending phase |
+| `/architect --phase-done <N>` | Mark a phase complete |
+| `/architect --phase-module-done <N> "Module"` | Mark a module done within a phase |
 | `/domain --explore "..."` | Start domain exploration |
 | `/domain --validate <id>` | Validate against domain files |
 | `/domain --architect-scaffold <id>` | Generate module docs from exploration |
@@ -344,6 +349,7 @@ Tools callable programmatically by the agent during a session:
 | `guardian_goal_evaluate` | Evaluate goal progress (validator + LLM judge) |
 | `architect_status` | Show epic state |
 | `architect_discover` | Find modules + next slice |
+| `architect_roadmap` | Show roadmap phases and status |
 | `pipeline_status` | Pipeline progress |
 | `pipeline_advance` | Mark step passed |
 | `pipeline_fail` | Mark step failed |

package/dist/cli.js

@@ -1335,7 +1335,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.7", 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.9", 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

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

package/templates/pi/agent/AGENTS.md

@@ -77,6 +77,7 @@ delegation:
 4. **DRY context** — Shared knowledge lives in `.pi/context/`, not scattered across agent files.
 5. **Shift-left validation** — Plans are validated before code is written.
 6. **Auto-advance pipeline** — After completing a step, immediately call `pipeline_advance` to move to the next step/item. Do NOT ask the user for permission — just advance and continue.
+7. **Auto-advance epics** — When you merge the last issue of an epic (architecture readiness), immediately start the next epic by running `/architect --epic "Next Module Name"`. Check the roadmap with `/architect --roadmap` to see which module is next. Do NOT ask the user — check the roadmap yourself and proceed.
 
 ## Commands
 

package/templates/pi/architecture/implementation-roadmap.md

@@ -0,0 +1,99 @@
+# Implementation Roadmap
+
+<!--
+@canonical .pi/architecture/implementation-roadmap.md
+Status: Proposed
+Date: [Date]
+-->
+
+## Overview
+
+This roadmap defines the phased implementation of the project, organizing bounded
+contexts into delivery phases with explicit dependencies, database migrations, and
+acceptance criteria.
+
+**Format conventions:**
+- Each `## Phase N` section defines one delivery phase
+- `### Modules` table lists the bounded contexts implemented in this phase
+- `### Dependencies` lists phase prerequisites
+- `### Database Migrations` lists SQL migration files
+- `### Acceptance Criteria` lists verifiable checkboxes
+
+---
+
+## Phase 0: [Phase Name] (Days [Start]–[End])
+
+**Goal:** [One-sentence goal for this phase]
+
+### Modules
+
+| Module | Deliverables | Architecture Doc |
+|--------|-------------|------------------|
+| [Module Name] | [Key deliverables] | `.pi/architecture/modules/[module].md` |
+| [Module Name] | [Key deliverables] | `.pi/architecture/modules/[module].md` |
+
+### Dependencies
+
+- [Phase name or "None"]
+
+### Database Migrations
+
+- `NNN_[migration_name]`: [Description of what it creates]
+
+### Acceptance Criteria
+
+- [ ] [Verifiable criterion]
+- [ ] [Verifiable criterion]
+
+---
+
+## Phase 1: [Phase Name] (Days [Start]–[End])
+
+**Goal:** [One-sentence goal for this phase]
+
+### Modules
+
+| Module | Deliverables | Architecture Doc |
+|--------|-------------|------------------|
+| [Module Name] | [Key deliverables] | `.pi/architecture/modules/[module].md` |
+
+### Dependencies
+
+- Phase 0
+
+### Database Migrations
+
+- `NNN_[migration_name]`: [Description]
+
+### Acceptance Criteria
+
+- [ ] [Verifiable criterion]
+
+---
+
+## Dependency Graph
+
+```
+Phase 0 ([Name])
+    │
+    ▼
+Phase 1 ([Name])
+    │
+    ▼
+Phase 2 ([Name])
+```
+
+## Effort Estimates
+
+| Phase | Modules | Estimated Days | Risk | Dependencies |
+|-------|---------|---------------|------|-------------|
+| P0: [Name] | [N] | [N] | [Low/Medium/High] | None |
+| P1: [Name] | [N] | [N] | [Low/Medium/High] | P0 |
+| P2: [Name] | [N] | [N] | [Low/Medium/High] | P1 |
+
+## Key Milestones
+
+| Milestone | Target | What's True |
+|-----------|--------|-------------|
+| **M0: [Name]** | Day [N] | [What's working] |
+| **M1: [Name]** | Day [N] | [What's working] |

package/templates/pi/extensions/architect.ts

@@ -6,12 +6,18 @@
  *
  * COMMANDS
  * /architect --epic "Name" [--tracking-issue N]   Start new epic
+ * /architect --roadmap                           Show roadmap status
+ * /architect --phase "Phase 1"                    Start a roadmap phase
+ * /architect --phase-status                       Show current phase
+ * /architect --phase-done <N>                     Mark phase complete
+ * /architect --phase-module-done <N> "Module"    Mark module done in phase
  * /architect status                                  Show current state
  * /architect next-epic                               Show next planned slice
  * /architect abort                                   Cancel current epic
  *
  * TOOLS
  * architect_status   - Current epic state and progress
+ * architect_roadmap  - Show roadmap phases and status
  * architect_discover - Discover modules and find next logical slice
  */
 
@@ -88,10 +94,40 @@ type EpicState = {
 	createdAt: string;
 };
 
+// ── Roadmap Types ──
+
+type RoadmapPhaseModule = {
+	name: string;
+	deliverables: string;
+	doc: string;
+};
+
+type RoadmapPhase = {
+	index: number;
+	title: string;
+	goal: string;
+	days: string;
+	modules: RoadmapPhaseModule[];
+	completedModules: string[]; // names of completed modules within this phase
+	dependencies: string[];
+	migrations: string[];
+	criteria: string[];
+	status: "pending" | "in_progress" | "done";
+};
+
+type RoadmapState = {
+	phases: RoadmapPhase[];
+	currentPhaseIndex: number;
+	startedAt: string;
+	updatedAt: string;
+};
+
 // ── Constants ──
 
 const ARCH_MODULES_DIR = ".pi/architecture/modules";
 const ISSUES_DIR = ".pi/issues";
+const ROADMAP_FILE = ".pi/architecture/implementation-roadmap.md";
+const ROADMAP_STATE_FILE = ".pi/.guardian-roadmap-state.json";
 
 // ── Helpers ──
 
@@ -442,6 +478,214 @@ function findNextLogicalSlice(cwd: string, moduleFiles: string[]): ArchitectureS
 	return null;
 }
 
+// ── Roadmap Parsing ──
+
+function parseRoadmap(cwd: string): RoadmapPhase[] {
+	const path = join(cwd, ROADMAP_FILE);
+	if (!existsSync(path)) return [];
+	const content = readFileSync(path, "utf-8");
+	const lines = content.split("\n");
+	const phases: RoadmapPhase[] = [];
+	let currentPhase: Partial<RoadmapPhase> | null = null;
+	let inModules = false;
+	let inDeps = false;
+	let inMigrations = false;
+	let inCriteria = false;
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		const trimmed = line.trim();
+
+		// Detect phase heading: ## Phase N: Name (Days X-Y)
+		const phaseMatch = trimmed.match(/^## Phase (\d+):\s*(.+?)\s*\((Days\s*[^)]+)\)?$/i);
+		if (phaseMatch) {
+			if (currentPhase && currentPhase.title) {
+				phases.push({
+					index: currentPhase.index!,
+					title: currentPhase.title!,
+					goal: currentPhase.goal || "",
+					days: currentPhase.days || "",
+					modules: currentPhase.modules || [],
+					dependencies: currentPhase.dependencies || [],
+					migrations: currentPhase.migrations || [],
+					criteria: currentPhase.criteria || [],
+					status: "pending",
+				});
+			}
+			currentPhase = {
+				index: parseInt(phaseMatch[1], 10),
+				title: phaseMatch[2].trim(),
+				days: phaseMatch[3].trim(),
+				modules: [],
+				dependencies: [],
+				migrations: [],
+				criteria: [],
+			};
+			inModules = false; inDeps = false; inMigrations = false; inCriteria = false;
+			continue;
+		}
+
+		if (!currentPhase) continue;
+
+		// Goal line
+		const goalMatch = trimmed.match(/^\*\*Goal:\*\*\s*(.+)/i);
+		if (goalMatch) {
+			currentPhase.goal = goalMatch[1].trim();
+			continue;
+		}
+
+		// Section headers
+		if (trimmed.match(/^###\s+Modules?/i)) {
+			inModules = true; inDeps = false; inMigrations = false; inCriteria = false; continue;
+		}
+		if (trimmed.match(/^###\s+Dependencies?/i)) {
+			inModules = false; inDeps = true; inMigrations = false; inCriteria = false; continue;
+		}
+		if (trimmed.match(/^###\s+Database\s+Migrations?/i)) {
+			inModules = false; inDeps = false; inMigrations = true; inCriteria = false; continue;
+		}
+		if (trimmed.match(/^###\s+Acceptance\s+Criteria/i)) {
+			inModules = false; inDeps = false; inMigrations = false; inCriteria = true; continue;
+		}
+
+		// Exit section on next ### heading
+		if (trimmed.startsWith("###") && !trimmed.match(/^###\s+(Modules?|Dependencies?|Database\s+Migrations?|Acceptance\s+Criteria)/i)) {
+			inModules = false; inDeps = false; inMigrations = false; inCriteria = false;
+		}
+
+		// Parse module table rows: | Module | Deliverables | Doc |
+		if (inModules && trimmed.startsWith("|") && !trimmed.startsWith("|---") && !trimmed.startsWith("| Module")) {
+			const parts = trimmed.split("|").map((p: string) => p.trim()).filter(Boolean);
+			if (parts.length >= 2) {
+				currentPhase.modules!.push({
+					name: parts[0],
+					deliverables: parts[1] || "",
+					doc: parts[2] || `.pi/architecture/modules/${parts[0].toLowerCase().replace(/[^a-z0-9]+/g, "-")}.md`,
+				});
+			}
+		}
+
+		// Parse dependencies: list items
+		if (inDeps && trimmed.startsWith("-")) {
+			currentPhase.dependencies!.push(trimmed.replace(/^[-\s]+/, "").trim());
+		}
+
+		// Parse migrations: - NNN_name: description
+		if (inMigrations && trimmed.startsWith("-")) {
+			currentPhase.migrations!.push(trimmed.replace(/^[-\s]+/, "").trim());
+		}
+
+		// Parse acceptance criteria: - [ ] item
+		if (inCriteria && trimmed.startsWith("- [")) {
+			currentPhase.criteria!.push(trimmed.replace(/^\[-\s*\]\s*/, "").trim());
+		}
+	}
+
+	// Push last phase
+	if (currentPhase && currentPhase.title) {
+		phases.push({
+			index: currentPhase.index!,
+			title: currentPhase.title!,
+			goal: currentPhase.goal || "",
+			days: currentPhase.days || "",
+			modules: currentPhase.modules || [],
+			completedModules: currentPhase.completedModules || [],
+			dependencies: currentPhase.dependencies || [],
+			migrations: currentPhase.migrations || [],
+			criteria: currentPhase.criteria || [],
+			status: "pending",
+		});
+	}
+
+	// Restore status from saved state
+	const saved = loadRoadmapState(cwd);
+	if (saved) {
+		for (const phase of phases) {
+			const savedPhase = saved.phases.find((p: RoadmapPhase) => p.index === phase.index);
+			if (savedPhase) {
+				phase.status = savedPhase.status;
+				phase.completedModules = savedPhase.completedModules || [];
+			}
+		}
+	}
+
+	return phases;
+}
+
+function saveRoadmapState(cwd: string, state: RoadmapState): void {
+	const dir = dirname(join(cwd, ROADMAP_STATE_FILE));
+	if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+	writeFileSync(join(cwd, ROADMAP_STATE_FILE), JSON.stringify(state, null, 2));
+}
+
+function loadRoadmapState(cwd: string): RoadmapState | null {
+	const p = join(cwd, ROADMAP_STATE_FILE);
+	if (!existsSync(p)) return null;
+	try {
+		return JSON.parse(readFileSync(p, "utf-8"));
+	} catch {
+		return null;
+	}
+}
+
+function formatRoadmapStatus(phases: RoadmapPhase[]): string {
+	if (phases.length === 0) {
+		return "No implementation-roadmap.md found in .pi/architecture/.";
+	}
+	const lines = ["## Implementation Roadmap", ""];
+	for (const phase of phases) {
+		const icon = phase.status === "done" ? "✅" : phase.status === "in_progress" ? "🔄" : "⏳";
+		lines.push(`### Phase ${phase.index}: ${phase.title} ${icon}`);
+		lines.push(`**Goal:** ${phase.goal}`);
+		lines.push(`**Days:** ${phase.days}`);
+		lines.push(`**Status:** ${phase.status}`);
+		lines.push("**Modules:**");
+		for (const mod of phase.modules) {
+			const modIcon = phase.completedModules?.includes(mod.name) ? "✅" : "⏳";
+			lines.push(`  ${modIcon} ${mod.name}`);
+		}
+		lines.push(`**Modules done:** ${phase.completedModules?.length || 0}/${phase.modules.length}`);
+		if (phase.migrations.length > 0) {
+			lines.push(`**Migrations:** ${phase.migrations.length}`);
+		}
+		if (phase.criteria.length > 0) {
+			lines.push(`**Criteria:** ${phase.criteria.length}`);
+		}
+		if (phase.dependencies.length > 0) {
+			lines.push(`**Depends on:** ${phase.dependencies.join(", ")}`);
+		}
+		lines.push("");
+	}
+
+	const done = phases.filter((p) => p.status === "done").length;
+	const inProgress = phases.filter((p) => p.status === "in_progress").length;
+	lines.push(`**Overall:** ${done}/${phases.length} phases done, ${inProgress} in progress`);
+	return lines.join("\n");
+}
+
+function getNextPendingPhase(phases: RoadmapPhase[]): RoadmapPhase | null {
+	for (const phase of phases) {
+		if (phase.status !== "done") {
+			// Check dependencies
+			const depsMet = phase.dependencies.every((dep: string) => {
+				// "None" means no dependency
+				if (dep.toLowerCase() === "none") return true;
+				// Dependency format: "Phase N" or "Phase N: Name"
+				const depMatch = dep.match(/Phase\s+(\d+)/i);
+				if (depMatch) {
+					const depIdx = parseInt(depMatch[1], 10);
+					const depPhase = phases.find((p: RoadmapPhase) => p.index === depIdx);
+					return depPhase && depPhase.status === "done";
+				}
+				return true; // non-phase dependency treated as met
+			});
+			if (!depsMet) return null; // can't start yet
+			return phase;
+		}
+	}
+	return null; // all done
+}
+
 // ── Issue Generation ──
 
 function generateIssueMarkdown(
@@ -1052,16 +1296,23 @@ class EpicManager {
 				);
 			}
 		}
-		// Fallback: first module with planned components
+		// Fallback: if matched module has no planned components, error instead of silently switching
 		if (!slice) {
+			if (matchedModule) {
+				throw new Error(
+					`Module "${matchedModule}" matches epic "${name}" but all its components are already implemented. ` +
+					`No planned components found. Use a different epic or mark components as "planned" in the architecture doc.`,
+				);
+			}
+			// No match at all
+			slice = findNextLogicalSlice(this.cwd, moduleFiles);
+			if (!slice) {
+				throw new Error("All architecture components are implemented. No next slice found.");
+			}
 			ctx.ui.notify(
-				`No exact module match with planned components for "${name}". Using first available module instead.`,
+				`No module found matching "${name}". Using first module with planned components: "${slice.module}".`,
 				"warn",
 			);
-			slice = findNextLogicalSlice(this.cwd, moduleFiles);
-		}
-		if (!slice) {
-			throw new Error("All architecture components are implemented. No next slice found.");
 		}
 
 		ctx.ui.setStatus("architect", `Planning epic: ${name}`);
@@ -1248,13 +1499,16 @@ export default function (pi: ExtensionAPI) {
 	}
 
 	pi.registerCommand("architect", {
-		description: "Orchestrate the full architecture-to-implementation process",
+		description: "Orchestrate the full architecture-to-implementation process including roadmap phases",
 		handler: async (args, ctx) => {
 			if (!manager) manager = new EpicManager(ctx.cwd);
 			const raw = typeof args === "string" ? args : "";
 			const tokens = raw ? raw.split(/\s+/).filter(Boolean) : [];
 			if (tokens.length === 0) {
-				ctx.ui.notify("Usage: /architect [--epic Name] [--tracking-issue N] | status | next-epic | abort", "info");
+				ctx.ui.notify(
+					"Usage: /architect [--epic Name] [--tracking-issue N] | --roadmap | --phase \"Phase 1\" | --phase-status | --phase-done <N> | --phase-module-done <N> \"Module\" | status | next-epic | abort",
+					"info",
+				);
 				return;
 			}
 			const action = tokens[0];
@@ -1285,6 +1539,291 @@ export default function (pi: ExtensionAPI) {
 			const epicName = findFlag(tokens, "--epic");
 			const trackingIssueId = findFlag(tokens, "--tracking-issue");
 
+			// ── Roadmap commands ──
+			if (tokens[0] === "--roadmap" || action === "roadmap") {
+				const phases = parseRoadmap(ctx.cwd);
+				ctx.ui.notify(formatRoadmapStatus(phases), "info");
+				return;
+			}
+
+			if (tokens[0] === "--phase-status" || action === "phase-status") {
+				const phases = parseRoadmap(ctx.cwd);
+				const next = getNextPendingPhase(phases);
+				if (!next) {
+					const allDone = phases.every((p) => p.status === "done");
+					ctx.ui.notify(allDone ? "All phases complete! 🎉" : "Next phase blocked by dependencies.", "info");
+					return;
+				}
+				ctx.ui.notify(`Next phase: Phase ${next.index}: ${next.title} (${next.modules.length} modules)`, "info");
+				return;
+			}
+
+			if (tokens[0] === "--phase" || action === "phase") {
+				const phaseName = (tokens.slice(1).join(" ") || findFlag(tokens, "--phase")).replace(/["']/g, "").trim();
+				if (!phaseName) {
+					ctx.ui.notify('Usage: /architect --phase "Phase 1"', "error");
+					return;
+				}
+
+				const phases = parseRoadmap(ctx.cwd);
+				if (phases.length === 0) {
+					ctx.ui.notify("No implementation-roadmap.md found in .pi/architecture/.", "error");
+					return;
+				}
+
+				// Find phase by name or index
+				let targetPhase: RoadmapPhase | undefined;
+				const idxMatch = phaseName.match(/Phase\s+(\d+)/i);
+				if (idxMatch) {
+					targetPhase = phases.find((p) => p.index === parseInt(idxMatch[1], 10));
+				} else {
+					targetPhase = phases.find((p) => p.title.toLowerCase().includes(phaseName.toLowerCase()));
+				}
+
+				if (!targetPhase) {
+					ctx.ui.notify(`Phase "${phaseName}" not found in roadmap.`, "error");
+					return;
+				}
+
+				// Check dependencies
+				const unmetDeps = targetPhase.dependencies.filter((dep) => {
+					if (dep.toLowerCase() === "none") return false;
+					const depMatch = dep.match(/Phase\s+(\d+)/i);
+					if (!depMatch) return false;
+					const depPhase = phases.find((p) => p.index === parseInt(depMatch[1], 10));
+					return depPhase && depPhase.status !== "done";
+				});
+				if (unmetDeps.length > 0) {
+					ctx.ui.notify(
+						`Cannot start Phase ${targetPhase.index}: unmet dependencies (${unmetDeps.join(", ")}).`,
+						"error",
+					);
+					return;
+				}
+
+				if (targetPhase.status === "done") {
+					ctx.ui.notify(`Phase ${targetPhase.index}: ${targetPhase.title} is already complete.`, "info");
+					return;
+				}
+
+				// Mark phase as in_progress
+				const roadmapState = loadRoadmapState(ctx.cwd) || {
+					phases: [],
+					currentPhaseIndex: 0,
+					startedAt: new Date().toISOString(),
+					updatedAt: new Date().toISOString(),
+				};
+				roadmapState.phases = phases.map((p) => ({
+					...p,
+					status: p.index === targetPhase!.index ? "in_progress" : p.status,
+				}));
+				roadmapState.currentPhaseIndex = targetPhase.index;
+				roadmapState.updatedAt = new Date().toISOString();
+				saveRoadmapState(ctx.cwd, roadmapState);
+
+				// Create standard epic for each module using the same pipeline as --epic
+				const results: string[] = [];
+				for (const mod of targetPhase.modules) {
+					if (targetPhase.completedModules?.includes(mod.name)) {
+						results.push(`✅ ${mod.name} — already completed, skipped`);
+						continue;
+					}
+					// Check if module has planned components BEFORE calling startEpic
+					// (startEpic silently falls back to wrong module if no planned components)
+					const matchedFile = findModuleByName(ctx.cwd, mod.name);
+					let hasPlanned = false;
+					if (matchedFile) {
+						const comps = parseModuleFile(join(ctx.cwd, ARCH_MODULES_DIR, matchedFile));
+						hasPlanned = comps.some((c) => c.status === "planned");
+					}
+					if (!hasPlanned) {
+						results.push(`✅ ${mod.name} — all components implemented, skipped`);
+						// Auto-mark as completed module
+						const rs = loadRoadmapState(ctx.cwd) || {
+							phases: [], currentPhaseIndex: 0, startedAt: "", updatedAt: "",
+						};
+						const comp = new Set((rs.phases.find((p) => p.index === targetPhase.index)?.completedModules || []));
+						comp.add(mod.name);
+						if (rs.phases.find((p) => p.index === targetPhase.index)) {
+							rs.phases.find((p) => p.index === targetPhase.index)!.completedModules = Array.from(comp);
+						}
+						rs.updatedAt = new Date().toISOString();
+						saveRoadmapState(ctx.cwd, rs);
+						continue;
+					}
+					try {
+						const state = await manager.startEpic(ctx, mod.name);
+						if (!state || !state.slices || state.slices.length === 0) {
+							results.push(`⚠️ ${mod.name} — no architecture components found`);
+							continue;
+						}
+						const items = (state.issues || []).map((i: { id: string }) => i.id);
+						// Create pipeline state for this epic
+						const pipelineId = `PL-${String(Math.floor(Math.random() * 10000)).padStart(4, "0")}`;
+						const pipelineState = {
+							id: pipelineId,
+							name: mod.name,
+							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: "create-mr", prompt: ".pi/prompts/issue-closeout.md", acceptance: { type: "none" } },
+								{ name: "merge", prompt: ".pi/prompts/issue-merge.md", acceptance: { type: "validator", validators: ["ci", "canonical"] } },
+							],
+							currentItemIndex: 0,
+							currentStepIndex: 0,
+							status: "running",
+							retryCount: 0,
+							results: [],
+							mergeOnValid: true,
+							createdAt: new Date().toISOString(),
+							updatedAt: new Date().toISOString(),
+						};
+						// Write pipeline state only for the FIRST module (active pipeline)
+						// Other epics' pipelines are tracked in the phase state, not active
+						const pipelineFile = join(ctx.cwd, ".pi/.guardian-pipeline-state.json");
+						if (!existsSync(pipelineFile)) {
+							const pipelineDir = dirname(pipelineFile);
+							if (!existsSync(pipelineDir)) mkdirSync(pipelineDir, { recursive: true });
+							writeFileSync(pipelineFile, JSON.stringify(pipelineState, null, 2));
+						}
+						results.push(`📋 ${mod.name} — ${items.length} issues created (pipeline ${pipelineId})`);
+					} catch (e) {
+						results.push(`❌ ${mod.name} — error: ${e}`);
+					}
+				}
+
+				// Mark completed modules from roadmap state
+				const updatedRoadmap = loadRoadmapState(ctx.cwd) || roadmapState;
+				updatedRoadmap.updatedAt = new Date().toISOString();
+				saveRoadmapState(ctx.cwd, updatedRoadmap);
+
+				// Find the first module that got a pipeline (active epic)
+				const firstActive = results.find((r) => r.startsWith("📋"));
+				const activeEpic = firstActive ? firstActive.replace(/^📋\s*/, "").split(" —")[0] : null;
+
+				const summary = [
+					`## Phase ${targetPhase.index}: ${targetPhase.title} — Epics Created`,
+					`**Goal:** ${targetPhase.goal}`,
+					`**Days:** ${targetPhase.days}`,
+					"",
+					"### Results",
+					...results.map((r) => `- ${r}`),
+					"",
+					"### How to implement",
+					activeEpic ? `Active epic: **${activeEpic}** — use \`pipeline_next_task\` to start.` : "All modules already implemented.",
+					"When an epic is done, use /architect --epic \"<next-module>\" to start the next one.",
+					"",
+					"After completing all module epics, close the phase:",
+					`  \`/architect --phase-done ${targetPhase.index}\``,
+					"",
+					"### Acceptance Criteria",
+					targetPhase.criteria.map((c) => `- [ ] ${c}`).join("\n"),
+				].join("\n");
+
+				ctx.ui.notify(
+					`Phase ${targetPhase.index}: ${targetPhase.title} — ${results.length} modules processed`,
+					"success",
+				);
+				pi.sendMessage(
+					{ content: summary, display: true },
+					{ deliverAs: "followUp", triggerTurn: true },
+				);
+				return;
+			}
+
+			if (tokens[0] === "--phase-module-done" || action === "phase-module-done") {
+				const phaseIdx = parseInt(tokens[1] || "", 10);
+				if (isNaN(phaseIdx) || !tokens[2]) {
+					ctx.ui.notify('Usage: /architect --phase-module-done <phase-number> "<module-name>"', "error");
+					return;
+				}
+				const rawName = tokens.slice(2).join(" ").replace(/["']/g, "").trim();
+				const phases = parseRoadmap(ctx.cwd);
+				const phase = phases.find((p) => p.index === phaseIdx);
+				if (!phase) {
+					ctx.ui.notify(`Phase ${phaseIdx} not found.`, "error");
+					return;
+				}
+				const matchedModule = phase.modules.find(
+					(m) => m.name.toLowerCase() === rawName.toLowerCase(),
+				);
+				if (!matchedModule) {
+					ctx.ui.notify(
+						`Module "${rawName}" not found in Phase ${phaseIdx}. Available: ${phase.modules.map((m) => m.name).join(", ")}`,
+						"error",
+					);
+					return;
+				}
+				const roadmapState = loadRoadmapState(ctx.cwd) || {
+					phases: [],
+					currentPhaseIndex: 0,
+					startedAt: new Date().toISOString(),
+					updatedAt: new Date().toISOString(),
+				};
+				const completed = new Set(phase.completedModules || []);
+				completed.add(matchedModule.name);
+				roadmapState.phases = phases.map((p) => ({
+					...p,
+					completedModules: p.index === phaseIdx ? Array.from(completed) : p.completedModules,
+				}));
+				roadmapState.updatedAt = new Date().toISOString();
+				saveRoadmapState(ctx.cwd, roadmapState);
+				const done = completed.size;
+				const total = phase.modules.length;
+				ctx.ui.notify(`Phase ${phaseIdx}: "${matchedModule.name}" marked done (${done}/${total} modules)`, "success");
+				return;
+			}
+
+			if (tokens[0] === "--phase-done" || action === "phase-done") {
+				const phaseIdx = parseInt(tokens[1] || "", 10);
+				if (isNaN(phaseIdx)) {
+					ctx.ui.notify('Usage: /architect --phase-done <phase-number>', "error");
+					return;
+				}
+				const phases = parseRoadmap(ctx.cwd);
+				const phase = phases.find((p) => p.index === phaseIdx);
+				if (!phase) {
+					ctx.ui.notify(`Phase ${phaseIdx} not found.`, "error");
+					return;
+				}
+				const roadmapState = loadRoadmapState(ctx.cwd) || {
+					phases: [],
+					currentPhaseIndex: 0,
+					startedAt: new Date().toISOString(),
+					updatedAt: new Date().toISOString(),
+				};
+				roadmapState.phases = phases.map((p) => ({
+					...p,
+					status: p.index === phaseIdx ? "done" : p.status,
+				}));
+				roadmapState.updatedAt = new Date().toISOString();
+				saveRoadmapState(ctx.cwd, roadmapState);
+				ctx.ui.notify(`Phase ${phaseIdx}: ${phase.title} marked complete! ✅`, "success");
+
+				const next = getNextPendingPhase(
+					phases.map((p) => ({ ...p, status: p.index === phaseIdx ? "done" : p.status })),
+				);
+				if (next) {
+					pi.sendMessage(
+						{
+							content: `**Next up:** Phase ${next.index}: ${next.title} — run \`/architect --phase "Phase ${next.index}"\` to start.`,
+							display: true,
+						},
+						{ deliverAs: "followUp", triggerTurn: true },
+					);
+				} else {
+					const allDone = phases.every((p) => p.index === phaseIdx || p.status === "done");
+					if (allDone) {
+						pi.sendMessage(
+							{ content: "🎉 **All roadmap phases complete!**", display: true },
+							{ deliverAs: "followUp", triggerTurn: true },
+						);
+					}
+				}
+				return;
+			}
+
 			if (!epicName) {
 				ctx.ui.notify('Usage: /architect --epic "Epic Name" [--tracking-issue N]', "error");
 				return;
@@ -1317,16 +1856,6 @@ export default function (pi: ExtensionAPI) {
 					return;
 				}
 
-				// Initialize git if needed
-				try {
-					const gitCheck = runScript(ctx.cwd, "git rev-parse --git-dir 2>/dev/null");
-					if (gitCheck.exitCode !== 0) {
-						runScript(ctx.cwd, "git init");
-						runScript(ctx.cwd, "git add .");
-						runScript(ctx.cwd, 'git commit -m "Initial Guardian scaffold"');
-					}
-				} catch { /* ignore */ }
-
 				// Remove stale pipeline state so the new one takes effect
 				try {
 					const oldPipelinePath = join(ctx.cwd, ".pi/.guardian-pipeline-state.json");
@@ -1455,4 +1984,15 @@ export default function (pi: ExtensionAPI) {
 			return { content: [{ type: "text", text: lines.join("\n") }] };
 		},
 	});
+
+	pi.registerTool({
+		name: "architect_roadmap",
+		label: "Architect Roadmap",
+		description: "Show the implementation roadmap phases and status.",
+		parameters: { type: "object", properties: {} },
+		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+			const phases = parseRoadmap(ctx.cwd);
+			return { content: [{ type: "text", text: formatRoadmapStatus(phases) }] };
+		},
+	});
 }

package/templates/pi/extensions/coordinator.ts

@@ -20,7 +20,13 @@ type ExtensionContext = {
 type ToolCallEvent = { toolName: string; toolCallId: string; input: { command: string } };
 
 type ExtensionAPI = {
-	on(event: string, handler: (event: unknown, ctx: ExtensionContext) => void | Promise<void>): void;
+	on(
+		event: string,
+		handler: (
+			event: unknown,
+			ctx: ExtensionContext,
+		) => void | { block: boolean; reason: string } | Promise<void | { block: boolean; reason: string }>,
+	): void;
 	registerTool(options: {
 		name: string;
 		label: string;
@@ -30,7 +36,7 @@ type ExtensionAPI = {
 			toolCallId: string,
 			params: Record<string, unknown>,
 			signal: AbortSignal,
-			onUpdate: (update: { type: string; message: string }) => void,
+			onUpdate: (update: { content: Array<{ type: string; text: string }> }) => void,
 			ctx: ExtensionContext,
 		): unknown | Promise<unknown>;
 	}): void;
@@ -213,15 +219,33 @@ export default function (pi: ExtensionAPI) {
 			validators: Type.Optional(Type.Array(Type.String())),
 		}),
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
-			// 1. Classify scope
+			// 1. Classify scope (inlined from guardian_scope to avoid nested tool calls)
 			let scope = typeof params.scope === "string" ? params.scope : undefined;
 			if (!scope) {
-				const scopeResult = await ctx.tools.execute("guardian_scope", {});
-				// Parse the text result to extract scope
-				const text =
-					(scopeResult as { content?: Array<{ text?: string }> })?.content?.[0]?.text ?? "";
-				const match = text.match(/Scope:\s+\*\*(\w+)\*\*/);
-				scope = match?.[1] ?? "moderate";
+				let diff;
+				try {
+					diff = await ctx.shell.execute("git diff --numstat HEAD", { signal });
+				} catch {
+					try {
+						diff = await ctx.shell.execute("git diff --numstat", { signal });
+					} catch {
+						scope = "moderate";
+					}
+				}
+				if (diff) {
+					const rows = diff.stdout.split("\n").filter((line: string) => line.trim());
+					const fileCount = rows.length;
+					const lineChanges = rows.reduce((sum: number, row: string) => {
+						const [added, removed] = row.split(/\s+/);
+						const a = Number.parseInt(added, 10);
+						const r = Number.parseInt(removed, 10);
+						return sum + (Number.isFinite(a) ? a : 0) + (Number.isFinite(r) ? r : 0);
+					}, 0);
+					if (fileCount >= 16 || lineChanges >= 500) scope = "critical";
+					else if (fileCount >= 6 || lineChanges >= 200) scope = "complex";
+					else if (fileCount >= 3 || lineChanges >= 50) scope = "moderate";
+					else scope = "simple";
+				}
 			}
 
 			onUpdate({ content: [{ type: "text", text: `Scope: ${scope}` }] });
@@ -244,14 +268,30 @@ export default function (pi: ExtensionAPI) {
 
 			const validators = Array.isArray(params.validators)
 				? params.validators.filter((v): v is string => typeof v === "string")
-				: (validatorMap[scope] ?? validatorMap.moderate);
+				: (validatorMap[scope ?? "moderate"] ?? validatorMap.moderate);
 
 			onUpdate({ content: [{ type: "text", text: `Validators: ${validators.join(", ")}` }] });
 
-			// 3. Run validators
-			const validationResults = await ctx.tools.execute("guardian_validate", { validators, scope });
+			// 3. Run validators (inlined from guardian_validate to avoid nested tool calls)
+			const valResults: Record<string, { passed: boolean; output: string }> = {};
+			for (const validator of validators) {
+				if (signal?.aborted) break;
+				if (!isValidatorName(validator)) {
+					valResults[validator] = { passed: false, output: `Unsupported validator: ${validator}` };
+					continue;
+				}
+				onUpdate({ content: [{ type: "text", text: `Running ${validator} validation...` }] });
+				const scriptPath = VALIDATORS[validator];
+				try {
+					const result = await ctx.shell.execute(`bash ${scriptPath}`, { signal });
+					valResults[validator] = { passed: result.exitCode === 0, output: result.stdout };
+				} catch (error) {
+					valResults[validator] = { passed: false, output: `Error: ${error}` };
+				}
+			}
 
 			// 4. Build coordination result
+			const allPassed = Object.values(valResults).every((r) => r.passed);
 			const lines: string[] = [
 				"## Coordination Report",
 				"",
@@ -259,17 +299,27 @@ export default function (pi: ExtensionAPI) {
 				`**Scope:** ${scope}`,
 				`**Validators:** ${validators.join(", ")}`,
 				"",
-				"### Next Steps",
-				scope === "critical"
-					? "- Request human approval before proceeding"
-					: "- Proceed with implementation",
+				`**Result:** ${allPassed ? "✅ All Passed" : "❌ Some Failed"}`,
+				"",
+				"### Validation Details",
 			];
 
-			// Append validation results
-			const valText =
-				(validationResults as { content?: Array<{ text?: string }> })?.content?.[0]?.text ?? "";
-			if (valText) {
-				lines.push("", "### Validation", valText);
+			for (const [name, vr] of Object.entries(valResults)) {
+				lines.push(`**${name}:** ${vr.passed ? "✅ PASS" : "❌ FAIL"}`);
+				const output = vr.output.trim();
+				if (output) {
+					const tail = output.split("\n").slice(-10).join("\n");
+					lines.push(`\`\`\`\n${tail}\n\`\`\``);
+				}
+			}
+
+			lines.push("", "### Next Steps");
+			if (scope === "critical") {
+				lines.push("- Request human approval before proceeding");
+			} else if (allPassed) {
+				lines.push("- ✅ All validators passed — proceed with implementation");
+			} else {
+				lines.push("- ❌ Some validators failed — fix issues before proceeding");
 			}
 
 			return toolResult(lines.join("\n"));
@@ -279,7 +329,7 @@ export default function (pi: ExtensionAPI) {
 	// ── Block catastrophic commands only (lightweight safety net) ──
 	// Git commit/push are allowed — agents need them for autonomous workflows.
 	// Destructive operations are blocked to prevent irreversible damage.
-	pi.on("tool_call", async (event) => {
+	pi.on("tool_call", async (event, _ctx) => {
 		if (!isToolCallEventType("bash", event)) return;
 
 		const cmd = event.input.command;

package/templates/pi/extensions/domain-explorer.ts

@@ -75,7 +75,7 @@ type ExtensionAPI = {
 			toolCallId: string,
 			params: Record<string, unknown>,
 			signal: AbortSignal,
-			onUpdate: (update: { type: string; message: string }) => void,
+			onUpdate: (update: { content: Array<{ type: string; text: string }> }) => void,
 			ctx: ExtensionContext,
 		): unknown | Promise<unknown>;
 	}): void;

package/templates/pi/extensions/goal-loop.ts

@@ -230,16 +230,15 @@ async function runLLMJudge(
 
 	const prompt = `Goal:\n${truncatedGoal}\n${subgoalsBlock}\n\nAgent's most recent response:\n${truncatedResponse}\n\nIs the goal satisfied?`;
 
-	// Use guardian_coordinate to run an LLM-based judgment
+	// Check if git diff is accessible (for heuristic judgment)
 	try {
-		const result = await ctx.tools.execute("guardian_scope", {});
-		// We can't directly call LLM from extension — instead return a heuristic judgment
-		// The LLM judge runs via the agent itself being prompted to self-assess
-		// For now, return continue to let the agent decide
-		return { done: false, reason: "LLM judge requires agent self-assessment turn" };
+		await ctx.shell.execute("git rev-parse --git-dir 2>/dev/null", {});
 	} catch {
-		return { done: false, reason: "judge unavailable, continuing" };
+		// Not a git repo — continue anyway
 	}
+	// The LLM judge runs via the agent itself being prompted to self-assess
+	// For now, return continue to let the agent decide
+	return { done: false, reason: "LLM judge requires agent self-assessment turn" };
 }
 
 function truncate(text: string, limit: number): string {

package/templates/pi/preflight_report.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-07-02T20:21:01Z",
+  "timestamp": "2026-07-03T03:41:18Z",
   "mode": "all",
   "stages_run": [],
   "summary": {