docguard-cli 0.32.0 → 0.33.1

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

@@ -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)
@@ -567,18 +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.
   // `nudge-hook`: stdout is the Claude Code hook feedback channel — any banner
   // byte corrupts the JSON the hook runner parses.
-  const headless = jsonMode || flags.write || flags.checkOnly || flags.changedOnly || flags.quiet || flags.plan || command === 'agent' || command === 'mcp' || command === 'nudge-hook';
+  // `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
@@ -598,6 +622,14 @@ 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
@@ -625,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' },
@@ -720,7 +753,13 @@ async function main() {
       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);
@@ -766,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/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/docs-coverage.mjs

@@ -43,6 +43,11 @@ const COMMON_DOTFILES = new Set([
   '.babelrc', '.browserslistrc', '.stylelintrc',
   '.dockerignore', '.python-version', '.tool-versions', '.ruby-version',
   '.gitkeep', '.keep',
+  // DocGuard's own files — self-explanatory (embedded _comment / schema),
+  // and flagging them creates a warning the moment a team adopts the tool
+  // (e.g. `guard --update-baseline` writing the baseline instantly produced
+  // a DCV001 about the baseline file itself).
+  '.docguard.json', '.docguardignore', '.docguard.baseline.json',
 ]);
 
 // Generated tool artifacts (caches, coverage data, lock-data) that land at the

package/cli/writers/baseline.mjs

@@ -0,0 +1,84 @@
+/**
+ * Adoption Baseline — `.docguard.baseline.json` (repo root, COMMITTED).
+ *
+ * The brownfield-adoption pattern (ESLint/semgrep-style): a legacy repo
+ * freezes its existing findings once (`guard --update-baseline`), commits the
+ * file, and from then on guard/ci gate only NEW drift. Suppressed findings
+ * are counted and displayed — never silently hidden — and the baseline is a
+ * reviewable diff in every PR that updates it.
+ *
+ * Root, not `.docguard/`: the state dir is gitignored, and a baseline only
+ * works if the whole team and CI share it.
+ *
+ * Fingerprints are content-addressed, not line-addressed: `code | location
+ * path (line numbers stripped) | message with digit-runs normalized to #`.
+ * Line numbers churn on every edit and messages embed volatile counts
+ * ("21 commits since…") — both would rot the baseline in a week.
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export const BASELINE_FILE = '.docguard.baseline.json';
+
+/** Stable fingerprint for one finding. */
+export function fingerprintFinding(f) {
+  const code = f.code || 'UNCODED';
+  const path = typeof f.location === 'string' ? f.location.replace(/:\d+$/, '') : '';
+  const msg = String(f.message || '').replace(/\d+/g, '#').replace(/\s+/g, ' ').trim();
+  return createHash('sha256').update(`${code}|${path}|${msg}`).digest('hex').slice(0, 16);
+}
+
+/**
+ * Load the committed baseline as a Map of fingerprint → allowed occurrence
+ * count, or null when the project has none (the common case — zero overhead).
+ *
+ * Occurrence counts matter (review finding H2): two findings with the same
+ * code + file + message shape — e.g. two hardcoded passwords in one file —
+ * share a fingerprint. A count-less set would let one frozen instance
+ * suppress every FUTURE instance of that class in that file, a
+ * security-relevant false negative. With counts, freezing 1 suppresses 1;
+ * a second appearance surfaces and gates.
+ */
+export function loadBaseline(projectDir) {
+  const p = resolve(projectDir, BASELINE_FILE);
+  if (!existsSync(p)) return null;
+  try {
+    const data = JSON.parse(readFileSync(p, 'utf-8'));
+    if (!data || typeof data.fingerprints !== 'object' || data.fingerprints === null) return null;
+    const map = new Map();
+    for (const [fp, n] of Object.entries(data.fingerprints)) {
+      const count = Number.isInteger(n) && n > 0 ? n : 0;
+      if (count > 0) map.set(fp, count);
+    }
+    return map.size > 0 ? map : null;
+  } catch {
+    // A malformed baseline must not silently un-gate CI: treat as absent so
+    // every finding surfaces (fail-open on visibility, fail-closed on hiding).
+    return null;
+  }
+}
+
+/**
+ * Write the baseline from the current findings: fingerprint → occurrence
+ * count, keys sorted so the committed file diffs cleanly. Returns the number
+ * of distinct fingerprints.
+ */
+export function saveBaseline(projectDir, findings) {
+  const counts = {};
+  for (const f of findings) {
+    const fp = fingerprintFinding(f);
+    counts[fp] = (counts[fp] || 0) + 1;
+  }
+  const fingerprints = Object.fromEntries(Object.keys(counts).sort().map(k => [k, counts[k]]));
+  const doc = {
+    _comment: 'DocGuard adoption baseline — existing findings frozen at adoption time (fingerprint → occurrence count). Guard suppresses up to that many instances of each and gates everything new. Regenerate with: docguard guard --update-baseline',
+    version: 2,
+    generatedAt: new Date().toISOString(),
+    count: Object.keys(fingerprints).length,
+    fingerprints,
+  };
+  writeFileSync(resolve(projectDir, BASELINE_FILE), JSON.stringify(doc, null, 2) + '\n');
+  return Object.keys(fingerprints).length;
+}

