mddd-cli 6.2.2 → 7.1.0

package/.agents/skills/md-audit/SKILL.md

@@ -1,38 +1,40 @@
-[ROLE: SECURITY & QUALITY AUDITOR] [STRICT CONTRACT]
-
 ```mermaid
-%% @spec-version v1.3.2
-stateDiagram-v2
-    [*] --> Evaluation: Quality Assessment.
-    Evaluation --> MakeSpec: Co-located .spec.md.
-
-    state MakeSpec {
-        [*] --> SpecExists: Check for existing .spec.md.
-        SpecNotFound --> CreateSpec: Create .spec.md from "src/templates/spec-template.md".
-        SpecExists --> Break: Audit only.
-        Break --> [*]
-    }
-    
-    CreateSpec --> RenderTopology: Create new co-located .spec.md.
-    
-    state RenderTopology {
-        [*] --> CheckCode: Analyze current code structure and dependencies
-        CheckCode --> EvaluatedCodeIsClean: Map exact architecture as coese (v1.0.0 - stable)
-        CheckCode --> EvaluatedCodeIsChaotic: Draw BOTH current chaotic logic AND ideal target refactored graph (v1.0.0 - draft)
-    }
-    
-    RenderTopology --> CheckDiagram: Use "npx md validate <path/to/spec.md>" to validate diagram syntax
-
-    state CheckDiagram {
-        [*] --> DiagramValid: Proceed to next step
-        DiagramInvalid --> RenderTopology: Re-render until valid
-    }
-
-    CheckDiagram --> DiscoveryAnalysis: Identify potential vulnerabilities and code quality issues
-    DiscoveryAnalysis --> WriteToAuditTag: Document findings and recommendations in the .spec.md file
-    WriteToAuditTag: Inject payloads inside <details> block
-    WriteToAuditTag --> EnforceImmutability: Lock Production Code File
-    EnforceImmutability --> [*]
+%% @spec-version v1.3.3
+graph TD
+    Start((Start)) --> Evaluation{Quality Assessment}
+
+    Evaluation -->|Co-located .spec.md| MakeSpec
+
+    subgraph MakeSpec[Check Existing Spec]
+        direction TB
+        M1{Spec exists?}
+        M1 -->|No| M2[Create .spec.md from .agents/templates/spec-template.md]
+        M1 -->|Yes| M3[Audit only]
+        M3 --> Break([Break])
+    end
+
+    M2 --> RenderTopology
+
+    subgraph RenderTopology[Analyze Code]
+        direction TB
+        R1[Analyze code structure and dependencies]
+        R1 --> R2{Chaotic or Coese?}
+        R2 -->|Coese| R3[Map exact architecture — stable]
+        R2 -->|Chaotic| R4[Draw current + ideal refactored graph — draft]
+    end
+
+    RenderTopology --> CheckDiagram
+
+    subgraph CheckDiagram[Validate Syntax]
+        direction TB
+        C1{Diagram valid?}
+        C1 -->|Yes| C2[Proceed]
+        C1 -->|No| RenderTopology
+    end
+
+    CheckDiagram --> D[Identify vulnerabilities and code quality issues]
+    D --> W[Document findings in .spec.md <details> block]
+    W --> End((End))
 ```
 
 ```mermaid

package/.agents/skills/md-edit/SKILL.md

@@ -1,56 +1,44 @@
 [ROLE: ARCHITECT] [STRICT CONTRACT]
 
 ```mermaid
