docguard-cli 0.38.0__tar.gz → 0.40.0__tar.gz

{docguard_cli-0.38.0/templates → docguard_cli-0.40.0/.agent}/commands/docguard.guard.md

@@ -28,6 +28,7 @@ Read the JSON contract — do not parse prose:
 | `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[]` |
+| `evidence` | Exact declaration states and their explicit scope limitation |
 | `semanticClaims.count` | Documented counts/limits/enums NOT yet verified against code |
 | `validators[]` | Per-validator results, including `na` (nothing to validate ≠ pass) |
 
@@ -53,7 +54,10 @@ Read the JSON contract — do not parse prose:
    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`
+4. If `evidence.configured`, resolve every contradiction/stale/inconclusive/
+   unsupported declaration with `npx docguard-cli verify --evidence --format json`.
+   A verified declaration covers only its selected statement.
+5. If `semanticClaims.count > 0`, 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.
 

{docguard_cli-0.38.0 → docguard_cli-0.40.0/.agent}/commands/docguard.review.md

@@ -27,10 +27,15 @@ Findings carry stable codes — `npx docguard-cli explain <CODE>` when unclear.
 ## Step 2: Verify Documented Claims Against Code
 
 ```bash
+npx docguard-cli verify --evidence --format json
 npx docguard-cli verify --semantic
 ```
 
-This extracts every checkable claim in the canonical docs — counts, limits,
+Review exact declaration states first. A contradiction may indicate a code
+regression from approved intent; stale evidence requires regenerating the saved
+upstream report. A scoped pass does not verify its containing document.
+
+The semantic command then extracts remaining checkable claims 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

{docguard_cli-0.38.0 → docguard_cli-0.40.0}/.agent/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.38.0
+  version: 0.40.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.38.0 -->
+<!-- docguard:version: 0.40.0 -->
 
 # DocGuard Fix Skill
 
@@ -44,7 +44,9 @@ npx docguard-cli fix --write 2>&1
 
 Removes endpoints documented in `docs-canonical/API-REFERENCE.md` that the OpenAPI
 spec confirms no longer exist (table row + detail block). Only edits
-`docguard:generated` docs, idempotent, prints what changed. Don't hand-edit these.
+`docguard:generated` whole documents. Mapped human docs expose only unique
+`source=code` sections, and `--force` cannot bypass ownership. The operation is
+idempotent and prints what changed. Don't hand-edit generated sections.
 
 ### Step 1: Diagnose Current State
 
@@ -217,6 +219,15 @@ After all fixes are applied, output:
 - **Log deviations** — if you deviate from canonical expectations, add `// DRIFT: reason` in DRIFT-LOG.md
 - **Never include secrets** — document variable/secret NAMES only, never actual values
 
+## Evidence Findings
+
+Run `docguard verify --evidence --format json` when guard returns an `EVD` code.
+Repair invalid, missing, ambiguous, stale, or unsupported evidence at the named
+source. For `EVD002`, inspect the approved requirement and implementation before
+editing either side; current code does not automatically override canonical
+intent. Rerun evidence verification after the targeted change. Never broaden a
+statement template or remove an evidence declaration merely to make guard pass.
+
 ## Integration with Spec Kit
 
 If `.specify/` directory exists:

{docguard_cli-0.38.0/extensions/spec-kit-docguard → docguard_cli-0.40.0/.agent}/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.38.0
+  version: 0.40.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.38.0 -->
+<!-- docguard:version: 0.40.0 -->
 
 # DocGuard Guard Skill
 
@@ -44,12 +44,12 @@ Execute DocGuard's full guard validator suite against the current project, parse
 Execute the guard command and capture full output:
 
 ```bash
-npx docguard-cli guard 2>&1
+npx docguard-cli guard --format json
 ```
 
 If in a DocGuard development environment (cli/docguard.mjs exists), use:
 ```bash
-node cli/docguard.mjs guard 2>&1
+node cli/docguard.mjs guard --format json
 ```
 
 ### Step 2: Parse Validator Results
