mddd-cli 3.0.1 → 3.1.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.0.1');
+  .version('3.1.0');
 
 // ==========================================
 // COMMAND: md init

package/bin/cli.spec.md

@@ -1,67 +1,49 @@
-# Refactoring Plan: cli | v3.0.0
+# CLI Module | v4.0.0 (Stable)
 
 ## 1. Flow Contract (Mermaid)
 
 ### 1.1 Topologia Atual (As-Is)
 
 ```mermaid
-%% @spec-version v3.0.0
+%% @spec-version v4.0.0
 graph TD
-    subgraph "CLI Entry (cli.js)"
-        A[index.js#!/usr/bin/env node] --> B[Commander: program.parse]
-    end
-
-    subgraph "Command Routing"
-        B --> C[md init]
-    end
-
-    subgraph "md init Action"
-        C --> H[mkdir .agents/skills]
-        C --> I[Write system_prompt.md]
-        C --> J[Write 4 embedded SKILL.md files]
-    end
-```
-
-### 1.2 Topologia Aprovada (To-Be → Refactoring Target)
-
-```mermaid
-%% @spec-version v3.0.0
-graph TD
-    subgraph "CLI Entry (cli.js)"
-        A[bin/cli.js] --> B[Commander Router]
-        B --> C[delegate to ./commands/init.js]
+    subgraph "CLI Entry (bin/cli.js)"
+        A[bin/cli.js: Commander Router] --> B[delegate to ./commands/init.js]
     end
 
     subgraph "Commands Layer"
-        C --> H[InitService.createSystemPrompt]
-        C --> I[InitService.createSkills]
+        B --> C[InitService.createSystemPrompt]
+        B --> D[InitService.createSkills]
     end
 
     subgraph "Shared Services"
-        H --> Q[FileSystemService]
-        I --> Q
-        Q --> R[fs/promises]
+        C --> E[FileSystemService.writeFile]
+        D --> E
+        E --> F[fs/promises]
     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`.
+
 ## 2. Decision Matrix
 
-| Código Atual | Co-located .spec.md Exists? | Design Assessment | Ação de Auditoria | Manipulação de Código Permitida? | Versão Inicial |
+| Código Atual | Co-located `.spec.md` Exists? | Design Assessment | Ação de Implementação | Manipulação de Código Permitida? | Versão Inicial |
 | :--- | :---: | :---: | :--- | :---: | :---: |
-| `bin/cli.js` (421 linhas) | ❌ NO | Caótico / Acoplado | Auto-gerar Spec + Mapear Lógica Atual E Proposta | ❌ **FORBIDDEN (Immutability)** | `v1.0.0` |
-| `src/commands/init.js` + `src/services/InitService.js` + `src/services/FileSystemService.js` (refatorado) | ✅ YES (this spec) | Refatorado / Modular | Aprovado com diagrama To-Be como alvo de implementação | ✅ **ALLOW (Refactoring)** | `v3.0.0` |
+| `bin/cli.js` (37 linhas) | ✅ YES | Clean / CLI Entry | Delega para `src/commands/init.js` | ✅ **ALLOW** | `v1.0.0` |
+| `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` |
 
-### Fatores Primitivos de Acoplamento
+### Fatores Primitivos de Qualidade
 
 | Fator | Valor | Impacto |
 | :--- | :---: | :--- |
-| Arquivo único monolítico? | ✅ YES | Acoplamento extremo; todas as responsabilidades no mesmo closure |
-| Lógica de template embutida? | ✅ YES | 4 skills + 2 templates inline no código (string templates >20KB) |
-| Duplicação entre `new` e `audit`? | ❌ N/A (removido) | Comandos `new`, `edit`, `audit` e `impl` foram removidos do escopo |
-| Tratamento de erros inconsistente? | ❌ N/A (removido) | Comandos `edit`/`audit`/`impl` removidos |
-| Sem separação CLI/Business? | ❌ NO | `init` permanece com separação CLI/Business via `src/commands/init.js` |
-| Lógica de crawling de diretório isolada? | ❌ N/A (removido) | `findClosestMacro` removido junto com comando `new` |
-| Código testável? | ❌ NO | Sem módulos exportados; dependência direta de `fs`, `path` sem injeção |
+| CLI Entry desacoplado? | ✅ YES | `bin/cli.js` com 37 linhas, apenas Commander + delegação |
+| Lógica de template co-localizada? | ✅ YES | `SYSTEM_PROMPT_CONTENT` e `SKILLS` em `src/commands/init.js` |
+| Separação CLI/Business? | ✅ YES | Camadas bem definidas: CLI → Commands → Services |
+| Serviços com injeção de dependência? | ✅ YES | `FileSystemService` aceita mock no construtor |
+| Código testável? | ⚠️ PARCIAL | Serviços são testáveis; `bin/cli.js` não exporta funções |
+| Escopo reduzido? | ✅ YES | Apenas comando `init` — comandos removidos foram eliminados |
 
 ## 3. Audit History
 