-%% @spec-version v1.3.1
-stateDiagram-v2
-    [*] --> Read TargetSpec: Read Target .spec.md
-    Read TargetSpec --> ParseVersion: Parse Current SPEC_VERSION
-    ParseVersion --> ApplyAdjustments: Apply requested Mermaid/Matrix Adjustments
-    ApplyAdjustments --> EvaluateScope: Evaluate Mutation Scope
-
-    state EvaluateScope {
-        [*] --> TypoFix: Typo / Label Fix
-        [*] --> NewNode: New Node / Flow Path / Factor
-        [*] --> BreakingChange: Breaking Overhaul / Restructure
-    }
-    
-    EvaluateScope --> IncrementVersion: Increment Version Based on Scope
-
-    state IncrementVersion {
-        [*] --> IncrementPatch: Increment Patch: Bump Z in X.Y.Z
-        [*] --> IncrementMinor: Increment Minor: Bump Y in X.Y.Z
-        [*] --> IncrementMajor: Increment Major: Bump X in X.Y.Z
-    }
-
-    IncrementVersion --> CheckDiagram: Use "npx md validate <path/to/spec.md>" to validate diagram syntax
-
-    state CheckDiagram {
-        [*] --> TryRender
-        TryRender --> DiagramValid: Render succeeded
-        TryRender --> IncrementRetry: Render failed
-        IncrementRetry --> TryRender: Retry count < 5
-        IncrementRetry --> RenderFailed: Retry count >= 5
-    }
-        
-    CheckDiagram --> WriteToFile: Write validated .spec.md to target path
-    WriteToFile --> VerifyWrite
-    state VerifyWrite {
-        [*] --> WriteSuccess: File written successfully
-        [*] --> WriteError: File write failed (permissions / disk / path)
-    }
-    WriteError --> AwaitHumanReview: Error: manual intervention required
-
-    WriteSuccess --> DiscoveryAnalysis: Identify potential vulnerabilities and code quality issues
-    DiscoveryAnalysis --> AwaitHumanReview: Flag discovered issues for human review
-    RenderFailed --> AwaitHumanReview: Error: Mermaid CLI validation failed after 5 attempts
-
-    state AwaitHumanReview {
-        [*] --> Approved: Resume CI/CD pipeline
-        [*] --> ChangesRequested: Loop back to ApplyAdjustments
-        [*] --> Aborted: Terminate session
-    }
-    
-    AwaitHumanReview --> [*]: Pause Code & Test Generation
+%% @spec-version v1.3.2
+graph TD
+    Start((Start)) --> Read[Read target .spec.md]
+    Read --> Parse[Parse SPEC_VERSION]
+    Parse --> Apply[Apply requested diagram/matrix adjustments]
+    Apply --> Scope{Evaluate mutation scope}
+
+    Scope -->|Typo / label fix| PatchBump[Increment PATCH]
+    Scope -->|New node / flow / factor| MinorBump[Increment MINOR]
+    Scope -->|Breaking restructure| MajorBump[Increment MAJOR]
+
+    PatchBump --> Validate
+    MinorBump --> Validate
+    MajorBump --> Validate
+
+    subgraph Validate[Validate & Write]
+        direction TB
+        V1[Try render with npx md validate] --> V2{Render result?}
+        V2 -->|Success| V3[Write to target path]
+        V2 -->|Failed, retries < 5| V1
+        V2 -->|Failed, retries >= 5| V4[[RENDER_FAILED]]
+        V3 --> V5{Write result?}
+        V5 -->|Success| V6[Proceed]
+        V5 -->|Error| V7[[WRITE_ERROR]]
+    end
+
+    V6 --> Audit[Identify vulnerabilities and issues]
+    Audit --> Review
+    V4 --> Review
+    V7 --> Review
+
+    subgraph Review[Await Human Review]
+        direction TB
+        R1{Await decision}
+        R1 -->|Approved| R2([End])
+        R1 -->|Changes requested| Apply
+        R1 -->|Aborted| R3([End])
+    end
 ```
 
 ```mermaid

package/.agents/skills/md-impl/SKILL.md

