docguard-cli 0.28.0 → 0.29.0

package/docs/ai-integration.md

@@ -1,179 +1,178 @@
 # AI Integration Guide
 
-DocGuard is **AI-native**. It generates prompts that AI agents execute — the human reviews, not writes.
+DocGuard is **AI-native by design**: a deterministic, zero-LLM core that finds
+documentation-code drift, paired with surfaces that let any AI consumer act on
+what it finds. The division of labour never changes:
 
-## How It Works
+> **Deterministic discovery, LLM judgment.** DocGuard extracts the facts
+> (routes, schemas, env vars, documented claims, finding codes); the agent
+> reads, verifies, and writes prose. DocGuard never calls an LLM itself.
 
-```
-docguard diagnose  →  AI reads output  →  AI writes docs  →  docguard guard  →  ✅
-```
-
-DocGuard is designed to be used **by** AI agents, not just **for** humans.
-
-## Supported AI Agents
+## Pick your integration surface
 
-DocGuard works with any AI coding agent that can read CLI output:
+| You are… | Use | One-liner |
+|----------|-----|-----------|
+| An MCP-capable agent (Claude Code, Cursor, …) | **MCP server** | `claude mcp add docguard -- npx docguard-cli mcp` |
+| An agent that can run CLI commands | **JSON contract** | `npx docguard-cli guard --format json` |
+| A slash-command workflow | **Installed commands** | `docguard init` installs `/docguard.*` into `.agent/commands/` |
+| GitHub Code Scanning / SARIF dashboards | **SARIF output** | `npx docguard-cli guard --format sarif` |
+| A PR reviewer (human or bot) | **GitHub Action** | inline annotations + sticky doc-impact comment, default on |
+| An LLM reading the repo cold | **llms.txt / llms-full.txt / context pack** | `docguard llms`, `llms --full`, `memory --pack` |
 
-| Agent | Integration |
-|-------|------------|
-| **Claude Code** | Reads `diagnose` output, writes docs, runs `guard` |
-| **GitHub Copilot** | Slash commands in `.github/commands/` |
-| **Cursor** | Slash commands in `.cursor/rules/` |
-| **Google Antigravity** | Workflows in `.agents/workflows/` |
-| **Google Gemini** | Commands in `.gemini/commands/` |
-| **Any CLI-capable LLM** | Reads JSON output from `--format json` |
+## MCP server (native tools, no shelling out)
 
-## Slash Commands
+```bash
+# Claude Code
+claude mcp add docguard -- npx docguard-cli mcp
+# any MCP client: stdio transport, JSON-RPC 2.0
+npx docguard-cli mcp
+```
 
-`docguard init` auto-installs slash commands for detected AI agents:
+Five tools, each accepting an optional `projectDir`:
 
-```
-.github/commands/diagnose.md     # GitHub Copilot
-.cursor/rules/diagnose.md        # Cursor
-.gemini/commands/diagnose.md     # Google Gemini
-.agents/workflows/diagnose.md    # Antigravity
-```
+| Tool | Returns |
+|------|---------|
+| `docguard_guard` | The full guard JSON contract — status, findings (stable codes), coverage, unverified-claim count |
+| `docguard_score` | `{score, grade, categories}` |
+| `docguard_explain` | A finding code's contract: title, help, suppression pragma, owning validator |
+| `docguard_verify_claims` | Documented numbers/limits/enums as verification tasks — **the caller checks each against the code** |
+| `docguard_diagnose` | Failing/warning validators with per-finding suggestions, shaped for action |
 
-## The AI Workflow
+The server is read-only (never scaffolds), keeps stdout as a pure JSON-RPC
+transport, and turns in-tool failures (e.g. a malformed `.docguard.json`) into
+`isError` results instead of dying.
 
