docguard-cli 0.6.0 → 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';
+}

package/cli/commands/generate.mjs

@@ -23,6 +23,70 @@ const CODE_EXTENSIONS = new Set([
   '.py', '.java', '.go', '.rs', '.rb', '.php', '.cs',
 ]);
 
+/**
+ * Standards citation map — each doc type maps to its governing industry standard.
+ * Inspired by RAG-grounded standards alignment (Lopez et al., AITPG, IEEE TSE 2026).
+ */
+const STANDARDS_CITATIONS = {
+  'ARCHITECTURE.md': {
+    standard: 'arc42 Template + C4 Model',
+    reference: 'Starke, G. & Brown, S. "arc42 — Architecture communication template." https://arc42.org | Brown, S. "The C4 Model for visualising software architecture." https://c4model.com',
+    sections: '§1 Introduction, §2 Constraints, §3 Context, §4 Solution Strategy, §5 Building Blocks, §6 Runtime, §7 Deployment, §8 Crosscutting, §9 ADRs, §10 Quality, §11 Risks, §12 Glossary',
+  },
+  'DATA-MODEL.md': {
+    standard: 'C4 Component Diagram + Entity-Relationship (Chen notation)',
+    reference: 'Brown, S. "C4 Model — Component diagrams." https://c4model.com | Chen, P. "The Entity-Relationship Model." ACM TODS 1(1), 1976',
+    sections: 'Entities, Relationships, ER Diagrams (Mermaid), Field-level definitions',
+  },
+  'TEST-SPEC.md': {
+    standard: 'ISO/IEC/IEEE 29119-3:2022 — Test Documentation',
+    reference: 'ISO/IEC/IEEE, "Software and systems engineering — Software testing — Part 3: Test documentation." International Standard, 2022',
+    sections: 'Test Categories, Coverage Rules, Test Matrix, Tool Configuration',
+  },
+  'SECURITY.md': {
+    standard: 'OWASP ASVS v4.0 + CWE Top 25',
+    reference: 'OWASP Foundation, "Application Security Verification Standard v4.0." https://owasp.org/asvs | MITRE, "CWE Top 25." https://cwe.mitre.org/top25',
+    sections: 'Authentication, Secrets Management, Access Control, Input Validation',
+  },
+  'ENVIRONMENT.md': {
+    standard: '12-Factor App Methodology',
+    reference: 'Wiggins, A. "The Twelve-Factor App." https://12factor.net',
+    sections: 'Environment Variables, Config Separation, Setup Steps, Provider Configuration',
+  },
+  'API-REFERENCE.md': {
+    standard: 'OpenAPI Specification 3.1',
+    reference: 'OpenAPI Initiative, "OpenAPI Specification v3.1.0." https://spec.openapis.org/oas/v3.1.0',
+    sections: 'Endpoints, Request/Response schemas, Authentication, Error codes',
+  },
+};
+
+/**
+ * Append a standards citation footer to generated doc content.
+ * @param {string} content - The generated markdown content
+ * @param {string} docName - The filename (e.g., 'ARCHITECTURE.md')
+ * @returns {string} Content with citation footer appended
+ */
+function appendStandardsCitation(content, docName) {
+  const citation = STANDARDS_CITATIONS[docName];
+  if (!citation) return content;
+
+  const footer = `
+---
+
+## Standards Reference
+
+> **Aligned with**: ${citation.standard}
+>
+> **Sections covered**: ${citation.sections}
+>
+> **Reference**: ${citation.reference}
+>
+> *Standards alignment inspired by RAG-grounded generation (Lopez et al., AITPG, IEEE TSE 2026).*
+`;
+
+  return content.trimEnd() + '\n' + footer;
+}
+
 export function runGenerate(projectDir, config, flags) {
   console.log(`${c.bold}🔮 DocGuard Generate — ${config.projectName}${c.reset}`);
   console.log(`${c.dim}   Directory: ${projectDir}${c.reset}`);
@@ -511,7 +575,7 @@ See \\\`docs-canonical/KNOWN-GOTCHAS.md\\\` for known issues.
 | 0.1.0 | ${new Date().toISOString().split('T')[0]} | DocGuard Generate | Auto-generated (arc42 + C4 aligned) |
 `;
 
-  writeFileSync(path, content, 'utf-8');
+  writeFileSync(path, appendStandardsCitation(content, 'ARCHITECTURE.md'), 'utf-8');
   console.log(`  ${c.green}✅ ARCHITECTURE.md${c.reset} (arc42 §1-§12, ${componentRows.length} components, ${Object.values(stack).filter(Boolean).length} tech)`);
   return true;
 }
