guardian-framework 0.1.104 → 0.1.109

package/README.md

@@ -72,6 +72,14 @@ Guardian analyzes your intent and produces a structured domain model. But this i
 
 You go back and forth until the model reflects your actual business. Only then do you proceed.
 
+Guardian now applies **proportional modeling depth** (ADR-008): every bounded
+context is classified **core / supporting / generic** — the LLM proposes it,
+you gate it — and must justify entity-vs-VO calls, capture aggregate
+invariants, triage domain events, and draw the context map. Core subdomains
+get full tactical DDD; generic subdomains get an anti-corruption layer, not a
+hand-built model. Depth flows through module docs, contracts and validators
+end-to-end. See the user manual §29.
+
 ### 3. Scaffold Architecture Modules
 
 ```
@@ -204,9 +212,10 @@ cd your-project
 npx guardian-framework init
 
 # 2. Explore (iterative — review, refine, repeat)
-/domain --explore "your business intent"
+/domain --explore "your business intent"   # agent classifies core/supporting/generic — YOU gate it
+/domain --validate <session-id>            # structural + UL + ADR-008 depth rules
 
-# 3. Generate architecture from exploration
+# 3. Generate architecture from exploration (module docs gain Modeling Depth + invariants)
 /domain --architect-scaffold <session-id>
 
 # 4. Enrich module docs with full DDD content

package/dist/cli.js

@@ -3074,7 +3074,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((p3) => relativePath.includes(p3))) {
     return "user";
   }
@@ -3197,7 +3202,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 = {
     ".": {
@@ -11625,6 +11630,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 \u2014 full tactical modeling),
+  "supporting" (needed but not differentiating \u2014 simple services), or "generic" (off-the-shelf problem \u2014 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 \u2014 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}
 
@@ -11668,7 +11686,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": [
@@ -11676,7 +11707,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": [
@@ -11684,7 +11720,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": [
@@ -11693,7 +11734,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",
@@ -11829,19 +11873,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-???"),
@@ -11865,10 +11914,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) {
@@ -11904,6 +11964,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";
@@ -12046,6 +12149,14 @@ function answerExploration(sessionId, responseJson, options) {
 function readExplorationSession(sessionId, projectDir) {
   const root = projectDir ?? process.cwd();
   const filePath = path2.join(root, ".pi", "domain", "exploration", `${sessionId}.md`);
+  const rawPath = filePath.replace(/\.md$/, ".raw.json");
+  if (fs.existsSync(rawPath)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(rawPath, "utf-8"));
+      if (parsed?.sessionId)
+        return parsed;
+    } catch {}
+  }
   if (!fs.existsSync(filePath)) {
     return null;
   }
@@ -12229,6 +12340,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 \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 || [];
     if (!dryRun && fs.existsSync(filePath)) {
       warnings.push(`Module already exists, will be overwritten: ${fileName}`);
     }
@@ -12485,6 +12600,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 || "\u2014"}
+`;
+      const edgeSummary = contextEdges.map((e) => (e.from === bc.name ? `${e.relationship} \u2192 ${e.to}` : `${e.from} \u2192 ${e.relationship}`) + (e.note ? ` (${e.note})` : "")).join("; ");
+      content += `**Context Map:** ${edgeSummary || "\u2014"}
 `;
       content += `
 `;
@@ -12565,15 +12691,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 += `
 `;
           }
@@ -12659,6 +12792,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** \u2014 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** \u2014 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} \u2014 ${e.note || "\u2014"}
+`;
+          }
+        }
+        content += `
+`;
+      }
       content += `## Acceptance Criteria
 `;
       content += `
@@ -12716,6 +12881,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(`
@@ -12734,9 +12904,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(`
+`) || "\u2014";
+    return `### ${bc.name}
+- **Subdomain:** ${bc.subdomainType ?? "unclassified"} \u2014 ${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");
@@ -12891,6 +13103,10 @@ ${content}`;
   const tempPath = `${outputPath}.tmp`;
   fs.writeFileSync(tempPath, content, "utf-8");
   fs.renameSync(tempPath, outputPath);
+  const rawPath = `${outputPath.replace(/\.md$/, "")}.raw.json`;
+  const rawTemp = `${rawPath}.tmp`;
+  fs.writeFileSync(rawTemp, JSON.stringify(result, null, 2), "utf-8");
+  fs.renameSync(rawTemp, rawPath);
   return outputPath;
 }