@@ -73,12 +55,12 @@ graph TD
 | 2026-05-27 | MDDD-Audit Agent (Cline) | v1.0.0 | Auditoria inicial. Código classificado como **Caótico/Acoplado**. Diagrama As-Is documenta a topologia real (monolítica). Diagrama To-Be propõe separação em Commands Layer + Shared Services + Template Engine + Testes. Decisão de imutabilidade: código de produção não foi modificado. |
 | 2026-05-27 | Cline (Agent-Actor) | v2.0.0 | **MAJOR Mutation (v1.0.0 → v2.0.0):** Aprovada refatoração estrutural do monolito `bin/cli.js` (421 linhas) para arquitetura modular: Commands Layer (`src/commands/*.js`) + Shared Services (`src/services/*.js`) + Template Engine (`src/services/TemplateFactory.js`) + Unit Tests. Removida restrição FORBIDDEN (Immutability). Diagrama To-Be promovido a alvo de implementação oficial. |
 | 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. |
 
 ### Análise de Qualidade
 
-- **Acoplamento**: ⚠️ **MÉDIO** - O comando `init` restante ainda reside em `bin/cli.js` mas delega para `src/commands/init.js`.
-- **Coesão**: ✅ **ALTA** - Escopo reduzido a apenas inicialização do ambiente MDDD.
-- **Testabilidade**: ⚠️ **MÉDIA** - Serviços são injetados via construtor, mas `bin/cli.js` não exporta funções para teste unitário isolado.
-- **Manutenibilidade**: ✅ **ALTA** - Código simplificado com apenas um comando e clara separação de responsabilidades.
-
-</details>
+- **Acoplamento**: ✅ **BAIXO** — CLI Entry com 37 linhas delega para Commands Layer; Services são independentes com DI.
+- **Coesão**: ✅ **ALTA** — Cada módulo tem responsabilidade única e bem definida.
+- **Testabilidade**: ⚠️ **PARCIAL** — `InitService` e `FileSystemService` são testáveis via injeção de dependência; `bin/cli.js` permanece sem exportações para teste unitário.
+- **Manutenibilidade**: ✅ **ALTA** — Arquitetura limpa com 3 camadas claras e escopo reduzido a apenas `init`.

package/package.json

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

package/src/commands/init.js