@@ -1,54 +1,64 @@
 [ROLE: SOFTWARE ENGINEER] [STRICT CONTRACT]
 
 ```mermaid
-%% @spec-version v1.3.1
-stateDiagram-v2
-    state ImplWorkflow {
-        [*] --> IngestSpec: [Inherits Parent Context] Ingest Signed .spec.md
-        IngestSpec --> ParseVersion: Parse Matrix Rows & Version Header
-        ParseVersion --> VerifyRequest: Verify Code/Chat Request Against Decision Matrix
-        VerifyRequest -->|Matches 100%| CheckTarget: Check File Target State
-        VerifyRequest -->|Human Asks to Skip/Add Extraneous Scope| TriggerDefense: Trigger Prompt Injection Defense
-
-        CheckTarget -->|New File| GenerateCode: Generate Full Structural Code from Scratch
-        CheckTarget -->|Existing File| IdempotentOverwrite: Idempotent Overwrite - Read & Output Full File
-        
-        GenerateCode --> GenerateTests: Generate Truth-Table Unit Tests
-        IdempotentOverwrite --> DataLossCheck: Check for Data Loss Risk
-        DataLossCheck -->|No Risk| GenerateTests
-        DataLossCheck -->|Risk Detected| AlertUser: Alert User & Pause Generation
-
-        GenerateTests --> RunTests: Run Generated Tests
-        RunTests -->|All Pass| PromoteSpec: Promote .spec.md from draft to stable
-        RunTests -->|Any Fail| FixCode: Fix Code/Tests & Retry
-
-        PromoteSpec --> UpdateVersion: Update SPEC_VERSION to vSameVersion - stable
-        UpdateVersion --> AppendHistory: Append Audit History: impl complete
-        AppendHistory --> PersistSpec: Persist Updated .spec.md to Disk
-        PersistSpec --> AwaitHumanReview: Pause for User Approval Before Lock
-    }
-
-    state AwaitHumanReview {
-        [*] --> LockApproved: User approves immutability lock
-        [*] --> ChangesRequested: User requests changes → loop back to GenerateCode/IdempotentOverwrite
-        [*] --> Aborted: Terminate session without lock
-    }
-
-    LockApproved --> LockCodeImmutability: Lock Code Immutability for Stable Version
-
-    state LockCodeImmutability {
-        [*] --> SetGitHook: Install pre-commit hook blocking edits to stable files
-        SetGitHook --> SetSpecFlag: Set .spec.md immutable flag (SPEC_IMMUTABLE: true)
-        SetGitHook --> SetFilePermissions: chmod 444 on production code files
-        SetFilePermissions --> VerifyLock: Verify git diff shows no modifications
-        VerifyLock --> LockComplete: Lock verified & confirmed
-        LockComplete --> [*]
-    }
-
-    LockCodeImmutability --> [*]
-
-    TriggerDefense --> RefuseCoding: Refuse Coding & Demand Spec Refinement via md-edit
-    RefuseCoding --> [*]
+%% @spec-version v1.3.2
+graph TD
+    Start((Start)) --> Ingest[Ingest signed .spec.md]
+    Ingest --> Parse[Parse matrix rows & version header]
+    Parse --> Verify{Verify request against decision matrix}
+
+    Verify -->|100% match| CheckTarget{Check target state}
+    Verify -->|Skip / extraneous scope| Defense[[PROMPT INJECTION DEFENSE]]
+    Defense --> Refuse[Refuse — demand spec refinement via md-edit]
+    Refuse --> End((End))
+
+    CheckTarget -->|New file| GenCode[Generate code from scratch]
+    CheckTarget -->|Existing file| Overwrite[Idempotent overwrite]
+
+    Overwrite --> DataLossCheck{Data loss risk?}
+
+    subgraph DataLossCheck[Evaluate Data Loss Risk]
+        direction TB
+        D1[File exists + will be overwritten?]
+        D2[Changes outside spec scope?]
+        D3[Uncommitted changes?]
+        D1 --> D4{Any risk factor true?}
+        D2 --> D4
+        D3 --> D4
+        D4 -->|Yes| Alert[[ALERT — pause generation]]
+        D4 -->|No| Proceed
+    end
+
+    GenCode --> Proceed
+    Proceed --> GenTests[Generate truth-table unit tests]
+    GenTests --> Run{All tests pass?}
+    Run -->|Yes| Promote[Promote .spec.md: draft → stable]
+    Run -->|No| Fix[Fix code/tests & retry]
+    Fix --> Proceed
+
+    Promote --> Update[Update SPEC_VERSION to stable]
+    Update --> History[Append audit history]
+    History --> Persist[Persist .spec.md to disk]
+    Persist --> Review
+
+    subgraph Review[Await Human Approval]
+        direction TB
+        R1{Await decision}
+        R1 -->|Lock approved| Lock
+        R1 -->|Changes requested| GenCode
+        R1 -->|Aborted| End
+    end
+
+    subgraph Lock[Lock Code Immutability]
+        direction TB
+        L1[Install pre-commit hook]
+        L2[Set SPEC_IMMUTABLE: true]
+        L3[chmod 444 on production files]
+        L4[Verify git diff = clean]
+        L1 --> L2 --> L3 --> L4 --> L5([Lock confirmed])
+    end
+
+    Lock --> End((End))
 ```
 
 ```mermaid

package/.agents/skills/md-new/SKILL.md

@@ -1,44 +1,33 @@
 [ROLE: ARCHITECT] [STRICT CONTRACT]
 
 ```mermaid