@@ -608,7 +672,7 @@ ${resourceSections}
 | 0.1.0 | ${new Date().toISOString().split('T')[0]} | DocGuard Generate | Auto-generated (${deepRoutes.length} endpoints from ${deepRoutes[0]?.source || 'code'}) |
 `;
 
-  writeFileSync(path, content, 'utf-8');
+  writeFileSync(path, appendStandardsCitation(content, 'API-REFERENCE.md'), 'utf-8');
   console.log(`  ${c.green}✅ API-REFERENCE.md${c.reset} (${deepRoutes.length} endpoints, ${Object.keys(groups).length} resources)`);
   return true;
 }
@@ -763,7 +827,7 @@ ${erDiagram}
 | 0.1.0 | ${new Date().toISOString().split('T')[0]} | DocGuard Generate | Auto-generated (${entities.length} entities, ${relationships.length} relationships from ${schemaSource}) |
 `;
 
-  writeFileSync(path, content, 'utf-8');
+  writeFileSync(path, appendStandardsCitation(content, 'DATA-MODEL.md'), 'utf-8');
   console.log(`  ${c.green}✅ DATA-MODEL.md${c.reset} (${entities.length} entities, ${relationships.length} relationships from ${schemaSource})`);
   return true;
 }
@@ -826,7 +890,7 @@ ${envVarRows || '| <!-- No .env.example found --> | | | | |'}
 | 0.1.0 | ${new Date().toISOString().split('T')[0]} | DocGuard Generate | Auto-generated (${scan.envVars.length} env vars found) |
 `;
 
-  writeFileSync(path, content, 'utf-8');
+  writeFileSync(path, appendStandardsCitation(content, 'ENVIRONMENT.md'), 'utf-8');
   console.log(`  ${c.green}✅ ENVIRONMENT.md${c.reset} (${scan.envVars.length} env vars detected)`);
   return true;
 }
@@ -911,7 +975,7 @@ ${serviceRows || '| <!-- No services found --> | | | |'}
 | 0.1.0 | ${new Date().toISOString().split('T')[0]} | DocGuard Generate | Auto-generated (${scan.tests.length} test files, ${serviceMap.filter(s => s.status === '✅').length}/${serviceMap.length} mapped) |
 `;
 
-  writeFileSync(path, content, 'utf-8');
+  writeFileSync(path, appendStandardsCitation(content, 'TEST-SPEC.md'), 'utf-8');
   console.log(`  ${c.green}✅ TEST-SPEC.md${c.reset} (${scan.tests.length} tests, ${serviceMap.filter(s => s.status === '✅').length}/${serviceMap.length} services mapped)`);
   return true;
 }
