docguard-cli 0.22.1 → 0.24.0

package/cli/shared-source.mjs

@@ -39,6 +39,39 @@ function safeReadJson(path) {
   try { return JSON.parse(readFileSync(path, 'utf-8')); } catch { return null; }
 }
 
+/**
+ * Files DocGuard reads WHOLE and regex/AST-scans. A bundle, minified vendor
+ * file, or generated client checked into source is slow to read, hostile to
+ * regex, expensive to AST-parse, and is never the project's authored truth.
+ * 1.5 MB sits far above any hand-written module yet below typical bundles.
+ */
+export const MAX_SCAN_BYTES = 1_500_000;
+
+/** True for build artifacts / minified / generated / declaration files. */
+export function isGeneratedPath(p) {
+  const b = String(p);
+  return /\.min\.[cm]?js$/i.test(b)
+      || /\.(bundle|chunk)\.[cm]?jsx?$/i.test(b)
+      || /[.-]generated\.[a-z0-9]+$/i.test(b)
+      || /\.d\.ts$/i.test(b);
+}
+
+/**
+ * Read a source file for scanning, or return null when it should be skipped:
+ * unreadable, a generated/minified artifact, or larger than `maxBytes`. This is
+ * the single guard that keeps every scanner from choking on a checked-in
+ * bundle. Skipping is logged by callers that care (most just see "no match").
+ */
+export function readScannable(absPath, { maxBytes = MAX_SCAN_BYTES } = {}) {
+  try {
+    if (isGeneratedPath(absPath)) return null;
+    if (statSync(absPath).size > maxBytes) return null;
+    return readFileSync(absPath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Expand a workspace glob (e.g. "packages/*") into concrete directories
  * that contain a package.json. Only the trailing single-level "/*" glob is
@@ -236,8 +269,8 @@ export function grepEnvUsage(projectDir, config = {}) {
     if (!CODE_EXTENSIONS.has(extname(filePath))) return;
     const rel = relative(projectDir, filePath);
     if (shouldIgnore(rel, config)) return;
-    let content;
-    try { content = readFileSync(filePath, 'utf-8'); } catch { return; }
+    const content = readScannable(filePath);
+    if (content === null) return; // unreadable, generated, or too large to scan
     if (!content.includes('env')) return;
     // patterns[2] is the import.meta.env one — its matches are Vite-injected
     // when the name is an intrinsic, and must not be reported as user env vars.
@@ -250,6 +283,30 @@ export function grepEnvUsage(projectDir, config = {}) {
         names.add(m[1]);
       }
     }
+
+    // v0.24: env vars are increasingly declared in a validation schema
+    // (Zod / envalid / convict) and read via a typed `config` object instead of
+    // `process.env.X` — so the direct-access patterns above miss them and every
+    // documented var looked "missing from code" (field report). Only harvest
+    // when the file actually validates process.env through such a schema.
+    const validatesEnv =
+      /(?:safeParse|parse)\s*\(\s*process\.env\b/.test(content) || // zod: schema.parse(process.env)
+      /\bcleanEnv\s*\(\s*process\.env\b/.test(content) ||          // envalid
+      /\bconvict\s*\(/.test(content);                              // convict
+    if (validatesEnv) {
+      let km;
+      // Zod / envalid: the schema KEYS are the env var names. Data schemas use
+      // camelCase keys, so requiring UPPER_SNAKE keeps this env-specific.
+      const keyRe = /^\s*['"]?([A-Z][A-Z0-9_]*[A-Z0-9])['"]?\s*:/gm;
+      while ((km = keyRe.exec(content)) !== null) {
+        if (km[1].length >= 3 && !VITE_INTRINSICS.has(km[1])) names.add(km[1]);
+      }
+      // convict: the env var name is the `env:` property value, not the key.
+      const convictRe = /\benv\s*:\s*['"]([A-Z][A-Z0-9_]*[A-Z0-9])['"]/g;
+      while ((km = convictRe.exec(content)) !== null) {
+        if (km[1].length >= 3) names.add(km[1]);
+      }
+    }
   };
 
   const walk = (dir) => {

package/cli/shared-trace-patterns.mjs

@@ -0,0 +1,118 @@
+/**
+ * Shared trace patterns — the single source of truth for doc→code traceability,
+ * used by BOTH the `docguard trace` command (cli/commands/trace.mjs) and the
+ * guard-time Traceability validator (cli/validators/traceability.mjs).
+ *
+ * Previously each file had its own copy: trace.mjs was multilingual (v0.16-P2)
+ * while the validator stayed JS/TS-only, so the README's "language-aware trace
+ * mapping" claim was false for the `guard` path. Sharing here makes the claim
+ * true and prevents the two from drifting again (field-report Issue 3).
+ *
+ * The API-REFERENCE entry additionally carries the explicit Next.js App Router
+ * pattern (app/api, pages/api) preserved from the v0.22.0 #195 fix.
+ */
+
+/**
+ * A markdown file is documentation, never the source that *implements* a
+ * canonical doc — so it must not count as a doc→code match. Without this,
+ * SECURITY.md's "Auth modules" glob (which includes `guard`) matched
+ * `commands/docguard.guard.md` and listed DocGuard's own command docs as the
+ * project's auth modules (field report). Real config-file matches (.env,
+ * Dockerfile, pyproject.toml, .gitignore) are unaffected — none are `.md`.
+ * Used by both `docguard trace` and the guard-time Traceability validator.
+ */
+export function isTraceableSource(relPath) {
+  return !relPath.endsWith('.md');
+}
+
+export const TEST_PATTERNS = [
+  // JS/TS
+  /\.test\.[jt]sx?$/, /\.spec\.[jt]sx?$/, /\.test\.(mjs|cjs)$/,
+  // Python — pytest conventions
+  /(^|\/)test_[^/]+\.py$/, /[^/]+_test\.py$/, /(^|\/)tests?\/[^/]+\.py$/,
+  // Go
+  /_test\.go$/,
+  // Java/Kotlin — JUnit/TestNG conventions
+  /(?:Test|Tests|Spec|IT)\.(?:java|kt)$/,
+  // Rust — tests live in tests/ or as #[cfg(test)] modules; pattern below covers integration tests
+  /(^|\/)tests\/[^/]+\.rs$/,
+  // Ruby/RSpec
+  /_spec\.rb$/, /_test\.rb$/,
+  // PHP/PHPUnit
+  /Test\.php$/, /(^|\/)tests?\/[^/]+\.php$/,
+];
+
+export const TRACE_MAP = {
+  'ARCHITECTURE.md': {
+    standard: 'arc42 / C4 Model',
+    sourcePatterns: [
+      // Entry points: JS (index/main/app/server.[jt]sx?), Python (__main__.py, main.py, app.py, cli.py),
+      // Go (main.go, cmd/), Rust (main.rs, lib.rs), Java (Application.java, Main.java)
+      { label: 'Entry points', glob: /(?:^|\/)(?:index|main|app|server|cli|__main__|Application|Main)\.(?:[jt]sx?|mjs|cjs|py|go|rs|java|kt|rb)$|(?:^|\/)cmd\// },
+      // Config files: JS (package.json/tsconfig/next.config/vite.config), Python (pyproject.toml/setup.py/setup.cfg),
+      // Rust (Cargo.toml), Go (go.mod), Java/Kotlin (pom.xml/build.gradle), Ruby (Gemfile), PHP (composer.json)
+      { label: 'Config files', glob: /(?:^|\/)(?:package\.json|tsconfig|next\.config|vite\.config|pyproject\.toml|setup\.(?:py|cfg)|Cargo\.toml|go\.mod|pom\.xml|build\.gradle|Gemfile|composer\.json)/ },
+      // Route handlers + module dirs
+      { label: 'Route handlers / modules', glob: /(?:^|\/)(?:routes?|api|pages|app|controllers?|handlers?|views?|services?)\// },
+    ],
+  },
+  'DATA-MODEL.md': {
+    standard: 'C4 Component / ER (Chen)',
+    sourcePatterns: [
+      // Schema/model files: JS (schema/model/entity/migration/prisma), Python (models.py/schema.py/Pydantic/SQLAlchemy),
+      // Go (models/), Rust (struct definitions in models/), Java (entities/)
+      { label: 'Schema definitions', glob: /(?:schema|model|entity|migration|prisma)/i },
+      // Type definitions: JS types.ts, Python types.py, Rust types.rs
+      { label: 'Type definitions', glob: /(?:^|\/)types?\.(?:[jt]sx?|mjs|py|rs|go|java|kt)$/ },
+      // ORM/database libs (any language)
+      { label: 'Database configs', glob: /(?:drizzle|knex|sequelize|typeorm|sqlalchemy|alembic|django|diesel|sqlx|gorm|hibernate|active.?record)/i },
+    ],
+  },
+  'TEST-SPEC.md': {
+    standard: 'ISO/IEC/IEEE 29119-3',
+    sourcePatterns: [
+      // Test files in any ecosystem (mirrors TEST_PATTERNS above)
+      { label: 'Test files', glob: /\.(?:test|spec)\.(?:mjs|cjs|[jt]sx?)$|(?:^|\/)test_[^/]+\.py$|[^/]+_test\.py$|_test\.go$|(?:Test|Spec|IT)\.(?:java|kt)$|(?:^|\/)tests?\/[^/]+\.(?:rs|py|rb|php)$|_(?:spec|test)\.rb$|Test\.php$/ },
+      // Test runner configs: JS (jest/vitest/playwright/cypress), Python (pytest.ini/tox.ini), Rust (Cargo.toml has [[test]]),
+      // Java (pom.xml/build.gradle), Go (no config file typically)
+      { label: 'Test config', glob: /(?:jest|vitest|playwright|cypress|pytest|tox|phpunit)\.config|(?:^|\/)pytest\.ini$|(?:^|\/)tox\.ini$|(?:^|\/)phpunit\.xml$/ },
+      { label: 'E2E / integration tests', glob: /(?:^|\/)(?:e2e|integration|tests?\/integration)\// },
+    ],
+  },
+  'SECURITY.md': {
+    standard: 'OWASP ASVS v4.0',
+    sourcePatterns: [
+      // Auth modules — semantic, language-agnostic
+      { label: 'Auth modules', glob: /(?:auth|login|session|jwt|oauth|middleware|guard|csrf|cors|permissions?|policy)/i },
+      // Secret configs — .env family + secrets.* / keyring patterns
+      { label: 'Secret configs', glob: /\.env(?:\.|$)|(?:^|\/)secrets?\.(?:py|js|ts|yaml|yml|json)$|keyring/i },
+      // Gitignore + ignore files
+      { label: 'Ignore files', glob: /^\.(?:git|docker|npm)ignore$/ },
+    ],
+  },
+  'ENVIRONMENT.md': {
+    standard: '12-Factor App',
+    sourcePatterns: [
+      // .env family across all ecosystems
+      { label: 'Env files', glob: /\.env(?:\.|$)|(?:^|\/)\.envrc$/ },
+      // Containerization
+      { label: 'Container configs', glob: /(?:^|\/)(?:Dockerfile|docker-compose|\.dockerignore|Containerfile)/ },
+      // Python venv / requirements / lock files
+      { label: 'Python env', glob: /(?:^|\/)(?:requirements[^/]*\.txt|Pipfile|poetry\.lock|uv\.lock|pyproject\.toml)$/ },
+      // CI/CD configs
+      { label: 'CI/CD configs', glob: /(?:^|\/)\.(?:github|gitlab-ci|circleci|drone|gitea)/ },
+    ],
+  },
+  'API-REFERENCE.md': {
+    standard: 'OpenAPI 3.1',
+    sourcePatterns: [
+      // Route handlers + Python views/urls + Java/Spring controllers
+      { label: 'Route handlers', glob: /(?:^|\/)(?:routes?|controllers?|handlers?|views?|urls?\.py)/ },
+      { label: 'Next.js API routes', glob: /(^|\/)(app|pages)\/api\// },
+      // OpenAPI / API specs
+      { label: 'API spec', glob: /(?:openapi|swagger|asyncapi)\.(?:json|ya?ml)/ },
+      // Middleware / decorators
+      { label: 'API middleware', glob: /(?:^|\/)middleware\/|decorators?\.py$/ },
+    ],
+  },
+};

package/cli/shared.mjs

@@ -39,6 +39,65 @@ export function resolveSeverity(config, validatorKey) {
   return 'medium';
 }
 
+// ── Canonical section heading matching ─────────────────────────────────────
+/**
+ * Required canonical sections used to be matched by literal substring, so an
+ * arc42/C4 doc with "## 5.4 Layer boundaries" or "## Building Block View"
+ * scored as if the section were absent — the validator made well-structured
+ * docs look WORSE than the skeleton (field report). These synonyms + section-
+ * number tolerance let equivalent headings count. Synonyms only ever ADD
+ * matches; the literal canonical heading always still passes.
+ *
+ * Keyed by the normalized canonical heading (lowercase, alphanumerics + spaces).
+ */
+export const SECTION_SYNONYMS = {
+  'system overview':       ['system context', 'system summary', 'introduction and goals', 'context and scope', 'overview and goals'],
+  'component map':         ['components', 'component overview', 'building block view', 'building blocks', 'containers', 'module overview'],
+  'tech stack':            ['technology stack', 'technologies', 'technical stack'],
+  'entities':              ['entity definitions', 'data model', 'domain model', 'data entities'],
+  'authentication':        ['auth', 'authn', 'authentication and authorization', 'identity'],
+  'secrets management':    ['secrets', 'secret management', 'secrets handling', 'credentials', 'credential management'],
+  'test categories':       ['test types', 'categories of tests', 'test strategy', 'testing strategy', 'test approach'],
+  'coverage rules':        ['coverage', 'coverage targets', 'coverage goals', 'coverage requirements', 'coverage policy'],
+  'environment variables': ['env vars', 'environment', 'configuration', 'config variables'],
+  'setup steps':           ['setup', 'getting started', 'installation', 'setup instructions', 'local setup', 'quick start'],
+  'layer boundaries':      ['layers', 'layering', 'module boundaries', 'layer boundary', 'boundaries'],
+  'external dependencies': ['dependencies', 'external systems', 'third party dependencies', 'integrations', 'external interfaces'],
+  'revision history':      ['changelog', 'change history', 'history', 'revisions', 'document history', 'change log'],
+};
+
+/** Normalize a markdown heading: drop #, leading arc42-style numbers, punctuation. */
+function normalizeHeadingText(line) {
+  return line
+    .replace(/^#{1,6}\s*/, '')             // strip leading #s
+    .replace(/^\d+(?:\.\d+)*\.?\s+/, '')   // strip leading "5.4 " / "3. " section numbers
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ')           // non-alphanumeric → single space
+    .trim();
+}
+
+/**
+ * True if `content` has an H2–H6 heading equivalent to `canonicalHeading` —
+ * the exact text, a known synonym, or the same text behind an arc42-style
+ * section number (e.g. "## 5.4 Layer boundaries" satisfies "## Layer Boundaries").
+ *
+ * @param {string} content - markdown file contents
+ * @param {string} canonicalHeading - e.g. '## Component Map' or 'Component Map'
+ */
+export function docHasSection(content, canonicalHeading) {
+  const key = normalizeHeadingText(canonicalHeading);
+  if (!key) return false;
+  const accepted = [key, ...(SECTION_SYNONYMS[key] || [])];
+  const headings = content.match(/^#{2,6}\s+.+$/gm) || [];
+  for (const line of headings) {
+    const norm = normalizeHeadingText(line);
+    for (const phrase of accepted) {
+      if (norm.includes(phrase)) return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Parse a dotted-decimal version string into a tuple of integers for
  * comparison. Tolerates extra suffixes (e.g. `0.4-beta` → [0, 4]).
@@ -85,7 +144,7 @@ export const c = {
 // ── Compliance Profiles ───────────────────────────────────────────────────
 export const PROFILES = {
   starter: {
-    description: 'Minimal CDD — just architecture + changelog. For side projects and prototypes.',
+    description: 'Minimal CDD — architecture + changelog, no Spec Kit framework scaffold (pass --spec-kit to add it). For side projects and prototypes.',
     requiredFiles: {
       canonical: [
         'docs-canonical/ARCHITECTURE.md',

package/cli/validator-markers.mjs

@@ -0,0 +1,91 @@
+/**
+ * Inline whole-validator N/A markers — "declare intentional non-applicability,
+ * visibly."
+ *
+ * A project can mute an entire validator from inside its docs, with the
+ * rationale right next to the declaration and tracked in git:
+ *
+ *   <!-- docguard:validator testSpec n/a — POC, no automated tests yet -->
+ *   <!-- docguard:validator traceability n/a — no formal requirements doc -->
+ *
+ * This is the validator-level sibling of the section-level
+ * `<!-- docguard:section <id> n/a — reason -->`. Unlike the config switch
+ * (`validators: { testSpec: false }`), which renders as a silent "disabled",
+ * a marked validator renders as a visible `➖ [N/A] (declared N/A: reason)` —
+ * honest non-applicability, not an invisible skip or a fake green check.
+ *
+ * Markers are read from the project's primary docs (canonical docs + the root
+ * agent/readme files) so the rationale lives where humans and agents read.
+ *
+ * Zero NPM dependencies — pure Node.js built-ins.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+
+// `<!-- docguard:validator <key> n/a [— reason] -->`
+// Separator before the reason may be —, :, or one-or-more hyphens. Reason
+// is optional. Case-insensitive on the keyword and "n/a".
+const MARKER_RE = /<!--\s*docguard:validator\s+([A-Za-z0-9_-]+)\s+n\/a\b\s*(?:[—:\-]+\s*([^>]*?))?\s*-->/gi;
+
+/** Files where a validator marker is honored — the docs humans actually read. */
+function markerSourceFiles(projectDir) {
+  const files = [];
+  const canonicalDir = resolve(projectDir, 'docs-canonical');
+  if (existsSync(canonicalDir)) {
+    try {
+      for (const f of readdirSync(canonicalDir)) {
+        if (f.toLowerCase().endsWith('.md')) files.push(join(canonicalDir, f));
+      }
+    } catch { /* ignore */ }
+  }
+  for (const root of ['AGENTS.md', 'README.md', 'CLAUDE.md']) {
+    const p = resolve(projectDir, root);
+    if (existsSync(p)) files.push(p);
+  }
+  return files;
+}
+
+/** Normalize a key for tolerant matching: `Test-Spec`/`test_spec` → `testspec`. */
+function norm(key) {
+  return String(key).toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+/**
+ * Scan the project's primary docs for `docguard:validator <key> n/a` markers.
+ *
+ * @param {string} projectDir
+ * @param {Iterable<string>} validKeys - the canonical validator keys (camelCase)
+ * @returns {{ suppressed: Map<string,string>, unknown: Array<{raw:string, file:string}> }}
+ *   `suppressed` maps a canonical validator key → reason ('' if none given).
+ *   `unknown` lists markers whose key didn't resolve (typo protection).
+ */
+export function loadValidatorSuppressions(projectDir, validKeys) {
+  const canonicalByNorm = new Map();
+  for (const k of validKeys) canonicalByNorm.set(norm(k), k);
+
+  const suppressed = new Map();
+  const unknown = [];
+
+  for (const file of markerSourceFiles(projectDir)) {
+    let content;
+    try { content = readFileSync(file, 'utf-8'); } catch { continue; }
+    if (!content.includes('docguard:validator')) continue;
+
+    MARKER_RE.lastIndex = 0;
+    let m;
+    while ((m = MARKER_RE.exec(content)) !== null) {
+      const rawKey = m[1];
+      const reason = (m[2] || '').trim();
+      const canonical = canonicalByNorm.get(norm(rawKey));
+      if (!canonical) {
+        unknown.push({ raw: rawKey, file });
+        continue;
+      }
+      // First marker wins; keep its reason. Re-declaring is harmless.
+      if (!suppressed.has(canonical)) suppressed.set(canonical, reason);
+    }
+  }
+
+  return { suppressed, unknown };
+}

package/cli/validators/api-surface.mjs

@@ -29,6 +29,7 @@ import { detectOpenAPI } from '../scanners/doc-tools.mjs';
 import { scanRoutesDeep } from '../scanners/routes.mjs';
 import { parseApiReferenceDoc, compareEndpoints, endpointKey } from '../scanners/api-doc.mjs';
 import { collectPackageJsons, getWorkspaceDirs } from '../shared-source.mjs';
+import { relPosix } from '../shared-ignore.mjs';
 
 const MAX_REPORTED = 15;
 const API_DOC = 'docs-canonical/API-REFERENCE.md';
@@ -86,15 +87,35 @@ export function findAllOpenApiSpecs(projectDir, config) {
     seenAbs.add(absPath);
     specs.push({
       absPath,
-      relPath: absPath.startsWith(resolve(projectDir))
-        ? absPath.slice(resolve(projectDir).length + 1)
-        : absPath,
+      relPath: relPosix(projectDir, absPath),
       endpoints: oa.endpoints.filter(e => e && e.method && e.path),
     });
   }
   return specs;
 }
 
+/**
+ * OpenAPI specs that exist and declare a `paths:` section but parsed to ZERO
+ * endpoints — i.e. DocGuard's minimal YAML/JSON parser couldn't extract them
+ * (an unsupported feature: `$ref`, anchors, folded scalars). These are silently
+ * skipped by findAllOpenApiSpecs (good — code scanning takes over), but the
+ * parse failure must be SURFACED so a broken spec doesn't masquerade as a
+ * clean "no API surface" pass. Returns relative spec paths.
+ */
+export function findUnparseableSpecs(projectDir, config) {
+  const out = [];
+  const seen = new Set();
+  for (const dir of orderedSpecDirs(projectDir, config)) {
+    const oa = detectOpenAPI(dir);
+    if (!oa.found || !oa.parseIncomplete) continue;
+    const abs = resolve(dir, oa.path);
+    if (seen.has(abs)) continue;
+    seen.add(abs);
+    out.push(relPosix(projectDir, abs));
+  }
+  return out;
+}
+
 /**
  * Detect divergence between multiple canonical OpenAPI specs.
  * @returns {null | { specs, divergent: string[], authoritative: string }}
@@ -208,6 +229,19 @@ export function validateApiSurface(projectDir, config) {
     }
   }
 
+  // ── Honest-failure: an OpenAPI spec we couldn't parse ──
+  // A spec that declares paths but yielded zero endpoints means our parser
+  // choked on it. We fall back to code scanning (below), but the parse failure
+  // is surfaced here rather than silently producing a clean "no surface" pass.
+  for (const specPath of findUnparseableSpecs(projectDir, config)) {
+    warnings.push(
+      `OpenAPI spec ${specPath} declares paths but DocGuard parsed 0 endpoints from it ` +
+      `(likely an unsupported YAML feature — $ref, anchors, or folded scalars). ` +
+      `Falling back to code scanning; the spec's own endpoint list is unavailable. ` +
+      `Validate it with a full OpenAPI linter.`
+    );
+  }
+
   const drift = computeApiSurfaceDrift(projectDir, config);
 
   // ── Multi-spec divergence (independent of the API-REFERENCE doc) ──

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 ────
 
 /**
@@ -516,6 +480,21 @@ function getCanonicalDocs(projectDir) {
  * paragraphs are scored. Documents that are mostly tables/code/reference
  * material are skipped for readability (they'd score 0/100 unfairly).
  */
+/**
+ * Parse a per-doc quality-rule override marker, e.g.
+ *   <!-- docguard:quality negation-load off — security doc, prohibitive language is precise -->
+ *   <!-- docguard:quality negation-load 0.35 — operational doc -->
+ * Returns { off: true } | { threshold: <number> } | null. A required reason
+ * after the value is encouraged (and self-documenting) but not enforced here.
+ */
+function parseQualityOverride(content, rule) {
+  const re = new RegExp('<!--\\s*docguard:quality\\s+' + rule + '\\s+(off|\\d*\\.?\\d+)\\b', 'i');
+  const m = content.match(re);
+  if (!m) return null;
+  const v = m[1].toLowerCase();
+  return v === 'off' ? { off: true } : { threshold: parseFloat(v) };
+}
+
 function analyzeDocument(doc) {
   const content = readFileSync(doc.path, 'utf-8');
   const proseText = extractProse(content);
@@ -554,6 +533,7 @@ function analyzeDocument(doc) {
       conditionalLoad: conditional.ratio,
     },
     details: { passive, ambiguous, atomicity, negation, conditional },
+    overrides: { negationLoad: parseQualityOverride(content, 'negation-load') },
   };
 }
 
@@ -571,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;
 
@@ -650,13 +626,20 @@ export function validateDocQuality(projectDir, config) {
     }
 
     // ── Check 7: Negation Load ──
+    // Per-doc override (security/operational docs legitimately use "never",
+    // "must not", "cannot") and a project-wide config threshold both honored.
     results.total++;
-    if (m.negationLoad <= THRESHOLDS.negationLoad.warn) {
+    const negOv = analysis.overrides?.negationLoad;
+    const negThreshold = negOv?.threshold
+      ?? config.docQuality?.negationLoadThreshold
+      ?? THRESHOLDS.negationLoad.warn;
+    if (negOv?.off || m.negationLoad <= negThreshold) {
       results.passed++;
     } else {
       results.warnings.push(
         `${doc.name}: High negation load (${(m.negationLoad * 100).toFixed(0)}% of sentences use negation). ` +
-        `Rephrase in positive terms: "must not fail" → "must succeed" (IEEE 830 §4.3)`
+        `Rephrase in positive terms: "must not fail" → "must succeed" (IEEE 830 §4.3). ` +
+        `If the negation is intentional, add: <!-- docguard:quality negation-load off — your reason -->`
       );
     }
 

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.