docguard-cli 0.28.0 → 0.30.0

package/cli/writers/generate-io.mjs

@@ -0,0 +1,142 @@
+/**
+ * Generate IO — write-path helpers behind `docguard generate`: backup-then-
+ * write file IO, canonical-doc registration in .docguard.json, standards
+ * citation footers, and the surface-confidence heuristic.
+ *
+ * v0.29 split: extracted verbatim from cli/commands/generate.mjs — pure code
+ * motion, zero behavior change.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+
+/**
+ * Create a .bak backup of an existing file before --force overwrites it.
+ * Only backs up if the file exists and has content.
+ */
+export function backupFile(filePath) {
+  if (existsSync(filePath)) {
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+      if (content.trim().length > 0) {
+        copyFileSync(filePath, filePath + '.bak');
+      }
+    } catch { /* backup failure is non-fatal */ }
+  }
+}
+
+/**
+ * Safe write — creates a .bak backup before overwriting existing files.
+ * Call this instead of raw writeFileSync when generating docs.
+ */
+export 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.
+ */
+export 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;
+}
+
+/**
+ * Standards citation map — each doc type maps to its governing industry standard.
+ * Inspired by RAG-grounded standards alignment (Lopez et al., AITPG, IEEE TSE 2026).
+ */
+const STANDARDS_CITATIONS = {
+  'ARCHITECTURE.md': {
+    standard: 'arc42 Template + C4 Model',
+    reference: 'Starke, G. & Brown, S. "arc42 — Architecture communication template." https://arc42.org | Brown, S. "The C4 Model for visualising software architecture." https://c4model.com',
+    sections: '§1 Introduction, §2 Constraints, §3 Context, §4 Solution Strategy, §5 Building Blocks, §6 Runtime, §7 Deployment, §8 Crosscutting, §9 ADRs, §10 Quality, §11 Risks, §12 Glossary',
+  },
+  'DATA-MODEL.md': {
+    standard: 'C4 Component Diagram + Entity-Relationship (Chen notation)',
+    reference: 'Brown, S. "C4 Model — Component diagrams." https://c4model.com | Chen, P. "The Entity-Relationship Model." ACM TODS 1(1), 1976',
+    sections: 'Entities, Relationships, ER Diagrams (Mermaid), Field-level definitions',
+  },
+  'TEST-SPEC.md': {
+    standard: 'ISO/IEC/IEEE 29119-3:2022 — Test Documentation',
+    reference: 'ISO/IEC/IEEE, "Software and systems engineering — Software testing — Part 3: Test documentation." International Standard, 2022',
+    sections: 'Test Categories, Coverage Rules, Test Matrix, Tool Configuration',
+  },
+  'SECURITY.md': {
+    standard: 'OWASP ASVS v4.0 + CWE Top 25',
+    reference: 'OWASP Foundation, "Application Security Verification Standard v4.0." https://owasp.org/asvs | MITRE, "CWE Top 25." https://cwe.mitre.org/top25',
+    sections: 'Authentication, Secrets Management, Access Control, Input Validation',
+  },
+  'ENVIRONMENT.md': {
+    standard: '12-Factor App Methodology',
+    reference: 'Wiggins, A. "The Twelve-Factor App." https://12factor.net',
+    sections: 'Environment Variables, Config Separation, Setup Steps, Provider Configuration',
+  },
+  'API-REFERENCE.md': {
+    standard: 'OpenAPI Specification 3.1',
+    reference: 'OpenAPI Initiative, "OpenAPI Specification v3.1.0." https://spec.openapis.org/oas/v3.1.0',
+    sections: 'Endpoints, Request/Response schemas, Authentication, Error codes',
+  },
+};
+
+/**
+ * Append a standards citation footer to generated doc content.
+ * @param {string} content - The generated markdown content
+ * @param {string} docName - The filename (e.g., 'ARCHITECTURE.md')
+ * @returns {string} Content with citation footer appended
+ */
+export function appendStandardsCitation(content, docName) {
+  const citation = STANDARDS_CITATIONS[docName];
+  if (!citation) return content;
+
+  const footer = `
+---
+
+## Standards Reference
+
+> **Aligned with**: ${citation.standard}
+>
+> **Sections covered**: ${citation.sections}
+>
+> **Reference**: ${citation.reference}
+>
+> *Standards alignment inspired by RAG-grounded generation (Lopez et al., AITPG, IEEE TSE 2026).*
+`;
+
+  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'.
+ */
+export function surfaceConfidence(kind) {
+  return ['webapp', 'api', 'service'].includes(kind) ? 'normal' : 'low';
+}

package/cli/writers/sarif.mjs

@@ -0,0 +1,129 @@
+/**
+ * SARIF 2.1.0 writer — `docguard guard --format sarif`.
+ *
+ * Maps guard's structured findings (stable codes, locations, suggestions) onto
+ * the OASIS SARIF schema so DocGuard results land natively in GitHub Code
+ * Scanning, PR diff annotations, and enterprise SARIF dashboards. The mapping
+ * is possible only because every validator emits findings with stable codes —
+ * codes become reportingDescriptors (rules), findings become results.
+ *
+ * Zero npm dependencies — pure Node.js built-ins.
+ */
+
+import { readFileSync } from 'node:fs';
+import { CODES } from '../findings.mjs';
+
+const SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Sarif/v2.1/os/sarif-schema-2.1.0.json';
+const HELP_URI = 'https://github.com/raccioly/docguard#validators';
+
+function pkgInfo() {
+  try {
+    const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf-8'));
+    return { version: pkg.version || '0.0.0', homepage: pkg.homepage || HELP_URI };
+  } catch {
+    return { version: '0.0.0', homepage: HELP_URI };
+  }
+}
+
+/** severity 'error' → SARIF 'error'; everything else (warn) → 'warning'. */
+function toLevel(severity) {
+  return severity === 'error' ? 'error' : 'warning';
+}
+
+/**
+ * Split a finding location ('path' or 'path:line') into {uri, line}.
+ * A trailing :N is only a line number when N is all digits — Windows drive
+ * letters and URLs with ports never reach here (locations are repo-relative).
+ */
+function parseLocation(location) {
+  if (!location || typeof location !== 'string') return null;
+  const m = location.match(/^(.*?):(\d+)$/);
+  if (m) return { uri: m[1].replace(/\\/g, '/'), line: parseInt(m[2], 10) };
+  return { uri: location.replace(/\\/g, '/'), line: null };
+}
+
+/**
+ * Convert a runGuardInternal() result into a SARIF 2.1.0 log object.
+ *
+ * @param {object} guardData - the guard JSON contract ({findings, validators, ...})
+ * @param {{projectDir?: string}} [opts]
+ * @returns {object} SARIF log, ready for JSON.stringify
+ */
+export function toSarif(guardData, opts = {}) {
+  const { version, homepage } = pkgInfo();
+  const findings = Array.isArray(guardData.findings) ? guardData.findings : [];
+
+  // Validators that crashed (or legacy strings without findings) still need
+  // representation — a SARIF consumer must not read "no results" as "clean"
+  // when a validator errored. Synthesize one result per crash-path string on
+  // validators that emitted NO structured findings.
+  const synthetic = [];
+  for (const v of guardData.validators || []) {
+    if (v.status === 'skipped' || v.status === 'na') continue;
+    if (Array.isArray(v.findings) && v.findings.length > 0) continue;
+    for (const msg of v.errors || []) {
+      synthetic.push({ code: `DOCGUARD-${String(v.key || v.name || 'unknown').toUpperCase()}`, severity: 'error', message: msg, location: null, suggestion: null });
+    }
+    for (const msg of v.warnings || []) {
+      synthetic.push({ code: `DOCGUARD-${String(v.key || v.name || 'unknown').toUpperCase()}`, severity: 'warn', message: msg, location: null, suggestion: null });
+    }
+  }
+  const all = [...findings, ...synthetic];
+
+  // rules[]: one descriptor per distinct code, in first-appearance order.
+  const ruleIndexByCode = new Map();
+  const rules = [];
+  for (const f of all) {
+    if (ruleIndexByCode.has(f.code)) continue;
+    const meta = CODES[f.code];
+    const rule = { id: f.code };
+    if (meta) {
+      rule.name = meta.title;
+      rule.shortDescription = { text: meta.title };
+      rule.fullDescription = { text: meta.help };
+    }
+    rule.helpUri = HELP_URI;
+    rule.defaultConfiguration = { level: toLevel(f.severity) };
+    ruleIndexByCode.set(f.code, rules.length);
+    rules.push(rule);
+  }
+
+  const results = all.map((f) => {
+    const result = {
+      ruleId: f.code,
+      ruleIndex: ruleIndexByCode.get(f.code),
+      level: toLevel(f.severity),
+      message: { text: f.suggestion && f.suggestion.text ? `${f.message}\n→ ${f.suggestion.text}` : f.message },
+    };
+    const loc = parseLocation(f.location);
+    if (loc) {
+      const physicalLocation = { artifactLocation: { uri: loc.uri, uriBaseId: 'SRCROOT' } };
+      if (loc.line) physicalLocation.region = { startLine: loc.line };
+      result.locations = [{ physicalLocation }];
+    }
+    if (f.confidence === 'low') {
+      result.properties = { confidence: 'low', reportable: !!f.reportable };
+    }
+    return result;
+  });
+
+  const run = {
+    tool: {
+      driver: {
+        name: 'DocGuard',
+        informationUri: homepage,
+        version,
+        rules,
+      },
+    },
+    results,
+  };
+
+  if (opts.projectDir) {
+    // file:// URIs require a trailing slash on directory bases (SARIF §3.14.14).
+    const dir = String(opts.projectDir).replace(/\\/g, '/').replace(/\/$/, '');
+    run.originalUriBaseIds = { SRCROOT: { uri: `file://${dir}/` } };
+  }
+
+  return { $schema: SARIF_SCHEMA, version: '2.1.0', runs: [run] };
+}

package/commands/docguard.fix.md

@@ -1,81 +1,84 @@
 ---
-description: AI-driven documentation repair — research codebase, generate content, validate against CDD standards
+description: Find and fix all CDD documentation issues using AI-driven research
 handoffs:
   - label: Verify Fixes
     agent: docguard.guard
     prompt: Run guard to verify all fixes pass
-  - label: Check Score Improvement
+  - label: Check Score
     agent: docguard.score
     prompt: Show score improvement after fixes
 ---
 
-# DocGuard Fix — AI-Assisted Documentation Repair
+# /docguard.fix — Find and Fix CDD Documentation Issues
 
-Generate or repair canonical documentation. DocGuard splits fixes into two kinds:
+You are an AI agent responsible for maintaining documentation quality using DocGuard.
 
-- **Mechanical (deterministic, no AI):** structural edits DocGuard applies itself with
-  `docguard fix --write` — e.g. removing an endpoint from `docs-canonical/API-REFERENCE.md`
-  that the OpenAPI spec confirms no longer exists (its table row + detail block are deleted).
-- **Agent (needs an AI):** content rewrites that require judgment — e.g. replacing an
-  X-Ray prose section with CloudWatch, or writing a new endpoint's request/response block.
-  These use the research-prompt workflow below.
-
-## Apply mechanical fixes first (fast, safe)
+## Step 1: Mechanical fixes first (no AI judgment needed)
 
 ```bash
-npx docguard-cli fix --write          # removes stale documented endpoints; idempotent
+npx docguard-cli fix --write
 ```
-- Only edits docs marked `<!-- docguard:generated true -->` (use `--force` to override).
-- Prints exactly what it removed. Re-run is a no-op if nothing changed.
-- Run `docguard guard` afterward; whatever remains is agent work (below).
 
-## What to do (agent work)
+This deterministically applies the safe fix class: broken doc anchors, stale
+counts bound to code collections, stale version references. Each fix is
+provenance-checked and fail-closed — it never rewrites content whose source of
+truth it cannot verify. Doing this first shrinks the issue list you research.
+
+## Step 2: Assess what remains
 
-1. **Identify what needs fixing** (each issue is tagged `mechanical` or `agent`):
 ```bash
 npx docguard-cli diagnose
 ```
 
-2. **For a specific document**, generate a research-aware fix prompt:
+Parse the output — issues are categorized with AI-ready fix prompts. Every
+finding carries a stable code; run `npx docguard-cli explain <CODE>` whenever
+the right remediation isn't obvious from the message.
+
+If no issues remain, report "All CDD documentation is up to date" and stop.
+
+## Step 3: Fix each issue
+
+| Issue Type | Action |
+|-----------|--------|
+| `missing-file` | Run `npx docguard-cli fix --doc <name>` to generate |
+| `empty-doc` / `partial-doc` | Proceed to Step 4 for codebase research |
+| `missing-config` | Create `.docguard.json` based on project type |
+| `stale-doc` | Update `docguard:last-reviewed` date and content |
+| `quality-issue` | Fix negation language, add missing sections |
+| false positive | Suppress at the site: `// docguard:ignore <CODE>` (with a reason comment), and report it: `npx docguard-cli feedback` |
+
+**Doc wrong vs code wrong:** a doc/code mismatch does not automatically mean
+the doc is stale. Canonical docs are the spec — if the code drifted from a
+documented decision, flag the code (or record the deviation with a
+`// DRIFT: reason` comment + DRIFT-LOG.md entry) instead of silently rewriting
+the doc to match the regression.
+
+## Step 4: Write real content
+
+For each document that needs content:
+
 ```bash
-npx docguard-cli fix --doc architecture
-npx docguard-cli fix --doc security
-npx docguard-cli fix --doc test-spec
-npx docguard-cli fix --doc data-model
-npx docguard-cli fix --doc environment
+npx docguard-cli fix --doc <name>
 ```
 
-3. **Execute the research workflow** from the generated prompt:
-   - Read actual code files (not just filenames)
-   - Map module structure and dependencies
-   - Extract real data structures and schemas
-   - Identify actual auth mechanisms and security patterns
-
-4. **Write documentation with real content**:
-   - Use actual file paths, module names, dependency names
-   - Include working command examples
-   - Use positive language (IEEE 830: "MUST use" not "MUST NOT avoid")
-   - Ensure Flesch-Kincaid grade level 8-10
-
-5. **Include metadata header** in every canonical doc:
-```markdown
-<!-- docguard:version X.X.X -->
-<!-- docguard:status active -->
-<!-- docguard:last-reviewed YYYY-MM-DD -->
-```
+Where `<name>` is: `architecture`, `data-model`, `security`, `test-spec`, `environment`
+
+Read the output carefully — it contains:
+- **RESEARCH STEPS**: Exactly what files to read and commands to run
+- **WRITE THE DOCUMENT**: Expected structure and content for each section
+
+Execute the research steps, then write with REAL project content. No placeholders.
+Never edit inside `<!-- docguard:section ... source=code -->` markers by hand —
+those bodies are regenerated from code by `docguard sync --write`; pin them
+(`pinned="reason"`) if a hand-maintained exception is genuinely needed.
+
+## Step 5: Verify (iterate up to 3 times)
 
-6. **Validate the fix** (iterate up to 3 times):
 ```bash
 npx docguard-cli guard
+npx docguard-cli score
 ```
 
-7. If the project uses Spec Kit, align with spec-kit templates:
-   - `spec.md`: User Scenarios, Requirements (FR-IDs), Success Criteria (SC-IDs)
-   - `plan.md`: Summary, Technical Context, Project Structure
-   - `tasks.md`: Phased breakdown (Phase 1, 2, 3+), Task IDs (T001+)
-
-## Important
-
-- Never use placeholder content — every section must reference real code
-- Back up before overwriting — use `.bak` files or `safeWrite()`
-- Log deviations in DRIFT-LOG.md with `// DRIFT: reason`
+All checks should pass. If any fail, read the output and fix remaining issues.
+Report the final CDD score, plus anything you suppressed (with reasons) or
+reported as a false positive.

package/commands/docguard.guard.md

@@ -1,61 +1,67 @@
 ---
-description: Run DocGuard guard validation — check project documentation against CDD standards with all validators
+description: Run DocGuard guard validation — check all validators and fix any issues
 handoffs:
-  - label: Fix All Issues
+  - label: Fix Issues
     agent: docguard.fix
     prompt: Fix all documentation issues found by guard
-  - label: Deep Review
-    agent: docguard.review
-    prompt: Perform semantic cross-document consistency analysis
   - label: Check Score
     agent: docguard.score
-    prompt: Show CDD maturity score and improvement roadmap
+    prompt: Show CDD maturity score after fixes
 ---
 
-# DocGuard Guard — Documentation Quality Gate
+# /docguard.guard — Validate CDD Compliance
 
-Run the DocGuard CLI to validate all documentation against Canonical-Driven Development standards.
+You are an AI agent enforcing Canonical-Driven Development (CDD) compliance using DocGuard.
 
-## What to do
+## Step 1: Run Guard (machine-readable)
 
-1. **Run the guard command**:
 ```bash
-npx docguard-cli guard
+npx docguard-cli guard --format json
 ```
 
-2. **Parse the output**. Each of the validators reports ✅ (pass), ⚠️ (warning), ❌ (fail), or ➖ (N/A — nothing to validate). **A ➖ N/A is NOT a pass**: it means the validator found nothing to check (e.g. no API-REFERENCE.md, no DB schema, no layer boundaries declared). Don't read N/A as "healthy" — read it as "not assessed".
-
-   | Validator | What It Checks |
-   |-----------|---------------|
-   | Structure | Required CDD files exist |
-   | Doc Sections | Canonical docs have required sections |
-   | Docs-Sync | External doc references are valid |
-   | Drift-Comments | `// DRIFT:` code comments logged in DRIFT-LOG.md |
-   | Changelog | CHANGELOG.md is maintained |
-   | Test-Spec | Tests match TEST-SPEC.md rules |
-   | Environment | Environment documentation |
-   | Security | No hardcoded secrets, SECURITY.md quality |
-   | Architecture | Architecture documentation |
-   | Freshness | Docs updated within commit window |
-   | Traceability | Requirements trace to tests |
-   | Docs-Diff | Doc changes match code changes |
-   | API-Surface | API-REFERENCE.md endpoints match the real API surface (OpenAPI spec / routes) |
-   | Metadata-Sync | Metadata headers are consistent |
-   | Docs-Coverage | All config files documented |
-   | Doc-Quality | Readability, IEEE 830 compliance |
-   | TODO-Tracking | TODOs are tracked |
-   | Schema-Sync | Schema documentation matches code |
-   | Spec-Kit | Spec quality (FR-IDs, sections) |
-   | Metrics-Consistency | Internal counts are accurate |
-
-3. **Triage findings by severity**:
-   - **CRITICAL**: Structure, Security, Test-Spec failures
-   - **HIGH**: Doc Sections, Drift-Comments, Changelog, Traceability, API-Surface (documented-but-absent endpoint) failures
-   - **MEDIUM**: Freshness, Docs-Coverage, Doc-Quality, Metrics-Consistency warnings
-   - **LOW**: TODO-Tracking, Schema-Sync, Spec-Kit, Metadata-Sync warnings
-
-4. For each failing check, provide an **exact fix** — specific file, section, and content to change.
-
-5. After fixing, re-run `npx docguard-cli guard` to verify. Iterate until all checks pass.
-
-6. Exit codes: 0 = all pass, 1 = failures, 2 = warnings only.
+Read the JSON contract — do not parse prose:
+
+| Field | Meaning |
+|-------|---------|
+| `status` | `PASS` / `WARN` / `FAIL` (severity-aware; matches the exit code: 0/2/1) |
+| `findings[]` | Structured issues: `{code, severity, confidence, message, location, suggestion}` |
+| `nextStep` | The single suggested follow-up command (`null` on PASS) |
+| `reportable[]` | Low-confidence findings (possible false positives) — verify before acting |
+| `coverage` | Markdown tier map: `canonical / tracked / ignored / unclassified[]` |
+| `semanticClaims.count` | Documented counts/limits/enums NOT yet verified against code |
+| `validators[]` | Per-validator results, including `na` (nothing to validate ≠ pass) |
+
+## Step 2: Understand each finding before fixing
+
+- Every finding carries a stable code (e.g. `STR001`, `ENV003`, `XRF002`). Run
+  `npx docguard-cli explain <CODE>` for its contract, cause, and remediation.
+- `confidence: "low"` means the scanner itself is unsure — verify against the
+  code before changing anything, and report real false positives with
+  `npx docguard-cli feedback`.
+- A finding's `suggestion` may include a ready-to-run `command` or an inline
+  `pragma`. Prefer those over inventing your own fix.
+
+## Step 3: Fix, suppress, or escalate
+
+1. **Mechanical issues first**: `npx docguard-cli fix --write` applies safe,
+   provenance-checked fixes (broken anchors, stale counts/versions). Never
+   hand-edit what the tool can fix deterministically.
+2. **Prose/content issues**: follow the `/docguard.fix` workflow (research →
+   write real content).
+3. **Genuine false positives**: suppress at the finding site with the code —
+   `// docguard:ignore <CODE>` on (or above) the flagged line — or mark a whole
+   validator not-applicable in a doc:
+   `<!-- docguard:validator <key> n/a — reason -->`. Always include the reason.
+   Never suppress to silence a real issue.
+4. If `semanticClaims.count > 0`, offer to run `npx docguard-cli verify --semantic`
+   and check each extracted claim against the code — a green guard asserts
+   structure, not the truth of documented numbers.
+
+## Step 4: Report
+
+Show the user:
+1. `status` and pass/total, plus anything in `coverage.unclassified` (docs no
+   validator watches — suggest enrolling or ignoring them)
+2. Each finding fixed (by code), each suppressed (with reason), each reported
+   as a false positive
+3. Final score: `npx docguard-cli score`

package/commands/docguard.review.md

@@ -1,53 +1,71 @@
 ---
-description: Cross-document consistency analysis — semantic review of documentation health, accuracy, and alignment with codebase
+description: Review documentation quality — identify drift, coverage gaps, and improvements
 handoffs:
-  - label: Fix Issues Found
+  - label: Fix Issues
     agent: docguard.fix
     prompt: Fix the documentation issues identified in the review
   - label: Run Guard
     agent: docguard.guard
-    prompt: Validate all documentation passes CDD standards
+    prompt: Validate all checks pass after review
 ---
 
-# DocGuard Review — Documentation Quality Analysis
+# /docguard.review — Review Documentation vs Code
 
-Perform comprehensive, read-only analysis of documentation health with semantic cross-document consistency checking.
+You are an AI agent reviewing documentation quality and detecting drift between docs and code.
 
-## What to do
+## Step 1: Run Diagnostics
 
-1. **Run the full diagnostic**:
 ```bash
 npx docguard-cli diagnose
+npx docguard-cli diff
 npx docguard-cli score
 ```
 
-2. **Perform semantic analysis** (beyond what CLI can check):
+Read all output. Identify where documentation no longer matches the codebase.
+Findings carry stable codes — `npx docguard-cli explain <CODE>` when unclear.
 
-   | Analysis Pass | What to Check |
-   |--------------|--------------|
-   | Terminology | Same concepts named consistently across docs |
-   | Architecture ↔ Code | Components listed in ARCHITECTURE.md exist in codebase |
-   | Data Model ↔ Code | Schemas in DATA-MODEL.md match actual implementations |
-   | Test Coverage | Critical flows in TEST-SPEC.md have actual test files |
-   | Security Claims | Auth mechanisms in SECURITY.md match actual code |
-   | Cross-References | Internal doc links resolve to valid targets |
+## Step 2: Verify Documented Claims Against Code
 
-3. **Score each document** on 5 dimensions:
+```bash
+npx docguard-cli verify --semantic
+```
+
+This extracts every checkable claim in the canonical docs — counts, limits,
+rate numbers, retention windows, status enums — as a task list with the nearest
+cited code path. **You perform each verification**: read the cited code, compare
+the value, and report every mismatch with both values. This is the highest-value
+review step; deterministic validators cannot judge these.
+
+## Step 3: Semantic Analysis (Beyond CLI)
+
+For each canonical doc, verify alignment with actual code:
 
-   | Criterion | Weight | What to Evaluate |
-   |-----------|:------:|-----------------|
-   | Completeness | 30% | All mandatory sections present |
-   | Accuracy | 30% | Content matches actual codebase |
-   | Clarity | 20% | Readable, specific, no unexplained jargon |
-   | Currency | 10% | Up-to-date with latest code changes |
-   | Cross-refs | 10% | References are valid and bidirectional |
+| Analysis | What to Check |
+|----------|--------------|
+| Architecture ↔ Code | Components in ARCHITECTURE.md exist as real modules |
+| Data Model ↔ Code | Schemas in DATA-MODEL.md match actual implementations |
+| Security Claims | Auth mechanisms in SECURITY.md match actual code |
+| Test Coverage | Critical flows in TEST-SPEC.md have actual test files |
+| Terminology | Same concepts named consistently across all docs |
 
-4. **Classify findings by severity**:
-   - 🔴 **CRITICAL**: Security claim mismatch, missing mandatory doc, broken architecture reference
-   - 🟠 **HIGH**: Undocumented component, stale content (>5 commits behind), terminology conflict
-   - 🟡 **MEDIUM**: Missing cross-reference, minor coverage gap, readability issue
-   - 🟢 **LOW**: Minor formatting, optional section missing, style inconsistency
+## Step 4: Update Stale Docs
 
-5. **Output a structured report** with findings table, per-document health scores, and priority-ordered recommendations.
+For each stale or drifted document:
+1. **Decide which side is wrong first.** Canonical docs are the spec — if the
+   code regressed from a documented decision, flag the code (or record a
+   `// DRIFT: reason` + DRIFT-LOG.md entry); don't rewrite the doc to match a
+   regression.
+2. Sections inside `<!-- docguard:section ... source=code -->` markers are
+   regenerated — run `npx docguard-cli sync --write` instead of editing by hand.
+3. For hand-maintained sections: read the relevant source, update the specific
+   section, refresh `docguard:last-reviewed` to today.
+4. Add entry to CHANGELOG.md under [Unreleased].
+
+## Step 5: Verify
+
+```bash
+npx docguard-cli guard
+npx docguard-cli score
+```
 
-6. **Do NOT modify files** — this is read-only analysis. Suggest fixes for user approval.
+Report findings, changes made, and the final score.