-### Step 1: Diagnose
+## The JSON contract (CLI automation)
 
 ```bash
-npx docguard-cli diagnose
-```
-
-Output:
+npx docguard-cli guard --format json
 ```
-🔍 DocGuard Diagnose — my-project
-   Profile: standard | Score: 75/100 (B)
-   Guard:   35/41 passed | Status: WARN
 
-  Warnings (3):
-  ⚠ [Freshness] docs-canonical/ARCHITECTURE.md — 15 commits since last update
-    Fix: docguard fix --doc architecture
+| Field | Meaning |
+|-------|---------|
+| `status` | `PASS` / `WARN` / `FAIL` — severity-aware, matches the exit code (0/2/1) |
+| `findings[]` | `{code, severity, confidence, message, location, suggestion}` — codes are stable API (`STR001`, `ENV003`, `XRF002`, …) |
+| `nextStep` | The single suggested follow-up command (`null` on PASS) |
+| `reportable[]` | Low-confidence findings (possible false positives) — verify before acting |
+| `coverage` | Markdown tier map: canonical / tracked / ignored / `unclassified[]` |
+| `semanticClaims.count` | Documented counts/limits/enums **not yet verified against code** |
+| `validators[]` | Per-validator results — `na` means "nothing to validate", which is not a pass |
 
-  📋 Remediation Plan:
-  1. docguard fix --doc architecture
-  2. docguard guard ← verify fixes
+Working with findings:
 
-  🤖 AI-Ready Prompt:
-  TASK: Fix 3 documentation issue(s) in project "my-project"
-  ...
+```bash
+npx docguard-cli explain XRF002        # any code → contract, cause, fix, suppression
+npx docguard-cli fix --write           # apply deterministic fixes (provenance-checked)
+npx docguard-cli feedback              # report a false positive (local-first + prefilled issue)
 ```
 
-### Step 2: AI Fixes
+Suppress a confirmed false positive **at the finding site**, never by disabling
+a validator: `// docguard:ignore SEC001` on (or above) the flagged line, or
+`<!-- docguard:validator <key> n/a — reason -->` in a doc.
 
-The AI reads the remediation plan and executes `docguard fix --doc <name>` for each issue. Each fix command outputs research instructions:
+## SARIF (GitHub Code Scanning)
 
 ```bash
-npx docguard-cli fix --doc architecture
+npx docguard-cli guard --format sarif > docguard.sarif
 ```
 
-Output:
-```
-TASK: Write ARCHITECTURE.md for "my-project"
-
-RESEARCH STEPS:
-1. Read package.json for dependencies and project structure
-2. List top-level directories (src/, lib/, cli/)
-3. Read 2-3 representative files per directory
-4. Map the import graph
-5. Identify external dependencies
-
-WRITE THE DOCUMENT:
-- System Overview (2-3 sentences)
-- Component Map (table of modules)
-- Layer Boundaries (import rules)
-- Data Flow (request lifecycle)
-```
+Findings map 1:1 onto SARIF 2.1.0 — codes become rules (with the registry's
+title/help), locations become regions, low-confidence findings carry a property
+bag. Upload with `github/codeql-action/upload-sarif` and DocGuard findings
+appear inline on PR diffs and in the Security tab. Exit codes are unchanged
+(0/2/1), so the same run can gate and report.
 
-### Step 3: Verify
+## GitHub Action (PR feedback)
 
-```bash
-npx docguard-cli guard
+```yaml
+permissions: { pull-requests: write }
+steps:
+  - uses: actions/checkout@v4
+    with: { fetch-depth: 0 }
+  - uses: raccioly/docguard@v0.12.0
+    with:
+      command: guard
+      # both default to 'true':
+      # annotations: inline ::error/::warning per finding (capped at 50)
+      # pr-comment: sticky comment — verdict, top findings, impacted canonical docs
 ```
 
-If all checks pass → done. If issues remain → repeat from Step 1.
+The feedback steps run **even when guard fails** — that is when they matter —
+and degrade gracefully on fork tokens and shallow clones.
 
-## JSON Output for Automation
+## Context surfaces (for LLMs reading the repo)
 
-For programmatic integration:
+| Artifact | Command | What it is |
+|----------|---------|------------|
+| `llms.txt` | `docguard llms` | Link index of the canonical docs ([llms.txt standard](https://llmstxt.org)) |
+| `llms-full.txt` | `docguard llms --full` | Full doc bodies inlined — one fetch, per-doc 400-line cap |
+| `.docguard/context-pack.md` | `docguard memory --pack` | Compact session-start context: guard status, scanner-derived surface counts, doc index with review dates, your AGENTS.md rules verbatim, known drift. Everything derived from code — regenerable, hallucination-free |
 
-```bash
-npx docguard-cli diagnose --format json
-```
+Load the context pack at agent session start; regenerate any time — it is
+never hand-edited.
 
-```json
-{
-  "project": "my-project",
-  "profile": "standard",
-  "status": "WARN",
-  "score": 75,
-  "grade": "B",
-  "issues": [
-    {
-      "severity": "warning",
-      "validator": "Freshness",
-      "message": "ARCHITECTURE.md — 15 commits since last update",
-      "command": "docguard fix --doc architecture",
-      "docTarget": "architecture"
-    }
-  ],
-  "fixCommands": ["docguard fix --doc architecture"]
-}
-```
+## One source of truth for agent files
+
+Teams hand-duplicate AGENTS.md into `CLAUDE.md`, `.cursor/rules/`,
+`.github/copilot-instructions.md`, `GEMINI.md` — and the copies drift. Instead:
 
 ```bash
