[Extension]: Update DocGuard — CDD Enforcement (v0.33.0)

[raccioly]

Extension ID

docguard

Extension Name

DocGuard — CDD Enforcement

Version

0.33.0

Description

The only doc-integrity engine with an MCP server, SARIF/JUnit output, and a deterministic zero-LLM core. Validates, scores, and traces documentation against code — 27 validators, stable finding codes, adoption baseline for legacy repos, compliance-evidence reports, GitHub Action with PR annotations, spec-kit hooks. Pure Node.js, one pinned dep.

Author

raccioly

Repository URL

https://github.com/raccioly/docguard

Download URL

https://github.com/raccioly/docguard/releases/download/v0.33.0/spec-kit-docguard-v0.33.0.zip

License

MIT

Homepage (optional)

https://www.npmjs.com/package/docguard-cli

Documentation URL (optional)

https://github.com/raccioly/docguard/blob/main/extensions/spec-kit-docguard/README.md

Changelog URL (optional)

https://github.com/raccioly/docguard/blob/main/CHANGELOG.md

Required Spec Kit Version

=0.1.0

Required Tools (optional)

- node (>=18.0.0) - required
- npx - required
- specify - optional (auto-initializes the SDD workflow during docguard init)

Number of Commands

6

Number of Hooks (optional)

3

Tags

documentation, validation, quality, cdd, traceability, ai-agents, enforcement, spec-kit

Key Features

• 19-validator quality gate with severity triage and a remediation plan
• AI-driven documentation repair with codebase research and validation loops
• Cross-document semantic consistency analysis (read-only review)
• CDD maturity score with an ROI-based improvement roadmap
• Reverse-engineers canonical docs from an existing codebase
• spec-kit workflow hooks (after_implement, before_tasks, after_tasks)

Testing Checklist

• Extension installs successfully via download URL
• All commands execute without errors
• Documentation is complete and accurate
• No security vulnerabilities identified
• Tested on at least one real project

Submission Requirements

• Valid extension.yml manifest included
• README.md with installation and usage instructions
• LICENSE file included
• GitHub release created with version tag
• All command files exist and are properly formatted
• Extension ID follows naming conventions (lowercase-with-hyphens)

Testing Details

Tested on: Linux + macOS with the spec-kit CLI.

Install:

specify extension add docguard --from https://github.com/raccioly/docguard/releases/download/v0.33.0/spec-kit-docguard-v0.33.0.zip

Scenarios verified:

1. Extension installs from the release ZIP without manifest validation errors.
2. All six speckit.docguard.* commands resolve and run.
3. The three workflow hooks register against spec-kit's lifecycle.

Example Usage

# Install the extension
specify extension add docguard --from https://github.com/raccioly/docguard/releases/download/v0.33.0/spec-kit-docguard-v0.33.0.zip

# Run the documentation quality gate
/speckit.docguard.guard

Proposed Catalog Entry

{
  "docguard": {
    "name": "DocGuard \u2014 CDD Enforcement",
    "id": "docguard",
    "description": "The only doc-integrity engine with an MCP server, SARIF/JUnit output, and a deterministic zero-LLM core. Validates, scores, and traces documentation against code \u2014 27 validators, stable finding codes, adoption baseline for legacy repos, compliance-evidence reports, GitHub Action with PR annotations, spec-kit hooks. Pure Node.js, one pinned dep.",
    "author": "raccioly",
    "version": "0.33.0",
    "download_url": "https://github.com/raccioly/docguard/releases/download/v0.33.0/spec-kit-docguard-v0.33.0.zip",
    "repository": "https://github.com/raccioly/docguard",
    "homepage": "https://www.npmjs.com/package/docguard-cli",
    "documentation": "https://github.com/raccioly/docguard/blob/main/extensions/spec-kit-docguard/README.md",
    "changelog": "https://github.com/raccioly/docguard/blob/main/CHANGELOG.md",
    "license": "MIT",
    "requires": {
      "speckit_version": ">=0.1.0",
      "tools": [
        {
          "name": "node",
          "version": ">=18.0.0",
          "required": true
        }
      ]
    },
    "provides": {
      "commands": 6,
      "hooks": 3
    },
    "tags": [
      "documentation",
      "validation",
      "quality",
      "cdd",
      "traceability",
      "ai-agents",
      "enforcement",
      "spec-kit"
    ],
    "verified": false,
    "downloads": 0,
    "stars": 0
  }
}

Additional Context

Additional Context

This is an update to an existing catalog entry (docguard) for a new release — please bump the version and download URL on the current entry rather than adding a duplicate.

Release notes (v0.33.0):

Added

