docguard-cli 0.38.0 → 0.40.0

package/schemas/docguard-evidence.schema.json

@@ -0,0 +1,169 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raccioly.github.io/docguard/schemas/docguard-evidence.schema.json",
+  "title": "DocGuard evidence-scoped verification manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["$schema", "schemaVersion", "declarations"],
+  "properties": {
+    "$schema": { "const": "https://raccioly.github.io/docguard/schemas/docguard-evidence.schema.json" },
+    "schemaVersion": { "const": 1 },
+    "declarations": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 128,
+      "items": { "$ref": "#/$defs/declaration" }
+    }
+  },
+  "$defs": {
+    "safePath": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*(?:^|/)\\.local(?:/|$))(?!.*(?:^|/)\\.env(?:\\.|/|$))[^\\\\\\u0000:]+$"
+    },
+    "declaration": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "applicability", "target", "source", "predicate"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{2,127}$" },
+        "applicability": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["mode"],
+          "properties": { "mode": { "const": "always" } }
+        },
+        "target": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["document", "heading", "statement"],
+          "properties": {
+            "document": { "$ref": "#/$defs/safePath" },
+            "heading": { "type": "string", "minLength": 1, "maxLength": 200 },
+            "statement": { "type": "string", "minLength": 1, "maxLength": 1000 }
+          }
+        },
+        "source": {
+          "oneOf": [
+            { "$ref": "#/$defs/jsonSource" },
+            { "$ref": "#/$defs/collectionSource" },
+            { "$ref": "#/$defs/oasdiffSource" },
+            { "$ref": "#/$defs/bufSource" }
+          ]
+        },
+        "predicate": {
+          "oneOf": [
+            { "$ref": "#/$defs/equalsPredicate" },
+            { "$ref": "#/$defs/setPredicate" },
+            { "$ref": "#/$defs/countPredicate" },
+            { "$ref": "#/$defs/noFindingsPredicate" }
+          ]
+        }
+      }
+    },
+    "jsonSource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["adapter", "path", "pointer"],
+      "properties": {
+        "adapter": { "const": "json-pointer" },
+        "path": { "$ref": "#/$defs/safePath" },
+        "pointer": { "type": "string", "maxLength": 512, "pattern": "^(?:$|/)" }
+      }
+    },
+    "collectionSource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["adapter", "glob", "allowEmpty"],
+      "properties": {
+        "adapter": { "const": "collection-count" },
+        "glob": { "$ref": "#/$defs/safePath" },
+        "allowEmpty": { "type": "boolean" }
+      }
+    },
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "sha256"],
+      "properties": {
+        "path": { "$ref": "#/$defs/safePath" },
+        "sha256": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+      }
+    },
+    "reportBase": {
+      "type": "object",
+      "required": ["adapter", "adapterVersion", "path", "producerVersion", "command", "inputs"],
+      "properties": {
+        "adapterVersion": { "type": "integer", "minimum": 1, "maximum": 100 },
+        "path": { "$ref": "#/$defs/safePath" },
+        "producerVersion": { "type": "string", "minLength": 1, "maxLength": 80 },
+        "inputs": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 32,
+          "items": { "$ref": "#/$defs/input" }
+        }
+      }
+    },
+    "oasdiffSource": {
+      "allOf": [
+        { "$ref": "#/$defs/reportBase" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "adapter": { "const": "oasdiff" },
+            "adapterVersion": {}, "path": {}, "producerVersion": {}, "inputs": {},
+            "command": { "type": "string", "minLength": 1, "maxLength": 40 }
+          }
+        }
+      ]
+    },
+    "bufSource": {
+      "allOf": [
+        { "$ref": "#/$defs/reportBase" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "adapter": { "const": "buf" },
+            "adapterVersion": {}, "path": {}, "producerVersion": {}, "inputs": {},
+            "command": { "type": "string", "minLength": 1, "maxLength": 40 }
+          }
+        }
+      ]
+    },
+    "equalsPredicate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "valueType"],
+      "properties": {
+        "kind": { "const": "equals" },
+        "valueType": { "enum": ["string", "number", "boolean", "null"] }
+      }
+    },
+    "setPredicate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "itemType", "separator"],
+      "properties": {
+        "kind": { "const": "set-equals" },
+        "itemType": { "const": "string" },
+        "separator": { "type": "string", "minLength": 1, "maxLength": 16 }
+      }
+    },
+    "countPredicate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind"],
+      "properties": { "kind": { "const": "count-equals" } }
+    },
+    "noFindingsPredicate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind"],
+      "properties": { "kind": { "const": "no-findings" } }
+    }
+  }
+}

