docguard-cli 0.22.1 → 0.24.0

package/README.md

@@ -9,7 +9,7 @@
 [![PyPI](https://img.shields.io/pypi/v/docguard-cli)](https://pypi.org/project/docguard-cli/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org)
-[![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-brightgreen)](package.json)
+[![Runtime deps](https://img.shields.io/badge/runtime_deps-1_(pinned)-green)](package.json)
 [![Spec Kit Extension](https://img.shields.io/badge/Spec_Kit-Extension-blueviolet)](https://github.com/github/spec-kit)
 
 ---
@@ -106,9 +106,9 @@ Recent highlights across the v0.16 → v0.19 line:
   two commits. Pinpoints regressions without re-running the full suite by hand.
 - **`docguard upgrade --apply --pr`** — when the config schema bumps, DocGuard migrates
   `.docguard.json` for you and (optionally) opens a PR with the change.
-- **Language-aware `docguard trace`** — the standalone `trace` command understands Python, Rust, Go,
-  Java, Ruby, and PHP layouts in addition to JS/TS. (The guard-time Traceability validator is JS/TS-first
-  today; broader language parity is on the v0.23 roadmap.)
+- **Language-aware traceability** — both `docguard trace` *and* the guard-time Traceability validator
+  understand Python, Rust, Go, Java, Ruby, and PHP layouts in addition to JS/TS, via a shared pattern
+  set (`cli/shared-trace-patterns.mjs`) so the two never drift apart.
 - **Per-validator severity overrides** — escalate `freshness` to `high` for production repos,
   demote `doc-quality` to `low` for prototypes. Configurable per-project.
 - **JSON Schema for `.docguard.json`** — IDE autocomplete, in-line docs, and validation via

package/cli/commands/demo.mjs

@@ -25,7 +25,7 @@ import { spawnSync } from 'node:child_process';
 import { c } from '../shared.mjs';
 import { runGuardInternal, classifyResult } from './guard.mjs';
 import { runScoreInternal } from './score.mjs';
-import { loadConfig } from '../docguard.mjs';
+import { loadConfig } from '../config.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);

package/cli/commands/diff.mjs

@@ -174,7 +174,7 @@ export function diffEntities(dir, config = {}) {
   // an entity). scanSchemasDeep covers JS ORMs, SQLAlchemy/Pydantic, Diesel,
   // Go structs, JPA, Rails, and OpenAPI schemas.
   const docTools = detectDocTools(dir);
-  const schemas = scanSchemasDeep(dir, {}, docTools);
+  const schemas = scanSchemasDeep(dir, {}, docTools, config);
   const codeEntities = new Set();
   for (const e of (schemas.entities || [])) {
     const n = String(e.name || '').toLowerCase();
@@ -347,22 +347,33 @@ function diffTests(dir, config = {}) {
 
   // Glob-aware matching (documented entries are often patterns or basenames).
   const codeArr = [...codeTests];
-  const docArr = [...docTests];
-  const matches = (docEntry, codeRel) => {
+
+  // PERFORMANCE OPTIMIZATION: Pre-compile regular expressions to avoid O(N*M)
+  // instantiation bottlenecks inside the nested .filter and .some loops below.
+  const docMatchers = [...docTests].map(docEntry => {
     const entry = String(docEntry).trim();
     const hasSlash = entry.includes('/');
     const target = hasSlash ? entry : basename(entry);
-    const subject = hasSlash ? codeRel : basename(codeRel);
     const rx = new RegExp('^' + target.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*+/g, '.*') + '$');
-    return rx.test(subject);
+
+    return {
+      original: docEntry,
+      hasSlash,
+      rx
+    };
+  });
+
+  const matches = (matcher, codeRel) => {
+    const subject = matcher.hasSlash ? codeRel : basename(codeRel);
+    return matcher.rx.test(subject);
   };
 
   return {
     title: 'Test Files',
     icon: '🧪',
-    onlyInDocs: docArr.filter(d => !codeArr.some(c => matches(d, c))),
-    onlyInCode: codeArr.filter(c => !docArr.some(d => matches(d, c))),
-    matched: docArr.filter(d => codeArr.some(c => matches(d, c))),
+    onlyInDocs: docMatchers.filter(m => !codeArr.some(c => matches(m, c))).map(m => m.original),
+    onlyInCode: codeArr.filter(c => !docMatchers.some(m => matches(m, c))),
+    matched: docMatchers.filter(m => codeArr.some(c => matches(m, c))).map(m => m.original),
   };
 }
 

package/cli/commands/explain.mjs

@@ -76,13 +76,14 @@ const EXPLAINERS = {
   },
   testSpec: {
     title: 'Test-Spec — declared tests exist',
-    what: 'Reads TEST-SPEC.md\'s test mapping (rows linking sources to test files) and verifies each referenced test file exists.',
+    what: 'Reads TEST-SPEC.md\'s "## Source-to-Test Map" table and verifies every referenced file exists. Parsing is column-HEADER-aware: it locates the source column, the status column, and EVERY test-file column (Unit Test, Integration Test, …) by name, so both the minimal 3-column table and the 4-column table `docguard generate` emits are checked in full — a missing Integration Test is no longer skipped, and a blank cell no longer shifts the columns.',
     why:  'A spec that claims test coverage for X but the test file is missing is a stale promise.',
     triggers: [
-      ['no service-to-test mappings', 'TEST-SPEC.md has no recognized mapping table. Add a table with `| Source | Test file | Status |` columns.'],
+      ['no service-to-test mappings', 'TEST-SPEC.md has no recognized mapping table. Add a "## Source-to-Test Map" with column 1 = source, column 2 = test file, last = status. Both `| Source | Test file | Status |` and the generated `| Source File | Unit Test | Integration Test | Status |` are accepted.'],
       ['referenced test file does not exist', 'A path in TEST-SPEC.md\'s mapping doesn\'t exist. Update the path or remove the row.'],
+      ['this project has no automated tests (POC, spike, library)', 'Declare it visibly instead of fighting the validator: add `<!-- docguard:validator testSpec n/a — POC, no automated tests yet -->` to TEST-SPEC.md or AGENTS.md. Test-Spec then renders ➖ [N/A] with your reason (git-tracked), not a warning.'],
     ],
-    example: '| `src/auth.ts` | `tests/auth.test.ts` | ✅ |',
+    example: '| `src/auth.ts` | `tests/auth.test.ts` | ✅ |   (or the generated 4-column shape)',
     standard: 'ISO/IEC/IEEE 29119-3 (test specification)',
   },
   environment: {
@@ -119,14 +120,16 @@ const EXPLAINERS = {
     standard: 'CDD principle: docs and code commit together',
   },
   traceability: {
-    title: 'Traceability — every FR/SC ID has test coverage',
-    what: 'Scans specs/ for FR-### and SC-### requirement IDs. Each must appear in a test file as `@req FR-###`.',
-    why:  'Untraceable requirements drift from implementation.',
+    title: 'Traceability — requirement IDs have test coverage + docs link to code',
+    what: 'Two linkages under one validator: (1) scans specs/ for FR-###/SC-### (also REQ-###, T-###) requirement IDs, each of which must appear in a test as `@req FR-###`; (2) flags a canonical doc that exists but that no source file references back to — the "unlinked doc" warning.',
+    why:  'Untraceable requirements drift from implementation, and a doc no code points to is memory nothing reads.',
     triggers: [
       ['has no test coverage', 'Add `// @req FR-012` (or similar) as a comment in the test that verifies the requirement.'],
       ['orphaned test reference', 'A `@req` comment references an ID that doesn\'t exist in any spec. Update the ID or remove the marker.'],
+      ['unlinked doc', 'A canonical doc (e.g. TEST-SPEC.md) exists but no source file references it. Link it from code/tests, or treat it as advisory if the doc is intentionally standalone. This is a doc→source check, distinct from the FR/SC→test check above — they share the Traceability bucket.'],
+      ['this project has no formal requirements', 'Declare it visibly: add `<!-- docguard:validator traceability n/a — no formal requirements doc -->` to a canonical doc or AGENTS.md. Renders as ➖ [N/A] with the reason instead of warning on every loose ID.'],
     ],
-    example: 'spec.md defines `**FR-012**: ...` and test file has `// @req FR-012` near the test that verifies it',
+    example: 'spec.md defines `**FR-012**: ...` and a test has `// @req FR-012`; and TEST-SPEC.md is referenced from a test/source file',
     standard: 'ISO/IEC/IEEE 29148 (requirements traceability)',
   },
   apiSurface: {
@@ -215,8 +218,155 @@ const EXPLAINERS = {
     example: 'plan.md has Summary, Technical Context, Constitution Check, Project Structure',
     standard: 'GitHub Spec Kit',
   },
+
+  // ── Backfilled in v0.24 (field report, Issue A) ─────────────────────────
+  // These validators were registered in guard but had no explain entry, so
+  // `docguard explain <key>` returned "not found" — including the very
+  // negation-load escape hatch that v0.23.0 shipped (docQuality). The new
+  // tests/explain-coverage.test.mjs asserts this table covers every key the
+  // guard registry exposes, so the gap can't silently reopen.
+  docSections: {
+    // Reported by guard under the `structure` severity key, but it's a
+    // distinct check (required headings, not file existence) with its own
+    // warning + N/A marker — so it gets its own explainer.
+    title: 'Doc Sections — each canonical doc has its required headings',
+    what: 'For each canonical doc, verifies the required `##` sections exist as real headings: ARCHITECTURE.md (System Overview, Component Map, Tech Stack), DATA-MODEL.md (Entities), SECURITY.md (Authentication, Secrets Management), TEST-SPEC.md (Test Categories, Coverage Rules), ENVIRONMENT.md (Environment Variables, Setup Steps). The DATA-MODEL and ENVIRONMENT requirements relax automatically for CLI/library projects.',
+    why:  'A canonical doc that exists but lacks its sections is an empty shell — the section structure is what makes it a reliable memory anchor for humans and agents.',
+    triggers: [
+      ['missing section', 'Add the named `## Section` heading. If the section is genuinely not applicable (e.g. a CLI with no auth), add the N/A marker — a reason is required: `<!-- docguard:section authentication n/a — CLI tool, no auth layer -->`.'],
+    ],
+    example: 'SECURITY.md contains both `## Authentication` and `## Secrets Management` as real headings — or carries `<!-- docguard:section authentication n/a — CLI, no auth -->`',
+    standard: 'CDD STANDARD (canonical doc section contract)',
+  },
+  architecture: {
+    title: 'Architecture — module imports respect layer boundaries',
+    what: 'Builds an import graph across JS/TS files (ES imports, dynamic imports, CommonJS require) and flags (a) imports that cross a forbidden layer boundary declared in `config.layers` or a "Layer Boundaries" table in ARCHITECTURE.md, and (b) circular dependency cycles (length 3–6). N/A unless layers are declared in config or ARCHITECTURE.md.',
+    why:  'Layer violations and import cycles are how a clean architecture rots silently. Catching them at doc-time keeps the documented design honest.',
+    triggers: [
+      ['Circular dependency', 'Break the cycle — extract the shared piece into a module both can import, or invert one of the dependencies.'],
+      ['forbidden by ARCHITECTURE.md', 'An import crosses a boundary your ARCHITECTURE.md "Layer Boundaries" table forbids. Remove the import or update the declared boundary.'],
+      ['layer imports from forbidden layer', 'Same violation, declared via `config.layers.<layer>.canImport`. Adjust the import or widen the allowed list.'],
+    ],
+    example: 'ARCHITECTURE.md declares the routes layer may not import from routes, every import respects it, and there are no import cycles',
+    standard: 'Layered architecture / Acyclic Dependencies Principle',
+  },
+  docsDiff: {
+    title: 'Docs-Diff — declared tech stack + tests match reality',
+    what: 'Two soft-signal diffs: (1) technologies named in ARCHITECTURE.md vs. technologies implied by your dependencies (plus Dockerfile / Terraform detection); (2) test files referenced in TEST-SPEC.md vs. the `*.test.*` / `*.spec.*` files actually on disk. Warnings only — drift is a signal, not a failure. (Env-var drift is handled separately by the Environment validator.)',
+    why:  'The tech-stack section and the test list are the doc parts that rot fastest as dependencies and tests come and go.',
+    triggers: [
+      ['drift:', 'ARCHITECTURE.md or TEST-SPEC.md disagrees with the code. The warning spells out which items are "in code but not documented" vs. "documented but not found in code".'],
+      ['in code but not documented', 'Add the technology or test file to the relevant doc.'],
+      ['documented but not found in code', 'Remove the stale reference, or restore the file if it was deleted by mistake.'],
+    ],
+    example: 'ARCHITECTURE.md names exactly the stack the dependencies imply, and every glob in TEST-SPEC.md matches a real test file',
+    standard: 'CDD principle: documented surfaces match implemented surfaces',
+  },
+  metadataSync: {
+    title: 'Metadata-Sync — version strings agree with package.json',
+    what: 'Takes package.json `version` as the source of truth and flags (a) a different `version:` in extension.yml/yaml, and (b) older same-major version references in docs — but only in actionable contexts (release/download URLs, `@x.y.z` install specs, `version:` declarations). CHANGELOG.md and DRIFT-LOG.md are skipped as historical by definition.',
+    why:  'A README install line pinned to an old version, or an extension manifest left behind on release, sends users to the wrong artifact.',
+    triggers: [
+      ['but package.json is', 'A tracked version string disagrees with package.json. Update it (`docguard fix --write` handles this when marked auto-fixable).'],
+      ['in an actionable context', 'A docs install command / URL / declaration references an older same-major version. Bump it to the current version.'],
+    ],
+    example: 'package.json is 0.23.0, extension.yml says 0.23.0, and every install command / release URL points at 0.23.0',
+    standard: 'Semantic Versioning (consistency of published version references)',
+  },
+  docsCoverage: {
+    title: 'Docs-Coverage — documentable artifacts are mentioned somewhere',
+    what: 'Collects all doc text (README, AGENTS.md, CLAUDE.md, CONTRIBUTING.md, STANDARD.md, docs-canonical/, docs/, docs-implementation/, extensions/) and checks that root config files, package.json `bin` commands, source directories, and config files the code actually reads each appear in at least one doc. Also checks the README has Installation / Usage / License sections.',
+    why:  'A feature, command, or config file that no doc mentions is invisible to new contributors and to AI agents reading the project.',
+    triggers: [
+      ['exists but is not mentioned in any documentation', 'Document the config file\'s purpose in ARCHITECTURE.md or README.md.'],
+      ['but it\'s not mentioned in any documentation', 'A package.json `bin` command is undocumented — mention it in the README.'],
+      ['is not referenced in ARCHITECTURE.md', 'A source directory has no mention in ARCHITECTURE.md — add it to the Component Map.'],
+      ['is missing a', 'README.md lacks a required section (Installation / Usage / License, per the Standard README spec).'],
+    ],
+    example: 'Every root config file, package.json bin command, and source directory is named in README.md or ARCHITECTURE.md; the README has Installation, Usage, and License',
+    standard: 'Standard README (github.com/RichardLitt/standard-readme)',
+  },
+  docQuality: {
+    title: 'Doc-Quality — prose is clear and verifiable',
+    what: 'Runs 8 deterministic prose metrics on each canonical doc + README: passive voice, ambiguous pronouns, atomicity, Flesch readability, Flesch-Kincaid grade, sentence length, negation load, conditional load. Docs under 50 prose words or 3 sentences are skipped as reference material.',
+    why:  'Vague, passive, negation-heavy docs are hard for both humans and AI agents to act on. Metrics inspired by IEEE 830 / ISO 29148.',
+    triggers: [
+      ['High negation load', 'Rephrase in positive terms ("must not fail" → "must succeed"). If the negation is intentional (security/operational docs legitimately use "never"/"must not"), add the per-doc override: `<!-- docguard:quality negation-load off — your reason -->`, or set a custom bar with `<!-- docguard:quality negation-load 0.35 — reason -->`. Project-wide default: `docQuality.negationLoadThreshold` in .docguard.json.'],
+      ['High passive voice ratio', 'Use active voice: "the config is read by the loader" → "the loader reads the config".'],
+      ['High ambiguous pronoun ratio', 'Replace "it/this/that/they" with the specific noun.'],
+      ['Low atomicity', 'Split compound sentences so each states one verifiable fact (IEEE 830 §4.1).'],
+      ['Reading level too high', 'Aim for grade 12–16 for technical docs — shorter sentences, simpler words.'],
+      ['High conditional load', 'Split tangled conditionals into separate requirements.'],
+    ],
+    example: 'SECURITY.md written in active voice with negation in ≤20% of sentences — or carrying `<!-- docguard:quality negation-load off — prohibitive language is precise here -->`',
+    standard: 'IEEE 830 / ISO/IEC/IEEE 29148 (readable, verifiable requirements)',
+  },
+  schemaSync: {
+    title: 'Schema-Sync — DB models in code are documented in DATA-MODEL.md',
+    what: 'Detects schema files for 7 ORMs/frameworks (Prisma, Drizzle, Sequelize, TypeORM, Knex, Django, Rails), extracts the model/table names, and checks each appears (case-insensitive, singular/plural aware) in docs-canonical/DATA-MODEL.md. Migration/utility tables are filtered out. No schema files → passes silently.',
+    why:  'An undocumented table is a data model only the code knows — exactly the institutional memory CDD exists to preserve.',
+    triggers: [
+      ['not documented in DATA-MODEL.md', 'Add the model to DATA-MODEL.md\'s Entity Definitions section.'],
+      ['but no DATA-MODEL.md exists', 'Models were found but DATA-MODEL.md is missing. Run `docguard init` to create it, then document the schema.'],
+    ],
+    example: 'Every `model User` / `model Order` in schema.prisma is named in docs-canonical/DATA-MODEL.md',
+    standard: 'CDD principle: the data model is documented, not implied',
+  },
 };
 
+/**
+ * Validator-key → display name, mirroring the names guard prints in its
+ * report. Users only ever see these names (e.g. "Doc-Quality", "Doc Sections"),
+ * so `docguard explain` must resolve them too — typing what you see should work.
+ *
+ * This intentionally lists every key the guard registry exposes (guard.mjs).
+ * tests/explain-coverage.test.mjs asserts it stays in lock-step with the live
+ * registry, so a new validator can't ship without an explain entry + name.
+ */
+const DISPLAY_NAMES = {
+  structure: 'Structure',
+  docSections: 'Doc Sections',
+  docsSync: 'Docs-Sync',
+  drift: 'Drift-Comments',
+  changelog: 'Changelog',
+  testSpec: 'Test-Spec',
+  environment: 'Environment',
+  security: 'Security',
+  architecture: 'Architecture',
+  freshness: 'Freshness',
+  traceability: 'Traceability',
+  docsDiff: 'Docs-Diff',
+  apiSurface: 'API-Surface',
+  metadataSync: 'Metadata-Sync',
+  docsCoverage: 'Docs-Coverage',
+  docQuality: 'Doc-Quality',
+  todoTracking: 'TODO-Tracking',
+  schemaSync: 'Schema-Sync',
+  specKit: 'Spec-Kit',
+  crossReference: 'Cross-Reference',
+  generatedStaleness: 'Generated-Staleness',
+  surfaceSync: 'Surface-Sync',
+  canonicalSync: 'Canonical-Sync',
+  metricsConsistency: 'Metrics-Consistency',
+};
+
+/** Collapse a key / display name to a comparable form: lowercase, alnum only. */
+const normalizeKey = (s) => String(s).toLowerCase().replace(/[^a-z0-9]/g, '');
+
+/**
+ * normalized(alias) → canonical key, built once from both the explainer keys
+ * and the guard display names. Lets `docQuality`, `doc-quality`, `Doc-Quality`,
+ * and `"doc quality"` all resolve to the same entry.
+ */
+const ALIAS_INDEX = (() => {
+  const idx = {};
+  for (const key of Object.keys(EXPLAINERS)) idx[normalizeKey(key)] = key;
+  for (const [key, name] of Object.entries(DISPLAY_NAMES)) {
+    if (EXPLAINERS[key]) idx[normalizeKey(name)] = key; // name → key (only if explainable)
+  }
+  return idx;
+})();
+
 /**
  * Match a warning text fragment against the explainer table. Returns the
  * matching entry's key + the trigger entry that best matches, or null when
@@ -225,11 +375,10 @@ const EXPLAINERS = {
 function matchWarning(query) {
   const q = query.toLowerCase();
 
-  // Exact validator-key lookup (e.g. `docguard explain freshness`)
-  if (EXPLAINERS[query]) return { key: query, trigger: null };
-  // Also try kebab-case (e.g. `cross-reference` → `crossReference`)
-  const camelized = query.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
-  if (EXPLAINERS[camelized]) return { key: camelized, trigger: null };
+  // Key / display-name lookup, casing- and separator-insensitive. Covers
+  // `freshness`, `cross-reference`, `Doc-Quality`, `"doc sections"`, etc.
+  const aliased = ALIAS_INDEX[normalizeKey(query)];
+  if (aliased) return { key: aliased, trigger: null };
 
   // Search trigger phrases
   let best = null;
@@ -253,16 +402,19 @@ export function runExplain(projectDir, _config, flags) {
   const isJson = flags.format === 'json';
 
   if (!query) {
+    // Exhaustive by construction: iterate the guard display-name map so the
+    // list always covers every registered validator (field report, Issue A.3).
+    const listed = Object.keys(DISPLAY_NAMES).filter(k => EXPLAINERS[k]);
     if (isJson) {
-      console.log(JSON.stringify({ validators: Object.keys(EXPLAINERS) }, null, 2));
+      console.log(JSON.stringify({ validators: listed }, null, 2));
       return;
     }
     console.log(`${c.bold}🧭 docguard explain${c.reset} ${c.dim}— usage:${c.reset}`);
-    console.log(`  ${c.cyan}docguard explain <validator-key>${c.reset}    e.g. docguard explain freshness`);
+    console.log(`  ${c.cyan}docguard explain <validator>${c.reset}        e.g. docguard explain doc-quality  ${c.dim}(key or the name shown in guard)${c.reset}`);
     console.log(`  ${c.cyan}docguard explain "<warning text>"${c.reset}   e.g. docguard explain "no service-to-test mappings"`);
-    console.log(`\n${c.dim}Known validators:${c.reset}`);
-    for (const [k, e] of Object.entries(EXPLAINERS)) {
-      console.log(`  ${c.cyan}${k.padEnd(22)}${c.reset} ${c.dim}${e.title}${c.reset}`);
+    console.log(`\n${c.dim}Known validators (${listed.length}):${c.reset}`);
+    for (const k of listed) {
+      console.log(`  ${c.cyan}${DISPLAY_NAMES[k].padEnd(22)}${c.reset} ${c.dim}${EXPLAINERS[k].title}${c.reset}`);
     }
     return;
   }
@@ -305,4 +457,13 @@ export function runExplain(projectDir, _config, flags) {
 
   console.log(`${c.bold}Passing example:${c.reset}\n  ${c.dim}${e.example}${c.reset}\n`);
   console.log(`${c.bold}Standard:${c.reset} ${c.dim}${e.standard}${c.reset}`);
+
+  // v0.24: surface how to mute/tune from config — there was no in-tool way to
+  // discover this, so users reached for severity:"off" (a no-op) instead of
+  // the real switch (field report). docSections is reported under the
+  // `structure` key in guard, so it disables via that key.
+  const cfgKey = match.key === 'docSections' ? 'structure' : match.key;
+  console.log(`\n${c.bold}Tune it${c.reset} ${c.dim}(.docguard.json):${c.reset}`);
+  console.log(`  ${c.cyan}validators.${cfgKey}: false${c.reset} ${c.dim}— disable this validator entirely${c.reset}`);
+  console.log(`  ${c.cyan}severity.${cfgKey}: "high" | "low"${c.reset} ${c.dim}— change exit-code weight (low = warn-only). Severity never hides the warning from output.${c.reset}`);
 }

package/cli/commands/fix.mjs

@@ -699,10 +699,25 @@ function outputResults(issues, projectDir, config, flags) {
   const isPrompt = flags.format === 'prompt';
 
   if (issues.length === 0) {
+    // v0.24: `fix` only handles issues it can mechanically resolve / prompt for.
+    // It used to claim "documentation is complete!" even when `guard` still had
+    // advisory warnings (e.g. an unmapped Test-Spec table), so the two commands
+    // contradicted each other (field report). Surface guard's advisory count so
+    // they agree: 0 fixable ≠ 0 warnings.
+    let advisory = 0;
+    try {
+      const g = runGuardInternal(projectDir, config);
+      advisory = (g.validators || []).reduce((n, v) => n + ((v.warnings && v.warnings.length) || 0), 0);
+    } catch { /* if guard can't run, fall back to the plain clean message */ }
+
     if (isJson) {
-      console.log(JSON.stringify({ status: 'clean', issues: [], fixCount: 0 }));
+      console.log(JSON.stringify({ status: 'clean', issues: [], fixCount: 0, advisoryWarnings: advisory }));
     } else if (isPrompt) {
-      console.log('No CDD issues found. All documentation is complete.');
+      console.log(advisory > 0
+        ? `No mechanically-fixable issues. ${advisory} advisory warning(s) remain — run \`docguard guard\` to see them.`
+        : 'No CDD issues found. All documentation is complete.');
+    } else if (advisory > 0) {
+      console.log(`  ${c.green}${c.bold}✅ No fixable issues here.${c.reset} ${c.dim}guard still reports ${advisory} advisory warning(s) that need authoring, not mechanical fixes — run ${c.reset}${c.cyan}docguard guard${c.dim} to see them.${c.reset}\n`);
     } else {
       console.log(`  ${c.green}${c.bold}✅ No issues — documentation is complete!${c.reset}\n`);
     }

package/cli/commands/generate.mjs

@@ -234,13 +234,13 @@ export function runGenerate(projectDir, config, flags) {
   const scan = scanProject(projectDir);
 
   // ── 4. Deep Scan Routes ──
-  const deepRoutes = scanRoutesDeep(projectDir, stack, docTools);
+  const deepRoutes = scanRoutesDeep(projectDir, stack, docTools, { config });
   if (deepRoutes.length > 0) {
     console.log(`  ${c.bold}Route Scanning:${c.reset} ${deepRoutes.length} endpoints found (source: ${deepRoutes[0]?.source || 'code'})`);
   }
 
   // ── 5. Deep Scan Schemas ──
-  const deepSchemas = scanSchemasDeep(projectDir, stack, docTools);
+  const deepSchemas = scanSchemasDeep(projectDir, stack, docTools, config);
   if (deepSchemas.entities.length > 0) {
     console.log(`  ${c.bold}Schema Scanning:${c.reset} ${deepSchemas.entities.length} entities, ${deepSchemas.relationships.length} relationships (source: ${deepSchemas.source})`);
   }

package/cli/commands/guard.mjs

@@ -8,6 +8,7 @@
  */
 
 import { c, resolveSeverity } from '../shared.mjs';
+import { loadValidatorSuppressions } from '../validator-markers.mjs';
 import { detectAgentMode, isSpecKitInitialized } from '../ensure-skills.mjs';
 import { checkUpgradeStatus } from './upgrade.mjs';
 import { changedFilesSince, isGitRepo } from '../shared-git.mjs';
@@ -220,10 +221,26 @@ export function runGuardInternal(projectDir, config) {
     // Metrics-Consistency runs post-loop (needs guard results)
   ];
 
+  // Inline `<!-- docguard:validator <key> n/a — reason -->` markers let a
+  // project declare a whole validator non-applicable, visibly and in-repo
+  // (e.g. a POC marking testSpec/traceability N/A). Distinct from the config
+  // `validators:{k:false}` switch: a marked validator renders as ➖ [N/A] with
+  // its reason, not a silent skip. Resolve once against the full key set.
+  const allValidatorKeys = [...new Set(validatorMap.map(v => v.key)), 'canonicalSync', 'metricsConsistency'];
+  const { suppressed: naMarkers, unknown: unknownMarkers } = loadValidatorSuppressions(projectDir, allValidatorKeys);
+  const naResult = (name, key) => ({
+    name, key, status: 'na', quality: null, errors: [], warnings: [], passed: 0, total: 0, durationMs: 0,
+    note: naMarkers.get(key) ? `declared N/A: ${naMarkers.get(key)}` : 'declared N/A',
+  });
+
   // v0.14-Q2: per-validator timing. Cheap (one `performance.now()` pair per
   // validator) and the data is what we'd need to optimize anything later.
   // Exposed via --profile in the public guard.
   for (const { key, name, fn } of validatorMap) {
+    if (naMarkers.has(key)) {
+      results.push(naResult(name, key));
+      continue;
+    }
     if (validators[key] === false) {
       results.push({ name, key, status: 'skipped', quality: null, errors: [], warnings: [], passed: 0, total: 0, durationMs: 0 });
       continue;
@@ -244,7 +261,9 @@ export function runGuardInternal(projectDir, config) {
   //    Needs the live validator results to count "real" validators that ran.
   //    (Pre-canonical-sync ordering — comes before metrics-consistency so the
   //    metrics validator sees a stable surface count.)
-  if (validators.canonicalSync !== false) {
+  if (naMarkers.has('canonicalSync')) {
+    results.push(naResult('Canonical-Sync', 'canonicalSync'));
+  } else if (validators.canonicalSync !== false) {
     const start = performance.now();
     try {
       const result = validateCanonicalSync(projectDir, config, results);
@@ -257,7 +276,9 @@ export function runGuardInternal(projectDir, config) {
   }
 
   // ── Metrics-Consistency runs AFTER all other validators (needs their results) ──
-  if (validators.metricsConsistency !== false) {
+  if (naMarkers.has('metricsConsistency')) {
+    results.push(naResult('Metrics-Consistency', 'metricsConsistency'));
+  } else if (validators.metricsConsistency !== false) {
     const start = performance.now();
     try {
       const result = validateMetricsConsistency(projectDir, config, results);
@@ -294,7 +315,13 @@ export function runGuardInternal(projectDir, config) {
     else effectiveWarnings += wCount;
   }
 
-  const overallStatus = totalErrors > 0 ? 'FAIL' : totalWarnings > 0 ? 'WARN' : 'PASS';
+  // The headline status word MUST agree with the exit code, which is
+  // severity-aware (effectiveErrors/effectiveWarnings, computed above).
+  // Deriving it from RAW counts was a bug: a validator marked severity=high
+  // with only warnings printed "WARN" yet exited 1 (FAIL), and one marked
+  // severity=low printed "WARN" yet exited 0 (PASS). Use effective counts so
+  // what the user reads is what CI does.
+  const overallStatus = effectiveErrors > 0 ? 'FAIL' : effectiveWarnings > 0 ? 'WARN' : 'PASS';
 
   return {
     project: config.projectName,
@@ -310,6 +337,11 @@ export function runGuardInternal(projectDir, config) {
     effectiveErrors,
     effectiveWarnings,
     validators: results,
+    // Unknown keys in `docguard:validator … n/a` markers — typo protection so
+    // a mistyped key doesn't silently fail to suppress. Surfaced by runGuard.
+    validatorMarkerWarnings: unknownMarkers.map(
+      u => `Unknown validator key "${u.raw}" in a docguard:validator marker — ignored. Valid keys: ${allValidatorKeys.join(', ')}`
+    ),
     timestamp: new Date().toISOString(),
   };
 }
@@ -328,10 +360,18 @@ export function runGuardInternal(projectDir, config) {
 export const CHANGED_ONLY_VALIDATORS = ['docsSync', 'environment', 'apiSurface', 'drift', 'todoTracking'];
 
 /**
- * Build a validators map that enables only the pre-commit-lite set.
+ * Build a validators map that enables the pre-commit-lite set — PLUS any
+ * validator the team explicitly escalated to `severity: high`.
  * Used by `docguard guard --changed-only`.
+ *
+ * Why the union: `--changed-only` trades coverage for speed, but a
+ * `severity: high` override is an explicit "this must always block CI" signal.
+ * Silently dropping such a validator here meant a changed-only gate could pass
+ * (exit 0) on exactly the drift the team most wanted blocked — e.g. a committed
+ * secret when `security` is marked high. So high-severity validators are forced
+ * on regardless of the lite set, unless the user also explicitly disabled them.
  */
-function liteValidatorsConfig() {
+export function liteValidatorsConfig(config = {}) {
   const all = [
     'structure', 'docsSync', 'drift', 'changelog', 'testSpec', 'environment',
     'security', 'architecture', 'freshness', 'traceability', 'docsDiff',
@@ -339,8 +379,15 @@ function liteValidatorsConfig() {
     'schemaSync', 'specKit', 'crossReference', 'generatedStaleness',
     'canonicalSync', 'metricsConsistency',
   ];
+  const userValidators = (config && config.validators) || {};
   const out = {};
-  for (const k of all) out[k] = CHANGED_ONLY_VALIDATORS.includes(k);
+  for (const k of all) {
+    let enabled = CHANGED_ONLY_VALIDATORS.includes(k);
+    if (!enabled && resolveSeverity(config, k) === 'high' && userValidators[k] !== false) {
+      enabled = true;
+    }
+    out[k] = enabled;
+  }
   return out;
 }
 
@@ -358,16 +405,24 @@ export function runGuard(projectDir, config, flags) {
     // scope to this list; others run normally over the whole tree.
     const ref = flags.since || 'HEAD~1';
     const changed = isGitRepo(projectDir) ? changedFilesSince(projectDir, ref) : [];
+    const liteVals = liteValidatorsConfig(config);
+    // Validators that ran beyond the lite set because they're severity=high.
+    const escalated = Object.keys(liteVals).filter(
+      k => liteVals[k] && !CHANGED_ONLY_VALIDATORS.includes(k)
+    );
     config = {
       ...config,
-      validators: liteValidatorsConfig(),
+      validators: liteVals,
       changedFiles: changed,
       changedSinceRef: ref,
     };
     const label = changed.length > 0
       ? `${changed.length} file(s) changed since ${ref}`
       : `no changes since ${ref} — running all ${CHANGED_ONLY_VALIDATORS.length} lite validators on full tree`;
-    console.log(`${c.cyan}⚡ docguard guard --changed-only${c.reset} ${c.dim}(${label})${c.reset}\n`);
+    const escalatedNote = escalated.length > 0
+      ? ` ${c.yellow}+ ${escalated.length} high-severity validator(s): ${escalated.join(', ')}${c.reset}`
+      : '';
+    console.log(`${c.cyan}⚡ docguard guard --changed-only${c.reset} ${c.dim}(${label})${c.reset}${escalatedNote}\n`);
   }
 
   const data = runGuardInternal(projectDir, config);
@@ -440,11 +495,23 @@ export function runGuard(projectDir, config, flags) {
   console.log(`\n${c.bold}  ─────────────────────────────────────${c.reset}`);
 
   if (data.status === 'PASS') {
-    console.log(`  ${c.green}${c.bold}✅ PASS${c.reset} ${c.green}— All ${data.total} checks passed${c.reset}`);
+    // PASS can still carry raw warnings if a validator was demoted to
+    // severity=low — surface that honestly rather than claiming a clean sweep.
+    if (data.warnings > 0) {
+      console.log(`  ${c.green}${c.bold}✅ PASS${c.reset} ${c.green}— ${data.passed}/${data.total} passed (${data.warnings} non-blocking warning(s))${c.reset}`);
+    } else {
+      console.log(`  ${c.green}${c.bold}✅ PASS${c.reset} ${c.green}— All ${data.total} checks passed${c.reset}`);
+    }
   } else if (data.status === 'WARN') {
-    console.log(`  ${c.yellow}${c.bold}⚠️  WARN${c.reset} ${c.yellow}— ${data.passed}/${data.total} passed, ${data.warnings} warning(s)${c.reset}`);
+    // effective* counts are what drove the verdict; raw warnings are still
+    // enumerated per-validator above, so nothing is hidden.
+    console.log(`  ${c.yellow}${c.bold}⚠️  WARN${c.reset} ${c.yellow}— ${data.passed}/${data.total} passed, ${data.effectiveWarnings} warning(s)${c.reset}`);
   } else {
-    console.log(`  ${c.red}${c.bold}❌ FAIL${c.reset} ${c.red}— ${data.passed}/${data.total} passed, ${data.errors} error(s), ${data.warnings} warning(s)${c.reset}`);
+    // effectiveErrors may include warnings escalated by severity=high, so call
+    // them "blocking issue(s)" rather than "error(s)". The severity-override
+    // note below spells out any escalation/demotion.
+    const warnSuffix = data.effectiveWarnings > 0 ? `, ${data.effectiveWarnings} warning(s)` : '';
+    console.log(`  ${c.red}${c.bold}❌ FAIL${c.reset} ${c.red}— ${data.passed}/${data.total} passed, ${data.effectiveErrors} blocking issue(s)${warnSuffix}${c.reset}`);
   }
 
   // Next step hint — always point to diagnose when issues exist
@@ -533,6 +600,14 @@ export function runGuard(projectDir, config, flags) {
     console.log(`\n  ${c.yellow}💡${c.reset} ${c.dim}Enhance DocGuard with Spec Kit: ${c.cyan}uv tool install specify-cli --from git+https://github.com/github/spec-kit.git${c.reset}`);
   }
 
+  // Typo protection for docguard:validator markers — a mistyped key would
+  // otherwise silently fail to suppress the validator.
+  if (Array.isArray(data.validatorMarkerWarnings) && data.validatorMarkerWarnings.length > 0) {
+    for (const w of data.validatorMarkerWarnings) {
+      console.log(`\n  ${c.yellow}⚠ ${w}${c.reset}`);
+    }
+  }
+
   // When severity overrides demoted warnings to "low" (or promoted them to
   // "high"), show a one-line note so the user knows the exit code may not
   // match what they expected from reading the warning count.

package/cli/commands/hooks.mjs

@@ -56,6 +56,7 @@ function spliceManagedBlock(existing, newBody) {
 }
 import { resolve } from 'node:path';
 import { c } from '../shared.mjs';
+import { getHooksDir } from '../shared-git.mjs';
 
 const HOOKS = {
   'pre-commit': {
@@ -216,17 +217,20 @@ export function runHooks(projectDir, config, flags) {
   console.log(`${c.bold}🪝 DocGuard Hooks — ${config.projectName}${c.reset}`);
   console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
 
-  // Check if .git exists
-  const gitDir = resolve(projectDir, '.git');
-  if (!existsSync(gitDir)) {
+  // Resolve the real hooks dir via git — NOT `<projectDir>/.git/hooks`, which
+  // is wrong inside a linked worktree (where `.git` is a file, not a dir) and
+  // ignores a custom core.hooksPath.
+  const hooksDir = getHooksDir(projectDir);
+  if (!hooksDir) {
     console.log(`  ${c.red}❌ Not a git repository. Run ${c.cyan}git init${c.red} first.${c.reset}\n`);
     process.exit(1);
   }
 
-  const hooksDir = resolve(gitDir, 'hooks');
-  if (!existsSync(hooksDir)) {
-    mkdirSync(hooksDir, { recursive: true });
-  }
+  // Only create the dir when we're actually going to write a hook. Read-only
+  // modes (--list, --remove) must not have a filesystem side effect.
+  const ensureHooksDir = () => {
+    if (!existsSync(hooksDir)) mkdirSync(hooksDir, { recursive: true });
+  };
 
   // Determine which hooks to install
   let hookTypes = Object.keys(HOOKS);
@@ -273,6 +277,7 @@ export function runHooks(projectDir, config, flags) {
   }
 
   // Install mode
+  ensureHooksDir();
   let installed = 0;
   let skipped = 0;