-npx docguard-cli guard --format json
+docguard agents --sync    # regenerate the family from AGENTS.md (hash-marked)
+docguard agents --check   # CI gate: exit 2 if any generated variant is stale
 ```
 
-```json
-{
-  "project": "my-project",
-  "profile": "standard",
-  "status": "PASS",
-  "passed": 41,
-  "total": 41,
-  "validators": [
-    { "name": "Structure", "status": "pass", "passed": 8, "total": 8 }
-  ]
-}
-```
+Generated variants carry a source-hash marker. Files you wrote by hand (no
+marker) are never touched without `--force`.
 
-## CI/CD Integration
+## Slash commands
 
-### GitHub Actions
+`docguard init` installs `/docguard.*` commands into `.agent/commands/` (the
+spec-kit convention; agents like Claude Code, Copilot, and Cursor pick them
+up). They encode the full workflows below — `templates/commands/` in this repo
+is the canonical source.
 
-DocGuard ships a ready-to-use workflow:
+## The agent workflow
 
-```yaml
-# .github/workflows/docguard.yml
-name: DocGuard CDD Check
-on: [pull_request]
-jobs:
-  docguard:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: '20' }
-      - run: npx docguard-cli ci --format json --threshold 70
 ```
-
-Or copy `templates/ci/github-actions.yml` from this repo.
-
-### Pre-commit Hook
-
-```bash
-npx docguard-cli hooks
+diagnose → fix (research + write) → guard → verify --semantic → done
 ```
 
-Automatically runs `guard` before every commit.
+1. **`docguard diagnose`** — one command that identifies everything, with
+   AI-ready fix prompts (add `--format json` for structure).
+2. **`docguard fix --doc <name>`** — emits research steps + expected structure
+   for one doc. Execute the research, write real content, no placeholders.
+3. **`docguard guard`** — verify. Loop until PASS.
+4. **`docguard verify --semantic`** — extract every checkable documented claim
+   (counts, limits, enums) with the nearest cited code path. **You** compare
+   each value against the code: a green guard asserts structure, not the truth
+   of documented numbers. This is the highest-value step an agent can run.
+
+Before editing docs after code changes, prefer the mechanical layers:
+`docguard sync --write` (regenerates `source=code` marked sections) and
+`docguard fix --write` (counts, versions, anchors) — never hand-edit what the
+tool can fix deterministically.
 
-## Best Practices for AI Agents
+## Is your repo readable by agents?
 
-1. **Always run `diagnose` first** — it's the one command that identifies everything
-2. **Use `--format json`** for structured, parseable output
-3. **Run `guard` after fixes** to verify — loop until all checks pass
-4. **Use `fix --doc <name>`** for targeted prompts when you know which doc needs work
-5. **Check `score --tax`** periodically to ensure documentation isn't becoming a burden
+```bash
+docguard score
+```
+
+The **Agent Readability** block (display-only) measures how well AI consumers
+can read the repo: agent entry file, entry-file token budget, section
+addressability, structured-content density, machine markers, llms.txt, link
+integrity. Each failing metric names its fix.
+
+## Best practices for AI agents
+
+1. **MCP first** — native tools beat parsing CLI output.
+2. **Trust the codes** — every finding has a stable code; `explain` it before
+   acting, suppress at the site with it, report false positives via `feedback`.
+3. **Run `guard` after every fix batch** — loop until PASS.
+4. **Never treat `na` as a pass** — "nothing to validate" is a coverage gap.
+5. **Check `semanticClaims.count` on green runs** — offer `verify --semantic`.
+6. **Respect the drift protocol** — deviating from canonical docs requires
+   `// DRIFT: reason` + a DRIFT-LOG.md entry, not a silent doc rewrite; the
+   docs may be right and the code wrong.
+7. **`score --tax`** periodically — documentation should stay an asset, not a
+   burden.