@@ -1,3 +1,5 @@
+#!/usr/bin/env node
+
 import pc from 'picocolors';
 
 /**
@@ -43,18 +45,19 @@ graph TD
 
 | 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\`) |
+| | | - | **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.`;
+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.`;
 
 /**
  * Skills content map: skill name -> SKILL.md content.
@@ -99,7 +102,7 @@ stateDiagram-v2
   'md-edit': `[ROLE: ARCHITECT] [STRICT CONTRACT]
 
 \`\`\`mermaid
-%% @spec-version v1.1.0
+%% @spec-version v1.2.0
 graph LR
     A[Read Target .spec.md] --> B[Parse Current SPEC_VERSION]
     B --> C[Apply Mermaid/Matrix Adjustments]
@@ -113,29 +116,38 @@ graph LR
     F --> H
     G --> H
     
-    H -->|Syntax Valid| I[Save Contract & Halt]
+    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 | Target AI State |
-| :--- | :---: | :---: | :---: | :---: | :---: |
-| Complete Business Overhaul | - | - | - | **MAJOR Mutation (X.Y.Z -> X+1.0.0)** | ⏳ **AWAIT_USER_VALIDATION** |
-| New Context Conditional Branch | ✅ YES | - | - | **MINOR Mutation (X.Y.Z -> X.Y+1.0)** | ⏳ **AWAIT_USER_VALIDATION** |
-| New UI Flow Step / Lifecycle State | ❌ NO | ✅ YES | - | **MINOR Mutation (X.Y.Z -> X.Y+1.0)** | ⏳ **AWAIT_USER_VALIDATION** |
-| Visual Spacing / Text Refinement | ❌ NO | ❌ NO | ✅ YES | **PATCH Mutation (X.Y.Z -> X.Y.Z+1)** | ⏳ **AWAIT_USER_VALIDATION** |
+| 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.`,
+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.1.0
+%% @spec-version v1.2.0
 stateDiagram-v2
     [*] --> AnalyzeLegacyCode: Evaluate code quality, conciseness, and coupling
     AnalyzeLegacyCode --> FileSystemCheck
@@ -146,7 +158,7 @@ stateDiagram-v2
         CheckCoLocation --> AppendToExisting: Target Co-located .spec.md Exists
     }
     
-    CreateMissingSpec --> RenderTopology: Create new colocated .spec.md
+    CreateMissingSpec --> RenderTopology: Create new co-located .spec.md
     AppendToExisting --> InjectAuditBlock: Target Existing File Preservation Map
     
     state RenderTopology {
@@ -157,17 +169,18 @@ stateDiagram-v2
     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 --> [*]
+    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 |
-| :--- | :---: | :---: | :--- | :---: | :---: |
-| Legacy Code Active | ✅ YES | Clean / Modular | Append to existing \`<details><summary>Audit History</summary>\` | ❌ **FORBIDDEN (Immutability)** | Retain Current |
-| Legacy Code Active | ✅ YES | Chaotic / Coupled | Append to existing \`<details><summary>Audit History</summary>\` | ❌ **FORBIDDEN (Immutability)** | Retain Current |
-| Legacy Code Active | ❌ NO | Clean / Modular | Generate Spec File + Map Current Logic | ❌ **FORBIDDEN (Immutability)** | \`v1.0.0 - stable\` |
-| Legacy Code Active | ❌ NO | Chaotic / Coupled | Generate Spec File + Map Current Logic AND Proposed Refactoring | ❌ **FORBIDDEN (Immutability)** | \`v1.0.0 - draft\` |
+| 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: 
@@ -180,14 +193,15 @@ stateDiagram-v2
 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:** ALWAYS GENERATE THE .SPEC.MD FILE OR UPDATE THE EXISTING ONE.
+**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.1.0
+%% @spec-version v1.2.0
 graph TD
     A[Ingest Signed .spec.md] --> B[Parse Matrix Rows & Version Header]
     B --> C{Verify Code/Chat Request}
@@ -201,11 +215,17 @@ graph TD
     F --> H[Generate Truth-Table Unit Tests]
     G --> H
     
-    H --> I[Verify 100% Branch Coverage Alignment]
-    I --> [*]
+    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 --> J[Refuse Coding & Demand Spec Refinement via md-edit]
-    J --> [*]
+    E --> O[Refuse Coding & Demand Spec Refinement via md-edit]
+    O --> [*]
 \`\`\`
 
 ### Injection Defense & Execution Guard Matrix
@@ -220,11 +240,13 @@ graph TD
 ### 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.`,
+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.`,
 };
 
 /**
- * Executes the `md init` command.
+ * Executes the \`md init\` command.
  * @param {import('../services/InitService.js').InitService} initService
  * @returns {Promise<void>}
  */

package/src/commands/init.spec.md

