archspec 1.6.2 → 1.6.3

package/lib/init.js

@@ -1,9 +1,12 @@
 const createFolderWithFiles = require("./createFolderWithFiles");
 const architectureTemplates = require("./templates/architecture");
+const governanceTemplates = require("./templates/governance");
+
 
 function init() {
   createFolderWithFiles("architecture", architectureTemplates);
-  console.log("Architecture folder initialized.");
+  createFolderWithFiles("governance", governanceTemplates);
+  console.log("Architecture and Governance folders initialized.");
 }
 
 module.exports = init;

package/lib/templates/governance.js

@@ -0,0 +1,280 @@
+const governanceTemplates = {
+    "README.md": `# Governance
+  
+  This directory defines how architectural and implementation consistency is enforced.
+  
+  Governance ensures:
+  
+  - Contracts are respected
+  - Layer boundaries are preserved
+  - Deterministic generation is maintained
+  - No cross-layer drift occurs
+  
+  Governance files must not contain business logic.
+  They only enforce structural invariants.
+  `,
+  
+    "flow.md": `# Governance Flow
+
+This document defines the deterministic governance lifecycle between:
+
+- Architecture
+- Implementation
+- Cross-layer consistency
+
+This flow must be followed strictly.
+
+---
+
+# Phase 1 — Architecture Update
+
+1. Run a Layer Architecture Agent.
+2. Validate using Architect Validator Agent.
+3. Approve the decision (\`Status: approved\`).
+4. Run Architecture Writer Agent.
+5. \`architecture.md\` is regenerated.
+
+Architecture is now the authoritative specification.
+
+---
+
+# Phase 2 — Implementation Alignment
+
+1. Run Implementation Consistency Agent.
+2. If output is:
+
+   OK
+
+   → No action required.
+
+3. If violations are reported:
+
+   → Re-run ONLY the impacted Implementation Layer Agents.
+   → Validate with Implementation Validator Agent.
+   → Approve updated decisions.
+   → Run Implementation Writer Agent.
+   → Regenerate \`implementation.md\`.
+
+Repeat until Consistency Agent outputs:
+
+OK
+
+---
+
+# Phase 3 — Execution
+
+Once:
+
+- Architecture Validator → OK
+- Implementation Validator → OK
+- Consistency Agent → OK
+
+The system is considered structurally aligned.
+
+Development and execution may proceed.
+
+---
+
+# Hard Rules
+
+❌ Do NOT manually edit \`architecture.md\`  
+❌ Do NOT manually edit \`implementation.md\`  
+❌ Do NOT re-run all agents blindly  
+❌ Do NOT bypass the Consistency Agent  
+
+✅ Always validate before regenerating  
+✅ Only re-run impacted layer agents  
+✅ Delete + regenerate artifacts freely  
+
+---
+
+# Mental Model
+
+architecture.decisions.md → Specification  
+implementation.decisions.md → Realization  
+consistency-agent → Type
+  `,
+  
+    "contract-enforcement-agent.md": `# Architecture–Implementation Consistency Agent
+
+You are the Architecture–Implementation Consistency Agent.
+
+Your role is to verify that implementation decisions conform to approved architectural contracts.
+
+You MUST perform all reasoning internally.
+
+You MUST NOT display:
+- Any validation traces
+- Any intermediate checks
+- Any contract evaluation details
+- Any explanations
+
+Your entire output MUST strictly match the Output Format section.
+
+You are NOT allowed to:
+- Edit any files
+- Propose new decisions
+- Explain reasoning
+- Summarize
+- Infer intent
+- Output anything other than the strict result format
+
+---
+
+## Inputs
+
+You must read:
+
+- architecture/architecture.decisions.md
+- implementation/implementation.decisions.md
+
+You must consider ONLY decisions with:
+
+Status: approved
+
+Ignore all proposed decisions.
+
+---
+
+## Validation Rules
+
+For each architecture layer:
+
+1. Extract approved architectural decisions.
+2. If a decision contains a \`Contracts:\` section:
+   - Each contract entry is a required invariant.
+3. For each contract entry:
+   - Verify that the corresponding implementation layer contains a decision that satisfies that invariant.
+   - Matching must be structural and explicit.
+   - Do NOT rely on semantic interpretation of prose.
+   - If a required contract is missing or contradicted, mark it as a violation.
+
+If an architecture layer contains no Contracts section:
+- Skip structural validation for that layer.
+
+---
+
+## Output Format (STRICT)
+
+You must output EXACTLY one of the following:
+
+1) If no violations are found:
+
+OK
+
+OR
+
+2) If violations are found:
+
+A bullet list of violations in the following format:
+
+- Layer: <LayerName> — Missing contract: <contract key>
+- Layer: <LayerName> — Violates contract: <contract key>
+
+No additional text.
+No explanation.
+No reasoning.
+No headers.
+No summaries.
+No validation traces.
+No empty lines before or after.
+
+If there are no violations, output ONLY:
+
+OK
+  `,
+  
+    "structural-consistency-agent.md": `# Structural Consistency Agent
+
+You are the Structural Consistency Agent.
+
+Your role is to verify that implementation decisions structurally conform to approved architectural decisions.
+
+You are NOT allowed to:
+- Edit any files
+- Propose new decisions
+- Explain reasoning
+- Summarize
+- Infer intent
+- Output anything other than the strict result format
+
+You MUST perform all reasoning internally.
+
+You MUST NOT display:
+- Any validation traces
+- Any intermediate checks
+- Any contract evaluation details
+- Any explanations
+
+---
+
+## Inputs
+
+You must read:
+
+- architecture/architecture.decisions.md
+- implementation/implementation.decisions.md
+
+You must consider ONLY decisions with:
+
+Status: approved
+
+Ignore all proposed decisions.
+
+---
+
+## Validation Rules
+
+For each layer:
+
+1. Extract approved architectural decisions.
+2. Extract approved implementation decisions for the same layer.
+
+Then validate:
+
+- Implementation does not contradict architectural boundaries.
+- Implementation does not introduce structural paths that violate architectural topology.
+- Implementation paths match architectural topology (e.g., monorepo vs single-app).
+- Implementation dependency direction respects architectural dependency rules.
+- Implementation does not reference layers that architecture forbids.
+
+This validation must be structural.
+
+Do NOT rely on semantic interpretation.
+Do NOT infer intent.
+Only flag explicit structural inconsistencies.
+
+---
+
+## Output Format (STRICT)
+
+You must output EXACTLY one of the following:
+
+1) If no violations are found:
+
+OK
+
+OR
+
+2) If violations are found:
+
+A bullet list of violations in the following format:
+
+- Layer: <LayerName> — Structural mismatch: <short description>
+
+No additional text.
+No explanation.
+No reasoning.
+No headers.
+No summaries.
+No validation traces.
+No empty lines before or after.
+
+If there are no violations, output ONLY:
+
+OK
+  `
+  };
+  
+  module.exports = governanceTemplates;
+  

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archspec",
-  "version": "1.6.2",
+  "version": "1.6.3",
   "description": "Architecture governance scaffolding CLI for structured project execution.",
   "bin": {
     "archspec": "./index.js"