guardian-framework 0.1.27 → 0.1.29

package/README.md

@@ -35,6 +35,9 @@ Domain Exploration     ←─ you and the agent explore, iterate, refine
 Architecture Modules   ←─ you review, adjust, approve
     │
     ▼
+Enrich Module Docs     ←─ agent fills DDD content from exploration
+    │
+    ▼
 ADRs, Diagrams, Specs  ←─ you challenge decisions, finalize
     │
     ▼
@@ -75,15 +78,49 @@ You go back and forth until the model reflects your actual business. Only then d
 /domain --architect-scaffold <session-id>
 ```
 
-Guardian generates one architecture module per bounded context, with components, dependencies, and contract interfaces:
+Guardian generates one architecture module per bounded context, with architecture layers, aggregates, repository contracts, and domain events:
 
 ```markdown
 # Audit Ingestion
 
-## HMAC Signature Verifier
-status: planned
-description: Verifies HMAC-SHA256 signatures on incoming audit records.
-depends: none
+## Architecture
+| Layer | Responsibility |
+|-------|--------------|
+| **Domain** | Aggregates, entities, repository interfaces | src/audit-ingestion/domain/ |
+| **Application** | Use cases, DTOs | src/audit-ingestion/application/ |
+
+## Aggregates
+### AuditRecord
+**Repository Interface:**
+```rust
+pub trait AuditRecordRepository: Send + Sync {
+    async fn find_by_id(&self, id: &AuditRecordId) -> Result<Option<AuditRecord>, DomainError>;
+    async fn save(&self, entity: &AuditRecord) -> Result<(), DomainError>;
+    async fn delete(&self, id: &AuditRecordId) -> Result<(), DomainError>;
+}
+```
+
+## Domain Events
+| Event | Description | Trigger |
+|-------|-------------|--------|
+| AuditRecordIngested | ... | ... |
+```
+
+### 3.5 Enrich with Full DDD Content
+
+```
+/domain --enrich <session-id>
+```
+
+The agent reads the domain exploration and enhances each module stub with:
+- Mermaid data flow diagrams
+- Real Rust struct stubs
+- API endpoint tables
+- Ubiquitous Language per context
+- Cross-context dependencies
+- Security considerations
+
+This produces production-quality architecture docs (5–20 KB each) that an implementer can build from directly.
 
 ## Idempotency Handler
 status: planned
@@ -162,9 +199,12 @@ npx guardian-framework init
 # 3. Generate architecture from exploration
 /domain --architect-scaffold <session-id>
 
-# 4. Review and refine (ADRs, diagrams, modules — human-in-the-loop)
+# 4. Enrich module docs with full DDD content
+/domain --enrich <session-id>
+
+# 5. Review and refine (ADRs, diagrams, modules — human-in-the-loop)
 
-# 5. Adopt the roadmap
+# 6. Adopt the roadmap
 /architect --roadmap
 /architect --adopt-roadmap
 

package/dist/cli.js

@@ -1335,7 +1335,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.27", 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.29", 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 = {
     ".": {
@@ -10011,6 +10011,10 @@ function coerceEntityType(val) {
     return "value-object";
   if (val === "aggregate-root")
     return "aggregate-root";
+  if (val === "Aggregate Root")
+    return "aggregate-root";
+  if (val === "Value Object")
+    return "value-object";
   if (val === "ui-concept")
     return "ui-concept";
   if (val === "user-intent")
@@ -10250,6 +10254,9 @@ function readExplorationSession(sessionId, projectDir) {
     aggregateRoots
   };
 }
+function stripMarkdown(text) {
+  return text.replace(/\*\*(.+?)\*\*/g, "$1").replace(/\*(.+?)\*/g, "$1").replace(/~~(.+?)~~/g, "$1").replace(/`(.+?)`/g, "$1").replace(/\[(.+?)\]\(.+?\)/g, "$1").trim();
+}
 function extractTable(body, sectionName) {
   const sectionRegex = new RegExp(`## ${sectionName}\\n+([\\s\\S]*?)(?:\\n##|$)`);
   const sectionMatch = body.match(sectionRegex);
