mddd-cli 3.3.1 → 4.0.0

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

package/bin/cli.spec.md

@@ -1,11 +1,11 @@
-# CLI Module | v4.0.0 (Stable)
+# CLI Module | v4.2.0 (Stable)
 
 ## 1. Flow Contract (Mermaid)
 
 ### 1.1 Topologia Atual (As-Is)
 
 ```mermaid
-%% @spec-version v4.0.0
+%% @spec-version v4.2.0
 graph TD
     subgraph "CLI Entry (bin/cli.js)"
         A[bin/cli.js: Commander Router] --> B[delegate to ./commands/init.js]
@@ -21,9 +21,13 @@ graph TD
         D --> E
         E --> F[fs/promises]
     end
+
+    subgraph "External Dependencies"
+        F --> G["@mermaid-js/mermaid-cli"]
+    end
 ```
 
-O diagrama acima reflete a arquitetura final e estável pós-refatoração: separação clara entre CLI Entry, Commands Layer e Shared Services, com injeção de dependência do `FileSystemService`.
+O diagrama acima reflete a arquitetura final e estável pós-refatoração: separação clara entre CLI Entry, Commands Layer e Shared Services, com injeção de dependência do `FileSystemService`. O `@mermaid-js/mermaid-cli` é uma dependência externa instalada junto com o pacote para renderização de diagramas Mermaid.
 
 ## 2. Decision Matrix
 
@@ -33,6 +37,7 @@ O diagrama acima reflete a arquitetura final e estável pós-refatoração: sepa
 | `src/commands/init.js` | ✅ YES | Modular / Co-located | Contém prompts + delega para `InitService` | ✅ **ALLOW** | `v3.0.0` |
 | `src/services/InitService.js` | ✅ YES | Clean / Service | Orquestra criação de system_prompt e skills | ✅ **ALLOW** | `v3.0.0` |
 | `src/services/FileSystemService.js` | ✅ YES | Clean / Service | Abstrai `fs/promises` com DI | ✅ **ALLOW** | `v3.0.0` |
+| `@mermaid-js/mermaid-cli` | N/A | External Dependency | Renderização de diagramas Mermaid via CLI | ✅ **ALLOW** | `v4.2.0` |
 
 ### Fatores Primitivos de Qualidade
 
@@ -57,6 +62,7 @@ O diagrama acima reflete a arquitetura final e estável pós-refatoração: sepa
 | 2026-05-27 | Cline (Agent-Actor) | v3.0.0 | **MAJOR Mutation (v2.0.0 → v3.0.0):** Removidos comandos `new`, `edit`, `audit` e `impl` do escopo do CLI. Diagramas As-Is e To-Be simplificados para refletir apenas o comando `init` restante. Matriz de decisão e fatores de acoplamento atualizados. |
 | 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. |
 
 ### Análise de Qualidade
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mddd-cli",
-  "version": "3.3.1",
+  "version": "4.0.0",
   "description": "Official CLI for modular, co-located, and versioned Mermaid Diagram Driven Development (MDDD).",
   "type": "module",
   "exports": "./bin/cli.js",
@@ -38,6 +38,7 @@
   },
   "homepage": "https://github.com/JulioCRFilho/mermaid-diagram-driven-development#readme",
   "dependencies": {
+    "@mermaid-js/mermaid-cli": "^11.15.0",
     "commander": "^12.0.0",
     "picocolors": "^1.0.0"
   }

package/src/commands/init.js

@@ -1,319 +1,47 @@
 #!/usr/bin/env node
 
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
 import pc from 'picocolors';
 
-/**
- * PROMPT SYSTEM CONTENT: the full MDDD universal system prompt text.
- * (Embedded here to maintain co-location; refactored from the monolithic cli.js)
- */
-export const SYSTEM_PROMPT_CONTENT = `# Mermaid Diagram Driven Development (MDDD) Protocol
-
-You are an engineering agent operating strictly under MDDD. Your cognitive processing is guided by visual topologies and truth tables, completely eliminating text-based specification ambiguity.
-
-\`\`\`mermaid
-%% @spec-version v1.0.0
-stateDiagram-v2
-    [*] --> ReadSpecification: User Trigger Fired
-    ReadSpecification --> CheckDecisionMatrix: Evaluate Primitive Factors
-    CheckDecisionMatrix --> HaltWithConflict: Constraint Violation / Feature Creep
-    CheckDecisionMatrix --> ExecuteAction: Strict Match Confirmed
-    ExecuteAction --> MutateState: Apply File/Code Changes
-    MutateState --> UpdateVersionHeader: Apply Semantic Version Rules
-    UpdateVersionHeader --> [*]
-\`\`\`
-
-## 1. Co-location Architecture Tree
-
-src/
-└── [domain]/
-    ├── [domain_name].spec.md     # 🌎 Macro Module Domain
-    └── [feature_name]/
-        ├── [feature_name].spec.md # 🔬 Micro Flow Contract + Decision Matrix
-        └── [feature_name].* # 💻 Target Production Code File (Any Extension)
-
-## 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]
-\`\`\`
-
-## 3. Core Behavioral Framework Matrix
-
-| User Context | Target Spec Header | Human Request Path | Diagram Change Impact | AI Core Rule / Mandate / Ironclad Clause |
-| :---: | :---: | :---: | :---: | :--- |
-| | | | - | **MISSING** | - | - | Never remove, omit, or bypass the version tag from files. |
-| | | | Code Change Needed | **SIGNED** | Contradicts Matrix | - | 🛑 **HALT**: Refuse code generation. Demand \`md edit\` to align design first. |
-| | | | Feature Writing | - | Continuous Text Block | - | 📊 **STRUCTURE**: Convert text into tables of primitive factors (yes/no/rigid values). |
-| | | | Command Executed | \`SPEC_VERSION\` | - | Typo / Label Only | Increment Patch (\`X.Y.Z\` -> \`X.Y.Z+1\`) |
-| | | | Command Executed | \`SPEC_VERSION\` | - | New State / Arrow / Matrix Column | Increment Minor (\`X.Y.Z\` -> \`X.Y+1.0\`) |
-| | | | Command Executed | \`SPEC_VERSION\` | - | Structural Breaking / Flow Overhaul | Increment Major (\`X.Y.Z\` -> \`X+1.0.0\`) |
-
-## 4. Anti-Hallucination Guardrails
-1. **No Spec, No Code:** You are strictly forbidden from writing a single line of production code or unit tests if the corresponding \`.spec.md\` file does not exist or does not contain a populated Decision Matrix.
-2. **Implicit Logic Ban:** If a business condition, validation check, or outcome branch is not explicitly listed as a row or column in the Decision Matrix, it does not exist. Do not assume, extrapolate, or invent fallback behaviors.
-3. **Strict State Isolation:** When handling a micro feature, you cannot introduce global states or modify sibling domains unless instructed via explicit macro architectural mapping updates.
-4. **Idempotent Full-File Output Mandate:** You are completely forbidden from using code placeholders, truncating files, or emitting partial snippets (e.g., "// rest of class unchanged", "/* TODO */"). Every code generation action must output the entire, clean, compile-ready file from scratch, ensuring perfect context preservation.
-5. **Spec-First Ordering Mandate:** You are strictly forbidden from editing, modifying, or generating any production code file (.js, .ts, .py, .go, etc.) before the corresponding co-located \`.spec.md\` file has been created or updated to reflect the intended changes. The \`.spec.md\` must always be written or updated first — the spec is the source of truth, and code is derived from it. Violating this ordering constitutes a direct MDDD protocol breach and invalidates the entire change cycle.`;
+import mdNewContent from '../skills/md-new/content.js';
+import mdEditContent from '../skills/md-edit/content.js';
+import mdAuditContent from '../skills/md-audit/content.js';
+import mdImplContent from '../skills/md-impl/content.js';
+import { GITHUB_WORKFLOW_CONTENT } from '../workflows/mddd-preview.yml.js';
 
 /**
- * Skills content map: skill name -> SKILL.md content.
+ * Build the SKILLS map from co-located modules.
+ * @type {Record<string, string>}
  */
