mddd-cli 1.0.11 → 1.0.12

package/bin/cli.js

@@ -40,7 +40,7 @@ function findClosestMacro(currentDir) {
 program
     .name('md')
     .description('Manager for co-located specifications for Mermaid Diagram Driven Development (MDDD)')
-    .version('1.0.11');
+    .version('1.0.12');
 
 // ==========================================
 // COMMAND: md init
@@ -110,12 +110,13 @@ Operational instructions for modifying existing specifications:
 
             'md-audit': `[ROLE: SECURITY & QUALITY AUDITOR] [STRICT CONTRACT]
 Operational instructions for reverse engineering and legacy code analysis:
-1. EXECUTION: Execute the terminal command \`md audit [code_file_path]\`.
+1. EXECUTION: Execute the terminal command \`md audit [code_file_path]\`. This creates or locates a co-located \`[code_basename].spec.md\` file for audit output.
 2. COMPLEXITY ANALYSIS: Evaluate the provided code file. Check for coupling, scope leaks, and clarity of business rules.
-3. RETROACTIVE MAPPING: 
+3. RETROACTIVE MAPPING (DOCUMENTATION ONLY):
    - If the code is clean and modular: Write a Mermaid diagram corresponding to the current state of the code (v1.0.0).
-   - If the code is chaotic/coupled: Draw the Mermaid diagram of how the flow SHOULD ideally be structured after a refactoring.
-4. HISTORY ISOLATION: Insert your technical analysis report and the generated diagram strictly inside the \`<details><summary>Audit History</summary>\` tag at the end of the corresponding file. Never pollute the main scope with drafts.`,
+   - If the code is chaotic/coupled: Draw the Mermaid diagram of how the flow SHOULD ideally be restructured for future implementation. Do NOT modify the audited code file.
+4. WRITE TO SPEC FILE: Write ALL results — the technical analysis report, the generated diagram (in code fences), and any decision tables — directly into the co-located \`.spec.md\` file found at the path printed by the \`md audit\` command. Insert the analysis strictly inside the \`<details><summary>Audit History</summary>\` tag at the end of that file. Never pollute the main scope with drafts. If the spec file has empty sections, fill them with the retroactive content.
+5. CODE IMMUTABILITY: You are FORBIDDEN from changing, refactoring, or editing the audited code file. Only the \`md-impl\` command/skill is authorized to modify production code based on a signed spec file. If the audit reveals the code needs refactoring, document the ideal diagram in the spec file and stop.`,
 
             'md-impl': `[ROLE: SOFTWARE ENGINEER] [STRICT CONTRACT]
 Operational instructions for generating production code and unit tests:
@@ -241,16 +242,31 @@ program
         }
 
         const targetDir = path.dirname(codeFilePath);
-        const fileName = path.basename(codeFilePath);
-
-        console.log(pc.cyan(`🔍 Auditing code structure for coupling in: ${fileName}...`));
-        console.log(pc.yellow(`⚡ Requesting AI to validate complexity before generating MDDD specification.`));
+        const codeBaseName = path.basename(codeFilePath, path.extname(codeFilePath));
+        const specFileName = `${codeBaseName}.spec.md`;
+        const specFilePath = path.join(targetDir, specFileName);
 
+        // Ensures the target directory exists
         if (!fs.existsSync(targetDir)) {
             fs.mkdirSync(targetDir, { recursive: true });
         }
 
-        console.log(pc.green(`\n🚀 Ready! Use the /md-audit shortcut in chat to receive the analysis and structural refactoring diagram.`));
+        // Creates the .spec.md file if it doesn't exist
+        if (!fs.existsSync(specFilePath)) {
+            const version = 'v1.0.0';
+            const template = `# Audit: ${codeBaseName} | ${version}\n\n` +
+                `## 1. Flow Contract (Mermaid)\n\`\`\`mermaid\n%% @spec-version ${version}\ngraph 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`;
+            fs.writeFileSync(specFilePath, template);
+            console.log(pc.green(`✅ Co-located specification file created: ${specFilePath}`));
+        } else {
+            console.log(pc.blue(`📄 Existing specification found: ${specFilePath}`));
+        }
+
+        console.log(pc.cyan(`🔍 Auditing code structure for coupling in: ${path.basename(codeFilePath)}...`));
+        console.log(pc.yellow(`⚡ The AI will validate complexity and write the analysis to: ${specFilePath}`));
+        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/bin/cli.spec.md

