guardian-framework 0.1.63 → 0.1.65

package/dist/cli.js

@@ -2930,6 +2930,25 @@ import * as crypto2 from "crypto";
 import * as fs3 from "fs";
 import * as path4 from "path";
 import { fileURLToPath } from "url";
+function loadFrameworkVersion() {
+  if (_cachedVersion)
+    return _cachedVersion;
+  try {
+    const dir = path4.dirname(_filename);
+    const candidates = [
+      path4.resolve(dir, "..", "..", "package.json"),
+      path4.resolve(dir, "..", "package.json")
+    ];
+    for (const candidate of candidates) {
+      if (fs3.existsSync(candidate)) {
+        _cachedVersion = JSON.parse(fs3.readFileSync(candidate, "utf-8")).version;
+        return _cachedVersion;
+      }
+    }
+  } catch {}
+  _cachedVersion = "0.0.0";
+  return _cachedVersion;
+}
 function hashFile(filePath) {
   if (!fs3.existsSync(filePath)) {
     return "";
@@ -3099,10 +3118,11 @@ function calculateTokenStats(targetDir, manifest) {
     lastCalculatedAt: new Date().toISOString()
   };
 }
-var _filename, _dirname, MANIFEST_FILE = "guardian-manifest.json", FRAMEWORK_VERSION = "0.1.61", SCHEMA_VERSION = "0.1";
+var _filename, _dirname, MANIFEST_FILE = "guardian-manifest.json", _cachedVersion, FRAMEWORK_VERSION, SCHEMA_VERSION = "0.1";
 var init_manifest = __esm(() => {
   _filename = fileURLToPath(import.meta.url);
   _dirname = path4.dirname(_filename);
+  FRAMEWORK_VERSION = loadFrameworkVersion();
 });
 
 // src/lib/retry.ts
@@ -3129,7 +3149,7 @@ function calculateBackoff(attempt, baseDelayMs, maxBackoffMs) {
   return Math.min(delay, maxBackoffMs);
 }
 function sleep(ms) {
-  return new Promise((resolve3) => setTimeout(resolve3, ms));
+  return new Promise((resolve4) => setTimeout(resolve4, ms));
 }
 var DEFAULT_OPTIONS;
 var init_retry = __esm(() => {
@@ -3178,7 +3198,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.63", 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.65", 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 = {
     ".": {
@@ -10657,7 +10677,7 @@ import * as child_process from "child_process";
 import * as fs6 from "fs";
 async function executeHook(hookName, script, workspacePath, timeoutMs) {
   const startTime = Date.now();
-  return new Promise((resolve4) => {
+  return new Promise((resolve5) => {
     const proc = child_process.spawn("bash", ["-lc", script], {
       cwd: workspacePath,
       stdio: ["ignore", "pipe", "pipe"]
@@ -10698,7 +10718,7 @@ async function executeHook(hookName, script, workspacePath, timeoutMs) {
       clearTimeout(hardTimer);
       if (stallTimer)
         clearTimeout(stallTimer);
-      resolve4({
+      resolve5({
         success: code === 0,
         exitCode: code ?? 1,
         stdout: stdout2.trim(),
@@ -10710,7 +10730,7 @@ async function executeHook(hookName, script, workspacePath, timeoutMs) {
       clearTimeout(hardTimer);
       if (stallTimer)
         clearTimeout(stallTimer);
-      resolve4({
+      resolve5({
         success: false,
         exitCode: 1,
         stdout: "",
@@ -14454,6 +14474,7 @@ init_update();
 // src/commands/upgrade.ts
 init_dist4();
 init_manifest();
+init_update();
 async function runUpgrade(targetDir = process.cwd(), options = {}) {
   const manifest = readManifest(targetDir);
   if (!manifest) {
@@ -14462,10 +14483,11 @@ async function runUpgrade(targetDir = process.cwd(), options = {}) {
   }
   const currentSchema = manifest.schemaVersion ?? "unknown";
   const currentFramework = manifest.frameworkVersion ?? "unknown";
-  if (currentSchema === SCHEMA_VERSION && currentFramework === FRAMEWORK_VERSION) {
-    outro(`Project is already on the latest version (schema ${SCHEMA_VERSION}, framework ${FRAMEWORK_VERSION}).`);
-    return;
-  }
+  await runUpdate(targetDir, {
+    dryRun: options.dryRun,
+    force: options.force,
+    regenerate: options.regenerate
+  });
   const migrations = [];
   if (currentSchema !== SCHEMA_VERSION) {
     migrations.push(`Schema: ${currentSchema} \u2192 ${SCHEMA_VERSION}`);
@@ -14477,7 +14499,7 @@ async function runUpgrade(targetDir = process.cwd(), options = {}) {
     migrations.push(`Framework: ${currentFramework} \u2192 ${FRAMEWORK_VERSION}`);
   }
   if (migrations.length === 0) {
-    outro("No migrations needed.");
+    outro("Project is on the latest version. Template files synced.");
     return;
   }
   if (options.dryRun) {
@@ -15257,7 +15279,9 @@ async function runCommand(command, args) {
       break;
     case "upgrade":
       await runUpgrade(targetDir, {
-        dryRun: args.values.dryRun
+        dryRun: args.values.dryRun,
+        force: args.values.force,
+        regenerate: args.values.regenerate
       });
       break;
     case "uninstall":

package/dist/exports.js

@@ -1750,6 +1750,25 @@ import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
+function loadFrameworkVersion() {
+  if (_cachedVersion)
+    return _cachedVersion;
+  try {
+    const dir = path.dirname(_filename);
+    const candidates = [
+      path.resolve(dir, "..", "..", "package.json"),
+      path.resolve(dir, "..", "package.json")
+    ];
+    for (const candidate of candidates) {
+      if (fs.existsSync(candidate)) {
+        _cachedVersion = JSON.parse(fs.readFileSync(candidate, "utf-8")).version;
+        return _cachedVersion;
+      }
+    }
+  } catch {}
+  _cachedVersion = "0.0.0";
+  return _cachedVersion;
+}
 function hashFile(filePath) {
   if (!fs.existsSync(filePath)) {
     return "";
@@ -1919,10 +1938,11 @@ function calculateTokenStats(targetDir, manifest) {
     lastCalculatedAt: new Date().toISOString()
   };
 }
-var _filename, _dirname, MANIFEST_FILE = "guardian-manifest.json", FRAMEWORK_VERSION = "0.1.61", SCHEMA_VERSION = "0.1";
+var _filename, _dirname, MANIFEST_FILE = "guardian-manifest.json", _cachedVersion, FRAMEWORK_VERSION, SCHEMA_VERSION = "0.1";
 var init_manifest = __esm(() => {
   _filename = fileURLToPath(import.meta.url);
   _dirname = path.dirname(_filename);
+  FRAMEWORK_VERSION = loadFrameworkVersion();
 });
 
 // src/lib/result.ts
@@ -1963,7 +1983,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.63", 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.65", 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 = {
     ".": {
@@ -2668,7 +2688,7 @@ function calculateBackoff(attempt, baseDelayMs, maxBackoffMs) {
   return Math.min(delay, maxBackoffMs);
 }
 function sleep(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 var DEFAULT_OPTIONS;
 var init_retry = __esm(() => {
@@ -9781,7 +9801,7 @@ import * as child_process from "node:child_process";
 import * as fs4 from "node:fs";
 async function executeHook(hookName, script, workspacePath, timeoutMs) {
   const startTime = Date.now();
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     const proc = child_process.spawn("bash", ["-lc", script], {
       cwd: workspacePath,
       stdio: ["ignore", "pipe", "pipe"]
@@ -9822,7 +9842,7 @@ async function executeHook(hookName, script, workspacePath, timeoutMs) {
       clearTimeout(hardTimer);
       if (stallTimer)
         clearTimeout(stallTimer);
-      resolve2({
+      resolve3({
         success: code === 0,
         exitCode: code ?? 1,
         stdout: stdout2.trim(),
@@ -9834,7 +9854,7 @@ async function executeHook(hookName, script, workspacePath, timeoutMs) {
       clearTimeout(hardTimer);
       if (stallTimer)
         clearTimeout(stallTimer);
-      resolve2({
+      resolve3({
         success: false,
         exitCode: 1,
         stdout: "",
@@ -14122,6 +14142,7 @@ function collectDirectoriesToPrune(files2) {
 // src/commands/upgrade.ts
 init_dist4();
 init_manifest();
+init_update();
 async function runUpgrade(targetDir = process.cwd(), options = {}) {
   const manifest = readManifest(targetDir);
   if (!manifest) {
@@ -14130,10 +14151,11 @@ async function runUpgrade(targetDir = process.cwd(), options = {}) {
   }
   const currentSchema = manifest.schemaVersion ?? "unknown";
   const currentFramework = manifest.frameworkVersion ?? "unknown";
-  if (currentSchema === SCHEMA_VERSION && currentFramework === FRAMEWORK_VERSION) {
-    outro(`Project is already on the latest version (schema ${SCHEMA_VERSION}, framework ${FRAMEWORK_VERSION}).`);
-    return;
-  }
+  await runUpdate(targetDir, {
+    dryRun: options.dryRun,
+    force: options.force,
+    regenerate: options.regenerate
+  });
   const migrations = [];
   if (currentSchema !== SCHEMA_VERSION) {
     migrations.push(`Schema: ${currentSchema} → ${SCHEMA_VERSION}`);
@@ -14145,7 +14167,7 @@ async function runUpgrade(targetDir = process.cwd(), options = {}) {
     migrations.push(`Framework: ${currentFramework} → ${FRAMEWORK_VERSION}`);
   }
   if (migrations.length === 0) {
-    outro("No migrations needed.");
+    outro("Project is on the latest version. Template files synced.");
     return;
   }
   if (options.dryRun) {

package/package.json

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

package/templates/pi/extensions/architect-lib/forge-adapter.ts

@@ -54,6 +54,24 @@ export function readRepository(cwd: string): string | null {
 	return null;
 }
 
+/**
+ * Read project language from guardian-manifest.json (defaults to "typescript")
+ */
+export function readLanguage(cwd: string): string {
+	try {
+		const manifestPath = join(cwd, "guardian-manifest.json");
+		if (existsSync(manifestPath)) {
+			const raw = readFileSync(manifestPath, "utf-8");
+			const manifest = JSON.parse(raw) as { language?: string; templateContext?: { language?: string } };
+			if (manifest.language) return manifest.language;
+			if (manifest.templateContext?.language) return manifest.templateContext.language;
+		}
+	} catch {
+		// fall through to default
+	}
+	return "typescript";
+}
+
 /**
  * Get forge base URL. For GitLab, detects self-hosted instances via glab config.
  */

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

@@ -5,6 +5,7 @@ import type { ExtensionContext, EpicState, ModuleComponent, ArchitectureSlice, R
 import {
 	readRepoTool as adapterReadRepoTool,
 	readRepository as adapterReadRepository,
+	readLanguage as adapterReadLanguage,
 	getGitBaseUrl as adapterGetGitBaseUrl,
 	commandExists as adapterCommandExists,
 	runScript as adapterRunScript,
@@ -30,6 +31,7 @@ export function log(ctx: ExtensionContext, message: string, level = "info") {
 export const runScript = adapterRunScript;
 export const readRepoTool = adapterReadRepoTool;
 export const readRepository = adapterReadRepository;
+export const readLanguage = adapterReadLanguage;
 export const getGitBaseUrl = adapterGetGitBaseUrl;
 export const commandExists = adapterCommandExists;
 

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

@@ -0,0 +1,354 @@
+/**
+ * TDD Test Generator for Guardian Architect Extension
+ *
+ * Deterministic test file generation from architecture module components.
+ * No LLM involvement — tests are generated from structured component data.
+ *
+ * When --tdd is enabled on an epic via /architect --epic "Name" --tdd,
+ * this generator creates failing test files before implementation issues
+ * reach the agent. The agent makes them green via Red→Green→Refactor.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ModuleComponent } from "./types.ts";
+
+// ── Supported Languages ──
+
+const TDD_LANGUAGES = new Set(["typescript", "rust", "python", "go", "java"]);
+
+export function isTddSupported(language: string): boolean {
+	return TDD_LANGUAGES.has(language);
+}
+
+// ── Main Generator ──
+
+export interface TddGenerateOptions {
+	/** Array of components from the epic's slice */
+	components: ModuleComponent[];
+	/** Module identifier (e.g., "audit-ingestion") */
+	moduleId: string;
+	/** Project root directory */
+	cwd: string;
+	/** Language from manifest (default: "typescript") */
+	language: string;
+	/** Base test directory (default: "tests/unit") */
+	testBaseDir?: string;
+	/** Module name for path construction */
+	moduleName?: string;
+}
+
+/**
+ * Generate failing test files for all components in an epic slice.
+ * Returns list of generated file paths.
+ */
+export function generateEpicTestFiles(options: TddGenerateOptions): string[] {
+	const {
+		components,
+		moduleId,
+		cwd,
+		language,
+		testBaseDir = "tests/unit",
+		moduleName,
+	} = options;
+
+	if (!isTddSupported(language)) {
+		return [];
+	}
+
+	const generated: string[] = [];
+	const modulePath = moduleName || moduleId;
+
+	for (const comp of components) {
+		const componentId = comp.name.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+		const testDir = join(cwd, testBaseDir, modulePath, componentId);
+		mkdirSync(testDir, { recursive: true });
+
+		const fileName = getTestFileName(componentId, language);
+		const filePath = join(testDir, fileName);
+
+		// Skip if file already exists (don't overwrite user edits)
+		if (existsSync(filePath)) continue;
+
+		const content = generateTestContent(comp, language, moduleId, componentId);
+		writeFileSync(filePath, content, "utf-8");
+		generated.push(filePath);
+	}
+
+	return generated;
+}
+
+// ── Test File Name ──
+
+function getTestFileName(componentId: string, language: string): string {
+	switch (language) {
+		case "typescript":
+			return `${componentId}.test.ts`;
+		case "rust":
+			return `${componentId}_test.rs`;
+		case "python":
+			return `test_${componentId}.py`;
+		case "go":
+			return `${componentId}_test.go`;
+		case "java":
+			return `${toPascalCase(componentId)}Test.java`;
+		default:
+			return `${componentId}.test.ts`;
+	}
+}
+
+// ── Test Content Generation ──
+
+function generateTestContent(
+	component: ModuleComponent,
+	language: string,
+	moduleId: string,
+	componentId: string,
+): string {
+	switch (language) {
+		case "rust":
+			return generateRust(component, moduleId, componentId);
+		case "python":
+			return generatePython(component, moduleId, componentId);
+		case "go":
+			return generateGo(component, moduleId, componentId);
+		case "java":
+			return generateJava(component, moduleId, componentId);
+		case "typescript":
+		default:
+			return generateTypeScript(component, moduleId, componentId);
+	}
+}
+
+// ── TypeScript Test Generator ──
+
+function generateTypeScript(
+	component: ModuleComponent,
+	moduleId: string,
+	componentId: string,
+): string {
+	const lines: string[] = [
+		`// Generated by Guardian TDD`,
+		`// From: ${component.name} (${moduleId} module)`,
+		`// These tests will FAIL until ${component.name} is implemented.`,
+		``,
+		`import { describe, it, expect } from "bun:test";`,
+		``,
+		`describe("${component.name}", () => {`,
+	];
+
+	// Instantiation test
+	lines.push(...indent([
+		`it("should be defined", () => {`,
+		`  expect(false).toBe(true);`,
+		`  // TODO: uncomment when ${component.name} is implemented`,
+		`  // const instance = new ${component.name.replace(/[^a-zA-Z0-9]/g, "")}();`,
+		`  // expect(instance).toBeDefined();`,
+		`});`,
+	], 1));
+
+	// Dependency interaction tests
+	for (const dep of component.dependencies) {
+		lines.push(...indent([
+			`it("should interact with ${dep}", () => {`,
+			`  expect(false).toBe(true);`,
+			`  // TODO: implement dependency test for ${dep}`,
+			`  // const mock = { /* mock ${dep} interface */ };`,
+			`  // const result = new ${component.name.replace(/[^a-zA-Z0-9]/g, "")}(mock);`,
+			`  // expect(result).toBeDefined();`,
+			`});`,
+		], 1));
+	}
+
+	lines.push(`});`);
+	lines.push(``);
+	return lines.join("\n");
+}
+
+// ── Rust Test Generator ──
+
+function generateRust(
+	component: ModuleComponent,
+	moduleId: string,
+	componentId: string,
+): string {
+	const lines: string[] = [
+		`// Generated by Guardian TDD`,
+		`// From: ${component.name} (${moduleId} module)`,
+		`// These tests will FAIL until ${component.name} is implemented.`,
+		``,
+		`#[cfg(test)]`,
+		`mod tests {`,
+		`    use super::*;`,
+		``,
+		`    #[test]`,
+		`    fn test_${componentId}_is_defined() {`,
+		`        // TODO: uncomment when ${component.name} is implemented`,
+		`        // let _instance = ${toPascalCase(componentId)}::new();`,
+		`        assert!(false, "Test not yet implemented");`,
+		`    }`,
+	];
+
+	for (const dep of component.dependencies) {
+		lines.push(...[
+			``,
+			`    #[test]`,
+			`    fn test_${componentId}_interacts_with_${dep.replace(/[^a-z0-9]/gi, "_").toLowerCase()}() {`,
+			`        // TODO: implement dependency test for ${dep}`,
+			`        // let mock = Mock${dep.replace(/[^a-zA-Z0-9]/g, "")}::new();`,
+			`        // let result = ${toPascalCase(componentId)}::new(mock);`,
+			`        assert!(false, "Dependency test not yet implemented");`,
+			`    }`,
+		]);
+	}
+
+	lines.push(`}`);
+	lines.push(``);
+	return lines.join("\n");
+}
+
+// ── Python Test Generator ──
+
+function generatePython(
+	component: ModuleComponent,
+	moduleId: string,
+	componentId: string,
+): string {
+	const clsName = toPascalCase(componentId);
+	const lines: string[] = [
+		`# Generated by Guardian TDD`,
+		`# From: ${component.name} (${moduleId} module)`,
+		`# These tests will FAIL until ${component.name} is implemented.`,
+		``,
+		`import pytest`,
+		``,
+		``,
+		`class Test${clsName}:`,
+		`    """Tests for ${component.name}."""`,
+		``,
+		`    def test_${componentId}_is_defined(self):`,
+		`        """${component.name} should be instantiable."""`,
+		`        assert False, "TODO: uncomment when ${component.name} is implemented"`,
+		`        # instance = ${clsName}()`,
+		`        # assert instance is not None`,
+	];
+
+	for (const dep of component.dependencies) {
+		lines.push(...[
+			``,
+			`    def test_${componentId}_interacts_with_${dep.replace(/[^a-z0-9]/gi, "_").toLowerCase()}(self):`,
+			`        """${component.name} should interact with ${dep}."""`,
+			`        assert False, "TODO: implement dependency test for ${dep}"`,
+			`        # mock = MagicMock(spec=${dep.replace(/[^a-zA-Z0-9]/g, "")})`,
+			`        # instance = ${clsName}(mock)`,
+			`        # result = instance.execute()`,
+			`        # assert result is not None`,
+		]);
+	}
+
+	lines.push(``);
+	return lines.join("\n");
+}
+
+// ── Go Test Generator ──
+
+function generateGo(
+	component: ModuleComponent,
+	moduleId: string,
+	componentId: string,
+): string {
+	const lines: string[] = [
+		`// Generated by Guardian TDD`,
+		`// From: ${component.name} (${moduleId} module)`,
+		`// These tests will FAIL until ${component.name} is implemented.`,
+		``,
+		`package ${moduleId.replace(/[^a-zA-Z0-9]/g, "").toLowerCase()}`,
+		``,
+		`import "testing"`,
+		``,
+		`func Test${toPascalCase(componentId)}_IsDefined(t *testing.T) {`,
+		`	// TODO: uncomment when ${component.name} is implemented`,
+		`	// instance := New${toPascalCase(componentId)}()`,
+		`	// if instance == nil {`,
+		`	// 	t.Fail()`,
+		`	// }`,
+		`	t.Fatal("Test not yet implemented")`,
+		`}`,
+	];
+
+	for (const dep of component.dependencies) {
+		lines.push(...[
+			``,
+			`func Test${toPascalCase(componentId)}_InteractsWith_${capitalize(dep.replace(/[^a-zA-Z0-9]/g, ""))}(t *testing.T) {`,
+			`	// TODO: implement dependency test for ${dep}`,
+			`	// mock := new(Mock${capitalize(dep.replace(/[^a-zA-Z0-9]/g, ""))})`,
+			`	// instance := New${toPascalCase(componentId)}(mock)`,
+			`	// result := instance.Execute()`,
+			`	t.Fatal("Dependency test not yet implemented")`,
+			`}`,
+		]);
+	}
+
+	lines.push(``);
+	return lines.join("\n");
+}
+
+// ── Java Test Generator ──
+
+function generateJava(
+	component: ModuleComponent,
+	moduleId: string,
+	componentId: string,
+): string {
+	const clsName = toPascalCase(componentId);
+	const lines: string[] = [
+		`// Generated by Guardian TDD`,
+		`// From: ${component.name} (${moduleId} module)`,
+		`// These tests will FAIL until ${component.name} is implemented.`,
+		``,
+		`import org.junit.jupiter.api.Test;`,
+		`import static org.junit.jupiter.api.Assertions.*;`,
+		``,
+		`class ${clsName}Test {`,
+		``,
+		`    @Test`,
+		`    void test${clsName}_IsDefined() {`,
+		`        // TODO: uncomment when ${component.name} is implemented`,
+		`        // ${clsName} instance = new ${clsName}();`,
+		`        // assertNotNull(instance);`,
+		`        fail("Test not yet implemented");`,
+		`    }`,
+	];
+
+	for (const dep of component.dependencies) {
+		lines.push(...[
+			``,
+			`    @Test`,
+			`    void test${clsName}_InteractsWith_${capitalize(dep.replace(/[^a-zA-Z0-9]/g, ""))}() {`,
+			`        // TODO: implement dependency test for ${dep}`,
+			`        // ${capitalize(dep.replace(/[^a-zA-Z0-9]/g, ""))} mock = mock(${capitalize(dep.replace(/[^a-zA-Z0-9]/g, ""))}.class);`,
+			`        // ${clsName} instance = new ${clsName}(mock);`,
+			`        fail("Dependency test not yet implemented");`,
+			`    }`,
+		]);
+	}
+
+	lines.push(`}`);
+	lines.push(``);
+	return lines.join("\n");
+}
+
+// ── Utility ──
+
+function capitalize(s: string): string {
+	return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+function toPascalCase(s: string): string {
+	return s.split("-").map(capitalize).join("");
+}
+
+function indent(lines: string[], level: number): string[] {
+	const pad = "  ".repeat(level);
+	return lines.map((l) => `${pad}${l}`);
+}

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

@@ -113,5 +113,6 @@ export type EpicState = {
 	issues: { id: string; title: string; status: string; remoteIssueId?: string | null }[];
 	currentIssueIndex: number;
 	createdAt: string;
+	tdd: boolean;
 };
 

package/templates/pi/extensions/architect.ts

@@ -24,6 +24,7 @@ import {
 	parseRoadmap,
 	readGroupId,
 	readRepository,
+	readLanguage,
 	readRepoTool,
 	runScript,
 	saveRoadmapState,
@@ -34,6 +35,10 @@ import {
 	generateIssueMarkdown,
 	generateProofingMarkdown,
 } from "./architect-lib/generators";
+import {
+	generateEpicTestFiles,
+	isTddSupported,
+} from "./architect-lib/tdd-generator";
 
 // ── Helpers ──
 
@@ -94,6 +99,7 @@ function formatEpicStatus(state: EpicState | null): string {
 		`Progress: ${done}/${total} components`,
 		`Issues: ${(state.issues || []).length}`,
 		`Pipeline: ${state.status}`,
+		state.tdd ? `TDD: enabled` : `TDD: disabled`,
 	].join("\n");
 }
 
@@ -114,6 +120,7 @@ class EpicManager {
 		ctx: ExtensionContext,
 		name: string,
 		trackingIssueId?: string,
+		tdd = false,
 	): Promise<EpicState> {
 		const moduleFiles = discoverModules(this.cwd);
 		if (moduleFiles.length === 0) {
@@ -293,6 +300,20 @@ class EpicManager {
 		}
 		issues.push(readinessEntry);
 
+		// ── TDD test generation ──
+		let tddTestFiles: string[] = [];
+		if (tdd) {
+			const language = readLanguage(this.cwd);
+			if (isTddSupported(language)) {
+				tddTestFiles = generateEpicTestFiles({
+					components: slice.nextLogicalSlice,
+					moduleId: slice.module,
+					cwd: this.cwd,
+					language,
+				});
+			}
+		}
+
 		const state: EpicState = {
 			name,
 			trackingIssueId: effectiveTrackingId,
@@ -302,6 +323,7 @@ class EpicManager {
 			status: "planning",
 			currentIssueIndex: 0,
 			createdAt: new Date().toISOString(),
+			tdd,
 		};
 
 		this.state = state;
@@ -339,7 +361,7 @@ export default function (pi: ExtensionAPI) {
 			const tokens = raw ? parseArgs(raw) : [];
 			if (tokens.length === 0) {
 				ctx.ui.notify(
-					"Usage: /architect [--epic Name] [--tracking-issue N] | --roadmap | --phase \"Phase 1\" | --phase-status | --phase-done <N> | --phase-module-done <N> \"Module\" | status | next-epic | abort",
+					"Usage: /architect [--epic Name] [--tracking-issue N] [--tdd] | --roadmap | --phase \"Phase 1\" | --phase-status | --phase-done <N> | --phase-module-done <N> \"Module\" | status | next-epic | abort",
 					"info",
 				);
 				return;
@@ -701,19 +723,20 @@ export default function (pi: ExtensionAPI) {
 
 			const epicName = findFlag(tokens, "--epic");
 			const trackingIssueId = findFlag(tokens, "--tracking-issue");
+			const tddEnabled = tokens.includes("--tdd");
 
 			if (!epicName) {
-				ctx.ui.notify('Usage: /architect --epic "Epic Name" [--tracking-issue N]', "error");
+				ctx.ui.notify('Usage: /architect --epic "Epic Name" [--tracking-issue N] [--tdd]', "error");
 				return;
 			}
 
 			try {
 				if (!epicName || epicName.trim() === "") {
-					ctx.ui.notify('Usage: /architect --epic "Epic Name"', "error");
+					ctx.ui.notify('Usage: /architect --epic "Epic Name" [--tracking-issue N] [--tdd]', "error");
 					return;
 				}
 
-				const state = await manager.startEpic(ctx, epicName, trackingIssueId);
+				const state = await manager.startEpic(ctx, epicName, trackingIssueId, tddEnabled);
 
 				if (!state || !state.slices || state.slices.length === 0) {
 					ctx.ui.notify("Failed to discover architecture components. Check .pi/architecture/modules/.", "error");
@@ -811,6 +834,15 @@ export default function (pi: ExtensionAPI) {
 					"3. Run `pipeline_run_acceptance` to validate your work",
 					"4. Call `pipeline_advance` to move to the next step",
 					"5. Pipeline auto-advances through: implement → validate → create-mr → merge",
+					tddEnabled ? [
+						"",
+						"**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.",
+						"- 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.",
+					].join("\n") : "",
 					"",
 					"---",
 					"",

package/templates/pi/preflight_report.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-07-12T07:37:47Z",
+  "timestamp": "2026-07-12T10:45:07Z",
   "mode": "all",
   "stages_run": [],
   "summary": {