docguard-cli 0.32.0 → 0.33.0

package/PHILOSOPHY.md

@@ -115,6 +115,7 @@ CDD is a practitioner methodology whose patterns align with peer-reviewed resear
 - **Generate → validate → evaluate pipeline** — inspired by the AITPG framework (Lopez et al., IEEE TSE 2026): multi-agent generation grounded in standards produces more comprehensive documentation while staying semantically aligned with expert references.
 - **Calibrated quality evaluation** — DocGuard's HIGH/MEDIUM/LOW labels and multi-signal scoring adapt the CJE framework from TRACE (Lopez et al., IEEE TMLCN 2026).
 - **Standards-grounded generation** — each canonical document maps to a relevant standard (arc42, C4, OWASP ASVS, ISO 29119, OpenAPI, 12-Factor App).
+- **Enforcement over instructions** — a 2026 ETH Zurich study (138 repos, 5,694 agent PRs) found the most common style of agent-instruction file *degrades* agent performance; practitioner reports converge on the same conclusion: written rules are routinely ignored, programmatic checks are respected. CDD's answer is to make the docs machine-verified rather than merely machine-readable.
 
 > **Lead researcher**: [Martin Manuel Lopez](https://github.com/martinmanuel9) · [ORCID 0009-0002-7652-2385](https://orcid.org/0009-0002-7652-2385), University of Arizona
 

package/README.md

@@ -41,6 +41,7 @@
 - [Slash Commands](#-slash-commands)
 - [Examples](#-examples)
 - [Testing](#-testing)
+- [Enterprise Adoption](#-enterprise-adoption)
 - [CI/CD Integration](#%EF%B8%8F-cicd-integration)
 - [What's New](#-whats-new)
 - [File Structure](#-file-structure)
@@ -68,7 +69,7 @@ DocGuard is an official [GitHub Spec Kit](https://github.com/github/spec-kit) co
 
 ```mermaid
 graph TD
-    CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (18)"]
+    CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (20)"]
     Commands --> guard["guard"]
     Commands --> generate["generate"]
     Commands --> score["score"]
@@ -108,6 +109,14 @@ against what the code does, on every commit, with no LLM required. The full
 thesis (and the research behind it) lives in [PHILOSOPHY.md](PHILOSOPHY.md);
 recent feature highlights moved [below](#-whats-new).
 
+The field data backs the enforcement-over-instructions bet: an ETH Zurich
+study across 138 repos / 5,694 agent PRs found the most popular style of
+agent-instruction file *hurts* agent performance, and practitioners keep
+converging on the same lesson — written rules are routinely ignored;
+programmatic checks are what agents (and humans) actually respect. That is
+exactly the layer DocGuard provides: not another instructions file, but the
+validator suite that makes the instructions and docs verifiably true.
+
 ---
 
 ## ⚡ Quick Start
@@ -247,7 +256,7 @@ This installs DocGuard's slash commands (`/docguard.init`, `/docguard.guard`, `/
 
 ## Usage
 
-DocGuard ships **18 commands** (the "Daily 5" + 13 situational tools, including the zero-install `demo` and the `mcp` server). Six additional one-shot scaffolders are accessed via `docguard init --with <name>`. Eight v0.19 commands continue to work as deprecation aliases through v0.20.x — see [MIGRATION-v0.20.md](docs-implementation/MIGRATION-v0.20.md).
+DocGuard ships **20 commands** (the "Daily 5" + 15 situational tools, including the zero-install `demo`, the `mcp` server, and the `ci` pipeline gate). Six additional one-shot scaffolders are accessed via `docguard init --with <name>`. Seven v0.19 commands continue to work as deprecation aliases through v0.20.x — see [MIGRATION-v0.20.md](docs-implementation/MIGRATION-v0.20.md).
 
 **The Daily 5** — what you'll reach for 95% of the time:
 
@@ -274,7 +283,10 @@ DocGuard ships **18 commands** (the "Daily 5" + 13 situational tools, including
 | `verify --semantic` | Extract documented numbers/limits/enums (retention days, rate limits, GSI/role counts, status enums) as a task list for an agent to check against code — the semantic-drift class regex/AST can't see |
 | `verify --instructions` | Audit AGENTS.md/CLAUDE.md themselves for drift: duplicate rules, never-vs-always contradictions, stale file pointers, unknown commands — plus clustered rule pairs as agent judgment tasks |
 | `feedback` | Report likely false positives back to DocGuard — local-first record + a 1-click prefilled, redacted GitHub issue (zero typing) |
-| `mcp` | MCP server — exposes guard/score/explain/verify/diagnose as native tools for Claude, Cursor, and any MCP client. Stdio: `claude mcp add docguard -- npx docguard-cli mcp`. Team-shared HTTP: `docguard mcp --transport http --port 8585` (loopback by default; non-loopback binds require `--api-key`) |
+| `mcp` | MCP server — exposes guard/score/explain/verify/report/diagnose as native tools for Claude, Cursor, and any MCP client. Stdio: `claude mcp add docguard -- npx docguard-cli mcp`. Team-shared HTTP: `docguard mcp --transport http --port 8585` (loopback by default; non-loopback binds require `--api-key`) |
+| `report` | Compliance-evidence bundle for audits — guard verdict + CDD score + ALCOA+ attributes + fix history, stamped with git commit and a tamper-evident sha256 integrity hash (`--format json`, `--out <file>`). Evidence, not a gate: always exits 0 |
+| `ci` | Pipeline gate: guard + score in one command — never scaffolds or touches source; its only write is its own `.docguard/history.jsonl` (opt out: `--no-history`). `--threshold <n>` fails below a score, `--fail-on-warning` for strict mode, `--format json` for parsers |
+| `score --trend` | Score trajectory from recorded `ci` runs — sparkline, delta, and the last 10 runs with commit stamps |
 | `memory` | Per-domain accuracy headline (endpoints / entities / env / tech) |
 | `memory --diff` | Drill into which specific claims don't match code |
 | `memory --pack` | Write `.docguard/context-pack.md` — compact, code-truth-stamped session-start context for AI agents |
@@ -308,6 +320,8 @@ Run them solo (`docguard init --with hooks`) or stacked (`docguard init --with a
 | `--quiet` / `-q` | Suppress banner — for hooks, CI loops, scripts | All |
 | `--format json` | Machine-readable output (clean JSON, no ANSI bleed) | guard, score, diff, trace, diagnose, memory, impact, explain |
 | `--format sarif` | SARIF 2.1.0 output — findings as rules/results for GitHub Code Scanning and SARIF dashboards | guard |
+| `--format junit` | JUnit XML output — one testcase per validator, for GitLab CI (`artifacts:reports:junit`), Jenkins, Azure DevOps, CircleCI | guard |
+| `--update-baseline` | Adopt DocGuard on a legacy repo without a red day one: freeze today's findings into a committed `.docguard.baseline.json`; guard/ci then gate only NEW drift. Suppression is always visible ("N pre-existing finding(s) suppressed"), and `--no-baseline` shows the full picture | guard |
 | `--full` | Generate `llms-full.txt` (full doc bodies inlined) instead of the `llms.txt` link index | llms |
 | `--pack` | Write `.docguard/context-pack.md` — agent session-start context | memory |
 | `--sync` | Regenerate the agent-file family (CLAUDE.md, Copilot, Cursor, …) from AGENTS.md; hash-marked, never touches hand-written files without `--force` | agents |
@@ -563,6 +577,20 @@ DocGuard runs its own `guard`, `score`, `diff`, `diagnose`, and `badge` commands
 
 ---
 
+## 🏢 Enterprise Adoption
+
+Everything runs local or in your CI — no SaaS, no data leaving your infra.
+The pieces that matter at company scale:
+
+| Need | DocGuard answer |
+|------|-----------------|
+| **Adopt on a legacy repo** without a red pipeline on day one | `guard --update-baseline` freezes existing findings into a committed `.docguard.baseline.json`; only NEW drift gates from then on (suppression always visible) |
+| **Audit trail** for compliance reviews | `docguard report` — commit-stamped evidence bundle (guard verdict, findings by code, CDD score, ALCOA+ data-integrity attributes, fix history) with a tamper-evident sha256 integrity hash |
+| **Every CI system**, not just GitHub | `guard --format sarif` (GitHub Code Scanning) · `--format junit` (GitLab, Jenkins, Azure DevOps, CircleCI) · `--format json` (anything else) |
+| **Trajectory, not snapshots** | `docguard ci` records every run to `.docguard/history.jsonl`; `score --trend` shows the sparkline + delta |
+| **AI agents on the team** | MCP server (stdio or team-shared HTTP) exposes guard/score/explain/verify/report/diagnose as read-only tools; `agents --sync` keeps the whole agent-file family drift-proof |
+| **Data-integrity framing auditors know** | ALCOA+ scoring (FDA 21 CFR Part 11 / EMA Annex 11 vocabulary) built into `score` and `report` |
+
 ## ⚙️ CI/CD Integration
 
 > **Full recipes:** see [`docs-canonical/CI-RECIPES.md`](./docs-canonical/CI-RECIPES.md) for guard, auto-fix (commits mechanical fixes back to PRs), nightly sync, score-on-PR, and pre-commit configs.
@@ -631,31 +659,27 @@ Two ready-to-use templates ship with the Spec Kit extension and as standalone fi
 
 ## ✨ What's New
 
-Recent highlights across the v0.16 → v0.19 line:
-
-- **`docguard explain <validator>`** — `docguard explain freshness` prints purpose, rules, common
-  failures, and fix recipes for any of the 27 validators. No need to dig into source.
-- **`docguard memory --diff`** — surface what changed in your canonical docs between two refs
-  (`HEAD~10..HEAD` by default). Great for code review and changelog drafting.
-- **`docguard score --diff`** — see exactly which validators moved the score up or down between
-  two commits. Pinpoints regressions without re-running the full suite by hand.
-- **`docguard upgrade --apply --pr`** — when the config schema bumps, DocGuard migrates
-  `.docguard.json` for you and (optionally) opens a PR with the change.
-- **Language-aware traceability** — both `docguard trace` *and* the guard-time Traceability validator
-  understand Python, Rust, Go, Java, Ruby, and PHP layouts in addition to JS/TS, via a shared pattern
-  set (`cli/shared-trace-patterns.mjs`) so the two never drift apart.
-- **Per-validator severity overrides** — escalate `freshness` to `high` for production repos,
-  demote `doc-quality` to `low` for prototypes. Configurable per-project.
-- **JSON Schema for `.docguard.json`** — IDE autocomplete, in-line docs, and validation via
-  `$schema`. Shipped in the package at `schemas/docguard-config.schema.json`.
-- **Version pin (`docguardVersion` + `--pin`)** — pin the CLI version your project supports so
-  CI fails loudly if someone bumps DocGuard without re-running the suite.
-- **Cross-process plan cache** — repeated runs reuse the validator plan across processes when
-  the working tree hasn't changed. ~30% faster guard runs on typical repos.
-- **Headless-aware banner** — `--quiet`, `--format json`, `--write`, and `--changed-only`
-  automatically suppress the banner so JSON output stays parse-clean.
-- **npm-pack smoke gate** — every release now extracts the actual tarball and runs the CLI
-  end-to-end before publish, catching missing-file regressions.
+Highlights of the current line (v0.29 → v0.33):
+
+- **Adoption baseline** — `guard --update-baseline` freezes a legacy repo's existing findings
+  into a committed `.docguard.baseline.json`; guard/ci then gate only NEW drift, with suppression
+  always visible. Adopt today, burn down at your own pace.
+- **`docguard report`** — commit-stamped compliance-evidence bundle (guard verdict, findings by
+  code, CDD score, ALCOA+ attributes, fix history) with a tamper-evident sha256 integrity hash.
+  Also exposed as the `docguard_report` MCP tool.
+- **Score history + `score --trend`** — `docguard ci` records every run to
+  `.docguard/history.jsonl`; the trend view shows the sparkline and delta over time.
+- **Three machine formats for guard** — `--format json`, `--format sarif` (GitHub Code
+  Scanning), and `--format junit` (GitLab, Jenkins, Azure DevOps, CircleCI).
+- **MCP server, stdio + team HTTP** — guard/score/explain/verify/report/diagnose as read-only
+  agent tools: `claude mcp add docguard -- npx docguard-cli mcp`.
+- **Agent-file family sync** — `agents --sync` treats AGENTS.md as canonical and regenerates
+  CLAUDE.md / `.cursor/rules` / Copilot / Gemini variants with drift-proof source-hash markers.
+- **`verify --semantic` and `verify --instructions`** — extract documented numbers/limits/enums
+  as agent verification tasks; audit the agent-instruction files themselves for contradictions
+  and stale pointers.
+- **`docguard agent`** — one-shot ordered task graph with pre-filled code-truth, collapsing ~10
+  agent round-trips into one call.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 

package/cli/commands/ci.mjs

@@ -6,11 +6,18 @@
  *   0 = All pass, score meets threshold
  *   1 = Guard errors or score below threshold
  *   2 = Guard warnings only
+ *
+ * v0.33: each run appends one line to `.docguard/history.jsonl` (score,
+ * grade, commit, guard counts) so `docguard score --trend` can show the
+ * trajectory. Opt out with `--no-history`. The append is silent-on-failure —
+ * recording history must never fail the pipeline it records.
  */
 
 import { c } from '../shared.mjs';
 import { runGuardInternal } from './guard.mjs';
 import { runScoreInternal } from './score.mjs';
+import { appendHistory } from '../writers/history.mjs';
+import { getHeadInfo, isGitRepo } from '../shared-git.mjs';
 
 export function runCI(projectDir, config, flags) {
   const threshold = parseInt(flags.threshold || '0', 10);
@@ -26,12 +33,41 @@ export function runCI(projectDir, config, flags) {
 
   // ── Run guard (internal — no subprocess) ──
   const guardData = runGuardInternal(projectDir, config);
-  const hasErrors = guardData.errors > 0;
-  const hasWarnings = guardData.warnings > 0;
+  // Severity-aware effective counts (M2): `guard` gates on these, so `ci`
+  // must too — a severity=low demotion or severity=high escalation has to
+  // produce the same verdict from both commands.
+  const hasErrors = guardData.effectiveErrors > 0;
+  const hasWarnings = guardData.effectiveWarnings > 0;
 
   // ── Get score ──
   const scoreData = runScoreInternal(projectDir, config);
 
+  // Status reflects EVERY gate, not just guard (L3): a threshold or
+  // --fail-on-warning failure exits 1 and must not be recorded as PASS in
+  // history or the JSON consumers parse.
+  const thresholdMet = threshold <= 0 || scoreData.score >= threshold;
+  const status =
+    hasErrors || !thresholdMet || (failOnWarning && hasWarnings) ? 'FAIL'
+    : hasWarnings ? 'WARN'
+    : 'PASS';
+
+  // ── Record history (unless opted out) ──
+  if (!flags.noHistory) {
+    const git = isGitRepo(projectDir) ? getHeadInfo(projectDir) : null;
+    appendHistory(projectDir, {
+      timestamp: new Date().toISOString(),
+      commit: git ? git.commit.slice(0, 12) : null,
+      score: scoreData.score,
+      grade: scoreData.grade,
+      errors: guardData.errors,
+      warnings: guardData.warnings,
+      baselineSuppressed: guardData.baselineSuppressed || 0,
+      passed: guardData.passed,
+      total: guardData.total,
+      status,
+    });
+  }
+
   // ── Output ──
   if (isJson) {
     const result = {
@@ -44,14 +80,18 @@ export function runCI(projectDir, config, flags) {
         passed: guardData.passed,
         total: guardData.total,
         status: guardData.status,
+        baselineSuppressed: guardData.baselineSuppressed || 0,
         validators: guardData.validators.filter(v => v.status !== 'skipped'),
       },
       threshold,
-      thresholdMet: threshold <= 0 || scoreData.score >= threshold,
-      status: hasErrors ? 'FAIL' : hasWarnings ? 'WARN' : 'PASS',
+      thresholdMet,
+      status,
       timestamp: new Date().toISOString(),
     };
-    console.log(JSON.stringify(result, null, 2));
+    // Machine output must survive a pipe: stdout.write + natural exit, never
+    // console.log + process.exit (>8 KB payloads truncate mid-flush — same
+    // class as the guard --format json bug fixed in v0.28).
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
   } else {
     // Text output
     const guardStatus = hasErrors
@@ -61,20 +101,19 @@ export function runCI(projectDir, config, flags) {
       : `${c.green}✅ PASS${c.reset}`;
 
     console.log(`  ${c.bold}Guard:${c.reset}  ${guardStatus}  (${guardData.passed}/${guardData.total})`);
+    if (guardData.baselineSuppressed > 0) {
+      console.log(`  ${c.dim}📋 ${guardData.baselineSuppressed} pre-existing finding(s) suppressed by the committed baseline${c.reset}`);
+    }
     console.log(`  ${c.bold}Score:${c.reset}  ${scoreData.score}/100 (${scoreData.grade})`);
 
     if (threshold > 0) {
-      const met = scoreData.score >= threshold;
-      console.log(`  ${c.bold}Threshold:${c.reset}  ${met ? `${c.green}✅ ≥${threshold}` : `${c.red}❌ <${threshold}`}${c.reset}`);
+      console.log(`  ${c.bold}Threshold:${c.reset}  ${thresholdMet ? `${c.green}✅ ≥${threshold}` : `${c.red}❌ <${threshold}`}${c.reset}`);
     }
 
     console.log('');
   }
 
-  // Exit code determination
-  if (hasErrors) process.exit(1);
-  if (threshold > 0 && scoreData.score < threshold) process.exit(1);
-  if (failOnWarning && hasWarnings) process.exit(1);
-  if (hasWarnings) process.exit(2);
-  process.exit(0);
+  // Exit code follows `status` exactly — one derivation, no drift between
+  // what history/JSON record and what the pipeline does.
+  process.exitCode = status === 'FAIL' ? 1 : status === 'WARN' ? 2 : 0;
 }

package/cli/commands/guard.mjs

@@ -16,6 +16,8 @@ import { checkUpgradeStatus } from './upgrade.mjs';
 import { changedFilesSince, isGitRepo } from '../shared-git.mjs';
 import { extractSemanticClaims } from '../scanners/semantic-claims.mjs';
 import { toSarif } from '../writers/sarif.mjs';
+import { toJUnit } from '../writers/junit.mjs';
+import { loadBaseline, saveBaseline, fingerprintFinding, BASELINE_FILE } from '../writers/baseline.mjs';
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { resolve as resolvePath, relative as relativePath } from 'node:path';
 import { fileURLToPath as fp } from 'node:url';
@@ -393,6 +395,42 @@ export function runGuardInternal(projectDir, config) {
     }
   }
 
+  // ── Adoption baseline (v0.33) ──
+  // If the repo committed `.docguard.baseline.json`, findings frozen at
+  // adoption time are suppressed BEFORE any tally — so exit codes, severity
+  // rollups, json/sarif/junit, ci, and report all gate only NEW drift.
+  // Suppression is visible (baselineSuppressed in the payload + a display
+  // note), applies only to findings-backed results (legacy string-only
+  // errors/warnings can't be fingerprinted), and `--no-baseline`
+  // (config.baseline === false) turns it off.
+  let baselineSuppressed = 0;
+  const baselineMap = config.baseline === false ? null : loadBaseline(projectDir);
+  if (baselineMap) {
+    // Occurrence budget: each fingerprint suppresses at most its frozen
+    // count (H2). Validators run in a fixed order, so consumption is
+    // deterministic — the same tree always suppresses the same instances.
+    const remaining = new Map(baselineMap);
+    for (const r of results) {
+      if (!Array.isArray(r.findings) || r.findings.length === 0) continue;
+      if (r.errors.length + r.warnings.length !== r.findings.length) continue;
+      const kept = r.findings.filter(f => {
+        const fp = fingerprintFinding(f);
+        const budget = remaining.get(fp) || 0;
+        if (budget <= 0) return true;
+        remaining.set(fp, budget - 1);
+        return false;
+      });
+      const removed = r.findings.length - kept.length;
+      if (removed === 0) continue;
+      baselineSuppressed += removed;
+      r.findings = kept;
+      r.errors = kept.filter(f => f.severity === 'error').map(f => f.message);
+      r.warnings = kept.filter(f => f.severity !== 'error').map(f => f.message);
+      r.total = r.passed + kept.length;
+      Object.assign(r, classifyResult(r));
+    }
+  }
+
   const activeResults = results.filter(r => r.status !== 'skipped');
   const totalErrors = activeResults.reduce((sum, r) => sum + r.errors.length, 0);
   const totalWarnings = activeResults.reduce((sum, r) => sum + r.warnings.length, 0);
@@ -464,6 +502,7 @@ export function runGuardInternal(projectDir, config) {
     // things they've marked as high-severity.
     effectiveErrors,
     effectiveWarnings,
+    baselineSuppressed,
     coverage,
     semanticClaims,
     validators: results,
@@ -555,6 +594,30 @@ export function runGuard(projectDir, config, flags) {
     console.log(`${c.cyan}⚡ docguard guard --changed-only${c.reset} ${c.dim}(${label})${c.reset}${escalatedNote}\n`);
   }
 
+  // ── `--update-baseline`: freeze the CURRENT full finding set ──
+  // Runs with the baseline disabled so the file captures everything visible
+  // today (updating through an active baseline would only ever shrink it).
+  if (flags.updateBaseline) {
+    // --changed-only rewrites config.validators to the 5-validator lite set;
+    // freezing THAT would silently shrink the committed team baseline to a
+    // subset (L1). Refuse the combination rather than corrupt the file.
+    if (flags.changedOnly) {
+      console.error(`${c.red}✗ --update-baseline cannot be combined with --changed-only — the baseline must freeze the FULL validator set, not the pre-commit lite subset.${c.reset}`);
+      process.exitCode = 1;
+      return;
+    }
+    const fullData = runGuardInternal(projectDir, { ...config, baseline: false });
+    const n = saveBaseline(projectDir, fullData.findings || []);
+    if (flags.format === 'json') {
+      process.stdout.write(JSON.stringify({ written: true, file: BASELINE_FILE, fingerprints: n, findings: (fullData.findings || []).length }, null, 2) + '\n');
+    } else {
+      console.log(`${c.green}✅ Baseline written:${c.reset} ${BASELINE_FILE} (${n} fingerprint(s))`);
+      console.log(`${c.dim}   Commit it. guard/ci now gate only NEW findings; --no-baseline shows everything.${c.reset}`);
+    }
+    process.exitCode = 0;
+    return;
+  }
+
   const data = runGuardInternal(projectDir, config);
 
   // ── SARIF output (2.1.0) ──
@@ -567,6 +630,17 @@ export function runGuard(projectDir, config, flags) {
     return;
   }
 
+  // ── JUnit XML output ──
+  // SARIF is GitHub's language; JUnit is everyone else's (GitLab
+  // artifacts:reports:junit, Jenkins junit step, Azure DevOps, CircleCI).
+  // Exit-code semantics identical to sarif/json.
+  if (flags.format === 'junit') {
+    const xml = toJUnit(data);
+    process.exitCode = data.effectiveErrors > 0 ? 1 : data.effectiveWarnings > 0 ? 2 : 0;
+    process.stdout.write(xml + '\n');
+    return;
+  }
+
   // ── JSON output ──
   if (flags.format === 'json') {
     // Use severity-aware effective counts for exit code; raw counts stay in the JSON
@@ -671,6 +745,12 @@ export function runGuard(projectDir, config, flags) {
     console.log(`  ${c.red}${c.bold}❌ FAIL${c.reset} ${c.red}— ${data.passed}/${data.total} passed, ${data.effectiveErrors} blocking issue(s)${warnSuffix}${c.reset}`);
   }
 
+  // Baseline suppression is always visible — a gate that hides findings
+  // silently is the false-green failure mode this tool exists to prevent.
+  if (data.baselineSuppressed > 0) {
+    console.log(`  ${c.dim}📋 ${data.baselineSuppressed} pre-existing finding(s) suppressed by ${BASELINE_FILE} (--no-baseline to show)${c.reset}`);
+  }
+
   // ── Next steps — every run ends with a suggested action (v0.27) ──
   // The field-report principle: whenever DocGuard calls out an issue it must
   // suggest what to do next; on a clean run it points at the next workflow step

package/cli/commands/mcp.mjs

@@ -27,6 +27,7 @@ import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runGuardInternal } from './guard.mjs';
 import { runScoreInternal } from './score.mjs';
+import { buildReport } from './report.mjs';
 import { loadConfig } from '../config.mjs';
 import { CODES } from '../findings.mjs';
 import { extractSemanticClaims, buildSemanticVerifyTasks } from '../scanners/semantic-claims.mjs';
@@ -110,6 +111,16 @@ const TOOLS = [
     },
     annotations: READONLY_ANNOTATIONS,
   },
+  {
+    name: 'docguard_report',
+    title: 'Compliance-evidence bundle',
+    description: 'Generate the commit-stamped compliance-evidence bundle: guard verdict per validator, findings grouped by stable code, CDD score, ALCOA+ data-integrity attributes, fix history, and a tamper-evident sha256 integrity hash. Evidence, not a gate — it reports state without failing.',
+    inputSchema: {
+      type: 'object',
+      properties: { ...PROJECT_DIR_PROP },
+    },
+    annotations: READONLY_ANNOTATIONS,
+  },
   {
     name: 'docguard_diagnose',
     title: 'Diagnose what to fix',
@@ -169,6 +180,11 @@ const TOOL_HANDLERS = {
     };
   },
 
+  docguard_report(args, defaultDir) {
+    const { dir, config } = resolveTarget(args, defaultDir);
+    return buildReport(dir, config);
+  },
+
   docguard_diagnose(args, defaultDir) {
     const { dir, config } = resolveTarget(args, defaultDir);
     const data = runGuardInternal(dir, config);

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;
+}