🛡️ DocGuard

English · Português (BR) · Español

The enforcement layer for Spec-Driven Development. Validate. Score. Enforce. Ship documentation that AI agents can actually use.

---

✨ See what DocGuard catches in 30 seconds — no install, no setup:

npx docguard-cli demo

Runs against a baked-in sample project with intentional drift and shows you the findings + a clear path to fixing them.

---

Table of Contents

• What is DocGuard?
• Why DocGuard?
• Quick Start
• Spec Kit Integration
• Usage
• Validators
• Reading a finding
• Templates
• AI Agent Support
• Slash Commands
• Examples
• Testing
• Enterprise Adoption
• CI/CD Integration
• What's New
• File Structure
• Configuration
• Research Credits

---

What is DocGuard?

DocGuard enforces Canonical-Driven Development (CDD) — a methodology where documentation is the source of truth, not an afterthought. AI writes the docs, DocGuard validates them.

Traditional Development	Canonical-Driven Development
Code first, docs maybe	Docs first, code conforms
Docs rot silently	Drift is tracked and enforced
Docs are optional	Docs are required and validated
One AI agent, one context	Any agent, shared context via canonical docs

DocGuard is an official GitHub Spec Kit community extension. It validates the artifacts that Spec Kit creates, ensuring your specs stay high-quality throughout the development lifecycle.

🧭 How it works (8-page brief) · 📖 Philosophy · 📋 CDD Standard · ⚖️ Comparisons · 🔬 Validation · 🗺️ Roadmap

Architecture

graph TD
    CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (23)"]
    Commands --> guard["guard"]
    Commands --> generate["generate"]
    Commands --> score["score"]
    Commands --> diagnose["diagnose"]
    Commands --> setup["setup wizard"]
    Commands --> other["diff · init · fix · trace · impact · sync · reconcile · retire · specs<br/>explain · memory · upgrade · agents · hooks · badge · ci · watch"]

    guard --> Validators["Validators (29)"]
    generate --> Scanners["Scanners (4)<br/>routes · schemas · doc-tools · speckit"]
    score --> Scoring["Weighted Scoring<br/>8 categories"]
    diagnose --> Validators
    diagnose --> AIPrompts["AI-Ready<br/>Fix Prompts"]

    Validators --> Output["Output"]
    Scanners --> Output
    Scoring --> Output
    Output --> Terminal["Terminal"]
    Output --> JSON["JSON"]
    Output --> Badge["Badge"]

    style CLI fill:#2d5016,color:#fff
    style Validators fill:#1a3a5c,color:#fff
    style Scanners fill:#1a3a5c,color:#fff
    style Output fill:#5c3a1a,color:#fff

Distribution: Node.js core (npm) · Python wrapper (PyPI) · GitHub Action (action.yml) · Spec Kit Extension (ZIP)

---

Why DocGuard?

DocGuard checks declared documentation facts against repository evidence and gives agents structured repair tasks. Deterministic checks cover supported facts, references, and generated sections. Human-authored requirements and architectural decisions retain their authority when implementation diverges.

A guard result describes the checks performed. The CDD grade measures structural maturity. Exact declarations in .docguard-evidence.json can verify selected statements against current local evidence; every other statement remains unverified. Coverage and unresolved claims remain visible, so teams can choose an appropriate enforcement policy.

Research motivates evaluation of this approach. A 2026 study found that repository context files did not generally improve task success and increased inference cost in its evaluated settings. It also found agents generally followed the instructions. These results support testing concise, relevant context and measuring actual task outcomes; they do not establish DocGuard's effectiveness. Evaluating AGENTS.md, revised June 2026.

The current roadmap prioritizes accurate detection, reproducible evidence, document lifecycle management, and contributor-supplied regression cases. Released plans and superseded specifications are removed from active AI context and remain recoverable from Git.

---

⚡ Quick Start

Package naming: this repo is raccioly/docguard; the published package is docguard-cli on both npm and PyPI; the installed command is docguard. Same project — the -cli suffix is just the registry name. The package runs no install scripts, so npm i -g docguard-cli --ignore-scripts is equivalent.