package/docs/commands.md

@@ -36,8 +36,10 @@ npx docguard-cli diagnose --format prompt # Raw AI prompt (all issues combined)
 
 ```bash
 npx docguard-cli guard                   # Text output
-npx docguard-cli guard --format json     # Structured JSON
+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 --verbose         # Show all check details
+npx docguard-cli guard --changed-only    # Pre-commit lite mode (fast subset)
 ```
 
 **Exit codes:** `0` (pass), `1` (errors), `2` (warnings)
@@ -52,12 +54,21 @@ When issues are found, guard outputs: `Run docguard diagnose to get AI fix promp
   "status": "WARN",
   "passed": 37,
   "total": 40,
+  "findings": [
+    { "code": "ENV003", "severity": "warn", "message": "…", "location": "docs-canonical/ENVIRONMENT.md", "suggestion": { "kind": "fix", "text": "…" } }
+  ],
+  "nextStep": "docguard diagnose",
+  "coverage": { "canonical": 5, "tracked": 40, "ignored": 10, "unclassified": [] },
+  "semanticClaims": { "count": 12 },
   "validators": [
     { "name": "Structure", "status": "pass", "passed": 8, "total": 8, "errors": [], "warnings": [] }
   ]
 }
 ```
 
+Every finding carries a stable code — `docguard explain <CODE>` for its
+contract, `// docguard:ignore <CODE>` to suppress a false positive at the site.
+
 ### `docguard score`
 
 **CDD maturity score** (0-100) with category breakdown.
@@ -157,8 +168,43 @@ npx docguard-cli fix --doc environment
 **Generate agent-specific config files** from AGENTS.md.
 
 ```bash
-npx docguard-cli agents
-npx docguard-cli agents --list
+npx docguard-cli agents            # one-shot scaffold (skips existing files)
+npx docguard-cli agents --sync     # AGENTS.md → CLAUDE.md/Copilot/Cursor/… (hash-marked, repeatable)
+npx docguard-cli agents --check    # CI gate: exit 2 if any synced variant is stale
+```
+
+`--sync` treats AGENTS.md as the canonical source: generated variants carry a
+source-hash marker and are regenerated on change; files you wrote by hand are
+never touched without `--force`.
+
+### `docguard mcp`
+
+**MCP server over stdio** — DocGuard's read-only core as native agent tools
+(`docguard_guard`, `docguard_score`, `docguard_explain`,
+`docguard_verify_claims`, `docguard_diagnose`).
+
+```bash
+claude mcp add docguard -- npx docguard-cli mcp
+```
+
+### `docguard verify --semantic`
+
+**Extract documented claims** (counts, limits, enums) as a verification task
+list with cited code paths — the agent checks each value against the code.
+
+### `docguard explain <CODE>`
+
+**Explain any finding code** (`STR001`, `ENV003`, …): what it means, how to fix
+it, how to suppress a false positive at the finding site.
+
+### `docguard llms` / `docguard memory --pack`
+
+**Context surfaces for LLMs reading the repo:**
+
+```bash
+npx docguard-cli llms              # llms.txt (link index)
+npx docguard-cli llms --full       # llms-full.txt (full doc bodies inlined)
+npx docguard-cli memory --pack     # .docguard/context-pack.md (session-start context)
 ```
 
 ---

package/docs/configuration.md

@@ -43,6 +43,20 @@ DocGuard is configured via `.docguard.json` in the project root. If no config fi
     "security": true,
     "environment": true,
     "freshness": true
