docguard-cli 0.32.0 → 0.33.0

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('');
+}

package/cli/writers/junit.mjs

@@ -0,0 +1,103 @@
+/**
+ * JUnit XML writer — `docguard guard --format junit`.
+ *
+ * SARIF covers GitHub Code Scanning; JUnit covers everything else an
+ * enterprise runs: GitLab CI (`artifacts:reports:junit`), Jenkins
+ * (`junit` step), Azure DevOps, CircleCI, Bamboo. One testcase per
+ * validator keeps the report readable in those UIs — a failed validator
+ * shows its findings (code + message + location) as the failure body.
+ *
+ * Mapping (deterministic):
+ *   validator error findings         → <failure> (red in every CI)
+ *   validator crashed (fail, no
+ *   structured findings)             → <error> from its string errors (red)
+ *   warn-only validator              → passing testcase + findings in
+ *                                      <system-out> (visible, non-gating)
+ *   skipped / n/a                    → <skipped/>
+ *
+ * Zero npm dependencies — pure string assembly with strict XML escaping.
+ */
+
+function esc(s) {
+  return String(s ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+function findingLine(f) {
+  const code = f.code ? `[${f.code}] ` : '';
+  const loc = f.location ? ` (${f.location})` : '';
+  return `${code}${f.message}${loc}`;
+}
+
+/**
+ * Build the JUnit XML document from runGuardInternal's data.
+ * `data.validators` entries: { name, status, findings? }; `data.findings`
+ * is the flat list with `validator` back-references — we group by the
+ * validator display name via each result's own findings when present,
+ * falling back to the flat list.
+ */
+export function toJUnit(data) {
+  const cases = [];
+  let failures = 0, errorCount = 0, skipped = 0;
+
+  for (const v of data.validators || []) {
+    const vFindings = Array.isArray(v.findings)
+      ? v.findings
+      : (data.findings || []).filter(f => f.validator === v.key || f.validator === v.name);
+    const errors = vFindings.filter(f => f.severity === 'error');
+    const warns = vFindings.filter(f => f.severity !== 'error');
+    const attrs = `name="${esc(v.name)}" classname="docguard.guard"`;
+
+    if (v.status === 'skipped' || v.status === 'na') {
+      skipped++;
+      cases.push(`    <testcase ${attrs}><skipped/></testcase>`);
+    } else if (errors.length > 0) {
+      failures++;
+      const body = errors.map(findingLine).join('\n');
+      cases.push(
+        `    <testcase ${attrs}>\n` +
+        `      <failure message="${esc(errors[0].message)}" type="${esc(errors[0].code || 'docguard')}">${esc(body)}</failure>\n` +
+        `    </testcase>`
+      );
+    } else if (v.status === 'fail') {
+      // A validator that failed WITHOUT structured error findings — the
+      // crash path (guard catches the throw and records string errors only).
+      // This must go red in CI, not render as a passing testcase (M1).
+      errorCount++;
+      const body = (v.errors || []).join('\n') || 'validator failed without structured findings';
+      cases.push(
+        `    <testcase ${attrs}>\n` +
+        `      <error message="${esc((v.errors || [])[0] || 'validator failed')}" type="docguard.crash">${esc(body)}</error>\n` +
+        `    </testcase>`
+      );
+    } else if (warns.length > 0) {
+      const body = warns.map(findingLine).join('\n');
+      cases.push(
+        `    <testcase ${attrs}>\n` +
+        `      <system-out>${esc(body)}</system-out>\n` +
+        `    </testcase>`
+      );
+    } else {
+      cases.push(`    <testcase ${attrs}/>`);
+    }
+  }
+
+  const total = (data.validators || []).length;
+  const suiteAttrs =
+    `name="docguard guard — ${esc(data.project || 'project')}" ` +
+    `tests="${total}" failures="${failures}" errors="${errorCount}" skipped="${skipped}" ` +
+    `timestamp="${esc(data.timestamp || '')}"`;
+
+  return (
+    `<?xml version="1.0" encoding="UTF-8"?>\n` +
+    `<testsuites tests="${total}" failures="${failures}" errors="${errorCount}">\n` +
+    `  <testsuite ${suiteAttrs}>\n` +
+    cases.join('\n') + (cases.length ? '\n' : '') +
+    `  </testsuite>\n` +
+    `</testsuites>`
+  );
+}

package/docs/commands.md

@@ -38,6 +38,17 @@ npx docguard-cli diagnose --format prompt # Raw AI prompt (all issues combined)
 npx docguard-cli guard                   # Text output
 npx docguard-cli guard --format json     # Structured JSON (the stable agent contract)
 npx docguard-cli guard --format sarif    # SARIF 2.1.0 for GitHub Code Scanning
+npx docguard-cli guard --format junit    # JUnit XML for GitLab/Jenkins/Azure DevOps
+npx docguard-cli guard --update-baseline # Freeze current findings (brownfield adoption)
+npx docguard-cli guard --no-baseline     # Ignore the committed baseline this run
+```
+
+**Adoption baseline:** on a legacy repo, `--update-baseline` writes
+`.docguard.baseline.json` (commit it). From then on guard/ci suppress those
+frozen findings — visibly — and gate only new drift. Fingerprints are stable
+across line-number churn and volatile counts, so the baseline doesn't rot.
+
+```bash
 npx docguard-cli guard --verbose         # Show all check details
 npx docguard-cli guard --changed-only    # Pre-commit lite mode (fast subset)
 ```
@@ -181,7 +192,7 @@ never touched without `--force`.
 
 **MCP server over stdio** — DocGuard's read-only core as native agent tools
 (`docguard_guard`, `docguard_score`, `docguard_explain`,
-`docguard_verify_claims`, `docguard_diagnose`).
+`docguard_verify_claims`, `docguard_report`, `docguard_diagnose`).
 
 ```bash
 claude mcp add docguard -- npx docguard-cli mcp
@@ -211,15 +222,32 @@ npx docguard-cli memory --pack     # .docguard/context-pack.md (session-start co
 
 ## DevOps Commands
 
+### `docguard report`
+
+**Compliance-evidence bundle for audits** — guard verdict, CDD score, ALCOA+
+data-integrity attributes, findings grouped by code, and fix history, stamped
+with the git commit and a tamper-evident sha256 integrity hash. Evidence, not
+a gate: always exits 0 (`guard`/`ci` fail builds).
+
+```bash
+npx docguard-cli report                          # markdown to stdout
+npx docguard-cli report --format json            # machine bundle
+npx docguard-cli report --out evidence.md        # write to a file
+```
+
 ### `docguard ci`
 
-**Single command for CI/CD pipelines.** Runs guard + score internally (no subprocess).
+**Single command for CI/CD pipelines.** Runs guard + score internally (no
+subprocess). Read-only and machine-clean: it never scaffolds or mutates the
+workspace it validates. Each run appends one line to `.docguard/history.jsonl`
+so `docguard score --trend` can show the trajectory (opt out: `--no-history`).
 
 ```bash
 npx docguard-cli ci                              # Basic check
 npx docguard-cli ci --threshold 70               # Fail below score 70
 npx docguard-cli ci --threshold 80 --fail-on-warning  # Strict mode
 npx docguard-cli ci --format json                # JSON for GitHub Actions
+npx docguard-cli score --trend                   # Score history from past ci runs
 ```
 
 ### `docguard hooks`

package/docs/configuration.md

@@ -111,6 +111,20 @@ Conventional doc folders (`docs/`, `doc/`, `documentation/`, `guides/`,
 that set with non-standard homes — it never replaces auto-detection. To exclude
 a conventional dir, list it in `.docguardignore`.
 
+## Adoption baseline — `baseline`
+
+When a committed `.docguard.baseline.json` exists (written by
+`docguard guard --update-baseline`), guard/ci suppress the frozen findings
+and gate only new drift. Set `"baseline": false` in `.docguard.json` to
+ignore the file entirely (same as always passing `--no-baseline`):
+
+```json
+{ "baseline": false }
+```
+
+Suppression is always visible in output and in the `baselineSuppressed`
+JSON field — nothing is silently hidden.
+
 ## Muting a validator
 
 Two ways to turn a validator off, for two different intents:

package/docs/faq.md

@@ -123,6 +123,18 @@ Yes — DocGuard ships a template at `templates/ci/github-actions.yml`. Copy it
 
 Only if you install hooks (`docguard hooks`). Without hooks, it's advisory only.
 
+### I ran guard on our legacy repo and got dozens of findings. Now what?
+
+Freeze them and move forward:
+
+```bash
+npx docguard-cli guard --update-baseline   # writes .docguard.baseline.json — commit it
+```
+
+From then on guard/ci pass, suppress the frozen findings **visibly**
+("N pre-existing finding(s) suppressed"), and gate only NEW drift. Burn the
+baseline down at your own pace; `--no-baseline` shows the full picture anytime.
+
 ---
 
 ## Technical