docguard-cli 0.28.0 → 0.29.0

package/cli/scanners/agent-readability.mjs

@@ -0,0 +1,202 @@
+/**
+ * Agent Readability scanner — how well do this repo's docs serve an AI agent?
+ *
+ * Human readability (Flesch, passive voice — doc-quality.mjs) asks "can a
+ * person read this prose?". This scanner asks the 2026 question: "can an AI
+ * consumer FIND, QUOTE, and TRUST this documentation?" — token budgets,
+ * section addressability, machine-parseable structure, metadata markers, and
+ * unbroken pointers. Deterministic, zero-LLM, zero npm dependencies.
+ *
+ * DISPLAY-ONLY consumer contract: assessAgentReadability feeds a score display
+ * block (like ALCOA+) and must never feed the gating CDD grade — CI thresholds
+ * read that.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+
+/** chars/4 — the standard rough token estimate; consistency matters more than precision. */
+const estTokens = (s) => Math.ceil(s.length / 4);
+
+const GRADES = [[90, 'A'], [75, 'B'], [60, 'C'], [40, 'D']];
+function toGrade(score) {
+  for (const [min, g] of GRADES) if (score >= min) return g;
+  return 'F';
+}
+
+function readIfExists(path) {
+  try { return existsSync(path) ? readFileSync(path, 'utf-8') : null; } catch { return null; }
+}
+
+function canonicalDocs(projectDir) {
+  const dir = resolve(projectDir, 'docs-canonical');
+  if (!existsSync(dir)) return [];
+  try {
+    return readdirSync(dir)
+      .filter(f => f.toLowerCase().endsWith('.md'))
+      .sort()
+      .map(f => ({ name: `docs-canonical/${f}`, content: readIfExists(resolve(dir, f)) }))
+      .filter(d => d.content !== null);
+  } catch { return []; }
+}
+
+/**
+ * Split a markdown body into sections at H2/H3 headings.
+ * Returns [{heading, body}] — body excludes the heading line itself.
+ */
+function splitSections(content) {
+  const lines = content.split('\n');
+  const sections = [];
+  let current = null;
+  let inFence = false;
+  for (const line of lines) {
+    if (/^\s*```/.test(line)) inFence = !inFence;
+    const h = !inFence && line.match(/^#{2,3}\s+(.+)$/);
+    if (h) {
+      if (current) sections.push(current);
+      current = { heading: h[1].trim(), body: '' };
+    } else if (current) {
+      current.body += line + '\n';
+    }
+  }
+  if (current) sections.push(current);
+  return sections;
+}
+
+/** Fraction of non-blank lines that are structured (table/list/fence/heading/marker). */
+function structuredFraction(content) {
+  let structured = 0, total = 0, inFence = false;
+  for (const line of content.split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    total++;
+    if (/^```/.test(t)) { inFence = !inFence; structured++; continue; }
+    if (inFence) { structured++; continue; }
+    if (/^(\||[-*+]\s|\d+\.\s|#{1,6}\s|>|<!--)/.test(t)) structured++;
+  }
+  return total === 0 ? 0 : structured / total;
+}
+
+/**
+ * Assess agent readability for a project.
+ * @returns {{ metrics: Array<{key,label,score,detail,fix}>, score: number, grade: string }}
+ */
+export function assessAgentReadability(projectDir, config = {}) {
+  const metrics = [];
+  const agentsMd = readIfExists(resolve(projectDir, 'AGENTS.md'));
+  const claudeMd = readIfExists(resolve(projectDir, 'CLAUDE.md'));
+  const agentEntry = agentsMd ?? claudeMd;
+  const docs = canonicalDocs(projectDir);
+
+  // 1. agent-entry — without an entry file, an agent starts blind.
+  metrics.push({
+    key: 'agent-entry',
+    label: 'Agent entry file',
+    score: agentEntry ? 100 : 0,
+    detail: agentsMd ? 'AGENTS.md present' : claudeMd ? 'CLAUDE.md present (no AGENTS.md)' : 'no AGENTS.md or CLAUDE.md',
+    fix: agentEntry ? null : 'Create AGENTS.md (docguard init scaffolds it) — agents need an entry point',
+  });
+
+  // 2. token-budget — an entry file beyond the skim budget gets skimmed, not read.
+  if (agentEntry) {
+    const tokens = estTokens(agentEntry);
+    let score, fix = null;
+    if (tokens <= 2000) score = 100;
+    else if (tokens <= 4000) score = 75;
+    else if (tokens <= 8000) { score = 40; fix = 'Trim the agent entry file below ~4k tokens — link out to detail docs instead of inlining'; }
+    else { score = 10; fix = 'Agent entry file blows the context skim budget — split into linked canonical docs'; }
+    metrics.push({
+      key: 'token-budget',
+      label: 'Entry-file token budget',
+      score,
+      detail: `~${tokens} est. tokens (ideal ≤2000, acceptable ≤4000)`,
+      fix,
+    });
+  }
+
+  // 3. addressability — can a section be quoted alone, and do anchors resolve uniquely?
+  if (docs.length > 0) {
+    let quotable = 0, totalSections = 0, dupDocs = [];
+    for (const d of docs) {
+      const sections = splitSections(d.content);
+      totalSections += sections.length;
+      quotable += sections.filter(s => estTokens(s.body) <= 120).length;
+      const seen = new Set();
+      for (const s of sections) {
+        const slug = s.heading.toLowerCase();
+        if (seen.has(slug)) { dupDocs.push(`${d.name} ("${s.heading}")`); break; }
+        seen.add(slug);
+      }
+    }
+    const frac = totalSections === 0 ? 0 : quotable / totalSections;
+    let score = Math.round(frac * 100);
+    if (dupDocs.length > 0) score = Math.max(0, score - 30);
+    metrics.push({
+      key: 'addressability',
+      label: 'Section addressability',
+      score,
+      detail: `${quotable}/${totalSections} H2/H3 sections quotable alone (≤120 tok)${dupDocs.length ? `; duplicate headings: ${dupDocs[0]}${dupDocs.length > 1 ? ` +${dupDocs.length - 1}` : ''}` : ''}`,
+      fix: score >= 60 ? null : dupDocs.length ? 'Make headings unique within each doc — duplicates break anchor links' : 'Split long sections — an agent should be able to quote one section without dragging the whole doc',
+    });
+  }
+
+  // 4. structure-density — tables/lists/fences parse; prose walls don't.
+  if (docs.length > 0) {
+    const fracs = docs.map(d => structuredFraction(d.content));
+    const avg = fracs.reduce((a, b) => a + b, 0) / fracs.length;
+    const score = Math.min(100, Math.round((avg / 0.3) * 100));
+    metrics.push({
+      key: 'structure-density',
+      label: 'Structured-content density',
+      score,
+      detail: `${Math.round(avg * 100)}% of canonical-doc lines are structured (target ≥30%)`,
+      fix: score >= 60 ? null : 'Convert prose walls to tables/lists — structured content is machine-parseable',
+    });
+  }
+
+  // 5. marker-presence — machine-readable metadata density.
+  if (docs.length > 0) {
+    const marked = docs.filter(d => /docguard:(last-reviewed|section|generated)/.test(d.content)).length;
+    metrics.push({
+      key: 'marker-presence',
+      label: 'Machine markers',
+      score: Math.round((marked / docs.length) * 100),
+      detail: `${marked}/${docs.length} canonical docs carry docguard markers (last-reviewed / section / generated)`,
+      fix: marked === docs.length ? null : 'Add <!-- docguard:last-reviewed YYYY-MM-DD --> to unmarked docs — agents use it to judge trust',
+    });
+  }
+
+  // 6. llms-txt — the AI-consumer index standard.
+  const hasLlms = existsSync(resolve(projectDir, 'llms.txt'));
+  metrics.push({
+    key: 'llms-txt',
+    label: 'llms.txt index',
+    score: hasLlms ? 100 : 0,
+    detail: hasLlms ? 'llms.txt present at root' : 'no llms.txt at root',
+    fix: hasLlms ? null : 'Run docguard llms — generates the llms.txt AI index from your canonical docs',
+  });
+
+  // 7. self-containedness — broken relative pointers strand an agent mid-task.
+  // The entry file lives at the project root, so links resolve against it.
+  if (agentEntry) {
+    const links = [...agentEntry.matchAll(/\]\(([^)#]+\.md)(?:#[^)]*)?\)/g)]
+      .map(m => m[1])
+      .filter(l => !/^[a-z]+:\/\//i.test(l));
+    if (links.length > 0) {
+      const broken = links.filter(l => !existsSync(resolve(projectDir, l)));
+      metrics.push({
+        key: 'self-containedness',
+        label: 'Entry-file link integrity',
+        score: Math.round(((links.length - broken.length) / links.length) * 100),
+        detail: broken.length === 0
+          ? `${links.length}/${links.length} relative doc links resolve`
+          : `${broken.length}/${links.length} relative links broken (first: ${broken[0]})`,
+        fix: broken.length === 0 ? null : 'Fix the broken links — a dead pointer strands an agent mid-task',
+      });
+    }
+  }
+
+  const score = metrics.length === 0 ? 0
+    : Math.round(metrics.reduce((sum, m) => sum + m.score, 0) / metrics.length);
+  return { metrics, score, grade: toGrade(score) };
+}

package/cli/scanners/semantic-claims.mjs

@@ -28,7 +28,13 @@ import { resolve, join } from 'node:path';
 const NUMBER_PATTERNS = [
   { kind: 'duration', re: /\b(\d+(?:\.\d+)?)\s*(milliseconds?|ms|seconds?|secs?|minutes?|mins?|hours?|hrs?|days?|weeks?|months?|years?)\b/gi },
   { kind: 'rate',     re: /\b(\d+)\s*(?:\/|\bper\b|\breq(?:uests?)?\s*\/?)\s*(s|sec|seconds?|min|minutes?|hours?|h)\b/gi },
-  { kind: 'count',    re: /\b(\d+)\s*\+?\s*(GSIs?|LSIs?|indexes|indices|roles?|permissions?|scopes?|tables?|queues?|topics?|buckets?|endpoints?|routes?|validators?|columns?|fields?|shards?|partitions?|replicas?|retries|workers?|threads?|connections?)\b/gi },
+  // Field report #6: the noun list IS the precision mechanism — a number is only
+  // a claim when it sits next to a recognized "registered-unit" noun. The gap that
+  // shipped a wrong "16 extractors" past every check was simply that "extractors"
+  // (and its domain-collection siblings) weren't in this list. Added the common
+  // pluggable-architecture nouns. Deliberately NOT added: generic prose nouns that
+  // collide with running-text numbers (steps, items, checks, modules, services).
+  { kind: 'count',    re: /\b(\d+)\s*\+?\s*(GSIs?|LSIs?|indexes|indices|roles?|permissions?|scopes?|tables?|queues?|topics?|buckets?|endpoints?|routes?|validators?|columns?|fields?|shards?|partitions?|replicas?|retries|workers?|threads?|connections?|extractors?|plugins?|detectors?|scanners?|analyzers?|collectors?|commands?|subcommands?|rules?|hooks?|providers?|adapters?|handlers?|middlewares?|transformers?|processors?|generators?|parsers?|exporters?|importers?|integrations?|formatters?|linters?|agents?|skills?)\b/gi },
 ];
 
 // A list of 2+ UPPER_SNAKE tokens separated by / , | or "or" — an enum claim,

package/cli/scanners/speckit.mjs

@@ -23,7 +23,8 @@
  */
 
 import { existsSync, readFileSync, readdirSync, statSync, copyFileSync, writeFileSync } from 'node:fs';
-import { resolve, join } from 'node:path';
+import { resolve, join, relative } from 'node:path';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 // ──── Spec Kit Mandatory Sections ────
 // Based on spec-kit's spec-template.md, plan-template.md, tasks-template.md
@@ -385,95 +386,164 @@ export function generateFromSpecKit(projectDir, config, flags) {
  *   - Checks constitution → AGENTS.md mapping
  *
  * @returns {{ errors: string[], warnings: string[], passed: number, total: number }}
+ *
+ * v0.29: migrated to structured findings (SPK001–SPK007). 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.
  */
 export function validateSpecKitIntegration(projectDir, config) {
-  const results = { errors: [], warnings: [], passed: 0, total: 0 };
+  const findings = [];
+  let passed = 0;
+  let total = 0;
 
   const speckit = detectSpecKit(projectDir);
 
   // If no Spec Kit detected, suggest it
   if (!speckit.detected) {
-    results.total++;
-    results.warnings.push(
-      'No Spec Kit artifacts detected. Consider `specify init` for spec-driven development (github.com/github/spec-kit)'
-    );
-    return results;
+    total++;
+    findings.push(mkFinding({
+      code: 'SPK001',
+      validator: 'specKit',
+      severity: 'warn',
+      message: 'No Spec Kit artifacts detected. Consider `specify init` for spec-driven development (github.com/github/spec-kit)',
+      location: null,
+      suggestion: { kind: 'review', text: 'Adopt spec-driven development by initializing Spec Kit', command: 'specify init' },
+    }));
+    return resultFromFindings(findings, { passed, total });
   }
 
   // ── Check 1: .specify/ directory exists ──
-  results.total++;
+  total++;
   if (speckit.specifyDir) {
-    results.passed++;
+    passed++;
   } else {
-    results.warnings.push(
-      'Spec Kit artifacts found but .specify/ directory missing. Run `specify init` to create standard structure'
-    );
+    findings.push(mkFinding({
+      code: 'SPK002',
+      validator: 'specKit',
+      severity: 'warn',
+      message: 'Spec Kit artifacts found but .specify/ directory missing. Run `specify init` to create standard structure',
+      location: '.specify',
+      suggestion: { kind: 'fix', text: 'Create the standard Spec Kit structure', command: 'specify init' },
+    }));
   }
 
   // ── Check 2: Validate each spec's quality ──
   for (const spec of speckit.specs) {
     // 2a: spec.md quality
     if (spec.hasSpec && spec.specPath) {
-      results.total++;
+      total++;
+      const loc = relative(projectDir, spec.specPath);
       try {
         const issues = validateSpecQuality(spec.specPath);
         if (issues.length === 0) {
-          results.passed++;
+          passed++;
         } else {
           for (const issue of issues) {
-            results.warnings.push(`specs/${spec.name}/spec.md: ${issue}`);
+            findings.push(mkFinding({
+              code: 'SPK003',
+              validator: 'specKit',
+              severity: 'warn',
+              message: `specs/${spec.name}/spec.md: ${issue}`,
+              location: loc,
+              suggestion: { kind: 'fix', text: 'Bring the spec up to the spec-kit spec-template.md shape (sections, FR-/SC- IDs)' },
+            }));
           }
         }
       } catch {
-        results.warnings.push(`specs/${spec.name}/spec.md: Could not read file`);
+        findings.push(mkFinding({
+          code: 'SPK006',
+          validator: 'specKit',
+          severity: 'warn',
+          message: `specs/${spec.name}/spec.md: Could not read file`,
+          location: loc,
+          suggestion: { kind: 'review', text: 'Check the file exists and is readable (permissions/encoding)' },
+        }));
       }
     }
 
     // 2b: plan.md quality
     if (spec.hasPlan && spec.planPath) {
-      results.total++;
+      total++;
+      const loc = relative(projectDir, spec.planPath);
       try {
         const issues = validatePlanQuality(spec.planPath);
         if (issues.length === 0) {
-          results.passed++;
+          passed++;
         } else {
           for (const issue of issues) {
-            results.warnings.push(`specs/${spec.name}/plan.md: ${issue}`);
+            findings.push(mkFinding({
+              code: 'SPK004',
+              validator: 'specKit',
+              severity: 'warn',
+              message: `specs/${spec.name}/plan.md: ${issue}`,
+              location: loc,
+              suggestion: { kind: 'fix', text: 'Add the missing section per spec-kit plan-template.md' },
+            }));
           }
         }
       } catch {
-        results.warnings.push(`specs/${spec.name}/plan.md: Could not read file`);
+        findings.push(mkFinding({
+          code: 'SPK006',
+          validator: 'specKit',
+          severity: 'warn',
+          message: `specs/${spec.name}/plan.md: Could not read file`,
+          location: loc,
+          suggestion: { kind: 'review', text: 'Check the file exists and is readable (permissions/encoding)' },
+        }));
       }
     }
 
     // 2c: tasks.md quality
     if (spec.hasTasks && spec.tasksPath) {
-      results.total++;
+      total++;
+      const loc = relative(projectDir, spec.tasksPath);
       try {
         const issues = validateTasksQuality(spec.tasksPath);
         if (issues.length === 0) {
-          results.passed++;
+          passed++;
         } else {
           for (const issue of issues) {
-            results.warnings.push(`specs/${spec.name}/tasks.md: ${issue}`);
+            findings.push(mkFinding({
+              code: 'SPK005',
+              validator: 'specKit',
+              severity: 'warn',
+              message: `specs/${spec.name}/tasks.md: ${issue}`,
+              location: loc,
+              suggestion: { kind: 'fix', text: 'Add a phased breakdown with T-IDs per spec-kit tasks-template.md' },
+            }));
           }
         }
       } catch {
-        results.warnings.push(`specs/${spec.name}/tasks.md: Could not read file`);
+        findings.push(mkFinding({
+          code: 'SPK006',
+          validator: 'specKit',
+          severity: 'warn',
+          message: `specs/${spec.name}/tasks.md: Could not read file`,
+          location: loc,
+          suggestion: { kind: 'review', text: 'Check the file exists and is readable (permissions/encoding)' },
+        }));
       }
     }
   }
 
   // ── Check 3: Constitution → AGENTS.md mapping ──
   if (speckit.constitution) {
-    results.total++;
+    total++;
     const agentsPath = resolve(projectDir, 'AGENTS.md');
     if (existsSync(agentsPath)) {
-      results.passed++;
+      passed++;
     } else {
-      results.warnings.push('constitution.md exists but no AGENTS.md found. Create one for AI agent rules');
+      findings.push(mkFinding({
+        code: 'SPK007',
+        validator: 'specKit',
+        severity: 'warn',
+        message: 'constitution.md exists but no AGENTS.md found. Create one for AI agent rules',
+        location: 'AGENTS.md',
+        suggestion: { kind: 'fix', text: 'Create an AGENTS.md that references the constitution', command: 'docguard init' },
+      }));
     }
   }
 
-  return results;
+  return resultFromFindings(findings, { passed, total });
 }

package/cli/shared-ignore.mjs

@@ -89,8 +89,8 @@ export function isNonProductPath(relPath, config = {}) {
  *
  * Returns [] if the file is missing or unreadable — never throws.
  */
-import { readFileSync, existsSync } from 'node:fs';
-import { resolve as resolvePath, relative as relativePath, sep } from 'node:path';
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { resolve as resolvePath, relative as relativePath, join as joinPath, sep } from 'node:path';
 
 /**
  * Project-relative path with POSIX (`/`) separators — the canonical form that
@@ -212,26 +212,62 @@ export function shouldIgnore(relPath, config, validatorKey) {
 }
 
 /**
- * Convert a glob pattern to a RegExp for POSITIVE matching.
- * Unlike globToRegex (used for ignore filtering), this anchors the match
- * to the full relative path from the project root.
+ * THE canonical anchored glob compiler (v0.29 consolidation).
  *
- * Supports: * (any chars except /), ** (any path segments), . (literal dot).
+ * The repo previously carried THREE glob→regex implementations (ignore-side
+ * `globToRegex` above, the old `globToMatchRegex` here, and a third private
+ * copy in metrics-consistency for collection counting) with subtly different
+ * feature sets — a maintenance hazard for exactly the drift class this tool
+ * detects in others. This is now the single anchored compiler; the ignore-side
+ * `globToRegex` deliberately stays separate because its UNanchored,
+ * boundary-substring semantics ("dir" matches at any depth) are a different
+ * contract, documented above, with its own bug history.
+ *
+ * Supports (superset of all prior anchored variants):
+ *   `**\/`  → zero or more path segments   → (?:.*\/)?
+ *   `**`    → any chars (incl. /)          → .*
+ *   `*`     → any chars except /           → [^/]*
+ *   `?`     → one char except /            → [^/]
+ *   `{a,b}` → alternation (non-nested)     → (?:a|b)
+ * Everything else is regex-escaped. Fully anchored: ^...$.
  *
- * @param {string} pattern - Glob pattern (e.g., "backend/**\/__tests__/**\/*.test.ts")
+ * @param {string} pattern - Glob pattern (e.g., "backend/**\/__tests__/**\/*.test.{ts,js}")
  * @returns {RegExp}
  */
-function globToMatchRegex(pattern) {
-  // Normalize: replace **/ with a placeholder that means "zero or more path segments"
-  let escaped = pattern
-    .replace(/\./g, '\\.')
-    .replace(/\*\*\//g, '§STARSTAR§')   // **/ → zero-or-more segments
-    .replace(/\*\*/g, '.*')             // standalone ** → any chars
-    .replace(/\*/g, '[^/]*')            // single * → any chars except /
-    .replace(/§STARSTAR§/g, '(.*/)?');  // **/ → optional path prefix
-  return new RegExp(`^${escaped}$`);
+export function compileGlob(pattern) {
+  const glob = String(pattern);
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    const ch = glob[i];
+    if (ch === '*') {
+      if (glob[i + 1] === '*') {
+        i++;
+        if (glob[i + 1] === '/') { re += '(?:.*/)?'; i++; }
+        else re += '.*';
+      } else {
+        re += '[^/]*';
+      }
+    } else if (ch === '?') {
+      re += '[^/]';
+    } else if (ch === '{') {
+      const end = glob.indexOf('}', i);
+      if (end > i) {
+        re += '(?:' + glob.slice(i + 1, end).split(',')
+          .map(s => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|') + ')';
+        i = end;
+      } else {
+        re += '\\{';
+      }
+    } else {
+      re += ch.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+  }
+  return new RegExp(`^${re}$`);
 }
 
+// Back-compat internal alias — globMatch below always used the anchored form.
+const globToMatchRegex = compileGlob;
+
 /**
  * Check if a relative path matches ANY of the given glob patterns.
  * Purpose-built for POSITIVE matching (e.g., "is this a test file?").
@@ -255,3 +291,99 @@ export function globMatch(relPath, patterns) {
   const regexes = patterns.map(p => globToMatchRegex(p));
   return regexes.some(r => r.test(relPath));
 }
+
+/**
+ * THE canonical recursive file walker (v0.29 consolidation).
+ *
+ * ~13 validators each carried a private recursive walker with its own copied
+ * IGNORE_DIRS set and its own error handling — thirteen chances for skip logic
+ * to disagree. This is the single shared implementation.
+ *
+ * Contract:
+ *   - Skips directory names in `ignoreDirs` (default: DEFAULT_IGNORE_DIRS) and,
+ *     by default, every dot-prefixed entry (files AND dirs — matches the
+ *     dominant prior behavior).
+ *   - Calls `callback(absPath)` for every regular file reached.
+ *   - NEVER throws. Unreadable entries invoke `onError(err, path)` if given.
+ *   - Returns `true` iff the walk was COMPLETE (no unreadable entries). Callers
+ *     computing counts MUST check this: a partial walk that silently under-
+ *     counts is how a "code has N" assertion becomes confidently wrong — the
+ *     tool's own worst failure mode.
+ *
+ * @param {string} dir - Absolute directory to walk
+ * @param {(absPath: string) => void} callback
+ * @param {{ignoreDirs?: Set<string>, skipDotEntries?: boolean, keepDot?: (entry: string) => boolean, onError?: (err: Error, path: string) => void}} [opts]
+ *   `keepDot` — exception predicate for dot entries that MUST be walked even
+ *   with skipDotEntries on. Load-bearing for e.g. the security validator
+ *   (must scan `.env`) and traceability (`.env*`, `.gitignore`, `.github/`).
+ * @returns {boolean} - true if every entry was readable
+ */
+export function walkFiles(dir, callback, opts = {}) {
+  const {
+    ignoreDirs = DEFAULT_IGNORE_DIRS,
+    skipDotEntries = true,
+    keepDot = null,
+    onError = null,
+  } = opts;
+  let entries;
+  try { entries = readdirSync(dir); } catch (err) {
+    if (onError) onError(err, dir);
+    return false;
+  }
+  let complete = true;
+  for (const entry of entries) {
+    if (ignoreDirs.has(entry)) continue;
+    if (skipDotEntries && entry.startsWith('.') && !(keepDot && keepDot(entry))) continue;
+    const full = joinPath(dir, entry);
+    let stat;
+    try { stat = statSync(full); } catch (err) {
+      if (onError) onError(err, full);
+      complete = false;
+      continue;
+    }
+    if (stat.isDirectory()) {
+      if (!walkFiles(full, callback, opts)) complete = false;
+    } else if (stat.isFile()) {
+      callback(full);
+    }
+  }
+  return complete;
+}
+
+/**
+ * Count files under `projectDir` matching an anchored glob (project-relative).
+ * The code-truth side of `config.collections` (metrics-consistency).
+ *
+ * Walks only from the glob's literal prefix — never the whole repo for a deep
+ * pattern. FAIL-SAFE BY CONTRACT:
+ *   - returns 0 when the base path doesn't exist (unresolved glob — caller skips);
+ *   - returns -1 when the walk was INCOMPLETE (permission-denied subtree, bad
+ *     pattern). Previously a partial walk silently under-counted, so a doc
+ *     saying "19 extractors" could be "corrected" to a wrong lower number.
+ * Callers must treat any value <= 0 as "don't assert".
+ *
+ * @param {string} projectDir
+ * @param {string} pattern - e.g. "src/extractors/*.py"
+ * @returns {number} match count, 0 = unresolved, -1 = unreliable
+ */
+export function countGlobFiles(projectDir, pattern) {
+  const norm = String(pattern).replace(/\\/g, '/').replace(/^\.\//, '');
+  if (!norm) return -1;
+  const baseSegs = [];
+  for (const seg of norm.split('/')) {
+    if (/[*?{]/.test(seg)) break;
+    baseSegs.push(seg);
+  }
+  const baseDir = resolvePath(projectDir, baseSegs.join('/') || '.');
+  if (!existsSync(baseDir)) return 0;
+  let re;
+  try { re = compileGlob(norm); } catch { return -1; }
+  try {
+    if (statSync(baseDir).isFile()) return re.test(norm) ? 1 : 0; // literal file pattern
+  } catch { return -1; }
+  let n = 0;
+  const complete = walkFiles(baseDir, (full) => {
+    if (re.test(relPosix(projectDir, full))) n++;
+  });
+  return complete ? n : -1;
+}

package/cli/shared.mjs

@@ -253,9 +253,53 @@ export const PROFILES = {
 };
 
 // ── .docguardignore Support ───────────────────────────────────────────────
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { resolve, relative } from 'node:path';
 
+/**
+ * Conventional documentation-home directory names. A folder named one of these
+ * is unambiguously "docs DocGuard governs" — distinct from arbitrary markdown
+ * buried in a non-doc subdir (security/wolf-archive/, vendored toolkits), which
+ * the wu-whatsappinbox scoping fix deliberately excludes. We auto-track the
+ * former and never blanket-walk the latter.
+ */
+export const DEFAULT_DOC_DIRS = [
+  'docs', 'doc', 'documentation', 'docs-canonical', 'docs-implementation',
+  'guides', 'guide', 'handbook', 'manual', 'wiki', 'extensions',
+];
+
+/**
+ * Resolve the documentation-home directories for a project (relative dir paths,
+ * no trailing slash). Single source of truth so the claim scanner and the
+ * coverage map agree — "tracked" must mean "actually scanned," never a label
+ * the scanner ignores.
+ *
+ * Auto-detects the conventional doc-home names that actually exist at the root,
+ * plus the Docusaurus-style `website/docs`. `config.docs.dirs` EXTENDS that set
+ * (adds non-standard homes like a project's `wiki/`) rather than replacing it —
+ * the least-surprising model, since the whole point is to track MORE clearly-doc
+ * folders automatically. To EXCLUDE a conventional dir, use `.docguardignore`.
+ * NAMED dirs only — this never walks arbitrary subdirectories (that was the
+ * false-positive flood the scoping fix removed).
+ *
+ * @param {string} projectDir
+ * @param {object} [config]
+ * @returns {string[]} relative directory paths (e.g. ['docs', 'documentation'])
+ */
+export function resolveDocDirs(projectDir, config = {}) {
+  const isDir = (rel) => {
+    try { return statSync(resolve(projectDir, rel)).isDirectory(); } catch { return false; }
+  };
+  const out = new Set(DEFAULT_DOC_DIRS.filter(isDir));
+  if (isDir('website/docs')) out.add('website/docs');
+  const declared = config && config.docs && Array.isArray(config.docs.dirs) ? config.docs.dirs : [];
+  for (const d of declared) {
+    const norm = String(d).replace(/\\/g, '/').replace(/\/+$/, '');
+    if (norm) out.add(norm);
+  }
+  return [...out];
+}
+
 /**
  * Load ignore patterns from .docguardignore (like .gitignore).
  * Returns a function that checks if a relative path should be ignored.