docguard-cli 0.31.0 → 0.33.0

package/cli/commands/report.mjs

@@ -0,0 +1,200 @@
+/**
+ * Report Command — Compliance-evidence bundle for audits.
+ *
+ * `docguard report` runs guard + score internally and emits a deterministic
+ * evidence report: who/what/when (git commit, branch, tool version), the
+ * guard verdict per validator, the findings summary, the CDD score with its
+ * ALCOA+ data-integrity attributes, and the mechanical-fix history. An
+ * `integrity` sha256 over the canonical JSON payload makes the bundle
+ * tamper-evident — re-running `docguard report --format json` at the same
+ * commit reproduces the same evidence. The generation timestamp and the
+ * ALCOA+ section are excluded from the hash for that reason (both are
+ * wall-clock-relative; ALCOA's Contemporaneous attribute also depends on
+ * file mtimes, which reset on a fresh clone).
+ *
+ * Report is EVIDENCE, not a gate: it always exits 0. `guard` and `ci` remain
+ * the commands that fail builds. This split matters for auditors — evidence
+ * collection must not change behavior depending on what it observes.
+ *
+ * Output: markdown to stdout by default, `--format json` for the machine
+ * bundle, `--out <file>` to write either format to a file instead.
+ */
+
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve as resolvePath, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { c } from '../shared.mjs';
+import { runGuardInternal } from './guard.mjs';
+import { runScoreInternal, computeAlcoaCompliance } from './score.mjs';
+import { getHeadInfo, isGitRepo } from '../shared-git.mjs';
+import { loadFixMemory } from '../writers/fix-memory.mjs';
+
+const _PKG = JSON.parse(readFileSync(resolvePath(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json'), 'utf-8'));
+const CLI_VERSION = _PKG.version;
+
+/**
+ * Build the evidence payload. Pure gather — no printing, no exit. The
+ * `integrity` hash covers everything EXCEPT `generatedAt` and the hash
+ * itself, so the same tree state always yields the same hash.
+ */
+export function buildReport(projectDir, config) {
+  const guardData = runGuardInternal(projectDir, config);
+  const scoreData = runScoreInternal(projectDir, config);
+  const alcoa = computeAlcoaCompliance(projectDir, config, scoreData.categories);
+  const git = isGitRepo(projectDir) ? getHeadInfo(projectDir) : null;
+  const fixMemory = loadFixMemory(projectDir);
+
+  // Findings grouped by stable code — auditors care about "how many of
+  // which class", not the per-file noise. Codeless findings group as OTHER.
+  const byCode = new Map();
+  for (const f of guardData.findings || []) {
+    const code = f.code || 'OTHER';
+    const entry = byCode.get(code) || { code, severity: f.severity, count: 0, sample: null };
+    entry.count++;
+    if (!entry.sample && f.message) entry.sample = f.message;
+    byCode.set(code, entry);
+  }
+  const findingsSummary = [...byCode.values()].sort((a, b) => b.count - a.count || a.code.localeCompare(b.code));
+
+  const payload = {
+    tool: { name: 'docguard', version: CLI_VERSION },
+    project: {
+      name: config.projectName,
+      profile: config.profile || 'standard',
+      type: config.projectType || 'unknown',
+    },
+    git: git ? { commit: git.commit, branch: git.branch, dirty: git.dirty } : null,
+    guard: {
+      status: guardData.status,
+      passed: guardData.passed,
+      total: guardData.total,
+      errors: guardData.errors,
+      warnings: guardData.warnings,
+      // Audit-critical (H3): evidence must disclose what a committed baseline
+      // is suppressing — "no findings" with a hidden baseline is false green.
+      baselineSuppressed: guardData.baselineSuppressed || 0,
+      validators: (guardData.validators || [])
+        .filter(v => v.status !== 'skipped')
+        .map(v => ({ name: v.name, status: v.status })),
+    },
+    findings: findingsSummary,
+    score: {
+      score: scoreData.score,
+      grade: scoreData.grade,
+      categories: scoreData.categories,
+    },
+    alcoa: {
+      score: alcoa.score,
+      met: alcoa.met,
+      total: alcoa.total,
+      attributes: alcoa.attributes.map(a => ({
+        name: a.name, met: a.met, evidence: a.evidence, gap: a.gap,
+      })),
+    },
+    fixHistory: {
+      entries: fixMemory.entries.length,
+      lastApplied: fixMemory.entries.length
+        ? fixMemory.entries.reduce((max, e) => (e.appliedAt > max ? e.appliedAt : max), '')
+        : null,
+    },
+  };
+
+  // Integrity scope (M3): the hash covers the git-stable sections only. The
+  // ALCOA+ block is excluded because its Contemporaneous attribute derives
+  // from file mtimes vs now — it drifts with wall-clock time and resets on a
+  // fresh clone, which would break "same commit ⇒ same hash".
+  const { alcoa: _unhashed, ...hashable } = payload;
+  const integrity = 'sha256:' + createHash('sha256').update(JSON.stringify(hashable)).digest('hex');
+  return { ...payload, generatedAt: new Date().toISOString(), integrity };
+}
+
+function toMarkdown(r) {
+  const lines = [];
+  const gitLine = r.git
+    ? `commit \`${r.git.commit.slice(0, 12)}\`${r.git.branch ? ` (${r.git.branch})` : ' (detached HEAD)'}${r.git.dirty ? ' — **uncommitted changes present**' : ''}`
+    : 'not a git repository';
+
+  lines.push(`# Documentation Compliance Report — ${r.project.name}`);
+  lines.push('');
+  lines.push(`Generated ${r.generatedAt} by DocGuard v${r.tool.version} · ${gitLine}`);
+  lines.push('');
+  lines.push('## Summary');
+  lines.push('');
+  lines.push('| Metric | Value |');
+  lines.push('|--------|-------|');
+  lines.push(`| CDD Score | ${r.score.score}/100 (${r.score.grade}) |`);
+  lines.push(`| Guard | ${r.guard.status.toUpperCase()} — ${r.guard.passed}/${r.guard.total} checks, ${r.guard.errors} error(s), ${r.guard.warnings} warning(s) |`);
+  if (r.guard.baselineSuppressed > 0) {
+    lines.push(`| Baseline | ⚠️ ${r.guard.baselineSuppressed} pre-existing finding(s) suppressed by \`.docguard.baseline.json\` — not reflected in the counts above |`);
+  }
+  lines.push(`| ALCOA+ data integrity | ${r.alcoa.score}% (${r.alcoa.met}/${r.alcoa.total} attributes) |`);
+  lines.push(`| Profile | ${r.project.profile} (${r.project.type}) |`);
+  lines.push('');
+
+  lines.push('## Validators');
+  lines.push('');
+  lines.push('| Validator | Status |');
+  lines.push('|-----------|--------|');
+  for (const v of r.guard.validators) {
+    const icon = v.status === 'pass' ? '✅' : v.status === 'warn' ? '⚠️' : v.status === 'na' ? '➖' : '❌';
+    lines.push(`| ${v.name} | ${icon} ${v.status} |`);
+  }
+  lines.push('');
+
+  lines.push('## Findings');
+  lines.push('');
+  if (r.findings.length === 0) {
+    lines.push(r.guard.baselineSuppressed > 0
+      ? `No new findings beyond the ${r.guard.baselineSuppressed} suppressed by the committed baseline (run \`docguard guard --no-baseline\` for the full picture).`
+      : 'No findings — documentation matches the implementation at this commit.');
+  } else {
+    lines.push('| Code | Severity | Count | Example |');
+    lines.push('|------|----------|------:|---------|');
+    for (const f of r.findings) {
+      lines.push(`| ${f.code} | ${f.severity} | ${f.count} | ${(f.sample || '').replace(/\|/g, '\\|')} |`);
+    }
+  }
+  lines.push('');
+
+  lines.push('## ALCOA+ Attributes');
+  lines.push('');
+  lines.push('| Attribute | Met | Evidence / Gap |');
+  lines.push('|-----------|-----|----------------|');
+  for (const a of r.alcoa.attributes) {
+    lines.push(`| ${a.name} | ${a.met ? '✅' : '❌'} | ${(a.met ? a.evidence : a.gap) || '—'} |`);
+  }
+  lines.push('');
+
+  lines.push('## Fix History');
+  lines.push('');
+  lines.push(r.fixHistory.entries
+    ? `${r.fixHistory.entries} mechanical fix(es) on record (\`.docguard/fixed.json\`), last applied ${r.fixHistory.lastApplied}.`
+    : 'No mechanical fixes on record.');
+  lines.push('');
+
+  lines.push('## Integrity');
+  lines.push('');
+  lines.push(`\`${r.integrity}\` — sha256 over the canonical JSON payload, excluding \`generatedAt\`, this hash, and the \`alcoa\` section (its Contemporaneous attribute is wall-clock/mtime-relative). Re-run \`docguard report --format json\` at the same commit to reproduce.`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+export function runReport(projectDir, config, flags) {
+  const report = buildReport(projectDir, config);
+  const isJson = flags.format === 'json';
+  const output = isJson ? JSON.stringify(report, null, 2) : toMarkdown(report);
+
+  if (flags.out) {
+    writeFileSync(resolvePath(projectDir, flags.out), output + '\n');
+    // Chrome goes to stderr-style short confirm only in non-JSON mode; in
+    // JSON mode stay silent so scripted callers see nothing unexpected.
+    if (!isJson) console.log(`${c.green}✅ Report written to ${flags.out}${c.reset}`);
+    return report;
+  }
+
+  // Machine/markdown output IS the artifact: write + natural exit (never
+  // console.log + process.exit — >8 KB payloads truncate through a pipe).
+  process.stdout.write(output + '\n');
+  return report;
+}

package/cli/commands/score.mjs

@@ -11,6 +11,7 @@ import { validateSecurity } from '../validators/security.mjs';
 import { runGuardInternal } from './guard.mjs';
 import { extractSemanticClaims } from '../scanners/semantic-claims.mjs';
 import { assessAgentReadability } from '../scanners/agent-readability.mjs';
+import { loadHistory, sparkline } from '../writers/history.mjs';
 
 /**
  * Detect whether the project configures a test runner (the "Check 3" of the
@@ -144,6 +145,10 @@ const WEIGHTS = {
 };
 
 export function runScore(projectDir, config, flags) {
+  // v0.33: `--trend` renders the local score history recorded by `docguard
+  // ci` (.docguard/history.jsonl) instead of recomputing a score.
+  if (flags.trend) return runTrend(projectDir, config, flags);
+
   // v0.16-P1: suppress banner in JSON mode so stdout stays parseable.
   // Was already fixed for guard/diagnose in v0.12; score/trace/diff missed
   // the pattern. Reported on a Python project where `score --format json`
@@ -344,6 +349,52 @@ export function runScore(projectDir, config, flags) {
   console.log(`  ${c.dim}📎 Badge: ![CDD Score](${badgeUrl})${c.reset}\n`);
 }
 
+/**
+ * `score --trend` — render the score trajectory from `.docguard/history.jsonl`
+ * (written by `docguard ci`). Read-only display; exits 0 whether or not
+ * history exists — trend is information, not a gate.
+ */
+function runTrend(projectDir, config, flags) {
+  const isJson = flags.format === 'json';
+  const entries = loadHistory(projectDir, 50);
+
+  if (isJson) {
+    const latest = entries[entries.length - 1] || null;
+    const first = entries[0] || null;
+    process.stdout.write(JSON.stringify({
+      project: config.projectName,
+      entries,
+      latest,
+      delta: latest && first ? latest.score - first.score : null,
+    }, null, 2) + '\n');
+    return;
+  }
+
+  console.log(`${c.bold}📈 DocGuard Score Trend — ${config.projectName}${c.reset}\n`);
+  if (entries.length === 0) {
+    console.log(`  ${c.dim}No history yet. Run ${c.cyan}docguard ci${c.dim} to start recording`);
+    console.log(`  score history to .docguard/history.jsonl (one line per run).${c.reset}\n`);
+    return;
+  }
+
+  const scores = entries.map(e => e.score);
+  const latest = entries[entries.length - 1];
+  const first = entries[0];
+  const delta = latest.score - first.score;
+  const deltaStr = delta > 0 ? `${c.green}+${delta}${c.reset}` : delta < 0 ? `${c.red}${delta}${c.reset}` : '±0';
+
+  console.log(`  ${sparkline(scores)}  ${first.score} → ${c.bold}${latest.score}${c.reset} (${deltaStr}) over ${entries.length} run(s)\n`);
+
+  const recent = entries.slice(-10);
+  for (const e of recent) {
+    const icon = e.status === 'PASS' ? '✅' : e.status === 'WARN' ? '⚠️ ' : '❌';
+    const when = (e.timestamp || '').slice(0, 10);
+    const commit = e.commit ? ` ${c.dim}@${e.commit.slice(0, 7)}${c.reset}` : '';
+    console.log(`  ${icon} ${when}  ${String(e.score).padStart(3)}/100 (${e.grade})${commit}`);
+  }
+  console.log('');
+}
+
 /**
  * Internal scoring — returns data without printing.
  * Used by badge, ci, and other commands that need the score.
@@ -363,8 +414,11 @@ export function runScoreInternal(projectDir, config) {
  *        + Complete, Consistent, Enduring, Available
  *
  * Reference: WHO Technical Report Series, No. 996, 2016, Annex 5
+ *
+ * Exported for `docguard report` — the evidence bundle embeds the same
+ * ALCOA+ table the score display renders, from one computation.
  */
-function computeAlcoaCompliance(projectDir, config, scores) {
+export function computeAlcoaCompliance(projectDir, config, scores) {
   const attributes = [];
 
   // 1. Attributable — Can we trace who wrote/reviewed docs?

package/cli/docguard.mjs

@@ -29,7 +29,7 @@ import { runScore } from './commands/score.mjs';
 import { runDiff } from './commands/diff.mjs';
 import { runAgents } from './commands/agents.mjs';
 import { runGenerate } from './commands/generate.mjs';
-import { runHooks } from './commands/hooks.mjs';
+import { runHooks, runNudgeHook } from './commands/hooks.mjs';
 import { runBadge } from './commands/badge.mjs';
 import { runCI } from './commands/ci.mjs';
 import { runFix } from './commands/fix.mjs';
@@ -45,6 +45,7 @@ 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 { runReport } from './commands/report.mjs';
 import { runMemory } from './commands/memory.mjs';
 import { runDemo } from './commands/demo.mjs';
 import { runAgent } from './commands/agent.mjs';
@@ -80,7 +81,7 @@ ${c.bold}The Daily 5${c.reset} ${c.dim}— what you'll reach for 95% of the time
   ${c.green}guard${c.reset}      Validate against canonical docs (all validators)
   ${c.green}diff${c.reset}       Show gaps between docs and code (add ${c.cyan}--since <ref>${c.reset} for changed-file impact)
   ${c.green}sync${c.reset}       Refresh code-truth doc sections — keeps memory always up to date
-  ${c.green}score${c.reset}      CDD maturity score (0-100; ${c.cyan}--diff${c.reset} for delta between refs)
+  ${c.green}score${c.reset}      CDD maturity score (0-100; ${c.cyan}--diff${c.reset} for delta between refs, ${c.cyan}--trend${c.reset} for history from \`ci\` runs)
 
 ${c.bold}Tools (situational, but day-to-day useful)${c.reset}
   ${c.green}demo${c.reset}       Zero-install tour: see what DocGuard catches against a sample project in 30s
@@ -91,7 +92,9 @@ ${c.bold}Tools (situational, but day-to-day useful)${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}mcp${c.reset}        MCP server over stdio — guard/score/explain/verify/report/diagnose as agent tools
+  ${c.green}report${c.reset}     Compliance-evidence bundle — guard + score + ALCOA+ + integrity hash (${c.cyan}--format json${c.reset}, ${c.cyan}--out <file>${c.reset})
+  ${c.green}ci${c.reset}         Pipeline gate: guard + score in one command (${c.cyan}--threshold <n>${c.reset}, ${c.cyan}--fail-on-warning${c.reset}, ${c.cyan}--format json${c.reset}; records score history)
   ${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.cyan}--features${c.reset} for per-feature adherence)
   ${c.green}upgrade${c.reset}    Migrate ${c.cyan}.docguard.json${c.reset} schema + CLI (${c.cyan}--apply --pr${c.reset} for team-wide PR)
@@ -100,14 +103,14 @@ ${c.bold}Tools (situational, but day-to-day useful)${c.reset}
 ${c.bold}init --with <name>${c.reset} ${c.dim}— optional scaffolders, picked at init time${c.reset}
   ${c.dim}agents${c.reset}     AGENTS.md / CLAUDE.md / .cursor/rules / Copilot instructions
   ${c.dim}hooks${c.reset}      Git pre-commit / pre-push hooks
-  ${c.dim}ci${c.reset}         GitHub Actions / pipeline config
+  ${c.dim}ci${c.reset}         Run the CI gate (guard + score) once, right after init
   ${c.dim}badge${c.reset}      Shields.io score badges for README
   ${c.dim}llms${c.reset}       llms.txt generation
   ${c.dim}publish${c.reset}    External doc-site scaffold (Mintlify) ${c.dim}— experimental${c.reset}
 
 ${c.bold}Deprecation aliases${c.reset} ${c.dim}— still work in v0.20.x with a yellow warning${c.reset}
   ${c.dim}setup${c.reset} → ${c.cyan}init --wizard${c.reset}
-  ${c.dim}agents · hooks · ci · badge · llms · publish${c.reset} → ${c.cyan}init --with <name>${c.reset}
+  ${c.dim}agents · hooks · badge · llms · publish${c.reset} → ${c.cyan}init --with <name>${c.reset}
   ${c.dim}impact${c.reset} → ${c.cyan}diff --since <ref>${c.reset}
   ${c.dim}audit${c.reset} → ${c.green}guard${c.reset} ${c.dim}(permanent — no warning, no removal planned)${c.reset}
   ${c.dim}See docs-implementation/MIGRATION-v0.20.md for the full timeline.${c.reset}
@@ -211,13 +214,15 @@ const COMMAND_HELP = {
   },
   guard: {
     summary: 'Validate code against canonical docs (all validators).',
-    usage: 'docguard guard [--format json] [--changed-only] [--fail-on-warning]',
+    usage: 'docguard guard [--format json|sarif|junit] [--changed-only] [--fail-on-warning]',
     flags: [
-      ['--format json', 'Machine-readable results for CI'],
+      ['--format json', 'Machine-readable results for CI (also: sarif, junit)'],
       ['--changed-only', 'Only validate docs/code touched in the working tree'],
       ['--fail-on-warning', 'Exit non-zero on warnings (strict CI)'],
+      ['--update-baseline', 'Freeze current findings to .docguard.baseline.json — adopt on a legacy repo without a red day one'],
+      ['--no-baseline', 'Ignore the committed baseline for this run (show everything)'],
     ],
-    examples: ['docguard guard', 'docguard guard --format json'],
+    examples: ['docguard guard', 'docguard guard --format json', 'docguard guard --update-baseline'],
   },
   score: {
     summary: 'CDD maturity score (0–100).',
@@ -428,6 +433,17 @@ async function main() {
       // avoid collision with `docguard init --profile <name>`. `--show-timings`
       // is the long form for users who prefer explicit verbs.
       flags.timings = true;
+    } else if (args[i] === '--trend') {
+      flags.trend = true;
+    } else if (args[i] === '--no-history') {
+      flags.noHistory = true;
+    } else if (args[i] === '--update-baseline') {
+      flags.updateBaseline = true;
+    } else if (args[i] === '--no-baseline') {
+      flags.noBaseline = true;
+    } else if (args[i] === '--out' && args[i + 1]) {
+      flags.out = args[i + 1];
+      i++;
     } else if (args[i] === '--quiet' || args[i] === '-q') {
       // v0.16-P5: suppress the banner + ensureSkills decorative line.
       // Useful inside git hooks (every commit prints the banner otherwise)
@@ -495,6 +511,32 @@ async function main() {
       i++;
     } else if (args[i] === '--no-fix') {
       flags.noFix = true;
+    } else if (args[i] === '--no-indirect') {
+      // impact: skip the reverse-import-graph (indirect code→doc) analysis.
+      flags.indirect = false;
+    } else if (args[i] === '--prs') {
+      // impact: open-PR doc-conflict analysis (needs the gh CLI).
+      flags.prs = true;
+    } else if (args[i] === '--claude') {
+      // hooks: install/remove the Claude Code agent nudge hook.
+      flags.claude = true;
+    } else if (args[i] === '--transport' && args[i + 1]) {
+      // mcp: stdio (default) or http (Streamable HTTP, team-shared server).
+      flags.transport = args[i + 1];
+      i++;
+    } else if (args[i] === '--port' && args[i + 1]) {
+      flags.port = args[i + 1];
+      i++;
+    } else if (args[i] === '--host' && args[i + 1]) {
+      flags.host = args[i + 1];
+      i++;
+    } else if (args[i] === '--api-key' && args[i + 1]) {
+      flags.apiKey = args[i + 1];
+      i++;
+    } else if (args[i] === '--path' && args[i + 1]) {
+      // mcp --transport http: HTTP mount path (default /mcp).
+      flags.path = args[i + 1];
+      i++;
     } else if (args[i] === '--signals') {
       flags.signals = true;
     } else if (args[i] === '--debate') {
@@ -541,16 +583,26 @@ async function main() {
   // `generate --plan` (and were already suppressed for `--plan --write`).
   // 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';
+  // v0.33: 'junit' joins for the same reason (GitLab/Jenkins parse stdout XML).
+  const jsonMode = flags.format === 'json' || flags.format === 'sarif' || flags.format === 'junit';
   // `agent` emits a machine task graph (JSON by default) — it must be banner-
   // free and side-effect-free like the other read-only commands.
   // `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';
+  // `nudge-hook`: stdout is the Claude Code hook feedback channel — any banner
+  // byte corrupts the JSON the hook runner parses.
+  // `report`: stdout IS the evidence artifact (markdown or JSON) — banner
+  // bytes would corrupt it for redirection/piping in both formats.
+  const headless = jsonMode || flags.write || flags.checkOnly || flags.changedOnly || flags.quiet || flags.plan || command === 'agent' || command === 'mcp' || command === 'nudge-hook' || command === 'report';
 
   if (!headless) printBanner();
 
   const config = loadConfig(projectDir);
 
+  // `--no-baseline` disables the committed adoption baseline for this run —
+  // threaded through config so guard, ci, report, and mcp all honor it the
+  // same way runGuardInternal sees everything else.
+  if (flags.noBaseline) config.baseline = false;
+
   // Commands that only READ and REPORT — they must never mutate the working
   // tree. Scaffolding (ensureSkills → .agent/.specify, spawning `specify`)
   // belongs to setup/init/generate and the `init --with` family, where the
@@ -570,8 +622,19 @@ async function main() {
     'feedback',
     // verify only reads docs and emits a task list — pure report.
     'verify',
+    // report gathers evidence (guard+score, read-only); --out writes only the
+    // user-named file — it must never scaffold or mutate the tree otherwise.
+    'report',
+    // ci is the pipeline gate — it must never scaffold into the workspace it
+    // gates (review finding H1: bare `docguard ci` in text mode ran
+    // ensureSkills and wrote ~9 files before gating). Its only write is its
+    // own .docguard/history.jsonl, same carve-out as feedback.
+    'ci',
     // mcp serves read-only tools over stdio — scaffolding writes are off-limits.
     'mcp',
+    // nudge-hook runs inside an agent's PostToolUse hook — it may write only
+    // its own .docguard/nudge-state.json throttle file, never scaffold skills.
+    'nudge-hook',
   ]);
 
   // Silent auto-check: install skills/commands if missing. Skip entirely in
@@ -594,7 +657,8 @@ async function main() {
     setup:   { since: '0.20', replacement: 'docguard init --wizard' },
     agents:  { since: '0.20', replacement: 'docguard init --with agents' },
     hooks:   { since: '0.20', replacement: 'docguard init --with hooks' },
-    ci:      { since: '0.20', replacement: 'docguard init --with ci' },
+    // `ci` was deprecated here in v0.20 → un-deprecated in v0.33: it is the
+    // documented pipeline gate (guard + score + threshold), not a scaffolder.
     badge:   { since: '0.20', replacement: 'docguard init --with badge' },
     llms:    { since: '0.20', replacement: 'docguard init --with llms' },
     publish: { since: '0.20', replacement: 'docguard init --with publish' },
@@ -624,7 +688,9 @@ async function main() {
     process.exit(1);
   }
 
-  if (DEPRECATED_COMMANDS[command] && !flags.quiet) {
+  // `hooks --claude` is a first-class new surface (agent nudge hook), not the
+  // deprecated git-hooks alias — no deprecation warning for it.
+  if (DEPRECATED_COMMANDS[command] && !flags.quiet && !(command === 'hooks' && flags.claude)) {
     const { since, replacement } = DEPRECATED_COMMANDS[command];
     console.error(`${c.yellow}⚠ Deprecated since v${since}:${c.reset} ${c.cyan}docguard ${command}${c.reset} → use ${c.cyan}${replacement}${c.reset}`);
     console.error(`${c.dim}  The old form still works in v0.20.x but will be removed in v1.0. See MIGRATION-v0.20.md.${c.reset}`);
@@ -671,13 +737,29 @@ async function main() {
       runAgent(projectDir, config, flags);
       break;
     case 'hooks':
+      if (flags.claude) {
+        // Agent nudge hook (.claude/settings.json) — direct path, no wizard.
+        runHooks(projectDir, config, flags);
+        break;
+      }
       await runInit(projectDir, config, { ...flags, with: ['hooks'], skipPrompts: true });
       break;
+    case 'nudge-hook':
+      // Runtime for the Claude Code PostToolUse hook. stdout is the machine
+      // channel (headless — see the jsonMode/banner gate above).
+      runNudgeHook(projectDir);
+      break;
     case 'badge':
       await runInit(projectDir, config, { ...flags, with: ['badge'], skipPrompts: true });
       break;
     case 'ci':
-      await runInit(projectDir, config, { ...flags, with: ['ci'], skipPrompts: true });
+      // v0.33: restored as a first-class command. The v0.20 deprecation
+      // routed `ci` through runInit --with ci, which (a) scaffolded missing
+      // docs INTO the CI workspace — a validate command mutating the tree —
+      // and (b) printed init chrome into `--format json` stdout, corrupting
+      // it for parsers. A pipeline gate must be read-only and machine-clean,
+      // so it dispatches straight to runCI like guard/score.
+      runCI(projectDir, config, flags);
       break;
     case 'fix':
       runFix(projectDir, config, flags);
@@ -723,6 +805,12 @@ async function main() {
       // drift — the class regex/AST can't see). Read-only.
       runVerify(projectDir, config, flags);
       break;
+    case 'report':
+      // Compliance-evidence bundle (guard + score + ALCOA+ + fix history +
+      // integrity hash). Evidence, not a gate — always exits 0; guard/ci fail
+      // builds. Auditors need evidence collection that never self-censors.
+      runReport(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.

package/cli/findings.mjs

@@ -614,6 +614,12 @@ export const CODES = {
     help: 'A code-element reference in the doc matched source when the doc was last updated, but matches ZERO source instances at HEAD (two-revision check, arXiv 2212.01479). Excludes the two documented false-positive modes (removed-but-config-relevant flags, and symbols whose literal string was deleted while logic remains). Verify and update the reference.',
     suppress: '<!-- docguard:ignore REF001 — still relevant, e.g. user-facing flag -->',
   },
+  REF002: {
+    validator: 'reference-existence',
+    title: 'Code cites an ADR that has no document',
+    help: 'A code comment cites an Architecture Decision Record (e.g. ADR-012) that no ADR document defines — the citation is stale (renumbered, removed) or the ADR was never written. Numbers compare as integers, so ADR-0011 matches ADR-11. IETF RFC citations are deliberately not checked (external registry). Write the ADR, fix the number, or suppress on the citation line.',
+    suppress: '// docguard:ignore REF002 — your reason',
+  },
   APS001: {
     validator: 'api-doc-smells',
     title: 'Bloated API documentation',

package/cli/scanners/agent-readability.mjs

@@ -14,6 +14,7 @@
 
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
+import { loadIgnorePatterns } from '../shared.mjs';
 
 /** chars/4 — the standard rough token estimate; consistency matters more than precision. */
 const estTokens = (s) => Math.ceil(s.length / 4);
@@ -31,9 +32,13 @@ function readIfExists(path) {
 function canonicalDocs(projectDir) {
   const dir = resolve(projectDir, 'docs-canonical');
   if (!existsSync(dir)) return [];
+  // Honor .docguardignore — an excluded doc (e.g. a historical audit) must
+  // not drag down the readability metrics either (same rule as the
+  // semantic-claim extractor, bug-212).
+  const isIgnored = loadIgnorePatterns(projectDir);
   try {
     return readdirSync(dir)
-      .filter(f => f.toLowerCase().endsWith('.md'))
+      .filter(f => f.toLowerCase().endsWith('.md') && !isIgnored(`docs-canonical/${f}`))
       .sort()
       .map(f => ({ name: `docs-canonical/${f}`, content: readIfExists(resolve(dir, f)) }))
       .filter(d => d.content !== null);

package/cli/scanners/semantic-claims.mjs

@@ -23,6 +23,7 @@
 
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { resolve, join } from 'node:path';
+import { loadIgnorePatterns } from '../shared.mjs';
 
 // Numbers are only claims when adjacent to a recognized unit.
 const NUMBER_PATTERNS = [
@@ -49,17 +50,24 @@ const MAX_CLAIMS = 80;
 
 /** Canonical docs + the root docs where limits/counts commonly live. */
 function claimSourceDocs(projectDir) {
+  // Honor .docguardignore: a doc the user explicitly excluded from validation
+  // (e.g. a historical audit full of point-in-time counts) must not feed the
+  // "unverified claims" pool either — it inflated the count and buried the
+  // claims that ARE actionable (bug-212).
+  const isIgnored = loadIgnorePatterns(projectDir);
   const docs = [];
   const canonical = resolve(projectDir, 'docs-canonical');
   if (existsSync(canonical)) {
     try {
       for (const f of readdirSync(canonical)) {
-        if (f.toLowerCase().endsWith('.md')) docs.push(`docs-canonical/${f}`);
+        if (f.toLowerCase().endsWith('.md') && !isIgnored(`docs-canonical/${f}`)) {
+          docs.push(`docs-canonical/${f}`);
+        }
       }
     } catch { /* ignore */ }
   }
   for (const root of ['README.md', 'AGENTS.md']) {
-    if (existsSync(resolve(projectDir, root))) docs.push(root);
+    if (existsSync(resolve(projectDir, root)) && !isIgnored(root)) docs.push(root);
   }
   return docs;
 }

package/cli/shared-git.mjs

@@ -241,6 +241,29 @@ export function lastCommitHash(dir, filePath) {
   }
 }
 
+/**
+ * Resolve HEAD identity for evidence reports: { commit, branch, dirty }.
+ * `branch` is null on a detached HEAD (common in CI checkouts); `dirty` is
+ * true when tracked files have uncommitted changes — evidence consumers need
+ * to know the report may not describe a reproducible tree. Returns null when
+ * the dir isn't a git repo or git is unavailable.
+ */
+export function getHeadInfo(dir) {
+  try {
+    const run = (args) => execFileSync('git', args, {
+      cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'ignore'],
+    }).trim();
+    const commit = run(['rev-parse', 'HEAD']);
+    if (!commit) return null;
+    const branchRaw = run(['rev-parse', '--abbrev-ref', 'HEAD']);
+    const branch = branchRaw === 'HEAD' ? null : branchRaw;
+    const dirty = run(['status', '--porcelain', '--untracked-files=no']) !== '';
+    return { commit, branch, dirty };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Resolve the absolute path to this repo's git hooks directory.
  *

package/cli/validators/architecture.mjs

@@ -143,7 +143,14 @@ function validateConfigLayers(projectDir, config, layers, acc) {
 
 // ── Import Graph Builder ────────────────────────────────────────────────────
 
-function buildImportGraph(projectDir, config) {
+/**
+ * Build the project's JS/TS import graph. Exported for reuse by `impact`
+ * (indirect code→doc analysis walks this graph's reverse edges) — one graph
+ * builder, not two.
+ *
+ * @returns {{files: string[], edges: {from,to,dynamic}[], fileMap: Map<string,string[]>}}
+ */
+export function buildImportGraph(projectDir, config) {
   const graph = { files: [], edges: [], fileMap: new Map() };
 
   const allFiles = getFilesRecursive(projectDir, config, projectDir);