guardian-framework 0.1.78 → 0.1.80

package/dist/cli.js

@@ -3197,7 +3197,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.78", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
+var name = "guardian-framework", version = "0.1.80", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
 var init_package = __esm(() => {
   exports = {
     ".": {
@@ -12438,6 +12438,23 @@ ${bc.description}
 
 `;
       content += `${depsSection}
+`;
+      content += `## Acceptance Criteria
+
+`;
+      content += `Each component in this module must satisfy its specific acceptance criteria.
+`;
+      content += `Fill these out for each component before implementation begins.
+`;
+      content += `
+`;
+      content += `| # | Component | Criterion | Verify In |
+`;
+      content += `|---|-----------|-----------|-----------|
+`;
+      content += `| 1 | [Component] | [Specific, testable criterion] | [unit / integration / manual] |
+`;
+      content += `
 `;
       content += `## Key Files
 
@@ -12641,6 +12658,24 @@ ${bc.description}
       content += `Each layer MUST NOT leak into adjacent layers.
 `;
       content += `
+`;
+      content += `## Acceptance Criteria
+`;
+      content += `
+`;
+      content += `Each component in this module must satisfy its specific acceptance criteria.
+`;
+      content += `Fill these out for each component before implementation begins.
+`;
+      content += `
+`;
+      content += `| # | Component | Criterion | Verify In |
+`;
+      content += `|---|-----------|-----------|-----------|
+`;
+      content += `| 1 | [Component] | [Specific, testable criterion] | [unit / integration / manual] |
+`;
+      content += `
 `;
       content += `## ADRs
 `;

package/dist/exports.js

@@ -1982,7 +1982,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.78", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
+var name = "guardian-framework", version = "0.1.80", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
 var init_package = __esm(() => {
   exports = {
     ".": {
@@ -12762,6 +12762,23 @@ ${bc.description}
 
 `;
       content += `${depsSection}
+`;
+      content += `## Acceptance Criteria
+
+`;
+      content += `Each component in this module must satisfy its specific acceptance criteria.
+`;
+      content += `Fill these out for each component before implementation begins.
+`;
+      content += `
+`;
+      content += `| # | Component | Criterion | Verify In |
+`;
+      content += `|---|-----------|-----------|-----------|
+`;
+      content += `| 1 | [Component] | [Specific, testable criterion] | [unit / integration / manual] |
+`;
+      content += `
 `;
       content += `## Key Files
 
@@ -12965,6 +12982,24 @@ ${bc.description}
       content += `Each layer MUST NOT leak into adjacent layers.
 `;
       content += `
+`;
+      content += `## Acceptance Criteria
+`;
+      content += `
+`;
+      content += `Each component in this module must satisfy its specific acceptance criteria.
+`;
+      content += `Fill these out for each component before implementation begins.
+`;
+      content += `
+`;
+      content += `| # | Component | Criterion | Verify In |
+`;
+      content += `|---|-----------|-----------|-----------|
+`;
+      content += `| 1 | [Component] | [Specific, testable criterion] | [unit / integration / manual] |
+`;
+      content += `
 `;
       content += `## ADRs
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "guardian-framework",
-	"version": "0.1.78",
+	"version": "0.1.80",
 	"description": "Token-optimized agentic framework scaffolder with pi-first architecture",
 	"type": "module",
 	"main": "dist/exports.js",

package/templates/pi/architecture/modules/module-template.md

@@ -121,6 +121,18 @@ Response → commit or rollback → UI update
 
 ---
 
+## Acceptance Criteria
+
+Each component in this module has specific acceptance criteria that must be verified
+before the implementation issue can be closed. These ACs flow into the generated issues.
+
+| # | Component | Criterion | Verify In |
+|---|-----------|-----------|-----------|
+| 1 | [ComponentName] | [Specific, testable criterion for this component] | [unit test / integration test / manual] |
+| 2 | [ComponentName] | [Another criterion] | [verification method] |
+
+---
+
 ## Dependencies
 
 ### Depends On

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

@@ -1,64 +1,245 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import type { ArchitectureSlice, ModuleComponent } from "./types.ts";
 
+// ── Module Doc Readers ───────────────────────────────────────────────────────
+
+/** Read the raw module architecture doc, or empty string if missing. */
+function readModuleDoc(cwd: string, moduleId: string): string {
+	try {
+		return readFileSync(
+			join(cwd, ".pi", "architecture", "modules", `${moduleId}.md`),
+			"utf-8",
+		);
+	} catch {
+		return "";
+	}
+}
+
+/** Extract a named section's body (between ## heading and next ## / --- / EOF). */
+function extractSection(doc: string, heading: string): string {
+	const re = new RegExp(`## ${heading}\n([\\s\\S]*?)(?=\n##|\n---|$)`);
+	const m = re.exec(doc);
+	return m ? m[1].trim() : "";
+}
+
+interface AcRow { num: string; component?: string; criterion: string; verifyIn: string; }
+
+/**
+ * Parse every AC row from ## Acceptance Criteria.
+ * Supports:
+ *   4-column: `| # | Component | Criterion | Verify In |`
+ *   3-column: `| # | Criterion | Verify In |`
+ * Returns rows with component populated when the 4-col format is detected.
+ */
+function parseAcTable(doc: string): AcRow[] {
+	const section = extractSection(doc, "Acceptance Criteria");
+	if (!section) return [];
+	const rows = section.match(/^\| [\d✅☐][^|]*\|[^|]+\|[^|]+\|[^|]*\|$/gm) ?? [];
+	return rows.map((row) => {
+		const parts = row.split("|").map((p) => p.trim()).filter(Boolean);
+		// 4-col: [num, component, criterion, verifyIn]
+		// 3-col: [num, criterion, verifyIn]
+		const isFourCol = parts.length >= 4 && parts[1] !== "Criterion";
+		if (isFourCol) {
+			return { num: parts[0] ?? "", component: parts[1], criterion: parts[2] ?? "", verifyIn: parts[3] ?? "" };
+		}
+		return { num: parts[0] ?? "", criterion: parts[1] ?? "", verifyIn: parts[2] ?? "" };
+	});
+}
+
+/** Parse numbered steps from ## Implementation Sequence. */
+function parseImplSequence(doc: string): string[] {
+	const section = extractSection(doc, "Implementation Sequence");
+	if (!section) return [];
+	return (section.match(/^\d+\. .+$/gm) ?? []).map((s) => s.trim());
+}
+
+/**
+ * Filter ACs that belong to a specific component.
+ * 
+ * When the AC table has a Component column (4-col format), ACs are matched
+ * by component name. Falls back to keyword matching on criterion text when
+ * no component column is present.
+ */
+function primaryAcs(acs: AcRow[], componentName: string): AcRow[] {
+	if (acs.length === 0) return [];
+
+	// Prefer explicit component column match
+	const byComponent = acs.filter((ac) => ac.component && ac.component === componentName);
+	if (byComponent.length > 0) return byComponent;
+
+	// Fallback: keyword match on criterion text
+	const lower = componentName.toLowerCase();
+	const isDomainModel =
+		(lower.includes("entity") || lower.includes("aggregate") ||
+		 lower.includes("snapshot") || lower.includes("enum")) &&
+		!lower.includes("repository");
+
+	const matched = acs.filter((ac) =>
+		ac.criterion.toLowerCase().includes(lower.replace(/[^a-z0-9]/g, "")),
+	);
+	if (matched.length > 0) return matched;
+
+	if (isDomainModel) {
+		const domainKeywords = ["entity", "aggregate", "enum", "value object", "jpa", "migration", "flyway", "snapshot", "status"];
+		const filtered = acs.filter((ac) =>
+			domainKeywords.some((kw) => ac.criterion.toLowerCase().includes(kw)),
+		);
+		if (filtered.length > 0) return filtered;
+	}
+
+	// Last resort: evenly split ACs among all components (assuming n components, take 1/n-th)
+	return acs.slice(0, Math.max(1, Math.ceil(acs.length / 4)));
+}
+
+/** Format AcRow[] as a markdown table body (no header). Includes Component column if any row has one. */
+function acRowsToMarkdown(rows: AcRow[]): string {
+	const hasComponent = rows.some((r) => r.component);
+	if (hasComponent) {
+		return rows.map((r) => `| ${r.num} | ${r.component} | ${r.criterion} | ${r.verifyIn} |`).join("\n");
+	}
+	return rows.map((r) => `| ${r.num} | ${r.criterion} | ${r.verifyIn} |`).join("\n");
+}
+
+/** Build a human-readable title for the component issue. */
+function buildIssueTitle(comp: ModuleComponent, moduleId: string): string {
+	return `Implement ${comp.name} — ${moduleId}`;
+}
+
+/** Derive `in_scope` lines from primary ACs. Falls back to generic if none. */
+function buildInScope(comp: ModuleComponent, primaryAcRows: AcRow[], implSteps: string[], moduleId: string): string[] {
+	if (primaryAcRows.length > 0) {
+		return primaryAcRows.slice(0, 6).map((r) => r.criterion.replace(/^✅\s*/, ""));
+	}
+	if (implSteps.length > 0) {
+		return implSteps.slice(0, 4).map((s) => s.replace(/^\d+\.\s*/, ""));
+	}
+	return [
+		`Implement ${comp.name} for the ${moduleId} module`,
+		"Write unit tests for all public methods",
+		"Add integration tests with upstream/downstream components",
+	];
+}
+
+/** Detect whether project at `cwd` is a Java project. */
+function isJavaProject(cwd?: string): boolean {
+	if (!cwd) return false;
+	try {
+		return existsSync(join(cwd, "pom.xml")) ||
+		       existsSync(join(cwd, "build.gradle")) ||
+		       existsSync(join(cwd, "build.gradle.kts"));
+	} catch {
+		return false;
+	}
+}
+
 // ── Issue Generation ──
 
 export function generateIssueMarkdown(
-	component: ModuleComponent,
+	comp: ModuleComponent,
 	slice: ArchitectureSlice,
 	issueIndex: number,
-	totalIssues: number,
+	_totalIssues: number,
 	tdd?: boolean,
+	cwd?: string,
 ): string {
 	const moduleId = slice.module.replace(/^module-/, "");
-	const componentName = component.name.toLowerCase().replace(/\s+/g, "-");
 	const issueId = `ISSUE-${moduleId.toUpperCase()}-${issueIndex + 1}`;
 
+	// ── Read module doc for specifics ──
+	const doc = cwd ? readModuleDoc(cwd, slice.module) : "";
+	const allAcs = parseAcTable(doc);
+	const implSteps = parseImplSequence(doc);
+	const compAcs = primaryAcs(allAcs, comp.name);
+
+	const title = buildIssueTitle(comp, moduleId);
+	const inScope = buildInScope(comp, compAcs, implSteps, moduleId);
+
+	// Language-aware test paths
+	const isJava = isJavaProject(cwd);
+	const testBaseDir = isJava ? "src/test/java" : "tests/unit";
+	const testRunnerHint = isJava ? "mvn test" : "bun test";
+
 	const testLine = tdd
-		? `    - "update: tests/unit/${moduleId}/${componentName}/ (failing tests already generated — make them pass)"`
-		: `    - "create: tests/unit/${moduleId}/${componentName}/"`;
+		? `    - "update: ${testBaseDir}/ (failing tests already generated — make them pass)"`
+		: `    - "create: ${testBaseDir}/"`;
+
+	// YAML front-matter ACs
+	const yamlAcs = compAcs.length > 0
+		? compAcs.map((r) => {
+			const c = r.criterion.replace(/^✅\s*/, "").replaceAll("\"", "'");
+			return `    - "${c}"`;
+		}).join("\n")
+		: `    - "CI pipeline passes (validate-ci.sh)"
+    - "All unit tests pass"
+    - "Architecture compliance (validate-architecture.sh)"
+    - "Canonical references valid (validate-canonical.sh)"`;
+
+	// Markdown body: all ACs
+	const hasCompCol = allAcs.some((a) => a.component);
+	const allAcHeader = hasCompCol
+		? `| # | Component | Criterion | Verify In |\n|---|-----------|-----------|-----------|`
+		: `| # | Criterion | Verify In |\n|---|-----------|-----------|`;
+	const allAcMarkdown = allAcs.length > 0
+		? `${allAcHeader}\n${acRowsToMarkdown(allAcs)}`
+		: `| # | Criterion | Validator |\n|---|-----------|-----------|\n| 1 | CI pipeline passes | \`validate-ci.sh\` |\n| 2 | All unit tests pass | \`validate-tests.sh\` |\n| 3 | Integration tests pass | \`validate-integration.sh\` |\n| 4 | Architecture compliance | \`validate-architecture.sh\` |\n| 5 | Canonical references valid | \`validate-canonical.sh\` |`;
+
+	// Implementation steps from module doc
+	const stepsMarkdown = implSteps.length > 0
+		? implSteps.map((s) => `- ${s}`).join("\n")
+		: `- Read .pi/architecture/modules/${slice.module}.md\n- Implement entities and interfaces\n- Implement infrastructure (adapter, mapper, repository)\n- Implement use case\n- Write unit + integration tests\n- Run validators\n- Create MR`;
+
+	const tddSteps = tdd
+		? [
+				"1. Read canonical architecture references",
+				`2. Run the pre-generated failing tests: \`cd ${testBaseDir} && ${testRunnerHint}\``,
+				"3. Verify tests FAIL (Red phase)",
+				"4. Implement domain entities and interfaces",
+				"5. Implement application service/handler",
+				"6. Add infrastructure connections",
+				"7. Run tests again — they should PASS (Green phase)",
+				"8. Refactor if needed (Refactor phase)",
+				"9. Write integration tests",
+				"10. Run all validators",
+				"11. Create MR",
+			].join("\n")
+		: [
+				"1. Read canonical architecture references",
+				"2. Create domain entities and interfaces",
+				"3. Implement application service/handler",
+				"4. Add infrastructure connections",
+				"5. Write unit tests (≥ 90% coverage)",
+				"6. Write integration tests",
+				"7. Run all validators",
+				"8. Create MR",
+			].join("\n");
 
 	return `---
 guardian_issue:
   id: "${issueId}"
   epic: "TBD"
-  component: "${component.name}"
+  component: "${comp.name}"
   module: "${slice.module}"
   status: planned
   priority: high
   dependencies:
-${component.dependencies.map((d) => `    - "${d}"`).join("\n")}
+${comp.dependencies.map((d) => `    - "${d}"`).join("\n")}
 
   in_scope:
-    - Implement ${component.name} for the ${slice.module} module
-    - Write unit tests for all public interfaces
-    - Add integration tests with upstream/downstream components
-    - Create API documentation
+${inScope.map((s) => { const sc = s.replaceAll("\"", "'"); return `    - "${sc}"`; }).join("\n")}
 
   out_of_scope:
-    - Changes to upstream components (${component.dependencies.join(", ")})
+    - Changes to upstream components (${comp.dependencies.join(", ") || "none"})
     - UI/frontend changes
     - Deployment pipeline configuration
 
-  affected_layers:
-    domain:
-      - New domain models for ${componentName}
-    application:
-      - New service/handler for ${componentName}
-    infrastructure:
-      - New database tables or external service connections
-    api:
-      - New endpoints or event handlers
-
   canonical_references:
-    - module: ".pi/architecture/modules/${slice.module}.md#${componentName}"
+    - module: ".pi/architecture/modules/${slice.module}.md"
+    - acceptance_criteria: ".pi/architecture/modules/${slice.module}.md#acceptance-criteria"
 
   acceptance_criteria:
-    - "CI pipeline passes (validate-ci.sh)"
-    - "All unit tests pass with ≥ 90% coverage"
-    - "Integration tests pass with upstream/downstream components"
-    - "validate-security.sh passes"
-    - "validate-architecture.sh passes"
-    - "validate-canonical.sh passes"
+${yamlAcs}
 
   validators:
     - ci
@@ -68,7 +249,9 @@ ${component.dependencies.map((d) => `    - "${d}"`).join("\n")}
     - canonical
 
   implementation_notes: |
-    ${component.description || "Implement this component according to the architecture module."}
+    Read .pi/architecture/modules/${slice.module}.md BEFORE implementing.
+    All Acceptance Criteria in that file must be satisfied before this issue is closed.
+    Component focus: ${comp.name}.
 
   file_changes:
     - "modify: src/${moduleId}/domain/"
@@ -76,85 +259,60 @@ ${component.dependencies.map((d) => `    - "${d}"`).join("\n")}
     - "modify: src/${moduleId}/infrastructure/"
     - "modify: src/${moduleId}/interfaces/"
     - ${testLine}
-    - "create: tests/integration/${moduleId}/${componentName}/"
 ---
 
-# ${issueId}: ${component.name}
+# ${issueId}: ${title}
 
 ## Intent
 
-${component.description || `Implement ${component.name} for the ${slice.module} module.`}
+Implement **${comp.name}** for the \`${slice.module}\` module.
+
+> ⚠️ **Read before implementing:** \`.pi/architecture/modules/${slice.module}.md\`
+> Every item in the **Acceptance Criteria** section of that file must be satisfied
+> before this issue is closed — including adapter, mapper, and WireMock items.
 
 ## Architecture Context
 
 - **Module:** ${slice.module}
-- **Component:** ${component.name}
-- **Status:** ${component.status}
-- **Dependencies:** ${component.dependencies.length > 0 ? component.dependencies.join(", ") : "none"}
-
-## Dependencies
-
-\`\`\`
-${component.dependencies.map((d) => `  └── ${d}`).join("\n") || "  └── (root component — no dependencies)"}
-\`\`\`
-
-## In Scope
-
-- Implement ${component.name} for the ${slice.module} module
-- Write unit tests for all public interfaces
-- Add integration tests with upstream/downstream components
-- Create API documentation
-
-## Out of Scope
+- **Component:** ${comp.name}
+- **Status:** ${comp.status}
+- **Dependencies:** ${comp.dependencies.length > 0 ? comp.dependencies.join(", ") : "none"}
 
-- Changes to upstream components
-- UI/frontend changes
-- Deployment pipeline configuration
+## In Scope (this component)
 
-## Affected Layers
+${inScope.map((s) => `- ${s}`).join("\n")}
 
-### Domain
-- New domain models for ${componentName}
+## Acceptance Criteria (this issue)
 
-### Application
-- New service/handler for ${componentName}
+These acceptance criteria must be satisfied before this issue can be closed:
 
-### Infrastructure
-- New database tables or external service connections
+| # | Criterion | Verify In |
+|---|-----------|-----------|
+${compAcs.length > 0 ? compAcs.map((r) => `| ${r.num} | ${r.criterion} | ${r.verifyIn} |`).join("\n") : `| 1 | CI pipeline passes | \`validate-ci.sh\` |\n| 2 | All unit tests pass | \`validate-tests.sh\` |\n| 3 | Architecture compliance | \`validate-architecture.sh\` |\n| 4 | Canonical references valid | \`validate-canonical.sh\` |`}
 
-### API
-- New endpoints or event handlers
+## Full Module Acceptance Criteria
 
-## Canonical References
+> All items below must pass before the **epic** is closed.
+> Items may be split across multiple issues — verify your component's items before creating the MR.
 
-- **Module:** \`.pi/architecture/modules/${slice.module}.md#${componentName}\`
+${allAcMarkdown}
 
-## Acceptance Criteria
+## Implementation Sequence (from module doc)
 
-| # | Criterion | Validator |
-|---|-----------|-----------|
-| 1 | CI pipeline passes | \`validate-ci.sh\` |
-| 2 | All unit tests pass with ≥ 90% coverage | \`validate-tests.sh\` |
-| 3 | Integration tests pass | \`validate-integration.sh\` |
-| 4 | Security checks pass | \`validate-security.sh\` |
-| 5 | Architecture compliance | \`validate-architecture.sh\` |
-| 6 | Canonical references valid | \`validate-canonical.sh\` |
+${stepsMarkdown}
 
 ## Implementation
 
-> **Agent:** This is your complete session context. All information you need is above.
-> Start by reading the canonical reference files, then implement following the layer structure.
+> **Agent instructions:**
+> 1. Open \`.pi/architecture/modules/${slice.module}.md\` — read the full Acceptance Criteria table
+> 2. Identify which rows are your responsibility for **${comp.name}**
+> 3. Implement all of them — entity, JPA entity, migration, adapter (all endpoints), mapper, use case
+> 4. Verify each AC row is satisfied in \`src/\` before marking done
+> 5. Run validators and create MR
 
 ### Steps
 
-1. Read canonical architecture references
-2. Create domain entities and interfaces
-3. Implement application service/handler
-4. Add infrastructure connections
-5. Write unit tests (≥ 90% coverage)
-6. Write integration tests
-7. Run all validators
-8. Create MR
+${tddSteps}
 `;
 }
 // ── Contract Freeze Generator ──
@@ -162,9 +320,13 @@ ${component.dependencies.map((d) => `  └── ${d}`).join("\n") || "  └─
 export function generateContractFreezeMarkdown(
 	slice: ArchitectureSlice,
 	epicName: string,
-	codegenSkill?: string,
+	_codegenSkill?: string,
+	cwd?: string,
 ): string {
 	const moduleId = slice.module.replace(/^module-/, "");
+	const doc = cwd ? readModuleDoc(cwd, slice.module) : "";
+	const implSteps = parseImplSequence(doc);
+	const allAcs = parseAcTable(doc);
 
 	return `---
 guardian_issue:
@@ -200,8 +362,8 @@ guardian_issue:
     - module: ".pi/architecture/modules/${slice.module}.md"
 
   acceptance_criteria:
-    - "All component interfaces defined as interfaces/types"
-    - "DTO schemas documented"
+    - "All component interfaces defined as stubs (TODO bodies)"
+    - "DTO schemas documented with field names and types"
     - "API contracts frozen and reviewed"
     - "Implementation PRs reference these contracts"
 
@@ -213,7 +375,7 @@ guardian_issue:
     Define the contract before any implementation. Every implementation issue
     depends on this contract being frozen first. The contract should include:
     interfaces, types, DTOs, event schemas, API paths, error formats.
-    ${codegenSkill ? `Follow: .pi/skills/agents/${codegenSkill}.md` : ""}
+    ${_codegenSkill ? `Follow: .pi/skills/agents/${_codegenSkill}.md` : ""}
 
   file_changes:
     - "create: src/${moduleId}/domain/"
@@ -256,11 +418,25 @@ ${slice.nextLogicalSlice.map((c: { name: string }) => `- ${c.name}`).join("\n")}
 
 | # | Criterion | How to Verify |
 |---|-----------|---------------|
-| 1 | All component interfaces defined | Check src/<group>/<module>/domain/ and application/ |
+| 1 | All component interfaces defined as stubs (TODO bodies) | Check src/<module>/domain/ and application/ |
 | 2 | Contracts reviewed and frozen | PR approval |
-| 3 | DTO schemas documented | OpenAPI / TypeSpec / equivalent |
+| 3 | DTO schemas documented with field names and types | OpenAPI / record types |
 | 4 | Implementation depends on contracts | No implementation without interface |
 
+${allAcs.length > 0
+	? (() => {
+		const hasComp = allAcs.some((a) => a.component);
+		const header = hasComp
+			? `| # | Component | Criterion | Verify In |\n|---|-----------|-----------|-----------|`
+			: `| # | Criterion | Verify In |\n|---|-----------|-----------|`;
+		return `## Full Module Acceptance Criteria (for reference)\n\n> These are the complete ACs for the module. The contract freeze must define the interfaces\n> so every row below can be implemented in subsequent issues.\n\n${header}\n${acRowsToMarkdown(allAcs)}`;
+	})()
+	: ""}
+
+${implSteps.length > 0
+	? `## Full Implementation Sequence (for reference)\n\n${implSteps.map((s) => '- ' + s).join("\n")}`
+	: ""}
+
 ## Implementation
 
 > **Agent:** Create interface-only files. No implementation. Use Clean Architecture layers:

package/templates/pi/extensions/architect-lib/tdd-generator.ts

@@ -48,7 +48,6 @@ export function generateEpicTestFiles(options: TddGenerateOptions): string[] {
 		moduleId,
 		cwd,
 		language,
-		testBaseDir = "tests/unit",
 		moduleName,
 	} = options;
 
@@ -56,11 +55,23 @@ export function generateEpicTestFiles(options: TddGenerateOptions): string[] {
 		return [];
 	}
 
+	// ── Language-specific base dir & path strategy ──
+	let testBaseDir = options.testBaseDir;
+	let modulePath: string;
+
+	if (language === "java") {
+		testBaseDir = testBaseDir ?? "src/test/java";
+		modulePath = (moduleName || moduleId).replace(/[^a-zA-Z0-9\/]/g, "-");
+	} else {
+		testBaseDir = testBaseDir ?? "tests/unit";
+		modulePath = moduleName || moduleId;
+	}
+
 	const generated: string[] = [];
-	const modulePath = moduleName || moduleId;
 
 	for (const comp of components) {
-		const componentId = comp.name.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+		const componentId = comp.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+
 		const testDir = join(cwd, testBaseDir, modulePath, componentId);
 		mkdirSync(testDir, { recursive: true });
 
@@ -125,7 +136,7 @@ function generateTestContent(
 function generateTypeScript(
 	component: ModuleComponent,
 	moduleId: string,
-	componentId: string,
+	_componentId: string,
 ): string {
 	const lines: string[] = [
 		`// Generated by Guardian TDD`,

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

@@ -114,5 +114,6 @@ export type EpicState = {
 	currentIssueIndex: number;
 	createdAt: string;
 	tdd: boolean;
+	tddTestFiles: string[];
 };
 

package/templates/pi/extensions/architect.ts

@@ -6,7 +6,7 @@
 
 import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import type { ArchitectureSlice, EpicState, ExtensionAPI, ExtensionContext, ModuleComponent, RoadmapPhase, RoadmapState, RoadmapPhaseModule } from "./architect-lib/types.ts";
+import type { ArchitectureSlice, EpicState, ExtensionAPI, ExtensionContext, ModuleComponent, RoadmapPhase } from "./architect-lib/types.ts";
 import {
 	ARCH_MODULES_DIR,
 	commandExists,
@@ -22,7 +22,6 @@ import {
 	loadRoadmapState,
 	parseModuleFile,
 	parseRoadmap,
-	readGroupId,
 	readRepository,
 	readLanguage,
 	readRepoTool,
@@ -187,8 +186,8 @@ class EpicManager {
 				+ "\n  3. Or set repoTool: \"local\" in guardian-manifest.json for local-only mode"
 				+ "\n",
 			);
-			this.ui.notify("Epic aborted — remote setup failed. Set repoTool: \"local\" to run without a remote forge.", "error");
-			return;
+			ctx.ui.notify("Epic aborted — remote setup failed. Set repoTool: \"local\" to run without a remote forge.", "error");
+			return null as unknown as EpicState;
 		}
 
 		const issues: { id: string; title: string; status: string; remoteIssueId?: string | null }[] = [];
@@ -246,7 +245,7 @@ class EpicManager {
 			status: "planned",
 			remoteIssueId: null as string | null,
 		};
-		const freezeMarkdown = generateContractFreezeMarkdown(slice, name);
+		const freezeMarkdown = generateContractFreezeMarkdown(slice, name, undefined, this.cwd);
 		writeFileSync(join(issuesDir, `${freezeId}.md`), freezeMarkdown);
 		if (hasRemote && remoteRepo) {
 			const result = createRemoteIssue(this.cwd, freezeEntry.title, join(issuesDir, `${freezeId}.md`), "epic,contract", remoteRepo);
@@ -260,14 +259,15 @@ class EpicManager {
 		// 2. Implementation issues
 		for (let i = 0; i < slice.nextLogicalSlice.length; i++) {
 			const comp = slice.nextLogicalSlice[i];
+			const moduleId = slice.module.replace(/^module-/, "");
 			const id = `issue-${comp.name.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`;
 			const entry = {
 				id,
-				title: `${comp.name}: ${comp.description.slice(0, 80)}`,
+				title: `Implement ${comp.name} — ${moduleId}`,
 				status: "planned" as string,
 				remoteIssueId: null as string | null,
 			};
-			const md = generateIssueMarkdown(comp, slice, i, slice.nextLogicalSlice.length, tdd);
+			const md = generateIssueMarkdown(comp, slice, i, slice.nextLogicalSlice.length, tdd, this.cwd);
 			writeFileSync(join(issuesDir, `${id}.md`), md);
 			if (hasRemote && remoteRepo) {
 				const result = createRemoteIssue(this.cwd, entry.title, join(issuesDir, `${id}.md`), "epic,implementation", remoteRepo);

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

@@ -1034,12 +1034,13 @@ 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. **## Components** — Expand each aggregate with " + lang + " stubs, methods, invariants keep `status:` and `depends:` markers",
-					"4. **Domain Events** — Table: Event, Description, Trigger, Payload, Published By",
-					"5. **API Endpoints** — Table: Method, Path, Handler, Input, Output, Auth",
-					"6. **Ubiquitous Language** — Terms for this context from `.pi/domain/ubiquitous-language.md`",
-					"7. **Dependencies** — Depends On + Used By",
-					"8. **Implementation Sequence** — Ordered build list",
+					"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",
+					"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",
+					"10. **Implementation Sequence** — Ordered build list",
 					"",
 					"### STEP 4: Generate Implementation Roadmap",
 					"",

package/templates/pi/extensions/tsconfig.json

@@ -0,0 +1,15 @@
+{
+	"compilerOptions": {
+		"types": ["bun-types"],
+		"strict": true,
+		"target": "ES2022",
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"noEmit": true,
+		"isolatedModules": true,
+		"allowImportingTsExtensions": true
+	},
+	"include": ["**/*.ts"]
+}

package/templates/pi/preflight_report.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-07-14T09:09:07Z",
+  "timestamp": "2026-07-16T10:04:14Z",
   "mode": "all",
   "stages_run": [],
   "summary": {

package/templates/pi/scripts/ci/check_architecture_conformance.sh

@@ -35,21 +35,21 @@ declare -a FAILURES=()
 
 log_pass() {
     echo -e "  ${GREEN}✓ PASS${NC} $1"
-    ((PASS_COUNT++))
-    ((TOTAL_COUNT++))
+    PASS_COUNT=$((PASS_COUNT + 1))
+    TOTAL_COUNT=$((TOTAL_COUNT + 1))
 }
 
 log_fail() {
     echo -e "  ${RED}✗ FAIL${NC} $1 — $2"
-    ((FAIL_COUNT++))
-    ((TOTAL_COUNT++))
+    FAIL_COUNT=$((FAIL_COUNT + 1))
+    TOTAL_COUNT=$((TOTAL_COUNT + 1))
     FAILURES+=("$1: $2")
 }
 
 log_skip() {
     echo -e "  ${YELLOW}⊘ SKIP${NC} $1 — $2"
-    ((SKIP_COUNT++))
-    ((TOTAL_COUNT++))
+    SKIP_COUNT=$((SKIP_COUNT + 1))
+    TOTAL_COUNT=$((TOTAL_COUNT + 1))
 }
 
 # ── Language Detection ──

package/templates/pi/scripts/validate-architecture-readiness.sh

@@ -23,9 +23,9 @@ NC='\033[0m'
 PASS=0
 FAIL=0
 
-log_pass() { echo -e "  ${GREEN}✓ PASS${NC} $1"; ((PASS++)); }
-log_fail() { echo -e "  ${RED}✗ FAIL${NC} $1 — $2"; ((FAIL++)); }
-log_skip() { echo -e "  ${YELLOW}⊘ SKIP${NC} $1 — $2"; ((PASS++)); }
+log_pass() { echo -e "  ${GREEN}✓ PASS${NC} $1"; PASS=$((PASS + 1)); }
+log_fail() { echo -e "  ${RED}✗ FAIL${NC} $1 — $2"; FAIL=$((FAIL + 1)); }
+log_skip() { echo -e "  ${YELLOW}⊘ SKIP${NC} $1 — $2"; PASS=$((PASS + 1)); }
 
 echo "═══ Architecture Readiness Checks ═══"
 echo ""

package/templates/pi/scripts/validate-ci.sh

@@ -18,6 +18,8 @@ detect_language() {
         echo "rust"
     elif [ -f "go.mod" ]; then
         echo "go"
+    elif [ -f "pom.xml" ] || [ -f "build.gradle" ] || [ -f "build.gradle.kts" ]; then
+        echo "java"
     elif [ -f "package.json" ]; then
         echo "typescript"
     else