docguard-cli 0.27.0 → 0.29.0

package/cli/docguard.mjs

@@ -44,9 +44,11 @@ import { runUpgrade } from './commands/upgrade.mjs';
 import { runImpact } from './commands/impact.mjs';
 import { runExplain } from './commands/explain.mjs';
 import { runFeedback } from './commands/feedback.mjs';
+import { runVerify } from './commands/verify.mjs';
 import { runMemory } from './commands/memory.mjs';
 import { runDemo } from './commands/demo.mjs';
 import { runAgent } from './commands/agent.mjs';
+import { runMcp } from './commands/mcp.mjs';
 import { ensureSkills } from './ensure-skills.mjs';
 
 // ── Shared constants (imported to break circular dependencies) ──────────
@@ -87,7 +89,9 @@ ${c.bold}Tools (situational, but day-to-day useful)${c.reset}
   ${c.green}generate${c.reset}   Reverse-engineer canonical docs from existing code (${c.cyan}--plan${c.reset} for AI scan)
   ${c.green}agent${c.reset}      One-shot agent task graph — ordered tasks, pre-filled code-truth, per-task verify (${c.cyan}--format json${c.reset})
   ${c.green}explain${c.reset}    Explain a validator key, warning text, or finding code (${c.cyan}docguard explain SEC001${c.reset})
+  ${c.green}verify${c.reset}     Extract documented numbers/limits/enums for an agent to check vs code (${c.cyan}--semantic${c.reset})
   ${c.green}feedback${c.reset}   Report likely false positives back to DocGuard (local-first + 1-click prefilled issue)
+  ${c.green}mcp${c.reset}        MCP server over stdio — guard/score/explain/verify/diagnose as agent tools
   ${c.green}memory${c.reset}     Show what DocGuard remembers (${c.cyan}--diff${c.reset} drills into drift)
   ${c.green}trace${c.reset}      Requirements traceability matrix (${c.cyan}--reverse${c.reset} for code→doc map)
   ${c.green}upgrade${c.reset}    Migrate ${c.cyan}.docguard.json${c.reset} schema + CLI (${c.cyan}--apply --pr${c.reset} for team-wide PR)
