mddd-cli 4.0.1 → 4.0.3

package/bin/cli.js

@@ -16,7 +16,7 @@ const program = new Command();
 program
   .name('md')
   .description('Manager for co-located specifications for Mermaid Diagram Driven Development (MDDD)')
-  .version('4.0.1');
+  .version('4.0.3');
 
 // ==========================================
 // COMMAND: md init

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mddd-cli",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "description": "Official CLI for modular, co-located, and versioned Mermaid Diagram Driven Development (MDDD).",
   "type": "module",
   "exports": "./bin/cli.js",

package/src/skills/md-audit/content.js

@@ -1,19 +1,19 @@
 export default `[ROLE: SECURITY & QUALITY AUDITOR] [STRICT CONTRACT]
 
 \`\`\`mermaid
-%% @spec-version v1.3.0
+%% @spec-version v1.3.2
 stateDiagram-v2
-    [*] --> Evaluation: Quality Assessment
-    Evaluation --> MakeSpec: Co-located .spec.md
+    [*] --> Evaluation: Quality Assessment.
+    Evaluation --> MakeSpec: Co-located .spec.md.
 
     state MakeSpec {
-        [*] --> SpecExists: Check for existing .spec.md
-        SpecNotFound --> CreateSpec: Create new .spec.md
+        [*] --> 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
+    CreateSpec --> RenderTopology: Create new co-located .spec.md.
     
     state RenderTopology {
         [*] --> CheckCode: Analyze current code structure and dependencies
@@ -21,14 +21,16 @@ stateDiagram-v2
         CheckCode --> EvaluatedCodeIsChaotic: Draw BOTH current chaotic logic AND ideal target refactored graph (v1.0.0 - draft)
     }
     
-    RenderTopology --> CheckDiagram: Use npx @mermaid-js/mermaid-cli to Validate Syntax
+    RenderTopology --> CheckDiagram: Use npx @mermaid-js/mermaid-cli to Validate Diagrams Syntax (Mandatory)
 
     state CheckDiagram {
         [*] --> DiagramValid: Proceed to next step
         DiagramInvalid --> RenderTopology: Re-render until valid
     }
 
-    CheckDiagram --> WriteToAuditTag: Inject payloads inside <details> block
+    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 --> [*]
 \`\`\`

package/src/skills/md-edit/content.js

@@ -1,7 +1,7 @@
 export default `[ROLE: ARCHITECT] [STRICT CONTRACT]
 
 \`\`\`mermaid
-%% @spec-version v1.3.0
+%% @spec-version v1.3.1
 stateDiagram-v2
     [*] --> Read TargetSpec: Read Target .spec.md
     Read TargetSpec --> ParseVersion: Parse Current SPEC_VERSION
@@ -28,8 +28,8 @@ stateDiagram-v2
         [*] --> TryRender
         TryRender --> DiagramValid: Render succeeded
         TryRender --> IncrementRetry: Render failed
-        IncrementRetry --> TryRender: Retry count < 3
-        IncrementRetry --> RenderFailed: Retry count >= 3
+        IncrementRetry --> TryRender: Retry count < 5
+        IncrementRetry --> RenderFailed: Retry count >= 5
     }
         
     CheckDiagram --> WriteToFile: Write validated .spec.md to target path
@@ -40,8 +40,9 @@ stateDiagram-v2
     }
     WriteError --> AwaitHumanReview: Error: manual intervention required
 
-    WriteSuccess --> AwaitHumanReview
-    RenderFailed --> AwaitHumanReview: Error: Mermaid CLI validation failed after 3 attempts
+    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

package/src/skills/md-new/content.js

@@ -1,7 +1,7 @@
 export default `[ROLE: ARCHITECT] [STRICT CONTRACT]
 
 \`\`\`mermaid
-%% @spec-version v1.3.0
+%% @spec-version v1.3.1
 stateDiagram-v2
     [*] --> TargetVerification
 
@@ -17,9 +17,9 @@ stateDiagram-v2
         DiagramTypeInference --> InferNodes: Identify key nodes and relationships to be represented
     }
 
-    EvaluateContext --> GenerateBlueprint: Create .spec.md Blueprint with placeholders
+    EvaluateContext --> GenerateBlueprint: Create .spec.md from "src/templates/spec-template.md".
     GenerateBlueprint --> FormatSpecOutput: Format blueprint into target .spec.md structure
-    FormatSpecOutput --> CheckDiagram: Use npx @mermaid-js/mermaid-cli to Validate Syntax
+    FormatSpecOutput --> CheckDiagram: Use npx @mermaid-js/mermaid-cli to Validate Diagrams Syntax (Mandatory)
 
     state CheckDiagram {
         [*] --> DiagramValid: Proceed to next step
@@ -40,6 +40,6 @@ stateDiagram-v2
     }
 
     AppendCreationAudit --> AwaitHumanReview: Pause for user to review and adjust generated diagram
-    AwaitHumanReview --> [*]: Pause Code & Test Generation
+    AwaitHumanReview --> [*]
 \`\`\`
 `;

