docguard-cli 0.28.0 → 0.29.0

package/templates/commands/docguard.guard.md

@@ -13,41 +13,55 @@ handoffs:
 
 You are an AI agent enforcing Canonical-Driven Development (CDD) compliance using DocGuard.
 
-## Step 1: Run Guard
+## Step 1: Run Guard (machine-readable)
 
 ```bash
-npx docguard-cli guard
+npx docguard-cli guard --format json
 ```
 
-Read the output. It shows pass (✅), warn (⚠️), or fail (❌) for each of the validators:
+Read the JSON contract — do not parse prose:
 
-| Priority | Validators |
-|----------|-----------|
-| CRITICAL | Structure, Security, Test-Spec |
-| HIGH | Doc Sections, Drift-Comments, Changelog, Traceability, API-Surface |
-| MEDIUM | Freshness, Docs-Coverage, Doc-Quality, Metrics-Consistency |
-| LOW | TODO-Tracking, Schema-Sync, Spec-Kit, Metadata-Sync |
+| Field | Meaning |
+|-------|---------|
+| `status` | `PASS` / `WARN` / `FAIL` (severity-aware; matches the exit code: 0/2/1) |
+| `findings[]` | Structured issues: `{code, severity, confidence, message, location, suggestion}` |
+| `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, including `na` (nothing to validate ≠ pass) |
 
-## Step 2: Handle Results
+## Step 2: Understand each finding before fixing
 
-### If all checks pass:
-Report success and the score:
-```bash
-npx docguard-cli score
-```
+- Every finding carries a stable code (e.g. `STR001`, `ENV003`, `XRF002`). Run
+  `npx docguard-cli explain <CODE>` for its contract, cause, and remediation.
+- `confidence: "low"` means the scanner itself is unsure — verify against the
+  code before changing anything, and report real false positives with
+  `npx docguard-cli feedback`.
+- A finding's `suggestion` may include a ready-to-run `command` or an inline
+  `pragma`. Prefer those over inventing your own fix.
 
-### If checks fail:
-For each failing check, provide an **exact fix** — specific file, section, and content.
-Then run the fix workflow:
-```bash
-npx docguard-cli fix --doc <name>
-```
+## Step 3: Fix, suppress, or escalate
 
-Execute the research steps in the output, write real content, then re-run guard to verify.
+1. **Mechanical issues first**: `npx docguard-cli fix --write` applies safe,
+   provenance-checked fixes (broken anchors, stale counts/versions). Never
+   hand-edit what the tool can fix deterministically.
+2. **Prose/content issues**: follow the `/docguard.fix` workflow (research →
+   write real content).
+3. **Genuine false positives**: suppress at the finding site with the code —
+   `// docguard:ignore <CODE>` on (or above) the flagged line — or mark a whole
+   validator not-applicable in a doc:
+   `<!-- docguard:validator <key> n/a — reason -->`. Always include the reason.
+   Never suppress to silence a real issue.
+4. If `semanticClaims.count > 0`, offer to run `npx docguard-cli verify --semantic`
+   and check each extracted claim against the code — a green guard asserts
+   structure, not the truth of documented numbers.
 
-## Step 3: Report
+## Step 4: Report
 
 Show the user:
-1. Which checks passed/failed (with severity)
-2. What was fixed
-3. Final CDD score
+1. `status` and pass/total, plus anything in `coverage.unclassified` (docs no
+   validator watches — suggest enrolling or ignoring them)
+2. Each finding fixed (by code), each suppressed (with reason), each reported
+   as a false positive
+3. Final score: `npx docguard-cli score`

package/templates/commands/docguard.init.md

@@ -21,21 +21,33 @@ npx docguard-cli init
 
 This creates the folder structure and template files. The templates are skeletons — they need real content.
 
-## Step 2: Detect and Configure Project Type
+## Step 2: Pick the Right Profile
+
+`init` auto-detects the project type, but verify the profile fits — it sets
+which docs are required (a CLI shouldn't be forced to document an HTTP API):
+
+| Signal | Profile in `.docguard.json` |
+|--------|------------------------------|
+| Has `bin` field / CLI tool | `"profile": "cli"` |
+| Publishable package | `"profile": "library"` |
+| Side project / prototype | `"profile": "starter"` |
+| Team web app / API | `"profile": "standard"` (default) |
+| Regulated / strict | `"profile": "enterprise"` |
+
+Only schema-valid keys belong in `.docguard.json` — check
+`schemas/docguard-config.schema.json` (shipped in the package) before adding
+anything. If the project has domain collections (extractors, plugins, rules…),
+declare them so documented counts are verified against code:
+`"collections": { "extractors": "src/extractors/*.py" }`.
+
+For an EXISTING codebase, prefer reverse-engineering over blank skeletons:
 
 ```bash
-cat package.json
+npx docguard-cli generate --plan --write
 ```
 
-Create `.docguard.json` based on what you find:
-
-| Signal | Setting |
-|--------|---------|
-| Has `bin` field | `projectType: "cli"` |
-| Has react/next/vue | `projectType: "webapp"`, `needsE2E: true` |
-| Has express/fastify | `projectType: "api"`, `needsEnvVars: true` |
-| Has database deps | `needsDatabase: true` |
-| Default | `projectType: "library"` |
+This pre-fills code-truth sections (routes, schemas, env vars) and leaves you
+an agent-task list for the prose.
 
 ## Step 3: Write Real Documentation
 

package/templates/commands/docguard.review.md

@@ -22,8 +22,21 @@ npx docguard-cli score
 ```
 
 Read all output. Identify where documentation no longer matches the codebase.
+Findings carry stable codes — `npx docguard-cli explain <CODE>` when unclear.
 
-## Step 2: Semantic Analysis (Beyond CLI)
+## Step 2: Verify Documented Claims Against Code
+
+```bash
+npx docguard-cli verify --semantic
+```
+
+This extracts every checkable claim in the canonical docs — counts, limits,
+rate numbers, retention windows, status enums — as a task list with the nearest
+cited code path. **You perform each verification**: read the cited code, compare
+the value, and report every mismatch with both values. This is the highest-value
+review step; deterministic validators cannot judge these.
+
+## Step 3: Semantic Analysis (Beyond CLI)
 
 For each canonical doc, verify alignment with actual code:
 
@@ -35,16 +48,20 @@ For each canonical doc, verify alignment with actual code:
 | Test Coverage | Critical flows in TEST-SPEC.md have actual test files |
 | Terminology | Same concepts named consistently across all docs |
 
-## Step 3: Update Stale Docs
+## Step 4: Update Stale Docs
 
 For each stale or drifted document:
-1. Read the relevant source code files
-2. Update the specific section that changed
-3. Update the `docguard:last-reviewed` date to today
-4. If the change is intentional drift, add an entry to DRIFT-LOG.md
-5. Add entry to CHANGELOG.md under [Unreleased]
+1. **Decide which side is wrong first.** Canonical docs are the spec — if the
+   code regressed from a documented decision, flag the code (or record a
+   `// DRIFT: reason` + DRIFT-LOG.md entry); don't rewrite the doc to match a
+   regression.
+2. Sections inside `<!-- docguard:section ... source=code -->` markers are
+   regenerated — run `npx docguard-cli sync --write` instead of editing by hand.
+3. For hand-maintained sections: read the relevant source, update the specific
+   section, refresh `docguard:last-reviewed` to today.
+4. Add entry to CHANGELOG.md under [Unreleased].
 
-## Step 4: Verify
+## Step 5: Verify
 
 ```bash
 npx docguard-cli guard

package/templates/commands/docguard.update.md

@@ -16,11 +16,12 @@ You are an AI agent that updates documentation to reflect recent code changes.
 ## Step 1: Identify What Changed
 
 ```bash
+npx docguard-cli diff --since HEAD~5
 git log --oneline -10
-git diff HEAD~5 --stat
 ```
 
-Read the recent commits. Understand what code changed and why.
+`diff --since` maps the changed files directly to the canonical docs they
+affect — read its output first; the git log supplies the "why".
 
 ## Step 2: Check Which Docs Are Affected
 
@@ -38,10 +39,19 @@ For each changed file, determine which canonical doc it affects:
 
 ## Step 3: Update Each Affected Doc
 
-For each affected document:
+Mechanical layers first — they update marked sections and counts without AI
+judgment:
+
+```bash
+npx docguard-cli sync --write
+npx docguard-cli fix --write
+```
+
+Then, for each remaining affected document:
 1. Read the current document
 2. Read the relevant source code changes
-3. Update the specific section that changed
+3. Update the specific section that changed (never hand-edit inside
+   `<!-- docguard:section ... source=code -->` markers — sync owns those)
 4. Update the `docguard:last-reviewed` date to today
 5. Add entry to CHANGELOG.md under [Unreleased]