@@ -0,0 +1,174 @@
+# init.js — Command Specification
+
+**SPEC_VERSION: v1.2.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.2.0
+stateDiagram-v2
+    [*] --> ExecuteCommand: User runs "md init"
+    ExecuteCommand --> CreateSystemPrompt: initService.createSystemPrompt(content)
+    CreateSystemPrompt --> CreateSkills: initService.createSkills(skillMap, logger)
+    CreateSkills --> ReportSuccess: console.log(…) green messages
+    ReportSuccess --> [*]
+```
+
+---
+
+## 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 | `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 |
+| `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.2.0 (minor — three skills updated with new contract enforcements). |
+
+</details>

package/src/services/FileSystemService.spec.md

@@ -0,0 +1,100 @@
+# FileSystemService — Specification
+
+**SPEC_VERSION: v1.0.0 — stable**
+
+## Overview
+
+The `FileSystemService` class provides a thin abstraction layer over Node.js `fs/promises` and `sync` fs operations. It supports **dependency injection** via constructor mock parameter, enabling unit testing of consumers without touching real disk I/O.
+
+Co-located with `src/services/FileSystemService.js`.
+
+---
+
+## Behavioral Flow (Mermaid)
+
+```mermaid
+%% @spec-version v1.0.0
+stateDiagram-v2
+    state "Constructor" as Ctor
+    state "Public API" as API
+    state "Delegation" as Del
+
+    [*] --> Ctor: new FileSystemService
+    Ctor --> CtorDecision: fsMock provided?
+    CtorDecision --> CtorMock: Yes
+    CtorDecision --> CtorReal: No
+    CtorMock --> API
+    CtorReal --> API
+
+    API --> API_existsSync: existsSync path
+    API --> API_mkdirSyncRecursive: mkdirSyncRecursive path
+    API --> API_ensureDir: ensureDir path
+    API --> API_readFile: readFile path
+    API --> API_writeFile: writeFile path, content
+    API --> API_appendFile: appendFile path, content
+    API --> API_readdirSync: readdirSync dir
+
+    API_existsSync --> Del_existsSync: delegate
+    API_mkdirSyncRecursive --> Del_mkdirSync: delegate
+    API_ensureDir --> Del_ensureCheck: delegate
+    Del_ensureCheck --> Del_mkdirSync: if not exists
+    API_readFile --> Del_readFile: delegate
+    API_writeFile --> Del_writeFile: delegate
+    API_appendFile --> Del_appendFile: delegate
+    API_readdirSync --> Del_readdirSync: delegate
+
+    Del_existsSync --> [*]
+    Del_mkdirSync --> [*]
+    Del_readFile --> [*]
+    Del_writeFile --> [*]
+    Del_appendFile --> [*]
+    Del_readdirSync --> [*]
+```
+
+---
+
+## Decision Matrix
+
+### Primitive Factors
+
+| Method | Async | Sync | Returns | FS Read | FS Write (Side Effect) | Conditional Branch | Error Propagation |
+| :--- | :---: | :---: | :--- | :---: | :---: | :---: | :--- |
+| `readFile(path)` | ✅ | ❌ | `Promise<string>` | ✅ | ❌ | ❌ | Delegated to fs |
+| `writeFile(path, content)` | ✅ | ❌ | `Promise<void>` | ❌ | ✅ Overwrite | ❌ | Delegated to fs |
+| `appendFile(path, content)` | ✅ | ❌ | `Promise<void>` | ❌ | ✅ Append | ❌ | Delegated to fs |
+| `existsSync(path)` | ❌ | ✅ | `boolean` | ✅ | ❌ | ❌ | N/A |
+| `mkdirSyncRecursive(path)` | ❌ | ✅ | `void` | ❌ | ✅ Dir create | ❌ | Delegated to fs |
+| `ensureDir(path)` | ❌ | ✅ | `void` | ❌ | ✅ Dir create | ✅ if !exists → mkdir | Delegated to fs |
+| `readdirSync(dir)` | ❌ | ✅ | `string[]` | ✅ | ❌ | ❌ | Delegated to fs |
+
+### DI Testability Factors
+
+| Factor | Value | Impact |
+| :--- | :---: | :--- |
+| Constructor accepts mock? | ✅ YES | `Partial<FileSystemOperations>` optional parameter |
+| Fallback to real fs? | ✅ YES | Each property uses `||` fallback when mock field is undefined |
+| All 7 operations injectable? | ✅ YES | `readFile`, `writeFile`, `appendFile`, `existsSync`, `mkdirSyncRecursive`, `readdirSync` |
+| No global state? | ✅ YES | Instance-scoped `#fs` private field |
+| Consumers can be tested without disk? | ✅ YES | `InitService` and any consumer receive mock via constructor |
+
+---
+
+## Consumed By
+
+| Consumer | File | Dependency Mechanism |
+| :--- | :--- | :--- |
+| `InitService` | `src/services/InitService.js` | Constructor injection (`#fs` field) |
+| `init.js` (command) | `src/commands/init.js` | Indirect via `InitService` |
+
+---
+
+## Audit History
+
+<details>
+<summary>Click to expand</summary>
+
+| Date | Agent | Version | Change Summary |
+| :--- | :--- | :---: | :--- |
+| 2026-05-28 | Cline (md-audit) | v1.0.0 | **Spec created by md-audit.** Reverse-engineered from `src/services/FileSystemService.js` (38 lines). Code classified as **Clean / DI-ready**. All 7 methods documented with primitive factor analysis. No modifications to production code. |
+
+</details>