-export const SKILLS = {
-  'md-new': `[ROLE: ARCHITECT] [STRICT CONTRACT]
-
-\`\`\`mermaid
-%% @spec-version v1.1.0
-stateDiagram-v2
-    [*] --> TargetVerification
-    TargetVerification --> StopAndSwitchToEdit: .spec.md File Already Exists
-    TargetVerification --> EvaluateContext: File Does Not Exist
-    
-    state EvaluateContext {
-        [*] --> CheckDirectoryDepth
-        CheckDirectoryDepth --> InferMacro: Target is Domain Root (e.g., src/domain)
-        CheckDirectoryDepth --> InferMicro: Target is Sub-Feature (e.g., src/domain/feature)
-    }
-
-    InferMacro --> ExecCliNew: Apply stateDiagram-v2 Template
-    InferMicro --> ExecCliNew: Apply graph LR + Matrix Template
-    
-    ExecCliNew --> AwaitHumanReview: Run "md new [path]" & Populate Blueprint
-    AwaitHumanReview --> [*]: Pause Code & Test Generation
-\`\`\`
-
-### Operational Execution Matrix
-
-| File Exists? | Path Depth Type | Parent Indicated? | CLI Execution Syntax | Target Payload Blueprint | Next AI Action |
-| :---: | :---: | :---: | :--- | :--- | :---: |
-| ✅ YES | - | - | *None* (Aborted) | *None* | 🛑 **STOP** (Call md-edit instead) |
-| ❌ NO | Domain Root | ❌ NO | \`md new [domain_path]\` | \`stateDiagram-v2\` Placeholder Domain Map | ⏳ **AWAIT_VISUAL_APPROVAL** |
-| ❌ NO | Sub-Feature | ❌ NO | \`md new [feature_path]\` | \`graph LR\` + Auto-scanned parent link reference | ⏳ **AWAIT_VISUAL_APPROVAL** |
-| ❌ NO | Sub-Feature | ✅ YES | \`md new [feature_path] -p[parent]\` | \`graph LR\` + Explicit link injected to designated Parent | ⏳ **AWAIT_VISUAL_APPROVAL** |
-
-### Automation & Inference Ironclad Rules
-1. **Deterministic Inference:** You must strictly follow the directory depth. If the target path is a top-level domain folder inside your source root, treat it as a Module Macro. If it is nested inside a domain, it is a Micro Feature. Never ask the user to declare this.
-2. **Implicit Parent Binding:** When creating a Sub-Feature without an explicit \`-p\` parameter, acknowledge that the CLI tool will automatically scan and mutate the nearest parent macro file via recursive climbing. You must read the updated parent immediately after execution to synchronize your internal context map.
-3. Agnostic Blueprint Initialization: When generating the initial blueprint files, you must scan the neighboring files in the target domain directory to identify the current programming language and framework conventions. Adapt your placeholder references to strictly pair with the localized file architecture.`,
-
-  'md-edit': `[ROLE: ARCHITECT] [STRICT CONTRACT]
-
-\`\`\`mermaid
-%% @spec-version v1.2.0
-graph LR
-    A[Read Target .spec.md] --> B[Parse Current SPEC_VERSION]
-    B --> C[Apply Mermaid/Matrix Adjustments]
-    C --> D{Evaluate Mutation Scope}
-    
-    D -->|Typo / Label Fix| E[Increment Patch: Bump Z in X.Y.Z]
-    D -->|New Node / Flow Path / Factor| F[Increment Minor: Bump Y in X.Y.Z]
-    D -->|Breaking Overhaul / Restructure| G[Increment Major: Bump X in X.Y.Z]
-    
-    E --> H[Validate Mermaid Syntax]
-    F --> H
-    G --> H
-    
-    H -->|Syntax Valid| I[Write .spec.md to Disk with Updated Version]
-    H -->|Syntax Invalid| J[🛑 HALT: Abort & Ask Human]
-    I --> K{Spec Status Assessment}
-    K -->|Is draft| L[Tag as draft proposal - AWAIT_USER_VALIDATION]
-    K -->|Is stable| M[Tag as stable - STALE_LOCKED]
-    L --> N[Append Audit History Entry]
-    M --> N
-    N --> O[Persist Updated File]
-    O --> [*]
-\`\`\`
-
-### Evolution Versioning Matrix
-
-| Structural Change Type | Adds Factor Column? | Adds Transition Node/Arrow? | Label / Typo Corrections Only? | Semantic Version Modification | Spec Status After Edit | Target AI State |
-| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
-| Complete Business Overhaul | - | - | - | **MAJOR Mutation (X.Y.Z -> X+1.0.0)** | **draft** (proposal) | ⏳ **AWAIT_USER_VALIDATION** |
-| New Context Conditional Branch | ✅ YES | - | - | **MINOR Mutation (X.Y.Z -> X.Y+1.0)** | **draft** (proposal) | ⏳ **AWAIT_USER_VALIDATION** |
-| New UI Flow Step / Lifecycle State | ❌ NO | ✅ YES | - | **MINOR Mutation (X.Y.Z -> X.Y+1.0)** | **draft** (proposal) | ⏳ **AWAIT_USER_VALIDATION** |
-| Visual Spacing / Text Refinement | ❌ NO | ❌ NO | ✅ YES | **PATCH Mutation (X.Y.Z -> X.Y.Z+1)** | **stable** (locked) | ✅ **STABLE_LOCKED** |
-
-### Mutation Integrity Ironclad Rules
-1. **Incremental SemVer Locking:** You must read the existing \`SPEC_VERSION\` from the file header before modifying it. Never reset, guess, or overwrite the version to a lower state. Bumping Minor explicitly drops the patch version to zero (\`X.Y.Z\` -> \`X.Y+1.0\`). Bumping Major explicitly drops both minor and patch to zero (\`X.Y.Z\` -> \`X+1.0.0\`).
-2. **Strict Syntax Guard:** Before writing the modifications to disk, execute an internal mental compilation of the Mermaid syntax. If any arrow (\`-->\`), state connector, or label syntax breaks the official Mermaid spec, immediately halt execution and report the error to the user without modifying the file.
-3. **Audit History Log Requirement:** Every time you perform an edit, you must append a new row to the markdown table inside the \`<details><summary>Click to expand</summary>...</details>\` block at the bottom of the file, containing the current date, your agent identity, the new version number, and a concise summary of the changes made.
-4. **Node ID Immutability:** When adding new transitions or nodes to an existing graph, you are strictly forbidden from altering, renaming, or refactoring the identifiers (IDs) of existing states/nodes unless explicitly requested by the user.
-5. **Draft vs Stable Status Tagging:** Every edited \`.spec.md\` file MUST have its status explicitly declared after the \`SPEC_VERSION\` header. Structural changes (major/minor) that alter behavior MUST be tagged as \`draft\` (proposal) until the corresponding code is implemented and verified. Non-structural changes (patch/typographical) may remain or become \`stable\` (locked) immediately. The status format is: \`**SPEC_VERSION: vX.Y.Z — [draft|stable]**\`.
-6. **Spec File Write Mandate:** After computing the new version and validating syntax, you **MUST** write the updated \`.spec.md\` file to disk. The edit cycle is not complete until the file is persisted with the updated version header, modified diagram/matrix, and audit history entry.`,
-
-  'md-audit': `[ROLE: SECURITY & QUALITY AUDITOR] [STRICT CONTRACT]
-
-\`\`\`mermaid
-%% @spec-version v1.2.0
-stateDiagram-v2
-    [*] --> AnalyzeLegacyCode: Evaluate code quality, conciseness, and coupling
-    AnalyzeLegacyCode --> FileSystemCheck
-    
-    state FileSystemCheck {
-        [*] --> CheckCoLocation
-        CheckCoLocation --> CreateMissingSpec: Target Co-located .spec.md Missing
-        CheckCoLocation --> AppendToExisting: Target Co-located .spec.md Exists
-    }
-    
-    CreateMissingSpec --> RenderTopology: Create new co-located .spec.md
-    AppendToExisting --> InjectAuditBlock: Target Existing File Preservation Map
-    
-    state RenderTopology {
-        [*] --> CodeIsClean: Map exact architecture as-is (v1.0.0 - stable)
-        [*] --> CodeIsChaotic: Draw BOTH current real logic AND ideal target refactored graph (v1.0.0 - draft)
-    }
-    
-    RenderTopology --> WriteToAuditTag: Inject payloads inside <details> block
-    InjectAuditBlock --> WriteToAuditTag: Append to existing <details> block without overwriting business specs
-    WriteToAuditTag --> EnforceImmutability: Lock Production Code File
-    EnforceImmutability --> SpecFileGuaranteed: Validate .spec.md Exists and Is Populated
-    SpecFileGuaranteed --> [*]
-\`\`\`
-
-### Reverse Engineering & Auto-Repair Decision Matrix
-
-| Source File State | Co-located .spec.md Exists? | Code Design Assessment | Target Output Destination | Code File Manipulation Allowed? | Initial Compiled Version | .spec.md Creation Guarantee |
-| :--- | :---: | :---: | :--- | :---: | :---: | :---: |
-| Legacy Code Active | ✅ YES | Clean / Modular | Append to existing \`<details><summary>Audit History</summary>\` | ❌ **FORBIDDEN (Immutability)** | Retain Current | ✅ **GUARANTEED** (Updated) |
-| Legacy Code Active | ✅ YES | Chaotic / Coupled | Append to existing \`<details><summary>Audit History</summary>\` | ❌ **FORBIDDEN (Immutability)** | Retain Current | ✅ **GUARANTEED** (Updated) |
-| Legacy Code Active | ❌ NO | Clean / Modular | Generate Spec File + Map Current Logic | ❌ **FORBIDDEN (Immutability)** | \`v1.0.0 - stable\` | ✅ **GUARANTEED** (Created) |
-| Legacy Code Active | ❌ NO | Chaotic / Coupled | Generate Spec File + Map Current Logic AND Proposed Refactoring | ❌ **FORBIDDEN (Immutability)** | \`v1.0.0 - draft\` | ✅ **GUARANTEED** (Created) |
-
-### Missing Spec Auto-Repair Blueprint Requirements
-* **Enforce Section Injections:** Every generated specification file must structurally enforce: 
-  1. \`SPEC_VERSION: v1.0.0\` metadata header at the very top.
-  2. \`stateDiagram-v2\` or \`graph LR\` derived exactly from code logic behaviors.
-  3. \`Decision Matrix\` tables filled if the code contains conditional execution branches.
-  4. An isolated \`<details><summary>Audit History</summary>...</details>\` block at the bottom containing the specific code review analytics.
-
-### Quality Assurance & Immutability Ironclad Rules
-1. **Absolute Immutability Command:** Under no circumstances are you allowed to patch, alter, or modify the target production code file during the \`md-audit\` cycle. Your execution scope is strictly limited to observation and documentation within the Markdown specification file.
-2. **Preservation Guarantee:** When appending an audit report to an existing \`.spec.md\` file, you must read the file completely and guarantee that the business requirements, main diagrams, and current decision matrices are left untouched. You are only allowed to inject rows inside the \`<details>\` audit history block.
-3. **Chaotic Code Double-Mapping:** If you evaluate the legacy code as chaotic or highly coupled, you must not replace the current reality with your ideal version. You are required to draw the current graph (flawed as it is) to serve as a baseline, and then provide a separate, clearly labeled Mermaid graph showing the suggested refactored topology.
-4. **Spec Creation Guarantee:** Regardless of whether the co-located \`.spec.md\` file existed before the audit cycle or not, you **MUST** ensure that at the end of the \`md-audit\` process a valid \`.spec.md\` file exists in the target directory. If it did not exist: create it from scratch with all required sections. If it did exist: update it by appending the audit block. Never leave the audit target without a \`.spec.md\` file.
-
-**Rule:** UNDER NO CIRCUMSTANCES MAY YOU COMPLETE AN \`md-audit\` CYCLE WITHOUT A CO-LOCATED \`.spec.md\` FILE.
-`,
-
-  'md-impl': `[ROLE: SOFTWARE ENGINEER] [STRICT CONTRACT]
-
-\`\`\`mermaid
-%% @spec-version v1.2.0
-graph TD
-    A[Ingest Signed .spec.md] --> B[Parse Matrix Rows & Version Header]
-    B --> C{Verify Code/Chat Request}
-    
-    C -->|Matches Decision Matrix Rows 100%| D[Check File Target State]
-    C -->|Human Asks to Skip/Add Extraneous Scope| E[Trigger Prompt Injection Defense]
-    
-    D -->|New File| F[Generate Full Structural Code from Scratch]
-    D -->|Existing File| G[Idempotent Overwrite: Read & Output Full File]
-    
-    F --> H[Generate Truth-Table Unit Tests]
-    G --> H
-    
-    H --> I{Tests Pass 100%?}
-    I -->|Yes| J[Promote .spec.md from draft to stable]
-    I -->|No| K[Fix Code/Tests & Retry]
-    
-    J --> L[Update SPEC_VERSION to vSameVersion - stable]
-    L --> M[Append Audit History: impl complete]
-    M --> N[Persist Updated .spec.md to Disk]
-    N --> [*]
-    
-    E --> O[Refuse Coding & Demand Spec Refinement via md-edit]
-    O --> [*]
-\`\`\`
-
-### Injection Defense & Execution Guard Matrix
-
-| Spec Contract Signed? | Chat Prompt Code Alignment | Human Requests Bypassing Spec Matrix? | Core AI Action Authorized | Error Response Pattern |
-| :---: | :---: | :---: | :--- | :--- |
-| ❌ NO | - | - | ❌ **DENY GENERATION** | Demand invocation of \`md-new\` or \`md-audit\` |
-| ✅ YES | ❌ Out-of-bounds | - | ❌ **DENY GENERATION** | "Please use the md-edit command to update the diagram..." |
-| ✅ YES | - | ✅ YES (Feature Creep) | ❌ **DENY GENERATION** | "Please use the md-edit command to update the diagram..." |
-| ✅ YES | ✅ 100% Rigid Match| ❌ NO | ✅ **ALLOW SOLID CODEGEN** | Complete compliance code + 100% matrix row unit tests |
-
-### Production Implementation & Codegen Ironclad Rules
-1. **The Matrix Test Alignment Mandate:** Your unit test suite must match the Decision Matrix row by row. For every single row present in the specification's truth table, you are strictly required to build at least one explicit, dedicated unit test case mapping those precise primitive factors to that exact outcome.
-2. **Anti-Placeholder Clause:** You are absolutely forbidden from generating incomplete code structures, omitting code sections, or using placeholders like \`// TODO\`, \`// implementation goes here\`, or \`// rest of the class remains unchanged\`. You must always output the complete, compile-ready, and production-grade file layout.
-3. **Strict SOLID Compliance:** Every piece of logic generated under this cycle must follow strict Clean Architecture principles and SOLID patterns. If the specification implies a new conditional branch, you must implement it using polymorphism or structured strategies rather than compounding nested \`if-else\` or pattern-matching anti-patterns unless explicitly dictated by the diagram topology.
-4. **Draft-to-Stable Promotion Duty:** After all implementation and tests pass successfully, you **MUST** update the co-located \`.spec.md\` file to promote its status from \`draft\` to \`stable\`. The version number stays the same — only the status suffix changes. This marks the spec as implemented and locked.
-5. **Spec File Lock After Implementation:** The \`.spec.md\` file version header must reflect the final implemented state: \`**SPEC_VERSION: vX.Y.Z — stable**\`. This signals to all downstream agents that the design is no longer a proposal and the code matches the spec.`,
+const SKILLS = {
+  'md-new': mdNewContent,
+  'md-edit': mdEditContent,
+  'md-audit': mdAuditContent,
+  'md-impl': mdImplContent,
 };
 
 /**
-* GitHub Actions workflow YAML for automated full specification and native Mermaid preview on PRs.
-* Injects the complete markdown file, relying on GitHub's native rendering engines.
-*/
-export const GITHUB_WORKFLOW_CONTENT = [
-  "name: 🗺️ MDDD Full Spec Preview",
-  "",
-  "on:",
-  "  pull_request:",
-  "    paths:",
-  "      - '**/*.spec.md'",
-  "",
-  "jobs:",
-  "  render-preview:",
-  "    runs-on: ubuntu-latest",
-  "    permissions:",
-  "      pull-requests: write",
-  "      contents: read",
-  "",
-  "    steps:",
-  "      - name: ⬇️ Checkout Repository",
-  "        uses: actions/checkout@v4",
-  "        with:",
-  "          fetch-depth: 0", // CRUCIAL: Traz o histórico completo para o git diff funcionar
-  "",
-  "      - name: 📸 Build Preview Comment",
-  "        id: build-comment",
-  '        run: |',
-  '          echo "comment<<EOF" >> "$GITHUB_OUTPUT"',
-  '          echo "### 🗺️ MDDD - Design Changes Detected!" >> "$GITHUB_OUTPUT"',
-  '          echo "Review the proposed specification and visual topology below before approving." >> "$GITHUB_OUTPUT"',
-  '          echo "" >> "$GITHUB_OUTPUT"',
-  "",
-  '          # Busca os arquivos modificados comparando dinamicamente com a branch destino do PR',
-  '          CHANGED=$(git diff --name-only "origin/${{ github.base_ref }}...HEAD" -- "*.spec.md" 2>/dev/null || echo "")',
-  "",
-  "          for file in $CHANGED; do",
-  '            [ -f "$file" ] || continue',
-  '            echo "" >> "$GITHUB_OUTPUT"',
-  '            echo "#### 📄 File: \`${file}\`" >> "$GITHUB_OUTPUT"',
-  '            echo "" >> "$GITHUB_OUTPUT"',
-  '            echo "<details open>" >> "$GITHUB_OUTPUT"',
-  '            echo "<summary>Click to collapse full specification preview</summary>" >> "$GITHUB_OUTPUT"',
-  '            echo "" >> "$GITHUB_OUTPUT"',
-  "",
-  '            # Injeta o conteúdo completo do arquivo markdown',
-  '            cat "$file" >> "$GITHUB_OUTPUT"',
-  '            echo "" >> "$GITHUB_OUTPUT"',
-  "",
-  '            echo "</details>" >> "$GITHUB_OUTPUT"',
-  '            echo "" >> "$GITHUB_OUTPUT"',
-  "          done",
-  "",
-  '          echo "EOF" >> "$GITHUB_OUTPUT"',
-  "",
-  "      - name: 💬 Comment Preview on PR",
-  "        uses: thollander/actions-comment-pull-request@v2",
-  "        with:",
-  '          message: "${{ steps.build-comment.outputs.comment }}"',
-  "          comment_tag: 'mddd-design-preview'",
-].join('\n');
+ * Resolve and read system_prompt.md from the project root.
+ * @returns {string}
+ */
+function readSystemPrompt() {
+  const currentFile = fileURLToPath(import.meta.url);
+  const rootDir = path.resolve(path.dirname(currentFile), '..', '..');
+  const promptPath = path.join(rootDir, 'system_prompt.md');
+  return readFileSync(promptPath, 'utf-8');
+}
 
 /**
- * Executes the \`md init\` command.
+ * Executes the `md init` command.
  * @param {import('../services/InitService.js').InitService} initService
  * @returns {Promise<void>}
  */
 export async function execute(initService) {
-  await initService.createSystemPrompt(SYSTEM_PROMPT_CONTENT);
+  const systemPrompt = readSystemPrompt();
+
+  await initService.createSystemPrompt(systemPrompt);
   await initService.createSkills(SKILLS, (msg) => console.log(msg));
   await initService.createGitHubWorkflow(GITHUB_WORKFLOW_CONTENT, (msg) => console.log(msg));
 

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

@@ -0,0 +1,52 @@
+export default `[ROLE: SECURITY & QUALITY AUDITOR] [STRICT CONTRACT]
+
+\`\`\`mermaid
+%% @spec-version v1.3.0
+stateDiagram-v2
+    [*] --> Evaluation: Quality Assessment
+    Evaluation --> MakeSpec: Co-located .spec.md
+
+    state MakeSpec {
+        [*] --> SpecExists: Check for existing .spec.md
+        SpecNotFound --> CreateSpec: Create new .spec.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-is (v1.0.0 - stable)
+        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
+
+    state CheckDiagram {
+        [*] --> DiagramValid: Proceed to next step
+        DiagramInvalid --> RenderTopology: Re-render until valid
+    }
+
+    CheckDiagram --> WriteToAuditTag: Inject payloads inside <details> block
+    WriteToAuditTag --> EnforceImmutability: Lock Production Code File
+    EnforceImmutability --> [*]
+\`\`\`
+
+\`\`\`mermaid
+%% @spec-version v1.3.0
+%% Decision Matrix for EvaluatedCodeIsClean vs EvaluatedCodeIsChaotic
+flowchart TD
+    M[Measure Cyclomatic Complexity] --> A{Aggregate Results}
+    C[Measure Module Coupling] --> A
+    H[Measure Module Cohesion LCOM] --> A
+    V[Count Lint/Code Violations] --> A
+
+    A -->|Complexity < 10 AND Coupling < 3 AND Cohesion > 0.9 AND Violations == 0| Clean[EvaluatedCodeIsClean]
+    A -->|Complexity >= 10 OR Coupling >= 3 OR Cohesion <= 0.9 OR Violations > 0| Chaotic[EvaluatedCodeIsChaotic]
+
+    style Clean fill:#1b5e20,color:#fff
+    style Chaotic fill:#b71c1c,color:#fff
+\`\`\`
+
+`;

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

@@ -0,0 +1,73 @@
+export default `[ROLE: ARCHITECT] [STRICT CONTRACT]
+
+\`\`\`mermaid
+%% @spec-version v1.3.0
+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 @mermaid-js/mermaid-cli to Validate Syntax
+
+    state CheckDiagram {
+        [*] --> TryRender
+        TryRender --> DiagramValid: Render succeeded
+        TryRender --> IncrementRetry: Render failed
+        IncrementRetry --> TryRender: Retry count < 3
+        IncrementRetry --> RenderFailed: Retry count >= 3
+    }
+        
+    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 --> AwaitHumanReview
+    RenderFailed --> AwaitHumanReview: Error: Mermaid CLI validation failed after 3 attempts
+
+    state AwaitHumanReview {
+        [*] --> Approved: Resume CI/CD pipeline
+        [*] --> ChangesRequested: Loop back to ApplyAdjustments
+        [*] --> Aborted: Terminate session
+    }
+    
+    AwaitHumanReview --> [*]: Pause Code & Test Generation
+\`\`\`
+
+\`\`\`mermaid
+%% @spec-version v1.3.0
+%% Decision Matrix for EvaluateScope: TypoFix vs NewNode vs BreakingChange
+flowchart TD
+    M[Mutation Request Contains...] --> A{Evaluate Factors}
+
+    T[Only label / text changes] --> A
+    N[New states / flows / factors added] --> A
+    B[Existing states / flows removed or restructured] --> A
+
+    A -->|"T == true AND N == false AND B == false"| Patch[TypoFix → IncrementPatch]
+    A -->|"N == true AND B == false"| Minor[NewNode → IncrementMinor]
+    A -->|"B == true"| Major[BreakingChange → IncrementMajor]
+
+    style Patch fill:#1b5e20,color:#fff
+    style Minor fill:#0d47a1,color:#fff
+    style Major fill:#b71c1c,color:#fff
+\`\`\`
+`;

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

@@ -0,0 +1,87 @@
+export default `[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 --> [*]
+\`\`\`
+
+\`\`\`mermaid
+%% @spec-version v1.3.1
+%% Decision Matrix for CheckTarget: NewFile vs ExistingFile
+flowchart TD
+    R[Check Target Path...] --> A{Evaluate Factors}
+
+    P[Path does not exist on disk] --> A
+    E[Path exists on disk] --> A
+
+    A -->|"P == true"| NewFile[CheckTarget → NewFile]
+    A -->|"E == true"| ExistingFile[CheckTarget → ExistingFile]
+
+    style NewFile fill:#0d47a1,color:#fff
+    style ExistingFile fill:#e65100,color:#fff
+\`\`\`
+
+\`\`\`mermaid
+%% @spec-version v1.3.1
+%% Decision Matrix for DataLossCheck: No Risk vs Risk Detected
+flowchart TD
+    M[Evaluate Data Loss Risk Factors...] --> A{Aggregate Risk Conditions}
+
+    FF[File exists on disk AND will be overwritten] --> A
+    C[Code changes detected outside spec scope] --> A
+    B[No recent git backup / uncommitted changes] --> A
+    V[User confirmation flag not set] --> A
+
+    A -->|"FF == true OR C == true OR B == true OR V == true"| Risk[Risk Detected → Alert User]
+    A -->|"FF == false AND C == false AND B == false AND V == false"| NoRisk[No Risk → Proceed to GenerateTests]
+
+    style NoRisk fill:#1b5e20,color:#fff
+    style Risk fill:#b71c1c,color:#fff
+\`\`\`
+`;

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

@@ -0,0 +1,45 @@
+export default `[ROLE: ARCHITECT] [STRICT CONTRACT]
+
+\`\`\`mermaid
+%% @spec-version v1.3.0
+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 Blueprint with placeholders
+    GenerateBlueprint --> FormatSpecOutput: Format blueprint into target .spec.md structure
+    FormatSpecOutput --> CheckDiagram: Use npx @mermaid-js/mermaid-cli to Validate 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 --> [*]: Pause Code & Test Generation
+\`\`\`
+`;

package/src/workflows/mddd-preview.yml.js

@@ -0,0 +1,61 @@
+/**
+ * GitHub Actions workflow YAML for automated full specification and native Mermaid preview on PRs.
+ * Extracted from init.js v1.5.0 domain extraction.
+ */
+export const GITHUB_WORKFLOW_CONTENT = [
+  "name: 🗺️ MDDD Full Spec Preview",
+  "",
+  "on:",
+  "  pull_request:",
+  "    paths:",
+  "      - '**/*.spec.md'",
+  "",
+  "jobs:",
+  "  render-preview:",
+  "    runs-on: ubuntu-latest",
+  "    permissions:",
+  "      pull-requests: write",
+  "      contents: read",
+  "",
+  "    steps:",
+  "      - name: ⬇️ Checkout Repository",
+  "        uses: actions/checkout@v4",
+  "        with:",
+  "          fetch-depth: 0", // CRUCIAL: Traz o histórico completo para o git diff funcionar
+  "",
+  "      - name: 📸 Build Preview Comment",
+  "        id: build-comment",
+  '        run: |',
+  '          echo "comment<<EOF" >> "$GITHUB_OUTPUT"',
+  '          echo "### 🗺️ MDDD - Design Changes Detected!" >> "$GITHUB_OUTPUT"',
+  '          echo "Review the proposed specification and visual topology below before approving." >> "$GITHUB_OUTPUT"',
+  '          echo "" >> "$GITHUB_OUTPUT"',
+  "",
+  '          # Busca os arquivos modificados comparando dinamicamente com a branch destino do PR',
+  '          CHANGED=$(git diff --name-only "origin/${{ github.base_ref }}...HEAD" -- "*.spec.md" 2>/dev/null || echo "")',
+  "",
+  "          for file in $CHANGED; do",
+  '            [ -f "$file" ] || continue',
+  '            echo "" >> "$GITHUB_OUTPUT"',
+  '            echo "#### 📄 File: \`${file}\`" >> "$GITHUB_OUTPUT"',
+  '            echo "" >> "$GITHUB_OUTPUT"',
+  '            echo "<details open>" >> "$GITHUB_OUTPUT"',
+  '            echo "<summary>Click to collapse full specification preview</summary>" >> "$GITHUB_OUTPUT"',
+  '            echo "" >> "$GITHUB_OUTPUT"',
+  "",
+  '            # Injeta o conteúdo completo do arquivo markdown',
+  '            cat "$file" >> "$GITHUB_OUTPUT"',
+  '            echo "" >> "$GITHUB_OUTPUT"',
+  "",
+  '            echo "</details>" >> "$GITHUB_OUTPUT"',
+  '            echo "" >> "$GITHUB_OUTPUT"',
+  "          done",
+  "",
+  '          echo "EOF" >> "$GITHUB_OUTPUT"',
+  "",
+  "      - name: 💬 Comment Preview on PR",
+  "        uses: thollander/actions-comment-pull-request@v2",
+  "        with:",
+  '          message: "${{ steps.build-comment.outputs.comment }}"',
+  "          comment_tag: 'mddd-design-preview'",
+].join('\n');

package/src/commands/init.spec.md

@@ -1,265 +0,0 @@
-# init.js — Command Specification
-
-**SPEC_VERSION: v1.4.0 — stable**
-
-## Overview
-
-The `init.js` module implements the `md init` CLI command. It holds the canonical MDDD universal system prompt and the full skill library (`md-new`, `md-edit`, `md-audit`, `md-impl`), delegating file-system persistence to an injected `InitService`.
-
----
-
-## Behavioral Flow (Reverse Engineered)
-
-```mermaid
-%% @spec-version v1.3.0
-stateDiagram-v2
-    [*] --> ExecuteCommand: User runs "md init"
-    ExecuteCommand --> CreateSystemPrompt: initService.createSystemPrompt(content)
-    CreateSystemPrompt --> CreateSkills: initService.createSkills(skillMap, logger)
-    CreateSkills --> CreateGitHubWorkflow: initService.createGitHubWorkflow(workflowYaml)
-    CreateGitHubWorkflow --> ReportSuccess: console.log(…) green messages
-    ReportSuccess --> [*]
-```
-
----
-
-## GitHub Actions Preview Workflow
-
-A partir da v1.3.0, o `md init` também cria/atualiza um workflow do GitHub Actions em `.github/workflows/mddd-preview.yml`. Esse workflow gera previews visuais dos diagramas Mermaid alterados em pull requests que tocam arquivos `.spec.md`.
-
-> **Idempotência garantida:** Se o arquivo `.github/workflows/mddd-preview.yml` já existir, ele será sobrescrito com o conteúdo canônico atual. Isso garante que todos os projetos inicializados com `md init` tenham a versão mais recente do workflow de preview.
-
-```yaml
-name: 🗺️ MDDD Diagram Preview
-
-on:
-  pull_request:
-    paths:
-      - '**/*.spec.md'
-
-jobs:
-  render-preview:
-    runs-on: ubuntu-latest
-    permissions:
-      pull-requests: write
-      contents: read
-
-    steps:
-      - name: ⬇️ Checkout Repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: 📦 Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-
-      - name: 📸 Render Mermaid Diagrams to PNG
-        run: |
-          mkdir -p .github/mddd-previews
-          npm install --no-save @mermaid-js/mermaid-cli puppeteer 2>&1 | tail -2
-
-          # Find changed .spec.md files in this PR
-          CHANGED=$(git diff --name-only "origin/${{ github.base_ref }}...${{ github.sha }}" -- '*.spec.md' 2>/dev/null || echo "")
-
-          for file in $CHANGED; do
-            [ -f "$file" ] || continue
-            echo "📄 Processing: $file"
-
-            # Extract each ```mermaid block to a .mmd temp file using node inline
-            # Note: single-quote heredoc prevents shell expansion of $ and backticks
-            node -e '
-              const fs=require("fs"),p=require("path");
-              const c=fs.readFileSync(process.argv[1],"utf8");
-              const v=c.match(/SPEC_VERSION: v?([\d.]+)/)?.[1]||"0";
-              const r=/```mermaid\n?([\s\S]*?)```/g;
-              let m,i=0;
-              while((m=r.exec(c))!==null){
-                let d=m[1].replace(/^%%.*$/gm,"").trim();
-                if(!d)continue;
-                const n=p.basename(process.argv[1],".spec.md")+"-"+i+".mmd";
-                fs.writeFileSync("/tmp/"+n,"%% @spec-version v"+v+"\n"+d);
-                console.log("  Extracted diagram "+(i+1)+" -> "+n);
-                i++;
-              }
-            ' "$file"
-          done
-
-          for mmd in /tmp/*.mmd; do
-            [ -f "$mmd" ] || continue
-            base=$(basename "$mmd" .mmd)
-            echo "🎨 Rendering $base..."
-            npx -p @mermaid-js/mermaid-cli mmdc -i "$mmd" -o ".github/mddd-previews/$base.png" -b white -w 1200 2>&1 | tail -1 || echo "  ⚠️ Render failed for $base"
-          done
-
-      - name: 💬 Comment Preview on PR
-        uses: thollander/actions-comment-pull-request@v2
-        with:
-          message: |
-            ### 🗺️ MDDD - Alterações de Design Detectadas!
-            Revise a topologia visual proposta abaixo antes de aprovar o código.
-
-            > Os diagramas renderizados estão disponíveis como artefatos da workflow run (seção \"Summary\").
-          comment_tag: 'mddd-design-preview'
-```
-
----
-
-## Embedded Skill Inventory
-
-The `SKILLS` map in `init.js` contains four behavioral sub-specifications. The table below tracks their individual versions and key contract guarantees:
-
-| Skill | Role | Current Version | Key Contract Update |
-| :--- | :--- | :---: | :--- |
-| `md-new` | Architect | v1.1.0 | Domain depth inference + parent binding |
-| `md-edit` | Architect | **v1.2.0** | **Draft vs Stable tagging + Spec file write mandate** |
-| `md-audit` | Security & Quality Auditor | **v1.2.0** | **Spec Creation Guarantee** — .spec.md MUST exist at end of cycle |
-| `md-impl` | Software Engineer | **v1.2.0** | **Draft-to-Stable promotion + Spec lock after implementation** |
-
-> **md-edit v1.2.0 highlights:**
-> - New `Write .spec.md to Disk with Updated Version` node in topology — edit cycle persists the file
-> - New `Spec Status Assessment` branch: structural changes (major/minor) tagged as **draft** (proposal), typographical fixes tagged as **stable** (locked)
-> - New column `Spec Status After Edit` in Evolution Versioning Matrix
-> - New Ironclad Rule #5 (Draft vs Stable Status Tagging): explicit `draft` or `stable` suffix after SPEC_VERSION
-> - New Ironclad Rule #6 (Spec File Write Mandate): edit cycle only complete after file persisted
-
-> **md-audit v1.2.0 highlights:**
-> - New `SpecFileGuaranteed` terminal state in topology: validates that a co-located `.spec.md` exists and is populated before the flow reaches `[*]`
-> - New column `.spec.md Creation Guarantee` in the Reverse Engineering Decision Matrix — all four scenario rows marked `✅ GUARANTEED`
-> - New Ironclad Rule #4 (Spec Creation Guarantee): the agent **must** ensure a valid `.spec.md` file exists after every audit cycle
-> - Final imperative rule: `UNDER NO CIRCUMSTANCES MAY YOU COMPLETE AN md-audit CYCLE WITHOUT A CO-LOCATED .spec.md FILE`
-
-> **md-impl v1.2.0 highlights:**
-> - New test verification gate (`Tests Pass 100%?`) before completion — implementation must pass before promotion
-> - New `Promote .spec.md from draft to stable` state after successful tests
-> - New `Persist Updated .spec.md to Disk` step — the impl cycle writes the promoted spec
-> - New Ironclad Rule #4 (Draft-to-Stable Promotion Duty): after tests pass, promote spec to `stable`
-
----
-
-## System Prompt Guardrails (Section 4)
-
-The `SYSTEM_PROMPT_CONTENT` embedded in `init.js` defines five Anti-Hallucination Guardrails that govern all agent behavior under MDDD:
-
-| # | Guardrail | Purpose |
-| :---: | :--- | :--- |
-| 1 | **No Spec, No Code** | No production code without a `.spec.md` with populated Decision Matrix |
-| 2 | **Implicit Logic Ban** | Business conditions must be explicit in the Matrix |
-| 3 | **Strict State Isolation** | No cross-domain state mutation without macro mapping |
-| 4 | **Idempotent Full-File Output Mandate** | No placeholders, truncations, or partial snippets |
-| 5 | **Spec-First Ordering Mandate** | `.spec.md` MUST be created/updated **before** any production code file — code is derived from spec |
-
-> **Guardrail #5 (v1.2.0):** This guardrail was added to prevent the exact protocol violation that occurred when `init.js` was edited before its `.spec.md`. It explicitly requires that the `.spec.md` file be written or updated first, making the spec the source of truth and code a derived artifact. Violation constitutes a direct MDDD protocol breach.
-
----
-
-## Mermaid Diagram Validation Rules
-
-### 5.1 Forbidden Characters Per Diagram Type
-
-| Diagram Type | Context | Forbidden Characters | Reason |
-| :--- | :--- | :--- | :--- |
-| `stateDiagram-v2` | State/Transition Labels | `:` (colon) | Breaks transition arrow syntax (`-->`). Use `-` or words instead. |
-| `stateDiagram-v2` | State Names | `[]` `()` `{}` `<>` | Reserved delimiters for notes, composities, and forks. Wrap in quotes if unavoidable. |
-| `stateDiagram-v2` | Any Label | `"` `'` (unescaped quotes) | Breaks string parsing inside directives like `%%` comments and labels. |
-| `graph TD/LR/BT/RL` | Node IDs | `()` `[]` `{}` `<>` | Reserved bracket syntax for node shapes. Causes parse failure or shape corruption. |
-| `graph TD/LR/BT/RL` | Node Text Labels | `"` (double quote) | Terminates the label string early if the label itself is quoted. Use single-character alternatives. |
-| `graph TD/LR/BT/RL` | Edge Labels | `\|` (pipe) | `\|` terminates the edge label in `--\|label\|-->` syntax. |
-| `graph TD/LR/BT/RL` | Any Text | `,` `;` | Acts as statement separator in Mermaid parser. Unexpected splits. |
-| `graph TD/LR/BT/RL` | Any Text | `` ` `` (backtick) | Reserved for Markdown code span parsing in newer Mermaid versions. |
-| All Diagram Types | `%%` comment blocks | `{` `}` inside inline comments | Can be misinterpreted as Mermaid directive blocks. |
-| All Diagram Types | Raw Unicode Control Chars | `\u0000`-`\u001F` (except `\n`, `\t`) | Invisible control characters corrupt the SVG renderer output. |
-
-### 5.2 Safe Alternatives Table
-
-| Instead of… | Use… | Example |
-| :--- | :--- | :--- |
-| `:` in state name | `-` or whitespace | `ProcessingComplete` ✅ instead of `Processing:Complete` ❌ |
-| `()` in node label | Wrap entire label in `["..."]` | `A["Process Data (v2)"]` ✅ |
-| `"` inside a label | Remove quotes or use `#quot;` HTML entity | `A["Status is #quot;OK#quot;"]` ✅ |
-| `,` in text | Replace with ` - ` or `&` | `Validate & Transform` ✅ instead of `Validate, Transform` ❌ |
-| Complex special chars | Enclose node text in double-quote brackets `["..."]` | `B["Node with (special) chars & stuff"]` ✅ |
-
-### 5.3 Post-Creation Review Checklist
-
-After writing **every** `.spec.md` file containing a Mermaid diagram block, you **MUST** perform this review:
-
-1. ✅ **Bracket Balance Check**: Count every `[` `]` `(` `)` `{` `}` — each opening must have a matching closing bracket.
-2. ✅ **Colon-Free State Names**: Verify no `:` exists inside state names (exception: `%%` directives and `[*]` pseudo-states).
-3. ✅ **Edge Label Pipes**: Confirm every `|` in edge label syntax is properly paired (`--|label|-->`).
-4. ✅ **Quote Consistency**: Ensure quote marks are balanced and not breaking string boundaries.
-5. ✅ **No Trailing Backslashes**: Check no line ends with `\` unless it is an intentional line continuation.
-6. ✅ **Render Test Mental Simulation**: Trace the diagram visually in your mind — do the arrows point to real nodes? Are all states reachable? No floating edges?
-
-If any of the above checks fail, **correct the diagram before proceeding** to code generation.
-
-### 5.4 Forbidden Pattern Examples
-
-```mermaid
-%% ❌ BAD: Colon in state name breaks transition
-stateDiagram-v2
-    Processing:Data --> Complete   ← BROKEN: colon interpreted as state:description syntax
-
-%% ✅ GOOD: No colon, clear naming
-stateDiagram-v2
-    ProcessingData --> Complete
-```
-
-```mermaid
-%% ❌ BAD: Unescaped comma and parentheses in graph
-graph TD
-    A[Validate, Transform (v2)] --> B   ← BROKEN: comma splits, parens confuse parser
-
-%% ✅ GOOD: Wrapped in double-quote brackets
-graph TD
-    A["Validate, Transform (v2)"] --> B
-```
-
-### 5.5 Enforcement Rule
-
-> **🛑 HALT**: If after review you detect any forbidden character in a Mermaid diagram block, refuse to proceed with code generation. Fix the diagram first. This rule supersedes all other productivity directives.
-
----
-
-## Decision Matrix
-
-| Step | Operation | I/O | Conditional Branch? | Error Handling |
-| :--- | :--- | :--- | :---: | :--- |
-| 1 | `initService.createSystemPrompt(SYSTEM_PROMPT_CONTENT)` | Writes `system_prompt.md` | ❌ No | Delegated to InitService |
-| 2 | `initService.createSkills(SKILLS, logFn)` | Writes `SKILLS/*.md` files | ❌ No | Delegated to InitService |
-| 3 | `initService.createGitHubWorkflow(GITHUB_WORKFLOW_CONTENT)` | Writes `.github/workflows/mddd-preview.yml` | ❌ No | Delegated to InitService |
-| 4 | `console.log(pc.green(…))` | stdout — success report | ❌ No | N/A |
-
-> **Note:** The `SKILLS` map contains four embedded behavioral sub-specifications (`md-new`, `md-edit`, `md-audit`, `md-impl`), each with its own internal topology and decision logic. Those are documented within their respective string values and are not re-instantiated here to avoid duplication. For details on the `md-audit` v1.2.0 updates, see the [Embedded Skill Inventory](#embedded-skill-inventory) section above.
-
----
-
-## Exported Symbols
-
-| Export | Type | Purpose |
-| :--- | :--- | :--- |
-| `SYSTEM_PROMPT_CONTENT` | `string` | Full MDDD protocol prompt text (now includes Guardrail #5: Spec-First Ordering Mandate) |
-| `SKILLS` | `Record<string, string>` | Skill-name → SKILL.md content mapping |
-| `GITHUB_WORKFLOW_CONTENT` | `string` | GitHub Actions workflow YAML for Mermaid diagram preview on PRs |
-| `execute(initService)` | `async function` | Command entry point |
-
----
-
-## Audit History
-
-<details><summary>Click to expand</summary>
-
-| Date | Agent | Version | Change Summary |
-| :--- | :--- | :---: | :--- |
-| 2026-05-28 | Cline (md-audit) | v1.0.0 | Initial reverse-engineered spec from production code. Code classified as **Clean / Modular**. No modifications to `init.js`. |
-| 2026-05-28 | Cline (md-impl) | v1.0.1 | Idempotent full-file overwrite of `init.js`. No behavioral changes — same 3-step flow preserved. Unit tests created under `tests/commands/init.spec.js` with 6/6 passing. SPEC_VERSION bumped from v1.0.0 to v1.0.1 (patch). |
-| 2026-05-28 | Cline (md-edit) | v1.1.0 | Updated `md-audit` skill embedded in `init.js` to v1.2.0: added `SpecFileGuaranteed` terminal state in topology diagram, added `.spec.md Creation Guarantee` column to Decision Matrix, added Ironclad Rule #4 (Spec Creation Guarantee), and reinforced the final imperative rule mandating .spec.md creation on every audit cycle. SPEC_VERSION bumped from v1.0.1 to v1.1.0 (minor — new contract enforcement). |
-| 2026-05-28 | Cline (md-edit) | **v1.2.0** | Added **Guardrail #5 (Spec-First Ordering Mandate)** to `SYSTEM_PROMPT_CONTENT` in `init.js`: explicitly forbids editing production code before the corresponding `.spec.md` file has been created or updated. This prevents the protocol violation of editing `.js` files before `.spec.md` files. Updated `md-edit` skill to v1.2.0 with draft vs stable tagging, spec file write mandate, and evolution matrix update. Updated `md-impl` skill to v1.2.0 with draft-to-stable promotion duty, test verification gate, and spec lock after implementation. SPEC_VERSION bumped from v1.1.0 to v1.3.0 (minor — new GITHUB_WORKFLOW content and createGitHubWorkflow step added). |
-| 2026-05-28 | Cline (md-edit) | **v1.4.0** | **Fix: `xanmanning/mermaid-render-action` removed from GitHub** — substituído por `@mermaid-js/mermaid-cli` (official Mermaid CLI). Workflow agora extrai blocos ```mermaid de arquivos `.spec.md` alterados no PR e renderiza com `mmdc`. Adicionado `actions/setup-node@v4` para Node.js 20. SPEC_VERSION bumped from v1.3.0 to v1.4.0 (minor — structural change to workflow YAML). Status set to **draft** pending implementation. |
-
-> **v1.4.0 (current):** Replaced broken `xanmanning/mermaid-render-action` (repository removed) with official `@mermaid-js/mermaid-cli`. The workflow now: (1) detects changed `.spec.md` files in the PR, (2) extracts Mermaid code blocks using a Node.js inline script, (3) renders each block to PNG using `mmdc` with `-b white -w 1200`. Added `actions/setup-node@v4` step. Comment message updated to reference workflow artifacts instead of raw.githubusercontent.com URLs. SPEC_VERSION bumped from v1.3.0 to v1.4.0 (minor — structural breaking change to workflow topology). Status promoted from **draft** to **stable** — implementation and tests verified. |
-
-> **v1.3.0 (previous):** Added `CreateGitHubWorkflow` state to the behavioral flow diagram. New `GITHUB_WORKFLOW_CONTENT` exported constant containing the GitHub Actions YAML for automated Mermaid diagram preview on PRs. New step 3 in Decision Matrix: `initService.createGitHubWorkflow(GITHUB_WORKFLOW_CONTENT)` writes `.github/workflows/mddd-preview.yml`. Status promoted from **draft** to **stable**. |
-
-</details>