guardian-framework 0.1.52 → 0.1.54

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "guardian-framework",
-	"version": "0.1.52",
+	"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.