Node.js (npm)

# No install needed — run directly
npx docguard-cli diagnose

# Or install globally
npm i -g docguard-cli
docguard diagnose

Python (PyPI)

pip install docguard-cli
docguard diagnose

Note: The Python package is a thin wrapper that delegates to npx. Node.js 18+ is required on the system.

Docker (MCP server)

The MCP server ships as a container image on GHCR — no Node.js install required. Public image, so no authentication is needed to pull it:

# Run the MCP server against the current directory
docker run -i --rm -v "$PWD":/workspace ghcr.io/raccioly/docguard:latest

The entrypoint is the stdio MCP transport: stdout is the JSON-RPC channel, so don't pipe anything else into it. Mount the project you want inspected at /workspace and pass {"projectDir": "/workspace"} in tool calls (or rely on the default working directory).

Pin a version rather than tracking latest in CI:

docker run -i --rm -v "$PWD":/workspace ghcr.io/raccioly/docguard:0.34.9

The server is read-only — it never writes to the mounted project.

More ways to integrate

• pre-commit — changed-only guard on every commit:

  repos:
    - repo: https://github.com/raccioly/docguard
      rev: v0.29.0
      hooks: [{ id: docguard-guard }]   # docguard-guard-full for pre-push
  

• MCP (Claude, Cursor, any MCP client) — claude mcp add docguard -- npx -y docguard-cli mcp; 5 read-only tools (guard, score, explain, verify-claims, diagnose). Registry manifest ships in-repo (server.json, Smithery-ready).
• GitLab CI — component staged at templates/ci/gitlab-component.yml (guard/score/ci job with a SARIF artifact).
• Homebrew — brew install raccioly/tap/docguard (formula in packaging/homebrew/).

Core Workflow

# 1. Initialize docs for your project
npx docguard-cli init

# 2. Or reverse-engineer docs from existing code
npx docguard-cli generate

# 3. AI diagnoses issues and generates fix prompts
npx docguard-cli diagnose

# 4. Validate — use as CI gate
npx docguard-cli guard

# 5. Check maturity score
npx docguard-cli score

The AI Loop

diagnose  →  AI reads prompts  →  AI fixes docs  →  guard verifies
   ↑                                                       ↓
   └───────────────── issues found? ←──────────────────────┘

diagnose is the primary command. It runs all validators, maps every failure to an AI-actionable fix prompt, and outputs a remediation plan. Your AI agent runs it, fixes the docs, and runs guard to verify.

Mechanical vs. agent fixes

DocGuard splits drift into two kinds and is explicit about which is which:

Kind	Example	How it's fixed
Mechanical (deterministic)	An endpoint documented in API-REFERENCE.md that the OpenAPI spec confirms is gone	docguard fix --write deletes the row + detail block itself — no AI
Agent (needs judgment)	Rewriting an X-Ray prose section as CloudWatch; writing a new endpoint's request/response	Routed to an AI agent via diagnose / fix --doc prompts

docguard fix --write only touches docs marked <!-- docguard:generated true --> (override with --force), is idempotent, and prints exactly what changed. It never rewrites prose — that stays with the agent.

Continuous documentation workflow

guard ──▶ fix --write (mechanical, auto) ──▶ guard ──▶ diagnose (agent prompts for the rest)

• CI / pre-commit: docguard hooks --type pre-commit --auto-fix installs a hook that applies mechanical fixes, re-stages the docs, then runs guard; anything left is surfaced as agent prompts.
• Agent-driven: docguard diagnose --auto scaffolds missing docs and applies mechanical fixes, then emits prompts for the content rewrites that remain.
• JSON for automation: guard/diagnose --format json include a mechanicalFixes array and tag each issue mechanical vs agent, so an agent can apply or delegate precisely.

---

🌱 Spec Kit Integration

