docguard-cli 0.5.2 → 0.7.0

package/PHILOSOPHY.md

@@ -143,6 +143,28 @@ CDD is designed for progressive adoption:
 
 ---
 
+## Academic Foundations
+
+CDD is a practitioner methodology, but its core patterns align with peer-reviewed research in AI-driven documentation and quality evaluation:
+
+### The Three-Stage Pipeline
+
+DocGuard's architecture follows a **generate → validate → evaluate** pipeline inspired by the AITPG framework (Lopez et al., IEEE TSE 2026), which demonstrated that multi-agent debate over RAG-grounded standards produces 32% more comprehensive documentation while maintaining semantic alignment with expert references.
+
+### Calibrated Quality Evaluation
+
+DocGuard's quality scoring (HIGH/MEDIUM/LOW labels, multi-signal composite scores) adapts the Calibrated Judge Evaluation (CJE) framework from TRACE (Lopez et al., IEEE TMLCN 2026), which showed that weighted multi-signal scoring with confidence intervals provides actionable quality gating for enterprise deployment.
+
+### Standards-Grounded Generation
+
+Both AITPG and TRACE demonstrate that grounding AI-generated content in vectorized standards (ISO 29119, 3GPP) dramatically improves output quality. DocGuard applies this principle by mapping each canonical document to its relevant industry standard (arc42, C4, OWASP ASVS, ISO 29119, OpenAPI 3.1, 12-Factor App).
+
+> **Full citations**: See [CONTRIBUTING.md — Research & Academic Credits](CONTRIBUTING.md#research--academic-credits)
+>
+> **Lead researcher**: [Martin Manuel Lopez](https://github.com/martinmanuel9) · [ORCID 0009-0002-7652-2385](https://orcid.org/0009-0002-7652-2385), University of Arizona
+
+---
+
 ## License
 
 This philosophy document and the CDD methodology are released under the [MIT License](https://opensource.org/licenses/MIT).

package/README.md

@@ -322,6 +322,19 @@ We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ---
 
+## Research Credits
+
+DocGuard's quality evaluation and documentation generation patterns are informed by peer-reviewed research from the University of Arizona and the Joint Interoperability Test Command (JITC), U.S. Department of Defense:
+
+- **AITPG** — AI-driven Test Plan Generator using Multi-Agent Debate and RAG ([Lopez et al., IEEE TSE 2026](Research/AITPG.pdf))
+- **TRACE** — Telecom Root Cause Analysis through Calibrated Explainability ([Lopez et al., IEEE TMLCN 2026](Research/TRACE.pdf))
+
+Lead researcher: **[Martin Manuel Lopez](https://github.com/martinmanuel9)** · [ORCID 0009-0002-7652-2385](https://orcid.org/0009-0002-7652-2385)
+
+See [CONTRIBUTING.md](CONTRIBUTING.md#research--academic-credits) for full citations and concept attributions.
+
+---
+
 ## License
 
 [MIT](LICENSE) — Free to use, modify, and distribute.

package/cli/commands/diagnose.mjs

@@ -16,8 +16,9 @@
 import { c } from '../docguard.mjs';
 import { runGuardInternal } from './guard.mjs';
 import { runScoreInternal } from './score.mjs';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, mkdirSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { execSync } from 'node:child_process';
 
 // Map validator failures to the right fix --doc target
 const VALIDATOR_TO_DOC = {
@@ -39,62 +40,141 @@ const FIX_INSTRUCTIONS = {
     action: 'Create missing files',
     command: 'docguard init',
     description: 'Run init to create missing documentation templates.',
+    autoFixable: true,
   },
   'Doc Sections': {
     action: 'Fill document sections',
     command: 'docguard fix --doc',
     description: 'Documents exist but have missing or placeholder sections. Use fix --doc to generate AI content prompts.',
+    autoFixable: false,
   },
   'Docs-Sync': {
     action: 'Sync documentation references',
     command: 'docguard fix --doc architecture',
     description: 'Documentation references are out of sync with code. Review and update component maps.',
+    autoFixable: false,
   },
   'Drift': {
     action: 'Update DRIFT-LOG.md',
     description: 'Code deviates from canonical docs without logged reasons. Add DRIFT entries or update the canonical docs.',
+    autoFixable: false,
   },
   'Changelog': {
     action: 'Update CHANGELOG.md',
     description: 'CHANGELOG.md is missing or has no [Unreleased] section. Add recent changes.',
+    autoFixable: false,
   },
   'Test-Spec': {
     action: 'Update TEST-SPEC.md',
     command: 'docguard fix --doc test-spec',
     description: 'Test documentation needs updating to match actual test structure.',
+    autoFixable: false,
   },
   'Environment': {
     action: 'Update ENVIRONMENT.md',
     command: 'docguard fix --doc environment',
     description: 'Environment documentation is missing or incomplete.',
+    autoFixable: false,
   },
   'Security': {
     action: 'Update SECURITY.md',
     command: 'docguard fix --doc security',
     description: 'Security documentation needs updating.',
+    autoFixable: false,
   },
   'Architecture': {
     action: 'Update ARCHITECTURE.md',
     command: 'docguard fix --doc architecture',
     description: 'Architecture documentation doesn\'t match the codebase.',
+    autoFixable: false,
   },
   'Freshness': {
     action: 'Review stale documents',
     description: 'Documents haven\'t been reviewed since recent code changes. Re-run fix --doc for each stale doc.',
+    autoFixable: false,
   },
 };
 
 export function runDiagnose(projectDir, config, flags) {
   // ── Step 1: Run guard internally ──
-  const guardData = runGuardInternal(projectDir, config);
+  let guardData = runGuardInternal(projectDir, config);
   const scoreData = runScoreInternal(projectDir, config);
 
   // ── Step 2: Collect issues ──
+  let issues = collectIssues(guardData);
+
+  // ── Step 3: Auto-fix what we can (unless --no-fix) ──
+  const shouldAutoFix = !flags.noFix && flags.format !== 'json';
+  if (shouldAutoFix && issues.length > 0) {
+    const autoFixable = issues.filter(i => i.autoFixable);
+    const hasStructural = issues.some(i => i.validator === 'Structure');
+
+    if (hasStructural || autoFixable.length > 0) {
+      // Run init to create missing files
+      try {
+        const cliPath = resolve(import.meta.dirname, '..', 'docguard.mjs');
+        execSync(`node "${cliPath}" init --dir "${projectDir}"`, {
+          encoding: 'utf-8',
+          stdio: 'pipe',
+        });
+      } catch { /* init may partially succeed */ }
+
+      // Run generate to fill in content
+      try {
+        const cliPath = resolve(import.meta.dirname, '..', 'docguard.mjs');
+        execSync(`node "${cliPath}" generate --dir "${projectDir}" --force`, {
+          encoding: 'utf-8',
+          stdio: 'pipe',
+        });
+      } catch { /* generate may partially succeed */ }
+
+      // Re-run guard to see what's still broken
+      guardData = runGuardInternal(projectDir, config);
+      issues = collectIssues(guardData);
+
+      if (!flags.format || flags.format === 'text') {
+        const fixedCount = autoFixable.length - issues.filter(i => i.autoFixable).length;
+        if (fixedCount > 0) {
+          console.log(`  ${c.green}⚡ Auto-fixed ${fixedCount} issue(s)${c.reset} (created/regenerated docs)\n`);
+        }
+      }
+    }
+  }
+
+  // Detect stale docs from freshness and map to specific fix --doc targets
+  for (const issue of issues) {
+    if (issue.validator === 'Freshness' && !issue.docTarget) {
+      const match = issue.message.match(/([\w-]+\.md)/i);
+      if (match) {
+        const docName = match[1].toLowerCase().replace('.md', '');
+        const docMap = { 'architecture': 'architecture', 'data-model': 'data-model', 'security': 'security', 'test-spec': 'test-spec', 'environment': 'environment' };
+        issue.docTarget = docMap[docName] || null;
+        if (issue.docTarget) {
+          issue.command = `docguard fix --doc ${issue.docTarget}`;
+        }
+      }
+    }
+  }
+
+  // ── Step 4: Output ──
+  if (flags.format === 'json') {
+    outputJSON(guardData, scoreData, issues);
+  } else if (flags.format === 'prompt') {
+    outputPrompt(projectDir, guardData, scoreData, issues, flags);
+  } else {
+    outputText(projectDir, guardData, scoreData, issues, flags);
+  }
+}
+
+/**
+ * Collect issues from guard results with fix metadata.
+ */
+function collectIssues(guardData) {
   const issues = [];
   for (const v of guardData.validators) {
     if (v.status === 'skipped' || v.status === 'pass') continue;
 
-    const fixInfo = FIX_INSTRUCTIONS[v.name] || { action: `Review ${v.name}`, description: 'Manual review needed.' };
+    const fixInfo = FIX_INSTRUCTIONS[v.name] || { action: `Review ${v.name}`, description: 'Manual review needed.', autoFixable: false };
     const docTarget = VALIDATOR_TO_DOC[v.name];
 
     for (const err of v.errors) {
@@ -105,6 +185,7 @@ export function runDiagnose(projectDir, config, flags) {
         action: fixInfo.action,
         command: fixInfo.command || null,
         docTarget,
+        autoFixable: fixInfo.autoFixable || false,
       });
     }
     for (const warn of v.warnings) {
@@ -115,34 +196,11 @@ export function runDiagnose(projectDir, config, flags) {
         action: fixInfo.action,
         command: fixInfo.command || null,
         docTarget,
+        autoFixable: fixInfo.autoFixable || false,
       });
     }
   }
-
-  // Detect stale docs from freshness and map to specific fix --doc targets
-  for (const issue of issues) {
-    if (issue.validator === 'Freshness' && !issue.docTarget) {
-      // Try to extract doc name from warning message
-      const match = issue.message.match(/([\w-]+\.md)/i);
-      if (match) {
-        const docName = match[1].toLowerCase().replace('.md', '');
-        const docMap = { 'architecture': 'architecture', 'data-model': 'data-model', 'security': 'security', 'test-spec': 'test-spec', 'environment': 'environment' };
-        issue.docTarget = docMap[docName] || null;
-        if (issue.docTarget) {
-          issue.command = `docguard fix --doc ${issue.docTarget}`;
-        }
-      }
-    }
-  }
-
-  // ── Step 3: Output ──
-  if (flags.format === 'json') {
-    outputJSON(guardData, scoreData, issues);
-  } else if (flags.format === 'prompt') {
-    outputPrompt(projectDir, guardData, scoreData, issues);
-  } else {
-    outputText(projectDir, guardData, scoreData, issues);
-  }
+  return issues;
 }
 
 function outputJSON(guardData, scoreData, issues) {
@@ -168,7 +226,7 @@ function outputJSON(guardData, scoreData, issues) {
   console.log(JSON.stringify(result, null, 2));
 }
 
-function outputText(projectDir, guardData, scoreData, issues) {
+function outputText(projectDir, guardData, scoreData, issues, flags) {
   console.log(`${c.bold}🔍 DocGuard Diagnose — ${guardData.project}${c.reset}`);
   console.log(`${c.dim}   Profile: ${guardData.profile} | Score: ${scoreData.score}/100 (${scoreData.grade})${c.reset}`);
   console.log(`${c.dim}   Guard:   ${guardData.passed}/${guardData.total} passed | Status: ${guardData.status}${c.reset}\n`);
@@ -213,17 +271,27 @@ function outputText(projectDir, guardData, scoreData, issues) {
   }
 
   // ── AI Prompt (always shown in text mode for easy copy) ──
-  console.log(`  ${c.bold}🤖 AI-Ready Prompt:${c.reset}`);
-  console.log(`  ${c.dim}Copy everything below and paste to your AI agent:${c.reset}\n`);
-  outputPrompt(undefined, guardData, scoreData, issues);
+  if (flags && flags.debate) {
+    // Multi-perspective debate prompts (AITPG/TRACE-inspired)
+    console.log(`  ${c.bold}🤖 Multi-Perspective AI Debate Prompt:${c.reset}`);
+    console.log(`  ${c.dim}Copy everything below and paste to your AI agent:${c.reset}\n`);
+    outputDebatePrompt(projectDir, guardData, scoreData, issues);
+  } else {
+    console.log(`  ${c.bold}🤖 AI-Ready Prompt:${c.reset}`);
+    console.log(`  ${c.dim}Copy everything below and paste to your AI agent:${c.reset}\n`);
+    outputPrompt(undefined, guardData, scoreData, issues, flags);
+  }
 }
 
-function outputPrompt(projectDir, guardData, scoreData, issues) {
+function outputPrompt(projectDir, guardData, scoreData, issues, flags) {
   if (issues.length === 0) {
     console.log('No issues to fix. Documentation is healthy.');
     return;
   }
 
+  // Detect agent capability for prompt complexity (inspired by CJE equalizer effect, TRACE 2026)
+  const agentTier = detectAgentTier(projectDir || '.');
+
   const lines = [];
   lines.push(`TASK: Fix ${issues.length} documentation issue(s) in project "${guardData.project}"`);
   lines.push(`Profile: ${guardData.profile} | Score: ${scoreData.score}/100 | Guard: ${guardData.status}`);
@@ -257,6 +325,11 @@ function outputPrompt(projectDir, guardData, scoreData, issues) {
     if (group.docTarget) {
       lines.push(`   Then research the codebase and write real content for this document.`);
     }
+    // Agent-aware: add extra detail for smaller models
+    if (agentTier === 'basic') {
+      lines.push(`   NOTE: Review the codebase file by file. Look for patterns matching this issue.`);
+      lines.push(`   Check docs-canonical/ for the expected format. Compare against existing docs.`);
+    }
     for (const msg of group.issues) {
       lines.push(`   - ${msg}`);
     }
@@ -269,5 +342,123 @@ function outputPrompt(projectDir, guardData, scoreData, issues) {
   lines.push('Expected result: All checks pass (0 errors, 0 warnings)');
   lines.push(`Target score: ≥${scoreData.score + 5}/100`);
 
+  // Agent-aware: add explicit checklist for basic-tier agents
+  if (agentTier === 'basic') {
+    lines.push('');
+    lines.push('VERIFICATION CHECKLIST (complete each step):');
+    lines.push('□ Read each file in docs-canonical/ before editing');
+    lines.push('□ Run `docguard guard` after each file change');
+    lines.push('□ Confirm 0 errors before moving to next issue');
+    lines.push('□ Run `docguard score` to confirm improvement');
+  }
+
+  console.log(lines.join('\n'));
+}
+
+/**
+ * Generate multi-perspective debate prompts.
+ * Inspired by AITPG multi-agent role specialization (Positive/Negative/Edge + Critic)
+ * and TRACE adversarial debate (Advocate/Challenger/Mediator/Explainer).
+ * Lopez et al., IEEE TSE/TMLCN 2026.
+ */
+function outputDebatePrompt(projectDir, guardData, scoreData, issues) {
+  const lines = [];
+
+  lines.push('═══════════════════════════════════════════════════════');
+  lines.push('MULTI-PERSPECTIVE DOCUMENTATION ANALYSIS');
+  lines.push(`Project: "${guardData.project}" | Score: ${scoreData.score}/100 | Issues: ${issues.length}`);
+  lines.push('Methodology: Multi-agent debate (Lopez et al., AITPG/TRACE, IEEE 2026)');
+  lines.push('═══════════════════════════════════════════════════════');
+  lines.push('');
+
+  // Issue context
+  lines.push('CONTEXT — Current Issues:');
+  for (let i = 0; i < issues.length; i++) {
+    lines.push(`  ${i + 1}. [${issues[i].severity.toUpperCase()}] [${issues[i].validator}] ${issues[i].message}`);
+  }
+  lines.push('');
+
+  // ── Agent 1: Advocate ──
+  lines.push('───────────────────────────────────────────────────────');
+  lines.push('PERSPECTIVE 1: ADVOCATE (What is working well)');
+  lines.push('───────────────────────────────────────────────────────');
+  lines.push('Role: You are the Advocate agent. Your job is to identify what the project');
+  lines.push('documentation is doing RIGHT and which patterns should be PRESERVED.');
+  lines.push('');
+  lines.push('Instructions:');
+  lines.push('1. Read all files in docs-canonical/');
+  lines.push('2. Identify which documents are well-structured and complete');
+  lines.push('3. Note which naming conventions, section formats, and patterns are consistent');
+  lines.push('4. List 3-5 strengths that must be preserved during remediation');
+  lines.push('');
+
+  // ── Agent 2: Challenger ──
+  lines.push('───────────────────────────────────────────────────────');
+  lines.push('PERSPECTIVE 2: CHALLENGER (What is broken or risky)');
+  lines.push('───────────────────────────────────────────────────────');
+  lines.push('Role: You are the Challenger agent. Your job is to STRESS-TEST the documentation');
+  lines.push('and identify gaps, inconsistencies, and risks that the issues list might miss.');
+  lines.push('');
+  lines.push('Instructions:');
+  lines.push('1. For each issue listed above, explain WHY it matters and what the root cause is');
+  lines.push('2. Identify any ADDITIONAL issues not caught by docguard guard');
+  lines.push('3. Check: Are there undocumented API routes? Missing env vars? Stale references?');
+  lines.push('4. Rank all issues by business impact (P0 = blocks deployment, P1 = degrades quality, P2 = cosmetic)');
+  lines.push('');
+
+  // ── Agent 3: Synthesizer ──
+  lines.push('───────────────────────────────────────────────────────');
+  lines.push('PERSPECTIVE 3: SYNTHESIZER (Prioritized remediation plan)');
+  lines.push('───────────────────────────────────────────────────────');
+  lines.push('Role: You are the Synthesizer agent. Given the Advocate\'s strengths and the');
+  lines.push('Challenger\'s gaps, produce a PRIORITIZED and ACTIONABLE remediation plan.');
+  lines.push('');
+  lines.push('Instructions:');
+  lines.push('1. Preserve the patterns the Advocate identified as strengths');
+  lines.push('2. Address the Challenger\'s issues in priority order (P0 → P1 → P2)');
+  lines.push('3. For each fix, specify:');
+  lines.push('   a. Which file to edit');
+  lines.push('   b. What section to add or modify');
+  lines.push('   c. What content to write (be specific, not vague)');
+  lines.push('4. After all fixes, verify with: docguard guard');
+  lines.push(`5. Target score: ≥${Math.min(scoreData.score + 10, 100)}/100`);
+  lines.push('');
+  lines.push('═══════════════════════════════════════════════════════');
+  lines.push('Execute all three perspectives in sequence, then implement the Synthesizer\'s plan.');
+  lines.push('═══════════════════════════════════════════════════════');
+
   console.log(lines.join('\n'));
 }
+
+/**
+ * Detect the AI agent tier from AGENTS.md or .docguard.json.
+ * Returns 'advanced' (concise prompts) or 'basic' (verbose step-by-step).
+ * Inspired by CJE equalizer effect (Lopez et al., TRACE, IEEE TMLCN 2026).
+ */
+function detectAgentTier(projectDir) {
+  // Check .docguard.json for explicit agent config
+  const configPath = resolve(projectDir, '.docguard.json');
+  if (existsSync(configPath)) {
+    try {
+      const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+      if (config.agentTier) return config.agentTier;
+    } catch { /* ignore */ }
+  }
+
+  // Check AGENTS.md for known agent names
+  const agentFiles = ['AGENTS.md', 'CLAUDE.md', '.github/copilot-instructions.md'];
+  for (const file of agentFiles) {
+    const agentPath = resolve(projectDir, file);
+    if (existsSync(agentPath)) {
+      const content = readFileSync(agentPath, 'utf-8').toLowerCase();
+      // Advanced agents: Claude, GPT-4, Gemini Pro
+      const advancedMarkers = ['claude', 'gpt-4', 'gemini pro', 'gemini 2', 'opus', 'sonnet'];
+      if (advancedMarkers.some(m => content.includes(m))) {
+        return 'advanced';
+      }
+    }
+  }
+
+  // Default to advanced (most users run modern models)
+  return 'advanced';
+}