docguard-cli 0.34.9 → 0.36.0

package/cli/validator-coverage.mjs

@@ -0,0 +1,20 @@
+/** Coverage describes what ran; a successful gate is not exhaustive assurance. */
+import { existsSync } from 'node:fs';
+import { resolveDocRole, docRolePath } from './shared-doc-roles.mjs';
+const PREREQUISITES = { testSpec: 'testSpec', environment: 'environment', apiSurface: 'apiReference', architecture: 'architecture' };
+const STATES = new Set(['checked', 'partial', 'disabled', 'not-applicable', 'missing-prerequisite', 'unsupported', 'no-matches', 'error']);
+export function describeCheckCoverage(projectDir, config, result) {
+  if (result.status === 'skipped') return { status: 'disabled', reason: 'Disabled by the effective configuration or selected command scope.' };
+  if (result.note?.startsWith('declared N/A')) return { status: 'not-applicable', reason: result.note };
+  if (STATES.has(result.applicability?.status) && typeof result.applicability.reason === 'string') return result.applicability;
+  if (result.total > 0) return { status: 'checked', reason: 'Completed the declared checks; this does not establish exhaustive language, framework, or semantic coverage.' };
+  const role = PREREQUISITES[result.key];
+  if (role && !existsSync(resolveDocRole(projectDir, config, role))) return { status: 'missing-prerequisite', reason: 'No document available for role ' + role + ': ' + docRolePath(config, role) };
+  return { status: 'no-matches', reason: result.note || 'No checkable inputs matched this detector. This does not establish that the project has no relevant behavior.' };
+}
+export function summarizeCheckCoverage(results) {
+  const counts = Object.fromEntries([...STATES].map(status => [status, 0]));
+  for (const result of results) counts[result.applicability.status]++;
+  return { counts, limitations: results.filter(r => r.applicability.status !== 'checked').map(r => ({ key: r.key, name: r.name, ...r.applicability })),
+    limitation: 'Check coverage is distinct from document inventory and factual accuracy. Unsupported or unmatched inputs remain unverified.' };
+}

package/cli/validators/api-surface.mjs

@@ -1,3 +1,4 @@
+import { docRolePath, resolveDocRole } from '../shared-doc-roles.mjs';
 /**
  * API-Surface Validator — Detects drift between the documented API surface
  * (docs-canonical/API-REFERENCE.md) and the project's actual API surface.
@@ -9,18 +10,16 @@
  *   1. OpenAPI spec (sourceRoot/workspace-aware)  → high confidence
  *   2. Monorepo-aware code route scan             → lower confidence (warn only)
  *
- * Severity policy:
- *   - documented-but-absent  → ERROR when confirmed by an OpenAPI spec
- *                              (docs lie about a real endpoint → fail the build);
- *                              downgraded to WARNING on heuristic code-scan only.
- *   - present-but-undocumented → WARNING (a real route missing from the docs).
+ * OpenAPI remains the contract authority, not proof of runtime absence.
+ * Contract omissions are errors with independent code evidence. Removal needs
+ * both a contract omission and a nonempty code scan without the endpoint;
+ * code-present and unknown-coverage omissions stay review-only.
  *
  * Also flags MULTIPLE OpenAPI specs in the repo that disagree on their endpoint
  * set (e.g. a served spec and a generated spec that have diverged).
  *
  * Returns { errors, warnings, passed, total, fixes, authoritativeSpec } — the
- * `fixes` array lists deterministic remove-endpoint actions that
- * `docguard fix --write` can apply without an LLM.
+ * `fixes` array contains only omissions corroborated by a nonempty code scan.
  */
 
 import { existsSync, readFileSync } from 'node:fs';
