guardian-framework 0.1.39 → 0.1.41

package/templates/pi/extensions/architect.ts

@@ -1,1267 +1,34 @@
 /**
- * Architect Extension - Full Architecture-to-Implementation Pipeline
+ * Architect Extension — Full Architecture-to-Implementation Pipeline
  *
- * Self-contained extension for pi. Reads architecture module docs from
- * .pi/architecture/modules/ and produces epics + issues for implementation.
- *
- * 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
+ * Entry point. Imports from submodules and registers the extension.
  */
 
-import { execFileSync, execSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-
-
-// ── Types ──
-
-type ExtensionContext = {
-	cwd: string;
-	ui: {
-		notify(message: string, level?: string): void;
-		setStatus(key: string, message: string | null): void;
-		confirm(title: string, message: string): Promise<boolean>;
-	};
-	tools: { execute(name: string, params: Record<string, unknown>): Promise<unknown> };
-};
-
-type ExtensionAPI = {
-	on(event: string, handler: (event: unknown, ctx: ExtensionContext) => void | Promise<void>): void;
-	registerTool(options: {
-		name: string;
-		label: string;
-		description: string;
-		parameters: unknown;
-		execute(
-			toolCallId: string,
-			params: Record<string, unknown>,
-			signal: AbortSignal,
-			onUpdate: (update: { type: string; message: string }) => void,
-			ctx: ExtensionContext,
-		): unknown | Promise<unknown>;
-	}): void;
-	registerCommand(
-		name: string,
-		options: {
-			description: string;
-			handler(args: string, ctx: ExtensionContext): unknown | Promise<unknown>;
-		},
-	): void;
-	sendMessage<T = unknown>(
-		message: { customType?: string; content: string; display?: boolean; details?: Record<string, unknown> },
-		options?: { deliverAs?: "steer" | "followUp" | "nextTurn"; triggerTurn?: boolean },
-	): void;
-	sendUserMessage(
-		content: string,
-		options?: { deliverAs?: "steer" | "followUp" },
-	): void;
-};
-
-type ModuleComponent = {
-	name: string;
-	status: "planned" | "in-progress" | "implemented" | "deprecated";
-	description: string;
-	dependencies: string[];
-};
-
-type ArchitectureSlice = {
-	module: string;
-	components: ModuleComponent[];
-	nextLogicalSlice: ModuleComponent[];
-};
-
-type EpicState = {
-	name: string;
-	trackingIssueId: string | null;
-	epicId: string | null;
-	status: "planning" | "validating" | "publishing" | "executing" | "done" | "aborted";
-	slices: ArchitectureSlice[];
-	issues: { id: string; title: string; status: string; remoteIssueId?: string | null }[];
-	currentIssueIndex: number;
-	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 ──
-
-function log(ctx: ExtensionContext, message: string, level = "info") {
-	ctx.ui.notify(message, level);
-}
-
-function runScript(cwd: string, script: string): { exitCode: number; stdout: string } {
-	try {
-		const stdout = execSync(`bash -c "${script}"`, { cwd, timeout: 120_000, encoding: "utf-8" });
-		return { exitCode: 0, stdout };
-	} catch (e: unknown) {
-		const err = e as { status?: number; stdout?: string; message?: string };
-		return { exitCode: err.status ?? 1, stdout: err.stdout ?? err.message ?? "" };
-	}
-}
-
-// Read repoTool from guardian-manifest.json (defaults to "gh")
-function readRepoTool(cwd: string): string {
-	try {
-		const manifestPath = join(cwd, "guardian-manifest.json");
-		if (existsSync(manifestPath)) {
-			const raw = readFileSync(manifestPath, "utf-8");
-			const manifest = JSON.parse(raw) as { repoTool?: string };
-			if (manifest.repoTool === "glab") return "glab";
-		}
-	} catch {
-		// fall through to default
-	}
-	return "gh";
-}
-
-// Read the repository slug (owner/repo) from guardian-manifest.json
-function readRepository(cwd: string): string | null {
-	try {
-		const manifestPath = join(cwd, "guardian-manifest.json");
-		if (existsSync(manifestPath)) {
-			const raw = readFileSync(manifestPath, "utf-8");
-			const manifest = JSON.parse(raw) as {
-				repository?: string;
-				templateContext?: { repository?: string };
-			};
-			if (manifest.repository) return manifest.repository;
-			if (manifest.templateContext?.repository)
-				return manifest.templateContext.repository;
-		}
-	} catch {
-		// ignore
-	}
-	return null;
-}
-
-function readLanguage(cwd: string): string {
-	const manifestPath = join(cwd, "guardian-manifest.json");
-	try {
-		if (existsSync(manifestPath)) {
-			const raw = readFileSync(manifestPath, "utf-8");
-			const manifest = JSON.parse(raw) as { language?: string };
-			if (manifest.language) return manifest.language;
-		}
-	} catch {}
-	return "typescript";
-}
-
-function codegenSkillName(language: string): string {
-	const map: Record<string, string> = {
-		rust: "rust-codegen",
-		go: "go-codegen",
-		python: "python-codegen",
-		typescript: "typescript-codegen",
-		java: "java-codegen",
-	};
-	return map[language] || "typescript-codegen";
-}
-
-/**
- * Get Git platform base URL. For GitLab, tries to detect self-hosted instances.
- */
-function getGitBaseUrl(repoTool: string): string {
-	if (repoTool === "glab") {
-		try {
-			const uri = execSync("glab config get gitlab_uri 2>/dev/null", {
-				encoding: "utf-8",
-			}).trim();
-			if (uri) return uri.replace(/\/+$/, "");
-		} catch {
-			// fall through to default
-		}
-		return "https://gitlab.com";
-	}
-	return "https://github.com";
-}
-
-function commandExists(cmd: string): boolean {
-	try {
-		execSync(`command -v ${cmd}`, { stdio: "ignore" });
-		return true;
-	} catch {
-		return false;
-	}
-}
-
-// Try to create a remote GitHub/GitLab issue via the shell script wrapper.
-// Uses execFileSync to avoid shell quoting issues with nested commands.
-function createRemoteIssue(
-	cwd: string,
-	title: string,
-	bodyFilePath: string,
-	labels: string,
-	repository?: string,
-): { success: boolean; issueNumber: string | null; error?: string } {
-	const createScript = join(cwd, ".pi/scripts/git/create-tracking-issue.sh");
-	if (!existsSync(createScript)) {
-		return { success: false, issueNumber: null, error: "create-tracking-issue.sh not found" };
-	}
-
-	const args: string[] = [
-		createScript,
-		"--title",
-		title,
-		"--body-file",
-		bodyFilePath,
-		"--labels",
-		labels,
-	];
-	if (repository) args.push("--repo", repository);
-
-	let stdout = "";
-	let exitCode = 0;
-	try {
-		stdout = execFileSync("bash", args, {
-			cwd,
-			timeout: 120_000,
-			encoding: "utf-8",
-		});
-	} catch (e: unknown) {
-		const err = e as { status?: number; stdout?: string; message?: string };
-		exitCode = err.status ?? 1;
-		stdout = err.stdout ?? err.message ?? "";
-	}
-
-	if (exitCode !== 0) {
-		return { success: false, issueNumber: null, error: stdout };
-	}
-
-	const numberMatch = stdout.match(/TRACKING_ID=(\d+)/);
-	if (numberMatch) {
-		return { success: true, issueNumber: numberMatch[1] };
-	}
-	const urlMatch = stdout.match(/#(\d+)/);
-	if (urlMatch) {
-		return { success: true, issueNumber: urlMatch[1] };
-	}
-	return { success: false, issueNumber: null, error: "Could not parse issue number" };
-}
-
-// Ensure the GitHub/GitLab repository exists and local git remote is configured.
-// Returns the repository slug if remote is ready, empty string if not available.
-function ensureRemoteRepo(
-	cwd: string,
-	repository: string,
-	epicName: string,
-	repoTool: string,
-): string {
-	// Check if remote already exists via git remote
-	const remoteCheck = runScript(cwd, "git remote get-url origin 2>/dev/null");
-	if (remoteCheck.exitCode === 0) {
-		return repository;
-	}
-
-	// Remote not configured locally — ensure the remote repo exists on GitHub/GitLab
-	if (repoTool === "gh") {
-		runScript(
-			cwd,
-			`gh repo create "${repository}" --private --description "Epic: ${epicName}" 2>&1`,
-		);
-		// Remove stale origin if it exists but points nowhere useful
-		runScript(cwd, "git remote remove origin 2>/dev/null");
-		const httpsUrl = `https://github.com/${repository}.git`;
-		runScript(cwd, `git remote add origin "${httpsUrl}"`);
-		return repository;
-	}
-
-	// GitLab path
-	runScript(
-		cwd,
-		`glab repo create "${repository}" --private --description "Epic: ${epicName}" 2>&1`,
-	);
-	runScript(cwd, "git remote remove origin 2>/dev/null");
-	const httpsUrl = `https://gitlab.com/${repository}.git`;
-	runScript(cwd, `git remote add origin "${httpsUrl}"`);
-	return repository;
-}
-
-// Link a remote issue to the epic tracking issue
-function linkRemoteIssue(
-	cwd: string,
-	issueId: string,
-	epicId: string,
-): { success: boolean; error?: string } {
-	const linkScript = join(cwd, ".pi/scripts/git/link-issue-to-epic.sh");
-	if (!existsSync(linkScript)) {
-		return { success: false, error: "link-issue-to-epic.sh not found" };
-	}
-
-	const safeIssue = issueId.replace(/[^a-zA-Z0-9 _\-.]/g, "");
-	const safeEpic = epicId.replace(/[^a-zA-Z0-9 _\-.]/g, "");
-
-	const cmd = `bash "${linkScript}" --issue-id "${safeIssue}" --epic-id "${safeEpic}"`;
-	const result = runScript(cwd, cmd);
-	if (result.exitCode !== 0) {
-		return { success: false, error: result.stdout };
-	}
-	return { success: true };
-}
-
-// ── Architecture Discovery ──
-
-function readGroupId(cwd: string): string {
-    // Try pom.xml
-    const pomPath = join(cwd, "pom.xml");
-    try {
-        const pom = readFileSync(pomPath, "utf-8");
-        const match = pom.match(/<groupId>([^<]+)<\/groupId>/);
-        if (match && match[1] !== "com.example") return match[1];
-    } catch {}
-    // Try build.gradle
-    const gradlePath = join(cwd, "build.gradle");
-    try {
-        const gradle = readFileSync(gradlePath, "utf-8");
-        const match = gradle.match(/group\s*=\s*['"]([^'"]+)['"]/);
-        if (match) return match[1];
-    } catch {}
-    return "com.example";
-}
-
-function findModuleByName(cwd: string, name: string): string | null {
-    const files = discoverModules(cwd);
-    const nameLower = name.toLowerCase().replace(/[^a-z0-9]/g, "");
-
-    // Pass 1: exact match only (preferred)
-    for (const f of files) {
-        const key = f.replace(".md", "").toLowerCase().replace(/[^a-z0-9]/g, "");
-        if (key === nameLower) {
-            return f;
-        }
-    }
-
-    // Pass 2: prefix match — query is a prefix of the module name (most specific)
-    // e.g., "audit" matches audit-ingestion over audit-query or audit-export
-    const prefixMatches: string[] = [];
-    for (const f of files) {
-        const key = f.replace(".md", "").toLowerCase().replace(/[^a-z0-9]/g, "");
-        if (key.startsWith(nameLower) && key.length > nameLower.length) {
-            prefixMatches.push(f);
-        }
-    }
-    if (prefixMatches.length === 1) {
-        return prefixMatches[0];
-    }
-
-    // Pass 3: substring match — only if unambiguous (exactly one match)
-    const substringMatches: string[] = [];
-    for (const f of files) {
-        const key = f.replace(".md", "").toLowerCase().replace(/[^a-z0-9]/g, "");
-        if (nameLower.includes(key) || key.includes(nameLower)) {
-            substringMatches.push(f);
-        }
-    }
-    if (substringMatches.length === 1) {
-        return substringMatches[0];
-    }
-
-    // Ambiguous or no match — let caller decide
-    return null;
-}
-
-function discoverModules(cwd: string): string[] {
-	const dir = join(cwd, ARCH_MODULES_DIR);
-	if (!existsSync(dir)) return [];
-	try {
-		return readdirSync(dir).filter((f) => f.endsWith(".md"));
-	} catch {
-		return [];
-	}
-}
-
-function parseModuleFile(filePath: string): ModuleComponent[] {
-	if (!existsSync(filePath)) return [];
-	const content = readFileSync(filePath, "utf-8");
-	const components: ModuleComponent[] = [];
-
-	const lines = content.split("\n");
-	let inComponentSection = false;
-	let inDetailsSection = false;
-	let currentName = "";
-	let currentStatus = "";
-	let currentDesc = "";
-	let currentDeps: string[] = [];
-
-	function saveCurrent() {
-		if (currentName) {
-			// Default to planned if no explicit status found
-			const status = currentStatus || "planned";
-			const desc = currentDesc || `${currentName} component`;
-			components.push({
-				name: currentName,
-				status: status as ModuleComponent["status"],
-				description: desc.trim(),
-				dependencies: currentDeps.length > 0 ? currentDeps : ["none"],
-			});
-		}
-	}
-
-	for (const line of lines) {
-		const trimmed = line.trim();
-
-		// Enter component section (supports "## Components", "## Component Details", "## Component")
-		if (trimmed.match(/^##\s+Components?/i) || trimmed.match(/^##\s+Component\s+Details/i)) {
-			inComponentSection = true;
-			continue;
-		}
-
-		// Leave component section on next top-level section
-		if (inComponentSection && trimmed.match(/^##\s+/) && !trimmed.match(/^##\s+Components?/i)) {
-			saveCurrent();
-			currentName = "";
-			currentStatus = "";
-			currentDesc = "";
-			currentDeps = [];
-			inComponentSection = false;
-			inDetailsSection = false;
-			continue;
-		}
-
-		// Component heading (###) — start a new component entry
-		if (inComponentSection && trimmed.match(/^###\s+/)) {
-			// Skip non-component ### headings like "### Depends On" or "### Security"
-			const name = trimmed.replace(/^###\s+/, "");
-			if (name.match(/^(depends|security|testing|performance|error|change|data flow|responsibilities|overview|interfaces|inputs|outputs)/i)) {
-				continue;
-			}
-			saveCurrent();
-			currentName = name;
-			currentStatus = "";
-			currentDesc = "";
-			currentDeps = [];
-			continue;
-		}
-
-		if (!currentName) continue;
-
-		if (trimmed.startsWith("status:")) {
-			currentStatus = trimmed.replace("status:", "").trim().toLowerCase();
-		} else if (trimmed.startsWith("depends:")) {
-			const depsStr = trimmed.replace("depends:", "").trim();
-			if (depsStr && depsStr !== "none" && depsStr !== "[TODO") {
-				currentDeps = depsStr.split(",").map((d) => d.trim()).filter(Boolean);
-			}
-		} else if (trimmed.startsWith("**Purpose:**")) {
-			currentDesc = trimmed.replace(/\*\*Purpose:\*\*\s*/, "").trim();
-		} else if (!currentDesc && trimmed.length > 10 && !trimmed.startsWith("#") && !trimmed.startsWith("-") && !trimmed.startsWith("|") && !trimmed.startsWith(">") && !trimmed.startsWith("```")) {
-			// Use first substantial sentence as description
-			currentDesc = trimmed.slice(0, 200);
-		}
-	}
-
-	saveCurrent();
-	return components;
-}
-
-function findNextLogicalSlice(cwd: string, moduleFiles: string[]): ArchitectureSlice | null {
-	for (const moduleFile of moduleFiles) {
-		const components = parseModuleFile(join(cwd, ARCH_MODULES_DIR, moduleFile));
-		const planned = components.filter((c) => c.status === "planned");
-		if (planned.length > 0) {
-			return {
-				module: moduleFile.replace(".md", ""),
-				components,
-				nextLogicalSlice: planned,
-			};
-		}
-	}
-	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*\]\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(
-	component: ModuleComponent,
-	slice: ArchitectureSlice,
-	issueIndex: number,
-	totalIssues: number,
-	codegenSkill?: string,
-): string {
-	const moduleId = slice.module.replace(/^module-/, "");
-	const componentName = component.name.toLowerCase().replace(/\s+/g, "-");
-	const issueId = `ISSUE-${moduleId.toUpperCase()}-${issueIndex + 1}`;
-
-	return `---
-guardian_issue:
-  id: "${issueId}"
-  epic: "TBD"
-  component: "${component.name}"
-  module: "${slice.module}"
-  status: planned
-  priority: high
-  dependencies:
-${component.dependencies.map((d) => `    - "${d}"`).join("\n")}
-
-  in_scope:
-    - Implement ${component.name} for the ${slice.module} module
-    - Write unit tests for all public interfaces
-    - Add integration tests with upstream/downstream components
-    - Create API documentation
-
-  out_of_scope:
-    - Changes to upstream components (${component.dependencies.join(", ")})
-    - UI/frontend changes
-    - Deployment pipeline configuration
-
-  affected_layers:
-    domain:
-      - New domain models for ${componentName}
-    application:
-      - New service/handler for ${componentName}
-    infrastructure:
-      - New database tables or external service connections
-    api:
-      - New endpoints or event handlers
-
-  canonical_references:
-    - module: ".pi/architecture/modules/${slice.module}.md#${componentName}"
-
-  acceptance_criteria:
-    - "CI pipeline passes (validate-ci.sh)"
-    - "All unit tests pass with ≥ 90% coverage"
-    - "Integration tests pass with upstream/downstream components"
-    - "validate-security.sh passes"
-    - "validate-architecture.sh passes"
-    - "validate-canonical.sh passes"
-
-  validators:
-    - ci
-    - tests
-    - security
-    - architecture
-    - canonical
-
-  implementation_notes: |
-    ${component.description || "Implement this component according to the architecture module."}
-    ${codegenSkill ? `Follow: .pi/skills/agents/${codegenSkill}.md` : ""}
-
-  file_changes:
-    - "modify: src/${moduleId}/domain/"
-    - "modify: src/${moduleId}/application/"
-    - "modify: src/${moduleId}/infrastructure/"
-    - "modify: src/${moduleId}/interfaces/"
-    - "create: tests/unit/${moduleId}/${componentName}/"
-    - "create: tests/integration/${moduleId}/${componentName}/"
----
-
-# ${issueId}: ${component.name}
-
-## Intent
-
-${component.description || `Implement ${component.name} for the ${slice.module} module.`}
-
-## Architecture Context
-
-- **Module:** ${slice.module}
-- **Component:** ${component.name}
-- **Status:** ${component.status}
-- **Dependencies:** ${component.dependencies.length > 0 ? component.dependencies.join(", ") : "none"}
-
-## Dependencies
-
-\`\`\`
-${component.dependencies.map((d) => `  └── ${d}`).join("\n") || "  └── (root component — no dependencies)"}
-\`\`\`
-
-## In Scope
-
-- Implement ${component.name} for the ${slice.module} module
-- Write unit tests for all public interfaces
-- Add integration tests with upstream/downstream components
-- Create API documentation
-
-## Out of Scope
-
-- Changes to upstream components
-- UI/frontend changes
-- Deployment pipeline configuration
-
-## Affected Layers
-
-### Domain
-- New domain models for ${componentName}
-
-### Application
-- New service/handler for ${componentName}
-
-### Infrastructure
-- New database tables or external service connections
-
-### API
-- New endpoints or event handlers
-
-## Canonical References
-
-- **Module:** \`.pi/architecture/modules/${slice.module}.md#${componentName}\`
-
-## Acceptance Criteria
-
-| # | Criterion | Validator |
-|---|-----------|-----------|
-| 1 | CI pipeline passes | \`validate-ci.sh\` |
-| 2 | All unit tests pass with ≥ 90% coverage | \`validate-tests.sh\` |
-| 3 | Integration tests pass | \`validate-integration.sh\` |
-| 4 | Security checks pass | \`validate-security.sh\` |
-| 5 | Architecture compliance | \`validate-architecture.sh\` |
-| 6 | Canonical references valid | \`validate-canonical.sh\` |
-
-## Implementation
-
-> **Agent:** This is your complete session context. All information you need is above.
-> Start by reading the canonical reference files, then implement following the layer structure.
-
-### Steps
-
-1. Read canonical architecture references
-2. Create domain entities and interfaces
-3. Implement application service/handler
-4. Add infrastructure connections
-5. Write unit tests (≥ 90% coverage)
-6. Write integration tests
-7. Run all validators
-8. Create MR
-`;
-}
-// ── Contract Freeze Generator ──
-
-function generateContractFreezeMarkdown(
-	slice: ArchitectureSlice,
-	epicName: string,
-	codegenSkill?: string,
-): string {
-	const moduleId = slice.module.replace(/^module-/, "");
-
-	return `---
-guardian_issue:
-  id: "ISSUE-CONTRACT-FREEZE"
-  epic: "${epicName}"
-  component: "Contract Freeze"
-  module: "${slice.module}"
-  status: planned
-  priority: critical
-  dependencies: []
-
-  in_scope:
-    - Define public interfaces for all components in this epic
-    - Define DTOs, schemas, and API contracts
-    - Document event payloads and topics
-    - Create interface stubs with no implementation
-    - Freeze: no implementation changes without contract change
-
-  out_of_scope:
-    - Any implementation logic
-    - Database schema changes
-    - Infrastructure setup
-
-  affected_layers:
-    domain:
-      - Interface definitions for domain services
-    application:
-      - Input/output DTO definitions
-    api:
-      - REST/event contracts
-
-  canonical_references:
-    - module: ".pi/architecture/modules/${slice.module}.md"
-
-  acceptance_criteria:
-    - "All component interfaces defined as interfaces/types"
-    - "DTO schemas documented"
-    - "API contracts frozen and reviewed"
-    - "Implementation PRs reference these contracts"
-
-  validators:
-    - architecture
-    - canonical
-
-  implementation_notes: |
-    Define the contract before any implementation. Every implementation issue
-    depends on this contract being frozen first. The contract should include:
-    interfaces, types, DTOs, event schemas, API paths, error formats.
-    ${codegenSkill ? `Follow: .pi/skills/agents/${codegenSkill}.md` : ""}
-
-  file_changes:
-    - "create: src/${moduleId}/domain/"
-    - "create: src/${moduleId}/application/"
-    - "create: src/${moduleId}/infrastructure/"
-    - "create: src/${moduleId}/interfaces/"
----
-
-# Contract Freeze: ${slice.module}
-
-## Intent
-
-Define and freeze all public interfaces, contracts, and schemas for the ${slice.module}
-epic before any implementation begins. This prevents architecture drift — implementation
-must satisfy contracts, not the other way around.
-
-## Included Components
-
-${slice.nextLogicalSlice.map((c: { name: string }) => `- ${c.name}`).join("\n")}
-
-## What Must Be Frozen
-
-### Interfaces
-- Service interfaces for every component
-- Repository/DAO interfaces
-- Factory interfaces
-
-### Contracts
-- Input/output DTO schemas
-- API endpoint contracts (method, path, request/response)
-- Event payload schemas
-- Error response formats
-
-### Out of Bounds (no contracts needed)
-- Internal implementation details
-- Database column names (hidden behind repository)
-- Framework-specific annotations
-
-## Acceptance Criteria
-
-| # | Criterion | How to Verify |
-|---|-----------|---------------|
-| 1 | All component interfaces defined | Check src/<group>/<module>/domain/ and application/ |
-| 2 | Contracts reviewed and frozen | PR approval |
-| 3 | DTO schemas documented | OpenAPI / TypeSpec / equivalent |
-| 4 | Implementation depends on contracts | No implementation without interface |
-
-## Implementation
-
-> **Agent:** Create interface-only files. No implementation. Use Clean Architecture layers:
-> 1. Read the architecture module to understand each component's role
-> 2. Place domain interfaces in domain/, service interfaces in application/, API contracts in interfaces/http/
-> 3. DTOs with proper validation decorators go in application/
-> 4. Event schemas go in domain/event/
-> 5. Repository interfaces go in infrastructure/repository/
->
-> The goal is a reviewed, frozen contract that implementation issues can depend on.
-`;
-}
-
-// ── Proofing Issue Generator ──
-
-function generateProofingMarkdown(
-	slice: ArchitectureSlice,
-	epicName: string,
-): string {
-	const moduleId = slice.module.replace(/^module-/, "");
-
-	return `---
-guardian_issue:
-  id: "ISSUE-PROOFING"
-  epic: "${epicName}"
-  component: "Proofing & CI Enforcement"
-  module: "${slice.module}"
-  status: planned
-  priority: critical
-  dependencies: []
-
-  in_scope:
-    - Create deterministic validation scripts for each contract
-    - Verify all interfaces have matching implementations
-    - Check test coverage meets thresholds
-    - Integrate proofing scripts into .pi/scripts/ci/
-    - Scripts must be self-contained shell scripts (zero token cost)
-    - Scripts auto-register in local-ci.sh via regex (stage_*.sh, check_*.sh)
-    - Run bash .pi/scripts/ci/local-ci.sh — must pass before closing this issue
-
-  out_of_scope:
-    - Implementation changes
-    - New features
-    - Production deployment
-
-  affected_layers:
-    ci:
-      - New proofing scripts in .pi/scripts/ci/
-      - Updated CI stage configuration
-
-  canonical_references:
-    - module: ".pi/architecture/modules/${slice.module}.md"
-
-  acceptance_criteria:
-    - "All proofing scripts created and executable"
-    - "Each contract has at least one validation check"
-    - "Scripts pass on current implementation"
-    - "Scripts fail if implementation is removed"
-    - "Scripts integrated into CI pipeline (stage in run_hardening_stages.sh)"
-    - "bash .pi/scripts/ci/local-ci.sh exits 0 (all scripts pass together)"
-
-  validators:
-    - ci
-    - tests
-    - canonical
-
-  implementation_notes: |
-    Create deterministic shell scripts that validate: each defined interface has an
-    implementation, each implementation has tests, test coverage meets threshold,
-    contracts are not violated. These escape the LLM ad-hoc check trap — they run
-    every build for zero token cost.
-
-  file_changes:
-    - "create: .pi/scripts/ci/check_${moduleId}_contracts.sh"
-    - "create: .pi/scripts/ci/check_${moduleId}_coverage.sh"
-    - "create: .pi/scripts/ci/stage_${moduleId}_proofing.sh"
-    - "modify: .pi/scripts/ci/run_hardening_stages.sh"
-    - "modify (auto): .pi/scripts/ci/local-ci.sh — scripts register via regex pattern, no manual edit needed"
----
-
-# Proofing & CI Enforcement: ${slice.module}
-
-## Intent
-
-Create deterministic, automated validation scripts that prove every contract from the
-freeze phase is correctly implemented and tested. These scripts make compliance
-automatic — no human review needed for routine checks.
-
-## What Each Script Does
-
-### Contract Implementation Check
-- Reads each interface from the contract freeze
-- Verifies a concrete implementation class exists
-- Verifies all interface methods are implemented
-- Reports violations with file:line references
-
-### Coverage Threshold Check
-- Runs the project's coverage tool
-- Asserts each module meets minimum coverage (default 80%)
-- Fails the build if coverage drops
-
-### CI Integration
-Each check becomes a CI stage in the hardening pipeline — it runs automatically
-on every PR. No LLM cost. No human review. Just pass or fail.
-
-## Scripts To Create
-
-| Script | Purpose | Location |
-|--------|---------|----------|
-| check_${moduleId}_contracts.sh | Validate contract implementation | .pi/scripts/ci/ |
-| check_${moduleId}_coverage.sh | Enforce coverage thresholds | .pi/scripts/ci/ |
-| stage_${moduleId}_proofing.sh | CI stage wrapper | .pi/scripts/ci/ |
-
-## CI Pipeline Update
-
-Add the new stage to \`run_hardening_stages.sh\`:
-
-\`\`\`bash
-run_stage "11" "${moduleId}_proofing" \\
-    "\${SCRIPTS_DIR}/stage_${moduleId}_proofing.sh" \\
-    "always"
-\`\`\`
-
-## Acceptance Criteria
-
-| # | Criterion | Script |
-|---|-----------|--------|
-| 1 | All interfaces have implementations | check_contracts.sh |
-| 2 | Coverage ≥ 80% per module | check_coverage.sh |
-| 3 | CI runs checks on every PR | run_hardening_stages.sh |
-| 4 | All scripts exit 0 on pass, 1 on fail | self-validating |
-| 5 | All scripts pass together | bash .pi/scripts/ci/local-ci.sh |
-
-## Implementation
-
-> **Agent:** Create shell scripts. Keep them simple — grep, find, awk.
-> No frameworks, no dependencies. Each script should be:
-> 1. Runnable standalone (bash script.sh)
-> 2. Runnable as a CI stage
-> 3. Self-documenting with --help
-> 4. Exit 0 for pass, 1 for fail
->
-> End by running the full CI pipeline to verify integration:
-> \`bash .pi/scripts/ci/run_hardening_stages.sh\`
-`;
-}
-
-// ── Architecture Readiness Generator (expanded) ──
-
-function generateArchitectureReadinessMarkdown(
-	slice: ArchitectureSlice,
-	epicName: string,
-): string {
-	const moduleId = slice.module.replace(/^module-/, "");
-
-	return `---
-guardian_issue:
-  id: "ISSUE-READINESS"
-  epic: "${epicName}"
-  component: "Architecture Readiness"
-  module: "${slice.module}"
-  status: planned
-  priority: critical
-  dependencies: []
-
-  in_scope:
-    - Create runbook (startup, shutdown, recovery procedures)
-    - Create DR plan (backup, restore, failover)
-    - Add observability (metrics, tracing, structured logging)
-    - Add health check endpoints
-    - Update architecture documentation
-    - Sync canonical references
-    - Verify CI enforces all the above
-
-  out_of_scope:
-    - New feature work
-    - Implementation changes
-
-  affected_layers:
-    domain:
-      - Architecture documentation updates
-    application:
-      - Observability hooks
-    infrastructure:
-      - Health checks, monitoring config
-    ci:
-      - Verify proofing scripts + validators in CI
-
-  canonical_references:
-    - module: ".pi/architecture/modules/${slice.module}.md"
-
-  acceptance_criteria:
-    - "Runbook created and reviewed"
-    - "DR plan documented"
-    - "Observability patterns in place (tracing, metrics, logging)"
-    - "Health check endpoint responds"
-    - "Architecture docs synced with implementation"
-    - "Canonical references verified (validate-canonical.sh passes)"
-    - "Proofing scripts integrated in CI and passing"
-    - "All validators pass: ci, tests, security, architecture, canonical, operations"
-
-  validators:
-    - ci
-    - tests
-    - security
-    - architecture
-    - canonical
-    - operations
-
-  implementation_notes: |
-    The final issue in every epic. Production readiness means: the team can operate it
-    (runbook), recover from failure (DR plan), observe it (metrics/tracing/logging),
-    and CI will catch regressions (proofing scripts + validators).
-
-  file_changes:
-    - "create: docs/runbook-${moduleId}.md"
-    - "create: docs/dr-plan-${moduleId}.md"
-    - "modify: .pi/architecture/CHANGELOG.md"
-    - "modify: .pi/architecture/modules/${slice.module}.md"
----
-
-# Architecture Readiness: ${slice.module}
-
-## Intent
-
-Make the ${slice.module} module production-ready. This is the final issue in every epic
-— it closes the loop between implementation and operability.
-
-## Deliverables
-
-### Runbook
-\`docs/runbook-${moduleId}.md\` covering:
-- Startup sequence and dependencies
-- Graceful shutdown procedure
-- Common failure modes and recovery
-- Configuration reference
-
-### DR Plan
-\`docs/dr-plan-${moduleId}.md\` covering:
-- Backup strategy and schedule
-- Restore procedure
-- Failover plan
-- RTO/RPO targets
-
-### Observability
-- Metrics: key business and technical metrics exposed
-- Tracing: distributed tracing context propagated
-- Logging: structured logging with correlation IDs
-- Health: /health endpoint with dependency checks
-
-### CI Enforcement
-Verify that:
-- Proofing scripts from the proofing issue are in CI
-- All validators (ci, tests, security, architecture, canonical, operations) pass
-- A CI pipeline run against this state succeeds
-
-## Acceptance Criteria
-
-| # | Criterion | Validator |
-|---|-----------|-----------|
-| 1 | Runbook exists | manual review |
-| 2 | DR plan exists | manual review |
-| 3 | Observability patterns present | validate-operations.sh |
-| 4 | Canonical references synced | validate-canonical.sh |
-| 5 | CI enforce validators | validate-ci.sh |
-| 6 | All proofing scripts pass | run_hardening_stages.sh |
-| 7 | Architecture docs updated | validate-architecture.sh |
-
-## Implementation
-
-> **Agent:** Close out the epic properly:
-> 1. Write runbook and DR plan docs
-> 2. Add observability instrumentation
-> 3. Update architecture module docs with final implementation details
-> 4. Sync CHANGE LOG
-> 5. Verify proofing scripts from the proofing issue pass
-> 6. Run full validation suite
-> 7. Architecture readiness validator: bash .pi/scripts/validate-architecture-readiness.sh
-> 8. Create final MR
-`;
-}
-
+import type { ArchitectureSlice, EpicState, ExtensionAPI, ExtensionContext, ModuleComponent } from "./architect-lib/types.ts";
+import {
+	ARCH_MODULES_DIR,
+	commandExists,
+	createRemoteIssue,
+	discoverModules,
+	ensureRemoteRepo,
+	findModuleByName,
+	findNextLogicalSlice,
+	getGitBaseUrl,
+	linkRemoteIssue,
+	parseModuleFile,
+	readGroupId,
+	readRepository,
+	readRepoTool,
+	runScript,
+} from "./architect-lib/helpers.ts";
+import {
+	generateArchitectureReadinessMarkdown,
+	generateContractFreezeMarkdown,
+	generateIssueMarkdown,
+	generateProofingMarkdown,
+} from "./architect-lib/generators.ts";
 
 // ── Epic State Persistence ──
 
@@ -1318,8 +85,6 @@ class EpicManager {
 		name: string,
 		trackingIssueId?: string,
 	): Promise<EpicState> {
-		const lang = readLanguage(this.cwd);
-		const skillName = codegenSkillName(lang);
 		const moduleFiles = discoverModules(this.cwd);
 		if (moduleFiles.length === 0) {
 			throw new Error("No architecture modules found in .pi/architecture/modules/.");
@@ -1333,32 +98,14 @@ class EpicManager {
 			const planned = components.filter((c: ModuleComponent) => c.status === "planned");
 			if (planned.length > 0) {
 				slice = { module: matchedModule.replace(".md", ""), components, nextLogicalSlice: planned };
-			} else {
-				ctx.ui.notify(
-					`Module "${matchedModule}" found for epic "${name}" but has no parseable components. ` +
-					`Make sure its \`## Components\` section uses sub-headings (\`### ComponentName\`) with \`status:\` markers. ` +
-					`Falling back to first module with planned components.`,
-					"warn",
-				);
 			}
 		}
-		// Fallback: if matched module has no planned components, error instead of silently switching
+		// Fallback: first module with planned components
 		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 module found matching "${name}". Using first module with planned components: "${slice.module}".`,
-				"warn",
-			);
+		}
+		if (!slice) {
+			throw new Error("All architecture components are implemented. No next slice found.");
 		}
 
 		ctx.ui.setStatus("architect", `Planning epic: ${name}`);
@@ -1435,7 +182,7 @@ class EpicManager {
 			status: "planned",
 			remoteIssueId: null as string | null,
 		};
-		const freezeMarkdown = generateContractFreezeMarkdown(slice, name, skillName);
+		const freezeMarkdown = generateContractFreezeMarkdown(slice, name);
 		writeFileSync(join(issuesDir, `${freezeId}.md`), freezeMarkdown);
 		if (hasRemote && remoteRepo) {
 			const result = createRemoteIssue(this.cwd, freezeEntry.title, join(issuesDir, `${freezeId}.md`), "epic,contract", remoteRepo);
@@ -1456,7 +203,7 @@ class EpicManager {
 				status: "planned" as string,
 				remoteIssueId: null as string | null,
 			};
-			const md = generateIssueMarkdown(comp, slice, i, slice.nextLogicalSlice.length, skillName);
+			const md = generateIssueMarkdown(comp, slice, i, slice.nextLogicalSlice.length);
 			writeFileSync(join(issuesDir, `${id}.md`), md);
 			if (hasRemote && remoteRepo) {
 				const result = createRemoteIssue(this.cwd, entry.title, join(issuesDir, `${id}.md`), "epic,implementation", remoteRepo);
@@ -1545,16 +292,13 @@ export default function (pi: ExtensionAPI) {
 	}
 
 	pi.registerCommand("architect", {
-		description: "Orchestrate the full architecture-to-implementation process including roadmap phases",
+		description: "Orchestrate the full architecture-to-implementation process",
 		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] | --roadmap | --phase \"Phase 1\" | --phase-status | --phase-done <N> | --phase-module-done <N> \"Module\" | status | next-epic | abort",
-					"info",
-				);
+				ctx.ui.notify("Usage: /architect [--epic Name] [--tracking-issue N] | status | next-epic | abort", "info");
 				return;
 			}
 			const action = tokens[0];
@@ -1585,336 +329,6 @@ 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 issues already exist for this module (session restart)
-					const issuesDir = join(ctx.cwd, ".pi/issues");
-					const freezePath = join(issuesDir, "issue-contract-freeze.md");
-					if (existsSync(freezePath)) {
-						// Issues exist — reconstruct pipeline without re-creating
-						const existingIssues: string[] = [];
-						if (existsSync(issuesDir)) {
-							const files = readdirSync(issuesDir);
-							for (const f of files) {
-								if (f.endsWith(".md") && !f.startsWith(".")) {
-									existingIssues.push(f.replace(/\.md$/, ""));
-								}
-							}
-						}
-						const pipelineFile = join(ctx.cwd, ".pi/.guardian-pipeline-state.json");
-						if (!existsSync(pipelineFile) && existingIssues.length > 0) {
-							const pipelineId = `PL-${String(Math.floor(Math.random() * 10000)).padStart(4, "0")}`;
-							const pipelineState = {
-								id: pipelineId,
-								name: mod.name,
-								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: "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(),
-							};
-							const pipelineDir = dirname(pipelineFile);
-							if (!existsSync(pipelineDir)) mkdirSync(pipelineDir, { recursive: true });
-							writeFileSync(pipelineFile, JSON.stringify(pipelineState, null, 2));
-						}
-						results.push(`📋 ${mod.name} — ${existingIssues.length} issues found (pipeline resumed)`);
-						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;
@@ -1947,6 +361,16 @@ 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");
@@ -2022,11 +446,8 @@ export default function (pi: ExtensionAPI) {
 					issueContent || `Review .pi/issues/${issueFilename} for full details.`,
 				].join("\n");
 
-				pi.sendMessage(
-					{ content: instructions, display: true },
-					{ deliverAs: "followUp", triggerTurn: true },
-				);
-				return;
+				ctx.ui.notify(`Epic "${epicName}" created with ${items.length} issues. Pipeline ${pipelineId} ready.`, "success");
+				return instructions;
 			} catch (e) {
 				ctx.ui.notify(`Architect error: ${e}`, "error");
 			}
@@ -2075,15 +496,4 @@ 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) }] };
-		},
-	});
 }