guardian-framework 0.1.7 → 0.1.8

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.8", 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.8", 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.8",
 	"description": "Token-optimized agentic framework scaffolder with pi-first architecture",
 	"type": "module",
 	"main": "dist/exports.js",

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,17 @@
  *
  * 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 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 +93,39 @@ 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[];
+	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 +476,204 @@ 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 || [],
+			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;
+		}
+	}
+
+	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 (${phase.modules.length}):** ${phase.modules.map((m: RoadmapPhaseModule) => m.name).join(", ")}`);
+		if (phase.migrations.length > 0) {
+			lines.push(`**Migrations:** ${phase.migrations.length}`);
+		}
+		if (phase.criteria.length > 0) {
+			const done = phase.criteria.filter(() => phase.status === "done").length;
+			lines.push(`**Criteria:** ${done}/${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) => {
+				// 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(
@@ -1248,13 +1480,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> | status | next-epic | abort",
+					"info",
+				);
 				return;
 			}
 			const action = tokens[0];
@@ -1285,6 +1520,177 @@ 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 = findFlag(tokens, "--phase") || tokens.slice(1).join(" ");
+				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) => {
+					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);
+
+				// Generate start message with module breakdown
+				const moduleList = targetPhase.modules
+					.map((m) => `- **${m.name}**: ${m.deliverables}`)
+					.join("\n");
+				const migrateList =
+					targetPhase.migrations.length > 0
+						? "\n\n### Database Migrations\n" +
+							targetPhase.migrations.map((m) => `- \`${m}\``).join("\n")
+						: "";
+
+				const instructions = [
+					`## Phase ${targetPhase.index}: ${targetPhase.title}`,
+					`**Goal:** ${targetPhase.goal}`,
+					`**Days:** ${targetPhase.days}`,
+					"",
+					"### Modules",
+					moduleList,
+					migrateList,
+					"",
+					"### How to proceed",
+					"Create epics for each module above using:",
+					`  \`/architect --epic "<module-name>"\``,
+					"",
+					"Complete all module epics, then mark phase done:",
+					`  \`/architect --phase-done ${targetPhase.index}\``,
+					"",
+					"### Acceptance Criteria",
+					targetPhase.criteria.map((c) => `- [ ] ${c}`).join("\n"),
+				].join("\n");
+
+				ctx.ui.notify(
+					`Phase ${targetPhase.index}: ${targetPhase.title} started (${targetPhase.modules.length} modules).`,
+					"success",
+				);
+				pi.sendMessage(
+					{ content: instructions, display: true },
+					{ deliverAs: "followUp", triggerTurn: true },
+				);
+				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;
@@ -1455,4 +1861,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/preflight_report.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-07-02T20:21:01Z",
+  "timestamp": "2026-07-02T20:32:22Z",
   "mode": "all",
   "stages_run": [],
   "summary": {