• Adoption baseline — guard --update-baseline + committed .docguard.baseline.json. The ESLint/semgrep-style brownfield pattern: freeze a legacy repo's existing findings once, commit the file, and guard/ci gate only NEW drift from then on — no red pipeline on adoption day. Fingerprints are content-addressed (finding code + location path with line numbers stripped + message with digit-runs normalized), so they survive line churn and volatile counts ("21 commits since…") — and they carry occurrence counts: freezing one hardcoded-secret finding in a file suppresses exactly one; a second instance of the same class surfaces and gates (the ESLint-baseline semantics). Suppression is never silent: the summary prints "N pre-existing finding(s) suppressed", baselineSuppressed rides the JSON contract, and --no-baseline (or "baseline": false in .docguard.json) shows everything. A malformed baseline is treated as absent — corruption can never un-gate CI. Applied inside runGuardInternal, so guard, ci, report, SARIF/JUnit outputs, and the MCP tools all honor it uniformly. Also: DocGuard's own files (.docguard.json, .docguardignore, .docguard.baseline.json) are exempt from Docs-Coverage's undocumented-config check — writing the baseline no longer instantly creates a DCV001 about the baseline.

• guard --format junit — JUnit XML for the rest of the CI world. SARIF covers GitHub Code Scanning; JUnit covers GitLab (artifacts:reports:junit), Jenkins (junit step), Azure DevOps, and CircleCI. One testcase per validator: error findings render as <failure> (red in every CI UI), a crashed validator renders as <error> (also red — never a silent pass), warn-only validators pass with findings in <system-out>, skipped/N/A validators map to <skipped/>. Strict XML escaping, exit codes identical to guard's json/sarif branches, banner-free stdout. GitLab and Jenkins recipes added to CI-RECIPES (Recipe 1b).

• docguard_report MCP tool. The compliance-evidence bundle is now callable by agents: same payload as docguard report --format json (guard verdict, findings by code, score, ALCOA+, fix history, integrity hash), read-only annotations, over both stdio and HTTP transports. MCP tool count 5 → 6.

• Score history + score --trend. Every docguard ci run appends one line to .docguard/history.jsonl ({timestamp, commit, score, grade, guard counts, status}); docguard score --trend renders the trajectory — sparkline, first→latest delta, and the last 10 runs with commit stamps (--format json for the raw series). Opt out per run with ci --no-history. Local-first: .docguard/ stays gitignored; in ephemeral CI, persist the file across runs with a cache/artifact step (see CI-RECIPES). The append is silent-on-failure — recording history never fails the pipeline it records.

• docguard report — compliance-evidence bundle for audits. Runs guard + score internally and emits a deterministic evidence report: tool version, git commit/branch/dirty state, per-validator guard verdict, findings grouped by stable code, CDD score with categories, the ALCOA+ data-integrity attribute table, and the mechanical-fix history from .docguard/fixed.json. The bundle carries a tamper-evident sha256 integrity hash over the git-stable sections of the payload (the generation timestamp and the ALCOA+ block are excluded — the latter's Contemporaneous attribute is mtime/wall-clock-relative — so the same commit always reproduces the same hash, including on a fresh clone). Markdown to stdout by default, --format json for the machine bundle, --out <file> to write either to a file. Report is evidence, not a gate: it always exits 0 — guard and ci remain the commands that fail builds, so evidence collection never self-censors. Headless in both formats (stdout is the artifact; no banner bytes). Enterprise rationale: docs platforms ship no audit logs at any tier — DocGuard now generates a documentation audit trail from the repo itself.

Fixed

• Pre-release adversarial review — 12 findings fixed before ship. An independent review pass over this release's batch caught and fixed, among others: ci missing from the read-only command set (a bare text-mode ci still scaffolded skills into the workspace it gates); baseline fingerprints suppressing NEW same-class findings in the same file (now occurrence-counted); report/ci not disclosing baseline suppression (now in the payload, the markdown summary, and history entries); JUnit rendering a crashed validator as a passing testcase; ci gating on raw instead of severity-aware counts (it now matches guard exactly); threshold failures recorded as PASS in history; --update-baseline --changed-only shrinking the committed baseline to the lite validator subset (now refused); and a non-atomic history trim. Every fix ships with a regression test.

• docguard ci un-deprecated and made safe for pipelines. The v0.20 consolidation routed ci through init --with ci, which (a) scaffolded missing canonical docs INTO the CI workspace — a validate command mutating the tree it validates — and (b) printed the deprecation warning + init chrome into --format json stdout, corrupting it for parsers. ci now dispatches straight to the gate (guard + score, read-only, machine-clean) and is a first-class command again; init --with ci still runs the gate once after init. runCI also moved off console.log + process.exit to stdout.write + process.exitCode — the >8 KB pipe-truncation class fixed for guard --format json in v0.28.

[github-actions]

cc @github/spec-kit-maintainers — new catalog submission for review.

[github-actions]

Pull request created: #3559

Generated by Add Community Extension from Issue Submission · 243 AIC · ⌖ 15.2 AIC · ⊞ 34.5K

[mnriem]

Thank you!