guardian-framework 0.1.57 → 0.1.59

package/dist/cli.js

@@ -2224,7 +2224,7 @@ function calculateTokenStats(targetDir, manifest) {
     lastCalculatedAt: new Date().toISOString()
   };
 }
-var _filename, _dirname, MANIFEST_FILE = "guardian-manifest.json", FRAMEWORK_VERSION = "0.1.57", SCHEMA_VERSION = "0.1";
+var _filename, _dirname, MANIFEST_FILE = "guardian-manifest.json", FRAMEWORK_VERSION = "0.1.59", SCHEMA_VERSION = "0.1";
 var init_manifest = __esm(() => {
   _filename = fileURLToPath(import.meta.url);
   _dirname = path3.dirname(_filename);
@@ -2303,7 +2303,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.57", 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.59", 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 = {
     ".": {
@@ -14208,7 +14208,7 @@ async function runVerify(targetDir = process.cwd()) {
 
 // src/index.ts
 init_manifest();
-var VERSION = "0.1.57";
+var VERSION = "0.1.59";
 async function runCli() {
   const args = parseArgs({
     allowPositionals: true,

package/dist/exports.js

@@ -1919,7 +1919,7 @@ function calculateTokenStats(targetDir, manifest) {
     lastCalculatedAt: new Date().toISOString()
   };
 }
-var _filename, _dirname, MANIFEST_FILE = "guardian-manifest.json", FRAMEWORK_VERSION = "0.1.57", SCHEMA_VERSION = "0.1";
+var _filename, _dirname, MANIFEST_FILE = "guardian-manifest.json", FRAMEWORK_VERSION = "0.1.59", SCHEMA_VERSION = "0.1";
 var init_manifest = __esm(() => {
   _filename = fileURLToPath(import.meta.url);
   _dirname = path.dirname(_filename);
@@ -1963,7 +1963,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.57", 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.59", 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.57",
+	"version": "0.1.59",
 	"description": "Token-optimized agentic framework scaffolder with pi-first architecture",
 	"type": "module",
 	"main": "dist/exports.js",

package/templates/pi/extensions/architect-lib/forge-adapter.ts

@@ -0,0 +1,266 @@
+/**
+ * Forge Adapter — Centralized forge abstraction for GitHub and GitLab.
+ *
+ * All forge-specific operations (auth, repo, issues, MR/PR) go through this module.
+ * Use `readRepoTool()` to determine which forge is active, then call the appropriate
+ * helper — null returned / empty string means "not available / not supported".
+ *
+ * Canonical Reference: .pi/extensions/architect-lib/helpers.ts
+ * Last Sync: 2026-07-09
+ */
+
+import { execFileSync, execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// ── Forge Detection ──
+
+/**
+ * Read repoTool from guardian-manifest.json (defaults to "gh")
+ */
+export 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 repository slug from guardian-manifest.json
+ */
+export 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;
+}
+
+/**
+ * Get forge base URL. For GitLab, detects self-hosted instances via glab config.
+ */
+export 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) {
+				const normalized = uri.replace(/\/+$/, "");
+				// Ensure URL has a scheme, default to https://
+				if (!/^https?:\/\//i.test(normalized)) {
+					return `https://${normalized}`;
+				}
+				return normalized;
+			}
+		} catch {
+			// fall through to default
+		}
+		return "https://gitlab.com";
+	}
+	return "https://github.com";
+}
+
+export function commandExists(cmd: string): boolean {
+	try {
+		execSync(`command -v ${cmd}`, { stdio: "ignore" });
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Run a bash script and return exit code + stdout.
+ */
+export 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 ?? "" };
+	}
+}
+
+// ── Auth Validation ──
+
+/**
+ * Verify forge CLI is authenticated AND has access to the configured repository.
+ * Returns true only if both checks pass.
+ */
+export function verifyForgeAccess(cwd: string): { authenticated: boolean; projectAccessible: boolean } {
+	const repoTool = readRepoTool(cwd);
+	const repository = readRepository(cwd);
+	const result = { authenticated: false, projectAccessible: false };
+
+	if (!commandExists(repoTool)) return result;
+
+	// Check CLI auth status
+	const authResult = runScript(
+		cwd,
+		repoTool === "glab" ? "glab auth status 2>/dev/null" : "gh auth status 2>/dev/null",
+	);
+	if (authResult.exitCode !== 0) return result;
+	result.authenticated = true;
+
+	// Verify project-level access
+	if (repository) {
+		const projectCheck = runScript(
+			cwd,
+			repoTool === "glab"
+				? `glab api "projects/${repository}" --method GET 2>/dev/null | jq -r '.id // empty'`
+				: `gh api "repos/${repository}" --method GET 2>/dev/null | jq -r '.id // empty'`,
+		);
+		if (projectCheck.exitCode === 0 && projectCheck.stdout.trim().length > 0) {
+			result.projectAccessible = true;
+		}
+	} else {
+		// No repository configured — auth is sufficient
+		result.projectAccessible = true;
+	}
+
+	return result;
+}
+
+// ── PR/MR Operations ──
+
+/**
+ * Check if a PR (GitHub) or MR (GitLab) exists for the given branch.
+ */
+export function forgePrExists(cwd: string, branch: string): boolean {
+	const repoTool = readRepoTool(cwd);
+	try {
+		if (repoTool === "glab") {
+			const result = execSync(
+				`glab mr list --source-branch "${branch}" --output json 2>/dev/null`,
+				{ cwd, encoding: "utf-8" },
+			);
+			const parsed = JSON.parse(result.trim() || "[]");
+			return Array.isArray(parsed) && parsed.length > 0;
+		}
+		const result = execSync(
+			`gh pr list --head "${branch}" --json number --jq "length" 2>/dev/null`,
+			{ cwd, encoding: "utf-8" },
+		);
+		return parseInt(result.trim()) > 0;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Check if a PR (GitHub) or MR (GitLab) for the given branch is merged.
+ */
+export function forgePrMerged(cwd: string, branch: string): boolean {
+	const repoTool = readRepoTool(cwd);
+	try {
+		if (repoTool === "glab") {
+			const result = execSync(
+				`glab mr list --source-branch "${branch}" --output json 2>/dev/null`,
+				{ cwd, encoding: "utf-8" },
+			);
+			const parsed = JSON.parse(result.trim() || "[]") as { state?: string }[];
+			return Array.isArray(parsed) && parsed.some((mr) => mr.state === "merged");
+		}
+		const result = execSync(
+			`gh pr list --head "${branch}" --json state,mergedAt --jq ".[] | select(.state==\"MERGED\") | .mergedAt" 2>/dev/null`,
+			{ cwd, encoding: "utf-8" },
+		);
+		return result.trim().length > 0;
+	} catch {
+		return false;
+	}
+}
+
+// ── Issue Operations ──
+
+/**
+ * Fetch issue content from remote forge or fallback to local file.
+ */
+export function fetchIssueContent(
+	cwd: string,
+	issueId: string,
+	remoteIssueId?: string | null,
+): { content: string; source: string } {
+	const repository = readRepository(cwd);
+	const repoTool = readRepoTool(cwd);
+	const baseUrl = getGitBaseUrl(repoTool);
+
+	if (remoteIssueId && repository) {
+		try {
+			let result;
+			if (repoTool === "glab") {
+				result = runScript(
+					cwd,
+					`glab issue view ${remoteIssueId} --repo ${repository} --output json`,
+				);
+				if (result.exitCode === 0 && result.stdout) {
+					const parsed = JSON.parse(result.stdout) as {
+						title?: string;
+						description?: string;
+					};
+					if (parsed.description) {
+						return {
+							content: parsed.description,
+							source: `Remote issue: ${baseUrl}/${repository}/issues/${remoteIssueId}`,
+						};
+					}
+				}
+			} else {
+				result = runScript(
+					cwd,
+					`gh issue view ${remoteIssueId} --repo ${repository} --json title,body`,
+				);
+				if (result.exitCode === 0 && result.stdout) {
+					const parsed = JSON.parse(result.stdout) as { title?: string; body?: string };
+					if (parsed.body) {
+						return {
+							content: parsed.body,
+							source: `Remote issue: ${baseUrl}/${repository}/issues/${remoteIssueId}`,
+						};
+					}
+				}
+			}
+		} catch {
+			// fallback to local file
+		}
+	}
+
+	// Fallback to local file
+	const issueFilename = `${issueId}.md`.replace(/\//g, "-");
+	const issuePath = join(cwd, ".pi/issues", issueFilename);
+	try {
+		if (existsSync(issuePath)) {
+			return {
+				content: readFileSync(issuePath, "utf-8"),
+				source: `Local file: .pi/issues/${issueFilename}`,
+			};
+		}
+	} catch {
+		// ignore
+	}
+
+	return {
+		content: "Issue content not available.",
+		source: issueId,
+	};
+}

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

@@ -1,12 +1,22 @@
 import { execFileSync, execSync } from "node:child_process";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { join } from "node:path";
-import type { ExtensionContext, EpicState, ModuleComponent, ArchitectureSlice } from "./types.ts";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { ExtensionContext, EpicState, ModuleComponent, ArchitectureSlice, RoadmapPhase, RoadmapState, RoadmapPhaseModule } from "./types.ts";
+import {
+	readRepoTool as adapterReadRepoTool,
+	readRepository as adapterReadRepository,
+	getGitBaseUrl as adapterGetGitBaseUrl,
+	commandExists as adapterCommandExists,
+	runScript as adapterRunScript,
+	verifyForgeAccess,
+} from "./forge-adapter.ts";
 // ── Constants ──
 
 export const EPIC_STATE_KEY = ".pi/.guardian-epic-state.json";
 export const ARCH_MODULES_DIR = ".pi/architecture/modules";
 export const ISSUES_DIR = ".pi/issues";
+export const ROADMAP_FILE = ".pi/architecture/implementation-roadmap.md";
+export const ROADMAP_STATE_FILE = ".pi/.guardian-roadmap-state.json";
 
 // ── Helpers ──
 
@@ -14,77 +24,14 @@ export function log(ctx: ExtensionContext, message: string, level = "info") {
 	ctx.ui.notify(message, level);
 }
 
-export 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")
-export 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
-export 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;
-}
-
-/**
- * Get Git platform base URL. For GitLab, tries to detect self-hosted instances.
- */
-export 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";
-}
+// These functions are now centralized in ../forge-adapter.ts
+// We re-export them here for backward compatibility with architect.ts
 
-export function commandExists(cmd: string): boolean {
-	try {
-		execSync(`command -v ${cmd}`, { stdio: "ignore" });
-		return true;
-	} catch {
-		return false;
-	}
-}
+export const runScript = adapterRunScript;
+export const readRepoTool = adapterReadRepoTool;
+export const readRepository = adapterReadRepository;
+export const getGitBaseUrl = adapterGetGitBaseUrl;
+export const commandExists = adapterCommandExists;
 
 // Try to create a remote GitHub/GitLab issue via the shell script wrapper.
 // Uses execFileSync to avoid shell quoting issues with nested commands.
@@ -167,15 +114,37 @@ export function ensureRemoteRepo(
 	// 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;
+		// Validate existing origin: check it's reachable and matches the manifest repo
+		const remoteUrl = remoteCheck.stdout.trim();
+		const repoSlug = repository.replace(/^https?:\/\//, "").replace(/^git@/, "");
+
+		// Check reachability
+		const reachable = runScript(cwd, "git ls-remote origin HEAD 2>/dev/null");
+		if (reachable.exitCode !== 0) {
+			console.warn(`Origin remote exists but is not reachable (${remoteUrl}). Will re-create.`);
+			// Remove and re-create below
+			runScript(cwd, "git remote remove origin 2>/dev/null");
+		} else {
+			// Verify remote URL contains the manifest repository path
+			if (remoteUrl.includes(repository.replace(/^https?:\/\//, "").replace(/^git@/, "").replace(/\.git$/, ""))
+				|| remoteUrl.includes(repository)) {
+				return repository;
+			}
+			console.warn(`Existing origin points to a different repository. Re-creating.`);
+			runScript(cwd, "git remote remove origin 2>/dev/null");
+		}
 	}
 
 	// Remote not configured locally — ensure the remote repo exists on GitHub/GitLab
 	if (repoTool === "gh") {
-		runScript(
+		const createResult = runScript(
 			cwd,
 			`gh repo create "${repository}" --private --description "Epic: ${epicName}" 2>&1`,
 		);
+		if (createResult.exitCode !== 0) {
+			console.warn(`Failed to create GitHub repo: ${createResult.stdout}`);
+			return "";
+		}
 		// 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`;
@@ -185,10 +154,14 @@ export function ensureRemoteRepo(
 
 	// GitLab path — detect self-hosted base URL from glab config
 	const glabBaseUrl = getGitBaseUrl("glab");
-	runScript(
+	const createResult = runScript(
 		cwd,
 		`glab repo create "${repository}" --private --description "Epic: ${epicName}" 2>&1`,
 	);
+	if (createResult.exitCode !== 0) {
+		console.warn(`Failed to create GitLab project: ${createResult.stdout}`);
+		return "";
+	}
 	runScript(cwd, "git remote remove origin 2>/dev/null");
 	const httpsUrl = `${glabBaseUrl}/${repository}.git`;
 	runScript(cwd, `git remote add origin "${httpsUrl}"`);
@@ -375,3 +348,204 @@ export function findNextLogicalSlice(cwd: string, moduleFiles: string[]): Archit
 	return null;
 }
 
+// ── Roadmap Functions ──
+
+export 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 || [],
+					completedModules: currentPhase.completedModules || [],
+					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: [],
+				completedModules: [],
+				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;
+		}
+	}
+
+	return phases;
+}
+
+export 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));
+}
+
+export 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;
+	}
+}
+
+export 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" ? "🔄" : "⏳";
+		const completedModules = phase.completedModules?.length || 0;
+		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 (${completedModules}/${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) {
+			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");
+}
+
+export 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
+}
+

package/templates/pi/extensions/architect.ts

@@ -35,6 +35,31 @@ import {
 	generateProofingMarkdown,
 } from "./architect-lib/generators";
 
+// ── Helpers ──
+
+/**
+ * Parse CLI-style arguments with quote awareness.
+ * Handles double-quoted strings so that `--epic "My Epic"` yields ["--epic", "My Epic"].
+ */
+function parseArgs(raw: string): string[] {
+	const tokens: string[] = [];
+	let current = "";
+	let inQuote = false;
+	for (const ch of raw) {
+		if (ch === '"') {
+			inQuote = !inQuote;
+			continue;
+		}
+		if (!inQuote && ch === " ") {
+			if (current) { tokens.push(current); current = ""; }
+			continue;
+		}
+		current += ch;
+	}
+	if (current) tokens.push(current);
+	return tokens;
+}
+
 // ── Epic State Persistence ──
 
 const EPIC_STATE_KEY = ".pi/.guardian-epic-state.json";
@@ -127,8 +152,18 @@ class EpicManager {
 				repoTool === "glab" ? "glab auth status 2>/dev/null" : "gh auth status 2>/dev/null",
 			);
 			if (authCheck.exitCode === 0) {
-				remoteRepo = ensureRemoteRepo(this.cwd, targetRepo, name, repoTool);
-				hasRemote = remoteRepo.length > 0;
+				// Verify project-level access, not just global auth
+				const projectAccessCheck = repository ? runScript(
+					this.cwd,
+					repoTool === "glab"
+						? `glab api "projects/${repository}" --method GET 2>/dev/null | jq -r '.id // empty'`
+						: `gh api "repos/${repository}" --method GET 2>/dev/null | jq -r '.id // empty'`,
+				) : { exitCode: 0, stdout: "" };
+
+				if (projectAccessCheck.exitCode === 0 && projectAccessCheck.stdout.trim().length > 0) {
+					remoteRepo = ensureRemoteRepo(this.cwd, targetRepo, name, repoTool);
+					hasRemote = remoteRepo.length > 0;
+				}
 			}
 		}
 
@@ -301,7 +336,7 @@ export default function (pi: ExtensionAPI) {
 		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) : [];
+			const tokens = raw ? parseArgs(raw) : [];
 			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",

package/templates/pi/extensions/pipeline.ts

@@ -23,6 +23,15 @@
 import { execSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import {
+	fetchIssueContent,
+	forgePrExists as adapterForgePrExists,
+	forgePrMerged as adapterForgePrMerged,
+	readRepoTool,
+	readRepository,
+	getGitBaseUrl,
+	runScript,
+} from "./architect-lib/forge-adapter.ts";
 
 // ── Validator Scripts ──
 
@@ -38,131 +47,27 @@ const VALIDATOR_SCRIPTS: Record<string, string> = {
 
 // ── Helpers ──
 
-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 ?? "" };
-	}
-}
-
-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 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";
-}
-
-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";
-}
-
-// Fetch issue content from remote (gh or glab) or fallback to local file
-function fetchIssueContent(
-	cwd: string,
-	issueId: string,
-	remoteIssueId?: string | null,
-): { content: string; source: string } {
-	const repository = readRepository(cwd);
-	const repoTool = readRepoTool(cwd);
-	const baseUrl = getGitBaseUrl(repoTool);
-
-	if (remoteIssueId && repository) {
-		try {
-			let result;
-			if (repoTool === "glab") {
-				result = runScript(
-					cwd,
-					`glab issue view ${remoteIssueId} --repo ${repository} --output json`,
-				);
-				if (result.exitCode === 0 && result.stdout) {
-					const parsed = JSON.parse(result.stdout) as {
-						title?: string;
-						description?: string;
-					};
-					if (parsed.description) {
-						return {
-							content: parsed.description,
-							source: `Remote issue: ${baseUrl}/${repository}/issues/${remoteIssueId}`,
-						};
-					}
-				}
-			} else {
-				result = runScript(
-					cwd,
-					`gh issue view ${remoteIssueId} --repo ${repository} --json title,body`,
-				);
-				if (result.exitCode === 0 && result.stdout) {
-					const parsed = JSON.parse(result.stdout) as { title?: string; body?: string };
-					if (parsed.body) {
-						return {
-							content: parsed.body,
-							source: `Remote issue: ${baseUrl}/${repository}/issues/${remoteIssueId}`,
-						};
-					}
-				}
-			}
-		} catch {
-			// fallback to local file
+/**
+ * Parse CLI-style arguments with quote awareness.
+ * Handles double-quoted strings so that `--name "My Epic"` yields ["--name", "My Epic"].
+ */
+function parseArgs(raw: string): string[] {
+	const tokens: string[] = [];
+	let current = "";
+	let inQuote = false;
+	for (const ch of raw) {
+		if (ch === '"') {
+			inQuote = !inQuote;
+			continue;
 		}
-	}
-
-	// Fallback to local file
-	const issueFilename = `${issueId}.md`.replace(/\//g, "-");
-	const issuePath = join(cwd, ".pi/issues", issueFilename);
-	try {
-		if (existsSync(issuePath)) {
-			return {
-				content: readFileSync(issuePath, "utf-8"),
-				source: `Local file: .pi/issues/${issueFilename}`,
-			};
+		if (!inQuote && ch === " ") {
+			if (current) { tokens.push(current); current = ""; }
+			continue;
 		}
-	} catch {
-		// ignore
+		current += ch;
 	}
-
-	return {
-		content: "Issue content not available.",
-		source: issueId,
-	};
+	if (current) tokens.push(current);
+	return tokens;
 }
 
 // ── Types ──
@@ -330,9 +235,19 @@ function statusLine(state: PipelineState | null): string {
 
 class PipelineManager {
 	private state: PipelineState | null;
+	private repoTool: string;
 
 	constructor(private cwd: string) {
 		this.state = loadPipelineState(cwd);
+		this.repoTool = readRepoTool(cwd);
+	}
+
+	/**
+	 * Reload pipeline state from disk, discarding any cached in-memory state.
+	 * Use this when another extension (e.g., architect) may have written state directly.
+	 */
+	private reloadFromDisk(): void {
+		this.state = loadPipelineState(this.cwd);
 	}
 
 	/**
@@ -352,8 +267,8 @@ class PipelineManager {
 
 			// Check ground truth
 			const branchExists = this.gitBranchExists(branch);
-			const prMerged = this.ghPrMerged(branch);
-			const prExists = this.ghPrExists(branch);
+			const prMerged = this.forgePrMerged(branch);
+			const prExists = this.forgePrExists(branch);
 			const hasCommits = branchExists && this.branchHasCommits(branch);
 
 			if (prMerged) {
@@ -400,7 +315,7 @@ class PipelineManager {
 		}
 
 		// If all items done, update overall status
-		if (this.state.results.every((r) => r.status === "done") && this.state.items.length > 0) {
+		if (this.state.results.length === this.state.items.length && this.state.results.length > 0 && this.state.results.every((r) => r.status === "done")) {
 			this.state.status = "done";
 			this.state.currentItemIndex = this.state.items.length;
 			this.state.currentStepIndex = 0;
@@ -442,18 +357,18 @@ class PipelineManager {
 		} catch { return false; }
 	}
 
-	private ghPrExists(branch: string): boolean {
-		try {
-			const result = execSync(`gh pr list --head "${branch}" --json number --jq "length" 2>/dev/null`, { cwd: this.cwd, encoding: "utf-8" });
-			return parseInt(result.trim()) > 0;
-		} catch { return false; }
+	/**
+	 * Check if a PR/MR exists for the given branch, dispatching by repoTool.
+	 */
+	private forgePrExists(branch: string): boolean {
+		return adapterForgePrExists(this.cwd, branch);
 	}
 
-	private ghPrMerged(branch: string): boolean {
-		try {
-			const result = execSync(`gh pr list --head "${branch}" --json state,mergedAt --jq ".[] | select(.state==\"MERGED\") | .mergedAt" 2>/dev/null`, { cwd: this.cwd, encoding: "utf-8" });
-			return result.trim().length > 0;
-		} catch { return false; }
+	/**
+	 * Check if a PR/MR for the given branch is merged, dispatching by repoTool.
+	 */
+	private forgePrMerged(branch: string): boolean {
+		return adapterForgePrMerged(this.cwd, branch);
 	}
 
 	/**
@@ -507,16 +422,16 @@ class PipelineManager {
 				return { verified: true, reason: "Commits found on branch" };
 			}
 			case "create-mr": {
-				if (!this.ghPrExists(branch)) {
-					return { verified: false, reason: `No PR found for branch ${branch}. Create a PR first.` };
+				if (!this.forgePrExists(branch)) {
+					return { verified: false, reason: `No PR/MR found for branch ${branch}. Create a PR/MR first.` };
 				}
-				return { verified: true, reason: "PR exists" };
+				return { verified: true, reason: "PR/MR exists" };
 			}
 			case "merge": {
-				if (!this.ghPrMerged(branch)) {
-					return { verified: false, reason: `PR for ${branch} is not merged yet.` };
+				if (!this.forgePrMerged(branch)) {
+					return { verified: false, reason: `PR/MR for ${branch} is not merged yet.` };
 				}
-				return { verified: true, reason: "PR merged" };
+				return { verified: true, reason: "PR/MR merged" };
 			}
 			default:
 				return { verified: true, reason: "Unknown step — skipping verification" };
@@ -785,9 +700,9 @@ export default function (pi: ExtensionAPI) {
 			if (!manager) manager = new PipelineManager(ctx.cwd);
 			const state = manager.getState();
 
-			// pi passes args as a string. Split into tokens.
+			// pi passes args as a string. Parse into tokens (quote-aware).
 			const raw = typeof args === "string" ? args : "";
-			const tokens = raw.split(/\s+/).filter(Boolean);
+			const tokens = parseArgs(raw);
 			const action = tokens[0];
 
 			// Status
@@ -917,6 +832,7 @@ export default function (pi: ExtensionAPI) {
 		parameters: { type: "object", properties: {} },
 		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
 			if (!manager) manager = new PipelineManager(ctx.cwd);
+			manager.reloadFromDisk();
 			const state = manager.getState();
 			if (!state) {
 				return { content: [{ type: "text" as const, text: "No active pipeline." }] };
@@ -938,6 +854,7 @@ export default function (pi: ExtensionAPI) {
 		},
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			if (!manager) manager = new PipelineManager(ctx.cwd);
+			manager.reloadFromDisk();
 			const state = manager.getState();
 			if (!state || state.status !== "running") {
 				return { content: [{ type: "text" as const, text: "No running pipeline." }] };
@@ -1037,6 +954,7 @@ export default function (pi: ExtensionAPI) {
 		},
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			if (!manager) manager = new PipelineManager(ctx.cwd);
+			manager.reloadFromDisk();
 			const state = manager.getState();
 			if (!state || state.status !== "running") {
 				return { content: [{ type: "text" as const, text: "No running pipeline." }] };
@@ -1085,6 +1003,7 @@ export default function (pi: ExtensionAPI) {
 		},
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			if (!manager) manager = new PipelineManager(ctx.cwd);
+			manager.reloadFromDisk();
 
 			const name = (params.name as string) || "pipeline";
 			const items = ((params.items as string) || "")
@@ -1133,6 +1052,7 @@ export default function (pi: ExtensionAPI) {
 		},
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			if (!manager) manager = new PipelineManager(ctx.cwd);
+			manager.reloadFromDisk();
 			const state = manager.getState();
 			if (!state || state.status !== "running") {
 				return { content: [{ type: "text" as const, text: "No running pipeline." }] };
@@ -1213,6 +1133,7 @@ export default function (pi: ExtensionAPI) {
 		parameters: { type: "object", properties: {} },
 		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
 			if (!manager) manager = new PipelineManager(ctx.cwd);
+			manager.reloadFromDisk();
 			const state = manager.getState();
 			if (!state || state.status !== "running") {
 				return { content: [{ type: "text" as const, text: "No running pipeline." }] };

package/templates/pi/preflight_report.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-07-09T08:58:48Z",
+  "timestamp": "2026-07-09T10:08:06Z",
   "mode": "all",
   "stages_run": [],
   "summary": {

package/templates/pi/scripts/git/create-tracking-issue.sh

@@ -138,16 +138,14 @@ case "$PLATFORM" in
         [[ -n "$TITLE" ]] && ARGS+=(--title "$TITLE")
         [[ -n "$MILESTONE" ]] && ARGS+=(--milestone "$MILESTONE")
 
-        # Body: strip YAML frontmatter from --body-file, then write to temp file for glab
+        # Body: strip YAML frontmatter from --body-file, then pass as inline --description
+        # (glab does not support --description-file, so we load into a string)
         if [[ -n "$BODY_FILE" && -f "$BODY_FILE" ]]; then
             STRIPPED_BODY=$(awk '/^---$/{n++; next} n>=2{print}' "$BODY_FILE")
             if [[ -n "$STRIPPED_BODY" ]]; then
-                TMP_BODY=$(mktemp /tmp/guardian-issue-body-XXXXXX 2>/dev/null) || TMP_BODY="/tmp/guardian-issue-body-$$.md"
-                echo "$STRIPPED_BODY" > "$TMP_BODY"
-                ARGS+=(--description-file "$TMP_BODY")
-                trap "rm -f '$TMP_BODY'" EXIT
+                ARGS+=(--description "$STRIPPED_BODY")
             else
-                ARGS+=(--description-file "$BODY_FILE")
+                ARGS+=(--description "$(cat "$BODY_FILE")")
             fi
         elif [[ -n "$BODY" ]]; then
             ARGS+=(--description "$BODY")

package/templates/pi/scripts/git/link-issue-to-epic.sh

@@ -42,7 +42,23 @@ Relates to #$EPIC_ID" 2>/dev/null
         echo "Linked GitHub issue #$ISSUE_ID to #$EPIC_ID"
         ;;
     gitlab)
-        glab issue update "$ISSUE_ID" --milestone "$EPIC_ID" 2>/dev/null
+        # Use GitLab API to link issue to epic (--milestone is semantically wrong).
+        # API: POST /groups/:group/epics/:epic_iid/issues/:issue_iid
+        # We derive the group from the project path.
+        if command -v jq &>/dev/null && [[ -n "${CI_PROJECT_ID:-}" || -n "${GITLAB_PROJECT_ID:-}" ]]; then
+            local pid="${CI_PROJECT_ID:-${GITLAB_PROJECT_ID:-}}"
+            glab api "projects/$pid" --method GET 2>/dev/null | jq -r '.namespace.full_path // empty' | read -r group_path
+            if [[ -n "$group_path" ]]; then
+                glab api --method POST "groups/$group_path/epics/$EPIC_ID/issues/$ISSUE_ID" 2>/dev/null || {
+                    # Fallback: add a note referencing the epic
+                    glab issue note "$ISSUE_ID" --message "Part of epic #$EPIC_ID" 2>/dev/null || true
+                }
+            else
+                glab issue note "$ISSUE_ID" --message "Part of epic #$EPIC_ID" 2>/dev/null || true
+            fi
+        else
+            glab issue note "$ISSUE_ID" --message "Part of epic #$EPIC_ID" 2>/dev/null || true
+        fi
         echo "Linked GitLab issue #$ISSUE_ID to epic #$EPIC_ID"
         ;;
     *)