guardian-framework 0.1.104 → 0.1.109

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

@@ -122,10 +122,10 @@ function buildInScope(comp: ModuleComponent, primaryAcRows: AcRow[], implSteps:
 }
 
 /** Supported project languages. */
-type ProjectLanguage = "typescript" | "java" | "python" | "go" | "rust";
+export type ProjectLanguage = "typescript" | "java" | "python" | "go" | "rust";
 
 /** Detect project language at `cwd` by checking for build files. */
-function detectLanguage(cwd?: string): ProjectLanguage {
+export function detectLanguage(cwd?: string): ProjectLanguage {
 	if (!cwd) return "typescript";
 	try {
 		if (existsSync(join(cwd, "pom.xml")) || existsSync(join(cwd, "build.gradle")) || existsSync(join(cwd, "build.gradle.kts")))
@@ -143,7 +143,7 @@ function detectLanguage(cwd?: string): ProjectLanguage {
 }
 
 /** Language-specific file extension for implementation files. */
-function implExtension(lang: ProjectLanguage): string {
+export function implExtension(lang: ProjectLanguage): string {
 	switch (lang) {
 		case "java": return "java";
 		case "python": return "py";
@@ -154,7 +154,7 @@ function implExtension(lang: ProjectLanguage): string {
 }
 
 /** Language-specific test directory base. */
-function testBaseDirFromLang(lang: ProjectLanguage): string {
+export function testBaseDirFromLang(lang: ProjectLanguage): string {
 	switch (lang) {
 		case "java": return "src/test/java";
 		case "python": return "tests";
@@ -165,7 +165,7 @@ function testBaseDirFromLang(lang: ProjectLanguage): string {
 }
 
 /** Language-specific test runner command hint. */
-function testRunnerHintFromLang(lang: ProjectLanguage): string {
+export function testRunnerHintFromLang(lang: ProjectLanguage): string {
 	switch (lang) {
 		case "java": return "mvn test";
 		case "python": return "pytest";
@@ -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/tdd-generator.ts

@@ -81,7 +81,7 @@ export interface TddGenerateOptions {
 	cwd: string;
 	/** Language from manifest (default: "typescript") */
 	language: string;
-	/** Base test directory (default: "tests/unit") */
+	/** Base test directory (auto-detected from project language if not set) */
 	testBaseDir?: string;
 	/** Module name for path construction */
 	moduleName?: string;

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;