DocGuard is a community extension for GitHub's Spec Kit framework. While Spec Kit focuses on creating specifications (via AI slash commands like /speckit.specify and /speckit.plan), DocGuard focuses on validating their quality.

How They Work Together

┌─────────────────┐          ┌──────────────────┐
│    Spec Kit      │          │    DocGuard       │
│                  │          │                   │
│  /speckit.specify│ ──────→  │  docguard guard   │
│  Creates specs   │          │  Validates specs  │
│  (AI-driven)     │          │  (automated)      │
└─────────────────┘          └──────────────────┘

Phase	Tool	What happens
1. Initialize	specify init	Creates .specify/ directory and templates
2. Write specs	/speckit.specify	AI creates spec.md with FR-IDs, user stories
3. Validate	docguard guard	Checks spec quality (mandatory sections, FR/SC IDs)
4. Plan	/speckit.plan	AI creates plan.md with technical context
5. Validate	docguard guard	Checks plan quality (sections, structure)
6. Tasks	/speckit.tasks	AI creates tasks.md with phased breakdown
7. Validate	docguard guard	Checks task quality (phases, T-IDs)
8. Implement	/speckit.implement	AI writes code
9. Enforce	docguard guard	Final quality gate — CI/CD

What DocGuard Validates in Spec Kit Projects

• spec.md — Mandatory sections (User Scenarios, Requirements, Success Criteria), FR-xxx IDs, SC-xxx IDs
• plan.md — Summary, Technical Context, Project Structure sections
• tasks.md — Phased task breakdown (Phase 1, 2, 3+), T-xxx task IDs
• constitution.md — Detected at .specify/memory/constitution.md or project root
• Requirement traceability — FR, SC, NFR, US, AC, UC, SYS, ARCH, MOD, T IDs

Installing as a Spec Kit Extension

specify extension add docguard

This installs DocGuard's slash commands (/docguard.init, /docguard.guard, /docguard.review, /docguard.fix, /docguard.update) into your AI agent's command palette.

---

Usage

DocGuard ships 23 commands (the "Daily 5" + 18 situational tools, including lifecycle reconciliation, retirement and spec tracking, the zero-install demo, the mcp server, and the ci pipeline gate). Six additional one-shot scaffolders are accessed via docguard init --with <name>. Legacy command forms remain compatible until v1.0 and print their replacements.

The Daily 5 — what you'll reach for 95% of the time:

Command	What It Does
init	Bootstrap a project (--wizard for interactive · --with <name> for scaffolders)
guard	Validate against canonical docs — 29 validators
diff	Show gaps between docs and code (--since <ref> for impact mode)
sync	Refresh code-truth doc sections — keeps memory always up to date
score	Structural CDD maturity score (0-100; not a guard verdict; --diff for delta between refs)

Tools (situational, but day-to-day useful):

