mddd-cli 2.1.2 → 2.1.4

package/bin/cli.js

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

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "mddd-cli",
-  "version": "2.1.2",
+  "version": "2.1.4",
   "description": "Official CLI for modular, co-located, and versioned Mermaid Diagram Driven Development (MDDD).",
-  "main": "bin/cli.js",
   "type": "module",
+  "exports": "./bin/cli.js",
   "bin": {
-    "md": "bin/cli.js"
+    "md": "./bin/cli.js"
   },
   "files": [
-    "bin/"
+    "bin",
+    "src"
   ],
   "engines": {
     "node": ">=18.0.0"
@@ -40,4 +41,4 @@
     "commander": "^12.0.0",
     "picocolors": "^1.0.0"
   }
-}
+}

package/readme.md

@@ -8,7 +8,7 @@
 
 <p align="center">
   <a href="#english">🇺🇸 English</a> •
-  <a href="#português">🇧🇷 Português</a>
+  <a href="#portuguese">🇧🇷 Português</a>
 </p>
 
 ---
@@ -307,6 +307,7 @@ If you encounter any issues, open a [GitHub Issue](https://github.com/JulioCRFil
 Distributed under the MIT license. See the [LICENSE](https://www.google.com/search?q=LICENSE) file for more information.
 
 ---
+<a id="portuguese"></a>
 
 # 🇧🇷 Português
 

package/src/commands/audit.js

@@ -0,0 +1,22 @@
+import pc from 'picocolors';
+import { SpecGenerator } from '../services/SpecGenerator.js';
+import { AuditService } from '../services/AuditService.js';
+
+/**
+ * Executes the `md audit <codeFilePath>` command.
+ * @param {AuditService} auditService
+ * @param {SpecGenerator} specGenerator
+ * @param {string} codeFilePath
+ * @returns {Promise<void>}
+ */
+export async function execute(auditService, specGenerator, codeFilePath) {
+  auditService.validateCodeFile(codeFilePath);
+
+  const { specFilePath: finalSpecPath } = await specGenerator.createIfMissing(codeFilePath);
+  const result = auditService.run(codeFilePath, finalSpecPath);
+
+  console.log(pc.blue(`📄 Existing specification: ${finalSpecPath}`));
+  console.log(pc.cyan(`🔍 Auditing code structure for coupling in: ${result.codeBasename}...`));
+  console.log(pc.yellow(`⚡ The AI will validate complexity and write the analysis to: ${finalSpecPath}`));
+  console.log(pc.green(`\n🚀 Ready! Use the /md-audit shortcut in chat for the AI to write the analysis and structural refactoring diagram into the co-located spec file.`));
+}

package/src/commands/edit.js

@@ -0,0 +1,19 @@
+import pc from 'picocolors';
+
+/**
+ * Executes the `md edit <specFilePath>` command.
+ * @param {import('../services/SpecEditor.js').SpecEditor} specEditor
+ * @param {string} specFilePath
+ * @param {string[]} instructionParts
+ * @returns {void}
+ */
+export function execute(specEditor, specFilePath, instructionParts) {
+  specEditor.validateSpec(specFilePath);
+
+  const fullInstruction = instructionParts.join(' ');
+  const prepared = specEditor.prepareInstruction(specFilePath, fullInstruction);
+
+  console.log(pc.cyan(`📝 Requesting alteration in flow: "${prepared.specFilePath}"`));
+  console.log(pc.yellow(`⚙️  Evaluated instruction: ${prepared.instruction}`));
+  console.log(pc.green(`\n🚀 Ready! Use the /md-edit shortcut in chat for the AI to apply changes to the diagram and increment the version.`));
+}

package/src/commands/impl.js

@@ -0,0 +1,16 @@
+import pc from 'picocolors';
+
+/**
+ * Executes the `md impl <specFilePath>` command.
+ * @param {import('../services/ImplValidator.js').ImplValidator} implValidator
+ * @param {string} specFilePath
+ * @returns {void}
+ */
+export function execute(implValidator, specFilePath) {
+  implValidator.validate(specFilePath);
+
+  const fileName = specFilePath.split('/').pop() || specFilePath.split('\\').pop();
+  console.log(pc.cyan(`🛠️  Reading business blueprint from: ${fileName}...`));
+  console.log(pc.yellow(`🎯 Establishing the signed diagram as the Single Source of Truth.`));
+  console.log(pc.green(`\n🚀 Ready! Use the /md-impl shortcut in chat for the AI to start generating productive code and tests.`));
+}

package/src/commands/init.js

@@ -0,0 +1,234 @@
+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.`;
+
+/**
+ * Skills content map: skill name -> SKILL.md content.
+ */
+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.1.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[Save Contract & Halt]
+    H -->|Syntax Invalid| J[🛑 HALT: Abort & Ask Human]
+\`\`\`
+
+### 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** |
+
+### 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.`,
+
+  'md-audit': `[ROLE: SECURITY & QUALITY AUDITOR] [STRICT CONTRACT]
+
+\`\`\`mermaid
+%% @spec-version v1.1.0
+stateDiagram-v2
+    [*] --> AnalyzeLegacyCode: Evaluate Coupling & Scope Leaks
+    AnalyzeLegacyCode --> FileSystemCheck
+    
+    state FileSystemCheck {
+        [*] --> CheckCoLocation
+        CheckCoLocation --> CreateMissingSpec: Target Co-located .spec.md Missing
+        CheckCoLocation --> AppendToExisting: Target Co-located .spec.md Exists
+    }
+    
+    CreateMissingSpec --> RenderTopology: Initialize New .spec.md
+    AppendToExisting --> InjectAuditBlock: Target Existing File Preservation Map
+    
+    state RenderTopology {
+        [*] --> CodeIsClean: Map exact architecture as-is (v1.0.0)
+        [*] --> CodeIsChaotic: Draw BOTH current real logic AND ideal target refactored graph
+    }
+    
+    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 --> [*]
+\`\`\`
+
+### 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 | Auto-generate Spec File + Map Current Logic | ❌ **FORBIDDEN (Immutability)** | \`v1.0.0\` |
+| Legacy Code Active | ❌ NO | Chaotic / Coupled | Auto-generate Spec File + Map Current AND Proposed Logic | ❌ **FORBIDDEN (Immutability)** | \`v1.0.0\` |
+
+### Missing Spec Auto-Repair Blueprint Requirements
+* **Enforce Section Injections:** Every auto-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.`,
+
+  'md-impl': `[ROLE: SOFTWARE ENGINEER] [STRICT CONTRACT]
+
+\`\`\`mermaid
+%% @spec-version v1.1.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[Verify 100% Branch Coverage Alignment]
+    I --> [*]
+    
+    E --> J[Refuse Coding & Demand Spec Refinement via md-edit]
+    J --> [*]
+\`\`\`
+
+### 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.`,
+};
+
+/**
+ * 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);
+  await initService.createSkills(SKILLS, (msg) => console.log(msg));
+
+  console.log(pc.green('\n🚀 Universal [system_prompt.md] and SKILLS generated successfully in the project root!'));
+  console.log(pc.green('Run the "md init" command whenever you update the MDDD-CLI NPM package.'));
+}

package/src/commands/new.js

@@ -0,0 +1,56 @@
+import path from 'node:path';
+import pc from 'picocolors';
+
+/**
+ * Executes the `md new <targetPath>` command.
+ * @param {import('../services/SpecGenerator.js').SpecGenerator} specGenerator
+ * @param {import('../services/ParentLinker.js').ParentLinker} parentLinker
+ * @param {import('../services/FileSystemService.js').FileSystemService} fs
+ * @param {string} targetPath
+ * @param {{ macro?: boolean, parent?: string }} options
+ * @returns {Promise<void>}
+ */
+export async function execute(specGenerator, parentLinker, fs, targetPath, options) {
+  const normalizedPath = path.normalize(targetPath).replace(/[\\/]+$/, '');
+
+  fs.ensureDir(normalizedPath);
+
+  const folderName = path.basename(normalizedPath);
+  const finalFile = path.join(normalizedPath, `${folderName}.spec.md`);
+
+  if (fs.existsSync(finalFile)) {
+    // Check if it's a directory (edge case)
+    try {
+      const stats = await fs.getRaw().stat?.(finalFile);
+      if (stats?.isDirectory()) {
+        console.log(pc.red(`❌ Error: A directory named ${finalFile} already exists. Cannot create specification file.`));
+        process.exit(1);
+      }
+    } catch {
+      // stat not available in mock, fall through to normal check
+    }
+  }
+
+  if (fs.existsSync(finalFile)) {
+    console.log(pc.yellow(`⚠️  Specification already exists at: ${finalFile}. Operation aborted to avoid link duplication in the parent file.`));
+    process.exit(0);
+  }
+
+  const isMacro = options.macro || false;
+  const version = 'v1.0.0';
+
+  const { filePath } = await specGenerator.create(normalizedPath, isMacro, version);
+  console.log(pc.green(`✅ New specification file created: ${filePath}`));
+
+  let macroPath = options.parent || (!isMacro ? parentLinker.findClosestMacro(normalizedPath) : null);
+
+  if (macroPath) {
+    if (!fs.existsSync(macroPath)) {
+      console.log(pc.red(`❌ Specified parent file not found: ${macroPath}`));
+      process.exit(1);
+    }
+
+    await parentLinker.linkToParent(macroPath, filePath, folderName);
+    console.log(pc.blue(`🔗 Successfully linked into parent flow: ${macroPath}`));
+  }
+}

package/src/services/AuditService.js

@@ -0,0 +1,41 @@
+/**
+ * Handles the `md audit` command business logic.
+ */
+export class AuditService {
+  /** @type {import('./FileSystemService.js').FileSystemService} */
+  #fs;
+
+  /**
+   * @param {import('./FileSystemService.js').FileSystemService} fsService
+   */
+  constructor(fsService) {
+    this.#fs = fsService;
+  }
+
+  /**
+   * Validates that a code file exists.
+   * @param {string} codeFilePath
+   * @returns {boolean}
+   * @throws {Error} if not found
+   */
+  validateCodeFile(codeFilePath) {
+    if (!this.#fs.existsSync(codeFilePath)) {
+      throw new Error(`Code file not found: ${codeFilePath}`);
+    }
+    return true;
+  }
+
+  /**
+   * Runs audit placeholders (actual AI analysis happens in chat via /md-audit skill).
+   * @param {string} codeFilePath
+   * @param {string} specFilePath
+   * @returns {{ codeBasename: string, specFilePath: string }}
+   */
+  run(codeFilePath, specFilePath) {
+    const basename = codeFilePath.split('/').pop() || codeFilePath.split('\\').pop();
+    return {
+      codeBasename: basename,
+      specFilePath,
+    };
+  }
+}

package/src/services/FileSystemService.js

@@ -0,0 +1,100 @@
+// @ts-check
+import fs from 'node:fs/promises';
+import { existsSync, mkdirSync, readdirSync } from 'node:fs';
+
+/**
+ * @typedef {Object} FileSystemOperations
+ * @property {(path: string) => Promise<string>} readFile
+ * @property {(path: string, content: string) => Promise<void>} writeFile
+ * @property {(path: string, content: string) => Promise<void>} appendFile
+ * @property {(path: string) => boolean} existsSync
+ * @property {(path: string) => void} mkdirSyncRecursive
+ * @property {(path: string) => string[]} readdirSync
+ */
+
+/**
+ * Shared file system service with dependency injection support for testability.
+ */
+export class FileSystemService {
+  /** @type {FileSystemOperations} */
+  #fs;
+
+  /**
+   * @param {Partial<FileSystemOperations>} [fsMock] - Optional mock for testing
+   */
+  constructor(fsMock) {
+    this.#fs = {
+      readFile: fsMock?.readFile || fs.readFile.bind(fs),
+      writeFile: fsMock?.writeFile || fs.writeFile.bind(fs),
+      appendFile: fsMock?.appendFile || fs.appendFile.bind(fs),
+      existsSync: fsMock?.existsSync || existsSync,
+      mkdirSyncRecursive: fsMock?.mkdirSyncRecursive || ((p) => mkdirSync(p, { recursive: true })),
+      readdirSync: fsMock?.readdirSync || readdirSync,
+    };
+  }
+
+  /**
+   * Checks if a path exists synchronously.
+   * @param {string} path
+   * @returns {boolean}
+   */
+  existsSync(path) {
+    return this.#fs.existsSync(path);
+  }
+
+  /**
+   * Creates a directory recursively.
+   * @param {string} path
+   */
+  mkdirSyncRecursive(path) {
+    this.#fs.mkdirSyncRecursive(path);
+  }
+
+  /**
+   * Creates a directory if it doesn't exist.
+   * @param {string} path
+   */
+  ensureDir(path) {
+    if (!this.#fs.existsSync(path)) {
+      this.#fs.mkdirSyncRecursive(path);
+    }
+  }
+
+  /**
+   * Reads a file as UTF-8 string.
+   * @param {string} path
+   * @returns {Promise<string>}
+   */
+  async readFile(path) {
+    return this.#fs.readFile(path);
+  }
+
+  /**
+   * Writes a string to a file.
+   * @param {string} path
+   * @param {string} content
+   * @returns {Promise<void>}
+   */
+  async writeFile(path, content) {
+    return this.#fs.writeFile(path, content);
+  }
+
+  /**
+   * Appends content to a file.
+   * @param {string} path
+   * @param {string} content
+   * @returns {Promise<void>}
+   */
+  async appendFile(path, content) {
+    return this.#fs.appendFile(path, content);
+  }
+
+  /**
+   * Synchronous readdir for directory crawling.
+   * @param {string} dir
+   * @returns {string[]}
+   */
+  readdirSync(dir) {
+    return this.#fs.readdirSync(dir);
+  }
+}