@@ -977,7 +1041,7 @@ ${scan.envVars.filter(v => isSecretVar(v.name)).map(v =>
 | 0.1.0 | ${new Date().toISOString().split('T')[0]} | DocGuard Generate | Auto-generated |
 `;
 
-  writeFileSync(path, content, 'utf-8');
+  writeFileSync(path, appendStandardsCitation(content, 'SECURITY.md'), 'utf-8');
   console.log(`  ${c.green}✅ SECURITY.md${c.reset} (auth: ${stack.auth || 'not detected'})`);
   return true;
 }

package/cli/commands/guard.mjs

@@ -52,7 +52,7 @@ export function runGuardInternal(projectDir, config) {
 
   for (const { key, name, fn } of validatorMap) {
     if (validators[key] === false) {
-      results.push({ name, key, status: 'skipped', errors: [], warnings: [], passed: 0, total: 0 });
+      results.push({ name, key, status: 'skipped', quality: null, errors: [], warnings: [], passed: 0, total: 0 });
       continue;
     }
 
@@ -61,9 +61,22 @@ export function runGuardInternal(projectDir, config) {
       const hasErrors = result.errors.length > 0;
       const hasWarnings = result.warnings.length > 0;
       const status = hasErrors ? 'fail' : hasWarnings ? 'warn' : 'pass';
-      results.push({ ...result, name, key, status });
+
+      // Quality label: HIGH/MEDIUM/LOW (inspired by CJE quality stratification, Lopez et al. TRACE 2026)
+      let quality;
+      if (hasErrors) {
+        quality = 'LOW';
+      } else if (hasWarnings) {
+        quality = 'MEDIUM';
+      } else {
+        // Pass — check coverage ratio for HIGH vs MEDIUM
+        const ratio = result.total > 0 ? result.passed / result.total : 1;
+        quality = ratio >= 0.9 ? 'HIGH' : 'MEDIUM';
+      }
+
+      results.push({ ...result, name, key, status, quality });
     } catch (err) {
-      results.push({ name, key, status: 'fail', errors: [err.message], warnings: [], passed: 0, total: 1 });
+      results.push({ name, key, status: 'fail', quality: 'LOW', errors: [err.message], warnings: [], passed: 0, total: 1 });
     }
   }
 
@@ -114,12 +127,16 @@ export function runGuard(projectDir, config, flags) {
       continue;
     }
 
+    // Quality label badge
+    const qColor = v.quality === 'HIGH' ? c.green : v.quality === 'MEDIUM' ? c.yellow : c.red;
+    const qBadge = `${qColor}[${v.quality}]${c.reset}`;
+
     if (v.status === 'pass') {
-      console.log(`  ${c.green}✅ ${v.name}${c.reset}${c.dim}      ${v.passed}/${v.total} checks passed${c.reset}`);
+      console.log(`  ${c.green}✅ ${v.name}${c.reset} ${qBadge}${c.dim}  ${v.passed}/${v.total} checks passed${c.reset}`);
     } else if (v.status === 'fail') {
-      console.log(`  ${c.red}❌ ${v.name}${c.reset}${c.dim}      ${v.passed}/${v.total} checks passed${c.reset}`);
+      console.log(`  ${c.red}❌ ${v.name}${c.reset} ${qBadge}${c.dim}  ${v.passed}/${v.total} checks passed${c.reset}`);
     } else {
-      console.log(`  ${c.yellow}⚠️  ${v.name}${c.reset}${c.dim}      ${v.passed}/${v.total} checks passed${c.reset}`);
+      console.log(`  ${c.yellow}⚠️  ${v.name}${c.reset} ${qBadge}${c.dim}  ${v.passed}/${v.total} checks passed${c.reset}`);
     }
 
     if (flags.verbose || v.status === 'fail') {

package/cli/commands/score.mjs

@@ -99,6 +99,37 @@ export function runScore(projectDir, config, flags) {
     console.log(`  Tax-to-value ratio:  ${taxColor}${c.bold}${tax.level}${c.reset}`);
     console.log(`  ${c.dim}${tax.recommendation}${c.reset}\n`);
   }
+
+  // ── Multi-Signal Breakdown (--signals flag) ──
+  // Inspired by CJE multi-signal composite scoring (Lopez et al., TRACE, IEEE TMLCN 2026)
+  if (flags.signals) {
+    console.log(`  ${c.bold}📡 Multi-Signal Quality Breakdown${c.reset}`);
+    console.log(`  ${c.dim}─────────────────────────────────${c.reset}`);
+
+    const signals = [
+      { name: 'Structure',     score: scores.structure,    weight: WEIGHTS.structure,    description: 'Required files exist' },
+      { name: 'Doc Quality',   score: scores.docQuality,   weight: WEIGHTS.docQuality,   description: 'Docs have required sections + content' },
+      { name: 'Testing',       score: scores.testing,      weight: WEIGHTS.testing,      description: 'Test spec alignment' },
+      { name: 'Security',      score: scores.security,     weight: WEIGHTS.security,     description: 'No hardcoded secrets, .gitignore' },
+      { name: 'Environment',   score: scores.environment,  weight: WEIGHTS.environment,  description: 'Env docs, .env.example' },
+      { name: 'Drift',         score: scores.drift,        weight: WEIGHTS.drift,        description: 'Drift tracking discipline' },
+      { name: 'Changelog',     score: scores.changelog,    weight: WEIGHTS.changelog,    description: 'Changelog maintenance' },
+      { name: 'Architecture',  score: scores.architecture, weight: WEIGHTS.architecture, description: 'Layer boundary compliance' },
+    ];
+
+    for (const sig of signals) {
+      const weighted = Math.round((sig.score / 100) * sig.weight);
+      const quality = sig.score >= 90 ? 'HIGH' : sig.score >= 50 ? 'MEDIUM' : 'LOW';
+      const qColor = quality === 'HIGH' ? c.green : quality === 'MEDIUM' ? c.yellow : c.red;
+      const bar = renderBar(sig.score);
+
+      console.log(`  ${bar} ${qColor}[${quality}]${c.reset} ${sig.name.padEnd(14)} ${sig.score}% → ${c.bold}${weighted}/${sig.weight}${c.reset} pts  ${c.dim}${sig.description}${c.reset}`);
+    }
+
+    console.log(`\n  ${c.dim}Composite: Σ(signal_score × weight) = ${totalScore}/100${c.reset}`);
+    console.log(`  ${c.dim}Quality labels: HIGH (≥90%), MEDIUM (50-89%), LOW (<50%)${c.reset}`);
+    console.log(`  ${c.dim}Methodology: CJE multi-signal composite (Lopez et al., TRACE, IEEE TMLCN 2026)${c.reset}\n`);
+  }
 }
 
 /**

package/cli/commands/trace.mjs

@@ -0,0 +1,311 @@
+/**
+ * Trace Command — Generate a requirements traceability matrix
+ * Maps canonical docs ↔ source code ↔ tests → produces a traceability report.
+ *
+ * Inspired by requirements traceability in Lopez et al., AITPG (IEEE TSE 2026)
+ * and ISO/IEC/IEEE 29119 traceability requirements.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join, extname, basename, relative } from 'node:path';
+import { c } from '../docguard.mjs';
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
+  '.cache', '__pycache__', '.venv', 'vendor', '.turbo', '.vercel',
+  '.amplify-hosting', '.serverless',
+]);
+
+const CODE_EXTENSIONS = new Set([
+  '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx',
+  '.py', '.java', '.go', '.rs', '.rb', '.php', '.cs',
+]);
+
+const TEST_PATTERNS = [
+  /\.test\.[jt]sx?$/,
+  /\.spec\.[jt]sx?$/,
+  /test_.*\.py$/,
+  /_test\.go$/,
+  /Test\.java$/,
+];
+
+/**
+ * Mapping of canonical documents to the code/config artifacts they trace to.
+ * Each entry defines what source patterns prove coverage of that canonical doc.
+ */
+const TRACE_MAP = {
+  'ARCHITECTURE.md': {
+    standard: 'arc42 / C4 Model',
+    sourcePatterns: [
+      { label: 'Entry points', glob: /^(index|main|app|server)\.[jt]sx?$/ },
+      { label: 'Config files', glob: /^(package\.json|tsconfig.*|next\.config|vite\.config)/ },
+      { label: 'Route handlers', glob: /(routes?|api|pages|app)\// },
+    ],
+  },
+  'DATA-MODEL.md': {
+    standard: 'C4 Component / ER (Chen)',
+    sourcePatterns: [
+      { label: 'Schema definitions', glob: /(schema|model|entity|migration|prisma)/i },
+      { label: 'Type definitions', glob: /types?\.[jt]sx?$/ },
+      { label: 'Database configs', glob: /(drizzle|knex|sequelize|typeorm)/i },
+    ],
+  },
+  'TEST-SPEC.md': {
+    standard: 'ISO/IEC/IEEE 29119-3',
+    sourcePatterns: [
+      { label: 'Test files', glob: /\.(test|spec)\.[jt]sx?$/ },
+      { label: 'Test config', glob: /(jest|vitest|playwright|cypress)\.config/ },
+      { label: 'E2E tests', glob: /(e2e|integration)\// },
+    ],
+  },
+  'SECURITY.md': {
+    standard: 'OWASP ASVS v4.0',
+    sourcePatterns: [
+      { label: 'Auth modules', glob: /(auth|login|session|jwt|oauth|middleware)/i },
+      { label: 'Secret configs', glob: /\.(env|env\.example|env\.local)$/ },
+      { label: 'Gitignore', glob: /^\.gitignore$/ },
+    ],
+  },
+  'ENVIRONMENT.md': {
+    standard: '12-Factor App',
+    sourcePatterns: [
+      { label: 'Env files', glob: /\.env/ },
+      { label: 'Docker configs', glob: /(Dockerfile|docker-compose|\.dockerignore)/ },
+      { label: 'CI/CD configs', glob: /\.(github|gitlab-ci|circleci)/ },
+    ],
+  },
+  'API-REFERENCE.md': {
+    standard: 'OpenAPI 3.1',
+    sourcePatterns: [
+      { label: 'Route handlers', glob: /(routes?|controllers?|handlers?)\// },
+      { label: 'OpenAPI spec', glob: /(openapi|swagger)\.(json|ya?ml)/ },
+      { label: 'API middleware', glob: /middleware\// },
+    ],
+  },
+};
+
+export function runTrace(projectDir, config, flags) {
+  console.log(`${c.bold}🔗 DocGuard Trace — ${config.projectName}${c.reset}`);
+  console.log(`${c.dim}   Directory: ${projectDir}${c.reset}`);
+  console.log(`${c.dim}   Generating requirements traceability matrix...${c.reset}\n`);
+
+  // ── 1. Inventory canonical docs ──
+  const docsDir = resolve(projectDir, 'docs-canonical');
+  const canonicalDocs = [];
+  if (existsSync(docsDir)) {
+    for (const f of readdirSync(docsDir)) {
+      if (f.endsWith('.md')) canonicalDocs.push(f);
+    }
+  }
+
+  // ── 2. Scan project files ──
+  const projectFiles = [];
+  scanDir(projectDir, projectDir, projectFiles);
+
+  // ── 3. Build traceability matrix ──
+  const matrix = [];
+
+  for (const [docName, traceInfo] of Object.entries(TRACE_MAP)) {
+    const docPath = resolve(docsDir, docName);
+    const docExists = existsSync(docPath);
+    let lastModified = null;
+    let docSize = 0;
+
+    if (docExists) {
+      const stat = statSync(docPath);
+      lastModified = stat.mtime.toISOString().split('T')[0];
+      docSize = stat.size;
+    }
+
+    // Find matching source files for each pattern
+    const traces = [];
+    for (const pattern of traceInfo.sourcePatterns) {
+      const matches = projectFiles.filter(f => pattern.glob.test(f));
+      traces.push({
+        label: pattern.label,
+        matchCount: matches.length,
+        files: matches.slice(0, 5), // Cap at 5 for display
+        hasMore: matches.length > 5,
+      });
+    }
+
+    // Find test coverage (files that test code related to this doc)
+    const relatedTests = findRelatedTests(projectFiles, traceInfo.sourcePatterns);
+
+    // Calculate coverage signal
+    const totalSources = traces.reduce((sum, t) => sum + t.matchCount, 0);
+    const coverageSignal = !docExists ? 'MISSING'
+      : totalSources === 0 ? 'UNLINKED'
+      : relatedTests.length > 0 ? 'TRACED'
+      : 'PARTIAL';
+
+    matrix.push({
+      document: docName,
+      standard: traceInfo.standard,
+      exists: docExists,
+      lastModified,
+      docSize,
+      traces,
+      relatedTests,
+      totalSources,
+      coverageSignal,
+    });
+  }
+
+  // ── 4. Output ──
+  if (flags.format === 'json') {
+    outputJSON(config.projectName, matrix);
+  } else {
+    outputText(config.projectName, matrix, canonicalDocs);
+  }
+}
+
+function outputJSON(projectName, matrix) {
+  const result = {
+    project: projectName,
+    traceability: matrix.map(m => ({
+      document: m.document,
+      standard: m.standard,
+      exists: m.exists,
+      lastModified: m.lastModified,
+      coverageSignal: m.coverageSignal,
+      sources: m.totalSources,
+      tests: m.relatedTests.length,
+      traces: m.traces,
+    })),
+    summary: {
+      total: matrix.length,
+      traced: matrix.filter(m => m.coverageSignal === 'TRACED').length,
+      partial: matrix.filter(m => m.coverageSignal === 'PARTIAL').length,
+      unlinked: matrix.filter(m => m.coverageSignal === 'UNLINKED').length,
+      missing: matrix.filter(m => m.coverageSignal === 'MISSING').length,
+    },
+    timestamp: new Date().toISOString(),
+  };
+  console.log(JSON.stringify(result, null, 2));
+}
+
+function outputText(projectName, matrix, canonicalDocs) {
+  // Header table
+  console.log(`  ${c.bold}Traceability Matrix${c.reset}\n`);
+  console.log(`  ${c.dim}${'Document'.padEnd(22)} ${'Standard'.padEnd(28)} ${'Status'.padEnd(10)} ${'Sources'.padEnd(9)} ${'Tests'.padEnd(7)} ${'Last Modified'}${c.reset}`);
+  console.log(`  ${c.dim}${'─'.repeat(22)} ${'─'.repeat(28)} ${'─'.repeat(10)} ${'─'.repeat(9)} ${'─'.repeat(7)} ${'─'.repeat(14)}${c.reset}`);
+
+  for (const entry of matrix) {
+    const statusColor = entry.coverageSignal === 'TRACED' ? c.green
+      : entry.coverageSignal === 'PARTIAL' ? c.yellow
+      : entry.coverageSignal === 'UNLINKED' ? c.yellow
+      : c.red;
+    const statusIcon = entry.coverageSignal === 'TRACED' ? '✅'
+      : entry.coverageSignal === 'PARTIAL' ? '⚠️ '
+      : entry.coverageSignal === 'UNLINKED' ? '🔗'
+      : '❌';
+
+    console.log(`  ${statusIcon} ${entry.document.padEnd(19)} ${c.dim}${entry.standard.padEnd(28)}${c.reset} ${statusColor}${entry.coverageSignal.padEnd(10)}${c.reset} ${String(entry.totalSources).padEnd(9)} ${String(entry.relatedTests.length).padEnd(7)} ${entry.lastModified || c.dim + 'n/a' + c.reset}`);
+  }
+
+  // Detailed traces (verbose)
+  console.log(`\n  ${c.bold}Detailed Traces${c.reset}\n`);
+
+  for (const entry of matrix) {
+    if (!entry.exists) {
+      console.log(`  ${c.red}❌ ${entry.document}${c.reset} — ${c.dim}Document not found. Run \`docguard generate\` to create.${c.reset}`);
+      continue;
+    }
+
+    console.log(`  ${c.bold}📄 ${entry.document}${c.reset} ${c.dim}(${entry.standard})${c.reset}`);
+
+    for (const trace of entry.traces) {
+      const icon = trace.matchCount > 0 ? `${c.green}✓${c.reset}` : `${c.dim}○${c.reset}`;
+      console.log(`     ${icon} ${trace.label}: ${trace.matchCount} file(s)`);
+      if (trace.matchCount > 0 && trace.files.length > 0) {
+        for (const f of trace.files) {
+          console.log(`       ${c.dim}→ ${f}${c.reset}`);
+        }
+        if (trace.hasMore) {
+          console.log(`       ${c.dim}  ... and ${trace.matchCount - 5} more${c.reset}`);
+        }
+      }
+    }
+
+    if (entry.relatedTests.length > 0) {
+      console.log(`     ${c.green}✓${c.reset} Test coverage: ${entry.relatedTests.length} test file(s)`);
+      for (const t of entry.relatedTests.slice(0, 3)) {
+        console.log(`       ${c.dim}→ ${t}${c.reset}`);
+      }
+      if (entry.relatedTests.length > 3) {
+        console.log(`       ${c.dim}  ... and ${entry.relatedTests.length - 3} more${c.reset}`);
+      }
+    } else {
+      console.log(`     ${c.yellow}○${c.reset} ${c.dim}No related test files found${c.reset}`);
+    }
+    console.log('');
+  }
+
+  // Summary
+  const traced = matrix.filter(m => m.coverageSignal === 'TRACED').length;
+  const partial = matrix.filter(m => m.coverageSignal === 'PARTIAL').length;
+  const unlinked = matrix.filter(m => m.coverageSignal === 'UNLINKED').length;
+  const missing = matrix.filter(m => m.coverageSignal === 'MISSING').length;
+
+  console.log(`  ${c.bold}─────────────────────────────────────${c.reset}`);
+  console.log(`  ${c.green}Traced: ${traced}${c.reset}  ${c.yellow}Partial: ${partial}${c.reset}  ${c.yellow}Unlinked: ${unlinked}${c.reset}  ${c.red}Missing: ${missing}${c.reset}`);
+  console.log(`  ${c.dim}Total: ${matrix.length} canonical documents evaluated${c.reset}`);
+
+  if (missing > 0 || unlinked > 0) {
+    console.log(`\n  ${c.dim}Run ${c.cyan}docguard generate${c.dim} to create missing docs.${c.reset}`);
+    console.log(`  ${c.dim}Run ${c.cyan}docguard diagnose${c.dim} to fix coverage gaps.${c.reset}`);
+  }
+
+  console.log(`\n  ${c.dim}Traceability methodology: ISO/IEC/IEEE 29119 (Lopez et al., AITPG, IEEE TSE 2026)${c.reset}\n`);
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function scanDir(rootDir, dir, files) {
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch { return; }
+
+  for (const entry of entries) {
+    if (IGNORE_DIRS.has(entry)) continue;
+    if (entry.startsWith('.') && entry !== '.env' && entry !== '.env.example'
+        && entry !== '.gitignore' && !entry.startsWith('.github')) continue;
+
+    const full = join(dir, entry);
+    let stat;
+    try { stat = statSync(full); } catch { continue; }
+
+    if (stat.isDirectory()) {
+      scanDir(rootDir, full, files);
+    } else {
+      files.push(relative(rootDir, full));
+    }
+  }
+}
+
+function findRelatedTests(projectFiles, sourcePatterns) {
+  // Find test files that might cover the source patterns
+  const testFiles = projectFiles.filter(f => TEST_PATTERNS.some(p => p.test(f)));
+
+  // Match tests to source patterns by directory/name proximity
+  const relatedTests = new Set();
+
+  for (const pattern of sourcePatterns) {
+    const sourceFiles = projectFiles.filter(f => pattern.glob.test(f));
+    for (const src of sourceFiles) {
+      const srcBase = basename(src).replace(/\.[^.]+$/, '');
+      const srcDir = src.split('/')[0];
+
+      for (const test of testFiles) {
+        // Match by name similarity or directory proximity
+        if (test.includes(srcBase) || test.includes(srcDir)) {
+          relatedTests.add(test);
+        }
+      }
+    }
+  }
+
+  return [...relatedTests];
+}

