mddd-cli 4.0.0 → 4.0.2

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.0');
+  .version('4.0.2');
 
 // ==========================================
 // COMMAND: md init

package/bin/cli.spec.md

@@ -1,11 +1,11 @@
-# CLI Module | v4.2.0 (Stable)
+# CLI Module | v4.2.1 (Stable)
 
 ## 1. Flow Contract (Mermaid)
 
 ### 1.1 Topologia Atual (As-Is)
 
 ```mermaid
-%% @spec-version v4.2.0
+%% @spec-version v4.2.1
 graph TD
     subgraph "CLI Entry (bin/cli.js)"
         A[bin/cli.js: Commander Router] --> B[delegate to ./commands/init.js]
@@ -63,6 +63,7 @@ O diagrama acima reflete a arquitetura final e estável pós-refatoração: sepa
 | 2026-05-28 | Cline (Agent-Actor) | v4.0.0 | **MAJOR Mutation (v3.0.0 → v4.0.0):** Refatoração concluída e estabilizada. Diagrama As-Is e To-Be unificados em um único diagrama estável refletindo a arquitetura real: `bin/cli.js` (37 linhas) → `src/commands/init.js` → `src/services/InitService.js` + `src/services/FileSystemService.js`. Título alterado de "Refactoring Plan" para "CLI Module (Stable)". Matriz de decisão e fatores de qualidade atualizados para refletir o estado modular final. |
 | 2026-05-28 | Cline (md-audit) | v4.1.0 | **MINOR Mutation (v4.0.0 → v4.1.0):** Criados specs faltantes `src/services/FileSystemService.spec.md` e `src/services/InitService.spec.md` via `md-audit`. A Matriz de Decisão, que já declarava ✅ `YES` para ambos, agora reflete a realidade do filesystem. Nenhuma alteração em código de produção. |
 | 2026-05-30 | Cline (Agent-Actor) | v4.2.0 | **MINOR Mutation (v4.1.0 → v4.2.0):** Adicionado `@mermaid-js/mermaid-cli@^11.15.0` como dependência no `package.json`. Diagrama atualizado para incluir o subgraph "External Dependencies" com referência ao mermaid-cli. Matriz de decisão estendida com linha para a dependência externa. |
+| 2026-05-30 | Cline (Agent-Actor) | v4.2.1 | **PATCH Mutation (v4.2.0 → v4.2.1):** Adicionado `system_prompt.md` ao campo `"files"` no `package.json` para resolver erro `ENOENT` ao executar `md init` com instalação global via npm. |
 
 ### Análise de Qualidade
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mddd-cli",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "description": "Official CLI for modular, co-located, and versioned Mermaid Diagram Driven Development (MDDD).",
   "type": "module",
   "exports": "./bin/cli.js",
@@ -9,7 +9,8 @@
   },
   "files": [
     "bin",
-    "src"
+    "src",
+    "system_prompt.md"
   ],
   "engines": {
     "node": ">=18.0.0"

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.1
 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
@@ -28,7 +28,9 @@ stateDiagram-v2
         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,7 +17,7 @@ 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
 
@@ -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

@@ -0,0 +1,235 @@
+# 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.
+
+```mermaid
+%% @spec-version v2.0.0
+%% @protocol-version 1.0.0
+stateDiagram-v2
+    [*] --> CheckSpec: UNIVERSAL RULE — Check specification file
+
+    state CheckSpec {
+        SpecExists --> ReadSpecification: Request Allowed.
+        SpecNotFound --> SkillCheck: Check skill requested.
+    }
+
+    state SkillCheck {
+        MdNew --> ReadSpecification: Request Allowed.
+        MdAudit --> ReadSpecification: Request Allowed.
+        MdEdit --> ReadSpecification: Request Allowed.
+        Other --> Denied: Specification file required.
+    }
+
+    Denied --> ConflictResolution: Explain missing spec
+
+    state ReadSpecification {
+        [*] --> ParseMermaidDiagrams: Extract all %% @spec-version diagrams
+        ParseMermaidDiagrams --> ExtractDecisionMatrices: Map topology nodes/edges
+        ExtractDecisionMatrices --> ValidatePrimitiveFactors: Check factor columns
+        ValidatePrimitiveFactors --> [*]: Spec loaded into context
+    }
+
+    ReadSpecification --> CheckDecisionMatrix: Evaluate Primitive Factors
+    CheckDecisionMatrix --> HaltWithConflict: Constraint Violation / Feature Creep
+    CheckDecisionMatrix --> ExecuteAction: Strict Match Confirmed
+    HaltWithConflict --> ConflictResolution: Auto-detect conflict source
+
+    state ConflictResolution {
+        ExplainConflict --> LogConflict: Document in Audit History
+        LogConflict --> ProposeAlternatives: Suggest decision matrix changes
+        ProposeAlternatives --> UserDecision: Await human input
+        UserDecision --> CheckDecisionMatrix: Matrix updated
+        UserDecision --> HaltProcess: User cancels
+    }
+
+    HaltProcess --> UpdateDetailsFooter: Record aborted attempt
+    ExecuteAction --> MutateState: Apply File/Code Changes
+    MutateState --> UpdateVersionHeader: Apply Semantic Version Rules (MAJOR.MINOR.PATCH)
+    UpdateVersionHeader --> UpdateDetailsFooter: Append Audit History entry
+    UpdateDetailsFooter --> [*]
+```
+
+## 0. Spec File Format (.spec.md)
+
+Every `.spec.md` file MUST follow this structure:
+
+```
+%% @spec-version 1.0.0
+%% @domain [domain_name]
+%% @feature [feature_name] (optional for domain-level specs)
+%% @author [author_name] (optional)
+
+# [Feature/Domain Name] Specification
+
+## Context
+Brief description of the purpose and scope of this specification.
+
+## Flow Diagram
+```mermaid
+[One or more Mermaid diagrams defining the topology/flow]
+```
+
+## Decision Matrix
+| Primitive Factor 1 | Primitive Factor 2 | ... | Proposed Action | Decision |
+| --- | --- | --- | --- | --- |
+| ✅ YES / ❌ NO | ✅ YES / ❌ NO | ... | `ACTION_NAME` | ✅ ALLOW / ❌ DENY |
+
+## Tasks
+- [ ] Task extracted from spec
+
+## Change History
+| Version | Date | Author | Change Description |
+| --- | --- | --- | --- |
+| 1.0.0 | YYYY-MM-DD | ... | Initial spec creation |
+```
+
+## 1. Co-location Architecture Tree
+
+src/
+└── [domain_name]/
+    ├── [domain_name].spec.md                   # 🌎 Macro Module Domain (stateDiagram-v2)
+    ├── [feature_name]/
+    │   ├── [feature_name].spec.md              # 🔬 Micro Flow Contract + Decision Matrix
+    │   └── [feature_name].[extension]          # 💻 Target Production Code File (Any Extension)
+    └── ...                                     # Additional features per domain
+
+> **Note:** `[domain_name]` and `[feature_name]` are placeholders for your actual project names.
+> A single domain can contain multiple features, each in its own subdirectory.
+
+## 2. Parent Interaction Logic
+
+```mermaid
+graph TD
+    A[Create/Change Sub-Feature] --> B[Open Indicated Parent File]
+    B --> C[Locate Bifurcation Node in Parent Mermaid]
+    C --> D[Modify Parent Graph: Point Arrow to New State]
+    D --> E[Child File: Inherit Parent Context in Entry Node]
+    E --> F[Update Parent @spec-version: Increment PATCH]
+```
+
+### 2.1 Reverse Consistency (Parent → Child)
+
+When a parent domain spec is modified, the following MUST be verified:
+
+1. **Orphan Detection:** Check if any child feature references a state/transition in the parent that no longer exists.
+2. **Cascade Update:** If a parent state is renamed or removed, all child specs referencing it MUST be updated.
+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 `✅ YES` / `❌ NO` (binary) or categorical values like `FREE`, `ENTERPRISE`, `ADMIN`.
+
+| Factor Type | Example | Allowed Values |
+| --- | --- | --- |
+| Binary | `Active Tenant?` | `✅ YES` / `❌ NO` |
+| Categorical | `Active Billing Tier?` | `FREE`, `PRO`, `ENTERPRISE` |
+| Negated Binary | `Global Kill Switch Active?` | `✅ YES` (blocked) / `❌ NO` (normal) |
+
+### 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 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| ❌ NO | - | - | - | - | - | `BOOT_APP` | ❌ DENY | - |
+| ✅ YES | ✅ YES | **ENTERPRISE** | ✅ YES | ✅ YES | ❌ NO | `INSTALL_APP` | ✅ ALLOW | `INSTALLED` |
+| ✅ YES | - | - | - | - | ✅ YES | `BOOT_APP` | ❌ DENY | `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 Version Header Format
+
+The `%% @spec-version` comment MUST be the **first line** of the `.spec.md` file:
+
+```markdown
+%% @spec-version 1.0.0
+%% @domain payment
+%% @feature refund-flow
+```
+
+### 4.3 Audit History (Change Log)
+
+Each change MUST append a row to the **Change History** table at the bottom of the `.spec.md` file:
+
+```
+%% @spec-version 1.1.0
+
+## Change History
+| Version | Date | Author | Change Description | Change Type |
+| --- | --- | --- | --- | --- |
+| 1.1.0 | 2025-06-01 | AI | Added refund retry logic state | MINOR |
+| 1.0.0 | 2025-05-15 | AI | Initial spec creation | MAJOR |
+```
+
+## 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]
+```
+
+## UNIVERSAL RULE
+
+The UNIVERSAL RULE is now integrated into the main processing diagram at the top. Its essence:
+
+**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.
+
+```mermaid
+%% @spec-version v2.0.0
+%% @protocol-version 1.0.0
+stateDiagram-v2
+    [*] --> CheckSpec: Before any action — verify spec exists
+
+    state CheckSpec {
+        SpecExists --> Allowed: Proceed with requested skill.
+        SpecNotFound --> Denied: Only md-new / md-audit allowed.
+    }
+
+    Denied --> [*]: Halt — "No .spec.md file found. Use md-new or md-audit."
+    Allowed --> Action: Execute requested skill.
+    Action --> Verify: Validate output.
+    Verify --> [*]: Success.
+    Verify --> Action: Retry if criteria not met.