@@ -10263,7 +10270,7 @@ function extractTable(body, sectionName) {
     const trimmed = line.trim();
     const content = trimmed.startsWith("|") ? trimmed.slice(1) : trimmed;
     const withoutTrailing = content.endsWith("|") ? content.slice(0, -1) : content;
-    return withoutTrailing.split("|").map((s) => s.trim());
+    return withoutTrailing.split("|").map((s) => stripMarkdown(s.trim()));
   });
 }
 function scaffoldFromExploration(sessionId, options) {
@@ -10564,11 +10571,12 @@ None yet
 
 `;
     } else {
-      content = `# ${bc.name}
+      content += `# ${bc.name}
 
 `;
       content += `## Module Status
-
+`;
+      content += `
 `;
       content += `**Status:** Planned
 `;
@@ -10582,57 +10590,186 @@ None yet
 ${bc.description}
 
 `;
-      content += `## Components
+      content += `
+`;
+      content += `## Architecture
+`;
+      content += `
+`;
+      content += `This module follows **Domain-Driven Design** with Clean Architecture layers:
+`;
+      content += `
+`;
+      content += `| Layer | Responsibility |
+`;
+      content += `|-------|--------------|
+`;
+      content += `| **Domain** | Aggregates, entities, value objects, domain services, repository interfaces | src/${moduleName}/domain/ |
+`;
+      content += `| **Application** | Use cases / application services, DTOs, input validation | src/${moduleName}/application/ |
+`;
+      content += `| **Infrastructure** | Repository implementations, DB models, external clients | src/${moduleName}/infrastructure/ |
+`;
+      content += `| **Interfaces** | API handlers, event subscribers, serialization | src/${moduleName}/interfaces/ |
+`;
+      content += `
+`;
+      content += `## Aggregates
+`;
+      content += `
+`;
+      if (aggregateRoots.length > 0) {
+        for (const ar of aggregateRoots) {
+          content += `### ${ar.name}
 
-${componentsSection}
+`;
+          content += ar.description === "" ? "_No description._" : ar.description;
+          content += `
+`;
+          const ownedEntities = regularEntities.filter((e2) => e2.description.includes(ar.name) || ar.description.includes(e2.name));
+          const ownedVOs = valueObjects.filter((vo) => vo.description.includes(ar.name) || ar.description.includes(vo.name));
+          content += `
+`;
+          if (ownedEntities.length > 0) {
+            content += `**Owned Entities:**
+`;
+            for (const ent of ownedEntities) {
+              content += `- ${ent.name}: ${ent.description}
+`;
+            }
+            content += `
+`;
+          }
+          if (ownedVOs.length > 0) {
+            content += `**Value Objects:**
+`;
+            for (const vo of ownedVOs) {
+              content += `- ${vo.name}: ${vo.description}
+`;
+            }
+            content += `
+`;
+          }
+          const arVarName = ar.name.charAt(0).toLowerCase() + ar.name.slice(1);
+          content += `**Repository Interface:**
+`;
+          content += `
+`;
+          content += "```rust\n";
+          content += `pub trait ${ar.name}Repository: Send + Sync {
+`;
+          content += `    async fn find_by_id(&self, id: &${ar.name}Id) -> Result<Option<${ar.name}>, DomainError>;
+`;
+          content += `    async fn save(&self, ${arVarName}: &${ar.name}) -> Result<(), DomainError>;
+`;
+          content += `    async fn delete(&self, id: &${ar.name}Id) -> Result<(), DomainError>;
+`;
+          content += `}
+`;
+          content += "```";
+          content += `
+`;
+          if (ownedEntities.length > 0 || ownedVOs.length > 0) {
+            content += `**Aggregate Invariants:**
+`;
+            content += `- All operations go through ${ar.name} aggregate root
+`;
+            content += `- References to child entities resolve through ${ar.name}
+`;
+            content += `- ${ar.name}Id is the sole external identifier
+`;
+            content += `
+`;
+          }
+        }
+      } else {
+        content += `No aggregates defined yet.
+`;
+        content += `
+`;
+      }
+      content += `
 `;
       content += `## Domain Events
-
+`;
+      content += `
 `;
       if (contextEvents.length === 0) {
         content += `None defined yet.
-
+`;
+        content += `
 `;
       } else {
+        content += `| Event | Description | Trigger |
+`;
+        content += `|-------|-------------|--------|
+`;
         for (const ev of contextEvents) {
-          content += `- **${ev.name}** - ${ev.description} (triggered by: ${ev.triggeredBy})
+          content += `| ${ev.name} | ${ev.description} | ${ev.triggeredBy} |
 `;
         }
         content += `
 `;
       }
+      content += `
+`;
       content += `## Ubiquitous Language
-
 `;
-      if (contextTerms.length === 0) {
-        content += `None defined yet.
-
+      content += `
 `;
+      if (contextTerms.length === 0) {
+        content += "See `.pi/domain/ubiquitous-language.md` for full glossary.\n\n";
       } else {
-        content += `| Term | Definition | Aliases |
+        content += `| Term | Definition |
 `;
-        content += `|------|-----------|---------|
+        content += `|------|-----------|
 `;
         for (const t of contextTerms) {
-          content += `| ${t.term} | ${t.definition} | ${t.aliases.join(", ")} |
+          content += `| ${t.term} | ${t.definition} |
 `;
         }
         content += `
 `;
       }
+      content += `
+`;
       content += `## Dependencies
-
-${depsSection}
 `;
-      content += `## Key Files
-
-None yet
-
+      content += `
+`;
+      content += `${depsSection}
+`;
+      content += `
+`;
+      content += `## Implementation Notes
+`;
+      content += `
+`;
+      content += `Implementation should follow Rust DDD + Clean Architecture patterns:
+`;
+      content += `
+`;
+      content += `1. Domain layer: aggregates, entities, value objects, repository interfaces
+`;
+      content += `2. Infrastructure: Postgres repository implementations via SQLx
+`;
+      content += `3. Application: use case orchestration
+`;
+      content += `4. Interfaces: HTTP handlers with Axum
+`;
+      content += `
+`;
+      content += `Each layer MUST NOT leak into adjacent layers.
+`;
+      content += `
 `;
       content += `## ADRs
-
-None yet
-
+`;
+      content += `
+`;
+      content += `None yet
+`;
+      content += `
 `;
     }
     if (!dryRun) {

package/dist/exports.js

@@ -995,7 +995,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.27", 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.29", 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 = {
     ".": {
@@ -11212,6 +11212,10 @@ function coerceEntityType(val) {
     return "value-object";
   if (val === "aggregate-root")
     return "aggregate-root";
+  if (val === "Aggregate Root")
+    return "aggregate-root";
+  if (val === "Value Object")
+    return "value-object";
   if (val === "ui-concept")
     return "ui-concept";
   if (val === "user-intent")
@@ -11451,6 +11455,9 @@ function readExplorationSession(sessionId, projectDir) {
     aggregateRoots
   };
 }
+function stripMarkdown(text) {
+  return text.replace(/\*\*(.+?)\*\*/g, "$1").replace(/\*(.+?)\*/g, "$1").replace(/~~(.+?)~~/g, "$1").replace(/`(.+?)`/g, "$1").replace(/\[(.+?)\]\(.+?\)/g, "$1").trim();
+}
 function extractTable(body, sectionName) {
   const sectionRegex = new RegExp(`## ${sectionName}\\n+([\\s\\S]*?)(?:\\n##|$)`);
   const sectionMatch = body.match(sectionRegex);
@@ -11464,7 +11471,7 @@ function extractTable(body, sectionName) {
     const trimmed = line.trim();
     const content = trimmed.startsWith("|") ? trimmed.slice(1) : trimmed;
     const withoutTrailing = content.endsWith("|") ? content.slice(0, -1) : content;
-    return withoutTrailing.split("|").map((s) => s.trim());
+    return withoutTrailing.split("|").map((s) => stripMarkdown(s.trim()));
   });
 }
 function scaffoldFromExploration(sessionId, options) {
@@ -11765,11 +11772,12 @@ None yet
 
 `;
     } else {
-      content = `# ${bc.name}
+      content += `# ${bc.name}
 
 `;
       content += `## Module Status
-
+`;
+      content += `
 `;
       content += `**Status:** Planned
 `;
@@ -11783,57 +11791,186 @@ None yet
 ${bc.description}
 
 `;
-      content += `## Components
+      content += `
+`;
+      content += `## Architecture
+`;
+      content += `
+`;
+      content += `This module follows **Domain-Driven Design** with Clean Architecture layers:
+`;
+      content += `
+`;
+      content += `| Layer | Responsibility |
+`;
+      content += `|-------|--------------|
+`;
+      content += `| **Domain** | Aggregates, entities, value objects, domain services, repository interfaces | src/${moduleName}/domain/ |
+`;
+      content += `| **Application** | Use cases / application services, DTOs, input validation | src/${moduleName}/application/ |
+`;
+      content += `| **Infrastructure** | Repository implementations, DB models, external clients | src/${moduleName}/infrastructure/ |
+`;
+      content += `| **Interfaces** | API handlers, event subscribers, serialization | src/${moduleName}/interfaces/ |
+`;
+      content += `
+`;
+      content += `## Aggregates
+`;
+      content += `
+`;
+      if (aggregateRoots.length > 0) {
+        for (const ar of aggregateRoots) {
+          content += `### ${ar.name}
 
-${componentsSection}
+`;
+          content += ar.description === "" ? "_No description._" : ar.description;
+          content += `
+`;
+          const ownedEntities = regularEntities.filter((e2) => e2.description.includes(ar.name) || ar.description.includes(e2.name));
+          const ownedVOs = valueObjects.filter((vo) => vo.description.includes(ar.name) || ar.description.includes(vo.name));
+          content += `
+`;
+          if (ownedEntities.length > 0) {
+            content += `**Owned Entities:**
+`;
+            for (const ent of ownedEntities) {
+              content += `- ${ent.name}: ${ent.description}
+`;
+            }
+            content += `
+`;
+          }
+          if (ownedVOs.length > 0) {
+            content += `**Value Objects:**
+`;
+            for (const vo of ownedVOs) {
+              content += `- ${vo.name}: ${vo.description}
+`;
+            }
+            content += `
+`;
+          }
+          const arVarName = ar.name.charAt(0).toLowerCase() + ar.name.slice(1);
+          content += `**Repository Interface:**
+`;
+          content += `
+`;
+          content += "```rust\n";
+          content += `pub trait ${ar.name}Repository: Send + Sync {
+`;
+          content += `    async fn find_by_id(&self, id: &${ar.name}Id) -> Result<Option<${ar.name}>, DomainError>;
+`;
+          content += `    async fn save(&self, ${arVarName}: &${ar.name}) -> Result<(), DomainError>;
+`;
+          content += `    async fn delete(&self, id: &${ar.name}Id) -> Result<(), DomainError>;
+`;
+          content += `}
+`;
+          content += "```";
+          content += `
+`;
+          if (ownedEntities.length > 0 || ownedVOs.length > 0) {
+            content += `**Aggregate Invariants:**
+`;
+            content += `- All operations go through ${ar.name} aggregate root
+`;
+            content += `- References to child entities resolve through ${ar.name}
+`;
+            content += `- ${ar.name}Id is the sole external identifier
+`;
+            content += `
+`;
+          }
+        }
+      } else {
+        content += `No aggregates defined yet.
+`;
+        content += `
+`;
+      }
+      content += `
 `;
       content += `## Domain Events
-
+`;
+      content += `
 `;
       if (contextEvents.length === 0) {
         content += `None defined yet.
-
+`;
+        content += `
 `;
       } else {
+        content += `| Event | Description | Trigger |
+`;
+        content += `|-------|-------------|--------|
+`;
         for (const ev of contextEvents) {
-          content += `- **${ev.name}** - ${ev.description} (triggered by: ${ev.triggeredBy})
+          content += `| ${ev.name} | ${ev.description} | ${ev.triggeredBy} |
 `;
         }
         content += `
 `;
       }
+      content += `
+`;
       content += `## Ubiquitous Language
-
 `;
-      if (contextTerms.length === 0) {
-        content += `None defined yet.
-
+      content += `
 `;
+      if (contextTerms.length === 0) {
+        content += "See `.pi/domain/ubiquitous-language.md` for full glossary.\n\n";
       } else {
-        content += `| Term | Definition | Aliases |
+        content += `| Term | Definition |
 `;
-        content += `|------|-----------|---------|
+        content += `|------|-----------|
 `;
         for (const t of contextTerms) {
-          content += `| ${t.term} | ${t.definition} | ${t.aliases.join(", ")} |
+          content += `| ${t.term} | ${t.definition} |
 `;
         }
         content += `
 `;
       }
+      content += `
+`;
       content += `## Dependencies
-
-${depsSection}
 `;
-      content += `## Key Files
-
-None yet
-
+      content += `
+`;
+      content += `${depsSection}
+`;
+      content += `
+`;
+      content += `## Implementation Notes
+`;
+      content += `
+`;
+      content += `Implementation should follow Rust DDD + Clean Architecture patterns:
+`;
+      content += `
+`;
+      content += `1. Domain layer: aggregates, entities, value objects, repository interfaces
+`;
+      content += `2. Infrastructure: Postgres repository implementations via SQLx
+`;
+      content += `3. Application: use case orchestration
+`;
+      content += `4. Interfaces: HTTP handlers with Axum
+`;
+      content += `
+`;
+      content += `Each layer MUST NOT leak into adjacent layers.
+`;
+      content += `
 `;
       content += `## ADRs
-
-None yet
-
+`;
+      content += `
+`;
+      content += `None yet
+`;
+      content += `
 `;
     }
     if (!dryRun) {

package/package.json

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

package/templates/pi/extensions/pipeline.ts

@@ -456,6 +456,35 @@ class PipelineManager {
 
 			if (this.state.currentItemIndex >= this.state.items.length) {
 				this.state.status = "done";
+
+				// Auto-advance roadmap when module epic completes
+				const roadmapFile = join(this.cwd, ".pi/.guardian-roadmap-state.json");
+				if (existsSync(roadmapFile)) {
+					try {
+						const roadmap = JSON.parse(readFileSync(roadmapFile, "utf-8"));
+						const epicName = this.state.name;
+						const currentPhase = roadmap.phases?.[roadmap.currentPhaseIndex];
+						if (currentPhase && epicName) {
+							// Mark module as completed
+							const completed = new Set(currentPhase.completedModules || []);
+							completed.add(epicName);
+							currentPhase.completedModules = Array.from(completed);
+
+							// Check if all modules done → mark phase done
+							const allDone = currentPhase.modules.every(
+								(m: { name: string }) => completed.has(m.name),
+							);
+							if (allDone) {
+								currentPhase.status = "done";
+							}
+
+							roadmap.updatedAt = new Date().toISOString();
+							writeFileSync(roadmapFile, JSON.stringify(roadmap, null, 2));
+						}
+					} catch (err) {
+						// Silently fail — roadmap update is best-effort
+					}
+				}
 			}
 		}
 

package/templates/pi/preflight_report.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-07-03T11:06:29Z",
+  "timestamp": "2026-07-03T18:18:02Z",
   "mode": "all",
   "stages_run": [],
   "summary": {