guardian-framework 0.1.104 → 0.1.109

package/templates/pi/extensions/architect.ts

@@ -34,6 +34,10 @@ import {
 	generateContractFreezeMarkdown,
 	generateIssueMarkdown,
 	generateProofingMarkdown,
+	generateRuntimeIntegrationMarkdown,
+	moduleHasRuntimeIntegration,
+	detectLanguage,
+	testBaseDirFromLang,
 } from "./architect-lib/generators";
 import {
 	generateEpicTestFiles,
@@ -108,7 +112,7 @@ function formatEpicStatus(state: EpicState | null): string {
 class EpicManager {
 	private state: EpicState | null;
 
-	constructor(private cwd: string) {
+	constructor(private readonly cwd: string) {
 		this.state = loadEpicState(cwd);
 	}
 
@@ -116,7 +120,8 @@ class EpicManager {
 		return this.state;
 	}
 
-	async startEpic(
+	// NOSONAR: architect orchestrator (deliberate multi-branch dispatcher)
+	async startEpic( // NOSONAR: architect orchestrator — deliberate multi-branch dispatcher
 		ctx: ExtensionContext,
 		name: string,
 		trackingIssueId?: string,
@@ -137,9 +142,33 @@ class EpicManager {
 				slice = { module: matchedModule.replace(".md", ""), components, nextLogicalSlice: planned };
 			}
 		}
-		// Fallback: first module with planned components
+		// Fallback: auto-select ONLY when unambiguous. If the epic name did not
+		// match a module doc and several modules still have planned components,
+		// error with candidates instead of silently planning the wrong module
+		// (previously this silently picked the first match — e.g. stale docs).
 		if (!slice) {
-			slice = findNextLogicalSlice(this.cwd, moduleFiles);
+			const candidates: { file: string; planned: number }[] = [];
+			for (const f of moduleFiles) {
+				const comps = parseModuleFile(join(this.cwd, ARCH_MODULES_DIR, f));
+				const planned = comps.filter((c: ModuleComponent) => c.status === "planned");
+				if (planned.length > 0) candidates.push({ file: f, planned: planned.length });
+			}
+			if (candidates.length === 1) {
+				const c = candidates[0];
+				const comps = parseModuleFile(join(this.cwd, ARCH_MODULES_DIR, c.file));
+				slice = {
+					module: c.file.replace(".md", ""),
+					components: comps,
+					nextLogicalSlice: comps.filter((x: ModuleComponent) => x.status === "planned"),
+				};
+			} else if (candidates.length > 1) {
+				const list = candidates
+					.map((c) => `  - ${c.file.replace(".md", "")} (${c.planned} planned)`)
+					.join("\n");
+				throw new Error(
+					`Epic name "${name}" did not match any architecture module, and ${candidates.length} modules have planned components:\n${list}\nRename the epic to match a module (e.g. /architect --epic "Module Name") or mark stale module components as implemented.`,
+				);
+			}
 		}
 		if (!slice) {
 			throw new Error("All architecture components are implemented. No next slice found.");
@@ -279,6 +308,30 @@ class EpicManager {
 			issues.push(entry);
 		}
 
+		// 2.5 Runtime Integration & Legacy Migration (ADR-009) — mandatory when
+		// the module doc documents runtime integration. Placed after the
+		// implementation issues and before proofing so "implemented but never
+		// wired" cannot be deferred by a scope note.
+		if (moduleHasRuntimeIntegration(this.cwd, slice.module)) {
+			const integrationId = "issue-runtime-integration";
+			const integrationEntry = {
+				id: integrationId,
+				title: "Runtime Integration & Legacy Migration",
+				status: "planned" as string,
+				remoteIssueId: null as string | null,
+			};
+			const integrationMd = generateRuntimeIntegrationMarkdown(slice, name, this.cwd);
+			writeFileSync(join(issuesDir, `${integrationId}.md`), integrationMd);
+			if (hasRemote && remoteRepo) {
+				const result = createRemoteIssue(this.cwd, integrationEntry.title, join(issuesDir, `${integrationId}.md`), "epic,runtime-integration", remoteRepo);
+				if (result.success && result.issueNumber) {
+					integrationEntry.remoteIssueId = result.issueNumber;
+					if (effectiveTrackingId) linkRemoteIssue(this.cwd, result.issueNumber, effectiveTrackingId);
+				}
+			}
+			issues.push(integrationEntry);
+		}
+
 		// 3. Proofing
 		const proofingId = "issue-proofing";
 		const proofingEntry = {
@@ -342,7 +395,10 @@ class EpicManager {
 				`**Components:** ${slice.nextLogicalSlice.length}`,
 				"",
 				"## Issues",
-				...issues.map((i) => `- ${i.title}${i.remoteIssueId ? ` (#${i.remoteIssueId})` : ""}`),
+				...issues.map((i) => {
+								const ref = i.remoteIssueId ? ` (#${i.remoteIssueId})` : "";
+								return `- ${i.title}${ref}`;
+							}),
 				"",
 				"---",
 				"Auto-generated by Guardian Architect",
@@ -382,21 +438,31 @@ class EpicManager {
 
 // ── Extension ──
 
-export default function (pi: ExtensionAPI) {
-	let manager: EpicManager | null = null;
 
-	function findFlag(tokens: string[], prefix: string): string | undefined {
-		const eqMatch = tokens.find((a) => a.startsWith(`${prefix}=`));
-		if (eqMatch) return eqMatch.split("=").slice(1).join("=");
-		const idx = tokens.indexOf(prefix);
-		if (idx >= 0 && idx + 1 < tokens.length && !tokens[idx + 1].startsWith("--")) return tokens[idx + 1];
-		return undefined;
+function randomPL(): string {
+	const buf = new Uint8Array(2);
+	(globalThis as { crypto?: { getRandomValues?: (a: Uint8Array) => void } }).crypto?.getRandomValues?.(buf);
+	const n = ((buf[0] << 8) | buf[1]) % 10000;
+	return `PL-${String(n).padStart(4, "0")}`;
+}
+
+function findFlag(tokens: string[], prefix: string): string | undefined {
+	const eqMatch = tokens.find((a) => a.startsWith(`${prefix}=`));
+	if (eqMatch) return eqMatch.split("=").slice(1).join("=");
+	const idx = tokens.indexOf(prefix);
+	if (idx >= 0 && idx + 1 < tokens.length && !tokens[idx + 1].startsWith("--")) return tokens[idx + 1];
+	return undefined;
 	}
 
+export default function architectExtension(pi: ExtensionAPI) {
+	let manager: EpicManager | null = null;
+
+
 	pi.registerCommand("architect", {
 		description: "Orchestrate the full architecture-to-implementation process",
-		handler: async (args, ctx) => {
-			if (!manager) manager = new EpicManager(ctx.cwd);
+		// NOSONAR: architect command dispatcher (deliberate multi-branch router)
+		handler: async function architectHandler(args: unknown, ctx: ExtensionContext) { // NOSONAR: architect command router — deliberate multi-branch dispatcher
+			manager ??= new EpicManager(ctx.cwd);
 			const raw = typeof args === "string" ? args : "";
 			const tokens = raw ? parseArgs(raw) : [];
 			if (tokens.length === 0) {
@@ -451,7 +517,7 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			if (tokens[0] === "--phase" || action === "phase") {
-				const phaseName = (tokens.slice(1).join(" ") || findFlag(tokens, "--phase")).replace(/["']/g, "").trim();
+				const phaseName = (tokens.slice(1).join(" ") || findFlag(tokens, "--phase") || "").replace(/["']/g, "").trim();
 				if (!phaseName) {
 					ctx.ui.notify('Usage: /architect --phase "Phase 1"', "error");
 					return;
@@ -465,9 +531,9 @@ export default function (pi: ExtensionAPI) {
 
 				// Find phase by name or index
 				let targetPhase: RoadmapPhase | undefined;
-				const idxMatch = phaseName.match(/Phase\s+(\d+)/i);
+				const idxMatch = /Phase\s+(\d+)/i.exec(phaseName);
 				if (idxMatch) {
-					targetPhase = phases.find((p) => p.index === parseInt(idxMatch[1], 10));
+					targetPhase = phases.find((p) => p.index === Number.parseInt(idxMatch[1], 10));
 				} else {
 					targetPhase = phases.find((p) => p.title.toLowerCase().includes(phaseName.toLowerCase()));
 				}
@@ -482,7 +548,7 @@ export default function (pi: ExtensionAPI) {
 					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));
+					const depPhase = phases.find((p) => p.index === Number.parseInt(depMatch[1], 10));
 					return depPhase && depPhase.status !== "done";
 				});
 				if (unmetDeps.length > 0) {
@@ -537,7 +603,7 @@ export default function (pi: ExtensionAPI) {
 						}
 						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 pipelineId = randomPL();
 							const pipelineState = {
 								id: pipelineId,
 								name: mod.name,
@@ -579,10 +645,11 @@ export default function (pi: ExtensionAPI) {
 						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);
+						const roadmapPhase = rs.phases.find((p) => p.index === targetPhase.index);
+						if (roadmapPhase) {
+							const comp = new Set(roadmapPhase.completedModules || []);
+							comp.add(mod.name);
+							roadmapPhase.completedModules = Array.from(comp);
 						}
 						rs.updatedAt = new Date().toISOString();
 						saveRoadmapState(ctx.cwd, rs);
@@ -590,13 +657,13 @@ export default function (pi: ExtensionAPI) {
 					}
 					try {
 						const state = await manager.startEpic(ctx, mod.name);
-						if (!state || !state.slices || state.slices.length === 0) {
+						if (!state?.slices?.length) {
 							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 pipelineId = randomPL();
 						const pipelineState = {
 							id: pipelineId,
 							name: mod.name,
@@ -670,8 +737,8 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			if (tokens[0] === "--phase-module-done" || action === "phase-module-done") {
-				const phaseIdx = parseInt(tokens[1] || "", 10);
-				if (isNaN(phaseIdx) || !tokens[2]) {
+				const phaseIdx = Number.parseInt(tokens[1] || "", 10);
+				if (Number.isNaN(phaseIdx) || !tokens[2]) {
 					ctx.ui.notify('Usage: /architect --phase-module-done <phase-number> "<module-name>"', "error");
 					return;
 				}
@@ -713,8 +780,8 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			if (tokens[0] === "--phase-done" || action === "phase-done") {
-				const phaseIdx = parseInt(tokens[1] || "", 10);
-				if (isNaN(phaseIdx)) {
+				const phaseIdx = Number.parseInt(tokens[1] || "", 10);
+				if (Number.isNaN(phaseIdx)) {
 					ctx.ui.notify('Usage: /architect --phase-done <phase-number>', "error");
 					return;
 				}
@@ -778,7 +845,7 @@ export default function (pi: ExtensionAPI) {
 
 				const state = await manager.startEpic(ctx, epicName, trackingIssueId, tddEnabled);
 
-				if (!state || !state.slices || state.slices.length === 0) {
+				if (!state?.slices?.length) {
 					ctx.ui.notify("Failed to discover architecture components. Check .pi/architecture/modules/.", "error");
 					return;
 				}
@@ -806,7 +873,7 @@ export default function (pi: ExtensionAPI) {
 				} catch { /* ignore */ }
 
 				// Write pipeline state directly (ctx.tools not available in command handlers)
-				const pipelineId = `PL-${String(Math.floor(Math.random() * 10000)).padStart(4, "0")}`;
+				const pipelineId = randomPL();
 				const pipelineState = {
 					id: pipelineId,
 					name: epicName,
@@ -837,7 +904,7 @@ export default function (pi: ExtensionAPI) {
 					: "";
 
 				const firstItem = items[0];
-				const issueFilename = `${firstItem}.md`.replace(/\//g, "-");
+				const issueFilename = `${firstItem}.md`.replaceAll("/", "-");
 				const issuePath = join(ctx.cwd, ".pi/issues", issueFilename);
 
 				let issueContent = "";
@@ -870,7 +937,7 @@ export default function (pi: ExtensionAPI) {
 						"",
 						"**TDD Mode: ON**",
 						"- Failing test files were generated from architecture contracts before issues were created.",
-						"- Start each component by examining its test file in the `tests/unit/` directory.",
+						"- Start each component by examining its test file in the `" + testBaseDirFromLang(detectLanguage(ctx.cwd)) + "/` directory.",
 						"- Run tests first to see them fail, then implement to make them pass (Red→Green→Refactor).",
 						"- Tests are living artifacts — evolve them as the component grows.",
 						"- Reference `.pi/skills/tdd-practice.md` for TDD guidance.",
@@ -900,7 +967,7 @@ export default function (pi: ExtensionAPI) {
 		description: "Show the current epic status and progress.",
 		parameters: { type: "object", properties: {} },
 		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
-			if (!manager) manager = new EpicManager(ctx.cwd);
+			manager ??= new EpicManager(ctx.cwd);
 			const state = manager.getState();
 			return { content: [{ type: "text", text: formatEpicStatus(state) }] };
 		},
@@ -920,18 +987,15 @@ export default function (pi: ExtensionAPI) {
 			for (const file of moduleFiles) {
 				const components = parseModuleFile(join(ctx.cwd, ".pi/architecture/modules", file));
 				const planned = components.filter((c) => c.status === "planned");
-				lines.push(`### ${file.replace(".md", "")}`);
-				lines.push(`  Components: ${components.length} (${planned.length} planned)`);
+				lines.push(`### ${file.replace(".md", "")}`, `  Components: ${components.length} (${planned.length} planned)`);
 				if (planned.length > 0) {
-					lines.push("  Next slice:");
-					for (const c of planned) lines.push(`    - ${c.name}`);
+					lines.push("  Next slice:", ...planned.map((c: ModuleComponent) => `    - ${c.name}`));
 				}
 				lines.push("");
 			}
 			const slice = findNextLogicalSlice(ctx.cwd, moduleFiles);
 			if (slice) {
-				lines.push(`**Recommended next epic:** ${slice.module}`);
-				lines.push(`Components: ${slice.nextLogicalSlice.map((c: ModuleComponent) => c.name).join(", ")}`);
+				lines.push(`**Recommended next epic:** ${slice.module}`, `Components: ${slice.nextLogicalSlice.map((c: ModuleComponent) => c.name).join(", ")}`);
 			}
 			return { content: [{ type: "text", text: lines.join("\n") }] };
 		},

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

@@ -182,7 +182,7 @@ async function askSingleChoice(
 		{ id: "other", label: otherLabel, value: "__other__", isOther: true },
 	];
 
-	return ctx.ui.custom<AskAnswer | null>(
+	return (ctx.ui as any).custom(
 		(tui: any, theme: any, _kb: any, done: (r: AskAnswer | null) => void) => {
 			let optionIndex = 0;
 			let editMode = false;
@@ -306,7 +306,7 @@ async function askMultiChoice(
 		{ id: "submit", label: "Submit", value: "__submit__", isSubmit: true },
 	];
 
-	return ctx.ui.custom<AskAnswer[] | null>(
+	return (ctx.ui as any).custom(
 		(tui: any, theme: any, _kb: any, done: (r: AskAnswer[] | null) => void) => {
 			let optionIndex = 0;
 			let editMode = false;

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

@@ -65,7 +65,7 @@ function tokenizeCommand(cmd: string): { parts: string[]; ops: string[] } {
 		}
 
 		// Operators: |, ||, &&, ;, >, >>, <
-		if (ch === "|" || ch === ";" || ch === "<" || ch === ">") {
+		if (ch === "|" || ch === ";" || ch === "<" || ch === ">" || ch === "&") {
 			if (current.trim()) parts.push(current.trim());
 			current = "";
 
@@ -304,7 +304,7 @@ async function promptRunOrAbort(ctx: any, command: string, risk: Risk): Promise<
 		{ value: "abort", label: "Abort", description: "Block this command" },
 	];
 
-	const choice = await ctx.ui.custom<"run" | "abort">(
+	const choice = await (ctx.ui as any).custom(
 		(tui, theme, _kb, done) => {
 			const container = new Container();
 			container.addChild(

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

@@ -14,12 +14,12 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 
 type ExtensionAPI = {
-	on(event: string, handler: (event: unknown, ctx: unknown) => void | Promise<void>): void;
+	on(event: string, handler: (event: unknown, ctx: ReloadCtx) => void | Promise<void>): void;
 	registerCommand(
 		name: string,
 		options: {
 			description: string;
-			handler(args: string[], ctx: unknown): unknown | Promise<unknown>;
+			handler(args: string[], ctx: ReloadCtx): unknown | Promise<unknown>;
 		},
 	): void;
 };
@@ -35,11 +35,18 @@ function parseFrontMatter(text: string): string {
 	return text.slice(4, end);
 }
 
+type ReloadUi = {
+	notify(message: string, level?: string): void;
+	setStatus(key: string, message: string | null): void;
+	theme?: { fg(role: string, text: string): string };
+};
+type ReloadCtx = { ui?: ReloadUi };
+
 let lastKnownConfig = "";
 let watcher: fs.FSWatcher | undefined;
 let reloadCount = 0;
 
-function startWatching(ctx: unknown): void {
+function startWatching(ctx: ReloadCtx): void {
 	if (!fs.existsSync(CONFIG_FILE)) return;
 
 	lastKnownConfig = fs.readFileSync(CONFIG_FILE, "utf-8");
@@ -82,7 +89,7 @@ function stopWatching(): void {
 }
 
 export default function (pi: ExtensionAPI) {
-	pi.on("session_start", async (_event: unknown, ctx: unknown) => {
+	pi.on("session_start", async (_event: unknown, ctx: ReloadCtx) => {
 		stopWatching();
 		startWatching(ctx);
 	});
@@ -93,7 +100,7 @@ export default function (pi: ExtensionAPI) {
 
 	pi.registerCommand("reload-config", {
 		description: "Manually reload workflow config from AGENTS.md",
-		handler: async (_args: string[], ctx: unknown) => {
+		handler: async (_args: string[], ctx: ReloadCtx) => {
 			if (!fs.existsSync(CONFIG_FILE)) {
 				ctx?.ui?.notify("No .pi/agent/AGENTS.md found.", "warning");
 				return;

package/templates/pi/extensions/coordinator.ts

@@ -24,7 +24,7 @@ type ExtensionContext = {
 type ToolCallEvent = { toolName: string; toolCallId: string; input: { command: string } };
 
 type ExtensionAPI = {
-	on(event: string, handler: (event: unknown, ctx: ExtensionContext) => void | Promise<void>): void;
+	on(event: string, handler: (event: unknown, ctx: ExtensionContext) => unknown | Promise<unknown>): void;
 	registerTool(options: {
 		name: string;
 		label: string;
@@ -34,7 +34,7 @@ type ExtensionAPI = {
 			toolCallId: string,
 			params: Record<string, unknown>,
 			signal: AbortSignal,
-			onUpdate: (update: { type: string; message: string }) => void,
+			onUpdate: (update: { type?: string; message?: string; content?: unknown }) => void,
 			ctx: ExtensionContext,
 		): unknown | Promise<unknown>;
 	}): void;

package/templates/pi/extensions/curator.ts

@@ -252,7 +252,7 @@ class Curator {
 				: new Date(skill.createdAt).getTime();
 			const age = now - lastActivity;
 
-			if (age > archiveThreshold && skill.state !== "archived") {
+			if (age > archiveThreshold) {
 				if (!dryRun) {
 					this.archiveSkill(name);
 				}

package/templates/pi/extensions/domain-explorer.ts

@@ -464,6 +464,26 @@ export default function (pi: ExtensionAPI) {
 				addCheck("Glossary file", false, "Not found");
 			}
 
+			// 4b. ADR-008 modeling-depth rules (deterministic, over raw session JSON)
+			const depthRawPath = sessionPath.replace(/\.md$/, "") + ".raw.json";
+			const depthScript = path.join(ctx.cwd, ".pi", "scripts", "validate-exploration-depth.sh");
+			if (fs.existsSync(depthRawPath) && fs.existsSync(depthScript)) {
+				try {
+					const depthResult = await shellExec(ctx, "bash " + depthScript + " " + depthRawPath);
+					const lines = depthResult.stdout.trim().split("\n").filter((l) => l.trim() !== "");
+					const violations = lines.filter((l) => l.includes("[") && l.includes("] error:"));
+					addCheck(
+						"Modeling depth rules (ADR-008)",
+						depthResult.exitCode === 0,
+						violations.length > 0 ? violations.join(" | ") : lines.slice(-1)[0] || "",
+					);
+				} catch (err) {
+					addCheck("Modeling depth rules (ADR-008)", false, "Error: " + String(err));
+				}
+			} else {
+				addCheck("Modeling depth rules (ADR-008) - skipped", true, "no session raw.json");
+			}
+
 			// 4. Source code drift
 			const scriptPath = path.join(ctx.cwd, ".pi", "scripts", "validate-ubiquitous-language.sh");
 			if (fs.existsSync(scriptPath)) {
@@ -988,8 +1008,35 @@ export default function (pi: ExtensionAPI) {
 					"- Current ADR-001: `.pi/architecture/decisions/ADR-001-architecture-pattern.md`",
 					"- System diagram: `.pi/architecture/diagrams/system-context.md`",
 					"- Module stubs: `.pi/architecture/modules/` (" + moduleFiles.length + " files)",
+					"- ADR-008 modeling depth: `.pi/architecture/decisions/ADR-008-proportional-modeling-depth.md`",
+					"- Structured session JSON (depth fields): `.pi/domain/exploration/" + sessionId + ".raw.json`",
 					"",
-					"### STEP 1: Generate All ADRs",
+					"### STEP 0: ADR-008 Modeling Depth (read first, applies everywhere)",
+				"",
+				"Read the `**Modeling Depth:**` header of EVERY module doc plus the structured",
+				"session JSON (`.raw.json`). Enrich PROPORTIONALLY — never rewrite the depth header,",
+				"never delete an existing `Modeling Depth Note (ADR-008)` section, and never invent",
+				"modeling the exploration did not capture:",
+				"",
+				"- **tactical** (core subdomain): full DDD enrichment — aggregates as consistency",
+				"  boundaries with the exploration invariants (`rule` + illegalStatePrevented),",
+				"  behavior methods not setters, repository interface owned by the domain layer,",
+				"  value objects with entity-vs-VO justification, triaged domain events with payloads,",
+				"  and explicit domain / application / infrastructure service classification.",
+				"- **service** (supporting subdomain): enrich to a Service + Persistence Contract.",
+				"  Do NOT expand aggregates, value objects, domain events, or API surfaces beyond",
+				"  what the exploration captured.",
+				"- **adapter** (generic subdomain): enrich to an Interface + Anti-Corruption Layer —",
+				"  the narrow interface the domain consumes, the vendor/OSS choice, the ACL",
+				"  translation and its context-map edge. NO domain entities or aggregates.",
+				"",
+				"Language judgment: for Java/Spring modules apply the decision tables in the",
+				"`java-spring-enterprise-codegen` skill section 10 (entity-vs-VO, service classifier,",
+				"event triage, transaction placement — `@Transactional` only in application services).",
+				"Diagrams and section breadth follow each module's depth (full module-level diagram",
+				"set only for tactical; service = data-flow + sequence; adapter = ACL/integration).",
+				"",
+				"### STEP 1: Generate All ADRs",
 					"",
 					"**Do this first, before touching any module docs.** Module enrichment needs ADR references.",
 					"",
@@ -1035,8 +1082,8 @@ export default function (pi: ExtensionAPI) {
 					"1. **## Related ADRs** — Links to ADR files with descriptions of relevance",
 					"2. **## Diagrams** — Embed the 4 mermaid diagrams from Step 2",
 					"3. **## Acceptance Criteria** — Add a table row for each component: | # | Component | Criterion | Verify In | with specific, testable acceptance criteria",
-					"5. **## Components** — Expand each aggregate with " + lang + " stubs, methods, invariants keep `status:` and `depends:` markers",
-					"6. **Domain Events** — Table: Event, Description, Trigger, Payload, Published By",
+					"5. **## Components** — depth-aware: for tactical modules expand aggregates with " + lang + " stubs, methods, exploration invariants, VO justifications and a domain/-owned repository interface; for service/adapter modules keep only what the Modeling Depth Note permits (no invented aggregates/VOs). Always keep `status:` and `depends:` markers",
+					"6. **Domain Events** (tactical modules only) — Table: Event, Description, Trigger, Payload, Published By; include ADR-008 triage flags (domain expert cares / crosses boundary / audit trail)",
 					"7. **API Endpoints** — Table: Method, Path, Handler, Input, Output, Auth",
 					"8. **Ubiquitous Language** — Terms for this context from `.pi/domain/ubiquitous-language.md`",
 					"9. **Dependencies** — Depends On + Used By",

package/templates/pi/extensions/filechanges.ts

@@ -493,7 +493,7 @@ export default function (pi: ExtensionAPI) {
 					})),
 				];
 
-				const picked = await ctx.ui.custom<string | null>(
+				const picked = await (ctx.ui as any).custom(
 					(tui, theme, _kb, done) => {
 						const container = new Container();
 						container.addChild(new DynamicBorder((s) => theme.fg("accent", s)));
@@ -546,7 +546,7 @@ export default function (pi: ExtensionAPI) {
 				}
 
 				const md = `\`\`\`diff\n${t.diff.trimEnd() || "(no diff)"}\n\`\`\``;
-				await ctx.ui.custom<void>(
+				await (ctx.ui as any).custom(
 					(tui, theme, _kb, done) => {
 						const container = new Container();
 						container.addChild(new DynamicBorder((s) => theme.fg("accent", s)));

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

@@ -285,9 +285,9 @@ class GoalManager {
 
 	clear(): void {
 		if (!this.state) return;
-		this.state.status = "cleared";
-		saveGoalState(this.cwd, this.state);
-		this.state = null;
+		this._state.status = "cleared";
+		saveGoalState(this.cwd, this._state);
+		this._state = null;
 	}
 
 	addSubgoal(textIn: string): string {

package/templates/pi/extensions/hooks.ts

@@ -52,7 +52,7 @@ type ExtensionContext = {
 };
 
 type ExtensionAPI = {
-	on(event: string, handler: (event: unknown, ctx: ExtensionContext) => void | Promise<void>): void;
+	on(event: string, handler: (event: unknown, ctx: ExtensionContext) => unknown | Promise<unknown>): void;
 	registerTool(options: {
 		name: string;
 		label: string;

package/templates/pi/extensions/pi-env.d.ts

@@ -0,0 +1,96 @@
+// Ambient declarations for the pi runtime SDK. The host provides these at
+// runtime with real types; not vendored here. Auto-generated names from
+// actual imports across the extension sources so tsc type-checks cleanly.
+
+declare module "@mariozechner/pi-coding-agent" {
+	export const DynamicBorder: any;
+	export type DynamicBorder = any;
+	export const ExtensionAPI: any;
+	export type ExtensionAPI = any;
+	export const ExtensionCommandContext: any;
+	export type ExtensionCommandContext = any;
+	export const ExtensionContext: any;
+	export type ExtensionContext = any;
+	export const createFindTool: any;
+	export type createFindTool = any;
+	export const createGrepTool: any;
+	export type createGrepTool = any;
+	export const createLsTool: any;
+	export type createLsTool = any;
+	export const createReadTool: any;
+	export type createReadTool = any;
+	export const getMarkdownTheme: any;
+	export type getMarkdownTheme = any;
+	export const isEditToolResult: any;
+	export type isEditToolResult = any;
+	export const isToolCallEventType: any;
+	export type isToolCallEventType = any;
+	export const isWriteToolResult: any;
+	export type isWriteToolResult = any;
+}
+
+declare module "@mariozechner/pi-tui" {
+	export const Container: any;
+	export type Container = any;
+	export const Editor: any;
+	export type Editor = any;
+	export const EditorTheme: any;
+	export type EditorTheme = any;
+	export const Key: any;
+	export type Key = any;
+	export const Markdown: any;
+	export type Markdown = any;
+	export const SelectItem: any;
+	export type SelectItem = any;
+	export const SelectList: any;
+	export type SelectList = any;
+	export const Text: any;
+	export type Text = any;
+	export const matchesKey: any;
+	export type matchesKey = any;
+	export const truncateToWidth: any;
+	export type truncateToWidth = any;
+	export const wrapTextWithAnsi: any;
+	export type wrapTextWithAnsi = any;
+}
+
+declare module "@earendil-works/pi-coding-agent" {
+	export const ExecResult: any;
+	export type ExecResult = any;
+	export const ExtensionAPI: any;
+	export type ExtensionAPI = any;
+	export const ExtensionContext: any;
+	export type ExtensionContext = any;
+}
+
+declare module "typebox" {
+	export const Type: any;
+	export type Type = any;
+	export const Static: any;
+	export type Static = any;
+	export const TObject: any;
+	export type TObject = any;
+	export const TSchema: any;
+	export type TSchema = any;
+	export const TProperties: any;
+	export type TProperties = any;
+	export const TString: any;
+	export type TString = any;
+	export const TArray: any;
+	export type TArray = any;
+	export const TOptional: any;
+	export type TOptional = any;
+	export const TBoolean: any;
+	export type TBoolean = any;
+	export const TNumber: any;
+	export type TNumber = any;
+	export const TUnion: any;
+	export type TUnion = any;
+	export const TLiteral: any;
+	export type TLiteral = any;
+	export const TRecord: any;
+	export type TRecord = any;
+	export const TAny: any;
+	export type TAny = any;
+}
+declare module "@sinclair/typebox" { export const Type: any; export type Static = any; }

package/templates/pi/extensions/pipeline.ts

@@ -256,7 +256,7 @@ class PipelineManager {
 	 * 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 {
+	reloadFromDisk(): void {
 		this.state = loadPipelineState(this.cwd);
 	}
 

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

@@ -227,7 +227,7 @@ export default function (pi: ExtensionAPI) {
 						dryRun ? "Mode: **Dry Run** (no files written)" : "Mode: **Live**",
 						"",
 						"```",
-						result.trim(),
+						String(result).trim(),
 						"```",
 						"",
 						dryRun