+  },
+
+  "severity": {
+    "security": "high",
+    "todoTracking": "low"
+  },
+
+  "collections": {
+    "extractors": "src/extractors/*.py",
+    "commands": "cli/commands/*.mjs"
+  },
+
+  "docs": {
+    "dirs": ["reference", "website/docs"]
   }
 }
 ```
@@ -73,6 +87,30 @@ See [Profiles](./profiles.md) for details.
 | `environment` | `true` | Setup steps, env vars, prerequisites, .env.example |
 | `freshness` | varies | Docs updated recently relative to code changes (git-based) |
 
+## Severity overrides
+
+`severity.<validator>` changes a validator's **exit-code weight** without hiding
+anything from display: `"high"` promotes its warnings to blocking (CI fails),
+`"low"` demotes them (shown, but never fail the build). Valid values:
+`high | medium | low`. To silence a validator entirely, use `validators.<key>: false`.
+
+## Collections — verify documented counts against code
+
+`collections` binds a documentation noun to a glob whose **file count is the
+source of truth**. With `"extractors": "src/extractors/*.py"`, a doc claiming
+"16 extractors" while the glob matches 19 files becomes a guard warning (and a
+`fix --write`-able correction). Declaring the noun *is* the opt-in — no other
+marker needed. Reserved nouns (`checks`, `validators`, `tests`) keep their
+built-in DocGuard meaning. An unresolvable glob is skipped, never treated as 0.
+
+## Documentation homes — `docs.dirs`
+
+Conventional doc folders (`docs/`, `doc/`, `documentation/`, `guides/`,
+`handbook/`, `manual/`, `wiki/`, Docusaurus `website/docs/`, …) are
+**auto-detected** and claim-scanned without enrollment. `docs.dirs` EXTENDS
+that set with non-standard homes — it never replaces auto-detection. To exclude
+a conventional dir, list it in `.docguardignore`.
+
 ## Muting a validator
 
 Two ways to turn a validator off, for two different intents:

package/docs/faq.md

@@ -153,3 +153,18 @@ Yes. In `.docguard.json`:
 ```
 
 Or use a profile that has them disabled by default (like `starter`).
+
+### Can my AI agent use DocGuard without parsing CLI output?
+
+Yes — run the MCP server: `claude mcp add docguard -- npx docguard-cli mcp`
+exposes guard, score, explain, verify-claims, and diagnose as native tools for
+Claude, Cursor, and any MCP client. For CLI-driven agents, `guard --format json`
+is the stable contract (findings with stable codes) and `guard --format sarif`
+feeds GitHub Code Scanning. See [AI Integration](./ai-integration.md).
+
+### Guard flagged something that isn't wrong. What do I do?
+
+Suppress it **at the finding site** with its code — `// docguard:ignore SEC001`
+on (or above) the flagged line — and report it with `docguard feedback` (a
+local-first record plus a one-click prefilled GitHub issue). Don't disable the
+whole validator for one false positive.

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

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.28.0"
+  version: "0.29.0"
   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.28.0
+  version: 0.29.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.28.0 -->
+<!-- docguard:version: 0.29.0 -->
 
 # 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.28.0
+  version: 0.29.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.28.0 -->
+<!-- docguard:version: 0.29.0 -->
 
 # 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.28.0
+  version: 0.29.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.28.0 -->
+<!-- docguard:version: 0.29.0 -->
 
 # 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.28.0
+  version: 0.29.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.28.0 -->
+<!-- docguard:version: 0.29.0 -->
 
 # 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.28.0
+  version: 0.29.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.28.0 -->
+<!-- docguard:version: 0.29.0 -->
 
 # DocGuard Sync Skill
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {

package/schemas/docguard-config.schema.json

@@ -175,6 +175,23 @@
         }
       },
       "additionalProperties": true