@@ -33,7 +32,7 @@ import { relPosix } from '../shared-ignore.mjs';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 const MAX_REPORTED = 15;
-const API_DOC = 'docs-canonical/API-REFERENCE.md';
+
 
 /** Walk up from a dir to the nearest enclosing package.json directory. */
 function nearestPackageDir(projectDir, startDir) {
@@ -180,10 +179,11 @@ export function resolveApiSurface(projectDir, config) {
  * Compute API-surface drift in a structured, reusable form.
  * Used by the validator AND by `docguard fix --write`.
  * @returns {{ applicable, confidence, source, documented, documentedButAbsent,
- *             presentButUndocumented, matched }}
+ *             contractMismatches, presentButUndocumented, matched }}
  */
 export function computeApiSurfaceDrift(projectDir, config) {
-  const apiDocPath = resolve(projectDir, API_DOC);
+  const API_DOC = docRolePath(config, 'apiReference');
+  const apiDocPath = resolveDocRole(projectDir, config, 'apiReference');
   if (!existsSync(apiDocPath)) {
     return { applicable: false, confidence: 'none', source: null,
       documented: [], documentedButAbsent: [], presentButUndocumented: [], matched: [] };
@@ -198,12 +198,34 @@ export function computeApiSurfaceDrift(projectDir, config) {
   }
 
   const cmp = compareEndpoints(documented, surface.endpoints);
+  // The legacy writer treats spec-confidence documentedButAbsent as deletable.
+  // Keep contract omissions separate from their removable subset. An omission
+  // alone cannot authorize removal; code-present and unknown results are excluded.
+  let contractMismatches = [];
+  if (surface.confidence === 'spec' && cmp.documentedButAbsent.length) {
+    const framework = detectFramework(projectDir, config);
+    const routes = scanRoutesDeep(projectDir, { framework }, {}, { config });
+    const routeKeys = new Set(routes.map(r => endpointKey(r.method, r.path)));
+    contractMismatches = cmp.documentedButAbsent.map(endpoint => ({
+      ...endpoint,
+      authority: { kind: 'openapi', source: surface.source, status: 'not-declared', confidence: 'high' },
+      codeEvidence: {
+        status: routeKeys.has(endpointKey(endpoint.method, endpoint.path))
+          ? 'present' : routes.length ? 'not-found' : 'unknown',
+        confidence: 'low',
+      },
+    }));
+  }
   return {
     applicable: true,
     confidence: surface.confidence,
     source: surface.source,
     documented,
-    documentedButAbsent: cmp.documentedButAbsent,
+    documentedButAbsent: surface.confidence === 'spec'
+      ? contractMismatches.filter(e => e.codeEvidence.status === 'not-found')
+        .map(({ method, path }) => ({ method, path }))
+      : cmp.documentedButAbsent,
+    contractMismatches,
     presentButUndocumented: cmp.presentButUndocumented,
     matched: cmp.matched,
   };
@@ -251,11 +273,10 @@ export function computeSpecVsRouteDrift(projectDir, config) {
   };
 }
 
-// v0.29: migrated to structured findings (API001–API005). Messages are
-// byte-identical to the legacy strings — resultFromFindings derives the
-// errors/warnings arrays from the same findings; `fixes` and
-// `authoritativeSpec` are preserved.
+// Findings retain the authority behind each mismatch; contract authority
+// must never be presented as proof that no implementation exists.
 export function validateApiSurface(projectDir, config) {
+  const API_DOC = docRolePath(config, 'apiReference');
   const findings = [];
   const fixes = [];
   const trim = (arr) => {
@@ -365,66 +386,69 @@ export function validateApiSurface(projectDir, config) {
     };
   }
 
-  const { documentedButAbsent, presentButUndocumented, matched, confidence, source } = drift;
-  const total = matched.length + documentedButAbsent.length + presentButUndocumented.length + specRouteTotal;
+  const { documentedButAbsent, contractMismatches = [], presentButUndocumented, matched, confidence, source } = drift;
+  const total = matched.length + (confidence === 'spec' ? contractMismatches.length : documentedButAbsent.length) + presentButUndocumented.length + specRouteTotal;
   const passed = matched.length + specRoutePassed;
 
-  // documented-but-absent → deterministic remove-endpoint fixes
-  if (documentedButAbsent.length) {
-    const { shown, extra } = trim(documentedButAbsent);
+  // Spec omissions stay actionable without masquerading as runtime absence.
+  if (contractMismatches.length) {
+    const { shown, extra } = trim(contractMismatches);
     for (const e of shown) {
-      const msg = `Documented endpoint not found in code: ${e.method} ${e.path} (${API_DOC})`;
-      if (confidence === 'spec') {
-        findings.push(mkFinding({
-          code: 'API004',
-          validator: 'apiSurface',
-          severity: 'error',
-          message: msg,
-          location: API_DOC,
-          suggestion: { kind: 'fix', text: 'Remove the dead endpoint from the doc', command: 'docguard fix --write' },
-        }));
-      } else {
-        findings.push(mkFinding({
-          code: 'API004',
-          validator: 'apiSurface',
-          severity: 'warn',
-          // The "[code-scan — verify]" suffix marks this as heuristic-only:
-          // the route scanner may simply not see the endpoint's registration.
-          confidence: 'low',
-          message: `${msg} [code-scan — verify]`,
+      const codeDescription = e.codeEvidence.status === 'present'
+        ? 'A matching route was extracted from code.'
+        : e.codeEvidence.status === 'not-found'
+          ? 'No matching route was extracted from code; scanner coverage may be incomplete.'
+          : 'Code presence is unknown: no routes were extracted.';
+      findings.push({
+        ...mkFinding({
+          code: 'API004', validator: 'apiSurface', severity: 'error',
+          confidence: 'high', // certain contract omission, NOT certain code absence
+          message: `Documented endpoint missing from OpenAPI contract (${source}): ${e.method} ${e.path} (${API_DOC}). ${codeDescription}`,
           location: API_DOC,
-          suggestion: { kind: 'review', text: 'Verify the endpoint really is gone from the code, then remove it from the doc' },
-        }));
-      }
+          suggestion: e.codeEvidence.status === 'not-found'
+            ? { kind: 'fix', text: 'Remove the endpoint omitted from the contract and not found by the code scan; verify scanner coverage before applying', command: 'docguard fix --write' }
+            : { kind: 'review', text: e.codeEvidence.status === 'present'
+            ? 'Reconcile the implementation with the intended contract; update OpenAPI if the route is intended. Preserve the documented endpoint during review.'
+            : 'Reconcile the contract and documentation with the intended API. Verify implementation coverage and whether the endpoint was removed before editing documentation.' },
+        }),
+        evidence: { authority: e.authority, code: e.codeEvidence },
+      });
     }
     if (extra > 0) {
-      const tail = `…and ${extra} more documented endpoint(s) not found in code`;
-      if (confidence === 'spec') {
-        findings.push(mkFinding({
-          code: 'API004',
-          validator: 'apiSurface',
-          severity: 'error',
-          message: tail,
-          location: API_DOC,
-          suggestion: { kind: 'fix', text: 'Remove the dead endpoints from the doc', command: 'docguard fix --write' },
-        }));
-      } else {
-        findings.push(mkFinding({
-          code: 'API004',
-          validator: 'apiSurface',
-          severity: 'warn',
-          confidence: 'low',
-          message: tail,
-          location: API_DOC,
-          suggestion: { kind: 'review', text: 'Verify each documented endpoint against the code, then prune the doc' },
-        }));
-      }
+      findings.push(mkFinding({
+        code: 'API004', validator: 'apiSurface', severity: 'error',
+        message: `…and ${extra} more documented endpoint(s) missing from OpenAPI contract (${source}); code presence requires individual review`,
+        location: API_DOC,
+        suggestion: { kind: 'review', text: 'Reconcile each contract omission with code and intended behavior before editing documentation' },
+      }));
     }
-    // Only spec-confirmed absences are safe to auto-remove.
-    if (confidence === 'spec') {
-      for (const e of documentedButAbsent) {
-        fixes.push({ type: 'remove-endpoint', method: e.method, path: e.path, doc: API_DOC });
-      }
+  }
+
+  // Only the contract-and-code corroborated subset reaches mechanical writes.
+  if (confidence === 'spec') {
+    for (const e of documentedButAbsent) {
+      fixes.push({ type: 'remove-endpoint', method: e.method, path: e.path, doc: API_DOC });
+    }
+  }
+
+  // Without a spec, a negative scan remains a low-confidence review candidate.
+  if (confidence !== 'spec' && documentedButAbsent.length) {
+    const { shown, extra } = trim(documentedButAbsent);
+    for (const e of shown) {
+      findings.push(mkFinding({
+        code: 'API004', validator: 'apiSurface', severity: 'warn', confidence: 'low',
+        message: `Documented endpoint not found in code: ${e.method} ${e.path} (${API_DOC}) [code-scan — verify]`,
+        location: API_DOC,
+        suggestion: { kind: 'review', text: 'Verify the endpoint really is gone from the code, then remove it from the doc' },
+      }));
+    }
+    if (extra > 0) {
+      findings.push(mkFinding({
+        code: 'API004', validator: 'apiSurface', severity: 'warn', confidence: 'low',
+        message: `…and ${extra} more documented endpoint(s) not found by the code scanner`,
+        location: API_DOC,
+        suggestion: { kind: 'review', text: 'Verify each documented endpoint against the code before editing documentation' },
+      }));
     }
   }
 
@@ -436,7 +460,7 @@ export function validateApiSurface(projectDir, config) {
         code: 'API005',
         validator: 'apiSurface',
         severity: 'warn',
-        message: `Undocumented endpoint in code: ${e.method} ${e.path} — add it to ${API_DOC}`,
+        message: `Undocumented endpoint in ${confidence === 'spec' ? `OpenAPI contract (${source})` : 'code'}: ${e.method} ${e.path} — add it to ${API_DOC}`,
         location: API_DOC,
         suggestion: { kind: 'fix', text: `Document the endpoint in ${API_DOC}` },
       }));
@@ -446,7 +470,7 @@ export function validateApiSurface(projectDir, config) {
         code: 'API005',
         validator: 'apiSurface',
         severity: 'warn',
-        message: `…and ${extra} more undocumented endpoint(s) in code`,
+        message: `…and ${extra} more undocumented endpoint(s) in ${confidence === 'spec' ? `OpenAPI contract (${source})` : 'code'}`,
         location: API_DOC,
         suggestion: { kind: 'fix', text: `Document the remaining endpoints in ${API_DOC}` },
       }));