@@ -232,13 +236,14 @@ const COMMAND_HELP = {
     examples: ['docguard diff', 'docguard diff --since HEAD~5'],
   },
   sync: {
-    summary: 'Refresh code-truth doc sections (preview by default).',
-    usage: 'docguard sync [--write] [--since <ref>]',
+    summary: 'Refresh code-truth doc sections (preview by default). `--tests` reconciles the TEST-SPEC Source-to-Test Map from disk.',
+    usage: 'docguard sync [--write] [--since <ref>] [--tests]',
     flags: [
       ['--write', 'Apply the refresh (default is a dry-run preview)'],
       ['--since <ref>', 'Only sync sections whose source files changed since <ref>'],
+      ['--tests', 'Reconcile the TEST-SPEC Source-to-Test Map: drop ghost-source rows, append newly-covered source↔test pairs (report ghost tests). Pair with --write to apply.'],
     ],
-    examples: ['docguard sync', 'docguard sync --write'],
+    examples: ['docguard sync', 'docguard sync --write', 'docguard sync --tests', 'docguard sync --tests --write'],
   },
   fix: {
     summary: 'Generate AI fix instructions for docs (or apply deterministic fixes).',
@@ -287,6 +292,15 @@ const COMMAND_HELP = {
     flags: [['--format json', 'Machine-readable list of reportable findings + URLs']],
     examples: ['docguard feedback'],
   },
+  verify: {
+    summary: 'Extract the semantic claims in your canonical docs — documented numbers, limits, and enums (retention days, rate limits, GSI/role counts, status enums) — as a verification task list the agent checks against the code. This is the highest-value bug class (a doc value that drifted from code) and the one regex/AST cannot judge. DocGuard finds the claims; the LLM confirms them.',
+    usage: 'docguard verify [--semantic] [--format json]',
+    flags: [
+      ['--semantic', 'Extract documented numbers/limits/enums to verify against code (the current — and default — mode)'],
+      ['--format json', 'Machine-readable task list (the agent-executable artifact)'],
+    ],
+    examples: ['docguard verify --semantic', 'docguard verify --semantic --format json'],
+  },
 };
 
 function printCommandHelp(command) {
@@ -355,6 +369,31 @@ async function main() {
       flags.auto = true;
     } else if (args[i] === '--write') {
       flags.write = true;
+    } else if (args[i] === '--tests') {
+      // v0.28 (field report #10): `docguard sync --tests` reconciles the
+      // TEST-SPEC Source-to-Test Map from disk.
+      flags.tests = true;
+    } else if (args[i] === '--semantic') {
+      // v0.28 (field report #5): `docguard verify --semantic` extracts
+      // documented numbers/enums/limits for the agent to check against code.
+      flags.semantic = true;
+    } else if (args[i] === '--full') {
+      // v0.29: `docguard llms --full` emits llms-full.txt (inline doc bodies,
+      // the Mintlify-popularized companion to the llms.txt index).
+      flags.full = true;
+    } else if (args[i] === '--pack') {
+      // v0.29: `docguard memory --pack` writes .docguard/context-pack.md — a
+      // compact code-truth-stamped session-start context for AI agents.
+      flags.pack = true;
+    } else if (args[i] === '--sync') {
+      // v0.29: `docguard agents --sync` regenerates the agent-file family
+      // (CLAUDE.md, GEMINI.md, copilot-instructions, .cursor rules) from
+      // AGENTS.md — the canonical source. Kills hand-duplication drift.
+      flags.sync = true;
+    } else if (args[i] === '--check') {
+      // v0.29: `docguard agents --check` — CI staleness gate for the synced
+      // agent-file family (exit 2 when a variant is missing or stale).
+      flags.check = true;
     } else if (args[i] === '--plan') {
       flags.plan = true;
     } else if (args[i] === '--since' && args[i + 1]) {
@@ -492,10 +531,13 @@ async function main() {
   // touch" — so it joins the club to suppress the banner AND ensureSkills'
   // .agent/.specify writes, which were a surprising side effect of a bare
   // `generate --plan` (and were already suppressed for `--plan --write`).
-  const jsonMode = flags.format === 'json';
+  // v0.29: 'sarif' joins 'json' — any machine format where stdout IS the
+  // artifact belongs here, or the banner corrupts the payload.
+  const jsonMode = flags.format === 'json' || flags.format === 'sarif';
   // `agent` emits a machine task graph (JSON by default) — it must be banner-
   // free and side-effect-free like the other read-only commands.
-  const headless = jsonMode || flags.write || flags.checkOnly || flags.changedOnly || flags.quiet || flags.plan || command === 'agent';
+  // `mcp`: stdout IS the JSON-RPC transport — any banner byte corrupts the stream.
+  const headless = jsonMode || flags.write || flags.checkOnly || flags.changedOnly || flags.quiet || flags.plan || command === 'agent' || command === 'mcp';
 
   if (!headless) printBanner();
 
@@ -518,6 +560,10 @@ async function main() {
     // feedback only writes its own .docguard/feedback/ — it must NOT scaffold
     // skills or touch source, so it's gated out of ensureSkills like the rest.
     'feedback',
+    // verify only reads docs and emits a task list — pure report.
+    'verify',
+    // mcp serves read-only tools over stdio — scaffolding writes are off-limits.
+    'mcp',
   ]);
 
   // Silent auto-check: install skills/commands if missing. Skip entirely in
@@ -663,6 +709,17 @@ async function main() {
       // redacted, capped GitHub issue URL. Opt-in; nothing filed automatically.
       runFeedback(projectDir, config, flags);
       break;
+    case 'verify':
+      // v0.28 (field report #5): extract documented numbers/limits/enums as a
+      // verification task list for the agent to check against code (semantic
+      // drift — the class regex/AST can't see). Read-only.
+      runVerify(projectDir, config, flags);
+      break;
+    case 'mcp':
+      // MCP stdio server — guard/score/explain/verify-claims/diagnose as tools
+      // for MCP clients. Long-lived; resolves when stdin closes.
+      await runMcp(projectDir, config, flags);
+      break;
     case 'memory':
       runMemory(projectDir, config, flags);
       break;

package/cli/findings.mjs

@@ -89,6 +89,505 @@ export const CODES = {
     help: 'The secret scan matched zero source files — usually a too-broad ignore config or a wrong sourceRoot. A scan that checks nothing is a dangerous false ✅.',
     suppress: null,
   },
+  // ── v0.29 findings-migration tranche (structure / changelog / metrics) ──
+  STR001: {
+    validator: 'structure',
+    title: 'Missing required file',
+    help: 'A file listed in requiredFiles (canonical doc, changelog, or drift log) does not exist. Create it from a template with `docguard init`, or remove it from `requiredFiles` in .docguard.json if your profile genuinely does not need it.',
+    suppress: null,
+  },
+  STR002: {
+    validator: 'structure',
+    title: 'Missing agent instructions file',
+    help: 'None of the configured agent files (AGENTS.md / CLAUDE.md) exist. AI agents working in this repo have no project contract. Create one with `docguard init` or write it by hand.',
+    suppress: null,
+  },
+  STR003: {
+    validator: 'structure',
+    title: 'Missing required doc section',
+    help: 'A canonical doc exists but lacks a section its document type requires. Add the section — or, if it is genuinely not applicable, own the absence with an inline marker: `<!-- docguard:section <slug> n/a — reason -->`.',
+    suppress: '<!-- docguard:section <slug> n/a — reason -->',
+  },
+  CHG001: {
+    validator: 'changelog',
+    title: 'Missing [Unreleased] section',
+    help: 'Keep a Changelog format expects an [Unreleased] section where in-progress work accumulates before each release. `docguard fix --write` inserts one.',
+    suppress: null,
+  },
+  CHG002: {
+    validator: 'changelog',
+    title: 'No version sections',
+    help: 'CHANGELOG.md has no `## [version]` headers — it does not follow Keep a Changelog format, so release tooling and readers cannot parse the history.',
+    suppress: null,
+  },
+  CHG003: {
+    validator: 'changelog',
+    title: 'Staged code without a CHANGELOG entry',
+    help: 'Code files are staged for commit but the changelog is not. Per STANDARD.md, a code change and its changelog entry travel in the same commit.',
+    suppress: null,
+  },
+  MET001: {
+    validator: 'metricsConsistency',
+    title: 'Documented count drifted from DocGuard meta-count',
+    help: 'A docguard-bound "N checks/validators" number in a doc no longer matches the tool\'s actual count. `docguard fix --write` rewrites it (fail-closed: only docguard-bound lines, with provenance).',
+    suppress: null,
+  },
+  MET002: {
+    validator: 'metricsConsistency',
+    title: 'Documented count drifted from a declared collection',
+    help: 'A doc states "N <noun>" for a noun declared in `config.collections`, but the collection glob matches a different number of files. Either the doc is stale (fix with `docguard fix --write`) or the code lost/gained members unintentionally — check which side is wrong before fixing.',
+    suppress: null,
+  },
+  FRS001: {
+    validator: 'freshness',
+    title: 'Doc has no freshness signal',
+    help: 'The doc exists but is not committed to git and carries no review marker, so its currency cannot be assessed. Commit it, or stamp it with `<!-- docguard:last-reviewed YYYY-MM-DD -->` (or `<!-- docguard:status approved -->` for a doc generated this session).',
+    suppress: '<!-- docguard:status approved -->',
+  },
+  FRS002: {
+    validator: 'freshness',
+    title: 'Code moved on since the doc was last updated',
+    help: '10+ code commits landed after the doc\'s last update/review — its code-truth sections are likely stale. Run `docguard sync --write` to refresh them in one pass, or review and stamp `<!-- docguard:last-reviewed YYYY-MM-DD -->` if it is still accurate.',
+    suppress: null,
+  },
+  FRS003: {
+    validator: 'freshness',
+    title: 'Doc predates the latest code change by 30+ days',
+    help: 'The doc\'s last update is more than 30 days older than the newest code commit. Review it against the current code, then update it or stamp it reviewed.',
+    suppress: null,
+  },
+  FRS004: {
+    validator: 'freshness',
+    title: 'CHANGELOG lagging behind code changes',
+    help: 'Code changed but CHANGELOG.md has not been updated in over a week. Add the missing entries under [Unreleased].',
+    suppress: null,
+  },
+  FRS005: {
+    validator: 'freshness',
+    title: 'DRIFT-LOG possibly stale',
+    help: 'Recent commits added `DRIFT:` comments but DRIFT-LOG.md has not kept pace. Log the new deviations (each DRIFT comment needs a DRIFT-LOG entry) or remove resolved markers.',
+    suppress: null,
+  },
+  DSY001: {
+    validator: 'docsSync',
+    title: 'Route not referenced in canonical docs',
+    help: 'A route file exists but neither its path nor its basename appears in any docs-canonical .md file. Reference the route in a canonical doc (e.g. ARCHITECTURE.md or an API doc) so the documented surface matches the code.',
+    suppress: null,
+  },
+  DSY002: {
+    validator: 'docsSync',
+    title: 'Service not referenced in canonical docs',
+    help: 'A service/lib file exists but neither its path nor its basename appears in any docs-canonical .md file. Reference the service in a canonical doc (e.g. ARCHITECTURE.md) so the documented surface matches the code.',
+    suppress: null,
+  },
+  DSY003: {
+    validator: 'docsSync',
+    title: 'Route file missing from OpenAPI spec',
+    help: 'A route file defines paths (or has a route-like filename) with no matching path in the detected OpenAPI/Swagger spec. Re-run your spec generator (e.g. zod-to-openapi) or add the paths to the spec by hand.',
+    suppress: null,
+  },
+  DDF001: {
+    validator: 'docsDiff',
+    title: 'Tech Stack drift',
+    help: 'The tech named in docs-canonical/ARCHITECTURE.md and the dependencies actually declared (package.json across the monorepo, Dockerfile, .tf files) disagree. Drift is two-sided — document the new tech or remove the stale entries after checking which side is wrong.',
+    suppress: null,
+  },
+  DDF002: {
+    validator: 'docsDiff',
+    title: 'Test Files drift',
+    help: 'The test files documented in docs-canonical/TEST-SPEC.md and the test files on disk disagree. Add entries for new tests or remove documented tests that no longer exist — TEST-SPEC.md entries may be glob patterns.',
+    suppress: null,
+  },
+  DCV001: {
+    validator: 'docsCoverage',
+    title: 'Undocumented config file',
+    help: 'A project-specific config/dotfile at the repo root is not mentioned in any documentation. Document its purpose in ARCHITECTURE.md or README.md, or add it to `ignore` in .docguard.json if it is genuinely internal.',
+    suppress: null,
+  },
+  DCV002: {
+    validator: 'docsCoverage',
+    title: 'Undocumented CLI bin command',
+    help: 'package.json declares a `bin` entry users can run, but no documentation mentions it. Document the command, typically in README.md under Usage.',
+    suppress: null,
+  },
+  DCV003: {
+    validator: 'docsCoverage',
+    title: 'Source directory not in ARCHITECTURE.md',
+    help: 'A directory under a source root is not referenced in ARCHITECTURE.md. Add it to the Component Map, or add an ignore pattern in .docguard.json if it is build output.',
+    suppress: null,
+  },
+  DCV004: {
+    validator: 'docsCoverage',
+    title: 'Code-referenced config not documented',
+    help: "Source code reads a config file (a resolve/readFileSync/existsSync call) that no documentation mentions. Describe the file's purpose and format in README.md or ARCHITECTURE.md.",
+    suppress: null,
+  },
+  DCV005: {
+    validator: 'docsCoverage',
+    title: 'README missing a standard section',
+    help: 'README.md lacks a section every well-documented project needs — Installation, Usage, or License (Standard README spec). Add the missing section.',
+    suppress: null,
+  },
+  DCV006: {
+    validator: 'docsCoverage',
+    title: 'IaC detected but no Infrastructure section',
+    help: 'An IaC tool (CDK, Terraform, Pulumi, SAM, or Serverless) was detected but ARCHITECTURE.md has no Infrastructure heading. Add an "Infrastructure" section covering the tool\'s layout — the warning names the exact marker file and directories to describe.',
+    suppress: null,
+  },
+  MDS001: {
+    validator: 'metadataSync',
+    title: 'extension.yml version out of sync',
+    help: 'An extension.yml declares a version that differs from package.json. `docguard fix --write` rewrites it to the current version.',
+    suppress: null,
+  },
+  MDS002: {
+    validator: 'metadataSync',
+    title: 'Stale version reference in docs',
+    help: 'A markdown file references an older version of this package in an actionable context (download URL, install command, or version: declaration). `docguard fix --write` replaces it with the current version; prose mentions of old versions are intentionally not flagged.',
+    suppress: null,
+  },
+  ENV001: {
+    validator: 'environment',
+    title: 'Missing setup section in ENVIRONMENT.md',
+    help: 'ENVIRONMENT.md lacks both a "## Prerequisites" and a "## Setup Steps" heading (H2/H3 anchored, not a TOC mention). Add a Setup Steps section describing how to get the project running from a fresh clone.',
+    suppress: null,
+  },
+  ENV002: {
+    validator: 'environment',
+    title: 'Missing Environment Variables section',
+    help: 'ENVIRONMENT.md has no "## Environment Variables" heading. Add the section and document each variable the app reads — backticked names or a pipe table both count.',
+    suppress: null,
+  },
+  ENV003: {
+    validator: 'environment',
+    title: 'Env vars used in code but undocumented',
+    help: "Variables read via process.env / import.meta.env were found in code but not in ENVIRONMENT.md or .env.example. Document each listed variable in the doc, or add it to .env.example — either counts as documentation.",
+    suppress: null,
+  },
+  ENV004: {
+    validator: 'environment',
+    title: 'ENVIRONMENT.md references a missing .env.example',
+    help: 'The doc mentions .env.example but the file does not exist. Create it with placeholder values, or remove the stale reference.',
+    suppress: null,
+  },
+  ENV005: {
+    validator: 'environment',
+    title: '.env exists without a .env.example template',
+    help: "A local .env (or .env.local / .env.development) exists but there is no .env.example, so new contributors won't know what vars to set. Create a .env.example listing every variable with a placeholder value.",
+    suppress: null,
+  },
+  TSP001: {
+    validator: 'testSpec',
+    title: 'Source declared ❌ (missing tests) in TEST-SPEC',
+    help: 'A Source-to-Test Map row declares its source as ❌ — the author has flagged missing tests. Write the tests, then update the row status to ✅.',
+    suppress: null,
+  },
+  TSP002: {
+    validator: 'testSpec',
+    title: 'Source declared ⚠️ (partial coverage) in TEST-SPEC',
+    help: 'A Source-to-Test Map row declares partial coverage for its source. Extend the tests, then update the row status to ✅.',
+    suppress: null,
+  },
+  TSP003: {
+    validator: 'testSpec',
+    title: 'Mapped source file not found on disk',
+    help: 'A Source-to-Test Map row points at a source file that no longer exists — usually a stale entry after a move or delete. Update or remove the row. If the flagged cell is prose rather than a real path, report it as a false positive.',
+    suppress: null,
+  },
+  TSP004: {
+    validator: 'testSpec',
+    title: 'Mapped test file not found on disk',
+    help: 'A Source-to-Test Map row declares a test file that does not exist. Create the test file, or point the row at the actual test path.',
+    suppress: null,
+  },
+  TSP005: {
+    validator: 'testSpec',
+    title: 'E2E journey declared ❌ (missing test)',
+    help: 'A Critical User Journeys / Critical CLI Flows row is marked ❌. Implement the journey test, then mark the row ✅.',
+    suppress: null,
+  },
+  TSP006: {
+    validator: 'testSpec',
+    title: 'E2E journey marked ✅ but test file missing',
+    help: 'A journey row claims ✅ but none of its referenced test paths exist on disk (globs and "(N suites)" annotations are honored). The glyph is a claim, the file is the proof — fix the path in the row or restore the missing test.',
+    suppress: null,
+  },
+  TSP007: {
+    validator: 'testSpec',
+    title: 'No tests found anywhere in the project',
+    help: 'TEST-SPEC.md maps nothing and no tests/ directory, co-located *.test.* files, or vitest/jest config were found. Add tests, then map them in a "## Source-to-Test Map" table so coverage claims stay verifiable.',
+    suppress: null,
+  },
+  DRF001: {
+    validator: 'drift',
+    title: 'DRIFT comment but no drift log file',
+    help: 'Code contains a // DRIFT: comment but the drift log (DRIFT-LOG.md) does not exist, so the deviation is unlogged. Create the drift log — `docguard init` scaffolds it — then record this deviation in it.',
+    suppress: null,
+  },
+  DRF002: {
+    validator: 'drift',
+    title: 'DRIFT comment not logged in DRIFT-LOG.md',
+    help: "A // DRIFT: comment's file has no matching entry in DRIFT-LOG.md. Add an entry naming the file and explaining why the code deviates from docs-canonical.",
+    suppress: null,
+  },
+  TRC001: {
+    validator: 'traceability',
+    title: 'Required canonical doc missing (no traceability)',
+    help: 'A doc listed in requiredFiles.canonical does not exist, so no doc-to-source link can be checked. Create it from a template with `docguard init` (the structure validator flags the missing file too).',
+    suppress: null,
+  },
+  TRC002: {
+    validator: 'traceability',
+    title: 'Unlinked canonical doc (no matching source)',
+    help: 'The doc exists but no source file matches its built-in path patterns. If the implementing code lives in a non-standard location, link it explicitly by adding a `// @doc <DOC-NAME>.md` annotation near the top of a source file that implements the doc.',
+    suppress: '// @doc <DOC-NAME>.md',
+  },
+  TRC003: {
+    validator: 'traceability',
+    title: 'Orphaned doc in docs-canonical/',
+    help: 'A doc exists in docs-canonical/ but is not listed in requiredFiles.canonical, so no validator checks it and it can silently rot. Delete it, or add it to requiredFiles.canonical in .docguard.json so it gets validated.',
+    suppress: null,
+  },
+  TRC004: {
+    validator: 'traceability',
+    title: 'Requirement ID without test coverage',
+    help: 'A requirement ID found in the docs (REQ-/FR-/SC-/T-style) has no matching reference in any test file. Add an `@req <ID>` comment to the test that verifies it. Requirement traceability is opt-in: it only activates once IDs appear in your docs.',
+    suppress: null,
+  },
+  TRC005: {
+    validator: 'traceability',
+    title: 'Orphaned test reference to unknown requirement',
+    help: 'A test references a requirement ID that no doc defines — the test claims to verify something the docs never specified. Remove the stale reference, or add the requirement to the documentation.',
+    suppress: null,
+  },
+  TDO001: {
+    validator: 'todoTracking',
+    title: 'Skipped test without explanation',
+    help: 'A test.skip / it.skip / xit (or similar) has no justification nearby. Add a `// REASON:` comment on the skip line or up to 3 lines above it explaining why the test is skipped (SKIP/NOTE/WHY/TODO/FIXME prefixes also count).',
+    suppress: '// REASON: <why this test is skipped>',
+  },
+  TDO002: {
+    validator: 'todoTracking',
+    title: 'Untracked TODO/FIXME annotation',
+    help: 'A TODO/FIXME/HACK/XXX/TEMP/WORKAROUND comment is not tracked in any tracking doc (ROADMAP.md, CURRENT-STATE.md, TODO.md, BACKLOG.md, or docs-canonical/ equivalents). Track it there with its file location, resolve it, or exclude the path via `todoIgnore` in .docguard.json.',
+    suppress: null,
+  },
+  TDO003: {
+    validator: 'todoTracking',
+    title: 'Additional untracked TODOs elided',
+    help: 'Guard reports only the first 5 untracked TODO/FIXME items to avoid noise; this line counts the remainder. Track or resolve the reported items and re-run guard to surface more, or exclude noisy paths via `todoIgnore` in .docguard.json.',
+    suppress: null,
+  },
+  SCH001: {
+    validator: 'schemaSync',
+    title: 'Database models found but no DATA-MODEL.md',
+    help: 'Schema definitions were detected (Prisma/Drizzle/TypeORM/Sequelize/Knex/Django/Rails) but docs-canonical/DATA-MODEL.md does not exist, so the schema is undocumented. Run `docguard init` to create it, then document the models.',
+    suppress: null,
+  },
+  SCH002: {
+    validator: 'schemaSync',
+    title: 'Model not documented in DATA-MODEL.md',
+    help: 'A model/table found in a schema file does not appear anywhere in DATA-MODEL.md (matching is case-insensitive and singular/plural tolerant). Add it to the Entity Definitions section.',
+    suppress: null,
+  },
+  ARC001: {
+    validator: 'architecture',
+    title: 'Forbidden layer import (layers config)',
+    help: 'A file imports from a layer its own layer may not import, per the `layers` map in .docguard.json. Remove the import or route it through an allowed layer — or update the layers config if the architecture genuinely changed.',
+    suppress: null,
+  },
+  ARC002: {
+    validator: 'architecture',
+    title: 'Circular dependency',
+    help: 'A load-time import cycle was detected between source files. Break it by converting one edge to a dynamic `import()` (runtime imports do not create load-time cycle edges) or by extracting the shared code into a third module both sides import.',
+    suppress: null,
+  },
+  ARC003: {
+    validator: 'architecture',
+    title: 'Layer boundary violation (ARCHITECTURE.md)',
+    help: 'An import crosses a boundary the Layer Boundaries table in docs-canonical/ARCHITECTURE.md forbids. Remove or invert the import — or update the table if the rule changed, so docs and code agree.',
+    suppress: null,
+  },
+  CSY001: {
+    validator: 'canonicalSync',
+    title: 'No surface docs to check',
+    help: "canonical-sync found neither README.md nor AGENTS.md, so DocGuard's own surface-count claims cannot be checked. Add a README.md (this check only runs in the docguard-cli repo).",
+    suppress: null,
+  },
+  CSY002: {
+    validator: 'canonicalSync',
+    title: 'Stale "ships N commands" claim',
+    help: 'A surface doc (README.md/AGENTS.md) claims a command count that does not match the real user-facing command count parsed from --help (or the cli/commands file count). Update the claim.',
+    suppress: null,
+  },
+  CSY003: {
+    validator: 'canonicalSync',
+    title: 'Stale "N validators" claim',
+    help: "A surface doc (README.md/AGENTS.md) states a validator count that does not match guard's actual count (validator files + the inlined Doc Sections validator). Update the claim.",
+    suppress: null,
+  },
+  CSY004: {
+    validator: 'canonicalSync',
+    title: 'Stale architecture-diagram counts',
+    help: 'The Commands (N) / Validators (N) labels in the README mermaid architecture diagram do not match code-truth — the exact drift that went unnoticed for 5 releases. Update the mermaid block.',
+    suppress: null,
+  },
+  SPK001: {
+    validator: 'specKit',
+    title: 'Spec Kit not detected',
+    help: 'No .specify/ directory, specs/ folders, constitution.md, or memory/ was found. Consider adopting spec-driven development with `specify init` (github.com/github/spec-kit), or disable the specKit validator in .docguard.json if it is not wanted.',
+    suppress: null,
+  },
+  SPK002: {
+    validator: 'specKit',
+    title: 'Spec Kit artifacts without .specify/ structure',
+    help: 'Legacy spec/constitution/memory artifacts exist but the standard .specify/ directory is missing. Run `specify init` to create the v3+ standard structure.',
+    suppress: null,
+  },
+  SPK003: {
+    validator: 'specKit',
+    title: 'spec.md quality issue',
+    help: 'A spec.md is missing a mandatory template element: a required section (User Scenarios, Requirements, Success Criteria), FR-/REQ- requirement IDs, or SC- success-criteria IDs. A defect spec can opt into the narrower bugfix shape (Root Cause + Fix required instead) with the inline marker.',
+    suppress: '<!-- docguard:spec-type bugfix -->',
+  },
+  SPK004: {
+    validator: 'specKit',
+    title: 'plan.md quality issue',
+    help: 'A plan.md is missing a mandatory section (Summary, Technical Context, or Project Structure) per spec-kit plan-template.md. Add the section.',
+    suppress: null,
+  },
+  SPK005: {
+    validator: 'specKit',
+    title: 'tasks.md quality issue',
+    help: 'A tasks.md lacks a phased breakdown ("Phase 1:", "Phase 2:", …) or task IDs (T001, T002, …) per spec-kit tasks-template.md.',
+    suppress: null,
+  },
+  SPK006: {
+    validator: 'specKit',
+    title: 'Spec Kit artifact unreadable',
+    help: 'A spec.md/plan.md/tasks.md exists but could not be read. Check file permissions and encoding.',
+    suppress: null,
+  },
+  SPK007: {
+    validator: 'specKit',
+    title: 'Constitution without AGENTS.md',
+    help: 'constitution.md exists but there is no AGENTS.md. AI agents look to AGENTS.md for project rules — create one (e.g. via `docguard init`) and reference the constitution from it.',
+    suppress: null,
+  },
+  XRF001: {
+    validator: 'crossReference',
+    title: 'Broken doc link',
+    help: 'A markdown link between canonical docs points to a file that does not exist (checked relative to the source doc and the project root, URL-decoded). Fix the target path or remove the dead link.',
+    suppress: null,
+  },
+  XRF002: {
+    validator: 'crossReference',
+    title: 'Broken doc anchor',
+    help: 'A `#anchor` link does not match any heading in the target doc (GFM slug rules). When exactly one near-miss heading exists (edit distance ≤ 2) the warning is marked [auto-fixable] and `docguard fix --write` rewrites it; otherwise pick the correct heading by hand.',
+    suppress: null,
+  },
+  GST001: {
+    validator: 'generatedStaleness',
+    title: 'Generated doc stuck in draft',
+    help: 'A docguard:generated doc has sat in `status: draft` beyond the staleness window (default 14 days; `draftStalenessDays` in .docguard.json). Draft the prose (e.g. `/docguard.fix --doc <name>`) and promote it to status:current, or delete the forgotten skeleton.',
+    suppress: null,
+  },
+  GST002: {
+    validator: 'generatedStaleness',
+    title: 'Code-truth section stale',
+    help: "A `source=code` section's body no longer matches what the scanner produces — code changed without `docguard sync --write`, or someone hand-edited a generated section. Run `docguard sync --write` (or `docguard fix --write`), or pin the section if it is intentionally hand-maintained.",
+    suppress: '<!-- docguard:section id=<id> source=code pinned="reason" -->',
+  },
+  SSY001: {
+    validator: 'surfaceSync',
+    title: 'Surface entry missing glob',
+    help: 'A surfaceSync.surfaces entry in .docguard.json has no `glob`, so the code-truth set cannot be discovered and the surface is skipped. Add a glob like "cli/commands/*.mjs".',
+    suppress: null,
+  },
+  SSY002: {
+    validator: 'surfaceSync',
+    title: 'Surface list drift',
+    help: "A doc's table/bullet inventory for a declared surface disagrees with the files its glob discovers — items exist in code but are missing from the doc, or the doc lists items with no file behind them. Update the list, or add intentional aliases/non-public items to the surface's `ignore` list.",
+    suppress: null,
+  },
+  API001: {
+    validator: 'apiSurface',
+    title: 'OpenAPI spec unparseable',
+    help: "The spec declares `paths:` but DocGuard's minimal parser extracted zero endpoints (unsupported YAML: $ref, anchors, folded scalars). Code scanning takes over, but the spec cannot serve as ground truth — validate it with a full OpenAPI linter.",
+    suppress: null,
+  },
+  API002: {
+    validator: 'apiSurface',
+    title: 'OpenAPI specs diverge',
+    help: 'Two or more specs in canonical locations disagree on their endpoint sets; the sourceRoot-nearest spec is treated as authoritative. Regenerate or delete the stale copy so they agree.',
+    suppress: null,
+  },
+  API003: {
+    validator: 'apiSurface',
+    title: 'Spec-declared endpoint has no registered route',
+    help: 'The OpenAPI spec declares an endpoint that no scanned route registers. Either the spec is stale (remove the endpoint) or the route is registered dynamically where the scanner cannot see it — flagged low-confidence for exactly that reason.',
+    suppress: null,
+  },
+  API004: {
+    validator: 'apiSurface',
+    title: 'Documented endpoint not found in code',
+    help: 'docs-canonical/API-REFERENCE.md documents an endpoint absent from the actual surface. Spec-confirmed absences are errors and `docguard fix --write` removes them; code-scan-only absences are low-confidence warnings ([code-scan — verify]) — verify before pruning.',
+    suppress: null,
+  },
+  API005: {
+    validator: 'apiSurface',
+    title: 'Undocumented endpoint in code',
+    help: 'A real endpoint exists in the spec/routes but is missing from docs-canonical/API-REFERENCE.md. Add a documentation block for it.',
+    suppress: null,
+  },
+  DQ001: {
+    validator: 'docQuality',
+    title: 'High passive voice ratio',
+    help: "More than 25% of the doc's prose sentences are passive (configurable via docQuality.passiveVoiceThreshold). Rewrite in active voice — or opt the doc out with the inline marker if passive is intentional (sequence/flow docs).",
+    suppress: '<!-- docguard:quality passive-voice off — your reason -->',
+  },
+  DQ002: {
+    validator: 'docQuality',
+    title: 'High ambiguous pronoun ratio',
+    help: 'Over 15% of words are ambiguous pronouns (it/this/that/they…). Replace them with the specific noun they refer to so statements stay verifiable.',
+    suppress: null,
+  },
+  DQ003: {
+    validator: 'docQuality',
+    title: 'Low atomicity (compound sentences)',
+    help: 'Over 35% of sentences are compound. Split them so each sentence carries one verifiable statement (IEEE 830 §4.1).',
+    suppress: null,
+  },
+  DQ004: {
+    validator: 'docQuality',
+    title: 'Very low Flesch reading ease',
+    help: 'The doc scores below 5/100 — effectively unreadable even for technical material (tech docs typically score 10-30). Shorten sentences and use simpler words.',
+    suppress: null,
+  },
+  DQ005: {
+    validator: 'docQuality',
+    title: 'Reading grade level too high',
+    help: 'Flesch-Kincaid grade above 22 (PhD+). Aim for grade 12-16 for technical docs by simplifying sentence structure and vocabulary.',
+    suppress: null,
+  },
+  DQ006: {
+    validator: 'docQuality',
+    title: 'Average sentence too long',
+    help: 'Average prose sentence exceeds 30 words. Break long sentences up — target 30 words or fewer.',
+    suppress: null,
+  },
+  DQ007: {
+    validator: 'docQuality',
+    title: 'High negation load',
+    help: 'Over 20% of sentences use negation (configurable via docQuality.negationLoadThreshold). Rephrase in positive terms ("must not fail" → "must succeed", IEEE 830 §4.3) — or opt the doc out with the inline marker (security/operational docs legitimately prohibit).',
+    suppress: '<!-- docguard:quality negation-load off — your reason -->',
+  },
+  DQ008: {
+    validator: 'docQuality',
+    title: 'High conditional load',
+    help: 'Over 30% of sentences are conditional (if/unless/when…). Split conditionals into separate, unconditional requirements.',
+    suppress: null,
+  },
 };
 
 /**