+    },
+    "docs": {
+      "type": "object",
+      "description": "Documentation discovery (field report #6 follow-up).",
+      "properties": {
+        "dirs": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Additional documentation-home directories to claim-scan and count as 'tracked' (relative paths, e.g. [\"reference\", \"website/docs\"]). This EXTENDS the auto-detected conventional homes (docs/, doc/, documentation/, guides/, guide/, handbook/, manual/, wiki/, docs-canonical/, docs-implementation/, extensions/) — it never replaces them, since the goal is to track MORE clearly-documentation folders automatically. Only NAMED dirs are scanned; arbitrary subdirectories are never walked. To EXCLUDE a conventional dir, list it in .docguardignore."
+        }
+      },
+      "additionalProperties": true
+    },
+    "collections": {
+      "type": "object",
+      "description": "Project-declared collections (field report #6): maps a documentation noun (e.g. \"extractors\") to a glob whose matching-file count is the source of truth. Metrics-Consistency then flags a documented count that disagrees (\"16 extractors\" in prose vs 19 files on disk), deterministically and with no LLM. A declared collection IS the opt-in binding, so — unlike the built-in checks/validators counts — it does not require the noun's line to mention \"docguard\". An unresolved glob (0 matches) is skipped, never asserting \"0\". Reserved nouns (checks, validators, tests) keep their built-in meaning. Complements surfaceSync (WHICH members drift) with a count check (HOW MANY). Example: { \"extractors\": \"src/extractors/*.py\", \"commands\": \"cli/commands/*.mjs\" }.",
+      "additionalProperties": { "type": "string" }
     }
   },
   "additionalProperties": true

package/templates/commands/docguard.fix.md

@@ -13,29 +13,47 @@ handoffs:
 
 You are an AI agent responsible for maintaining documentation quality using DocGuard.
 
-## Step 1: Assess Current State
+## Step 1: Mechanical fixes first (no AI judgment needed)
 
 ```bash
-npx docguard-cli diagnose
+npx docguard-cli fix --write
 ```
 
-Parse the output to identify all issues — categorized as errors or warnings with AI-ready fix prompts.
+This deterministically applies the safe fix class: broken doc anchors, stale
+counts bound to code collections, stale version references. Each fix is
+provenance-checked and fail-closed — it never rewrites content whose source of
+truth it cannot verify. Doing this first shrinks the issue list you research.
 
-If no issues found, report "All CDD documentation is up to date" and stop.
+## Step 2: Assess what remains
 
-## Step 2: Fix Each Issue
+```bash
+npx docguard-cli diagnose
+```
 
-For each issue, determine the fix type:
+Parse the output — issues are categorized with AI-ready fix prompts. Every
+finding carries a stable code; run `npx docguard-cli explain <CODE>` whenever
+the right remediation isn't obvious from the message.
+
+If no issues remain, report "All CDD documentation is up to date" and stop.
+
+## Step 3: Fix each issue
 
 | Issue Type | Action |
 |-----------|--------|
 | `missing-file` | Run `npx docguard-cli fix --doc <name>` to generate |
-| `empty-doc` / `partial-doc` | Proceed to Step 3 for codebase research |
+| `empty-doc` / `partial-doc` | Proceed to Step 4 for codebase research |
 | `missing-config` | Create `.docguard.json` based on project type |
 | `stale-doc` | Update `docguard:last-reviewed` date and content |
 | `quality-issue` | Fix negation language, add missing sections |
+| false positive | Suppress at the site: `// docguard:ignore <CODE>` (with a reason comment), and report it: `npx docguard-cli feedback` |
+
+**Doc wrong vs code wrong:** a doc/code mismatch does not automatically mean
+the doc is stale. Canonical docs are the spec — if the code drifted from a
+documented decision, flag the code (or record the deviation with a
+`// DRIFT: reason` comment + DRIFT-LOG.md entry) instead of silently rewriting
+the doc to match the regression.
 
-## Step 3: Write Real Content
+## Step 4: Write real content
 
 For each document that needs content:
 
@@ -50,12 +68,17 @@ Read the output carefully — it contains:
 - **WRITE THE DOCUMENT**: Expected structure and content for each section
 
 Execute the research steps, then write with REAL project content. No placeholders.
+Never edit inside `<!-- docguard:section ... source=code -->` markers by hand —
+those bodies are regenerated from code by `docguard sync --write`; pin them
+(`pinned="reason"`) if a hand-maintained exception is genuinely needed.
 
-## Step 4: Verify (Iterate up to 3 times)
+## Step 5: Verify (iterate up to 3 times)
 
 ```bash
 npx docguard-cli guard
 npx docguard-cli score
 ```
 
-All checks should pass. If any fail, read the output and fix remaining issues. Report the final CDD score.
+All checks should pass. If any fail, read the output and fix remaining issues.
+Report the final CDD score, plus anything you suppressed (with reasons) or
+reported as a false positive.