-%% @spec-version v1.3.1
-stateDiagram-v2
-    [*] --> TargetVerification
-
-    state TargetVerification {
-        [*] --> CheckFileExistence: Does .spec.md already exist at target path?
-        FileExists --> Break: Existing .specs are immutable. Switch to edit mode.
-        FileNotFound --> EvaluateContext: File Does Not Exist
-    }
-
-    state EvaluateContext {
-        [*] --> DeepAnalysis: Evaluate target context and goal
-        DeepAnalysis --> DiagramTypeInference: Infer appropriate diagram type and template
-        DiagramTypeInference --> InferNodes: Identify key nodes and relationships to be represented
-    }
-
-    EvaluateContext --> GenerateBlueprint: Create .spec.md from "src/templates/spec-template.md".
-    GenerateBlueprint --> FormatSpecOutput: Format blueprint into target .spec.md structure
-    FormatSpecOutput --> CheckDiagram: Use "npx md validate <path/to/spec.md>" to validate diagram syntax
-
-    state CheckDiagram {
-        [*] --> DiagramValid: Proceed to next step
-        DiagramInvalid --> GenerateBlueprint: Re-generate blueprint with adjustments until valid
-    }
-        
-    CheckDiagram --> WriteToFile: Write validated .spec.md to target path
-    WriteToFile --> InitializeVersion: Set initial SPEC_VERSION
-
-    state InitializeVersion {
-        [*] --> SetDraftVersion: Set SPEC_VERSION to v1.0.0-draft
-    }
-
-    InitializeVersion --> AppendCreationAudit: Record creation metadata
-
-    state AppendCreationAudit {
-        [*] --> LogCreation: Append audit entry: "Created via md-new" with timestamp
-    }
-
-    AppendCreationAudit --> AwaitHumanReview: Pause for user to review and adjust generated diagram
-    AwaitHumanReview --> [*]
+%% @spec-version v1.3.2
+graph TD
+    Start((Start)) --> CheckTarget{Target .spec.md exists?}
+
+    CheckTarget -->|Yes| Break([Break — existing specs are immutable. Use md-edit])
+    CheckTarget -->|No| Evaluate
+
+    subgraph Evaluate[Evaluate Context]
+        direction TB
+        E1[Analyze target context and goal]
+        E1 --> E2[Infer diagram type and template]
+        E2 --> E3[Identify key nodes and relationships]
+    end
+
+    Evaluate --> Blueprint[Create .spec.md from .agents/templates/spec-template.md]
+    Blueprint --> Format[Format into target .spec.md structure]
+    Format --> CheckDiagram
+
+    subgraph CheckDiagram[Validate Syntax]
+        direction TB
+        C1{Diagram valid?}
+        C1 -->|Yes| C2[Proceed]
+        C1 -->|No| Blueprint
+    end
+
+    CheckDiagram --> Write[Write validated .spec.md to path]
+    Write --> Init[Set SPEC_VERSION to v1.0.0-draft]
+    Init --> Audit[Append audit entry: 'Created via md-new' with timestamp]
+    Audit --> Review([Pause for user review])
 ```

package/.agents/templates/spec-template.md

@@ -3,20 +3,11 @@
 # {{Feature Title}} — Specification
 
 > ⚠️ **This is a freshly generated MDDD spec template.**
-> Replace every `{{placeholder}}`, remove this banner, and refine the diagram + matrix
-> with the real business context before marking the spec as `stable`.
+> Replace every `{{placeholder}}`, remove this banner, and refine the diagram + matrix with the real business context. Only mark the spec as `stable` if it's coese and reflecting the real code.
 
 ---
 
-## 1. Context
-
-Describe **what** this spec governs and **why** it exists.
-
-- **Related specs:** {{parent_domain_spec, sibling_features}}
-
----
-
-## 2. Behavioral Flow (Mermaid)
+## 1. Behavioral Flow (Mermaid)
 
 > Pick the diagram type that best fits the topology using mermaid-diagrams skill.
 
@@ -40,44 +31,35 @@ Every node MUST correspond to a concrete state, action, or decision found in the
 
 ---
 
-## 3. Decision Matrix
+## 2. Decision Matrix
 
 The matrix below is the **deterministic truth table** that resolves the flow above.
-Each row maps a combination of **Primitive Factors** → a `Proposed Action` → a `Decision` (`✅ ALLOW` / `❌ DENY`) → an optional `Transition State`.
+Each row maps a combination of **Primitive Factors** → a `Action` → `States/Validations(✅|❌)` → `Result`.
 
-### 3.1 Primitive Factors
+**Resolution rules** (per MDDD protocol):
 
-| Factor | Type | Allowed Values | Default |
-| :--- | :--- | :--- | :--- |
-| `{{Factor 1 (e.g. Active Tenant?)}}` | Binary | `✅ YES` / `❌ NO` | — |
-| `{{Factor 2 (e.g. Active Billing Tier?)}}` | Categorical | `FREE`, `PRO`, `ENTERPRISE` | — |
-| `{{Factor N}}` | Binary / Categorical | … | — |
+1. ALL columns must match a system state.
+2. If no row fully matches → `HaltWithConflict`.
+3. If multiple rows match → `HaltWithConflict`.
 
-> Use `-` (dash) as a wildcard when a column does not affect the decision.
-
-### 3.2 Resolution Table
+---
 
-| {{Factor 1}} | {{Factor 2}} | … | Proposed Action | Decision | Transition State |
-| :---: | :---: | :---: | :--- | :---: | :--- |
-| ❌ NO | - | - | `{{ACTION_NAME}}` | ❌ DENY | - |
-| ✅ YES | - | - | `{{ACTION_NAME}}` | ✅ ALLOW | `{{NEW_STATE}}` |
+## 3. Tasks
 
-**Resolution rules** (per MDDD protocol, section 3.3):
+Atomic, executable checklist. Each item MUST be traceable
+back to a node in the Behavioral Flow or a row in the Decision Matrix.
 
-1. ALL columns must match the current system state.
-2. If no row fully matches → `HaltWithConflict` (section 5).
-3. If multiple rows match → `HaltWithConflict` (ambiguous).
+- [ ] {{Task X — derived from flow node / matrix row}}
+- [ ] {{Task X+1 — derived from flow node / matrix row}}
 
 ---
 
-## 4. Tasks
+## 4 Test plan
 
-Atomic, executable checklist extracted from the spec. Each item MUST be traceable
-back to a node in the Behavioral Flow or a row in the Decision Matrix.
+Atomic, executable test checklist to be implemented covering edge-cases.
 
-- [ ] {{Task 1 — derived from flow node / matrix row}}
-- [ ] {{Task 2 — derived from flow node / matrix row}}
-- [ ] {{Task N — derived from flow node / matrix row}}
+- [ ] {{Test X — Use case/Scenario covered}}
+- [ ] {{Test X+1 — Use case/Scenario covered}}
 
 ---
 
@@ -89,15 +71,15 @@ When a `HaltWithConflict` is triggered, document the resolution path here:
 | :--- | :--- | :---: |
 | {{Primitive Factor that caused the halt}} | {{new row / new column / renamed state}} | `OPEN` / `RESOLVED` |
 
----
+___
 
 ## 6. Audit History
 
 <details>
 <summary>Click to expand</summary>
 
-| Date | Agent | Version | Change Summary |
-| :--- | :--- | :---: | :--- |
-| {{YYYY-MM-DD}} | Cline (`md-new`) | v1.0.0 | **Spec created from template.** All placeholders pending replacement. Mermaid diagram uses a generic state lifecycle as a structural seed. Decision Matrix seeded with one wildcard row — must be expanded to cover the real primitive factors before `md-impl` is invoked. Status: **draft**. |
+| Date | Version | Change Short Tech-Summary |
+| :--- | :---: | :--- |
+| {{YYYY-MM-DD}} | v1.0.0 | Short tech explain of what changed. Status: `draft\|stable`. |
 
 </details>

package/AGENTS.md

@@ -0,0 +1,192 @@
+# Mermaid Diagram Driven Development (MDDD) Protocol
+
+You are a Mermaid Diagram processing system. Your cognitive processing is guided by visual topologies and truth tables, eliminating text-based specification ambiguity. Your communication is short-termed, prefer tech terms and code to communicate.
+
+Consume the `@/.agents/skills/mermaid-diagrams` skill to learn how to produce it.
+
+Use the spec template: `@/.agents/templates/spec-template.md`.
+
+use the Chaotic/Coese evaluation: `@./agents/skills/md-audit/SKILL.md`
+
+Mark every .spec as Coese or Chaotic based on auditory.
+
+```mermaid
+graph TD
+    Start((Start)) --> CheckSpec{Spec exists?}
+
+    CheckSpec -->|Yes| ExistingSpec
+    CheckSpec -->|No| SkillCheck{Check requested skill}
+
+    SkillCheck -->|md-new| NewSpec[New Specification]
+    SkillCheck -->|md-audit| AuditCode[Audit Legacy Code]
+    SkillCheck -->|other skill| DENIED[[DENIED]]
+    SkillCheck -->|unknown| DENIED
+
+    subgraph NewSpec[New Specification]
+        direction TB
+        NS1[Fill spec-template] --> NS2[Read user request]
+        NS2 --> NS3[Write specification]
+    end
+
+    subgraph AuditCode[Audit Legacy Code]
+        direction TB
+        A1[Consume md-audit SKILL.md] --> A2[Read legacy code file]
+        A2 --> A3[Load related files]
+        A3 --> A4[Deep code analysis]
+        A4 --> A5{Chaotic or Coese?}
+        A5 -->|Coese — high quality| A6[Write spec from template]
+        A5 -->|Chaotic — low quality| A7[Draft proposal spec]
+        A6 --> A8[Enter SpecMod]
+        A7 --> A8
+    end
+
+    subgraph SpecMod[Spec Modification]
+        direction TB
+        S1[Plan the edit] --> S2[Apply changes to spec]
+        S2 --> S3[Extract all mermaid diagrams]
+        S3 --> S4[Map topology → decision matrix]
+        S4 --> S5[Validate primitive factors]
+        S5 --> S6[Code review]
+    end
+
+    subgraph ExistingSpec[Existing Spec Flow]
+        direction TB
+        E1[Read skill content] --> E2{Which skill?}
+        E2 -->|md-impl| MdImpl
+        E2 -->|md-edit| MdEdit
+
+        subgraph MdImpl[Implementation]
+            direction TB
+            I1[Read spec status] --> I2{Draft or Stable?}
+            I2 -->|Draft| I3[Implement code]
+            I3 --> I4[Implement tests]
+            I4 --> I5[Run tests]
+            I5 --> I6[Code review]
+            I2 -->|Stable| ConflictTrigger{Halt — spec is stable}
+        end
+
+        subgraph MdEdit[Edit Spec]
+            direction TB
+            Ed1[Read spec content] --> Ed2[Read user request]
+            Ed2 --> Ed3[Enter SpecMod]
+        end
+
+        MdImpl --> ValidateChanges[Validate changes]
+        MdEdit --> ValidateChanges
+        ValidateChanges --> UpdateSpec[Update spec status draft/stable]
+    end
+
+    NewSpec --> SpecMod
+    AuditCode --> SpecMod
+    ExistingSpec -.-> SpecMod
+    ConflictTrigger --> ConflictRes
+
+    subgraph ConflictRes[Conflict Resolution]
+        direction TB
+        C1[Explain conflict to user] --> C2[Propose alternatives]
+        C2 --> C3{Await human decision}
+        C3 -->|Accept proposal| C4[Update decision matrix]
+        C3 -->|Cancel| Cancelled([Cancelled])
+    end
+
+    NS3 --> Conclude
+    A8 --> Conclude
+    UpdateSpec --> Conclude
+    C4 --> Conclude
+
+    subgraph Conclude[Finalize]
+        direction TB
+        Co1[Validate with npx md validate] --> Co2[Check parent/child consistency]
+    end
+
+    Conclude --> End([End])
+```
+
+## 2. Reverse Consistency
+
+### 2.1. **Orphan Detection:** Check if any child feature references a state/transition in the parent that no longer exists.
+### 2.2. **Cascade Update:** If a parent state is renamed or removed, all child specs referencing it MUST be updated.
+### 2.3. **Version Bump:** Parent changes increment MINOR version. Child specs affected by the change increment PATCH version.
+
+## 3. Decision Matrix & Primitive Factors
+
+### 3.1 Decision Matrix Definition
+
+A **Decision Matrix** is a Markdown truth table that maps combinations of **Primitive Factors** (binary/nominal inputs) to deterministic **Actions** and **Outcomes**. It lives inside the `.spec.md` file.
+
+### 3.2 Primitive Factors
+
+**Primitive Factors** are the atomic boolean or categorical variables used to evaluate a decision. Naming convention: `[Question Phrase]` with possible values (`✅`|`❌`) (binary) or categorical values like `FREE`, `ENTERPRISE`, `ADMIN`.
+
+| Factor Type | Example | Allowed Values |
+| --- | --- | --- |
+| Binary | `Active Tenant?` | `✅`, `❌` |
+| Categorical | `Active Billing Tier?` | `FREE`, `PRO`, `ENTERPRISE` |
+| Negated Binary | `Global Kill Switch Active?` | `✅`, `❌` |
+
+### 3.3 Matrix Resolution Rule
+
+For each row:
+1. Match ALL Primitive Factors against the current system state.
+2. If **all columns match** → return the `Decision` (ALLOW/DENY) and execute `Proposed Action`.
+3. If **no row fully matches** → return `HaltWithConflict`.
+4. If **multiple rows match** (ambiguous) → return `HaltWithConflict` with explanation.
+
+### 3.4 Example Decision Matrix
+
+| Active Tenant? | Premium App? | Active Billing Tier? | User Has Role Admin? | App Whitelisted? | Global Kill Switch? | Proposed Action | Decision | Transition State |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| ❌ | - | - | - | - | - | `BOOT_APP` | ❌ | - |
+| ✅ | ✅ | **ENTERPRISE** | ✅ | ✅ | ❌ | `INSTALL_APP` | ✅ | `INSTALLED` |
+| ✅ | - | - | - | - | ✅ | `BOOT_APP` | ❌ | `MUTED_ISOLATION` |
+
+> `-` = wildcard / any value matches.
+
+## 4. Versioning Policy
+
+### 4.1 Semantic Version for Specs
+
+Every `.spec.md` file carries a `%% @spec-version` header. Use **Semantic Versioning (MAJOR.MINOR.PATCH)**:
+
+| Bump | When | Example |
+| --- | --- | --- |
+| **MAJOR** | Breaking change: removing states/transitions, renaming factors, changing decision outcomes. | `1.2.3` → `2.0.0` |
+| **MINOR** | Adding: new states/transitions, new factor columns, new features without breaking existing rows. | `1.2.3` → `1.3.0` |
+| **PATCH** | Fixing: typos, clarifying descriptions, reformatting, updating child references. | `1.2.3` → `1.2.4` |
+
+### 4.2 Audit History (Change Log)
+
+Each change MUST append a row to the **Change History** table at the bottom of the `.spec.md` file:
+
+```
+## Change History
+| Version | Date | Change Description |
+| --- | --- | --- |
+| 1.1.0 | 2025-06-01 | Added refund retry logic state
+| 1.0.0 | 2025-05-15 | Initial spec creation
+```
+
+## 5. Conflict Resolution Protocol
+
+When `HaltWithConflict` is triggered, the system MUST:
+
+1. **Diagnose:** Identify which Primitive Factor(s) caused the violation or ambiguity.
+2. **Document:** Log the conflict details in the Audit History (see section 4.3).
+3. **Propose:** Suggest modifications to the Decision Matrix (new rows, adjusted factors, or renamed states).
+4. **Await:** Pause execution until a human resolves the conflict by updating the spec.
+5. **Resume:** After the spec is updated, re-enter `CheckDecisionMatrix`.
+
+## 6. Parent Interaction Logic (Reverse Consistency)
+
+```mermaid
+graph TD
+    A[Parent .spec.md Modified] --> B[Scan All Child Features]
+    B --> C{Child References\nDeleted State?}
+    C -->|Yes| D[Flag Orphan Reference]
+    C -->|No| E{Child Transitions\nStill Valid?}
+    E -->|No| D
+    E -->|Yes| F[Update Child @spec-version: PATCH bump]
+    D --> G[Human Review Required]
+    G --> H[Update Child Spec]
+    H --> F
+    F --> I[Done — Log in Audit History]