docguard-cli 0.27.0 → 0.29.0

package/cli/validators/docs-diff.mjs

@@ -7,12 +7,18 @@
  *
  * Respects config.ignore and config.testPatterns for test file discovery.
  * Uses shared-ignore.mjs for consistent filtering (Constitution IV, v1.1.0).
+ *
+ * v0.29: migrated to structured findings (DDF001–DDF002). Messages are
+ * byte-identical to the legacy strings — resultFromFindings derives the
+ * errors/warnings arrays from the same findings, so counts, exit codes, and
+ * existing tests are unaffected; guard just renders richer output.
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname, basename, relative } from 'node:path';
-import { shouldIgnore, globMatch } from '../shared-ignore.mjs';
+import { shouldIgnore, globMatch, walkFiles as sharedWalkFiles } from '../shared-ignore.mjs';
 import { collectPackageJsons, detectDocker, resolveSourceRoots } from '../shared-source.mjs';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build',
@@ -25,12 +31,35 @@ const CODE_EXTENSIONS = new Set([
   '.py', '.java', '.go', '.rs', '.rb', '.php',
 ]);
 
+// v0.29: one stable finding code per drift domain (not per occurrence).
+// Location = the canonical doc that owns the domain, so an agent knows which
+// file to reconcile. Drift is two-sided (doc stale OR code changed), hence
+// suggestion kind 'review' — a human decides which side is wrong.
+const DRIFT_FINDINGS = {
+  'Tech Stack': {
+    code: 'DDF001',
+    location: 'docs-canonical/ARCHITECTURE.md',
+    suggestion: {
+      kind: 'review',
+      text: 'Reconcile the Tech Stack in ARCHITECTURE.md with the actual dependencies — document the new tech or remove stale entries',
+    },
+  },
+  'Test Files': {
+    code: 'DDF002',
+    location: 'docs-canonical/TEST-SPEC.md',
+    suggestion: {
+      kind: 'review',
+      text: 'Reconcile TEST-SPEC.md with the test files on disk — document new tests or remove stale entries',
+    },
+  },
+};
+
 /**
  * Validate doc-code alignment — compares canonical docs vs source code.
  * @returns {{ errors: string[], warnings: string[], passed: number, total: number }}
  */
 export function validateDocsDiff(projectDir, config) {
-  const warnings = [];
+  const findings = [];
   let passed = 0;
   let total = 0;
 
@@ -70,11 +99,19 @@ export function validateDocsDiff(projectDir, config) {
       if (stale > 0) {
         parts.push(`${stale} documented but not found in code: ${fmtList(result.onlyInDocs)}`);
       }
-      warnings.push(`${result.title} drift: ${parts.join('; ')}`);
+      const meta = DRIFT_FINDINGS[result.title] || {};
+      findings.push(mkFinding({
+        code: meta.code,
+        validator: 'docsDiff',
+        severity: 'warn',
+        message: `${result.title} drift: ${parts.join('; ')}`,
+        location: meta.location,
+        suggestion: meta.suggestion,
+      }));
     }
   }
 
-  return { errors: [], warnings, passed, total };
+  return resultFromFindings(findings, { passed, total });
 }
 
 // ── Diff Functions (lightweight versions for validator) ──────────────────