package/src/services/ImplValidator.js

@@ -0,0 +1,27 @@
+/**
+ * Validates prerequisites for the `md impl` command.
+ */
+export class ImplValidator {
+  /** @type {import('./FileSystemService.js').FileSystemService} */
+  #fs;
+
+  /**
+   * @param {import('./FileSystemService.js').FileSystemService} fsService
+   */
+  constructor(fsService) {
+    this.#fs = fsService;
+  }
+
+  /**
+   * Validates that a spec file exists before implementation.
+   * @param {string} specFilePath
+   * @returns {boolean}
+   * @throws {Error} if not found
+   */
+  validate(specFilePath) {
+    if (!this.#fs.existsSync(specFilePath)) {
+      throw new Error(`Specification file not found: ${specFilePath}`);
+    }
+    return true;
+  }
+}

package/src/services/InitService.js

@@ -0,0 +1,52 @@
+import path from 'node:path';
+
+/**
+ * Handles the `md init` business logic: system prompt and skills creation.
+ */
+export class InitService {
+  /** @type {import('./FileSystemService.js').FileSystemService} */
+  #fs;
+
+  /**
+   * @param {import('./FileSystemService.js').FileSystemService} fsService
+   */
+  constructor(fsService) {
+    this.#fs = fsService;
+  }
+
+  /**
+   * Creates the universal system prompt file.
+   * @param {string} promptContent - The full MDDD system prompt content
+   * @returns {Promise<void>}
+   */
+  async createSystemPrompt(promptContent) {
+    await this.#fs.writeFile('system_prompt.md', promptContent);
+  }
+
+  /**
+   * Creates all skill folders and SKILL.md files.
+   * @param {Record<string, string>} skills - Map of skill name to skill content
+   * @returns {Promise<{console: (message: string) => void}>} Array of file paths created
+   */
+  async createSkills(skills, logger) {
+    const agentsDir = '.agents';
+    const skillsDir = path.join(agentsDir, 'skills');
+
+    this.#fs.ensureDir(agentsDir);
+    this.#fs.ensureDir(skillsDir);
+
+    const created = [];
+
+    for (const [skillName, content] of Object.entries(skills)) {
+      const skillFolder = path.join(skillsDir, skillName);
+      this.#fs.ensureDir(skillFolder);
+
+      const skillFile = path.join(skillFolder, 'SKILL.md');
+      await this.#fs.writeFile(skillFile, content);
+      created.push(skillFile);
+      logger(`✅ Skill successfully encapsulated: ${skillFile}`);
+    }
+
+    return created;
+  }
+}

package/src/services/ParentLinker.js

@@ -0,0 +1,70 @@
+import path from 'node:path';
+
+/**
+ * Crawls directories upward to find the nearest parent macro .spec.md file.
+ */
+export class ParentLinker {
+  /** @type {import('./FileSystemService.js').FileSystemService} */
+  #fs;
+
+  /**
+   * @param {import('./FileSystemService.js').FileSystemService} fsService
+   */
+  constructor(fsService) {
+    this.#fs = fsService;
+  }
+
+  /**
+   * Searches for the closest macro (*.spec.md) by recursively traversing the directory tree upward.
+   * Skips the spec file that matches the current folder name to avoid self-linking.
+   * @param {string} currentDir - Absolute path of the feature directory
+   * @returns {string|null} Path to the parent .spec.md, or null if not found
+   */
+  findClosestMacro(currentDir) {
+    let dir = path.resolve(currentDir);
+    const root = path.parse(dir).root;
+
+    while (dir !== root) {
+      try {
+        const files = this.#fs.readdirSync(dir);
+        const macroFile = files.find(
+          (f) => f.endsWith('.spec.md') && f !== `${path.basename(currentDir)}.spec.md`
+        );
+
+        if (macroFile) {
+          return path.join(dir, macroFile);
+        }
+      } catch (e) {
+        // Permission errors: stop climbing and return null
+        if (e.code === 'EACCES' || e.code === 'EPERM') {
+          break;
+        }
+        throw e;
+      }
+
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+    return null;
+  }
+
+  /**
+   * Appends a markdown link to the child spec into the parent spec file.
+   * @param {string} parentSpecPath - Path to the parent .spec.md
+   * @param {string} childSpecPath - Path to the child .spec.md
+   * @param {string} folderName - Name of the child feature folder
+   * @returns {Promise<void>}\n   */
+  async linkToParent(parentSpecPath, childSpecPath, folderName) {
+    const relativePath = path
+      .relative(path.dirname(parentSpecPath), childSpecPath)
+      .replace(/\\/g, '/'); // Garante compatibilidade de paths no estilo POSIX para o Markdown
+
+    const parentContent = await this.#fs.readFile(parentSpecPath);
+
+    // Injeta o link logo após o fim do bloco do Mermaid ou no topo do arquivo estruturado
+    const linkAddition = `\n\n- [Micro Feature: ${folderName}](${relativePath})`;
+
+    await this.#fs.writeFile(parentSpecPath, parentContent + linkAddition);
+  }
+}

package/src/services/SpecEditor.js

@@ -0,0 +1,37 @@
+/**
+ * Handles the `md edit` command business logic.
+ */
+export class SpecEditor {
+  /** @type {import('./FileSystemService.js').FileSystemService} */
+  #fs;
+
+  /**
+   * @param {import('./FileSystemService.js').FileSystemService} fsService
+   */
+  constructor(fsService) {
+    this.#fs = fsService;
+  }
+
+  /**
+   * Validates that a spec file exists.
+   * @param {string} specFilePath
+   * @returns {boolean}
+   * @throws {Error} if not found
+   */
+  validateSpec(specFilePath) {
+    if (!this.#fs.existsSync(specFilePath)) {
+      throw new Error(`Specification file not found: ${specFilePath}`);
+    }
+    return true;
+  }
+
+  /**
+   * Prepares the edit instruction message (placeholder — actual logic applied by AI agent).
+   * @param {string} specFilePath
+   * @param {string} instruction
+   * @returns {{ specFilePath: string, instruction: string }}
+   */
+  prepareInstruction(specFilePath, instruction) {
+    return { specFilePath, instruction };
+  }
+}

package/src/services/SpecGenerator.js

@@ -0,0 +1,58 @@
+import path from 'node:path';
+import { TemplateFactory } from './TemplateFactory.js';
+
+/**
+ * Handles .spec.md file generation for `md new` and `md audit` commands.
+ */
+export class SpecGenerator {
+  /** @type {import('./FileSystemService.js').FileSystemService} */
+  #fs;
+
+  /**
+   * @param {import('./FileSystemService.js').FileSystemService} fsService
+   */
+  constructor(fsService) {
+    this.#fs = fsService;
+  }
+
+  /**
+   * Creates a new .spec.md file for a feature (macro or micro).
+   * @param {string} targetPath - Normalized target directory path
+   * @param {boolean} isMacro - Whether to generate a macro template
+   * @param {string} version - Semantic version string (e.g. 'v1.0.0')
+   * @returns {Promise<{filePath: string, folderName: string}>}
+   */
+  async create(targetPath, isMacro, version) {
+    const folderName = path.basename(targetPath);
+    const finalFile = path.join(targetPath, `${folderName}.spec.md`);
+
+    const template = isMacro
+      ? TemplateFactory.macroTemplate(folderName, version)
+      : TemplateFactory.microTemplate(folderName, version);
+
+    await this.#fs.writeFile(finalFile, template);
+
+    return { filePath: finalFile, folderName };
+  }
+
+  /**
+   * Creates a missing .spec.md file for audit purposes.
+   * @param {string} codeFilePath - Path to the code file being audited
+   * @returns {Promise<{specFilePath: string, codeBaseName: string}>}
+   */
+  async createIfMissing(codeFilePath) {
+    const targetDir = path.dirname(codeFilePath);
+    const ext = path.extname(codeFilePath);
+    const codeBaseName = path.basename(codeFilePath, ext);
+    const specFileName = `${codeBaseName}.spec.md`;
+    const specFilePath = path.join(targetDir, specFileName);
+
+    if (!this.#fs.existsSync(specFilePath)) {
+      const version = 'v1.0.0';
+      const template = TemplateFactory.auditTemplate(codeBaseName, version);
+      await this.#fs.writeFile(specFilePath, template);
+    }
+
+    return { specFilePath, codeBaseName };
+  }
+}

package/src/services/SpecValidator.js

@@ -0,0 +1,27 @@
+/**
+ * Validates that a .spec.md file exists before processing.
+ */
+export class SpecValidator {
+  /** @type {import('./FileSystemService.js').FileSystemService} */
+  #fs;
+
+  /**
+   * @param {import('./FileSystemService.js').FileSystemService} fsService
+   */
+  constructor(fsService) {
+    this.#fs = fsService;
+  }
+
+  /**
+   * Validates that a spec file path exists.
+   * @param {string} specFilePath
+   * @returns {boolean} true if valid
+   * @throws {Error} if file does not exist
+   */
+  validate(specFilePath) {
+    if (!this.#fs.existsSync(specFilePath)) {
+      throw new Error(`Specification file not found: ${specFilePath}`);
+    }
+    return true;
+  }
+}

package/src/services/TemplateFactory.js

@@ -0,0 +1,80 @@
+/**
+ * Template engine for generating .spec.md file blueprints.
+ */
+export class TemplateFactory {
+  /**
+   * Generates a macro module template (stateDiagram-v2).
+   * @param {string} folderName
+   * @param {string} version
+   * @returns {string}
+   */
+  static macroTemplate(folderName, version) {
+    return (
+      `\n# Macro Module: ${folderName} | ${version}\n\n` +
+      '```mermaid\n' +
+      `%% @spec-version ${version}\n` +
+      'stateDiagram-v2\n' +
+      `    [*] --> Initial_${folderName}\n` +
+      '```\n\n' +
+      '## 3. Audit History\n' +
+      '<details>\n' +
+      '<summary>Click to expand</summary>\n' +
+      '\n\n\n' +
+      '</details>\n'
+    );
+  }
+
+  /**
+   * Generates a micro feature template (graph LR + Decision Matrix).
+   * @param {string} folderName
+   * @param {string} version
+   * @returns {string}
+   */
+  static microTemplate(folderName, version) {
+    return (
+      `\n# Specification: ${folderName} | ${version}\n\n` +
+      '## 1. Flow Contract (Mermaid)\n' +
+      '```mermaid\n' +
+      `%% @spec-version ${version}\n` +
+      'graph LR\n' +
+      '    A([Start]) --> B[Process]\n' +
+      '```\n\n' +
+      '## 2. Decision Matrix\n' +
+      '| Factor A? | Factor B? | Proposed Action | Decision (Outcome) | Transition State (New Status) |\n' +
+      '| :---: | :---: | :--- | :---: | :---: |\n' +
+      '| | | | | |\n\n' +
+      '## 3. Audit History\n' +
+      '<details>\n' +
+      '<summary>Click to expand</summary>\n' +
+      '\n\n\n' +
+      '</details>\n'
+    );
+  }
+
+  /**
+   * Generates an audit template (graph LR + AuditHistory).
+   * @param {string} codeBaseName
+   * @param {string} version
+   * @returns {string}
+   */
+  static auditTemplate(codeBaseName, version) {
+    return (
+      `# Audit: ${codeBaseName} | ${version}\n\n` +
+      '## 1. Flow Contract (Mermaid)\n' +
+      '```mermaid\n' +
+      `%% @spec-version ${version}\n` +
+      'graph LR\n' +
+      '    A([Start]) --> B[Process]\n' +
+      '```\n\n' +
+      '## 2. Decision Matrix\n' +
+      '| Condition | Action | Next State |\n' +
+      '| :---: | :--- | :---: |\n' +
+      '| | | |\n\n' +
+      '## 3. Audit History\n' +
+      '<details>\n' +
+      '<summary>Click to expand</summary>\n' +
+      '\n\n\n' +
+      '</details>\n'
+    );
+  }
+}