@@ -1,9 +1,9 @@
-# CLI: mddd-cli | v1.2.1
+# CLI: mddd-cli | v1.3.0
 
 ## 1. Flow Contract (Mermaid)
 
 ```mermaid
-%% @spec-version v1.2.1
+%% @spec-version v1.3.0
 stateDiagram-v2
     [*] --> Idle
     Idle --> ParseArgs: md <command> [args]
@@ -40,7 +40,12 @@ stateDiagram-v2
     CmdAudit --> ValidateCodeFile: file exists?
     ValidateCodeFile --> NotFoundAudit: no → ❌ Error
     ValidateCodeFile --> PrepareDir: yes → ensure targetDir
-    PrepareDir --> ReadyAudit: 🚀 Ready
+    PrepareDir --> DeriveSpecName: get codeBasename.spec.md
+    DeriveSpecName --> CheckSpecExists: spec file exists?
+    CheckSpecExists --> CreateSpec: no → write template
+    CheckSpecExists --> LogExisting: yes → 📄 Existing found
+    CreateSpec --> ReadyAudit: 🚀 Ready
+    LogExisting --> ReadyAudit: 🚀 Ready
 
     CmdImpl --> ValidateSpecFile: file exists?
     ValidateSpecFile --> NotFoundImpl: no → ❌ Error
@@ -64,7 +69,7 @@ stateDiagram-v2
 | `md init` | `init` | Create `.agents/` + `system_prompt.md` + 4 skill files | ✅ Created / ✅ Already exists |
 | `md new <path>` | `new` | Create co-located `.spec.md` at path; optional parent linking | ✅ Created / ⚠️ Exists / ❌ Error |
 | `md edit <file> <msg>` | `edit` | Validate file, print instruction to stdout | 📝 Ready / ❌ Not found |
-| `md audit <file>` | `audit` | Validate code file, ensure dir exists | 🚀 Ready / ❌ Not found |
+| `md audit <file>` | `audit` | Validate code file, create/co-locate `.spec.md` for audit output | 🚀 Ready / ❌ Not found |
 | `md impl <file>` | `impl` | Validate spec file exists | 🚀 Ready / ❌ Not found |
 
 ### 2.2 `init` Command — File Generation
@@ -85,7 +90,18 @@ stateDiagram-v2
 | `--parent` provided AND file NOT found | `process.exit(1)` with error | ❌ Fatal |
 | `--parent` NOT provided | Auto-search via `findClosestMacro()` | ✅ Linked (if found) / No link (if none) |
 
-### 2.4 `findClosestMacro(currentDir)` — Traversal Logic
+### 2.4 `audit` Command — Spec File Generation
+
+| Condition | Action | Next State |
+| :--- | :--- | :--- |
+| Code file does not exist | `process.exit(1)` with error | ❌ Fatal |
+| Code file exists, target dir does not exist | `mkdir -p <targetDir>` | Continue |
+| Code file exists, target dir exists | No action | Continue |
+| Co-located `.spec.md` does NOT exist | Write template with `# Audit: <basename> | v1.0.0` | ⚡ Ready |
+| Co-located `.spec.md` already exists | Log `📄 Existing specification found` | ⚡ Ready |
+| Always after file ready | Print instruction: AI writes analysis into `<details>` in `.spec.md` | 🚀 Ready |
+
+### 2.5 `findClosestMacro(currentDir)` — Traversal Logic
 
 | Condition | Action | Return |
 | :--- | :--- | :--- |
@@ -101,6 +117,7 @@ stateDiagram-v2
 - **Runtime**: Node.js >= 18 (ESM — `"type": "module"`)
 - **Pattern**: Each command is a self-contained `.action()` callback. Shared utility (`findClosestMacro`) is a module-level function with clear single responsibility.
 - **Error handling**: Consistent pattern — validate file existence early, exit with code 1 + red message on failure, green/blue/yellow for success/warnings.
+- **`md audit` spec generation**: The audit command derives the spec file name by stripping the code file extension and appending `.spec.md` (e.g., `user.go` → `user.spec.md`). The generated template includes a Decision Matrix, a placeholder Mermaid diagram, and an Audit History `<details>` section where the AI writes its full analysis.
 
 ## 4. Audit History
 
@@ -112,6 +129,7 @@ stateDiagram-v2
 | 2026-05-26 | AI (MDDD audit) | v1.0.0 | Initial spec: code is modular, cohesive, clean. Mapped as-is. |
 | 2026-05-26 | AI (MDDD audit) | v1.1.0 | Deep audit of `bin/cli.js` source code. Code is clean and modular — mapped as-is (architecture diagram below). |
 | 2026-05-26 | AI (MDDD audit) | v1.2.0 | Re-audit `bin/cli.js` v1.0.10 vs spec v1.1.0. Minor divergences found in `init` flow granularity and `new` guard logic. Spec updated to reflect real code. |
+| 2026-05-26 | AI (MDDD audit) | v1.3.0 | `md audit` now auto-creates/co-locates `[basename].spec.md` for AI audit output. Skill `md-audit` updated to instruct AI to write analysis into that file. |
 
 ### Audit Report: `bin/cli.js` (2026-05-26)
 
@@ -192,6 +210,7 @@ graph LR
         SK3[.agents/skills/md-audit/SKILL.md]
         SK4[.agents/skills/md-impl/SKILL.md]
         SPEC[targetPath/name.spec.md]
+        ASPEC[srcDir/codeBasename.spec.md]
     end
 
     CLI --> CMD
@@ -210,6 +229,7 @@ graph LR
 
     AUDIT --> FS
     AUDIT --> PC
+    AUDIT --> ASPEC
     IMPL --> FS
     IMPL --> PC
     EDIT --> FS

package/package.json

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