guardian-framework 0.1.104 → 0.1.109

package/dist/exports.js

@@ -1894,7 +1894,12 @@ function getStoredHash(record) {
   return hash ? hash.replace("sha256:", "") : null;
 }
 function categorizeFile(relativePath) {
-  const userEditable = ["agent/AGENTS.md", "domain/", "architecture/CHANGELOG.md", "architecture/implementation-roadmap.md"];
+  const userEditable = [
+    "agent/AGENTS.md",
+    "domain/",
+    "architecture/CHANGELOG.md",
+    "architecture/implementation-roadmap.md"
+  ];
   if (userEditable.some((p2) => relativePath.includes(p2))) {
     return "user";
   }
@@ -1982,7 +1987,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.104", 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.109", 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 = {
     ".": {
@@ -11949,6 +11954,19 @@ function buildExplorationPrompt(context) {
   const sanitized = sanitizeBusinessContext(context);
   return `You are a Domain-Driven Design expert. Analyze the following business description and extract a structured domain model.
 
+Modeling judgment required (professional DDD practice):
+- Classify EVERY bounded context as a subdomain type: "core" (competitive advantage — full tactical modeling),
+  "supporting" (needed but not differentiating — simple services), or "generic" (off-the-shelf problem — buy/OSS,
+  never model). Add a one-sentence subdomainRationale for each.
+- For every entity/model entry decide entity vs value object vs aggregate root using the identity test:
+  does it have identity that persists across state changes? Is it immutable + equal by attributes? Record the
+  justification booleans, not just a label.
+- Capture per-context invariants: business rules that must always hold and the illegal state each prevents.
+- Triage EVERY event candidate with the 3-question test (domain expert cares? crosses an aggregate boundary?
+  needs audit trail?). Drop candidates failing all three — they are implementation details, not domain events.
+- Draw the context map between bounded contexts (partnership / shared-kernel / conformist / anticorruption-layer / open-host).
+- Record ubiquitous-language conflicts: terms used differently by different parts of the business.
+
 Business Context:
 ${sanitized}
 
@@ -11992,7 +12010,20 @@ Respond with ONLY valid JSON matching this exact structure. Do not include markd
     {
       "name": "ContextName",
       "description": "Brief description of this bounded context",
-      "entities": ["EntityName1", "EntityName2"]
+      "entities": ["EntityName1", "EntityName2"],
+      "subdomainType": "core|supporting|generic",
+      "subdomainRationale": "why this subdomain classification",
+      "invariants": [
+        { "rule": "business rule that must always hold", "illegalStatePrevented": "the illegal state this prevents" }
+      ]
+    }
+  ],
+  "contextMap": [
+    {
+      "from": "ContextName",
+      "to": "OtherContextName",
+      "relationship": "partnership|shared-kernel|conformist|anticorruption-layer|open-host",
+      "note": "how the two contexts relate"
     }
   ],
   "entities": [
@@ -12000,7 +12031,12 @@ Respond with ONLY valid JSON matching this exact structure. Do not include markd
       "name": "EntityName",
       "context": "ContextName",
       "type": "entity|value-object|aggregate-root",
-      "description": "What this entity represents"
+      "description": "What this entity represents",
+      "justification": {
+        "identityPersists": true,
+        "immutable": false,
+        "equalByState": false
+      }
     }
   ],
   "domainEvents": [
@@ -12008,7 +12044,12 @@ Respond with ONLY valid JSON matching this exact structure. Do not include markd
       "name": "EventName",
       "context": "ContextName",
       "description": "What happened",
-      "triggeredBy": "What caused this event"
+      "triggeredBy": "What caused this event",
+      "triage": {
+        "domainExpertCares": true,
+        "crossesAggregateBoundary": false,
+        "needsAudit": false
+      }
     }
   ],
   "ubiquitousLanguage": [
@@ -12017,7 +12058,10 @@ Respond with ONLY valid JSON matching this exact structure. Do not include markd
       "definition": "Clear definition",
       "boundedContext": "ContextName",
       "aliases": ["AlternativeName1"],
-      "examples": "Usage example"
+      "examples": "Usage example",
+      "conflicts": [
+        { "termA": "Term used one way", "termB": "Same term used differently", "whyConflicting": "why the meanings diverge" }
+      ]
     }
   ],
   "openQuestions": "Any open questions about the domain",
@@ -12153,19 +12197,24 @@ function parseExplorationResponse(rawResponse, sessionId) {
       boundedContexts: Array.isArray(parsed.boundedContexts) ? parsed.boundedContexts.map((bc) => ({
         name: coerceString(bc.name, "Unknown"),
         description: coerceString(bc.description, ""),
-        entities: Array.isArray(bc.entities) ? bc.entities.map(String) : []
+        entities: Array.isArray(bc.entities) ? bc.entities.map(String) : [],
+        subdomainType: coerceSubdomainType(bc.subdomainType),
+        subdomainRationale: coerceString(bc.subdomainRationale, ""),
+        invariants: coerceInvariants(bc.invariants)
       })) : [],
       entities: Array.isArray(parsed.entities) ? parsed.entities.map((e) => ({
         name: coerceString(e.name, "Unknown"),
         context: coerceString(e.context, ""),
         type: coerceEntityType(e.type),
-        description: coerceString(e.description, "")
+        description: coerceString(e.description, ""),
+        justification: coerceJustification(e.justification)
       })) : [],
       domainEvents: Array.isArray(parsed.domainEvents) ? parsed.domainEvents.map((ev) => ({
         name: coerceString(ev.name, "Unknown"),
         context: coerceString(ev.context, ""),
         description: coerceString(ev.description, ""),
-        triggeredBy: coerceString(ev.triggeredBy, "")
+        triggeredBy: coerceString(ev.triggeredBy, ""),
+        triage: coerceTriage(ev.triage)
       })) : [],
       functionalRequirements: Array.isArray(parsed.functionalRequirements) ? parsed.functionalRequirements.map((fr) => ({
         id: coerceString(fr.id, "FR-???"),
@@ -12189,10 +12238,21 @@ function parseExplorationResponse(rawResponse, sessionId) {
         definition: coerceString(t2.definition, ""),
         boundedContext: coerceString(t2.boundedContext, ""),
         aliases: Array.isArray(t2.aliases) ? t2.aliases.map(String) : [],
-        examples: coerceString(t2.examples, "")
+        examples: coerceString(t2.examples, ""),
+        conflicts: Array.isArray(t2.conflicts) ? t2.conflicts.map((c3) => ({
+          termA: coerceString(c3.termA, ""),
+          termB: coerceString(c3.termB, ""),
+          whyConflicting: coerceString(c3.whyConflicting, "")
+        })) : undefined
       })) : [],
       openQuestions: coerceString(parsed.openQuestions, ""),
-      aggregateRoots: coerceString(parsed.aggregateRoots, "")
+      aggregateRoots: coerceString(parsed.aggregateRoots, ""),
+      contextMap: Array.isArray(parsed.contextMap) ? parsed.contextMap.map((e) => ({
+        from: coerceString(e.from, ""),
+        to: coerceString(e.to, ""),
+        relationship: coerceContextRelationship(e.relationship),
+        note: coerceString(e.note, "")
+      })) : undefined
     };
     return { ok: true, value: result };
   } catch (err) {
@@ -12228,6 +12288,49 @@ function coerceEntityType(val) {
     return "app-shell";
   return "entity";
 }
+function coerceSubdomainType(val) {
+  if (val === "core")
+    return "core";
+  if (val === "supporting")
+    return "supporting";
+  if (val === "generic")
+    return "generic";
+  return;
+}
+function coerceInvariants(val) {
+  if (!Array.isArray(val))
+    return;
+  return val.map((i2) => ({
+    rule: coerceString(i2.rule, ""),
+    illegalStatePrevented: coerceString(i2.illegalStatePrevented, "")
+  }));
+}
+function coerceJustification(val) {
+  if (typeof val !== "object" || val === null)
+    return;
+  const j = val;
+  return {
+    identityPersists: Boolean(j.identityPersists),
+    immutable: Boolean(j.immutable),
+    equalByState: Boolean(j.equalByState)
+  };
+}
+function coerceTriage(val) {
+  if (typeof val !== "object" || val === null)
+    return;
+  const t2 = val;
+  return {
+    domainExpertCares: Boolean(t2.domainExpertCares),
+    crossesAggregateBoundary: Boolean(t2.crossesAggregateBoundary),
+    needsAudit: Boolean(t2.needsAudit)
+  };
+}
+function coerceContextRelationship(val) {
+  if (val === "partnership" || val === "shared-kernel" || val === "conformist" || val === "anticorruption-layer" || val === "open-host") {
+    return val;
+  }
+  return "anticorruption-layer";
+}
 function coerceFrPriority(val) {
   if (val === "critical")
     return "critical";
@@ -12370,6 +12473,14 @@ function answerExploration(sessionId, responseJson, options) {
 function readExplorationSession(sessionId, projectDir) {
   const root = projectDir ?? process.cwd();
   const filePath = path11.join(root, ".pi", "domain", "exploration", `${sessionId}.md`);
+  const rawPath = filePath.replace(/\.md$/, ".raw.json");
+  if (fs12.existsSync(rawPath)) {
+    try {
+      const parsed = JSON.parse(fs12.readFileSync(rawPath, "utf-8"));
+      if (parsed?.sessionId)
+        return parsed;
+    } catch {}
+  }
   if (!fs12.existsSync(filePath)) {
     return null;
   }
@@ -12553,6 +12664,10 @@ function scaffoldFromExploration(sessionId, options) {
     const contextEntities = entitiesByContext[bc.name] || [];
     const contextEvents = result.domainEvents.filter((ev) => ev.context === bc.name);
     const contextTerms = result.ubiquitousLanguage.filter((t2) => t2.boundedContext === bc.name);
+    const depth = bc.subdomainType === "core" ? "tactical" : bc.subdomainType === "generic" ? "adapter" : bc.subdomainType === "supporting" ? "service" : "unclassified";
+    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 || [];
     if (!dryRun && fs12.existsSync(filePath)) {
       warnings.push(`Module already exists, will be overwritten: ${fileName}`);
     }
@@ -12809,6 +12924,17 @@ None yet
 
 ${bc.description}
 
+`;
+      content += `
+`;
+      content += "**Modeling Depth:** ";
+      content += depth === "tactical" ? "tactical (core domain)" : depth === "service" ? "service (supporting subdomain)" : depth === "adapter" ? "adapter (generic subdomain)" : "unclassified";
+      content += `${depthHeaderNote}
+`;
+      content += `**Subdomain Rationale:** ${bc.subdomainRationale || "—"}
+`;
+      const edgeSummary = contextEdges.map((e) => (e.from === bc.name ? `${e.relationship} → ${e.to}` : `${e.from} → ${e.relationship}`) + (e.note ? ` (${e.note})` : "")).join("; ");
+      content += `**Context Map:** ${edgeSummary || "—"}
 `;
       content += `
 `;
@@ -12889,15 +13015,22 @@ ${bc.description}
           content += "```";
           content += `
 `;
-          if (ownedEntities.length > 0 || ownedVOs.length > 0) {
+          if (ownedEntities.length > 0 || ownedVOs.length > 0 || invariants.length > 0) {
             content += `**Aggregate Invariants:**
 `;
-            content += `- All operations go through ${ar.name} aggregate root
+            if (invariants.length > 0) {
+              for (const inv of invariants) {
+                content += `- ${inv.rule} (prevents: ${inv.illegalStatePrevented})
+`;
+              }
+            } else {
+              content += `- All operations go through ${ar.name} aggregate root
 `;
-            content += `- References to child entities resolve through ${ar.name}
+              content += `- References to child entities resolve through ${ar.name}
 `;
-            content += `- ${ar.name}Id is the sole external identifier
+              content += `- ${ar.name}Id is the sole external identifier
 `;
+            }
             content += `
 `;
           }
@@ -12983,6 +13116,38 @@ ${bc.description}
 `;
       content += `
 `;
+      if (depth === "service" || depth === "adapter") {
+        content += `## Modeling Depth Note (ADR-008)
+`;
+        content += `
+`;
+        if (depth === "service") {
+          content += `This bounded context is a **supporting subdomain** — model at service/CRUD depth.
+`;
+          content += `Keep implementation to application services + persistence. Do NOT introduce new
+`;
+          content += `aggregates, value objects, or domain events beyond what this exploration captured.
+`;
+        } else {
+          content += `This bounded context is a **generic subdomain** — model at adapter depth.
+`;
+          content += `Integrate an off-the-shelf / vendor / OSS solution behind an anti-corruption layer.
+`;
+          content += `Do NOT write domain entities or aggregates here.
+`;
+        }
+        if (contextEdges.length > 0) {
+          content += `
+**Anti-corruption edges:**
+`;
+          for (const e of contextEdges) {
+            content += `- ${e.from} ${e.relationship} ${e.to} — ${e.note || "—"}
+`;
+          }
+        }
+        content += `
+`;
+      }
       content += `## Acceptance Criteria
 `;
       content += `
@@ -13040,6 +13205,11 @@ function loadExplorationTemplate() {
   }
   throw new Error("Exploration template not found in templates/pi/domain/exploration.md");
 }
+function indentBlock(text2, indent = "    ") {
+  return text2.split(`
+`).map((ln) => ln.length > 0 ? indent + ln : ln).join(`
+`);
+}
 function renderExplorationTemplate(result) {
   const template = loadExplorationTemplate();
   const actorsTable = result.actors.map((a2) => "| ${a.name} | ${a.description} | ${a.interactions} |").join(`
@@ -13058,9 +13228,51 @@ function renderExplorationTemplate(result) {
 `);
   const ubiquitousLanguageTable = result.ubiquitousLanguage.map((t2) => `| ${t2.term} | ${t2.definition} | ${t2.boundedContext} | ${t2.aliases.join(", ")} |`).join(`
 `);
+  const subdomainRows = result.boundedContexts.filter((bc) => bc.subdomainType || bc.invariants?.length).map((bc) => {
+    const inv = (bc.invariants || []).map((i2) => `- ${i2.rule} (prevents: ${i2.illegalStatePrevented})`).join(`
+`) || "—";
+    return `### ${bc.name}
+- **Subdomain:** ${bc.subdomainType ?? "unclassified"} — ${bc.subdomainRationale ?? ""}
+- **Invariants:**
+${indentBlock(inv)}`;
+  }).join(`
+
+`);
+  const contextMapRows = (result.contextMap || []).map((e) => `| ${e.from} | ${e.to} | ${e.relationship} | ${e.note} |`).join(`
+`);
+  const eventTriageRows = result.domainEvents.filter((ev) => ev.triage).map((ev) => `| ${ev.name} | ${ev.triage.domainExpertCares ? "yes" : "no"} | ${ev.triage.crossesAggregateBoundary ? "yes" : "no"} | ${ev.triage.needsAudit ? "yes" : "no"} |`).join(`
+`);
+  const ulConflictRows = result.ubiquitousLanguage.flatMap((t2) => (t2.conflicts || []).map((c3) => `| ${c3.termA} | ${c3.termB} | ${c3.whyConflicting} |`)).join(`
+`);
+  const modelingParts = [];
+  if (subdomainRows) {
+    modelingParts.push(`### Subdomain Classification & Invariants
+${subdomainRows}`);
+  }
+  if (contextMapRows) {
+    modelingParts.push(`### Context Map
+| From | To | Relationship | Note |
+|-----|----|--------------|------|
+${contextMapRows}`);
+  }
+  if (eventTriageRows) {
+    modelingParts.push(`### Domain Event Triage
+| Event | Domain expert cares | Crosses aggregate boundary | Needs audit trail |
+|-------|---------------------|---------------------------|-------------------|
+${eventTriageRows}`);
+  }
+  if (ulConflictRows) {
+    modelingParts.push(`### Ubiquitous Language Conflicts
+| Term A | Term B | Why conflicting |
+|--------|--------|-----------------|
+${ulConflictRows}`);
+  }
+  const modelingJudgmentSection = modelingParts.length > 0 ? modelingParts.join(`
+
+`) : "None captured yet.";
   const aggregateRoots = result.aggregateRoots ? result.aggregateRoots : "None identified yet.";
   const openQuestions = result.openQuestions ? result.openQuestions : "No open questions.";
-  return template.replaceAll("{{SESSION_ID}}", result.sessionId).replaceAll("{{CREATED_DATE}}", new Date().toISOString().split("T")[0]).replaceAll("{{BUSINESS_CONTEXT}}", escapePlaceholder(result.businessContext)).replaceAll("{{STATUS}}", result.status).replaceAll("{{ACTORS_TABLE}}", actorsTable || "None identified yet.").replaceAll("{{FUNCTIONAL_REQUIREMENTS_TABLE}}", functionalRequirementsTable || "None identified yet.").replaceAll("{{NON_FUNCTIONAL_REQUIREMENTS_TABLE}}", nonFunctionalRequirementsTable || "None identified yet.").replaceAll("{{ASSUMPTIONS_TABLE}}", assumptionsTable || "None identified yet.").replaceAll("{{BOUNDED_CONTEXTS_TABLE}}", boundedContextsTable || "None identified yet.").replaceAll("{{ENTITIES_TABLE}}", entitiesTable || "None identified yet.").replaceAll("{{DOMAIN_EVENTS_TABLE}}", domainEventsTable || "None identified yet.").replaceAll("{{UBIQUITOUS_LANGUAGE_TABLE}}", ubiquitousLanguageTable || "None identified yet.").replaceAll("{{OPEN_QUESTIONS}}", openQuestions).replaceAll("{{AGGREGATE_ROOTS}}", aggregateRoots);
+  return template.replaceAll("{{SESSION_ID}}", result.sessionId).replaceAll("{{CREATED_DATE}}", new Date().toISOString().split("T")[0]).replaceAll("{{BUSINESS_CONTEXT}}", escapePlaceholder(result.businessContext)).replaceAll("{{STATUS}}", result.status).replaceAll("{{ACTORS_TABLE}}", actorsTable || "None identified yet.").replaceAll("{{FUNCTIONAL_REQUIREMENTS_TABLE}}", functionalRequirementsTable || "None identified yet.").replaceAll("{{NON_FUNCTIONAL_REQUIREMENTS_TABLE}}", nonFunctionalRequirementsTable || "None identified yet.").replaceAll("{{ASSUMPTIONS_TABLE}}", assumptionsTable || "None identified yet.").replaceAll("{{BOUNDED_CONTEXTS_TABLE}}", boundedContextsTable || "None identified yet.").replaceAll("{{ENTITIES_TABLE}}", entitiesTable || "None identified yet.").replaceAll("{{DOMAIN_EVENTS_TABLE}}", domainEventsTable || "None identified yet.").replaceAll("{{UBIQUITOUS_LANGUAGE_TABLE}}", ubiquitousLanguageTable || "None identified yet.").replaceAll("{{OPEN_QUESTIONS}}", openQuestions).replaceAll("{{AGGREGATE_ROOTS}}", aggregateRoots).replaceAll("{{MODELING_JUDGMENT_SECTION}}", modelingJudgmentSection);
 }
 function escapePlaceholder(value) {
   return value.replace(/"/g, "\\\"").replace(/\n/g, "\\n");
@@ -13215,6 +13427,10 @@ ${content}`;
   const tempPath = `${outputPath}.tmp`;
   fs12.writeFileSync(tempPath, content, "utf-8");
   fs12.renameSync(tempPath, outputPath);
+  const rawPath = `${outputPath.replace(/\.md$/, "")}.raw.json`;
+  const rawTemp = `${rawPath}.tmp`;
+  fs12.writeFileSync(rawTemp, JSON.stringify(result, null, 2), "utf-8");
+  fs12.renameSync(rawTemp, rawPath);
   return outputPath;
 }
 

package/package.json

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

package/templates/languages/rust-patterns.md

@@ -211,8 +211,11 @@ cargo fmt --check
 # Security audit
 cargo audit
 
-# Coverage
-cargo tarpaulin --out Html
+# Coverage (real line coverage via cargo-llvm-cov — native LLVM
+# instrumentation, ~3x faster than tarpaulin). Install once:
+#   bash .pi/scripts/install_coverage_tools.sh
+# Gate in CI:  bash .pi/scripts/coverage.sh --gate --lcov
+cargo llvm-cov --workspace --summary-only
 ```
 
 ---

package/templates/pi/context/checklists.md

@@ -23,6 +23,20 @@
 - [ ] E2E tests pass
 - [ ] Architecture contract tests pass
 
+
+### Model Judgment (Java, ADR-008) — hard gates
+- [ ] txn-placement: @Transactional only in application/ (never domain/infrastructure/interfaces)
+- [ ] dip-domain: domain/ imports no jakarta.persistence/javax.persistence/springframework/hibernate
+- [ ] interface-ownership (tactical modules): every infrastructure/ repository has a domain/-owned interface
+- [ ] adapter-purity: generic-subdomain modules contain no domain/application model code
+
+### Model Judgment (Java, ADR-008) — review questions (validator agent, warn-level)
+- [ ] R1 anemic-model: app-service if/getStatus/setX chains on domain refs (grep evidence)
+- [ ] R2 LSP: domain entity extends a non-abstract base class
+- [ ] R3 cohesion: Helper/Utils/Manager/Orchestrator classes in domain/
+- [ ] R4 primitive obsession: >2 raw primitives on domain service signatures
+- [ ] R5 production-reachability (ADR-009): implemented application services have a production caller outside their module and outside tests (validate-runtime-wiring.sh)
+
 ## Security Validation
 
 ### All Code Changes
@@ -56,7 +70,7 @@
 
 ### Coverage
 - [ ] All tests pass
-- [ ] Coverage ≥ 80%
+- [ ] Coverage meets the project's real coverage gate (run the project's coverage tool / CI coverage job — no per-module heuristic *_coverage.sh)
 - [ ] All new code has tests
 - [ ] Tests follow AAA pattern (Arrange-Act-Assert)
 

package/templates/pi/domain/exploration.md

@@ -91,3 +91,12 @@ status: {{STATUS}}
 ## Aggregate Roots
 
 {{AGGREGATE_ROOTS}}
+---
+
+## Modeling Judgment (ADR-008)
+
+Subdomain classification (core/supporting/generic), aggregate invariants,
+context map, domain-event triage, and ubiquitous-language conflicts.
+
+{{MODELING_JUDGMENT_SECTION}}
+

package/templates/pi/domain/ubiquitous-language.md

@@ -22,3 +22,15 @@
 
 > **Rule of thumb:** If two agents use different names for the same concept, add an entry.
 > The canonical term is the one used in the architecture module documents.
+
+## Term Conflicts (language gaps)
+
+When the same term is used with different meanings by different parts of the
+business (e.g. "transaction" = a database transaction for engineers but a
+statement line for the business), that is a bounded-context boundary signal —
+record the conflict here and resolve it in the exploration review:
+
+| Term A | Term B | Why conflicting | Resolution |
+|--------|--------|-----------------|-----------|
+| <!-- e.g. Transaction | Booking | engineering vs business meaning | adopt "Booking" in Billing context --> |
+