@@ -244,77 +281,39 @@ export function collectCodeTests(dir, config = {}) {
 export function getTestFilesFromPatterns(dir, patterns, config) {
   const results = new Set();
 
-  function walk(currentDir) {
-    let entries;
-    try { entries = readdirSync(currentDir); } catch { return; }
-
-    for (const entry of entries) {
-      // Skip node_modules and other ignored dirs at directory level (fast path)
-      if (IGNORE_DIRS.has(entry) || entry.startsWith('.')) continue;
-      const fullPath = join(currentDir, entry);
-      try {
-        const stat = statSync(fullPath);
-        if (stat.isDirectory()) {
-          walk(fullPath);
-        } else if (stat.isFile()) {
-          const relPath = relative(dir, fullPath);
-          // Skip files in globally ignored paths
-          if (config && shouldIgnore(relPath, config)) continue;
-          // Use globMatch for positive pattern matching (rejects node_modules internally)
-          if (globMatch(relPath, patterns)) {
-            results.add(relPath);
-          }
-        }
-      } catch { /* skip */ }
+  // v0.29 consolidation: traversal delegates to the shared canonical walker;
+  // per-file filtering (config ignore + positive globMatch) stays here.
+  sharedWalkFiles(dir, (fullPath) => {
+    const relPath = relative(dir, fullPath);
+    // Skip files in globally ignored paths
+    if (config && shouldIgnore(relPath, config)) return;
+    // Use globMatch for positive pattern matching (rejects node_modules internally)
+    if (globMatch(relPath, patterns)) {
+      results.add(relPath);
     }
-  }
-
-  walk(dir);
+  }, { ignoreDirs: IGNORE_DIRS });
   return [...results];
 }
 
 /** Returns true if any file with the given extension exists under dir (ignoring vendor dirs). */
 function hasFileWithExt(dir, ext, config) {
+  // v0.29 consolidation: shared walker. The old hand-rolled version early-exited
+  // on first match; the shared walker completes the traversal — acceptable here
+  // (one-shot existence probe on source trees already pruned by IGNORE_DIRS).
   let found = false;
-  const walk = (d) => {
-    if (found) return;
-    let entries;
-    try { entries = readdirSync(d); } catch { return; }
-    for (const entry of entries) {
-      if (found) return;
-      if (IGNORE_DIRS.has(entry) || entry.startsWith('.')) continue;
-      const full = join(d, entry);
-      try {
-        const stat = statSync(full);
-        if (stat.isDirectory()) walk(full);
-        else if (stat.isFile() && extname(full) === ext) {
-          const rel = relative(dir, full);
-          if (!config || !shouldIgnore(rel, config)) found = true;
-        }
-      } catch { /* skip */ }
-    }
-  };
-  walk(dir);
+  sharedWalkFiles(dir, (full) => {
+    if (found || extname(full) !== ext) return;
+    const rel = relative(dir, full);
+    if (!config || !shouldIgnore(rel, config)) found = true;
+  }, { ignoreDirs: IGNORE_DIRS });
   return found;
 }
 
+// v0.29 consolidation: traversal delegates to the shared canonical walker.
 function getFilesRecursive(dir, config) {
   const results = [];
-  if (!existsSync(dir)) return results;
-  let entries;
-  try { entries = readdirSync(dir); } catch { return results; }
-
-  for (const entry of entries) {
-    if (IGNORE_DIRS.has(entry) || entry.startsWith('.')) continue;
-    const fullPath = join(dir, entry);
-    try {
-      const stat = statSync(fullPath);
-      if (stat.isDirectory()) {
-        results.push(...getFilesRecursive(fullPath, config));
-      } else if (stat.isFile() && CODE_EXTENSIONS.has(extname(fullPath))) {
-        results.push(fullPath);
-      }
-    } catch { /* skip */ }
-  }
+  sharedWalkFiles(dir, (fullPath) => {
+    if (CODE_EXTENSIONS.has(extname(fullPath))) results.push(fullPath);
+  }, { ignoreDirs: IGNORE_DIRS });
   return results;
 }

package/cli/validators/docs-sync.mjs

@@ -1,11 +1,17 @@
 /**
  * Docs-Sync Validator — Checks that source files have matching canonical doc entries
+ *
+ * v0.29: migrated to structured findings (DSY001–DSY003). Messages are
+ * byte-identical to the legacy strings — resultFromFindings derives the
+ * errors/warnings arrays from the same findings, so counts, exit codes, and
+ * existing tests are unaffected; guard just renders richer output.
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname, basename } from 'node:path';
 import { resolveSourceRoots } from '../shared-source.mjs';
-import { relPosix } from '../shared-ignore.mjs';
+import { relPosix, walkFiles as sharedWalkFiles } from '../shared-ignore.mjs';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', '.nuxt', 'dist', 'build', 'out',
@@ -61,7 +67,9 @@ function expandDirs(projectDir, config, subPaths) {
 }
 
 export function validateDocsSync(projectDir, config) {
-  const results = { name: 'docs-sync', errors: [], warnings: [], passed: 0, total: 0 };
+  const findings = [];
+  let passed = 0;
+  let total = 0;
 
   // Load all canonical doc content for checking
   const canonicalDir = resolve(projectDir, 'docs-canonical');
@@ -78,7 +86,8 @@ export function validateDocsSync(projectDir, config) {
   }
 
   if (!canonicalContent) {
-    return results; // No canonical docs to check against
+    // No canonical docs to check against
+    return { name: 'docs-sync', ...resultFromFindings([], { passed: 0, total: 0 }) };
   }
 
   // N-1: When the guard runs in --changed-only mode, config.changedFiles is
@@ -110,14 +119,21 @@ export function validateDocsSync(projectDir, config) {
       // N-1: skip files outside the --changed-only scope.
       if (!inScope(relPath)) continue;
 
-      results.total++;
+      total++;
       const name = basename(file, ext);
 
       // Check if the file path or name is mentioned in any canonical doc
       if (canonicalContent.includes(relPath) || canonicalContent.includes(name)) {
-        results.passed++;
+        passed++;
       } else {
-        results.warnings.push(`route ${relPath} not referenced in any canonical doc`);
+        findings.push(mkFinding({
+          code: 'DSY001',
+          validator: 'docsSync',
+          severity: 'warn',
+          message: `route ${relPath} not referenced in any canonical doc`,
+          location: relPath,
+          suggestion: { kind: 'fix', text: 'Reference this route (by path or name) in a canonical doc, e.g. ARCHITECTURE.md' },
+        }));
       }
     }
   }
@@ -135,13 +151,20 @@ export function validateDocsSync(projectDir, config) {
       // N-1: skip files outside the --changed-only scope.
       if (!inScope(relPath)) continue;
 
-      results.total++;
+      total++;
       const name = basename(file, ext);
 
       if (canonicalContent.includes(relPath) || canonicalContent.includes(name)) {
-        results.passed++;
+        passed++;
       } else {
-        results.warnings.push(`Service ${relPath} not referenced in any canonical doc`);
+        findings.push(mkFinding({
+          code: 'DSY002',
+          validator: 'docsSync',
+          severity: 'warn',
+          message: `Service ${relPath} not referenced in any canonical doc`,
+          location: relPath,
+          suggestion: { kind: 'fix', text: 'Reference this service (by path or name) in a canonical doc, e.g. ARCHITECTURE.md' },
+        }));
       }
     }
   }
@@ -184,7 +207,7 @@ export function validateDocsSync(projectDir, config) {
         const rawName = basename(file, ext).toLowerCase();
         if (rawName === 'index' || rawName === 'middleware' || rawName.startsWith('_')) continue;
 
-        results.total++;
+        total++;
 
         // Strategy 1: Parse the route file for actual route paths
         // Look for router.get('/path'), app.post('/path'), etc.
@@ -224,38 +247,30 @@ export function validateDocsSync(projectDir, config) {
         }
 
         if (matched) {
-          results.passed++;
+          passed++;
         } else {
-          results.warnings.push(
-            `Route file ${basename(file)} exists but no matching paths found in ${openapiFile}. ` +
-            `Run your spec generator (e.g., zod-to-openapi) to update the API spec`
-          );
+          findings.push(mkFinding({
+            code: 'DSY003',
+            validator: 'docsSync',
+            severity: 'warn',
+            message: `Route file ${basename(file)} exists but no matching paths found in ${openapiFile}. ` +
+              `Run your spec generator (e.g., zod-to-openapi) to update the API spec`,
+            location: relPathForFilter,
+            suggestion: { kind: 'fix', text: `Regenerate ${openapiFile} (e.g. via zod-to-openapi) so it covers this route file's paths` },
+          }));
         }
       }
     }
   }
 
-  return results;
+  return { name: 'docs-sync', ...resultFromFindings(findings, { passed, total }) };
 }
 
+// v0.29 consolidation: traversal delegates to the shared canonical walker;
+// IGNORE_DIRS stays local (its __tests__/__test__ entries are intentional —
+// co-located test dirs are not the source under documentation).
 function getFilesRecursive(dir) {
   const results = [];
-  if (!existsSync(dir)) return results;
-
-  const entries = readdirSync(dir);
-  for (const entry of entries) {
-    if (IGNORE_DIRS.has(entry) || entry.startsWith('.')) continue;
-    const fullPath = join(dir, entry);
-    try {
-      const stat = statSync(fullPath);
-      if (stat.isDirectory()) {
-        results.push(...getFilesRecursive(fullPath));
-      } else {
-        results.push(fullPath);
-      }
-    } catch {
-      // Skip
-    }
-  }
+  sharedWalkFiles(dir, (fullPath) => results.push(fullPath), { ignoreDirs: IGNORE_DIRS });
   return results;
 }

package/cli/validators/drift.mjs

@@ -1,10 +1,16 @@
 /**
  * Drift Validator — Every // DRIFT: comment must have a DRIFT-LOG.md entry
+ *
+ * v0.29: migrated to structured findings (DRF001–DRF002). Messages are
+ * byte-identical to the legacy strings — resultFromFindings derives the
+ * errors/warnings arrays from the same findings, so counts, exit codes, and
+ * existing tests are unaffected; guard just renders richer output.
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname } from 'node:path';
-import { relPosix } from '../shared-ignore.mjs';
+import { relPosix, walkFiles as sharedWalkFiles } from '../shared-ignore.mjs';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 const CODE_EXTENSIONS = new Set([
   '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx',
@@ -19,7 +25,9 @@ const IGNORE_DIRS = new Set([
 ]);
 
 export function validateDrift(projectDir, config) {
-  const results = { name: 'drift', errors: [], warnings: [], passed: 0, total: 0 };
+  const findings = [];
+  let passed = 0;
+  let total = 0;
 
   // v0.15-P3: when config.changedFiles is set (--changed-only mode), only
   // visit the listed paths. Drift comments in unchanged files are still in
@@ -64,58 +72,56 @@ export function validateDrift(projectDir, config) {
 
   if (driftComments.length === 0) {
     // No // DRIFT: comments to reconcile — not applicable (NOT a pass).
-    results.note = 'no // DRIFT: comments in code';
-    return results;
+    return {
+      name: 'drift',
+      ...resultFromFindings([], { passed: 0, total: 0 }),
+      note: 'no // DRIFT: comments in code',
+    };
   }
 
   // Read DRIFT-LOG.md
   const driftLogPath = resolve(projectDir, config.requiredFiles.driftLog);
   if (!existsSync(driftLogPath)) {
-    results.total = driftComments.length;
     for (const dc of driftComments) {
-      results.errors.push(
-        `${dc.file}:${dc.line} has DRIFT comment but DRIFT-LOG.md doesn't exist`
-      );
+      findings.push(mkFinding({
+        code: 'DRF001',
+        validator: 'drift',
+        severity: 'error',
+        message: `${dc.file}:${dc.line} has DRIFT comment but DRIFT-LOG.md doesn't exist`,
+        location: `${dc.file}:${dc.line}`,
+        suggestion: { kind: 'fix', text: 'Create the drift log, then record this deviation in it', command: 'docguard init' },
+      }));
     }
-    return results;
+    return { name: 'drift', ...resultFromFindings(findings, { passed: 0, total: driftComments.length }) };
   }
 
   const driftLogContent = readFileSync(driftLogPath, 'utf-8');
 
   // Check each drift comment has a matching entry in DRIFT-LOG.md
   for (const dc of driftComments) {
-    results.total++;
+    total++;
     // Check if the file is mentioned in DRIFT-LOG.md
     if (driftLogContent.includes(dc.file)) {
-      results.passed++;
+      passed++;
     } else {
-      results.errors.push(
-        `${dc.file}:${dc.line} — DRIFT comment not logged in DRIFT-LOG.md`
-      );
+      findings.push(mkFinding({
+        code: 'DRF002',
+        validator: 'drift',
+        severity: 'error',
+        message: `${dc.file}:${dc.line} — DRIFT comment not logged in DRIFT-LOG.md`,
+        location: `${dc.file}:${dc.line}`,
+        suggestion: { kind: 'fix', text: 'Add an entry for this file to DRIFT-LOG.md explaining the deviation' },
+      }));
     }
   }
 
-  return results;
+  return { name: 'drift', ...resultFromFindings(findings, { passed, total }) };
 }
 
+// v0.29 consolidation: traversal delegates to the shared canonical walker;
+// the IGNORE_DIRS set above stays local because its entries are intentional
+// per-validator variance (e.g. 'cli' — DocGuard's own source has DRIFT: in
+// regex patterns).
 function walkDir(dir, callback) {
-  if (!existsSync(dir)) return;
-
-  const entries = readdirSync(dir);
-  for (const entry of entries) {
-    if (IGNORE_DIRS.has(entry)) continue;
-    if (entry.startsWith('.')) continue;
-
-    const fullPath = join(dir, entry);
-    try {
-      const stat = statSync(fullPath);
-      if (stat.isDirectory()) {
-        walkDir(fullPath, callback);
-      } else if (stat.isFile()) {
-        callback(fullPath);
-      }
-    } catch {
-      // Skip files we can't read
-    }
-  }
+  sharedWalkFiles(dir, callback, { ignoreDirs: IGNORE_DIRS });
 }

package/cli/validators/environment.mjs

@@ -1,19 +1,30 @@
 /**
  * Environment Validator — Checks ENVIRONMENT.md docs and .env.example
  * Now respects projectTypeConfig (e.g., skip env checks for CLI tools)
+ *
+ * v0.29: migrated to structured findings (ENV001–ENV005). Messages are
+ * byte-identical to the legacy strings — resultFromFindings derives the
+ * errors/warnings arrays from the same findings, so counts, exit codes, and
+ * existing tests are unaffected; guard just renders richer output.
  */
 
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { grepEnvUsage } from '../shared-source.mjs';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 export function validateEnvironment(projectDir, config) {
-  const results = { name: 'environment', errors: [], warnings: [], passed: 0, total: 0 };
+  const findings = [];
+  let passed = 0;
+  let total = 0;
   const ptc = config.projectTypeConfig || {};
 
-  const envDocPath = resolve(projectDir, 'docs-canonical/ENVIRONMENT.md');
+  const envDoc = 'docs-canonical/ENVIRONMENT.md';
+  const envDocPath = resolve(projectDir, envDoc);
   if (!existsSync(envDocPath)) {
-    return results; // Structure validator catches missing files
+    // Structure validator catches missing files. Keep the exact legacy shape
+    // here (no `findings` key) — tests deep-equal this early return.
+    return { name: 'environment', errors: [], warnings: [], passed: 0, total: 0 };
   }
 
   const content = readFileSync(envDocPath, 'utf-8');
@@ -21,18 +32,32 @@ export function validateEnvironment(projectDir, config) {
   // Check for required sections (anchored headings — not substring matches that
   // could hit a TOC entry or code block).
   const hasHeading = (re) => re.test(content);
-  results.total++;
+  total++;
   if (hasHeading(/^#{2,3}\s+(Prerequisites|Setup Steps)\b/m)) {
-    results.passed++;
+    passed++;
   } else {
-    results.warnings.push('ENVIRONMENT.md: missing "## Prerequisites" or "## Setup Steps" section');
+    findings.push(mkFinding({
+      code: 'ENV001',
+      validator: 'environment',
+      severity: 'warn',
+      message: 'ENVIRONMENT.md: missing "## Prerequisites" or "## Setup Steps" section',
+      location: envDoc,
+      suggestion: { kind: 'fix', text: 'Add a "## Setup Steps" (or "## Prerequisites") section describing how to get the project running' },
+    }));
   }
 
-  results.total++;
+  total++;
   if (hasHeading(/^#{2,3}\s+Environment Variables\b/m)) {
-    results.passed++;
+    passed++;
   } else {
-    results.warnings.push('ENVIRONMENT.md: missing "## Environment Variables" section');
+    findings.push(mkFinding({
+      code: 'ENV002',
+      validator: 'environment',
+      severity: 'warn',
+      message: 'ENVIRONMENT.md: missing "## Environment Variables" section',
+      location: envDoc,
+      suggestion: { kind: 'fix', text: 'Add a "## Environment Variables" section documenting each variable the app reads' },
+    }));
   }
 
   // ── Real code-truth check: env vars USED in code but documented nowhere ──
@@ -92,15 +117,20 @@ export function validateEnvironment(projectDir, config) {
     // vacuous (always passes) and would just inflate the count.
     if (codeUsed.size > 0) {
       const usedButUndocumented = [...codeUsed].filter(v => !documented.has(v));
-      results.total++;
+      total++;
       if (usedButUndocumented.length === 0) {
-        results.passed++;
+        passed++;
       } else {
         const shown = usedButUndocumented.slice(0, 10).join(', ');
         const more = usedButUndocumented.length > 10 ? ` (+${usedButUndocumented.length - 10} more)` : '';
-        results.warnings.push(
-          `${usedButUndocumented.length} env var(s) used in code but not documented in ENVIRONMENT.md / .env.example: ${shown}${more}`
-        );
+        findings.push(mkFinding({
+          code: 'ENV003',
+          validator: 'environment',
+          severity: 'warn',
+          message: `${usedButUndocumented.length} env var(s) used in code but not documented in ENVIRONMENT.md / .env.example: ${shown}${more}`,
+          location: envDoc,
+          suggestion: { kind: 'fix', text: 'Document each listed variable in ENVIRONMENT.md, or add it to .env.example' },
+        }));
       }
     }
   }
@@ -109,35 +139,45 @@ export function validateEnvironment(projectDir, config) {
   if (ptc.needsEnvExample !== false && ptc.needsEnvVars !== false) {
     // Check if .env.example is referenced and exists
     if (content.includes('.env.example')) {
-      results.total++;
+      total++;
       if (existsSync(resolve(projectDir, '.env.example'))) {
-        results.passed++;
+        passed++;
       } else {
-        results.warnings.push(
-          'ENVIRONMENT.md references .env.example but the file does not exist'
-        );
+        findings.push(mkFinding({
+          code: 'ENV004',
+          validator: 'environment',
+          severity: 'warn',
+          message: 'ENVIRONMENT.md references .env.example but the file does not exist',
+          location: envDoc,
+          suggestion: { kind: 'fix', text: 'Create .env.example with placeholder values, or remove the stale reference from ENVIRONMENT.md' },
+        }));
       }
     }
 
     // Check if any .env file exists but no .env.example is provided
-    results.total++;
+    total++;
     const hasEnvFile = ['.env', '.env.local', '.env.development'].some(f =>
       existsSync(resolve(projectDir, f))
     );
     const hasEnvExample = existsSync(resolve(projectDir, '.env.example'));
 
     if (hasEnvFile && !hasEnvExample) {
-      results.warnings.push(
-        '.env file exists but no .env.example template — new contributors won\'t know what vars to set'
-      );
+      findings.push(mkFinding({
+        code: 'ENV005',
+        validator: 'environment',
+        severity: 'warn',
+        message: '.env file exists but no .env.example template — new contributors won\'t know what vars to set',
+        location: '.env.example',
+        suggestion: { kind: 'fix', text: 'Create a .env.example template listing every variable with a placeholder value' },
+      }));
     } else {
-      results.passed++;
+      passed++;
     }
   } else {
     // CLI/library project — just verify doc exists and has basic content
-    results.total++;
-    results.passed++;
+    total++;
+    passed++;
   }
 
-  return results;
+  return { name: 'environment', ...resultFromFindings(findings, { passed, total }) };
 }

package/cli/validators/freshness.mjs

@@ -28,11 +28,8 @@ try {
   _sharedGetLastCommitDate = null;
 }
 
-const IGNORE_DIRS = new Set([
-  'node_modules', '.git', '.next', 'dist', 'build',
-  'coverage', '.cache', '__pycache__', '.venv', 'vendor',
-  'templates', 'configs', 'Research',
-]);
+// (v0.29 cleanup: a dead IGNORE_DIRS set lived here — defined but never
+// referenced. Freshness reads specific configured docs; it never walks.)
 
 /**
  * Read the `<!-- docguard:last-reviewed YYYY-MM-DD -->` header from a doc file.
@@ -245,6 +242,8 @@ export function validateFreshness(dir, config) {
       // an agent that can stamp a marker but not commit was left guessing.
       results.push({
         status: 'warn',
+        code: 'FRS001',
+        doc: docFile,
         message: `${docFile} exists but is not yet committed to git — commit it, or add a <!-- docguard:last-reviewed YYYY-MM-DD --> marker (or <!-- docguard:status approved -->).`,
       });
       continue;
@@ -266,6 +265,8 @@ export function validateFreshness(dir, config) {
     if (codeCommitsSince >= WARNING_THRESHOLD_COMMITS) {
       results.push({
         status: 'warn',
+        code: 'FRS002',
+        doc: docFile,
         message: `${docFile} — ${codeCommitsSince} code commits since last doc update (${docDate.toISOString().split('T')[0]})`,
       });
       continue;
@@ -277,6 +278,8 @@ export function validateFreshness(dir, config) {
       if (daysDiff > STALE_THRESHOLD_DAYS) {
         results.push({
           status: 'warn',
+          code: 'FRS003',
+          doc: docFile,
           message: `${docFile} — last updated ${daysDiff} days before latest code change`,
         });
         continue;
@@ -300,6 +303,8 @@ export function validateFreshness(dir, config) {
       if (daysDiff > 7) {
         results.push({
           status: 'warn',
+          code: 'FRS004',
+          doc: config.requiredFiles?.changelog || 'CHANGELOG.md',
           message: `CHANGELOG.md not updated in ${daysDiff} days despite code changes`,
         });
       } else {
@@ -336,6 +341,8 @@ export function validateFreshness(dir, config) {
         if (codeCommitsSince > 3) {
           results.push({
             status: 'warn',
+            code: 'FRS005',
+            doc: config.requiredFiles?.driftLog || 'DRIFT-LOG.md',
             message: `DRIFT-LOG.md may be stale — ${driftCount} DRIFT comments found in recent commits`,
           });
         }