guardian-framework 0.1.127 → 0.1.129

package/dist/cli.js

@@ -3202,7 +3202,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.127", 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.129", 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 = {
     ".": {
@@ -12178,6 +12178,60 @@ function answerExploration(sessionId, responseJson, options) {
     warnings
   };
 }
+function moduleHasImplementation(projectDir, moduleName) {
+  const sanitized = (moduleName || "").toLowerCase().replace(/[^a-z0-9]/g, "");
+  if (!sanitized)
+    return false;
+  const roots = ["src", "crates", "packages", "internal", "lib", "app", "modules"];
+  const exts = ".*.(java|kt|ts|tsx|js|jsx|rs|py|go)$";
+  for (const root of roots) {
+    const base = path2.join(projectDir, root);
+    if (!fs.existsSync(base))
+      continue;
+    try {
+      const walk = (dir, depth) => {
+        if (depth > 6)
+          return false;
+        let entries;
+        try {
+          entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+          return false;
+        }
+        for (const e of entries) {
+          if (e.name === "node_modules" || e.name === "target" || e.name === "dist" || e.name === ".git")
+            continue;
+          const full = path2.join(dir, e.name);
+          if (e.isDirectory()) {
+            if (e.name === sanitized && hasSourceBelow(full, depth))
+              return true;
+            if (walk(full, depth + 1))
+              return true;
+          }
+        }
+        return false;
+      };
+      const hasSourceBelow = (dir, depth) => {
+        let entries;
+        try {
+          entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+          return false;
+        }
+        for (const e of entries) {
+          if (e.isFile() && new RegExp(exts).test(e.name) && !/test|spec/i.test(e.name))
+            return true;
+          if (e.isDirectory() && e.name !== "node_modules" && e.name !== "target" && depth < 6 && hasSourceBelow(path2.join(dir, e.name), depth + 1))
+            return true;
+        }
+        return false;
+      };
+      if (walk(base, 0))
+        return true;
+    } catch {}
+  }
+  return false;
+}
 function readExplorationSession(sessionId, projectDir) {
   const root = projectDir ?? process.cwd();
   const filePath = path2.join(root, ".pi", "domain", "exploration", `${sessionId}.md`);
@@ -12376,8 +12430,18 @@ function scaffoldFromExploration(sessionId, options) {
     const depthHeaderNote = bc.subdomainType === undefined || bc.subdomainType === null ? " (unclassified \u2014 defaulted to tactical; re-run exploration with ADR-008 depth)" : "";
     const contextEdges = (result.contextMap || []).filter((e) => e.from === bc.name || e.to === bc.name);
     const invariants = bc.invariants || [];
+    const force = options?.overwrite === true;
     if (!dryRun && fs.existsSync(filePath)) {
-      warnings.push(`Module already exists, will be overwritten: ${fileName}`);
+      const implemented = moduleHasImplementation(projectDir, moduleName);
+      if (implemented && !force) {
+        warnings.push(`Module is IMPLEMENTED, preserved (use overwrite:true to force): ${fileName}`);
+        continue;
+      }
+      if (implemented && force) {
+        warnings.push(`Overwriting implemented module doc (--force): ${fileName}`);
+      } else {
+        warnings.push(`Refreshing planned module doc (no implementation yet): ${fileName}`);
+      }
     }
     const aggregateRoots = contextEntities.filter((e) => e.type === "aggregate-root");
     const regularEntities = contextEntities.filter((e) => e.type === "entity");
@@ -13150,7 +13214,7 @@ async function runDomain(targetDir, args, options) {
       await runExplore(targetDir, options);
       break;
     case "scaffold":
-      await runScaffold(targetDir, args[1], options);
+      await runScaffold(targetDir, args[1], { ...options, overwrite: args.includes("--force") });
       break;
     case "answer":
       await runAnswer(targetDir, args[1], args[2], options);
@@ -13257,7 +13321,8 @@ async function runScaffold(targetDir, sessionId, options) {
   try {
     const result = scaffoldFromExploration(sessionId, {
       projectDir: targetDir,
-      dryRun: options.dryRun
+      dryRun: options.dryRun,
+      overwrite: options.overwrite
     });
     if (options.dryRun) {
       outro(`Dry-run: would generate ${result.modulesGenerated} module(s)`);

package/dist/exports.js

@@ -1987,7 +1987,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.127", 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.129", 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 = {
     ".": {
@@ -12502,6 +12502,60 @@ function answerExploration(sessionId, responseJson, options) {
     warnings
   };
 }
+function moduleHasImplementation(projectDir, moduleName) {
+  const sanitized = (moduleName || "").toLowerCase().replace(/[^a-z0-9]/g, "");
+  if (!sanitized)
+    return false;
+  const roots = ["src", "crates", "packages", "internal", "lib", "app", "modules"];
+  const exts = ".*.(java|kt|ts|tsx|js|jsx|rs|py|go)$";
+  for (const root of roots) {
+    const base = path11.join(projectDir, root);
+    if (!fs12.existsSync(base))
+      continue;
+    try {
+      const walk = (dir, depth) => {
+        if (depth > 6)
+          return false;
+        let entries;
+        try {
+          entries = fs12.readdirSync(dir, { withFileTypes: true });
+        } catch {
+          return false;
+        }
+        for (const e of entries) {
+          if (e.name === "node_modules" || e.name === "target" || e.name === "dist" || e.name === ".git")
+            continue;
+          const full = path11.join(dir, e.name);
+          if (e.isDirectory()) {
+            if (e.name === sanitized && hasSourceBelow(full, depth))
+              return true;
+            if (walk(full, depth + 1))
+              return true;
+          }
+        }
+        return false;
+      };
+      const hasSourceBelow = (dir, depth) => {
+        let entries;
+        try {
+          entries = fs12.readdirSync(dir, { withFileTypes: true });
+        } catch {
+          return false;
+        }
+        for (const e of entries) {
+          if (e.isFile() && new RegExp(exts).test(e.name) && !/test|spec/i.test(e.name))
+            return true;
+          if (e.isDirectory() && e.name !== "node_modules" && e.name !== "target" && depth < 6 && hasSourceBelow(path11.join(dir, e.name), depth + 1))
+            return true;
+        }
+        return false;
+      };
+      if (walk(base, 0))
+        return true;
+    } catch {}
+  }
+  return false;
+}
 function readExplorationSession(sessionId, projectDir) {
   const root = projectDir ?? process.cwd();
   const filePath = path11.join(root, ".pi", "domain", "exploration", `${sessionId}.md`);
@@ -12700,8 +12754,18 @@ function scaffoldFromExploration(sessionId, options) {
     const depthHeaderNote = bc.subdomainType === undefined || bc.subdomainType === null ? " (unclassified — defaulted to tactical; re-run exploration with ADR-008 depth)" : "";
     const contextEdges = (result.contextMap || []).filter((e) => e.from === bc.name || e.to === bc.name);
     const invariants = bc.invariants || [];
+    const force = options?.overwrite === true;
     if (!dryRun && fs12.existsSync(filePath)) {
-      warnings.push(`Module already exists, will be overwritten: ${fileName}`);
+      const implemented = moduleHasImplementation(projectDir, moduleName);
+      if (implemented && !force) {
+        warnings.push(`Module is IMPLEMENTED, preserved (use overwrite:true to force): ${fileName}`);
+        continue;
+      }
+      if (implemented && force) {
+        warnings.push(`Overwriting implemented module doc (--force): ${fileName}`);
+      } else {
+        warnings.push(`Refreshing planned module doc (no implementation yet): ${fileName}`);
+      }
     }
     const aggregateRoots = contextEntities.filter((e) => e.type === "aggregate-root");
     const regularEntities = contextEntities.filter((e) => e.type === "entity");
@@ -13474,7 +13538,7 @@ async function runDomain(targetDir, args, options) {
       await runExplore(targetDir, options);
       break;
     case "scaffold":
-      await runScaffold(targetDir, args[1], options);
+      await runScaffold(targetDir, args[1], { ...options, overwrite: args.includes("--force") });
       break;
     case "answer":
       await runAnswer(targetDir, args[1], args[2], options);
@@ -13581,7 +13645,8 @@ async function runScaffold(targetDir, sessionId, options) {
   try {
     const result = scaffoldFromExploration(sessionId, {
       projectDir: targetDir,
-      dryRun: options.dryRun
+      dryRun: options.dryRun,
+      overwrite: options.overwrite
     });
     if (options.dryRun) {
       outro(`Dry-run: would generate ${result.modulesGenerated} module(s)`);

package/package.json

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

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

@@ -239,6 +239,45 @@ function mergeRawJson(existing: Record<string, unknown>, incoming: Record<string
 	return merged;
 }
 
+// True when a module has real implementation code (not just a planned doc).
+function moduleHasCode(cwd: string, moduleName: string): boolean {
+	const sanitized = (moduleName || "").toLowerCase().replace(/[^a-z0-9]/g, "");
+	if (!sanitized) return false;
+	const roots = ["src", "crates", "packages", "internal", "lib", "app", "modules"];
+	const codeFile = (n: string): boolean => /.*\.(java|kt|ts|tsx|js|jsx|rs|py|go)$/.test(n) && !/test|spec/i.test(n);
+	const walk = (dir: string, depth: number): boolean => {
+		if (depth > 6) return false;
+		let entries;
+		try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return false; }
+		for (const e of entries) {
+			if (["node_modules", "target", "dist", ".git"].includes(e.name)) continue;
+			const full = path.join(dir, e.name);
+			if (e.isFile() && codeFile(e.name)) return true;
+			if (e.isDirectory() && (e.name === sanitized || walk(full, depth + 1))) {
+				// entered the module dir: any code file below counts
+				if (e.name === sanitized && hasCodeBelow(full, depth)) return true;
+			}
+		}
+		return false;
+	};
+	const hasCodeBelow = (dir: string, depth: number): boolean => {
+		let entries;
+		try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return false; }
+		for (const e of entries) {
+			if (["node_modules", "target", "dist"].includes(e.name)) continue;
+			const full = path.join(dir, e.name);
+			if (e.isFile() && codeFile(e.name)) return true;
+			if (e.isDirectory() && depth < 6 && hasCodeBelow(full, depth + 1)) return true;
+		}
+		return false;
+	};
+	for (const r of roots) {
+		const base = path.join(cwd, r);
+		if (fs.existsSync(base) && walk(base, 0)) return true;
+	}
+	return false;
+}
+
 function buildExplorationPrompt(context: string): string {
 	return [
 		"You are a Domain-Driven Design expert. Analyze the following business",
@@ -978,10 +1017,12 @@ export default function (pi: ExtensionAPI) {
 			// /domain --architect-scaffold <session-id>
 			// /domain --architect-scaffold <session-id>
 			if (trimmed.startsWith("--architect-scaffold")) {
-				const sessionId = trimmed.slice("--architect-scaffold".length).trim();
+				const rest = trimmed.slice("--architect-scaffold".length).trim();
+				const forceScaffold = rest.includes("--force");
+				const sessionId = rest.split(/\s+/)[0] || "";
 				if (!sessionId) {
 					ctx.ui.notify(
-						"Usage: /domain --architect-scaffold <session-id>",
+						"Usage: /domain --architect-scaffold <session-id> [--force]",
 						"error",
 					);
 					return "(domain command handled)";
@@ -1056,7 +1097,7 @@ export default function (pi: ExtensionAPI) {
 				let scaffoldError = "";
 
 				try {
-					const cmd = "guardian-framework domain scaffold " + sessionId + " 2>&1";
+					const cmd = "guardian-framework domain scaffold " + sessionId + (forceScaffold ? " --force" : "") + " 2>&1";
 					const shellResult = await shellExec(ctx, cmd);
 					if (shellResult.exitCode === 0) {
 						const outputLines = shellResult.stdout.split("\n");
@@ -1079,8 +1120,13 @@ export default function (pi: ExtensionAPI) {
 					ctx.ui.notify("Module scaffold unavailable - agent can create docs directly", "info");
 				}
 
-				// Step 2: Always regenerate ADR-001 to reflect current session
+				// Step 2: Refresh ADR-001 only when it does not exist yet (or --force).
+				// Never clobber an existing ADR that documents implemented architecture.
 				const adrPath = path.join(decisionsDir, "ADR-001-architecture-pattern.md");
+				if (fs.existsSync(adrPath) && !forceScaffold) {
+					ctx.ui.notify("Existing ADR-001 preserved — module docs scaffolded (use --force to refresh ADR)", "info");
+					return "(domain command handled)";
+				}
 				const bcList = bcNames.length > 0
 				? bcNames.map(n => "  - " + n).join("\n")
 				: "  - (to be defined during architecture planning)";
@@ -1229,9 +1275,11 @@ export default function (pi: ExtensionAPI) {
 				return resultLines.join("\n");
 			}
 			if (trimmed.startsWith("--enrich")) {
-				const sessionId = trimmed.slice("--enrich".length).trim();
+				const restE = trimmed.slice("--enrich".length).trim();
+				const forceEnrich = restE.includes("--force");
+				const sessionId = restE.split(/\s+/)[0] || "";
 				if (!sessionId) {
-					ctx.ui.notify("Usage: /domain --enrich <session-id>", "error");
+					ctx.ui.notify("Usage: /domain --enrich <session-id> [--force]", "error");
 					return "(domain command handled)";
 				}
 
@@ -1244,9 +1292,47 @@ export default function (pi: ExtensionAPI) {
 					return "(domain command handled)";
 				}
 
-				const moduleFiles = fs.readdirSync(modulesDir).filter(f => f.endsWith(".md") && f !== "module-template.md");
+				// Enrichment is SESSION-SCOPED: only module docs that belong to THIS
+				// session's bounded contexts may be touched, and existing module docs
+				// are preserved unless --force. Prevents clobbering other streams.
+				const allModules = fs.readdirSync(modulesDir).filter(f => f.endsWith(".md") && f !== "module-template.md");
+				const kebab = (n: string) => n.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+				let sessionModules: string[] = [];
+				const sRawPath = path.join(explorationDir, sessionId + ".raw.json");
+				if (fs.existsSync(sRawPath)) {
+					try {
+						const rawS = JSON.parse(fs.readFileSync(sRawPath, "utf-8")) as Record<string, unknown>;
+						const bcs = Array.isArray(rawS.boundedContexts) ? (rawS.boundedContexts as Record<string, unknown>[]) : [];
+						sessionModules = bcs.map((bc) => kebab(String(bc.name ?? "")) + ".md").filter((n) => allModules.includes(n));
+					} catch { /* ignore */ }
+				}
+				if (sessionModules.length === 0) {
+					// fallback: session md bounded-contexts table
+					const md = fs.existsSync(sessionPath) ? fs.readFileSync(sessionPath, "utf-8") : "";
+					const m = md.match(/## Bounded Contexts[\s\S]*?\n((?:\|.*\n)+?)(?=\n##|$)/);
+					if (m) {
+						sessionModules = m[1].split("\n")
+							.map((l) => l.split("|").map((c) => c.trim()).filter(Boolean)[0])
+							.filter(Boolean)
+							.map((n) => kebab(n) + ".md")
+							.filter((n) => allModules.includes(n));
+					}
+				}
+				const preserved: string[] = [];
+				const moduleFiles = sessionModules.filter((f) => {
+					const exists = fs.existsSync(path.join(modulesDir, f));
+					const implemented = moduleHasCode(ctx.cwd, f.replace(/\.md$/, ""));
+					if (exists && implemented && !forceEnrich) {
+						preserved.push(f);
+						return false;
+					}
+					return true;
+				});
+				if (preserved.length > 0) {
+					ctx.ui.notify("Preserving existing module docs (use --force to enrich): " + preserved.join(", "), "info");
+				}
 				if (moduleFiles.length === 0) {
-					ctx.ui.notify("No module docs found. Run /domain --architect-scaffold " + sessionId + " first.", "error");
+					ctx.ui.notify("No new module docs for this session. Existing docs preserved — no enrich needed (or pass --force).", "error");
 					return "(domain command handled)";
 				}
 

package/templates/pi/preflight_report.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-09-06T11:35:20Z",
+  "timestamp": "2026-09-06T13:20:31Z",
   "mode": "all",
   "stages_run": [],
   "summary": {