package/cli/docguard.mjs

@@ -36,6 +36,7 @@ import { runFix } from './commands/fix.mjs';
 import { runWatch } from './commands/watch.mjs';
 import { runDiagnose } from './commands/diagnose.mjs';
 import { runPublish } from './commands/publish.mjs';
+import { runTrace } from './commands/trace.mjs';
 
 // ── Colors (ANSI escape codes, zero deps) ──────────────────────────────────
 export const c = {
@@ -287,6 +288,7 @@ ${c.bold}Commands:${c.reset}
   ${c.green}fix${c.reset}        Find issues and generate AI fix instructions
   ${c.green}watch${c.reset}      Watch for file changes and re-run guard automatically
   ${c.green}publish${c.reset}    Scaffold external docs (Mintlify, Docusaurus)
+  ${c.green}trace${c.reset}      Generate requirements traceability matrix
 
 ${c.bold}Options:${c.reset}
   --dir <path>    Project directory (default: current directory)
@@ -396,6 +398,12 @@ function main() {
     } else if (args[i] === '--platform' && args[i + 1]) {
       flags.platform = args[i + 1];
       i++;
+    } else if (args[i] === '--no-fix') {
+      flags.noFix = true;
+    } else if (args[i] === '--signals') {
+      flags.signals = true;
+    } else if (args[i] === '--debate') {
+      flags.debate = true;
     }
   }
 
@@ -464,6 +472,10 @@ function main() {
     case 'pub':
       runPublish(projectDir, config, flags);
       break;
+    case 'trace':
+    case 'traceability':
+      runTrace(projectDir, config, flags);
+      break;
     default:
       console.error(`${c.red}Unknown command: ${command}${c.reset}`);
       console.log(`Run ${c.cyan}docguard --help${c.reset} for usage.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {