guardian-framework 0.1.53 → 0.1.54

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.0", SCHEMA_VERSION = "0.1";
+var _filename, _dirname, MANIFEST_FILE = "guardian-manifest.json", FRAMEWORK_VERSION = "0.1.54", 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.53", 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.54", 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 = {
     ".": {
@@ -2316,8 +2316,7 @@ var init_package = __esm(() => {
   };
   files = [
     "dist/",
-    "templates/",
-    "pi-package/"
+    "templates/"
   ];
   engines = {
     bun: ">=1.0.0"
@@ -2337,13 +2336,13 @@ var init_package = __esm(() => {
   };
   pi = {
     extensions: [
-      "./pi-package/extensions"
+      "./templates/pi/extensions"
     ],
     skills: [
-      "./pi-package/skills"
+      "./templates/pi/skills"
     ],
     prompts: [
-      "./pi-package/prompts"
+      "./templates/pi/prompts"
     ]
   };
   repository = {
@@ -2372,7 +2371,7 @@ var init_package = __esm(() => {
     "token-optimized",
     "claude-code",
     "github-copilot",
-    "pi-package"
+    "pi"
   ];
   package_default = {
     name,
@@ -14209,7 +14208,7 @@ async function runVerify(targetDir = process.cwd()) {
 
 // src/index.ts
 init_manifest();
-var VERSION = "0.1.0";
+var VERSION = "0.1.54";
 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.0", SCHEMA_VERSION = "0.1";
+var _filename, _dirname, MANIFEST_FILE = "guardian-manifest.json", FRAMEWORK_VERSION = "0.1.54", 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.53", 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.54", 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 = {
     ".": {
@@ -1976,8 +1976,7 @@ var init_package = __esm(() => {
   };
   files = [
     "dist/",
-    "templates/",
-    "pi-package/"
+    "templates/"
   ];
   engines = {
     bun: ">=1.0.0"
@@ -1997,13 +1996,13 @@ var init_package = __esm(() => {
   };
   pi = {
     extensions: [
-      "./pi-package/extensions"
+      "./templates/pi/extensions"
     ],
     skills: [
-      "./pi-package/skills"
+      "./templates/pi/skills"
     ],
     prompts: [
-      "./pi-package/prompts"
+      "./templates/pi/prompts"
     ]
   };
   repository = {
@@ -2032,7 +2031,7 @@ var init_package = __esm(() => {
     "token-optimized",
     "claude-code",
     "github-copilot",
-    "pi-package"
+    "pi"
   ];
   package_default = {
     name,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "guardian-framework",
-	"version": "0.1.53",
+	"version": "0.1.54",
 	"description": "Token-optimized agentic framework scaffolder with pi-first architecture",
 	"type": "module",
 	"main": "dist/exports.js",
@@ -16,8 +16,7 @@
 	},
 	"files": [
 		"dist/",
-		"templates/",
-		"pi-package/"
+		"templates/"
 	],
 	"engines": {
 		"bun": ">=1.0.0"
@@ -37,13 +36,13 @@
 	},
 	"pi": {
 		"extensions": [
-			"./pi-package/extensions"
+			"./templates/pi/extensions"
 		],
 		"skills": [
-			"./pi-package/skills"
+			"./templates/pi/skills"
 		],
 		"prompts": [
-			"./pi-package/prompts"
+			"./templates/pi/prompts"
 		]
 	},
 	"repository": {
@@ -73,7 +72,7 @@
 		"token-optimized",
 		"claude-code",
 		"github-copilot",
-		"pi-package"
+		"pi"
 	],
 	"author": "Arman Wolkensteiner-Jalili",
 	"license": "MIT"

package/templates/pi/extensions/architect.ts

@@ -4,9 +4,9 @@
  * Entry point. Imports from submodules and registers the extension.
  */
 
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import type { ArchitectureSlice, EpicState, ExtensionAPI, ExtensionContext, ModuleComponent } from "./architect-lib/types.ts";
+import type { ArchitectureSlice, EpicState, ExtensionAPI, ExtensionContext, ModuleComponent, RoadmapPhase, RoadmapState, RoadmapPhaseModule } from "./architect-lib/types.ts";
 import {
 	ARCH_MODULES_DIR,
 	commandExists,
@@ -15,13 +15,18 @@ import {
 	ensureRemoteRepo,
 	findModuleByName,
 	findNextLogicalSlice,
+	formatRoadmapStatus,
 	getGitBaseUrl,
+	getNextPendingPhase,
 	linkRemoteIssue,
+	loadRoadmapState,
 	parseModuleFile,
+	parseRoadmap,
 	readGroupId,
 	readRepository,
 	readRepoTool,
 	runScript,
+	saveRoadmapState,
 } from "./architect-lib/helpers";
 import {
 	generateArchitectureReadinessMarkdown,
@@ -298,7 +303,10 @@ export default function (pi: ExtensionAPI) {
 			const raw = typeof args === "string" ? args : "";
 			const tokens = raw ? raw.split(/\s+/).filter(Boolean) : [];
 			if (tokens.length === 0) {
-				ctx.ui.notify("Usage: /architect [--epic Name] [--tracking-issue N] | status | next-epic | abort", "info");
+				ctx.ui.notify(
+					"Usage: /architect [--epic Name] [--tracking-issue N] | --roadmap | --phase \"Phase 1\" | --phase-status | --phase-done <N> | --phase-module-done <N> \"Module\" | status | next-epic | abort",
+					"info",
+				);
 				return;
 			}
 			const action = tokens[0];
@@ -326,6 +334,336 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
+			// ── 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;
+			}
+
 			const epicName = findFlag(tokens, "--epic");
 			const trackingIssueId = findFlag(tokens, "--tracking-issue");
 
@@ -499,4 +837,15 @@ export default function (pi: ExtensionAPI) {
 			return { content: [{ type: "text", text: lines.join("\n") }] };
 		},
 	});
+
+	pi.registerTool({
+		name: "architect_roadmap",
+		label: "Architect Roadmap",
+		description: "Show the implementation roadmap phases and status.",
+		parameters: { type: "object", properties: {} },
+		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+			const phases = parseRoadmap(ctx.cwd);
+			return { content: [{ type: "text", text: formatRoadmapStatus(phases) }] };
+		},
+	});
 }

package/templates/pi/extensions/ask-user-question.ts

@@ -1,6 +1,9 @@
 // biome-ignore lint/suspicious/noExplicitAny: pi ExtensionContext has no published types
 // biome-ignore lint/style/noNonNullAssertion: pi UI callbacks use non-null assertions
 /**
+ * Canonical Reference: .pi/architecture/modules/core-libraries.md
+ * Last Sync: 2026-05-31
+
  * Ask User Question Extension for pi
  *
  * biome-ignore lint/suspicious/noExplicitAny: pi ExtensionContext has no published types

package/templates/pi/extensions/bash-guard.ts

@@ -1,4 +1,7 @@
 /**
+ * Canonical Reference: .pi/architecture/modules/core-libraries.md
+ * Last Sync: 2026-05-31
+
  * Bash-Guard Extension for pi
  *
  * Interactively blocks destructive shell commands before execution.
@@ -391,7 +394,10 @@ function normalizePath(p: string): string {
 	return p.replace(/\\/g, "/");
 }
 
-/** Check if a file path is safe to read. Refuses obvious secret files. */
+/**
+ * Canonical Reference: .pi/architecture/modules/core-libraries.md
+ * Last Sync: 2026-05-31
+ Check if a file path is safe to read. Refuses obvious secret files. */
 export function checkReadable(filePath: string): { ok: true } | { ok: false; reason: string } {
 	const norm = normalizePath(filePath);
 	const base = basename(norm);
@@ -414,7 +420,10 @@ export function checkReadable(filePath: string): { ok: true } | { ok: false; rea
 	return { ok: true };
 }
 
-/** Check if a file path is safe to write. Inherits read restrictions + system dir blocks. */
+/**
+ * Canonical Reference: .pi/architecture/modules/core-libraries.md
+ * Last Sync: 2026-05-31
+ Check if a file path is safe to write. Inherits read restrictions + system dir blocks. */
 export function checkWritable(filePath: string): { ok: true } | { ok: false; reason: string } {
 	const r = checkReadable(filePath);
 	if (!r.ok) return r;
@@ -428,7 +437,10 @@ export function checkWritable(filePath: string): { ok: true } | { ok: false; rea
 	return { ok: true };
 }
 
-/** Lightweight heuristic for blocking obviously destructive shell commands. */
+/**
+ * Canonical Reference: .pi/architecture/modules/core-libraries.md
+ * Last Sync: 2026-05-31
+ Lightweight heuristic for blocking obviously destructive shell commands. */
 export function checkShellCommand(cmd: string): { ok: true } | { ok: false; reason: string } {
 	const c = cmd.trim();
 	if (
@@ -496,6 +508,9 @@ const HEADLESS_BLOCKED: Array<{ pattern: RegExp; reason: string }> = [
 ];
 
 export default function (pi: ExtensionAPI) {
+	// GUARDIAN_YOLO=1 bypasses all bash guards (for long automatic runs)
+	if (process.env.GUARDIAN_YOLO === "1") return;
+
 	if (isSubagent) {
 		pi.on("tool_call", async (event) => {
 			if (!isToolCallEventType("bash", event)) return;

package/templates/pi/extensions/config-reload.ts

@@ -1,4 +1,7 @@
 /**
+ * Canonical Reference: .pi/architecture/modules/core-libraries.md
+ * Last Sync: 2026-05-31
+
  * Dynamic Config Reload Extension for pi
  *
  * Watches `.pi/agent/AGENTS.md` for file changes and re-applies

package/templates/pi/extensions/coordinator.ts

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

package/templates/pi/extensions/curator.ts

@@ -1,4 +1,7 @@
 /**
+ * Canonical Reference: .pi/architecture/modules/core-libraries.md
+ * Last Sync: 2026-05-31
+
  * Skill Curator Extension for pi
  *
  * Background maintenance for agent-created skills.

package/templates/pi/extensions/filechanges.ts

@@ -1,6 +1,9 @@
 // biome-ignore lint/suspicious/noExplicitAny: pi ExtensionContext has no published types
 // biome-ignore lint/style/noNonNullAssertion: pi UI callbacks use non-null assertions
 /**
+ * Canonical Reference: .pi/architecture/modules/core-libraries.md
+ * Last Sync: 2026-05-31
+
  * File-Changes Extension for pi
  *
  * Tracks all files modified by pi during a session.

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

@@ -1,4 +1,7 @@
 /**
+ * Canonical Reference: .pi/architecture/modules/core-libraries.md
+ * Last Sync: 2026-05-31
+
  * Goal Loop Extension for pi
  *
  * Persistent standing goals with validator-backed judge.
@@ -151,7 +154,10 @@ const BUILTIN_VALIDATORS: Record<string, string> = {
 	integration: ".pi/scripts/validate-integration.sh",
 };
 
-/** Discover custom validators from `.pi/scripts/validate-*.sh` */
+/**
+ * Canonical Reference: .pi/architecture/modules/core-libraries.md
+ * Last Sync: 2026-05-31
+ Discover custom validators from `.pi/scripts/validate-*.sh` */
 function discoverCustomValidators(cwd: string): Record<string, string> {
 	const scriptsDir = join(cwd, ".pi/scripts");
 	if (!existsSync(scriptsDir)) return {};
@@ -230,15 +236,16 @@ async function runLLMJudge(
 
 	const prompt = `Goal:\n${truncatedGoal}\n${subgoalsBlock}\n\nAgent's most recent response:\n${truncatedResponse}\n\nIs the goal satisfied?`;
 
-	// Check if git diff is accessible (for heuristic judgment)
+	// Use guardian_coordinate to run an LLM-based judgment
 	try {
-		await ctx.shell.execute("git rev-parse --git-dir 2>/dev/null", {});
+		const result = await ctx.tools.execute("guardian_scope", {});
+		// We can't directly call LLM from extension — instead return a heuristic judgment
+		// The LLM judge runs via the agent itself being prompted to self-assess
+		// For now, return continue to let the agent decide
+		return { done: false, reason: "LLM judge requires agent self-assessment turn" };
 	} catch {
-		// Not a git repo — continue anyway
+		return { done: false, reason: "judge unavailable, continuing" };
 	}
-	// The LLM judge runs via the agent itself being prompted to self-assess
-	// For now, return continue to let the agent decide
-	return { done: false, reason: "LLM judge requires agent self-assessment turn" };
 }
 
 function truncate(text: string, limit: number): string {

package/templates/pi/extensions/hooks.ts

@@ -1,4 +1,7 @@
 /**
+ * Canonical Reference: .pi/architecture/modules/core-libraries.md
+ * Last Sync: 2026-05-31
+
  * Shell Hooks Extension for pi
  *
  * Declarative shell-script hooks that fire on lifecycle events.

package/templates/pi/extensions/kanban.ts

@@ -1,4 +1,7 @@
 /**
+ * Canonical Reference: .pi/architecture/modules/core-libraries.md
+ * Last Sync: 2026-05-31
+
  * Kanban Extension for pi
  *
  * Durable JSON-backed task board for multi-agent collaboration.

package/templates/pi/extensions/plan-mode.ts

@@ -1,4 +1,7 @@
 /**
+ * Canonical Reference: .pi/architecture/modules/core-libraries.md
+ * Last Sync: 2026-05-31
+
  * Plan Mode Extension for pi
  *
  * Intercepts mutating tool calls (edit, write_file, create_directory) and queues

package/templates/pi/extensions/project-scaffolder.ts

@@ -20,8 +20,7 @@
  */
 
 import { type ExecSyncOptions, execSync } from "node:child_process";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
-import * as path from "node:path";
+import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 
 // ── Types ──
@@ -151,19 +150,7 @@ export default function (pi: ExtensionAPI) {
 
 				const lang = String(parsed.lang || parsed.language || "").toLowerCase();
 				const buildTool = String(parsed.buildTool || "").toLowerCase() || undefined;
-
-				// Read groupId from manifest if not passed via CLI (matches guardian CLI behavior)
-				let groupId = String(parsed.groupId || parsed.group || "");
-				if (!groupId) {
-					try {
-						const manifestPath = path.join(ctx.cwd, "guardian-manifest.json");
-						if (fs.existsSync(manifestPath)) {
-							const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
-							groupId = manifest.groupId || "";
-						}
-					} catch { /* ignore malformed manifest */ }
-				}
-				if (!groupId) groupId = "com.example";
+				const groupId = String(parsed.groupId || parsed.group || "com.example");
 				const validators = String(parsed.validators || "ci,tests");
 				const dryRun = parsed.dryRun === true || parsed["dry-run"] === true || parsed.d === true;
 				const force = parsed.force === true || parsed.f === true;

package/templates/pi/extensions/read-only-mode.ts

@@ -1,4 +1,7 @@
 /**
+ * Canonical Reference: .pi/architecture/modules/core-libraries.md
+ * Last Sync: 2026-05-31
+
  * Read-Only Mode Extension for pi
  *
  * Hard-enforces a tiny tool allowlist: read, grep, find, ls.

package/templates/pi/extensions/redaction.ts

@@ -1,4 +1,7 @@
 /**
+ * Canonical Reference: .pi/architecture/modules/core-libraries.md
+ * Last Sync: 2026-05-31
+
  * Redaction Extension for pi
  *
  * Automatically redacts sensitive data from tool results, terminal output,
@@ -40,6 +43,9 @@ const PATTERNS: Array<{ kind: string; re: RegExp }> = [
 ];
 
 /**
+ * Canonical Reference: .pi/architecture/modules/core-libraries.md
+ * Last Sync: 2026-05-31
+
  * Redact sensitive data from text. Returns the redacted string.
  */
 export function redactSensitive(text: string): string {
@@ -58,6 +64,9 @@ export function redactSensitive(text: string): string {
 }
 
 /**
+ * Canonical Reference: .pi/architecture/modules/core-libraries.md
+ * Last Sync: 2026-05-31
+
  * Count redactions made (for logging/telemetry-free reporting).
  */
 export function countRedactions(text: string): number {

package/templates/pi/extensions/session-persistence.ts

@@ -1,4 +1,7 @@
 /**
+ * Canonical Reference: .pi/architecture/modules/core-libraries.md
+ * Last Sync: 2026-05-31
+
  * Session Persistence Extension for pi
  *
  * Provides structured session lifecycle with:

package/templates/pi/extensions/slash-commands.ts

@@ -1,4 +1,7 @@
 /**
+ * Canonical Reference: .pi/architecture/modules/core-libraries.md
+ * Last Sync: 2026-05-31
+
  * Slash Commands Extension for pi
  *
  * Intercepts user input starting with `/` and transforms slash commands into

package/templates/pi/extensions/snippets.ts

@@ -1,4 +1,7 @@
 /**
+ * Canonical Reference: .pi/architecture/modules/core-libraries.md
+ * Last Sync: 2026-05-31
+
  * Snippets Extension for pi
  *
  * Manages reusable prompt fragments (snippets) that can be referenced via
@@ -57,7 +60,10 @@ function normalizeHandle(raw: string): string {
 		.replace(/^-+|-+$/g, "");
 }
 
-/** Expand #handle tokens in text, returning the body with tokens stripped and snippet XML blocks. */
+/**
+ * Canonical Reference: .pi/architecture/modules/core-libraries.md
+ * Last Sync: 2026-05-31
+ Expand #handle tokens in text, returning the body with tokens stripped and snippet XML blocks. */
 function expandSnippetTokens(
 	text: string,
 	snippets: readonly Snippet[],

package/templates/pi/extensions/validation-runner.ts

@@ -1,10 +1,17 @@
 /**
+ * Canonical Reference: .pi/architecture/modules/core-libraries.md
+ * Last Sync: 2026-06-02
+
  * Validation Runner Extension for pi
  *
  * Runs validation scripts as pi tools and commands.
+ * Supports language-specific validators from scripts/languages/{lang}/.
  * See coordinator.ts for guardian_scope and guardian_validate tools.
  */
 
+import * as fs from "node:fs";
+import * as path from "node:path";
+
 type ShellResult = {
 	exitCode: number;
 	stdout: string;
@@ -12,6 +19,7 @@ type ShellResult = {
 };
 
 type ExtensionContext = {
+	cwd: string;
 	ui: { notify(message: string, level?: string): void };
 	shell: { execute(command: string, options?: { signal?: AbortSignal }): Promise<ShellResult> };
 	tools: { execute(name: string, params: Record<string, unknown>): Promise<unknown> };
@@ -41,7 +49,7 @@ type ExtensionAPI = {
 	): void;
 };
 
-const VALIDATORS = {
+const BASE_VALIDATORS: Record<string, string> = {
 	architecture: ".pi/scripts/validate-architecture.sh",
 	canonical: ".pi/scripts/validate-canonical.sh",
 	ci: ".pi/scripts/validate-ci.sh",
@@ -49,34 +57,82 @@ const VALIDATORS = {
 	operations: ".pi/scripts/validate-operations.sh",
 	security: ".pi/scripts/validate-security.sh",
 	tests: ".pi/scripts/validate-tests.sh",
-} as const;
+};
 
-type ValidatorName = keyof typeof VALIDATORS;
+type ValidatorName = string;
 
-function isValidatorName(value: string): value is ValidatorName {
-	return Object.hasOwn(VALIDATORS, value);
+/**
+ * Get the project language from the manifest, if available.
+ */
+function getProjectLanguage(cwd: string): string | null {
+	try {
+		const manifestPath = path.join(cwd, "guardian-manifest.json");
+		if (fs.existsSync(manifestPath)) {
+			const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+			return manifest.language || null;
+		}
+	} catch {
+		// Ignore parse errors
+	}
+	return null;
+}
+
+/**
+ * Discover language-specific validators from scripts/languages/{lang}/ directory.
+ */
+function getLanguageValidators(cwd: string, language: string | null): Record<string, string> {
+	if (!language) return {};
+
+	const langDir = path.join(cwd, `.pi/scripts/languages/${language}`);
+	if (!fs.existsSync(langDir)) return {};
+
+	const validators: Record<string, string> = {};
+	try {
+		const files = fs.readdirSync(langDir);
+		for (const file of files) {
+			if (file.endsWith(".sh")) {
+				const name = file.replace("validate-", "").replace(".sh", "");
+				validators[`${language}:${name}`] = `.pi/scripts/languages/${language}/${file}`;
+			}
+		}
+	} catch {
+		// Ignore read errors
+	}
+	return validators;
 }
 
 export default function (pi: ExtensionAPI) {
-	// Session initialization
+	let language: string | null = null;
+
+	// Session initialization — detect project language
 	pi.on("session_start", async (_event, ctx) => {
-		ctx.ui.notify("Guardian validation runner initialized", "info");
+		language = getProjectLanguage(ctx.cwd);
+		if (language) {
+			ctx.ui.notify(`Guardian validation runner initialized (language: ${language})`, "info");
+		} else {
+			ctx.ui.notify("Guardian validation runner initialized", "info");
+		}
 	});
 
 	// Register validate command — runs scripts directly via shell
 	pi.registerCommand("validate", {
 		description: "Run all or specific validators",
 		handler: async (args, ctx) => {
+			// Build full validator map (base + language-specific)
+			const langValidators = getLanguageValidators(ctx.cwd, language);
+			const allValidators = { ...BASE_VALIDATORS, ...langValidators };
+
 			const validators =
 				args.length > 0
-					? args.filter(isValidatorName)
-					: ["ci", "tests", "operations", "security", "canonical"];
+					? args.filter((v) => Object.hasOwn(allValidators, v))
+					: Object.keys(allValidators);
+
 			ctx.ui.notify(`Running validators: ${validators.join(", ")}`, "info");
 
 			const results: Record<string, { passed: boolean; output: string }> = {};
 
 			for (const validator of validators) {
-				const scriptPath = VALIDATORS[validator];
+				const scriptPath = allValidators[validator];
 				try {
 					const result = await ctx.shell.execute(`bash ${scriptPath}`);
 					results[validator] = {

package/templates/pi/preflight_report.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-07-08T09:33:06Z",
+  "timestamp": "2026-07-08T11:39:04Z",
   "mode": "all",
   "stages_run": [],
   "summary": {
@@ -8,7 +8,7 @@
     "failed": 1,
     "skipped": 12
   },
-  "duration_seconds": 1,
+  "duration_seconds": 0,
   "results": [
   {
     "name": "check_mr_traceability.sh",
@@ -56,7 +56,7 @@
     "name": "cargo test --lib",
     "status": "fail",
     "message": "unit test failures",
-    "duration": 1
+    "duration": 0
   },
   {
     "name": "integration",

package/templates/pi/validators/default.toml

@@ -178,6 +178,17 @@ keep_lines_matching = ["FAILED", "error", "timeout", "connection refused", "asse
 max_lines = 80
 on_empty = "✅ All integration tests passed"
 
+# ── Ubiquitous Language Validator ────────────────────────────────────────────
+
+[filters.ubiquitous-language]
+command = "validate-ubiquitous-language"
+description = "Detect code drift from .pi/domain/ubiquitous-language.md glossary"
+# Run: bash .pi/scripts/validate-ubiquitous-language.sh [src_dir]
+strip_ansi = false
+keep_lines_matching = ["❌ FAIL", "⚠️  WARN", "Drift:", "alias", "canonical", "Variation"]
+max_lines = 80
+on_empty = "✅ No drift detected"
+
 # ── Git Status Validator ────────────────────────────────────────────────────
 
 [filters.git-status]
@@ -199,11 +210,3 @@ strip_ansi = true
 head_lines = 1
 truncate_lines_at = 120
 max_lines = 30
-
-# ── Ubiquitous Language Validator ────────────────────────────────────────────
-
-[filters.ubiquitous-language]
-command = "validate-ubiquitous-language"
-description = "Detect code drift from .pi/domain/ubiquitous-language.md glossary"
-strip_ansi = false
-keep_lines_matching = ["FAIL", "WARN", "Drift:", "alias", "canonical"]