@@ -75,6 +75,7 @@ Classify every non-passing check using this priority matrix:
 - Structure failures (missing canonical docs)
 - Security failures (hardcoded secrets, missing SECURITY.md)
 - Test-Spec failures (tests don't match spec)
+- Evidence contradictions or an invalid evidence manifest
 
 **HIGH (fix before commit)**:
 - Doc Sections failures (missing required sections)
@@ -139,7 +140,7 @@ For each finding, provide a **specific, actionable fix** — not "fix the issue"
 
 Based on the triage results:
 
-- **If all PASS**: "All validators passed. Project is CDD-compliant. Ready to commit."
+- **If all PASS**: "All configured validators passed. Report declared evidence coverage and any remaining heuristic claims; uncaptured prose is still unverified."
 - **If only MEDIUM/LOW warnings**: "Non-blocking warnings found. Safe to commit, but consider running `/docguard.fix` for automated remediation."
 - **If HIGH or CRITICAL failures**: "Blocking issues found. Fix these before committing. Suggest running `/docguard.fix --doc [most impactful doc]` next."
 
@@ -157,6 +158,16 @@ Present the user with options:
 - **Track progress** — if user runs guard multiple times, compare before/after
 - If user provides `$ARGUMENTS` like "just structure" or "only security", filter report to those validators
 
+## Evidence State Rules
+
+When the JSON payload contains `evidence`, preserve its state names exactly.
+Treat `verified-within-scope` as a pass only for that declaration. Treat
+`contradicted` as a high-confidence failure. For `stale`, regenerate the saved
+upstream report and hashes before reviewing prose. For `inconclusive`, restore
+or narrow the missing/ambiguous input. For `unsupported`, keep the finding
+visible and request a paired synthetic fixture before expanding support. Never
+rewrite approved intent from current code automatically.
+
 ## Integration with Spec Kit (Extension-First)
 
 DocGuard is a spec-kit extension. When this project has a `.specify/` directory:

{docguard_cli-0.38.0/extensions/spec-kit-docguard → docguard_cli-0.40.0/.agent}/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.38.0
+  version: 0.40.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.38.0 -->
+<!-- docguard:version: 0.40.0 -->
 
 # DocGuard Review Skill
 
@@ -51,7 +51,9 @@ Execute DocGuard's diagnostic and scoring tools:
 ```bash
 npx docguard-cli diagnose 2>&1
 npx docguard-cli score 2>&1
-npx docguard-cli guard 2>&1
+npx docguard-cli guard --format json
+npx docguard-cli verify --evidence --format json
+npx docguard-cli verify --semantic --format json
 ```
 
 Record:
@@ -59,6 +61,7 @@ Record:
 - CDD maturity score (0-100)
 - ALCOA+ compliance attributes
 - Category breakdown
+- Exact declared evidence states and the remaining heuristic claim tasks
 
 ### Step 3: Semantic Cross-Document Analysis
 
@@ -180,6 +183,8 @@ Ask: "Would you like me to fix the top N issues? (I'll show you what I plan to c
 - **Compare actual code vs docs** — don't just validate formatting
 - **Limit findings to 50** — aggregate overflow in a summary count
 - **Prioritize high-signal findings** — one CRITICAL finding is worth ten LOW findings
+- **Preserve evidence scope** — a verified declaration covers one selected statement, while undeclared prose and whole-document accuracy remain review work
+- **Preserve approved intent** — a contradiction can mean implementation regressed; determine which side owns truth before recommending an edit
 
 ## Context
 

{docguard_cli-0.38.0/extensions/spec-kit-docguard → docguard_cli-0.40.0/.agent}/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.38.0
+  version: 0.40.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.38.0 -->
+<!-- docguard:version: 0.40.0 -->
 
 # DocGuard Score Skill
 
@@ -173,6 +173,7 @@ If user has run score before (check git log for score badge changes):
 - **Be actionable** — every recommendation must have a specific action
 - **Compare before/after** — if user has previously run score in this session, show improvement
 - **Focus on ROI** — surface the cheapest fixes with the biggest score impact first
+- **Keep assurance separate** — report `assurance.declaredEvidence` and remaining `unverifiedClaims` beside the structural score; never convert a scoped evidence pass into an accuracy score for a document or project
 
 ## Context
 

{docguard_cli-0.38.0 → docguard_cli-0.40.0}/.agent/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.38.0
+  version: 0.40.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.38.0 -->
+<!-- docguard:version: 0.40.0 -->
 
 # DocGuard Sync Skill
 
@@ -76,6 +76,7 @@ For each `🤖 Prose to review` entry:
 
 ```bash
 npx --yes docguard-cli@latest guard
+npx --yes docguard-cli@latest verify --evidence
 ```
 
 Confirm there are no errors. If the API surface drifted (`API-Surface` failures),
@@ -102,7 +103,8 @@ that ref. Use that diff to:
 |---|---|
 | `↻ docs-canonical/API-REFERENCE.md → endpoints` | Code-truth refreshed by `--write`. No action needed. |
 | `🤖 docs-canonical/API-REFERENCE.md → overview` | Open the doc; update the `overview` prose to reflect the new endpoint set. |
-| `Skipped … not marked docguard:generated` | The doc isn't owned by DocGuard. Either add the marker (and commit ownership) or skip with `--force`. |
+| `Skipped … not marked docguard:generated` | A default-path doc lacks whole-document ownership. Review before using `--force`; a mapped human doc still requires a unique `source=code` section. |
+| `malformed or duplicate docguard:section markers` | Stop. Repair ownership markers explicitly; `--force` cannot authorize the write. |
 | `Documentation memory is up to date` | Done — no drift. |
 
 ## Anti-patterns (do NOT do these)
@@ -110,3 +112,4 @@ that ref. Use that diff to:
 - ❌ Editing inside `<!-- docguard:section source=code -->` — DocGuard will rewrite it on the next sync.
 - ❌ Removing the markers to "make the doc look cleaner" — that breaks future sync/regeneration.
 - ❌ Skipping `sync --write` and editing the code section by hand — let DocGuard do it.
+- ❌ Rewriting an evidence-bound human statement from generated code alone — rerun the declared predicate and review approved intent first.