guardian-framework 0.1.105 → 0.1.110

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

@@ -197,6 +197,26 @@ export function generateIssueMarkdown(
 	const title = buildIssueTitle(comp, moduleId);
 	const inScope = buildInScope(comp, compAcs, implSteps, moduleId);
 
+	// ADR-008: append compact modeling directives for aggregate/root components.
+	const isTactical = comp.modelingDepth === "tactical" || comp.aggregateRoot;
+	if (isTactical && (comp.invariants?.length || comp.events)) {
+		if (comp.invariants?.length) {
+			inScope.push("Honor the frozen aggregate invariants: " + comp.invariants.join("; "));
+		}
+		if (comp.events) {
+			const ev = [
+				...(comp.events.publishes?.length ? ["publishes " + comp.events.publishes.join(", ")] : []),
+				...(comp.events.subscribes?.length ? ["subscribes " + comp.events.subscribes.join(", ")] : []),
+			].join(", ");
+			if (ev) inScope.push("Domain events: " + ev);
+		}
+		if (comp.aggregateRoot) {
+			inScope.push(
+				"Implement " + comp.name + " as the aggregate root — no setters; state changes via behavior methods; repository interface owned by the domain layer",
+			);
+		}
+	}
+
 	// Language-aware test paths
 	const lang = detectLanguage(cwd);
 	const ext = implExtension(lang);
@@ -373,6 +393,30 @@ export function generateContractFreezeMarkdown(
 	const implSteps = parseImplSequence(doc);
 	const allAcs = parseAcTable(doc);
 
+	// ADR-008 modeling contract for components carrying depth metadata.
+	const modelingParts = slice.nextLogicalSlice
+		.filter((c: ModuleComponent) => c.modelingDepth === "tactical" || c.aggregateRoot || c.invariants?.length || c.events)
+		.map((c: ModuleComponent) => {
+			const lines: string[] = [`### ${c.name}`];
+			if (c.aggregateRoot) {
+				lines.push("- Aggregate root — all state changes flow through behavior methods (no setters)");
+				lines.push("- Repository interface is owned by the domain layer (interface-ownership, ADR-008)");
+				lines.push("- One aggregate per transaction; reference other aggregates by identity");
+			}
+			if (c.invariants?.length) {
+				lines.push("- Frozen invariants (become pre-generated failing tests):");
+				for (const inv of c.invariants) lines.push(`  - ${inv}`);
+			}
+			if (c.events) {
+				if (c.events.publishes?.length) lines.push("- Publishes: " + c.events.publishes.join(", "));
+				if (c.events.subscribes?.length) lines.push("- Subscribes: " + c.events.subscribes.join(", "));
+			}
+			return lines.join("\n");
+		});
+	const modelingContract = modelingParts.length > 0
+		? "## Modeling Contract (ADR-008)\n\n" + modelingParts.join("\n\n")
+		: "";
+
 	return `---
 guardian_issue:
   id: "ISSUE-CONTRACT-FREEZE"
@@ -481,6 +525,8 @@ ${implSteps.length > 0
 	? `## Full Implementation Sequence (for reference)\n\n${implSteps.map((s) => '- ' + s).join("\n")}`
 	: ""}
 
+${modelingContract}
+
 ## Implementation
 
 > **Agent:** Create interface-only files. No implementation. Use Clean Architecture layers:
@@ -552,7 +598,6 @@ guardian_issue:
 
   file_changes:
     - "create: .pi/scripts/ci/check_${moduleId}_contracts.sh"
-    - "create: .pi/scripts/ci/check_${moduleId}_coverage.sh"
     - "modify: .pi/scripts/ci/run_hardening_stages.sh"
 ---
 
@@ -572,10 +617,15 @@ automatic — no human review needed for routine checks.
 - Verifies all interface methods are implemented
 - Reports violations with file:line references
 
-### Coverage Threshold Check
-- Runs the project's coverage tool
-- Asserts each module meets minimum coverage (default 80%)
-- Fails the build if coverage drops
+### Coverage Threshold Check (real project coverage)
+- Coverage is enforced with the PROJECT'S REAL coverage tooling and gate
+  (e.g. \`cargo llvm-cov\` via a \`.pi/scripts/coverage.sh --gate\`, \`pytest
+  --cov\`, or \`c8\`/\`nyc\` for TS — whatever the project's CI coverage job
+  uses); assert the aggregate threshold the project actually enforces
+- Do NOT create a per-module \`*_coverage.sh\` script — grep-based module
+  coverage scripts are coverage-theater (count test functions, never a
+  percentage); the real coverage tool's artifact (lcov/cobertura) provides
+  the per-file breakdown instead
 
 ### CI Integration
 Each check becomes a CI stage in the hardening pipeline — it runs automatically
@@ -586,7 +636,6 @@ on every PR. No LLM cost. No human review. Just pass or fail.
 | Script | Purpose | Location |
 |--------|---------|----------|
 | check_${moduleId}_contracts.sh | Validate contract implementation | .pi/scripts/ci/ |
-| check_${moduleId}_coverage.sh | Enforce coverage thresholds | .pi/scripts/ci/ |
 | stage_${moduleId}_proofing.sh | CI stage wrapper | .pi/scripts/ci/ |
 
 ## CI Pipeline Update
@@ -604,7 +653,7 @@ run_stage "11" "${moduleId}_proofing" \\
 | # | Criterion | Script |
 |---|-----------|--------|
 | 1 | All interfaces have implementations | check_contracts.sh |
-| 2 | Coverage ≥ 80% per module | check_coverage.sh |
+| 2 | Coverage meets the project's real coverage gate (project coverage tool + threshold in CI) | project coverage job (e.g. .pi/scripts/coverage.sh --gate) |
 | 3 | CI runs checks on every PR | run_hardening_stages.sh |
 | 4 | All scripts exit 0 on pass, 1 on fail | self-validating |
 
@@ -634,6 +683,108 @@ run_stage "11" "${moduleId}_proofing" \\
 
 // ── Architecture Readiness Generator (expanded) ──
 
+
+/**
+ * ADR-009: Runtime Integration & Legacy Migration issue generator.
+ * Modules whose doc documents runtime integration get a mandatory epic item
+ * (after implementation, before proofing) so "implemented but never wired"
+ * can no longer be deferred via an honest note.
+ */
+export function moduleHasRuntimeIntegration(cwd: string, moduleId: string): boolean {
+	const doc = readModuleDoc(cwd, moduleId);
+	if (!doc) return false;
+	return /^#{2,3}\s+(Integration|Runtime|Dispatch|Wiring|.*Dispatch.*)/im.test(doc);
+}
+
+export function generateRuntimeIntegrationMarkdown(
+	slice: ArchitectureSlice,
+	epicName: string,
+	cwd?: string,
+): string {
+	const moduleId = slice.module.replace(/^module-/, "");
+	const doc = cwd ? readModuleDoc(cwd, slice.module) : "";
+	// Pull the documented integration seam(s) as guidance for the implementer.
+	const seam = (() => {
+		for (const heading of ["Integration with Existing Modules", "Runtime Integration", "Integration"]) {
+			const body = extractSection(doc, heading);
+			if (body && body.trim().length > 0) return `## ${heading}\n\n${body.trim().slice(0, 1800)}`;
+		}
+		return "";
+	})();
+
+	return `---
+guardian_issue:
+  id: "ISSUE-RUNTIME-INTEGRATION"
+  epic: "${epicName}"
+  component: "Runtime Integration & Legacy Migration"
+  module: "${slice.module}"
+  status: planned
+  priority: high
+  dependencies: []
+
+  in_scope:
+    - Wire the new service(s) into the REAL runtime path — every choke point the module doc
+      documents (primary dispatch loop PLUS parallel / resume / hook variants; not just one seam)
+    - Remove or delegate the legacy path the module replaces (legacy symbol deleted or calling
+      the new service); honor any declared migration rule (e.g. GAP-N)
+    - Flip the feature ADR from Proposed to Accepted once wired
+    - Add an end-to-end test through the PUBLIC API that exercises the new path
+
+  out_of_scope:
+    - New feature behavior beyond wiring
+    - Schema/data migrations (unless the module doc's migration rule requires them)
+
+  canonical_references:
+    - module: ".pi/architecture/modules/${slice.module}.md"
+    - adr: ".pi/architecture/decisions/ADR-009-runtime-wiring-multilang-judgment.md"
+
+  acceptance_criteria:
+    - "New service reachable from the runtime entry path (production, non-test caller)"
+    - "Legacy path removed or delegating; migration rule honored"
+    - "Feature ADR Accepted"
+    - "E2E through the public API exercises the new path"
+    - "validate-runtime-wiring.sh passes for the module (no dead service)"
+
+  validators:
+    - ci
+    - tests
+    - architecture
+    - operations
+    - canonical
+
+  implementation_notes: |
+    Run .pi/scripts/validate-runtime-wiring.sh before and after. If the new service
+    is only referenced by its own tests, it is NOT integrated. Converting the
+    documented dispatch choke point(s) is the acceptance slice — do not close this
+    issue with an honest deferral note.
+
+  file_changes:
+    - "modify: runtime dispatch / composition root (per module doc integration section)"
+---
+
+# Runtime Integration & Legacy Migration: ${slice.module}
+
+## Intent
+
+The implementation issues above delivered tested components. This issue makes them
+**actually run**: wire them into the runtime dispatch path, retire the legacy path,
+and prove it with an end-to-end test — per ADR-009 (implemented-but-unwired is the
+gap this closes).
+
+${seam || "> No explicit integration section found in the module doc — trace the runtime entry path (dispatch/composition root) yourself."}
+
+## Acceptance Criteria
+
+| # | Criterion | How to Verify |
+|---|-----------|---------------|
+| 1 | Service reachable from runtime entry path | grep production (non-test) caller outside the module |
+| 2 | Legacy path removed or delegating | legacy symbol deleted / delegates to new service |
+| 3 | Feature ADR Accepted | ADR Status not Proposed |
+| 4 | E2E exercises the new path through the public API | integration/e2e test |
+| 5 | validate-runtime-wiring.sh passes | script exit 0 |
+`;
+}
+
 export function generateArchitectureReadinessMarkdown(
 	slice: ArchitectureSlice,
 	epicName: string,

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

@@ -353,6 +353,11 @@ export function parseModuleFile(filePath: string): ModuleComponent[] {
 	let currentStatus = "";
 	let currentDesc = "";
 	let currentDeps: string[] = [];
+	let currentDepth = undefined as ModuleComponent["modelingDepth"];
+	let currentAggregateRoot = false;
+	let currentInvariants: string[] = [];
+	let currentPublishes: string[] = [];
+	let currentSubscribes: string[] = [];
 
 	function saveCurrent() {
 		if (currentName) {
@@ -364,6 +369,17 @@ export function parseModuleFile(filePath: string): ModuleComponent[] {
 				status: status as ModuleComponent["status"],
 				description: desc.trim(),
 				dependencies: currentDeps.length > 0 ? currentDeps : ["none"],
+				...(currentDepth ? { modelingDepth: currentDepth } : {}),
+				...(currentAggregateRoot ? { aggregateRoot: true } : {}),
+				...(currentInvariants.length > 0 ? { invariants: currentInvariants } : {}),
+				...(currentPublishes.length > 0 || currentSubscribes.length > 0
+					? {
+							events: {
+								publishes: currentPublishes,
+								subscribes: currentSubscribes,
+							},
+						}
+					: {}),
 			});
 		}
 	}
@@ -384,6 +400,11 @@ export function parseModuleFile(filePath: string): ModuleComponent[] {
 			currentStatus = "";
 			currentDesc = "";
 			currentDeps = [];
+			currentDepth = undefined;
+			currentAggregateRoot = false;
+			currentInvariants = [];
+			currentPublishes = [];
+			currentSubscribes = [];
 			inComponentSection = false;
 			inDetailsSection = false;
 			continue;
@@ -401,6 +422,11 @@ export function parseModuleFile(filePath: string): ModuleComponent[] {
 			currentStatus = "";
 			currentDesc = "";
 			currentDeps = [];
+			currentDepth = undefined;
+			currentAggregateRoot = false;
+			currentInvariants = [];
+			currentPublishes = [];
+			currentSubscribes = [];
 			continue;
 		}
 
@@ -413,6 +439,29 @@ export function parseModuleFile(filePath: string): ModuleComponent[] {
 			if (depsStr && depsStr !== "none" && depsStr !== "[TODO") {
 				currentDeps = depsStr.split(",").map((d) => d.trim()).filter(Boolean);
 			}
+		} else if (trimmed.startsWith("modelingDepth:")) {
+			const v = trimmed.replace("modelingDepth:", "").trim();
+			if (v === "tactical" || v === "service" || v === "adapter") currentDepth = v;
+		} else if (trimmed.startsWith("aggregateRoot:")) {
+			currentAggregateRoot = trimmed.replace("aggregateRoot:", "").trim() === "true";
+		} else if (trimmed.startsWith("invariants:")) {
+			currentInvariants = trimmed
+				.replace("invariants:", "")
+				.split(";")
+				.map((x) => x.trim())
+				.filter(Boolean);
+		} else if (trimmed.startsWith("publishes:")) {
+			currentPublishes = trimmed
+				.replace("publishes:", "")
+				.split(",")
+				.map((x) => x.trim())
+				.filter(Boolean);
+		} else if (trimmed.startsWith("subscribes:")) {
+			currentSubscribes = trimmed
+				.replace("subscribes:", "")
+				.split(",")
+				.map((x) => x.trim())
+				.filter(Boolean);
 		} else if (trimmed.startsWith("**Purpose:**")) {
 			currentDesc = trimmed.replace(/\*\*Purpose:\*\*\s*/, "").trim();
 		} else if (!currentDesc && trimmed.length > 10 && !trimmed.startsWith("#") && !trimmed.startsWith("-") && !trimmed.startsWith("|") && !trimmed.startsWith(">") && !trimmed.startsWith("```")) {

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

@@ -55,12 +55,16 @@ export type ExtensionContext = {
 		notify(message: string, level?: string): void;
 		setStatus(key: string, message: string | null): void;
 		confirm(title: string, message: string): Promise<boolean>;
+		theme?: unknown;
 	};
 	tools: { execute(name: string, params: Record<string, unknown>): Promise<unknown> };
 };
 
 export 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;
@@ -70,7 +74,7 @@ export 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;
@@ -96,6 +100,14 @@ export type ModuleComponent = {
 	status: "planned" | "in-progress" | "implemented" | "deprecated";
 	description: string;
 	dependencies: string[];
+	/** ADR-008 modeling depth for this component's module (from exploration) */
+	modelingDepth?: "tactical" | "service" | "adapter";
+	/** True when this component is an aggregate root — slice selection keeps it atomic */
+	aggregateRoot?: boolean;
+	/** Aggregate invariants (ADR-008) — become frozen contract + TDD tests */
+	invariants?: string[];
+	/** Domain events this aggregate publishes/subscribes to (ADR-008) */
+	events?: { publishes: string[]; subscribes: string[] };
 };
 
 export type ArchitectureSlice = {
@@ -104,6 +116,36 @@ export type ArchitectureSlice = {
 	nextLogicalSlice: ModuleComponent[];
 };
 
+
+/** A module row inside a roadmap phase (implementation-roadmap.md). */
+export interface RoadmapPhaseModule {
+	name: string;
+	deliverables: string;
+	doc: string;
+}
+
+/** A single delivery phase parsed from implementation-roadmap.md. */
+export interface RoadmapPhase {
+	index: number;
+	title: string;
+	goal: string;
+	days: string;
+	modules: RoadmapPhaseModule[];
+	completedModules: string[];
+	dependencies: string[];
+	migrations: string[];
+	criteria: string[];
+	status: string; // "pending" | "in_progress" | "done"
+}
+
+/** Persisted roadmap execution state (.pi/.guardian-roadmap-state.json). */
+export interface RoadmapState {
+	phases: RoadmapPhase[];
+	currentPhaseIndex: number;
+	startedAt: string;
+	updatedAt: string;
+}
+
 export type EpicState = {
 	name: string;
 	trackingIssueId: string | null;

package/templates/pi/extensions/architect.ts

@@ -34,10 +34,10 @@ import {
 	generateContractFreezeMarkdown,
 	generateIssueMarkdown,
 	generateProofingMarkdown,
+	generateRuntimeIntegrationMarkdown,
+	moduleHasRuntimeIntegration,
 	detectLanguage,
 	testBaseDirFromLang,
-	testRunnerHintFromLang,
-	implExtension,
 } from "./architect-lib/generators";
 import {
 	generateEpicTestFiles,
@@ -112,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);
 	}
 
@@ -120,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,
@@ -141,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.");
@@ -283,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 = {
@@ -346,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",
@@ -386,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) {
@@ -455,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;
@@ -469,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()));
 				}
@@ -486,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) {
@@ -541,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,
@@ -583,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);
@@ -594,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,
@@ -674,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;
 				}
@@ -717,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;
 				}
@@ -782,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;
 				}
@@ -810,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,
@@ -841,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 = "";
@@ -904,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) }] };
 		},
@@ -924,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") }] };
 		},