Command	Purpose
demo	Zero-install showcase — runs guard against a baked-in drifting fixture (npx docguard-cli demo)
diagnose	AI orchestrator — guard → emit fix prompts in one command
fix	Generate AI fix instructions for specific docs (--doc <name> --format prompt)
fix --write	Apply deterministic fixes (no AI — version bumps, counts, anchors, sections)
fix --history	Audit log of every mechanical fix applied (from .docguard/fixed.json)
generate	Reverse-engineer docs from existing codebase (--plan for AI scan) — includes auto-generated Mermaid ER diagrams from your detected schemas (Prisma/Drizzle/TypeORM/Sequelize/Django/Rails) in DATA-MODEL.md
agent	One-shot agent task graph, or a bounded current-evidence packet for one task (--task <text>, --format json)
explain <warning|CODE>	Paste any warning — or a finding code like SEC001 — to get the validator's docstring, fix path, and how to suppress
verify --evidence	Evaluate strict statement-to-source declarations for typed JSON values, bounded collection counts, saved oasdiff JSON, and saved Buf JSON Lines. Results distinguish scoped verification, contradiction, stale inputs, inconclusive evidence, and unsupported formats.
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	Review any finding or a synthetic false-positive/false-negative/unsupported fixture; verify its opposite control, reduce it deterministically, search open and closed duplicates, and optionally emit a test-only contribution. Nothing is submitted automatically.
retire	Find completed or superseded planning material (--plan/--check; --fail-on-warning gates advisory candidates) and explicitly remove clean tracked documentation from active AI context. .docguard-archive.json records recovery metadata and retired requirement identities, and --retention-ref proves the source revision remains reachable. This is separate from the Spec Kit Archive extension, which consolidates feature documents.
reconcile	Build a read-only code↔spec review graph since a Git ref. Classifies mechanical facts, approved intent, decisions, unrelated changes, and unsupported evidence; --write applies only mechanical generated-section refreshes.
specs	Maintain the versioned spec registry, preflight new specs, and apply evidence-gated completion transactions with bounded outcomes and active-context regeneration. Verified living specs can record later reviewed maintenance without reopening or duplicating the specification.
specs --check / specs --write	Validate or refresh .docguard-specs.json, the byte-stable index of immutable spec IDs, reviewed lifecycle/lineage/scope, artifact digests, task state, explicitly scoped test evidence, and archive tombstones. Refreshes preserve the reviewed block.
specs preflight [--path <spec>]	Before specification, print current spec lifecycle and evidence. Before planning, check the generated draft for structural blockers and report semantic overlap as review-only evidence.
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 — combined readiness, guard verdict, structural maturity, ALCOA+ attributes, and 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 + structural maturity in one command with READY/ATTENTION/BLOCKED assessment — 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
score --diff	Drill into which checks pulled each category down
trace / trace --reverse <file>	Requirements traceability — forward AND reverse
trace --features	Per-feature spec-adherence scores (requirement coverage, task completion, task evidence, artifacts) — worst-first with fix hints
upgrade [--apply] [--pr]	Check + migrate .docguard.json schema; --pr opens a PR
watch	Live mode: re-run guard on file changes

init --with <name> scaffolders — picked at init time:

Scaffolder	What It Generates
agents	AGENTS.md, CLAUDE.md, .cursor/rules/, .github/copilot-instructions.md
hooks	Git pre-commit / pre-push hooks
ci	GitHub Actions / pipeline YAML
badge	Shields.io score badges for README
llms	llms.txt (AI-friendly summary)
publish	External doc-site config (Mintlify) — experimental

Run them solo (docguard init --with hooks) or stacked (docguard init --with agents,hooks,badge,ci).

To declare an exact fact, copy templates/evidence-manifest.json to .docguard-evidence.json, point its literal Markdown template at one unique statement, and bind that value to a supported local source. Run docguard verify --evidence --format json before enabling the guard in CI. External compatibility declarations consume saved oasdiff or Buf output and require current SHA-256 identities for every declared repository input.

Deprecation aliases — setup · agents · hooks · badge · llms · publish · impact remain compatible until v1.0 with a yellow stderr warning. audit → guard is permanent and silent; ci is a current first-class pipeline command.

CLI Flags

Flag	Description	Commands
--dir <path>	Project directory (default: .); explicit selection suppresses ancestor-root guidance	All
--verbose	Show detailed output	All
--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, verify, reconcile, retire, specs
--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
--check	CI gate for the synced agent-file family — exit 2 when a variant is stale	agents
--force	Overwrite existing files (creates .bak backups)	generate, agents, init
--force-redo	Bypass ping-pong suppression in .docguard/fixed.json	fix --write
--profile <name>	Starter / standard / enterprise	init
--no-spec-kit	Skip auto-init of .specify/ / .agent/ scaffolding	init
--changed-only [--since <ref>]	Pre-commit lite mode (6 fast validators on changed files only)	guard
--timings	Per-validator wall-time profile (slowest first)	guard
--show-failing	Show warnings/errors even when status is PASS	guard
--pin	Record running CLI version into .docguard.json (reproducibility)	guard
--diff	Per-category drill-down	score, memory
--check-only	Exit 1 if behind (for CI)	upgrade
--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