package/schemas/docguard-feedback-fixture.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raccioly.github.io/docguard/schemas/docguard-feedback-fixture.schema.json",
+  "title": "DocGuard synthetic feedback fixture",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["$schema", "schemaVersion", "classification", "detector", "parserTier", "config", "expectedIdentity", "interestingness", "fixture", "oppositeControl", "provenance"],
+  "properties": {
+    "$schema": { "const": "https://raccioly.github.io/docguard/schemas/docguard-feedback-fixture.schema.json" },
+    "schemaVersion": { "const": 1 },
+    "classification": { "enum": ["false_positive", "false_negative", "unsupported_syntax", "ambiguous", "policy_disagreement"] },
+    "detector": {
+      "type": "object", "additionalProperties": false, "required": ["code", "validator"],
+      "properties": { "code": { "type": "string", "pattern": "^[A-Z]{3}[0-9]{3}$" }, "validator": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9]{1,63}$" } }
+    },
+    "parserTier": { "enum": ["js-ast", "py-ast", "regex-fallback", "fallback-language", "mixed", "not-applicable"] },
+    "config": { "type": "object" },
+    "expectedIdentity": { "type": "string", "pattern": "^[A-Z]{3}[0-9]{3}@.+$" },
+    "interestingness": {
+      "type": "object", "additionalProperties": false, "required": ["predicate"],
+      "properties": { "predicate": { "enum": ["finding_present", "finding_absent", "validator_unsupported"] } }
+    },
+    "fixture": { "$ref": "#/$defs/fileSet" },
+    "oppositeControl": { "$ref": "#/$defs/fileSet" },
+    "provenance": {
+      "type": "object", "additionalProperties": false, "required": ["synthetic", "redactionAttested"],
+      "properties": { "synthetic": { "const": true }, "redactionAttested": { "const": true } }
+    },
+    "contribution": {
+      "type": "object", "additionalProperties": false, "required": ["testOnly", "scopeDocumented", "benchmarkDelta"],
+      "properties": {
+        "testOnly": { "const": true }, "scopeDocumented": { "const": true },
+        "benchmarkDelta": {
+          "type": "object", "additionalProperties": false,
+          "required": ["falsePositives", "falseNegatives", "unsupportedCases", "abstainedSupportedCases"],
+          "properties": {
+            "falsePositives": { "type": "integer", "minimum": 0 }, "falseNegatives": { "type": "integer", "minimum": 0 },
+            "unsupportedCases": { "type": "integer", "minimum": 0 }, "abstainedSupportedCases": { "type": "integer", "minimum": 0 }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "fileSet": {
+      "type": "object", "additionalProperties": false, "required": ["files"],
+      "properties": { "files": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "$ref": "#/$defs/file" } } }
+    },
+    "file": {
+      "type": "object", "additionalProperties": false, "required": ["path", "content"],
+      "properties": { "path": { "type": "string", "minLength": 1 }, "content": { "type": "string", "maxLength": 131072 } }
+    }
+  }
+}

package/schemas/docguard-task-context.schema.json

@@ -0,0 +1,144 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raccioly.github.io/docguard/schemas/docguard-task-context.schema.json",
+  "title": "DocGuard task-specific context packet",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "task", "provenance", "assurance", "selection", "excerpts", "pointers", "verification", "navigation", "limitations", "coreDigest"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "docguard.task-context" },
+    "task": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["digest", "characters"],
+      "properties": {
+        "digest": { "$ref": "#/$defs/digest" },
+        "characters": { "type": "integer", "minimum": 1, "maximum": 2000 }
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["git", "registry"],
+      "properties": {
+        "git": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["revision", "dirty", "status"],
+          "properties": {
+            "revision": { "type": ["string", "null"], "pattern": "^[a-f0-9]{40,64}$" },
+            "dirty": { "type": ["boolean", "null"] },
+            "status": { "enum": ["snapshot", "unknown"] }
+          }
+        },
+        "registry": { "enum": ["snapshot", "unavailable"] }
+      }
+    },
+    "assurance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["scope", "factualAccuracy", "verification"],
+      "properties": {
+        "scope": { "const": "retrieval-only" },
+        "factualAccuracy": { "type": "null" },
+        "verification": { "const": "unverified" }
+      }
+    },
+    "selection": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "threshold", "candidatesConsidered", "selectedExcerpts", "omittedCandidates", "excludedLifecycleDocuments", "limits", "truncated"],
+      "properties": {
+        "status": { "enum": ["targeted", "abstained"] },
+        "threshold": { "type": "integer", "minimum": 1 },
+        "candidatesConsidered": { "type": "integer", "minimum": 0 },
+        "selectedExcerpts": { "type": "integer", "minimum": 0, "maximum": 6 },
+        "omittedCandidates": { "type": "integer", "minimum": 0 },
+        "excludedLifecycleDocuments": { "type": "integer", "minimum": 0 },
+        "limits": { "$ref": "#/$defs/limits" },
+        "truncated": { "type": "boolean" }
+      }
+    },
+    "excerpts": { "type": "array", "maxItems": 6, "items": { "$ref": "#/$defs/excerpt" } },
+    "pointers": { "type": "array", "maxItems": 8, "items": { "$ref": "#/$defs/pointer" } },
+    "verification": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/verification" } },
+    "navigation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["canonicalDocs", "activeSpecs"],
+      "properties": {
+        "canonicalDocs": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/path" } },
+        "activeSpecs": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["specId", "path"],
+            "properties": { "specId": { "$ref": "#/$defs/specId" }, "path": { "$ref": "#/$defs/path" } }
+          }
+        }
+      }
+    },
+    "limitations": { "type": "array", "minItems": 2, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+    "coreDigest": { "$ref": "#/$defs/digest" }
+  },
+  "$defs": {
+    "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "path": { "type": "string", "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\).+" },
+    "specId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._/-]{2,127}$" },
+    "limits": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["taskChars", "documents", "chunks", "selectedExcerpts", "linesPerExcerpt", "totalChars", "pointers"],
+      "properties": {
+        "taskChars": { "const": 2000 },
+        "documents": { "const": 32 },
+        "chunks": { "const": 256 },
+        "selectedExcerpts": { "const": 6 },
+        "linesPerExcerpt": { "const": 16 },
+        "totalChars": { "const": 6000 },
+        "pointers": { "const": 8 }
+      }
+    },
+    "excerpt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "kind", "specId", "heading", "startLine", "endLine", "fileHash", "excerptHash", "score", "reasons", "content"],
+      "properties": {
+        "path": { "$ref": "#/$defs/path" },
+        "kind": { "enum": ["canonical", "active-spec", "project-rules"] },
+        "specId": { "anyOf": [{ "$ref": "#/$defs/specId" }, { "type": "null" }] },
+        "heading": { "type": "string", "minLength": 1 },
+        "startLine": { "type": "integer", "minimum": 1 },
+        "endLine": { "type": "integer", "minimum": 1 },
+        "fileHash": { "$ref": "#/$defs/digest" },
+        "excerptHash": { "$ref": "#/$defs/digest" },
+        "score": { "type": "integer", "minimum": 1 },
+        "reasons": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+        "content": { "type": "string", "maxLength": 6000 }
+      }
+    },
+    "pointer": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "kind", "requirements", "reasons", "hash"],
+      "properties": {
+        "path": { "$ref": "#/$defs/path" },
+        "kind": { "enum": ["task-path", "cited-source", "implementation", "test"] },
+        "requirements": { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._/-]{2,127}#(?:FR|SC|NFR)-[0-9]{3}$" } },
+        "reasons": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+        "hash": { "$ref": "#/$defs/digest" }
+      }
+    },
+    "verification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["command", "purpose"],
+      "properties": {
+        "command": { "type": "string", "minLength": 1 },
+        "purpose": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/templates/AGENTS.md.template

@@ -52,10 +52,15 @@ npx docguard fix --format prompt
 When working on this project, follow this workflow:
 
 1. **Before any work**: Run `npx docguard guard` to understand current compliance state
-2. **After making changes**: Run `npx docguard fix --format prompt` to find remaining issues
-3. **Fix what DocGuard reports**: Each issue includes an `ai_instruction` telling you exactly what to do
-4. **Run guard again**: Verify all issues are resolved before committing
-5. **Update CHANGELOG.md**: All changes need a changelog entry
+2. **Check declared facts**: If `.docguard-evidence.json` exists, run `npx docguard verify --evidence --format json`; a pass covers only its selected statement
+3. **After making changes**: Run `npx docguard fix --format prompt` to find remaining issues
+4. **Fix what DocGuard reports**: Each issue includes an `ai_instruction` telling you exactly what to do
+5. **Run guard again**: Verify all issues are resolved before committing
+6. **Update CHANGELOG.md**: All changes need a changelog entry
+
+Preserve the five evidence states. Review approved intent before changing either
+side of a contradiction. Undeclared prose and whole-document accuracy remain
+unverified.
 
 ### Auto-Fix Available Issues
 

package/templates/ci/github-actions.yml

@@ -21,17 +21,17 @@ jobs:
           echo "DOCGUARD_REPORT=$RUNNER_TEMP/docguard-report.json" >> "$GITHUB_ENV"
           echo "DOCGUARD_LOG=$RUNNER_TEMP/docguard-stderr.log" >> "$GITHUB_ENV"
 
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0 # Freshness needs the complete commit history.
           persist-credentials: false
 
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: '20'
 
       - name: Install DocGuard
-        run: npm install --global --ignore-scripts docguard-cli@0.38.0
+        run: npm install --global --ignore-scripts docguard-cli@0.40.0
 
       - name: Run DocGuard
         shell: bash
@@ -70,7 +70,7 @@ jobs:
 
       - name: Upload Report
         if: always()
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: docguard-report
           path: |

package/templates/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.
 

package/templates/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

package/templates/evidence-manifest.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://raccioly.github.io/docguard/schemas/docguard-evidence.schema.json",
+  "schemaVersion": 1,
+  "declarations": [
+    {
+      "id": "policy.retention-days",
+      "applicability": { "mode": "always" },
+      "target": {
+        "document": "docs-canonical/SECURITY.md",
+        "heading": "Data retention",
+        "statement": "Audit records are retained for {{value}} days."
+      },
+      "source": {
+        "adapter": "json-pointer",
+        "path": "config/policy.json",
+        "pointer": "/retentionDays"
+      },
+      "predicate": { "kind": "equals", "valueType": "number" }
+    }
+  ]
+}

package/templates/feedback-fixture.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://raccioly.github.io/docguard/schemas/docguard-feedback-fixture.schema.json",
+  "schemaVersion": 1,
+  "classification": "false_positive",
+  "detector": { "code": "SEC001", "validator": "security" },
+  "parserTier": "js-ast",
+  "config": { "profile": "starter", "diskCache": false, "validators": { "security": true } },
+  "expectedIdentity": "SEC001@src/case.js",
+  "interestingness": { "predicate": "finding_present" },
+  "fixture": { "files": [{ "path": "src/case.js", "content": "const password = \"validation message with several words\";\n" }] },
+  "oppositeControl": { "files": [{ "path": "src/case.js", "content": "const password = \"real-looking-password\";\n" }] },
+  "provenance": { "synthetic": true, "redactionAttested": true },
+  "contribution": {
+    "testOnly": true,
+    "scopeDocumented": true,
+    "benchmarkDelta": { "falsePositives": 0, "falseNegatives": 0, "unsupportedCases": 0, "abstainedSupportedCases": 0 }
+  }
+}