docguard-cli 0.32.0 → 0.33.1

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/PRIVACY.md

@@ -0,0 +1,45 @@
+# Privacy Policy — DocGuard
+
+**Effective: 2026-07-16**
+
+DocGuard is a local-first command-line tool. This policy is short because the
+honest answer is short: **DocGuard collects nothing.**
+
+## What DocGuard does with your data
+
+- **All analysis runs locally.** Validators, scoring, reports, the MCP server —
+  everything reads files on your machine and writes output to your machine.
+  Nothing is uploaded, sampled, or "improved" with your code or docs.
+- **No telemetry, no analytics, no crash reporting.** There is no phone-home
+  code path. The deterministic core makes no network calls at all.
+- **No accounts.** DocGuard has no sign-up, no API keys of its own, and no
+  server-side component operated by us.
+
+## The explicit, user-initiated exceptions
+
+Three commands can *prepare* outbound actions — each is opt-in, visible, and
+executed by you or your own tooling, never silently by DocGuard:
+
+| Command | What happens |
+|---------|--------------|
+| `docguard feedback` | Builds a **prefilled GitHub issue URL** (redacted and length-capped) and saves a local record. Nothing is sent unless you open the URL and submit it yourself. |
+| `docguard upgrade --pr` / `impact --prs` | Shell out to **your** locally-authenticated `gh` CLI to interact with **your** repositories. DocGuard never holds credentials. |
+| `docguard mcp --transport http` | Serves read-only tools over HTTP. Binds to loopback by default; binding a non-loopback address **refuses to start** without an `--api-key`. |
+
+## Data written to disk (yours, locally)
+
+State lives under `.docguard/` in your repo (fix history, score history,
+caches) and `.docguard.baseline.json` if you create one. All of it is plain
+text, in your repository, under your version control — delete it any time.
+
+## Dependencies
+
+One pinned runtime dependency (`@babel/parser`). The npm package is published
+from GitHub Actions with provenance attestation, so you can verify the tarball
+was built from this repository.
+
+## Changes & contact
+
+Changes to this policy land in this file with a dated entry in
+[CHANGELOG.md](CHANGELOG.md). Questions: open an issue at
+<https://github.com/raccioly/docguard/issues> (see [SUPPORT.md](SUPPORT.md)).

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 |
@@ -440,6 +454,15 @@ DocGuard ships **18 professional templates** with metadata, badges, and revision
 
 ## 🤖 AI Agent Support
 
+### One-click MCP install
+
+[![Add to Cursor](https://img.shields.io/badge/Cursor-Add_MCP_Server-000000?logo=cursor)](cursor://anysphere.cursor-deeplink/mcp/install?name=docguard&config=eyJjb21tYW5kIjogIm5weCIsICJhcmdzIjogWyIteSIsICJkb2NndWFyZC1jbGkiLCAibWNwIl19)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP_Server-0098FF?logo=githubcopilot)](vscode:mcp/install?%7B%22name%22%3A%22docguard%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22docguard-cli%22%2C%22mcp%22%5D%7D)
+
+- **Claude Code**: `claude mcp add docguard -- npx docguard-cli mcp`
+- **Claude Desktop**: download `docguard-v<version>.mcpb` from the [latest release](https://github.com/raccioly/docguard/releases/latest) and drag it into Settings → Extensions — you'll be asked which project folder to analyze. No npm, no JSON editing.
+- **Anything MCP**: DocGuard is a verified namespace on the [official MCP registry](https://registry.modelcontextprotocol.io/v0/servers?search=docguard) (`io.github.raccioly/docguard`).
+
 DocGuard works with **every major AI coding agent**. All canonical docs are plain markdown — no vendor lock-in.
 
 | Agent | Compatibility | Auto-Generate Config |
@@ -563,6 +586,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 +668,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.
 
@@ -745,6 +778,13 @@ See [CONTRIBUTING.md](CONTRIBUTING.md#research--academic-credits) for full citat
 
 ---
 
+## 🔒 Privacy & Supply Chain
+
+DocGuard is local-first: no telemetry, no analytics, no phone-home — the full
+(short) policy is in [PRIVACY.md](PRIVACY.md). npm releases are published with
+[provenance attestation](https://docs.npmjs.com/generating-provenance-statements),
+so you can verify each tarball was built by GitHub Actions from this repository.
+
 ## 📄 License
 
 [MIT](LICENSE) — Free to use, modify, and distribute.

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);