docguard-cli 0.23.0 → 0.25.0

package/cli/validators/canonical-sync.mjs

@@ -124,37 +124,40 @@ export function validateCanonicalSync(projectDir, config, guardResults) {
     actualValidatorNames = guardResults.map(r => r.name).filter(Boolean);
   }
 
-  // ── Read README ─────────────────────────────────────────────────────
-  const readmePath = resolve(projectDir, 'README.md');
-  if (!existsSync(readmePath)) {
-    result.warnings.push('canonical-sync: README.md not found — cannot check surface claims');
-    result.total = 1;
-    return result;
+  // ── Read surface docs (README.md + AGENTS.md) ──────────────────────
+  // Both carry "N commands / N validators" surface claims. Scanning only the
+  // README is why AGENTS.md's counts ("Commands (15 total)", "24 validators")
+  // drifted unchecked for releases — close that gap by checking both.
+  const surfaceFiles = ['README.md', 'AGENTS.md'];
+  let readme = '';
+  let readAny = false;
+  for (const f of surfaceFiles) {
+    const p = resolve(projectDir, f);
+    if (!existsSync(p)) continue;
+    try { readme += readFileSync(p, 'utf-8') + '\n'; readAny = true; } catch { /* skip unreadable */ }
   }
-
-  let readme;
-  try {
-    readme = readFileSync(readmePath, 'utf-8');
-  } catch {
-    result.warnings.push('canonical-sync: README.md unreadable');
+  if (!readAny) {
+    result.warnings.push('canonical-sync: no README.md or AGENTS.md found — cannot check surface claims');
     result.total = 1;
     return result;
   }
 
   // ── Check 1: "ships N commands" ─────────────────────────────────────
+  // Check ALL claims (matchAll), not just the first: with README + AGENTS.md
+  // concatenated, a correct claim in one file must not mask a stale claim in
+  // the other (the same first-match-masking trap the secret scanner had).
   result.total++;
-  const shipsCommandsRe = /ships\s+\*{0,2}(\d+)\s+commands?\*{0,2}/i;
-  const m1 = readme.match(shipsCommandsRe);
-  if (m1) {
-    const claimed = Number(m1[1]);
-    if (claimed === actualCommandCount) {
+  const cmdMatches = [...readme.matchAll(/ships\s+\*{0,2}(\d+)\s+commands?\*{0,2}/gi)];
+  if (cmdMatches.length > 0) {
+    const wrong = [...new Set(cmdMatches.map(m => Number(m[1])).filter(n => n !== actualCommandCount))];
+    if (wrong.length === 0) {
       result.passed++;
     } else {
       const detail = actualUserFacingCount !== actualCommandFileCount
         ? `${actualCommandCount} user-facing commands in --help (${actualCommandFileCount} files including deprecation aliases)`
         : `${actualCommandCount} command file(s)`;
       result.warnings.push(
-        `README.md claims "ships ${claimed} commands" but the real count is ${detail}. Update the README.`
+        `A surface doc (README.md/AGENTS.md) claims ${wrong.map(n => `"ships ${n} commands"`).join(' / ')} but the real count is ${detail}. Update it.`
       );
     }
   } else {
@@ -177,7 +180,7 @@ export function validateCanonicalSync(projectDir, config, guardResults) {
     } else {
       const uniqueWrong = [...new Set(wrongClaims)];
       result.warnings.push(
-        `README.md claims ${uniqueWrong.map(n => `"${n} validators"`).join(' / ')} but guard reports ${actualValidatorCount}. Update the README.`
+        `A surface doc (README.md/AGENTS.md) claims ${uniqueWrong.map(n => `"${n} validators"`).join(' / ')} but guard reports ${actualValidatorCount}. Update it.`
       );
     }
   } else {

package/cli/validators/doc-quality.mjs

@@ -16,14 +16,12 @@
  *   cells as "long sentences"), this version extracts ONLY actual prose
  *   paragraphs. Docs that are mostly tables/code skip readability scoring.
  *
- * Optional: If `understanding` CLI is installed, runs a full 31-metric deep scan.
- *
- * Zero NPM runtime dependencies — pure Node.js built-ins only.
+ * Zero NPM runtime dependencies, and zero process execution — pure Node.js
+ * built-ins reading files only.
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname } from 'node:path';
-import { execSync, execFileSync } from 'node:child_process';
 
 // ──── Metric Thresholds ────
 // These define "good" vs "warning" boundaries for each metric.
@@ -441,40 +439,6 @@ function getGradeLabel(grade) {
   return 'graduate+';
 }
 
-// ──── Understanding CLI Integration ────
-
-/**
- * Check if the `understanding` CLI is available on the system.
- */
-function findUnderstandingCli() {
-  try {
-    const cmd = process.platform === 'win32' ? 'where understanding' : 'which understanding';
-    const result = execSync(`${cmd} 2>/dev/null`, {
-      encoding: 'utf-8',
-      timeout: 3000,
-    }).trim();
-    return result || null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Run the `understanding` CLI on a file and parse results.
- */
-function runUnderstandingDeepScan(filePath) {
-  try {
-    const result = execFileSync('understanding', ['analyze', filePath, '--enhanced', '--json'], {
-      encoding: 'utf-8',
-      timeout: 10000,
-      stdio: ['pipe', 'pipe', 'ignore'],
-    });
-    return JSON.parse(result);
-  } catch {
-    return null;
-  }
-}
-
 // ──── Main Validator ────
 
 /**
@@ -587,10 +551,6 @@ export function validateDocQuality(projectDir, config) {
     return results;
   }
 
-  // Check for optional understanding CLI
-  const understandingCli = findUnderstandingCli();
-  const useDeepScan = config.docQuality?.deepScan !== false && understandingCli;
-
   for (const doc of docs) {
     if (!existsSync(doc.path)) continue;
 

package/cli/validators/docs-coverage.mjs

@@ -35,8 +35,20 @@ const COMMON_DOTFILES = new Set([
   '.env', '.env.local', '.env.development', '.env.production',
   '.vscode', '.idea', '.github', '.husky',
   '.babelrc', '.browserslistrc', '.stylelintrc',
+  '.dockerignore', '.python-version', '.tool-versions', '.ruby-version',
+  '.gitkeep', '.keep',
 ]);
 
+// Generated tool artifacts (caches, coverage data, lock-data) that land at the
+// repo root but are NOT configuration a human authors or documents. Treating
+// them as "undocumented config files" is a false positive (field test:
+// quick-recon-tool flagged pytest's `.coverage` SQLite data file). Matched by
+// exact name OR prefix (`.coverage.<host>.<pid>` is coverage.py's parallel form).
+const GENERATED_DOTFILE_PREFIXES = ['.coverage', '.eslintcache', '.stylelintcache', '.tsbuildinfo'];
+function isGeneratedArtifact(name) {
+  return GENERATED_DOTFILE_PREFIXES.some(p => name === p || name.startsWith(p + '.'));
+}
+
 /**
  * Validate that code artifacts are referenced in documentation.
  * @param {string} projectDir - Project root directory
@@ -125,6 +137,7 @@ function checkConfigFiles(projectDir, allDocContent, config = {}) {
 
     if (!isDotFile && !isProjectConfig) continue;
     if (COMMON_DOTFILES.has(entry)) continue;
+    if (isGeneratedArtifact(entry)) continue;
     if (entry === 'tsconfig.json' || entry === 'package-lock.json') continue;
 
     // Skip directories — this check is for configuration FILES, not dirs.

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/generated-staleness.mjs

@@ -173,6 +173,19 @@ export function validateGeneratedStaleness(projectDir, config = {}) {
       if (!onDisk) continue;
 
       result.total++;
+
+      // B5 (field report): a `pinned` attribute on the section's open marker
+      //   <!-- docguard:section id=… source=code pinned="reason" -->
+      // marks the section as intentionally hand-maintained — the scanner
+      // mislabeled this surface (e.g. a scanner/tool repo whose source contains
+      // framework-like strings; see F1). Exempt it from staleness and count it
+      // as a pass, mirroring the docguard:quality opt-out marker. This is the
+      // escape hatch from the "stale forever / sync --write reverts it" trap.
+      if (onDisk.attrs?.pinned !== undefined) {
+        result.passed++;
+        continue;
+      }
+
       const expected = String(sec.body || '').trim();
       const actual = String(onDisk.body || '').trim();
 
@@ -194,7 +207,9 @@ export function validateGeneratedStaleness(projectDir, config = {}) {
         : '';
 
       result.warnings.push(
-        `${basename(doc.path)} → section "${sec.id}" is stale${hint}. Run \`docguard sync --write\` to refresh code-truth sections.`
+        `${basename(doc.path)} → section "${sec.id}" is stale${hint}. Run \`docguard sync --write\` to refresh code-truth sections. ` +
+        `If this section is intentionally hand-maintained (the scanner mislabeled it), pin it: ` +
+        `add \`pinned="reason"\` to its \`<!-- docguard:section id=${sec.id} … -->\` marker.`
       );
       // v0.14-P3: structured fix so `docguard fix --write` can fix this
       // mechanically (no AI needed — scanner already produced the right body).

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);