mddd-cli 1.0.10 → 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.10');
+    .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.1.0
+# CLI: mddd-cli | v1.3.0
 
 ## 1. Flow Contract (Mermaid)
 
 ```mermaid
-%% @spec-version v1.1.0
+%% @spec-version v1.3.0
 stateDiagram-v2
     [*] --> Idle
     Idle --> ParseArgs: md <command> [args]
@@ -17,8 +17,9 @@ stateDiagram-v2
         DetectCommand --> CmdImpl: impl <file>
     }
 
-    CmdInit --> CreateDotAgents: mkdir .agents/skills/
-    CreateDotAgents --> WriteSystemPrompt: write system_prompt.md
+    CmdInit --> MkdirDotAgents: mkdir .agents/
+    MkdirDotAgents --> MkdirSkills: mkdir .agents/skills/
+    MkdirSkills --> WriteSystemPrompt: write system_prompt.md
     WriteSystemPrompt --> WriteSkills: write 4 SKILL.md files
     WriteSkills --> Done: ✅ Success
 
@@ -39,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
@@ -63,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
@@ -74,7 +80,7 @@ stateDiagram-v2
 | `./.agents/skills` does not exist | `mkdir .agents/skills` | Continue |
 | Always | Write `system_prompt.md` | Continue |
 | For each skill (`md-new`, `md-edit`, `md-audit`, `md-impl`) | Create folder + `SKILL.md` | Continue → Done |
-| Skill `SKILL.md` already exists | Delete old, write new | Replace |
+| Skill `SKILL.md` already exists | Overwrite silently via `fs.writeFileSync` | Replace |
 
 ### 2.3 `new` Command — Parent Linking
 
@@ -82,10 +88,20 @@ stateDiagram-v2
 | :--- | :--- | :--- |
 | `--parent` provided AND file exists | Append link line to parent | ✅ Linked |
 | `--parent` provided AND file NOT found | `process.exit(1)` with error | ❌ Fatal |
-| `--parent` NOT provided AND NOT `--macro` | Auto-search via `findClosestMacro()` | ✅ Linked (if found) / No link (if none) |
-| `--macro` flag set | Skip parent linking (unless `-p` explicit) | Macro template generated |
+| `--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
 
@@ -111,6 +128,8 @@ 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)
 
@@ -137,10 +156,30 @@ stateDiagram-v2
 5. ⚠️ **Template strings** in `new` action: Extract to `templates/` directory for maintainability.
 6. ⚠️ **`process.exit()` scattering**: If this grows into a library, consider centralizing error handling and returning exit codes.
 
-**Architecture Diagram (Current State — v1.0.8)**:
+### Audit Report: `bin/cli.js` (2026-05-26) — v1.2.0 Re-audit
+
+**Target**: `bin/cli.js` — CLI entry point (v1.0.10)
+
+**Discrepancies Found vs Spec v1.1.0**:
+
+| Item | Spec Said | Code Does | Verdict |
+| :--- | :--- | :--- | :--- |
+| `init` flow — directory creation | `CreateDotAgents: mkdir .agents/skills/` | Two separate conditional mkdir: `mkdir .agents/` then `mkdir .agents/skills/` | ⚠️ Minor — spec combined into one state; fixed in v1.2.0 diagram |
+| `init` — SKILL.md overwrite | "Delete old, write new" | `fs.writeFileSync` overwrites silently, no deletion | ⚠️ Minor — wording fixed in v1.2.0 matrix |
+| `new` — `CheckExists` guard order | CheckExists branches to Skip or GenerateSpec | Code checks `fs.existsSync(normalizedPath)` for mkdir, then checks `fs.existsSync(finalFile)` separately | ✅ Correct — diagram simplified, no semantic error |
+| `new` — trailing slash normalization | Not mentioned | `normalizedPath` uses `.replace(/[\\/]+$/, '')` | ✅ Enhancement — documented below |
+| `findClosestMacro` — dir exclusion | Not specified | Excludes file named `${path.basename(currentDir)}.spec.md` | ✅ Enhancement — documented in matrix |
+| Version metadata | N/A (spec refers to v1.0.8) | Code declares `v1.0.10` | ✅ Cosmetic — spec now at v1.2.0 |
+
+**Newly Documented Behaviors**:
+- **Trailing slash cleanup**: `path.normalize(targetPath).replace(/[\\/]+$/, '')` strips trailing slashes before mkdir.
+- **Self-exclusion in `findClosestMacro`**: The macro search excludes `${path.basename(currentDir)}.spec.md` to avoid matching the directory's own spec file.
+- **Permission-denied break**: On `EACCES`/`EPERM`, the loop breaks and returns `null`. All other `fs.readdirSync` errors are rethrown.
+
+**Architecture Diagram (Current State — v1.0.10)**:
 
 ```mermaid
-%% @spec-version v1.1.0
+%% @spec-version v1.2.0
 graph LR
     subgraph "Entry Point"
         CLI["bin/cli.js"]
@@ -171,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
@@ -189,13 +229,11 @@ graph LR
 
     AUDIT --> FS
     AUDIT --> PC
+    AUDIT --> ASPEC
     IMPL --> FS
     IMPL --> PC
     EDIT --> FS
     EDIT --> PC
 ```
 
-**Recommendations for v2.0.0** (future):
-- Replace `process.exit()` with thrown exceptions or a centralized error handler for better testability
-
 </details>

package/package.json

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