docguard-cli 0.32.0 → 0.33.1

package/cli/writers/junit.mjs

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

package/docs/commands.md

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

package/docs/configuration.md

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

package/docs/faq.md

@@ -119,10 +119,41 @@ Exit code 0 = pass, 1 = fail. Use `--threshold` to set minimum score.
 
 Yes — DocGuard ships a template at `templates/ci/github-actions.yml`. Copy it to `.github/workflows/` or use the reusable action in `action.yml`.
 
+### Claude (or my AI agent) says DocGuard is "unknown" and wants a legitimacy check. Why?
+
+That's the agent's default posture toward **any** third-party MCP server or
+npx package — MCP servers run code with your permissions, so unknown ones get
+a trust prompt. It's not a DocGuard-specific flag. What DocGuard provides so
+the check can pass:
+
+- **npm provenance** — releases are signed by GitHub Actions (Sigstore), so
+  the tarball is verifiably built from this repository.
+- **Official MCP registry** — `io.github.raccioly/docguard` is a verified
+  namespace at registry.modelcontextprotocol.io.
+- **Read-only annotations** — every MCP tool declares `readOnlyHint`; the
+  server never writes or reaches the network.
+- **[PRIVACY.md](../PRIVACY.md)** — no telemetry, no data collection.
+
+To stop the prompt on your own machines: approve with "Always allow", or
+pre-trust it for a whole team via a project-scoped `.mcp.json` /
+enterprise managed-settings allowlist.
+
 ### Does DocGuard block commits?
 
 Only if you install hooks (`docguard hooks`). Without hooks, it's advisory only.
 
+### I ran guard on our legacy repo and got dozens of findings. Now what?
+
+Freeze them and move forward:
+
+```bash
+npx docguard-cli guard --update-baseline   # writes .docguard.baseline.json — commit it
+```
+
+From then on guard/ci pass, suppress the frozen findings **visibly**
+("N pre-existing finding(s) suppressed"), and gate only NEW drift. Burn the
+baseline down at your own pace; `--no-baseline` shows the full picture anytime.
+
 ---
 
 ## Technical

package/extensions/spec-kit-docguard/extension.yml

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.32.0"
+  version: "0.33.1"
   description: "Canonical-Driven Development enforcement as a true spec-kit extension. LLM-first design with automated validators, 4 AI behavior skills, spec-kit skill chaining, and workflow hooks. One pinned runtime dependency (@babel/parser); pure Node.js otherwise."
   author: "Ricardo Accioly"
   repository: "https://github.com/raccioly/docguard"

package/extensions/spec-kit-docguard/skills/docguard-fix/SKILL.md

@@ -6,10 +6,10 @@ description: AI-driven documentation repair with structured research workflow, t
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.32.0
+  version: 0.33.1
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.32.0 -->
+<!-- docguard:version: 0.33.1 -->
 
 # DocGuard Fix Skill
 

package/extensions/spec-kit-docguard/skills/docguard-guard/SKILL.md

@@ -7,10 +7,10 @@ description: Run DocGuard guard validation against Canonical-Driven Development
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.32.0
+  version: 0.33.1
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.32.0 -->
+<!-- docguard:version: 0.33.1 -->
 
 # DocGuard Guard Skill
 

package/extensions/spec-kit-docguard/skills/docguard-review/SKILL.md

@@ -6,10 +6,10 @@ description: Cross-document consistency analysis and quality assessment. Perform
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.32.0
+  version: 0.33.1
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.32.0 -->
+<!-- docguard:version: 0.33.1 -->
 
 # DocGuard Review Skill
 

package/extensions/spec-kit-docguard/skills/docguard-score/SKILL.md

@@ -6,10 +6,10 @@ description: CDD maturity assessment with category-aware improvement roadmap. Ru
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.32.0
+  version: 0.33.1
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.32.0 -->
+<!-- docguard:version: 0.33.1 -->
 
 # DocGuard Score Skill
 

package/extensions/spec-kit-docguard/skills/docguard-sync/SKILL.md

@@ -4,10 +4,10 @@ description: Keep canonical documentation ALWAYS UP TO DATE. Refreshes code-trut
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.32.0
+  version: 0.33.1
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.32.0 -->
+<!-- docguard:version: 0.33.1 -->
 
 # DocGuard Sync Skill
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "docguard-cli",
-  "version": "0.32.0",
+  "version": "0.33.1",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {
-    "docguard": "./cli/docguard.mjs"
+    "docguard": "cli/docguard.mjs"
   },
   "scripts": {
     "docguard": "node cli/docguard.mjs",
@@ -36,7 +36,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/raccioly/docguard"
+    "url": "git+https://github.com/raccioly/docguard.git"
   },
   "homepage": "https://github.com/raccioly/docguard#readme",
   "mcpName": "io.github.raccioly/docguard",
@@ -57,6 +57,7 @@
     "docs/",
     "schemas/",
     "STANDARD.md",
+    "PRIVACY.md",
     "PHILOSOPHY.md",
     "README.md",
     "LICENSE"

package/schemas/docguard-config.schema.json

@@ -29,6 +29,11 @@
       "enum": ["cli", "library", "webapp", "api", "unknown"],
       "description": "Project shape. Affects which validators run (e.g. webapp + api need env vars; cli/library can skip)."
     },
+    "baseline": {
+      "type": "boolean",
+      "description": "Set false to ignore a committed .docguard.baseline.json entirely (equivalent to always passing --no-baseline). Default: the baseline auto-applies when the file exists.",
+      "default": true
+    },
     "projectTypeConfig": {
       "type": "object",
       "description": "Per-type behavior knobs that override profile defaults.",