package/cli/validators/architecture.mjs

@@ -17,8 +17,9 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname, relative, dirname, basename } from 'node:path';
-import { shouldIgnore, walkFiles as sharedWalkFiles } from '../shared-ignore.mjs';
+import { shouldIgnore, isNonProductPath, walkFiles as sharedWalkFiles } from '../shared-ignore.mjs';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
+import { resolveDocRole } from '../shared-doc-roles.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build',
@@ -32,10 +33,12 @@ const CODE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.mjs', '.cjs', '.jsx']);
 // byte-identical to the legacy strings — resultFromFindings derives the
 // errors/warnings arrays from the same findings array (acc), which the
 // helpers below mutate in place.
-export function validateArchitecture(projectDir, config) {
+export function validateArchitecture(projectDir, config = {}) {
   const acc = { findings: [], passed: 0, total: 0 };
+  let applicability = { status: 'checked', reason: 'JS/TS static import graph inspected; arbitrary runtime dependencies are not resolved' };
   const compose = () => ({
     name: 'architecture',
+    applicability,
     ...resultFromFindings(acc.findings, { passed: acc.passed, total: acc.total }),
   });
 
@@ -47,6 +50,14 @@ export function validateArchitecture(projectDir, config) {
 
   // ── 2. Auto-detect import graph ──
   const importGraph = buildImportGraph(projectDir, config);
+  if (importGraph.unsupportedFiles.length > 0) {
+    applicability = {
+      status: importGraph.files.length > 0 ? 'partial' : 'unsupported',
+      reason: 'Python import graph analysis is unsupported: relative imports, package paths, src-layout resolution and dynamic imports are not verified; JS/TS findings, when present, are retained',
+    };
+  } else if (importGraph.files.length === 0) {
+    applicability = { status: 'not-applicable', reason: 'No supported JS/TS source files found for import graph analysis' };
+  }
   if (importGraph.files.length === 0) return compose();
 
   // ── 3. Detect circular dependencies ──
@@ -67,8 +78,8 @@ export function validateArchitecture(projectDir, config) {
   }
 
   // ── 4. Check layer boundaries from ARCHITECTURE.md ──
-  const archPath = resolve(projectDir, 'docs-canonical/ARCHITECTURE.md');
-  if (existsSync(archPath)) {
+  const archPath = resolveDocRole(projectDir, config, 'architecture');
+  if (archPath && existsSync(archPath)) {
     const archContent = readFileSync(archPath, 'utf-8');
     const declaredLayers = parseLayerBoundaries(archContent);
 
@@ -151,9 +162,12 @@ function validateConfigLayers(projectDir, config, layers, acc) {
  * @returns {{files: string[], edges: {from,to,dynamic}[], fileMap: Map<string,string[]>}}
  */
 export function buildImportGraph(projectDir, config) {
-  const graph = { files: [], edges: [], fileMap: new Map() };
+  const graph = { files: [], edges: [], fileMap: new Map(), unsupportedFiles: [] };
 
   const allFiles = getFilesRecursive(projectDir, config, projectDir);
+  graph.unsupportedFiles = allFiles
+    .filter(f => extname(f) === '.py' && !isNonProductPath(relative(projectDir, f).replace(/\\/g, '/'), config))
+    .map(f => relative(projectDir, f));
   const codeFiles = allFiles.filter(f => CODE_EXTENSIONS.has(extname(f)));
 
   for (const file of codeFiles) {

package/cli/validators/diff-suspicion.mjs

@@ -19,9 +19,11 @@
  */
 
 import { existsSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import { resolve, basename } from 'node:path';
-import { isGitRepo, getDiffText } from '../shared-git.mjs';
+import { isGitRepo, getDiffText, fileContentAtRev } from '../shared-git.mjs';
 import { parseUnifiedDiff, removedTokens, tokenize, tokenOverlap } from '../shared-diff.mjs';
+import { parseJsTs } from '../scanners/js-ast.mjs';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
 import { listCanonicalDocs } from '../shared-ignore.mjs';
 
@@ -65,9 +67,8 @@ function indexDocs(projectDir) {
       docs.set(name, { lines: content.split('\n'), tokens: tokenize(content) });
     } catch { /* skip unreadable */ }
   };
-  // Recursive. Keyed by bare basename — matches this validator's pre-existing
-  // flat-tree DSP001 message format ("ARCHITECTURE.md describes...").
-  for (const doc of listCanonicalDocs(projectDir)) add(basename(doc.rel), doc.abs);
+  // Preserve paths: nested documents with identical basenames are distinct.
+  for (const doc of listCanonicalDocs(projectDir)) add(doc.rel, doc.abs);
   // Agent-instruction files are documentation too — they routinely name code.
   for (const agent of ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']) {
     const p = resolve(projectDir, agent);
@@ -94,6 +95,39 @@ function referenceKind(docLines, file) {
   return null;
 }
 
+// Compare full snapshots: indentation cannot be inferred from isolated hunks.
+// Isolated Python parses stdin data; project code is never imported/executed.
+// Missing interpreters or parse failures retain the token-based evidence.
+function samePythonAst(projectDir, ref, file) {
+  const before = fileContentAtRev(projectDir, ref, file.oldPath);
+  const after = fileContentAtRev(projectDir, 'HEAD', file.newPath);
+  if (before === null || after === null) return false;
+  const script = 'import ast,json,sys; a,b=json.load(sys.stdin); print(ast.dump(ast.parse(a)) == ast.dump(ast.parse(b)))';
+  for (const command of ['python3', 'python']) {
+    const result = spawnSync(command, ['-I', '-S', '-c', script], {
+      input: JSON.stringify([before, after]), encoding: 'utf-8',
+      timeout: 4000, maxBuffer: 1024 * 1024,
+    });
+    if (result.status === 0) return result.stdout.trim() === 'True';
+    if (result.error?.code !== 'ENOENT') return false;
+  }
+  return false;
+}
+
+// Ignore parser bookkeeping only; retain every semantic AST field.
+function sameJsAst(projectDir, ref, file) {
+  const before = fileContentAtRev(projectDir, ref, file.oldPath);
+  const after = fileContentAtRev(projectDir, 'HEAD', file.newPath);
+  if (before === null || after === null) return false;
+  const oldTree = parseJsTs(before, file.oldPath);
+  const newTree = parseJsTs(after, file.newPath);
+  if (!oldTree.ok || !newTree.ok || oldTree.ast.errors?.length || newTree.ast.errors?.length) return false;
+  const metadata = new Set(['start', 'end', 'loc', 'extra', 'comments',
+    'leadingComments', 'trailingComments', 'innerComments', 'tokens', 'errors']);
+  const normalize = ast => JSON.stringify(ast, (key, value) => metadata.has(key) ? undefined : value);
+  return normalize(oldTree.ast) === normalize(newTree.ast);
+}
+
 export function validateDiffSuspicion(projectDir, config = {}) {
   const cfg = config.diffSuspicion || {};
   const minOverlap = Number.isInteger(cfg.minOverlap) ? cfg.minOverlap : 2;
@@ -109,8 +143,10 @@ export function validateDiffSuspicion(projectDir, config = {}) {
   );
   // Precompute removed-token sets; drop files whose change removed nothing.
   const changed = changedFiles
-    .map(f => ({ path: f.newPath, removed: removedTokens(f) }))
-    .filter(f => f.removed.size > 0);
+    .map(f => ({ file: f, path: f.newPath, removed: removedTokens(f) }))
+    .filter(f => f.removed.size > 0)
+    .filter(f => !f.path.endsWith('.py') || !samePythonAst(projectDir, ref, f.file))
+    .filter(f => !/\.[cm]?[jt]sx?$/.test(f.path) || !sameJsAst(projectDir, ref, f.file));
 
   if (changed.length === 0) {
     return resultFromFindings([], { passed: 0, total: 0, applicable: false });
@@ -146,10 +182,10 @@ export function validateDiffSuspicion(projectDir, config = {}) {
         validator: 'diff-suspicion',
         severity: 'warn',
         confidence: 'low',
-        message: `${docName} describes ${h.path} (${h.kind} ref), which just had ${h.shared.slice(0, 5).join(', ')}${h.shared.length > 5 ? '…' : ''} removed/changed (${ref}..HEAD) — verify the doc still matches.`,
+        message: `${docName} describes ${h.path} (${h.kind} ref), and overlaps old-side diff tokens: ${h.shared.slice(0, 5).join(', ')}${h.shared.length > 5 ? '…' : ''} or removed declaration names (${ref}..HEAD) — possible drift; review whether the documentation is affected.`,
         location: { file: docName },
         suggestion: {
-          summary: `Re-read ${docName} against the current ${h.path}; the removed symbols (${h.shared.slice(0, 8).join(', ')}) may now be wrong.`,
+          summary: `Re-read ${docName} against the current ${h.path}; the old-side tokens (${h.shared.slice(0, 8).join(', ')}) do not establish a semantic contradiction.`,
         },
       }));
     }
@@ -159,7 +195,7 @@ export function validateDiffSuspicion(projectDir, config = {}) {
         validator: 'diff-suspicion',
         severity: 'warn',
         confidence: 'low',
-        message: `${docName} references ${hits.length - maxPerDoc} more changed file(s) with removed domain symbols (${ref}..HEAD) — a broad change; review ${docName} as a whole.`,
+        message: `${docName} references ${hits.length - maxPerDoc} more changed file(s) with old-side token overlap (${ref}..HEAD) — a broad change; review ${docName} as a whole.`,
         location: { file: docName },
         suggestion: { summary: `${docName} looks broadly affected by this change set — review it end-to-end rather than line by line.` },
       }));

package/cli/validators/docs-coverage.mjs

@@ -1,3 +1,4 @@
+import { docRolePath, resolveDocRole } from '../shared-doc-roles.mjs';
 /**
  * Docs-Coverage Validator — Detects code features not referenced in docs.
  *
@@ -113,7 +114,7 @@ export function validateDocsCoverage(projectDir, config) {
   findings.push(...readmeChecks.findings);
 
   // ── Check 6: IaC-aware Infrastructure documentation ──
-  const iacChecks = checkIaCDocumentation(projectDir, iac);
+  const iacChecks = checkIaCDocumentation(projectDir, iac, config);
   total += iacChecks.total;
   passed += iacChecks.passed;
   findings.push(...iacChecks.findings);
@@ -233,7 +234,7 @@ function checkSourceDirs(projectDir, allDocContent, config = {}, iac = { isIaC:
   let passed = 0;
   let total = 0;
 
-  const archPath = resolve(projectDir, 'docs-canonical/ARCHITECTURE.md');
+  const archPath = resolveDocRole(projectDir, config, 'architecture');
   if (!existsSync(archPath)) return { findings, passed, total };
 
   let archContent;
@@ -336,11 +337,11 @@ function isInsideIaCPackage(relPath, packageDirs) {
  * has no Infrastructure heading. Suppresses the generic per-directory
  * warnings that would otherwise fire for bin/, lib/, modules/, handlers/, etc.
  */
-function checkIaCDocumentation(projectDir, iac) {
+function checkIaCDocumentation(projectDir, iac, config = {}) {
   const findings = [];
   if (!iac || !iac.isIaC) return { findings, passed: 0, total: 0 };
 
-  const archPath = resolve(projectDir, 'docs-canonical/ARCHITECTURE.md');
+  const archPath = resolveDocRole(projectDir, config, 'architecture');
   if (!existsSync(archPath)) {
     // No ARCHITECTURE.md at all — structure validator will catch that.
     // Don't double-warn here.
@@ -363,7 +364,7 @@ function checkIaCDocumentation(projectDir, iac) {
       validator: 'docsCoverage',
       severity: 'warn',
       message: buildIaCWarning(tool),
-      location: 'docs-canonical/ARCHITECTURE.md',
+      location: docRolePath(config, 'architecture'),
       suggestion: { kind: 'fix', text: `Add an "Infrastructure" section to ARCHITECTURE.md covering the ${tool.label} layout` },
     }));
   }

package/cli/validators/docs-diff.mjs

@@ -18,6 +18,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname, basename, relative } from 'node:path';
 import { shouldIgnore, globMatch, walkFiles as sharedWalkFiles } from '../shared-ignore.mjs';
 import { collectPackageJsons, detectDocker, resolveSourceRoots } from '../shared-source.mjs';
+import { docRolePath, resolveDocRole } from '../shared-doc-roles.mjs';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 const IGNORE_DIRS = new Set([
@@ -38,7 +39,7 @@ const CODE_EXTENSIONS = new Set([
 const DRIFT_FINDINGS = {
   'Tech Stack': {
     code: 'DDF001',
-    location: 'docs-canonical/ARCHITECTURE.md',
+    role: 'architecture',
     suggestion: {
       kind: 'review',
       text: 'Reconcile the Tech Stack in ARCHITECTURE.md with the actual dependencies — document the new tech or remove stale entries',
@@ -46,7 +47,7 @@ const DRIFT_FINDINGS = {
   },
   'Test Files': {
     code: 'DDF002',
-    location: 'docs-canonical/TEST-SPEC.md',
+    role: 'testSpec',
     suggestion: {
       kind: 'review',
       text: 'Reconcile TEST-SPEC.md with the test files on disk — document new tests or remove stale entries',
@@ -58,7 +59,7 @@ const DRIFT_FINDINGS = {
  * Validate doc-code alignment — compares canonical docs vs source code.
  * @returns {{ errors: string[], warnings: string[], passed: number, total: number }}
  */
-export function validateDocsDiff(projectDir, config) {
+export function validateDocsDiff(projectDir, config = {}) {
   const findings = [];
   let passed = 0;
   let total = 0;
@@ -105,7 +106,7 @@ export function validateDocsDiff(projectDir, config) {
         validator: 'docsDiff',
         severity: 'warn',
         message: `${result.title} drift: ${parts.join('; ')}`,
-        location: meta.location,
+        location: docRolePath(config, meta.role),
         suggestion: meta.suggestion,
       }));
     }
@@ -116,8 +117,51 @@ export function validateDocsDiff(projectDir, config) {
 
 // ── Diff Functions (lightweight versions for validator) ──────────────────
 
+/** Evaluate mentions locally; optionality is not evidence of absence or use. */
+function mentionsCurrentTechnology(content, tech, technologies) {
+  const escape = value => value.replace(/[.*+?^\x24{}()|[\]\\]/g, character => '\\' + character);
+  const names = new RegExp('\\b(?:' + technologies.map(escape).join('|') + ')\\b', 'gi');
+  const sentences = content.replace(/<!--[^]*?-->/g, '').replace(/[\x60*]/g, '')
+    .split(/\n|[;!?]|\.(?=\s|$)/);
+  for (const sentence of sentences) {
+    let subject = null;
+    for (let clause of sentence.split(/\b(?:but|whereas|while|however)\b/i)) {
+      let mentions = [...clause.matchAll(names)];
+      // Carry an omitted subject only within the same sentence, and only for
+      // an explicit continuation predicate ("but [it] is used ...").
+      if (!mentions.length && subject && /^\s*,?\s*(?:it\s+)?(?:is|was|remains)\s+/i.test(clause)) {
+        clause = subject + ' ' + clause.trim().replace(/^,\s*/, '').replace(/^it\s+/i, '');
+        mentions = [...clause.matchAll(names)];
+      }
+      if (mentions.length) subject = mentions.at(-1)[0];
+      // A leading "No" governs every item in a subject list, including tools
+      // outside our vocabulary. Stop at the predicate; later claims stay live.
+      const negativeList = /^\s*No\s+(.+?)\s+(?:is|are|was|were)\s+used\b/i.exec(clause);
+      const negativeListEnd = negativeList &&
+        !/\b(?:is|are|was|were|uses?|used|requires?|required)\b/i.test(negativeList[1])
+        ? clause.indexOf(negativeList[1]) + negativeList[1].length : -1;
+      for (let i = 0; i < mentions.length; i++) {
+        const mention = mentions[i];
+        if (mention[0].toLowerCase() !== tech.toLowerCase()) continue;
+        if (mention.index < negativeListEnd) continue;
+        const before = clause.slice(i ? mentions[i - 1].index + mentions[i - 1][0].length : 0, mention.index);
+        const after = clause.slice(mention.index + mention[0].length, mentions[i + 1]?.index ?? clause.length)
+          .replace(/^\s*[|:(—-]\s*/, ' ').trim();
+        const negativeBefore = /\b(?:no|without|neither|nor|not(?:\s+using|\s+used)?|(?:do|does|did)\s+not\s+use|never\s+used?|no\s+longer\s+(?:use|using)|(?:migrated|moved)\s+(?:away\s+)?from)\s*$/i;
+        const historicalBefore = /\b(?:previously|formerly|historically|once)\s+(?:(?:we\s+)?(?:used?|using)\s+)?$|\bused\s+to\s+use\s*$/i;
+        const negativeAfter = /^(?:(?:is|was|are|were)\s+)?(?:not\s+(?:used|using|supported|adopted)|no\s+longer\s+(?:used|supported)|unused|removed|retired)\b/i;
+        const optionalAfter = /^(?:(?:is|was|are|were)\s+)?(?:not\s+(?:needed|required)|optional)\b/i;
+        const historicalAfter = /^(?:(?:is|was|were)\s+)?(?:previously|formerly|historically|once)\b|^(?:was|were)\s+used\b/i;
+        if (!negativeBefore.test(before) && !historicalBefore.test(before) &&
+            !negativeAfter.test(after) && !optionalAfter.test(after) && !historicalAfter.test(after)) return true;
+      }
+    }
+  }
+  return false;
+}
+
 export function diffTechStack(dir, config = {}) {
-  const archPath = resolve(dir, 'docs-canonical/ARCHITECTURE.md');
+  const archPath = resolveDocRole(dir, config, 'architecture');
   if (!existsSync(archPath)) return null;
 
   // Monorepo-aware: merge dependencies across the root package + the source-root
@@ -134,7 +178,7 @@ export function diffTechStack(dir, config = {}) {
     'TypeScript', 'Tailwind', 'Docker', 'Terraform'];
 
   for (const tech of techPatterns) {
-    if (archContent.toLowerCase().includes(tech.toLowerCase())) {
+    if (mentionsCurrentTechnology(archContent, tech, techPatterns)) {
       docTech.add(tech);
     }
   }
@@ -177,7 +221,7 @@ export function diffTechStack(dir, config = {}) {
  * Always ignores node_modules via globMatch().
  */
 function diffTests(dir, config) {
-  const testSpecPath = resolve(dir, 'docs-canonical/TEST-SPEC.md');
+  const testSpecPath = resolveDocRole(dir, config, 'testSpec');
   if (!existsSync(testSpecPath)) return null;
 
   // Strip fenced code blocks first — they contain shell commands like

package/cli/validators/environment.mjs

@@ -1,3 +1,4 @@
+import { docRolePath, resolveDocRole } from '../shared-doc-roles.mjs';
 /**
  * Environment Validator — Checks ENVIRONMENT.md docs and .env.example
  * Now respects projectTypeConfig (e.g., skip env checks for CLI tools)
@@ -19,8 +20,8 @@ export function validateEnvironment(projectDir, config) {
   let total = 0;
   const ptc = config.projectTypeConfig || {};
 
-  const envDoc = 'docs-canonical/ENVIRONMENT.md';
-  const envDocPath = resolve(projectDir, envDoc);
+  const envDoc = docRolePath(config, 'environment');
+  const envDocPath = resolveDocRole(projectDir, config, 'environment');
   if (!existsSync(envDocPath)) {
     // Structure validator catches missing files. Keep the exact legacy shape
     // here (no `findings` key) — tests deep-equal this early return.