docguard-cli 0.23.0 → 0.25.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)
 
 ---

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

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

@@ -40,10 +40,40 @@ function backupFile(filePath) {
  * Call this instead of raw writeFileSync when generating docs.
  */
 function safeWrite(filePath, content) {
+  mkdirSync(dirname(filePath), { recursive: true });
   backupFile(filePath);
   writeFileSync(filePath, content, 'utf-8');
 }
 
+/**
+ * B7 (field report): after generate emits canonical docs, register them in
+ * `.docguard.json` requiredFiles.canonical so `guard` doesn't immediately flag
+ * the generator's OWN output as an "orphaned" doc ("exists but not in your
+ * requiredFiles"). Only ADDS (never removes/deletes), only docs-canonical/*.md
+ * that actually exist on disk, and only when a config file already exists (init
+ * owns config creation). Idempotent — a second run with nothing new is a no-op.
+ * @returns {number} count of paths newly registered.
+ */
+function registerGeneratedCanonicalDocs(projectDir, candidatePaths) {
+  const cfgPath = resolve(projectDir, '.docguard.json');
+  if (!existsSync(cfgPath)) return 0;
+  let cfg;
+  try { cfg = JSON.parse(readFileSync(cfgPath, 'utf-8')); } catch { return 0; }
+  const canon = [...new Set(candidatePaths)].filter(p =>
+    p.startsWith('docs-canonical/') && p.endsWith('.md') && existsSync(resolve(projectDir, p))
+  );
+  if (canon.length === 0) return 0;
+  if (!cfg.requiredFiles || typeof cfg.requiredFiles !== 'object') cfg.requiredFiles = {};
+  const existing = Array.isArray(cfg.requiredFiles.canonical) ? cfg.requiredFiles.canonical : [];
+  const seen = new Set(existing);
+  let added = 0;
+  for (const p of canon) if (!seen.has(p)) { existing.push(p); seen.add(p); added++; }
+  if (added === 0) return 0;
+  cfg.requiredFiles.canonical = existing;
+  try { writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n', 'utf-8'); } catch { return 0; }
+  return added;
+}
+
 const CODE_EXTENSIONS = new Set([
   '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx',
   '.py', '.java', '.go', '.rs', '.rb', '.php', '.cs',
@@ -113,6 +143,19 @@ function appendStandardsCitation(content, docName) {
   return content.trimEnd() + '\n' + footer;
 }
 
+/**
+ * F1 (field report): web-shaped surface (HTTP endpoints, SDK deps, routes)
+ * auto-extracted from a cli/library/unknown-kind project is often pattern-
+ * matches in the project's OWN source (e.g. a scanner/linter whose code mentions
+ * express, boto3, jwt as detection strings), not real usage. We do NOT suppress
+ * it — that could hide a real surface (a false-green) — we flag it 'low'
+ * confidence so the surface is verified before being documented. Web kinds
+ * (webapp/api/service) stay 'normal'.
+ */
+function surfaceConfidence(kind) {
+  return ['webapp', 'api', 'service'].includes(kind) ? 'normal' : 'low';
+}
+
 /**
  * `docguard generate --plan` — AI-powered Generate.
  * Builds the code-truth skeleton (marked sections) and emits the agent task
@@ -139,6 +182,7 @@ export function runGeneratePlan(projectDir, config, flags) {
         screens: plan.surface.screens.length,
         components: plan.surface.components.length,
         envVars: plan.surface.envVars.length,
+        confidence: surfaceConfidence(plan.profile.kind),
       },
       docs: plan.docs.map(d => ({
         path: d.path,
@@ -169,11 +213,18 @@ export function runGeneratePlan(projectDir, config, flags) {
           : `> **AI task:** ${sec.task}\n<!-- docguard:pending agent writes this section -->`;
         content = upsertSection(content, sec.id, body, { source: sec.source }).content;
       }
-      writeFileSync(full, content, 'utf-8');
+      // Route through safeWrite: creates the parent dir (docs-implementation/ may
+      // not exist yet — was an ENOENT crash) and snapshots a .bak before writing.
+      safeWrite(full, content);
       wrote++;
     }
+    // B7: register the scaffolded canonical docs so guard doesn't flag them.
+    const registered = registerGeneratedCanonicalDocs(projectDir, plan.docs.map(d => d.path));
     console.log(`${c.bold}🔮 DocGuard Generate --plan --write — ${config.projectName}${c.reset}`);
     console.log(`  ${c.green}✅ Scaffolded ${wrote} doc(s)${c.reset} with code-truth sections + ${plan.agentTasks.length} agent task(s).`);
+    if (registered > 0) {
+      console.log(`  ${c.dim}Registered ${registered} canonical doc(s) in .docguard.json requiredFiles.${c.reset}`);
+    }
     console.log(`  ${c.dim}Now run your AI agent (/docguard.fix) to write the prose sections, then ${c.cyan}docguard guard${c.dim}.${c.reset}\n`);
     return;
   }
@@ -182,6 +233,10 @@ export function runGeneratePlan(projectDir, config, flags) {
   console.log(`${c.bold}🔮 DocGuard Generate Plan — ${config.projectName}${c.reset}`);
   console.log(`${c.dim}   ${plan.profile.polyglot ? 'Polyglot' : 'Single-language'}: ${plan.profile.languages.join(', ')} | frameworks: ${plan.profile.frameworks.join(', ') || '—'} | kind: ${plan.profile.kind}${c.reset}\n`);
   console.log(`  ${c.bold}Code-truth surface:${c.reset} ${plan.surface.endpoints.length} endpoints · ${plan.surface.entities.length} entities · ${plan.surface.screens.length} screens · ${plan.surface.components.length} components · ${plan.surface.envVars.length} env vars\n`);
+  const webSurface = plan.surface.endpoints.length + plan.surface.entities.length + plan.surface.screens.length + plan.surface.components.length;
+  if (surfaceConfidence(plan.profile.kind) === 'low' && webSurface > 0) {
+    console.log(`  ${c.yellow}⚠️  Low-confidence surface:${c.reset} ${c.dim}this looks like a ${plan.profile.kind} (not a web app), so the HTTP/SDK/route surface above may be pattern-matches in your OWN source — not real usage. Verify before documenting; pin any corrected code section with ${c.cyan}pinned="reason"${c.dim}.${c.reset}\n`);
+  }
   console.log(`  ${c.bold}Documents to build (${plan.docs.length}):${c.reset}`);
   for (const d of plan.docs) {
     const code = d.sections.filter(s => s.source === 'code').length;
@@ -234,13 +289,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})`);
   }
@@ -301,8 +356,19 @@ export function runGenerate(projectDir, config, flags) {
   created += rootResults.created;
   skipped += rootResults.skipped;
 
+  // B7: keep guard coherent — register the canonical docs we emitted so the
+  // traceability validator doesn't flag the generator's own output.
+  const registered = registerGeneratedCanonicalDocs(projectDir, [
+    'docs-canonical/ARCHITECTURE.md', 'docs-canonical/API-REFERENCE.md',
+    'docs-canonical/DATA-MODEL.md', 'docs-canonical/ENVIRONMENT.md',
+    'docs-canonical/TEST-SPEC.md', 'docs-canonical/SECURITY.md',
+  ]);
+
   console.log(`\n${c.bold}  ─────────────────────────────────────${c.reset}`);
   console.log(`  ${c.green}Generated: ${created}${c.reset}  Skipped: ${skipped} (already exist)`);
+  if (registered > 0) {
+    console.log(`  ${c.dim}Registered ${registered} canonical doc(s) in .docguard.json requiredFiles.${c.reset}`);
+  }
   if (docTools._detected.length > 0) {
     console.log(`  ${c.dim}Leveraged: ${docTools._detected.join(', ')} (existing tools detected)${c.reset}`);
   }

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.