docguard-cli 0.22.1 → 0.24.0

package/cli/validators/docs-diff.mjs

@@ -169,24 +169,34 @@ function diffTests(dir, config) {
   // match it against code test paths (or basenames when the entry has no slash).
   // Exact-string comparison produced the false "N documented but not found".
   const codeArr = [...codeTests];
-  const docArr = [...docTests];
 
-  const matches = (docEntry, codeRel) => {
+  // PERFORMANCE OPTIMIZATION: Pre-compile regular expressions to avoid O(N*M)
+  // instantiation bottlenecks inside the nested .filter and .some loops below.
+  const docMatchers = [...docTests].map(docEntry => {
     const entry = String(docEntry).trim();
     const hasSlash = entry.includes('/');
     const target = hasSlash ? entry : basename(entry);
-    const subject = hasSlash ? codeRel : basename(codeRel);
     // Glob -> regex: escape regex specials, then any run of '*' becomes '.*'.
     const rx = new RegExp('^' + target
       .replace(/[.+^${}()|[\]\\]/g, '\\$&')
       .replace(/\*+/g, '.*') + '$');
-    return rx.test(subject);
+
+    return {
+      original: docEntry,
+      hasSlash,
+      rx
+    };
+  });
+
+  const matches = (matcher, codeRel) => {
+    const subject = matcher.hasSlash ? codeRel : basename(codeRel);
+    return matcher.rx.test(subject);
   };
 
   return {
     title: 'Test Files',
-    onlyInDocs: docArr.filter(d => !codeArr.some(c => matches(d, c))),
-    onlyInCode: codeArr.filter(c => !docArr.some(d => matches(d, c))),
+    onlyInDocs: docMatchers.filter(m => !codeArr.some(c => matches(m, c))).map(m => m.original),
+    onlyInCode: codeArr.filter(c => !docMatchers.some(m => matches(m, c))),
   };
 }
 

package/cli/validators/docs-sync.mjs

@@ -5,6 +5,7 @@
 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';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', '.nuxt', 'dist', 'build', 'out',
@@ -103,7 +104,7 @@ export function validateDocsSync(projectDir, config) {
       const ext = extname(file);
       if (!['.ts', '.tsx', '.js', '.jsx', '.mjs', '.py', '.java', '.go'].includes(ext)) continue;
 
-      const relPath = file.replace(projectDir + '/', '');
+      const relPath = relPosix(projectDir, file);
       if (isTestFile(relPath)) continue;
       if (!isValidRouteFile(relPath)) continue;
       // N-1: skip files outside the --changed-only scope.
@@ -129,7 +130,7 @@ export function validateDocsSync(projectDir, config) {
       const ext = extname(file);
       if (!['.ts', '.tsx', '.js', '.jsx', '.mjs', '.py', '.java', '.go'].includes(ext)) continue;
 
-      const relPath = file.replace(projectDir + '/', '');
+      const relPath = relPosix(projectDir, file);
       if (isTestFile(relPath)) continue;
       // N-1: skip files outside the --changed-only scope.
       if (!inScope(relPath)) continue;
@@ -175,7 +176,7 @@ export function validateDocsSync(projectDir, config) {
         const ext = extname(file);
         if (!['.ts', '.tsx', '.js', '.jsx', '.mjs'].includes(ext)) continue;
 
-        const relPathForFilter = file.replace(projectDir + '/', '');
+        const relPathForFilter = relPosix(projectDir, file);
         if (isTestFile(relPathForFilter)) continue;
         if (!isValidRouteFile(relPathForFilter)) continue;
 

package/cli/validators/drift.mjs

@@ -4,6 +4,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname } from 'node:path';
+import { relPosix } from '../shared-ignore.mjs';
 
 const CODE_EXTENSIONS = new Set([
   '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx',
@@ -31,7 +32,7 @@ export function validateDrift(projectDir, config) {
     // string fixtures (e.g. `'// DRIFT: a-drift\n'`). Reading the test as
     // source would treat the string as a real drift comment. Skip test
     // files unless the user opts in — same pattern TODO-Tracking uses.
-    const rel = filePath.replace(projectDir + '/', '');
+    const rel = relPosix(projectDir, filePath);
     const includeTests = config?.drift?.includeTestFiles === true;
     if (!includeTests && /(^|\/)(__tests__|tests?|spec)\/|\.(test|spec)\.[^.]+$/.test(rel)) {
       return;
@@ -44,7 +45,7 @@ export function validateDrift(projectDir, config) {
       const match = line.match(/(?:\/\/|#|\/\*|\-\-)\s*DRIFT:\s*(.+)/i);
       if (match) {
         driftComments.push({
-          file: filePath.replace(projectDir + '/', ''),
+          file: relPosix(projectDir, filePath),
           line: i + 1,
           comment: match[1].trim(),
         });

package/cli/validators/freshness.mjs

@@ -42,13 +42,20 @@ const IGNORE_DIRS = new Set([
  * (e.g., the reviewer read the file, confirmed it still matches reality, and
  * stamped the header without touching content, so there is no commit to find).
  */
-function readLastReviewedDate(absPath) {
+export function readLastReviewedDate(absPath) {
   try {
     const content = readFileSync(absPath, 'utf-8');
     const m = content.match(/<!--\s*docguard:last-reviewed\s+(\d{4}-\d{2}-\d{2})\s*-->/);
     if (!m) return null;
     const d = new Date(m[1] + 'T00:00:00Z');
-    return isNaN(d.getTime()) ? null : d;
+    if (isNaN(d.getTime())) return null;
+    // Reject future-dated headers. A typo'd or copy-pasted future date (e.g.
+    // 2030-01-01) would otherwise make a genuinely stale doc look "fresh"
+    // forever — its age goes negative and "commits since" rounds to zero. A
+    // review can't legitimately have happened in the future, so we ignore the
+    // header and fall back to the real git date. (1-day grace for timezones.)
+    if (d.getTime() > Date.now() + 24 * 60 * 60 * 1000) return null;
+    return d;
   } catch {
     return null;
   }
@@ -90,11 +97,15 @@ function getLastGitDate(filePath, dir) {
 function getCodeCommitsSince(date, dir) {
   try {
     const isoDate = date.toISOString();
-    const result = execSync(
-      `git log --since="${isoDate}" --oneline --diff-filter=M -- "*.js" "*.mjs" "*.ts" "*.tsx" "*.py" "*.java" "*.go" | wc -l`,
+    // execFileSync (argv array) + count in JS — no shell `| wc -l` pipe, which
+    // isn't portable (Windows) and made the count depend on an external binary.
+    const out = execFileSync(
+      'git',
+      ['log', `--since=${isoDate}`, '--oneline', '--diff-filter=M', '--',
+        '*.js', '*.mjs', '*.ts', '*.tsx', '*.py', '*.java', '*.go'],
       { cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
     ).trim();
-    return parseInt(result) || 0;
+    return out ? out.split('\n').filter(Boolean).length : 0;
   } catch {
     return 0;
   }
@@ -132,11 +143,13 @@ function getTotalCommits(dir) {
  */
 function getRecentCodeCommits(dir, count = 5) {
   try {
-    const result = execSync(
-      `git log -${count} --format="%h %aI %s" -- "*.js" "*.mjs" "*.ts" "*.tsx" "*.py" "*.java"`,
+    const out = execFileSync(
+      'git',
+      ['log', `-${count}`, '--format=%h %aI %s', '--',
+        '*.js', '*.mjs', '*.ts', '*.tsx', '*.py', '*.java'],
       { cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
     ).trim();
-    return result ? result.split('\n') : [];
+    return out ? out.split('\n') : [];
   } catch {
     return [];
   }
@@ -208,8 +221,18 @@ export function validateFreshness(dir, config) {
       continue;
     }
 
-    // Check how many code commits happened since this doc was last updated
-    const codeCommitsSince = getCodeCommitsSince(docDate, dir);
+    // Check how many code commits happened since this doc was last updated.
+    // A `last-reviewed` HEADER is day-granular and signals "I reviewed this ON
+    // this day" — so it covers commits made that same day. Counting from
+    // midnight would flag a doc as stale on the very day it was genuinely
+    // reviewed whenever >10 code commits also landed that day (a heavy-dev day),
+    // undermining the explicit-review signal this validator otherwise honors.
+    // Advance a header date to end-of-day so only commits on LATER days count.
+    // Git fallback dates are real timestamps and are used as-is.
+    const sinceDate = reviewedDate
+      ? new Date(reviewedDate.getTime() + 24 * 60 * 60 * 1000 - 1000)
+      : docDate;
+    const codeCommitsSince = getCodeCommitsSince(sinceDate, dir);
 
     if (codeCommitsSince >= WARNING_THRESHOLD_COMMITS) {
       results.push({
@@ -263,13 +286,22 @@ export function validateFreshness(dir, config) {
   const driftPath = resolve(dir, config.requiredFiles?.driftLog || 'DRIFT-LOG.md');
   if (existsSync(driftPath)) {
     const driftDate = getLastGitDate(config.requiredFiles?.driftLog || 'DRIFT-LOG.md', dir);
-    // Check for recent DRIFT comments added to code
+    // Check for recent DRIFT comments ADDED to code. The old approach piped
+    // `git log --all -p | grep -c DRIFT:`, which counted DRIFT: on removed
+    // lines, unchanged context, and every branch (`--all`) — wildly inflating
+    // the count and depending on `grep`. Here we read the last-5-commits diff
+    // for the current branch and count only ADDED lines (`+`, not the `+++`
+    // file header) that introduce a DRIFT comment.
     try {
-      const recentDrifts = execSync(
-        `git log -5 --all -p -- "*.js" "*.mjs" "*.ts" "*.tsx" "*.py" | grep -c "DRIFT:" || true`,
+      const diff = execFileSync(
+        'git',
+        ['log', '-5', '-p', '--', '*.js', '*.mjs', '*.ts', '*.tsx', '*.py'],
         { cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
-      ).trim();
-      const driftCount = parseInt(recentDrifts) || 0;
+      );
+      const driftCount = diff
+        .split('\n')
+        .filter(l => /^\+(?!\+\+)/.test(l) && l.includes('DRIFT:'))
+        .length;
       if (driftCount > 0 && driftDate) {
         const codeCommitsSince = getCodeCommitsSince(driftDate, dir);
         if (codeCommitsSince > 3) {

package/cli/validators/metadata-sync.mjs

@@ -32,21 +32,28 @@ export function validateMetadataSync(projectDir, config) {
   // workspace manifest with no version, fall back to a source-root package.
   const pkgPath = resolve(projectDir, 'package.json');
   let currentVersion = null;
+  let currentName = null;
   if (existsSync(pkgPath)) {
-    try { currentVersion = JSON.parse(readFileSync(pkgPath, 'utf-8')).version || null; } catch { /* ignore */ }
+    try {
+      const pj = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      currentVersion = pj.version || null;
+      currentName = pj.name || null;
+    } catch { /* ignore */ }
   }
   if (!currentVersion) {
     for (const { pkg } of collectPackageJsons(projectDir, config)) {
-      if (pkg.version) { currentVersion = pkg.version; break; }
+      if (pkg.version) { currentVersion = pkg.version; currentName = currentName || pkg.name || null; break; }
     }
   }
   if (!currentVersion) return { errors: [], warnings, passed: 0, total: 0 };
 
-  // Parse into components for smart comparison
+  // Parse into components for smart comparison. `|| 0` guards two-part versions
+  // (e.g. "1.2"): without it vParts[2] is undefined → parseInt → NaN, and every
+  // `fPatch < patch` comparison silently becomes false, disabling the check.
   const vParts = currentVersion.split('.');
-  const major = parseInt(vParts[0], 10);
-  const minor = parseInt(vParts[1], 10);
-  const patch = parseInt(vParts[2], 10);
+  const major = parseInt(vParts[0], 10) || 0;
+  const minor = parseInt(vParts[1], 10) || 0;
+  const patch = parseInt(vParts[2], 10) || 0;
 
   // ── Check 1: extension.yml version sync ──
   const extFiles = findExtensionYmls(projectDir);
@@ -72,8 +79,6 @@ export function validateMetadataSync(projectDir, config) {
   // ── Check 2: Version references in markdown files ──
   const isIgnored = loadIgnorePatterns(projectDir);
   const mdFiles = findMarkdownFiles(projectDir);
-  // Version patterns to find: v0.7.2, @0.7.2, /v0.7.2/, docguard-cli@0.7.2
-  const versionRegex = /(?:v|@|\/v?)(\d+\.\d+\.\d+)/g;
 
   for (const mdFile of mdFiles) {
     const relPath = relative(projectDir, mdFile);
@@ -93,13 +98,18 @@ export function validateMetadataSync(projectDir, config) {
     // - Badge URLs
     // NOT in prose text like "In v0.2.0 we added..." or roadmap discussions
     const actionablePatterns = [
-      // URLs with version: /v0.7.2/, /tags/v0.7.2, @0.7.2
+      // URLs with version: /v0.7.2/, /tags/v0.7.2, /releases/0.7.2
       /(?:archive|tags|releases|download)\/v?(\d+\.\d+\.\d+)/g,
-      // npm install/npx commands: docguard-cli@0.7.2
-      /@(\d+\.\d+\.\d+)/g,
       // YAML-style: version: "0.7.2" or version: 0.7.2
       /version:\s*["']?(\d+\.\d+\.\d+)["']?/g,
     ];
+    // npm/npx refs to THIS package only (e.g. docguard-cli@0.7.2), anchored to
+    // the package name. A bare /@(\d+\.\d+\.\d+)/ used to over-match unrelated
+    // versions — node@18.2.0, @types/node@1.2.3, or "@1.2.3" in prose.
+    if (currentName) {
+      const escaped = currentName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      actionablePatterns.push(new RegExp(`${escaped}@v?(\\d+\\.\\d+\\.\\d+)`, 'g'));
+    }
 
     for (const pattern of actionablePatterns) {
       pattern.lastIndex = 0;

package/cli/validators/metrics-consistency.mjs

@@ -57,7 +57,7 @@ export function validateMetricsConsistency(projectDir, config, guardResults) {
 
   // ── Scan markdown files for hardcoded numbers ──
   const isIgnored = loadIgnorePatterns(projectDir);
-  const mdFiles = findMarkdownFiles(projectDir);
+  const mdFiles = findMarkdownFiles(projectDir, config);
   // Patterns must match standalone number references, not ratio-style "8/8 checks"
   const patterns = [
     { key: 'checks', regex: /(?<!\d\/)\b(\d{2,})\s+(?:automated\s+)?checks?\b/gi, label: 'checks' },
@@ -151,24 +151,52 @@ function findTestFiles(dir) {
   return tests;
 }
 
-function findMarkdownFiles(dir) {
+// DocGuard's OWN installed slash-command docs (commands/docguard.*.md, and the
+// .agent/commands/ variant). These are tool-managed, not the project's docs —
+// scanning them flags DocGuard's own (sometimes stale) shipped "N validators"
+// count as the USER's drift, which they can't meaningfully act on. (.agent/ and
+// .specify/ are already dot-skipped by walkFiles; this catches the legacy ROOT
+// commands/ install location. A user's own commands/<name>.md is NOT excluded.)
+const DOCGUARD_OWN_DOC_RE = /[\\/](?:\.agent[\\/])?commands[\\/]docguard\.[a-z-]+\.md$/i;
+
+function findMarkdownFiles(dir, config = {}) {
   const seen = new Set();
   const mdFiles = [];
-  // Check root, docs-canonical, and extensions
-  const searchDirs = [
-    dir,
-    resolve(dir, 'docs-canonical'),
-    resolve(dir, 'extensions'),
-  ];
-
-  for (const searchDir of searchDirs) {
-    if (!existsSync(searchDir)) continue;
-    walkFiles(searchDir, (f) => {
-      if (f.endsWith('.md') && !seen.has(f)) {
-        seen.add(f);
-        mdFiles.push(f);
-      }
-    });
+  const add = (f) => {
+    if (f.endsWith('.md') && !seen.has(f) && !DOCGUARD_OWN_DOC_RE.test(f)) {
+      seen.add(f);
+      mdFiles.push(f);
+    }
+  };
+
+  // Root LEVEL ONLY (non-recursive): README and other top-level docs. A
+  // "N validators / N checks" claim that refers to DocGuard lives in the README
+  // or the canonical docs — not five levels deep under security/ or backend/.
+  // The old code recursively walked the WHOLE repo from the root, so it swept in
+  // OpenWolf session archives (security/wolf-archive/**/memory.md) and vendored
+  // toolkit READMEs whose unrelated "N checks" prose was then reported as the
+  // USER's drift (field test: wu-whatsappinbox, ~39 false warnings the author
+  // could not act on). Scoping to the docs DocGuard actually governs fixes it.
+  try {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      try { if (statSync(full).isFile()) add(full); } catch { /* unreadable entry */ }
+    }
+  } catch { /* unreadable root */ }
+
+  // Configured canonical docs (wherever they live), plus the conventional
+  // doc homes (docs/, docs-canonical/, extensions/) — scanned in full
+  // (recursive). Code/tooling dirs (security/, backend/, src/, …) are NOT doc
+  // homes and are deliberately excluded.
+  const canonical = config && config.requiredFiles && Array.isArray(config.requiredFiles.canonical)
+    ? config.requiredFiles.canonical : [];
+  for (const rel of canonical) {
+    const full = resolve(dir, rel);
+    if (existsSync(full)) { try { if (statSync(full).isFile()) add(full); } catch { /* skip */ } }
+  }
+  for (const sub of ['docs', 'docs-canonical', 'extensions']) {
+    const searchDir = resolve(dir, sub);
+    if (existsSync(searchDir)) walkFiles(searchDir, add);
   }
 
   return mdFiles;

package/cli/validators/security.mjs

@@ -7,7 +7,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname } from 'node:path';
-import { shouldIgnore } from '../shared-ignore.mjs';
+import { shouldIgnore, relPosix } from '../shared-ignore.mjs';
 
 const CODE_EXTENSIONS = new Set([
   '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx',
@@ -69,7 +69,7 @@ export function validateSecurity(projectDir, config) {
     // Skip .env.example — it should have placeholder values
     if (filePath.endsWith('.env.example')) return;
 
-    const relPath = filePath.replace(projectDir + '/', '');
+    const relPath = relPosix(projectDir, filePath);
 
     // Apply config ignore patterns (securityIgnore + global ignore)
     if (shouldIgnore(relPath, config, 'securityIgnore')) return;
@@ -80,8 +80,12 @@ export function validateSecurity(projectDir, config) {
 
     for (const { pattern, label } of SECRET_PATTERNS) {
       pattern.lastIndex = 0;
-      const match = pattern.exec(content);
-      if (match) {
+      let match;
+      // Scan ALL matches for this pattern, not just the first. A real secret
+      // can sit BELOW a safe placeholder of the same kind (e.g. an
+      // `apiKey = "EXAMPLE..."` line above a hardcoded real key). Bailing on
+      // the first match — as this loop used to — silently missed the real one.
+      while ((match = pattern.exec(content)) !== null) {
         // Lazily initialize lines only when a match is found
         if (!lines) lines = content.split('\n');
 
@@ -97,10 +101,14 @@ export function validateSecurity(projectDir, config) {
           }
         }
 
-        // Skip known-safe placeholder/example values
+        // Skip known-safe placeholder/example values, but keep scanning for a
+        // real one further down the file.
         if (isSafePlaceholder(matchLine, match[0])) continue;
 
         findings.push({ file: relPath, label, match: match[0].substring(0, 30) + '...' });
+        // One finding per (file, label) is enough — the reported message is
+        // identical for repeats and we've already proven a real secret exists.
+        break;
       }
     }
   });

package/cli/validators/structure.mjs

@@ -4,6 +4,7 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { docHasSection } from '../shared.mjs';
 
 export function validateStructure(projectDir, config) {
   const results = { name: 'structure', errors: [], warnings: [], passed: 0, total: 0 };
@@ -86,11 +87,11 @@ export function validateDocSections(projectDir, config) {
 
     for (const section of sections) {
       results.total++;
-      // Match an actual heading at line start (any level), not a substring that
-      // could appear in a table-of-contents link or a code block.
+      // Match a real heading (H2–H6), not a substring in a TOC link or code
+      // block. v0.24: synonym- and section-number-tolerant via docHasSection, so
+      // arc42/C4 docs ("## 5.4 Layer boundaries", "## Building Block View")
+      // count instead of being told to add a section they already have.
       const headingText = section.replace(/^#+\s*/, '');
-      const escapedHeading = headingText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-      const headingRe = new RegExp('^#{2,6}\\s+' + escapedHeading + '\\b', 'm');
       // v0.16-P7: N/A marker. A project can declare a required section as
       // "not applicable" via an HTML comment instead of writing boilerplate
       // "Absent by design" prose. Format:
@@ -108,7 +109,7 @@ export function validateDocSections(projectDir, config) {
         '<!--\\s*docguard:section\\s+' + slug.replace(/-/g, '[-_]') + '\\s+n/a\\s*[—-]+\\s*[A-Za-z0-9]',
         'i'
       );
-      if (headingRe.test(content)) {
+      if (docHasSection(content, section)) {
         results.passed++;
       } else if (naRe.test(content)) {
         // v0.16-P7: explicit N/A — counts as passed (the project has owned

package/cli/validators/surface-sync.mjs

@@ -206,11 +206,13 @@ function extractDocumentedTokens(content) {
     if (t) tokens.add(t);
   }
 
-  // Pattern B: bolded token in a table row. Matches the validators-style
-  // tables that use `| N | **Name** | description |` — backticks alone
-  // miss every entry in those tables. Restricted to lines starting with
-  // `|` so prose-level **bold** is not pulled in.
-  const boldRowRe = /^\s*\|.*?\*\*([^*\n]+)\*\*/gim;
+  // Pattern B: bolded NAME token in a table row. Matches the validators-style
+  // tables that use `| N | **Name** | description |` — backticks alone miss
+  // every entry in those tables. The bold must be the FIRST cell, or the second
+  // cell after a numeric first cell — NOT any bold further right. The old
+  // `\|.*?\*\*` grabbed the first bold ANYWHERE in the row, so a bold status
+  // column like `| guard | **High** |` polluted the surface set with "High".
+  const boldRowRe = /^\s*\|\s*(?:\d+\s*\|\s*)?\*\*([^*\n]+)\*\*/gim;
   while ((m = boldRowRe.exec(stripped)) !== null) {
     const t = normalize(m[1]);
     if (t) tokens.add(t);

package/cli/validators/test-spec.mjs

@@ -18,76 +18,97 @@ export function validateTestSpec(projectDir, config) {
   const content = readFileSync(testSpecPath, 'utf-8');
   const ptc = config.projectTypeConfig || {};
 
-  // Parse the Source-to-Test Map table (new header) or Service-to-Test Map (old header)
-  const serviceMapMatch = content.match(
-    /## (?:Service-to-Test Map|Source-to-Test Map)[\s\S]*?\n\|.*\|.*\|.*\|([\s\S]*?)(?=\n##|\n$|$)/
-  );
-
-  if (serviceMapMatch) {
-    const tableContent = serviceMapMatch[1];
-    const rows = tableContent
+  // Parse the Source-to-Test Map (new header) / Service-to-Test Map (old).
+  //
+  // Column-HEADER-aware: read the header row to locate the source column, the
+  // status column, and EVERY test-file column (Unit Test, Integration Test, …),
+  // then map each data row by index WITHOUT discarding empty cells. The old
+  // parser filtered empty cells — which shifted every column rightward whenever
+  // a cell was blank (e.g. an empty Integration Test) — and only ever checked
+  // the 2nd column, so the generated 4-column table's Integration Test was
+  // never verified (#9). Splitting on the outer pipes and trimming preserves
+  // column alignment so a blank cell stays an empty string in its own slot.
+  const mapSection = content.match(/## (?:Service-to-Test Map|Source-to-Test Map)[\s\S]*?(?=\n## |$)/);
+  if (mapSection) {
+    const splitRow = (line) => {
+      const parts = line.split('|');
+      parts.shift();   // text before the first pipe
+      parts.pop();     // text after the last pipe
+      return parts.map(s => s.trim());
+    };
+    const pipeRows = mapSection[0]
       .split('\n')
-      .filter(line => line.startsWith('|') && !line.includes('---'));
+      .filter(l => l.trim().startsWith('|') && !/^\s*\|[\s|:-]+\|\s*$/.test(l)); // drop the `---` separator
+    const headerCells = pipeRows.length ? splitRow(pipeRows[0]) : [];
+    const header = headerCells.map(h => h.toLowerCase());
+
+    // Classify columns by header name, with positional fallbacks.
+    let sourceIdx = header.findIndex(h => /\bsource\b/.test(h));
+    if (sourceIdx < 0) sourceIdx = 0;
+    let statusIdx = header.findIndex(h => /\bstatus\b/.test(h));
+    if (statusIdx < 0) statusIdx = header.length - 1;
+    let testIdxs = header
+      .map((h, i) => (/\btest\b|\be2e\b/.test(h) ? i : -1))
+      .filter(i => i >= 0 && i !== sourceIdx && i !== statusIdx);
+    if (testIdxs.length === 0) {
+      const fallback = sourceIdx === 1 ? 0 : 1; // the non-source early column
+      if (fallback !== statusIdx && fallback < header.length) testIdxs = [fallback];
+    }
 
-    for (const row of rows) {
-      const cells = row
-        .split('|')
-        .map(s => s.trim())
-        .filter(s => s.length > 0);
+    const isPlaceholder = (v) =>
+      !v || v === '—' || v.includes('N/A') ||
+      ['source file', 'test file', 'unit test', 'integration test', 'e2e test'].includes(v.toLowerCase());
 
-      if (cells.length < 3) continue;
+    // Only existence-check a cell that actually LOOKS like a file path: no
+    // internal spaces, and either a directory separator or a file extension.
+    // A `## Service-to-Test Map` section often holds several sub-tables of
+    // different shapes (Controllers, Services, an "Integration Tests" inventory
+    // like `| test-file | what it covers |`). Without this guard a prose
+    // "what it covers" cell — "Health endpoint with real dependencies" — gets
+    // checked as a missing test file (false positive; field test: wu-whatsappinbox).
+    const isPathLike = (v) => !!v && !/\s/.test(v) && (/[\\/]/.test(v) || /\.[A-Za-z0-9]{1,6}$/.test(v));
 
-      const sourceFile = cells[0];
-      const testFile = cells[1];
-      const status = cells[cells.length - 1]; // Last column is always status
+    for (const row of pipeRows.slice(1)) { // skip the header row
+      const cells = splitRow(row);
+      const sourceFile = cells[sourceIdx] || '';
+      const status = cells[statusIdx] || '';
 
-      // Skip template/example rows and italic placeholder rows
-      if (sourceFile.startsWith('<!--') || sourceFile === 'Source File' || sourceFile.startsWith('*')) continue;
+      // Skip template/example rows and italic placeholder rows.
+      if (!sourceFile || sourceFile.startsWith('<!--') || sourceFile === 'Source File' || sourceFile.startsWith('*')) continue;
 
       // Author-declared gaps (❌/⚠️) are surfaced as warnings. A ✅ glyph is the
       // author's CLAIM, not proof — it is NOT counted as a pass. The real pass
       // comes from the file-existence checks below (code truth, not the glyph).
-      if (status && status.includes('❌')) {
+      if (status.includes('❌')) {
         results.total++;
-        results.warnings.push(
-          `TEST-SPEC declares ${sourceFile} as ❌ — missing tests`
-        );
-      } else if (status && status.includes('⚠️')) {
+        results.warnings.push(`TEST-SPEC declares ${sourceFile} as ❌ — missing tests`);
+      } else if (status.includes('⚠️')) {
         results.total++;
-        results.warnings.push(
-          `TEST-SPEC declares ${sourceFile} as ⚠️ — partial coverage`
-        );
+        results.warnings.push(`TEST-SPEC declares ${sourceFile} as ⚠️ — partial coverage`);
       }
 
       // ── File existence checks ───────────────────────────────────────
-      // Verify source file still exists (catch stale map entries)
+      // Verify source file still exists (catch stale map entries).
       const cleanSource = sourceFile.replace(/`/g, '').trim();
-      if (cleanSource && cleanSource !== '—' && cleanSource !== 'Source File') {
-        const sourcePath = resolve(projectDir, cleanSource);
-        if (!existsSync(sourcePath)) {
-          results.total++;
-          results.warnings.push(
-            `Source-to-Test Map: source file \`${cleanSource}\` not found on disk — stale entry?`
-          );
-        } else {
-          results.total++;
+      if (cleanSource && cleanSource !== '—' && cleanSource !== 'Source File' && isPathLike(cleanSource)) {
+        results.total++;
+        if (existsSync(resolve(projectDir, cleanSource))) {
           results.passed++;
+        } else {
+          results.warnings.push(`Source-to-Test Map: source file \`${cleanSource}\` not found on disk — stale entry?`);
         }
       }
 
-      // Verify test file exists (catch wrong/stale test references)
-      const cleanTest = testFile ? testFile.replace(/`/g, '').trim() : '';
-      if (cleanTest && cleanTest !== '—' && cleanTest !== 'Test File' &&
-          cleanTest !== 'Unit Test' && !cleanTest.includes('N/A')) {
-        const testPath = resolve(projectDir, cleanTest);
-        if (!existsSync(testPath)) {
-          results.total++;
-          results.warnings.push(
-            `Source-to-Test Map: test file \`${cleanTest}\` not found — referenced by ${cleanSource}`
-          );
-        } else {
-          results.total++;
+      // Verify EVERY declared test file exists — Unit Test AND Integration Test
+      // (the old parser only checked one column).
+      for (const ti of testIdxs) {
+        const cleanTest = (cells[ti] || '').replace(/`/g, '').trim();
+        if (isPlaceholder(cleanTest) || !isPathLike(cleanTest)) continue;
+        results.total++;
+        if (existsSync(resolve(projectDir, cleanTest))) {
           results.passed++;
+        } else {
+          results.warnings.push(`Source-to-Test Map: test file \`${cleanTest}\` not found — referenced by ${cleanSource}`);
         }
       }
     }
@@ -175,7 +196,11 @@ export function validateTestSpec(projectDir, config) {
 
     if (hasTestDir || hasColocated || hasConfigTests) {
       // Tests exist but the spec maps none of them → not applicable, not a pass.
-      results.note = 'TEST-SPEC.md declares no service-to-test mappings. Add a "## Source-to-Test Map" table with `| Source | Test file | Status |` columns — run `docguard explain "no service-to-test mappings"` for the exact format.';
+      // v0.24: the validator reads column 1 as source, column 2 as the test
+      // file, and the last as status — so both the minimal 3-column shape and
+      // the 4-column table `docguard generate` emits are accepted. Say so, since
+      // the guidance previously contradicted the generated skeleton (field report).
+      results.note = 'TEST-SPEC.md declares no service-to-test mappings. Add a "## Source-to-Test Map" table — column 1 is the source, column 2 the test file, the last column the status. Both `| Source | Test file | Status |` and the generated `| Source File | Unit Test | Integration Test | Status |` shapes work. Run `docguard explain testSpec` for details.';
     } else {
       results.warnings.push(
         'No test directory or co-located test files found. ' +

package/cli/validators/todo-tracking.mjs

@@ -35,8 +35,10 @@ const TEST_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx']);
 
 // ──── Patterns ────
 
-const TODO_PATTERN = /\b(TODO|FIXME|HACK|XXX|TEMP(?!late|orar)|WORKAROUND)\s*[(:]/;
-const TODO_EXTRACT = /\b(TODO|FIXME|HACK|XXX|TEMP(?!late|orar)|WORKAROUND)\s*[:(]?\s*(.+)/;
+// TEMP must be the standalone word — `(?![A-Za-z])` excludes TEMPLATE, TEMPORARY,
+// TEMPO, TEMPEST, etc. (the old `(?!late|orar)` only caught the first two).
+const TODO_PATTERN = /\b(TODO|FIXME|HACK|XXX|TEMP(?![A-Za-z])|WORKAROUND)\s*[(:]/;
+const TODO_EXTRACT = /\b(TODO|FIXME|HACK|XXX|TEMP(?![A-Za-z])|WORKAROUND)\s*[:(]?\s*(.+)/;
 
 // Matches a comment-opening marker. Real TODOs live in comments — restricting
 // matches to text AFTER a comment marker prevents false positives from regex