package/src/templates/spec-template.md

@@ -0,0 +1,124 @@
+%% @spec-version 1.0.0
+%% @domain {{domain_name}}
+%% @feature {{feature_name}}
+%% @author {{author_name}}
+
+# {{Feature Title}} — Specification
+
+**SPEC_VERSION:** v1.0.0 — draft
+
+> ⚠️ **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`.
+
+---
+
+## 1. Context
+
+Describe **what** this spec governs and **why** it exists.
+
+- **Domain:** `{{domain_name}}`
+- **Feature / Module:** `{{feature_name}}`
+- **Scope (in):** {{what is covered}}
+- **Scope (out):** {{what is explicitly NOT covered}}
+- **Owners:** {{team_or_person}}
+- **Related specs:** {{parent_domain_spec, sibling_features}}
+
+---
+
+## 2. Behavioral Flow (Mermaid)
+
+> Pick the diagram type that best fits the topology:
+> `stateDiagram-v2` for lifecycles, `graph TD/LR` for procedural flows,
+> `sequenceDiagram` for multi-actor protocols, `flowchart` for branching logic.
+
+```mermaid
+%% @spec-version 1.0.0
+stateDiagram-v2
+    [*] --> Idle: initial entry point
+
+    state "Decision Node" as Decision
+    state "Happy Path" as Happy
+    state "Conflict / Halt" as Halt
+
+    Idle --> Decision: trigger event
+    Decision --> Happy: ✅ Primitive Factors match an ALLOW row
+    Decision --> Halt: ❌ No row matches / multiple rows match
+    Happy --> [*]
+    Halt --> [*]: escalate to human via Conflict Resolution
+```
+
+**Replace the diagram above with the real topology** for this feature.
+Every node MUST correspond to a concrete state, action, or decision found in the Decision Matrix.
+
+---
+
+## 3. 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`.
+
+### 3.1 Primitive Factors
+
+| 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 | … | — |
+
+> 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}}` |
+
+**Resolution rules** (per MDDD protocol, section 3.3):
+
+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).
+
+---
+
+## 4. Tasks
+
+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.
+
+- [ ] {{Task 1 — derived from flow node / matrix row}}
+- [ ] {{Task 2 — derived from flow node / matrix row}}
+- [ ] {{Task N — derived from flow node / matrix row}}
+
+---
+
+## 5. Conflict Resolution Notes
+
+When a `HaltWithConflict` is triggered, document the resolution path here:
+
+| Conflict Source | Proposed Matrix Change | Status |
+| :--- | :--- | :---: |
+| {{Primitive Factor that caused the halt}} | {{new row / new column / renamed state}} | `OPEN` / `RESOLVED` |
+
+---
+
+## 6. Change History
+
+| Version | Date | Author | Change Description | Change Type |
+| :---: | :--- | :--- | :--- | :---: |
+| 1.0.0 | {{YYYY-MM-DD}} | {{author_name}} | Initial spec creation via `md-new` | MAJOR |
+
+---
+
+## 7. 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**. |
+
+</details>

package/system_prompt.md

@@ -217,6 +217,8 @@ The UNIVERSAL RULE is now integrated into the main processing diagram at the top
 
 **Before ANY action, the system MUST verify that a `.spec.md` file exists for the target domain/feature.** If no spec exists, only `md-new` and `md-audit` skills are allowed to proceed (to create or propose a spec). All other skills (`md-impl`, `md-edit`, etc.) are DENIED without an existing specification.
 
+Diagrams: Always use npx @mermaid-js/mermaid-cli to Validate Diagrams Syntax (Mandatory)
+
 ```mermaid
 %% @spec-version v2.0.0
 %% @protocol-version 1.0.0
@@ -232,4 +234,5 @@ stateDiagram-v2
     Allowed --> Action: Execute requested skill.
     Action --> Verify: Validate output.
     Verify --> [*]: Success.
-    Verify --> Action: Retry if criteria not met.
+    Verify --> Action: Retry if criteria not met.
+ ```