package/src/services/InitService.spec.md

@@ -0,0 +1,71 @@
+# InitService — Specification
+
+**SPEC_VERSION: v1.0.0 — stable**
+
+## Overview
+
+The `InitService` class orchestrates the `md init` command business logic: creating the universal system prompt file and the full skill library directory structure. It receives a `FileSystemService` instance via constructor injection — no direct `fs` calls.
+
+Co-located with `src/services/InitService.js`.
+
+---
+
+## Behavioral Flow (Mermaid)
+
+```mermaid
+%% @spec-version v1.0.0
+stateDiagram-v2
+    [*] --> createSystemPrompt: initService.createSystemPrompt(promptContent)
+    createSystemPrompt --> writeFile: this.#fs.writeFile('system_prompt.md', content)
+    writeFile --> createSkills: initService.createSkills(skills, logger)
+
+    createSkills --> iterateSkills: for [skillName, content] of Object.entries(skills)
+    iterateSkills --> ensureSkillFolder: this.#fs.ensureDir(skillFolder)
+    ensureSkillFolder --> writeSkillFile: this.#fs.writeFile(skillFile, content)
+    writeSkillFile --> consoleLog: logger( `✅ Skill encapsulated ${skillFile}`)
+    consoleLog --> iterateSkills: next entry
+    iterateSkills --> returnCreated: return created[]
+    returnCreated --> [*]
+```
+
+---
+
+## Decision Matrix
+
+| Step | Method | I/O | Conditional Branch? | Error Handling | FS Side Effect |
+| :--- | :--- | :--- | :---: | :--- | :--- |
+| 1 | `createSystemPrompt(promptContent)` | Input: `string`<br>Output: `Promise<void>` | ❌ No | Delegated to `#fs.writeFile` | ✅ Writes `system_prompt.md` |
+| 2 | `createSkills(skills, logger)` | Input: `Record<string,string>` + logger fn<br>Output: `Promise<string[]>` | ❌ No (iteration only) | Delegated to `#fs` methods | ✅ Creates `.agents/`, `.agents/skills/`, `skillName/SKILL.md` per entry |
+| 3 | `this.#fs.ensureDir(agentsDir)` | Path: `'.agents'` | ✅ Internal in FS: conditional mkdir | Delegated | ✅ Dir creation |
+| 4 | `this.#fs.ensureDir(skillsDir)` | Path: `'.agents/skills'` | ✅ Internal in FS: conditional mkdir | Delegated | ✅ Dir creation |
+| 5 | `this.#fs.ensureDir(skillFolder)` | Path: per skill | ✅ Internal in FS: conditional mkdir | Delegated | ✅ Dir creation |
+| 6 | `logger(…)` | stdout message | ❌ No | N/A | ❌ None |
+
+---
+
+## Exported Symbols
+
+| Export | Type | Purpose |
+| :--- | :--- | :--- |
+| `InitService` | `class` | Orchestrates system prompt and skill creation via injected `FileSystemService` |
+
+---
+
+## Depends On
+
+| Dependency | File | Mechanism |
+| :--- | :--- | :--- |
+| `FileSystemService` | `src/services/FileSystemService.js` | Constructor injection (`#fs` private field) |
+
+---
+
+## Audit History
+
+<details>
+<summary>Click to expand</summary>
+
+| Date | Agent | Version | Change Summary |
+| :--- | :--- | :---: | :--- |
+| 2026-05-28 | Cline (md-audit) | v1.0.0 | **Spec created by md-audit.** Reverse-engineered from `src/services/InitService.js` (52 lines). Code classified as **Clean / Service with DI**. All orchestration steps documented with primitive factor analysis. No modifications to production code. |
+
+</details>