docguard-cli 0.31.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)
@@ -62,13 +63,13 @@ DocGuard enforces **Canonical-Driven Development (CDD)** — a methodology where
 
 DocGuard is an official [GitHub Spec Kit](https://github.com/github/spec-kit) community extension. It validates the artifacts that Spec Kit creates, ensuring your specs stay high-quality throughout the development lifecycle.
 
-📖 **[Philosophy](PHILOSOPHY.md)** · 📋 **[CDD Standard](STANDARD.md)** · ⚖️ **[Comparisons](COMPARISONS.md)** · 🗺️ **[Roadmap](ROADMAP.md)**
+📖 **[Philosophy](PHILOSOPHY.md)** · 📋 **[CDD Standard](STANDARD.md)** · ⚖️ **[Comparisons](COMPARISONS.md)** · 🔬 **[Validation](VALIDATION.md)** · 🗺️ **[Roadmap](ROADMAP.md)**
 
 ### Architecture
 
 ```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 over stdio — exposes guard/score/explain/verify/diagnose as native tools for Claude, Cursor, and any MCP client. Setup: `claude mcp add docguard -- npx docguard-cli mcp` |
+| `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 |
@@ -325,6 +339,9 @@ Run them solo (`docguard init --with hooks`) or stacked (`docguard init --with a
 | `--apply` | Actually run the migration | upgrade |
 | `--pr` | Open a PR with the migration | upgrade |
 | `--reverse <file>` | Reverse traceability (code → docs) | trace |
+| `--no-indirect` | Skip the reverse-import-graph analysis (docs about modules that import a changed file) | impact, diff --since |
+| `--prs` | Open-PR doc-conflict analysis — two PRs impacting the same canonical doc = merge-order risk (needs the `gh` CLI) | impact |
+| `--transport http` `--port` `--host` `--api-key` `--path` | Serve MCP over Streamable HTTP instead of stdio (team-shared server; loopback-only unless an api-key is set) | mcp |
 | `--history` | Show fix audit log | fix |
 
 ### Example Output
@@ -383,7 +400,7 @@ DocGuard runs **27 automated validators** on every `guard` check. Every one is *
 | 17 | **TODO-Tracking** | Untracked TODOs/FIXMEs and skipped tests (skips test files by default) | ✅ On |
 | 18 | **Schema-Sync** | Database models documented in DATA-MODEL.md | ✅ On |
 | 19 | **Spec-Kit** | Spec quality validation (FR-IDs, mandatory sections, phased tasks) | ✅ On |
-| 20 | **Cross-Reference** | Internal markdown links + anchors resolve (with "did you mean?" hints) | ✅ On |
+| 20 | **Cross-Reference** | Internal markdown links + anchors resolve (with "did you mean?" hints); Obsidian wikilinks validated when the repo uses them as file links (`.obsidian` present or a target resolves) | ✅ On |
 | 21 | **Generated-Staleness** | `source=code` sections match scanner output; `status: draft` doc age | ✅ On |
 | 22 | **Canonical-Sync** | DocGuard's own README count claims match code-truth (DocGuard repo only — N/A elsewhere) | ✅ On |
 | 23 | **Metrics-Consistency** | Hardcoded numbers match actual counts | ✅ On |
@@ -450,6 +467,19 @@ DocGuard works with **every major AI coding agent**. All canonical docs are plai
 | Google Gemini CLI | ✅ | `docguard agents --agent gemini` |
 | Kiro (AWS) | ✅ | — |
 
+### Always-on nudge hook (Claude Code)
+
+```bash
+docguard hooks --claude            # install   (remove: docguard hooks --claude --remove)
+```
+
+Registers a `PostToolUse` hook in the project's `.claude/settings.json`. After the
+agent edits a canonical doc it is nudged to run `docguard guard --changed-only`;
+after it edits a code file the docs reference, it is nudged toward `docguard impact`.
+Merge-safe (only DocGuard's own entry is ever added/removed), throttled to one nudge
+per file per 30 minutes, and the hook runtime can never break a session (errors are
+silent by contract). Explicit opt-in — `init` never installs it for you.
+
 ---
 
 ## ⚡ Slash Commands
@@ -547,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.
@@ -615,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/hooks.mjs

@@ -3,7 +3,7 @@
  * Creates git hooks that run guard/score before commits.
  */
 
-import { existsSync, writeFileSync, mkdirSync, chmodSync, readFileSync, unlinkSync } from 'node:fs';
+import { existsSync, writeFileSync, mkdirSync, chmodSync, readFileSync, unlinkSync, readdirSync } from 'node:fs';
 
 // v0.16-P3: managed-block markers. Letting users extend the hook with their
 // own commands (data-file guards, lint checks, etc.) without us clobbering
@@ -54,7 +54,7 @@ function spliceManagedBlock(existing, newBody) {
   const bodyNoShebang = newBody.replace(/^#!.*\n/, '');
   return `${before}${BEGIN_MARKER}\n${bodyNoShebang.replace(/\n+$/, '')}\n${END_MARKER}${after}`;
 }
-import { resolve } from 'node:path';
+import { resolve, relative, basename } from 'node:path';
 import { c } from '../shared.mjs';
 import { getHooksDir } from '../shared-git.mjs';
 
@@ -217,6 +217,15 @@ export function runHooks(projectDir, config, flags) {
   console.log(`${c.bold}🪝 DocGuard Hooks — ${config.projectName}${c.reset}`);
   console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
 
+  // ── Claude Code agent nudge: `docguard hooks --claude` ──
+  // Separate path from git hooks: it edits .claude/settings.json, needs no
+  // git repo, and is explicitly opt-in (writing agent config unasked is a
+  // trust break — same class as the ensureSkills READ_ONLY_COMMANDS rule).
+  if (flags.claude) {
+    installClaudeNudge(projectDir, { remove: !!flags.remove });
+    return;
+  }
+
   // Resolve the real hooks dir via git — NOT `<projectDir>/.git/hooks`, which
   // is wrong inside a linked worktree (where `.git` is a file, not a dir) and
   // ignores a custom core.hooksPath.
@@ -337,3 +346,159 @@ export function runHooks(projectDir, config, flags) {
 
   console.log('');
 }
+
+// ── Claude Code agent nudge ─────────────────────────────────────────────────
+//
+// `docguard hooks --claude` registers a PostToolUse hook in the PROJECT's
+// .claude/settings.json. After the agent edits a canonical doc (or a code
+// file the docs reference), the hook nudges it toward the right DocGuard
+// command — the graphify "query-first hook" distribution pattern, pointed at
+// doc integrity instead of graph queries.
+//
+// Trust rules:
+//   - Explicit opt-in only (never installed by ensureSkills/init).
+//   - Merge-safe: parses the existing settings.json and adds/removes ONLY the
+//     entry whose command contains the NUDGE_HOOK_COMMAND marker. A file that
+//     doesn't parse is never touched.
+//   - The runtime (`docguard nudge-hook`) is throttled and can never break an
+//     agent session: any internal error exits 0 with no output.
+
+const NUDGE_HOOK_COMMAND = 'docguard nudge-hook';
+const NUDGE_THROTTLE_MS = 30 * 60 * 1000; // one nudge per file per 30 min
+const NUDGE_STATE_PATH = '.docguard/nudge-state.json';
+const NUDGE_CODE_EXT = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|cs|swift)$/;
+const NUDGE_AGENT_FILES = new Set(['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']);
+
+function isOurNudgeGroup(group) {
+  return Array.isArray(group?.hooks) &&
+    group.hooks.some(h => typeof h?.command === 'string' && h.command.includes(NUDGE_HOOK_COMMAND));
+}
+
+export function installClaudeNudge(projectDir, { remove = false } = {}) {
+  const settingsDir = resolve(projectDir, '.claude');
+  const settingsPath = resolve(settingsDir, 'settings.json');
+
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    } catch {
+      console.log(`  ${c.red}❌ .claude/settings.json exists but is not valid JSON — refusing to touch it.${c.reset}`);
+      console.log(`  ${c.dim}Fix the file, then re-run docguard hooks --claude.${c.reset}\n`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  const groups = Array.isArray(settings.hooks?.PostToolUse) ? settings.hooks.PostToolUse : [];
+  const present = groups.some(isOurNudgeGroup);
+
+  if (remove) {
+    if (!present) {
+      console.log(`  ${c.dim}⏭️  No DocGuard nudge hook found in .claude/settings.json — nothing to remove.${c.reset}\n`);
+      return;
+    }
+    settings.hooks.PostToolUse = groups.filter(g => !isOurNudgeGroup(g));
+    if (settings.hooks.PostToolUse.length === 0) delete settings.hooks.PostToolUse;
+    if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+    console.log(`  ${c.yellow}🗑️  Removed the DocGuard nudge hook from .claude/settings.json${c.reset} ${c.dim}(everything else preserved)${c.reset}\n`);
+    return;
+  }
+
+  if (present) {
+    console.log(`  ${c.green}✅ DocGuard nudge hook already installed${c.reset} ${c.dim}(.claude/settings.json — idempotent)${c.reset}\n`);
+    return;
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.PostToolUse)) settings.hooks.PostToolUse = [];
+  settings.hooks.PostToolUse.push({
+    matcher: 'Edit|Write|MultiEdit',
+    hooks: [{ type: 'command', command: NUDGE_HOOK_COMMAND }],
+  });
+
+  if (!existsSync(settingsDir)) mkdirSync(settingsDir, { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+  console.log(`  ${c.green}✅ Installed the DocGuard nudge hook${c.reset} → .claude/settings.json (PostToolUse)`);
+  console.log(`  ${c.dim}After an agent edits a canonical doc (or code the docs reference), it is${c.reset}`);
+  console.log(`  ${c.dim}nudged toward docguard guard --changed-only / docguard impact.${c.reset}`);
+  console.log(`  ${c.dim}Throttled: one nudge per file per 30 minutes. Remove: docguard hooks --claude --remove${c.reset}\n`);
+}
+
+/**
+ * Runtime for the PostToolUse hook (`docguard nudge-hook`). Reads the Claude
+ * Code hook payload from stdin, classifies the edited file, and emits a
+ * `{"decision":"block","reason":…}` nudge on stdout when — and only when —
+ * DocGuard has something specific to say. stdout is the machine channel:
+ * nothing else may be printed. Errors NEVER propagate (exit 0, silent) — a
+ * broken nudge must not degrade the agent session.
+ */
+export function runNudgeHook(projectDir) {
+  try {
+    const payload = JSON.parse(readFileSync(0, 'utf-8'));
+    const toolInput = payload.tool_input || payload.toolInput || {};
+    const filePath = toolInput.file_path || toolInput.filePath;
+    if (!filePath) return;
+
+    const rel = relative(projectDir, resolve(projectDir, filePath)).replace(/\\/g, '/');
+    if (!rel || rel.startsWith('..')) return;
+
+    let reason = null;
+    const base = basename(rel);
+    const isCanonicalDoc =
+      (rel.startsWith('docs-canonical/') && rel.endsWith('.md')) ||
+      (NUDGE_AGENT_FILES.has(base) && !rel.includes('/'));
+
+    if (isCanonicalDoc) {
+      reason = `DocGuard: you edited ${rel} — a canonical/agent doc that gates this repo. ` +
+        `Before finishing, run \`docguard guard --changed-only\` to confirm links, anchors, and count claims still hold.`;
+    } else if (NUDGE_CODE_EXT.test(rel)) {
+      const referencingDocs = docsReferencingFile(projectDir, base);
+      if (referencingDocs.length > 0) {
+        reason = `DocGuard: ${referencingDocs.slice(0, 3).join(', ')} reference${referencingDocs.length === 1 ? 's' : ''} ` +
+          `\`${base}\` — after your edits, run \`docguard impact\` to see which doc sections to re-read or update.`;
+      }
+    }
+    if (!reason) return;
+
+    // Throttle per file — iterative edits must not spam the agent.
+    const statePath = resolve(projectDir, NUDGE_STATE_PATH);
+    let state = {};
+    try { state = JSON.parse(readFileSync(statePath, 'utf-8')); } catch { /* first run */ }
+    const now = Date.now();
+    if (state[rel] && now - state[rel] < NUDGE_THROTTLE_MS) return;
+    state[rel] = now;
+    try {
+      mkdirSync(resolve(projectDir, '.docguard'), { recursive: true });
+      writeFileSync(statePath, JSON.stringify(state, null, 2) + '\n', 'utf-8');
+    } catch { /* state is best-effort; still nudge */ }
+
+    process.stdout.write(JSON.stringify({ decision: 'block', reason }) + '\n');
+  } catch {
+    // Silent by contract.
+  }
+}
+
+/** Which canonical/agent docs mention this basename? Cheap line scan. */
+function docsReferencingFile(projectDir, base) {
+  const docs = [];
+  const check = (name, full) => {
+    try {
+      if (readFileSync(full, 'utf-8').includes(base)) docs.push(name);
+    } catch { /* unreadable */ }
+  };
+  const dir = resolve(projectDir, 'docs-canonical');
+  if (existsSync(dir)) {
+    try {
+      for (const f of readdirSync(dir)) {
+        if (f.endsWith('.md')) check(f, resolve(dir, f));
+      }
+    } catch { /* unreadable dir */ }
+  }
+  for (const a of NUDGE_AGENT_FILES) {
+    const p = resolve(projectDir, a);
+    if (existsSync(p)) check(a, p);
+  }
+  return docs;
+}