package/cli/writers/history.mjs

@@ -0,0 +1,82 @@
+/**
+ * Score History — local-first trend memory at `.docguard/history.jsonl`.
+ *
+ * `docguard ci` appends one line per run ({timestamp, commit, score, grade,
+ * errors, warnings, passed, total, status}); `docguard score --trend` reads
+ * it back and renders the trajectory. JSONL because append is the hot path:
+ * one O(1) write per CI run, and a truncated last line (crash mid-write)
+ * corrupts one entry, not the file. The rare trim rewrite goes through a
+ * temp-file + rename so a crash mid-trim can't truncate history; concurrent
+ * appends during a trim window can still lose an entry — acceptable for a
+ * trend log, not a ledger.
+ *
+ * Local-first by design: `.docguard/` is gitignored, so history accumulates
+ * per checkout. In ephemeral CI, persist it across runs with a cache/artifact
+ * step (see CI-RECIPES) — the file format is stable and merge-friendly.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+
+const HISTORY_PATH = '.docguard/history.jsonl';
+
+// Trim trigger: beyond this many entries the file is rewritten keeping the
+// most recent MAX_ENTRIES. Generous — 1000 CI runs of ~150 bytes ≈ 150 KB.
+const MAX_ENTRIES = 1000;
+
+/**
+ * Append one run entry. Silent no-op on failure (read-only checkouts, odd
+ * CI filesystems) — recording history must never fail the pipeline it's
+ * recording.
+ */
+export function appendHistory(projectDir, entry) {
+  try {
+    const p = resolve(projectDir, HISTORY_PATH);
+    mkdirSync(dirname(p), { recursive: true });
+    appendFileSync(p, JSON.stringify(entry) + '\n');
+    // Occasional trim, checked cheaply by size (~200 KB ≫ MAX_ENTRIES rows).
+    // Temp-file + rename: a crash mid-trim leaves the old file intact
+    // instead of a truncated one (L2).
+    if (statSync(p).size > 256 * 1024) {
+      const rows = loadHistory(projectDir, MAX_ENTRIES);
+      const tmp = p + '.tmp';
+      writeFileSync(tmp, rows.map(r => JSON.stringify(r)).join('\n') + '\n');
+      renameSync(tmp, p);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read the last `limit` valid entries, oldest → newest. Malformed lines
+ * (partial writes, hand edits) are skipped, never thrown.
+ */
+export function loadHistory(projectDir, limit = 50) {
+  try {
+    const p = resolve(projectDir, HISTORY_PATH);
+    if (!existsSync(p)) return [];
+    const out = [];
+    for (const line of readFileSync(p, 'utf-8').split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        const e = JSON.parse(line);
+        if (e && typeof e.score === 'number') out.push(e);
+      } catch { /* skip malformed line */ }
+    }
+    return out.slice(-limit);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Unicode sparkline over the score series (0–100 → ▁–█). Pure display.
+ */
+export function sparkline(scores) {
+  const BARS = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'];
+  return scores
+    .map(s => BARS[Math.min(BARS.length - 1, Math.max(0, Math.floor((s / 100) * BARS.length)))])
+    .join('');
+}