docguard-cli 0.35.0__tar.gz → 0.36.0__tar.gz

{docguard_cli-0.35.0 → docguard_cli-0.36.0}/.docguardignore

@@ -38,3 +38,9 @@ templates/demo-fixture/**
 packaging/
 packaging/**
 
+
+# Generated audit reports and probe templates are historical tool output, not product source.
+websec-out/
+websec-out/**
+graphify-out/
+graphify-out/**

docguard_cli-0.36.0/.github/ISSUE_TEMPLATE/docguard-feedback.md

@@ -0,0 +1,28 @@
+---
+name: DocGuard feedback (false positive / detection gap)
+about: Contribute a synthetic reproduction of a disputed finding or missed defect.
+title: "[feedback] <CODE>: <short description>"
+labels: docguard-feedback
+---
+
+- **DocGuard version:**
+- **Runtime / operating system:**
+- **Finding code / detector:**
+- **Type:** false positive / missed defect / unsupported syntax / policy question
+- **Existing open and closed issues/PRs checked:**
+
+**Expected behavior**
+
+**Actual behavior and exact command**
+
+**Minimal synthetic reproduction**
+
+Provide invented source and minimal configuration. Review all content before sharing. Full local feedback records can contain private paths and diagnostic text; do not attach them by default.
+
+**Neighboring valid or invalid case**
+
+What closely related example should still pass or fail after a fix?
+
+**Contribution**
+
+A report or a test-only contribution is welcome. See CONTRIBUTING.md, "Turn a finding into a regression test". No credentials or private source are required.

{docguard_cli-0.35.0 → docguard_cli-0.36.0}/.github/scripts/speckit-submission.py

@@ -61,7 +61,7 @@ def build(version: str, download_url: str):
             "name": "DocGuard — CDD Enforcement",
             "id": "docguard",
             "description": (
-                "The only doc-integrity engine with an MCP server, "
+                "A documentation-integrity engine with an MCP server, "
                 "SARIF/JUnit output, and a deterministic zero-LLM core. "
                 "Validates, scores, and traces documentation against code — "
                 "27 validators, stable finding codes, adoption baseline for "
@@ -125,7 +125,7 @@ def build(version: str, download_url: str):
         ("tags", "Tags",
          "documentation, validation, quality, cdd, traceability, ai-agents, enforcement, spec-kit"),
         ("features", "Key Features",
-         "- 19-validator quality gate with severity triage and a remediation plan\n"
+         "- Configurable quality gate with severity triage and a remediation plan\n"
          "- AI-driven documentation repair with codebase research and validation loops\n"
          "- Cross-document semantic consistency analysis (read-only review)\n"
          "- CDD maturity score with an ROI-based improvement roadmap\n"
@@ -134,10 +134,10 @@ def build(version: str, download_url: str):
         ("testing", "Testing Checklist", None),
         ("requirements", "Submission Requirements", None),
         ("testing-details", "Testing Details",
-         "**Tested on:** Linux + macOS with the spec-kit CLI.\n\n"
+         "**Release verification:** Record the platforms and results actually tested before submission.\n\n"
          "**Install:**\n```bash\n"
          f"specify extension add docguard --from {download_url}\n```\n\n"
-         "**Scenarios verified:**\n"
+         "**Scenarios to verify for this release:**\n"
          "1. Extension installs from the release ZIP without manifest validation errors.\n"
          "2. All six `speckit.docguard.*` commands resolve and run.\n"
          "3. The three workflow hooks register against spec-kit's lifecycle."),
@@ -179,7 +179,7 @@ def render_body(fields, checkbox_items) -> str:
     blocks = []
     for fid, label, value in fields:
         if value is None:  # checkbox group
-            ticked = "\n".join(f"- [x] {item}" for item in checkbox_items[fid])
+            ticked = "\n".join(f"- [ ] {item}" for item in checkbox_items[fid])
             blocks.append(f"### {label}\n\n{ticked}")
         else:
             blocks.append(f"### {label}\n\n{value}")

{docguard_cli-0.35.0 → docguard_cli-0.36.0}/.github/workflows/ci.yml

@@ -7,6 +7,9 @@ on:
   pull_request:
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
   test:
     runs-on: ubuntu-latest
@@ -20,11 +23,16 @@ jobs:
         node-version: [18, 20, 22, 24]
 
     steps:
-      - uses: actions/checkout@v7
+      - name: Initialize report paths
+        shell: bash
+        run: |
+          echo "DOCGUARD_REPORT=$RUNNER_TEMP/docguard-report.json" >> "$GITHUB_ENV"
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0 # Full git history for freshness validator
 
-      - uses: actions/setup-node@v7
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: ${{ matrix.node-version }}
 
@@ -53,15 +61,16 @@ jobs:
       # on this gate existing. Normal: ~33s (node 24) to ~51s (node 18) on CI.
       # Budget is deliberately loose — it catches catastrophes, not jitter.
       - name: Run Tests (with runtime budget)
+        shell: bash
         env:
           TEST_BUDGET_MS: 120000
         run: |
           set -o pipefail
-          npm test 2>&1 | tee /tmp/test-output.txt
-          DURATION=$(grep -oE 'duration_ms [0-9]+' /tmp/test-output.txt | tail -1 | grep -oE '[0-9]+' | cut -d. -f1)
+          node --test --test-reporter=tap tests/*.test.mjs 2>&1 | tee /tmp/test-output.txt
+          DURATION=$(awk '/^# duration_ms [0-9]+/ { duration = int($3) } END { print duration }' /tmp/test-output.txt)
           if [ -z "$DURATION" ]; then
-            echo "::warning::Could not parse test duration — skipping budget check"
-            exit 0
+            echo "::error::Missing TAP suite duration — runtime budget could not be verified"
+            exit 1
           fi
           echo "Test suite duration: ${DURATION}ms (budget: ${TEST_BUDGET_MS}ms)"
           if [ "$DURATION" -gt "$TEST_BUDGET_MS" ]; then
@@ -75,9 +84,21 @@ jobs:
         run: node cli/docguard.mjs --version
 
       - name: Guard (self-check)
+        shell: bash
         run: |
           # Exit 0 = pass, Exit 1 = errors (fail CI), Exit 2 = warnings only (allow)
-          node cli/docguard.mjs guard || [ $? -eq 2 ]
+          status=0
+          node cli/docguard.mjs guard --format json > "$DOCGUARD_REPORT" || status=$?
+          cat "$DOCGUARD_REPORT"
+          [ "$status" -eq 0 ] || [ "$status" -eq 2 ]
+
+      - name: Upload guard findings
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: docguard-report-node-${{ matrix.node-version }}
+          path: ${{ env.DOCGUARD_REPORT }}
+          if-no-files-found: warn
 
       - name: Score
         run: node cli/docguard.mjs score
@@ -113,13 +134,20 @@ jobs:
           python3 -c "import xml.etree.ElementTree as ET; r=ET.parse('/tmp/guard-junit.xml').getroot(); print('junit OK:', r.attrib)"
 
       - name: Baseline roundtrip (freeze → pass → restore)
+        shell: bash
         run: |
           mkdir -p /tmp/docguard-baseline && cd /tmp/docguard-baseline
           printf '{"projectName":"bl-ci","profile":"standard"}' > .docguard.json
           mkdir -p docs-canonical && echo "# Architecture" > docs-canonical/ARCHITECTURE.md
-          node $GITHUB_WORKSPACE/cli/docguard.mjs guard --update-baseline
-          node $GITHUB_WORKSPACE/cli/docguard.mjs guard   # must exit 0 now
-          node $GITHUB_WORKSPACE/cli/docguard.mjs guard --no-baseline || [ $? -ne 0 ]
+          node "$GITHUB_WORKSPACE/cli/docguard.mjs" guard --update-baseline
+          node "$GITHUB_WORKSPACE/cli/docguard.mjs" guard   # must exit 0 now
+          status=0
+          node "$GITHUB_WORKSPACE/cli/docguard.mjs" guard --no-baseline || status=$?
+          # This incomplete standard-profile fixture has errors, not just warnings.
+          if [ "$status" -ne 1 ]; then
+            echo "::error::Expected guard --no-baseline to exit 1, got $status"
+            exit 1
+          fi
 
       # ── Cross-project tests ──
       - name: Init in temp dir
@@ -151,8 +179,8 @@ jobs:
     if: startsWith(github.ref, 'refs/tags/v')
     needs: test
     steps:
-      - uses: actions/checkout@v7
-      - uses: actions/setup-node@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: 20
           registry-url: 'https://registry.npmjs.org'

{docguard_cli-0.35.0 → docguard_cli-0.36.0}/.wolf/buglog.json

@@ -4809,6 +4809,307 @@
       "related_bugs": [],
       "occurrences": 1,
       "last_seen": "2026-09-11T16:33:44.539Z"
+    },
+    {
+      "id": "bug-291",
+      "timestamp": "2026-09-11T19:39:03.585Z",
+      "error_message": "Source changes returned stale cached documentation plans",
+      "file": "cli/scanners/memory-plan.mjs",
+      "root_cause": "Cache identity relied on manifests and HEAD, missing source content",
+      "fix": "Hash bounded relevant input content and scanner/config identity; fail closed on incomplete reads and publish atomically",
+      "tags": [
+        "cache",
+        "stale-source"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T19:39:03.585Z"
+    },
+    {
+      "id": "bug-292",
+      "timestamp": "2026-09-11T19:39:03.585Z",
+      "error_message": "Generated pre-push hook allowed an unparsed formatted score",
+      "file": "cli/commands/hooks.mjs",
+      "root_cause": "Compact JSON regex did not match real formatted command output",
+      "fix": "Parse JSON with Node and block malformed output or unavailable runtime",
+      "tags": [
+        "hooks",
+        "enforcement"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T19:39:03.585Z"
+    },
+    {
+      "id": "bug-293",
+      "timestamp": "2026-09-11T19:39:03.585Z",
+      "error_message": "Requirement IDs inside test fixtures generated false orphan findings",
+      "file": "cli/validators/traceability.mjs",
+      "root_cause": "Generic source matching treated fixture strings as declarations",
+      "fix": "Extract real comments and test labels with AST or scoped lexical fallback",
+      "tags": [
+        "traceability",
+        "false-positive"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T19:39:03.585Z"
+    },
+    {
+      "id": "bug-294",
+      "timestamp": "2026-09-11T19:39:03.585Z",
+      "error_message": "Freshness omitted configured nested documents and watcher errors escaped cleanup",
+      "file": "cli/validators/freshness.mjs",
+      "root_cause": "Narrow source/doc discovery and incomplete asynchronous lifecycle handling",
+      "fix": "Expand scoped freshness inputs; batch history; reject future dates; coalesce watch work and clean up on errors",
+      "tags": [
+        "freshness",
+        "watch"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T19:39:03.585Z"
+    },
+    {
+      "id": "bug-295",
+      "timestamp": "2026-09-11T19:39:03.585Z",
+      "error_message": "Structural score and empty claim sets implied factual accuracy",
+      "file": "cli/commands/score.mjs",
+      "root_cause": "Structural proxies and absence of extracted claims were treated as verification",
+      "fix": "Expose structural maturity separately and preserve null/unverified assurance across consumers",
+      "tags": [
+        "score",
+        "assurance"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T19:39:03.585Z"
+    },
+    {
+      "id": "bug-296",
+      "timestamp": "2026-09-11T19:39:03.585Z",
+      "error_message": "init --with ci executed a check instead of creating a workflow",
+      "file": "cli/commands/init.mjs",
+      "root_cause": "Scaffolder dispatcher called the standalone CI runner",
+      "fix": "Copy the maintained template with preserve/force behavior and destination checks",
+      "tags": [
+        "init",
+        "ci"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T19:39:03.585Z"
+    },
+    {
+      "id": "bug-297",
+      "timestamp": "2026-09-11T19:41:37.939Z",
+      "error_message": "Disk cache promotion exceeded the entry bound and accepted malformed nested plans",
+      "file": "cli/scanners/memory-plan.mjs",
+      "root_cause": "Disk-hit insertion bypassed eviction and envelope validation omitted nested consumer shapes",
+      "fix": "Use shared bounded insertion and validate cached plan shapes and depth before reuse",
+      "tags": [
+        "cache",
+        "review"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T19:41:37.939Z"
+    },
+    {
+      "id": "bug-298",
+      "timestamp": "2026-09-11T19:41:37.939Z",
+      "error_message": "Empty findings implied implementation correctness; unknown ALCOA rendered as failed",
+      "file": "cli/commands/report.mjs",
+      "root_cause": "Markdown presentation ignored assurance and unknown status",
+      "fix": "Scope empty output to configured checks and preserve unverified ALCOA status",
+      "tags": [
+        "report",
+        "assurance"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T19:41:37.939Z"
+    },
+    {
+      "id": "bug-299",
+      "timestamp": "2026-09-11T19:41:37.939Z",
+      "error_message": "Feedback reported saved file paths after persistence failed",
+      "file": "cli/commands/feedback.mjs",
+      "root_cause": "JSON emitted before writes and errors were swallowed",
+      "fix": "Persist first; expose saved/error per record; null unsaved file and exit 1 on failure",
+      "tags": [
+        "feedback",
+        "io"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T19:41:37.939Z"
+    },
+    {
+      "id": "bug-300",
+      "timestamp": "2026-09-11T19:42:37.776Z",
+      "error_message": "Workflow expression scope was invalid and baseline restoration assertion accepted every status",
+      "file": ".github/workflows/ci.yml",
+      "root_cause": "runner.temp used at job env scope; shell OR expression treated any failure as expected",
+      "fix": "Move report paths into supported step contexts and assert the expected baseline-restored exit status with executable regression coverage",
+      "tags": [
+        "ci",
+        "review",
+        "templates"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T19:42:37.776Z"
+    },
+    {
+      "id": "bug-301",
+      "timestamp": "2026-09-11T20:42:23.164Z",
+      "error_message": "OpenAPI omissions attributed to missing implementation",
+      "file": "cli/validators/api-surface.mjs",
+      "root_cause": "Contract evidence was treated as code evidence",
+      "fix": "Cross-check extracted code routes, identify authority, and refuse removal when the route exists or code evidence is unavailable",
+      "tags": [
+        "precision",
+        "regression"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T20:42:23.164Z"
+    },
+    {
+      "id": "bug-302",
+      "timestamp": "2026-09-11T20:42:23.164Z",
+      "error_message": "Formatting-only edits produced deletion review noise",
+      "file": "cli/validators/diff-suspicion.mjs",
+      "root_cause": "Removed tokens were not compared with reintroduced tokens or syntax-equivalent code",
+      "fix": "Compare additions and AST equivalence while preserving genuinely removed declarations",
+      "tags": [
+        "precision",
+        "regression"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T20:42:23.164Z"
+    },
+    {
+      "id": "bug-303",
+      "timestamp": "2026-09-11T20:42:23.164Z",
+      "error_message": "Negated or historical technology prose appeared as current use",
+      "file": "cli/validators/docs-diff.mjs",
+      "root_cause": "Technology names matched without assertion context",
+      "fix": "Recognize negation including coordinated lists; retain independent affirmative claims",
+      "tags": [
+        "precision",
+        "regression"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T20:42:23.164Z"
+    },
+    {
+      "id": "bug-304",
+      "timestamp": "2026-09-11T20:42:23.164Z",
+      "error_message": "Synthetic expectations flagged while sibling placeholders could hide real credentials",
+      "file": "cli/validators/security.mjs",
+      "root_cause": "Text-wide placeholder handling lacked expression ownership",
+      "fix": "Restrict exemptions to explicit synthetic mock expectations and preserve real-secret controls",
+      "tags": [
+        "precision",
+        "regression"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T20:42:23.164Z"
+    },
+    {
+      "id": "bug-305",
+      "timestamp": "2026-09-11T20:42:23.164Z",
+      "error_message": "Explained conditional skips warned and nested suite skips were missed",
+      "file": "cli/validators/todo-tracking.mjs",
+      "root_cause": "Skip patterns did not distinguish titles, reasons, and nested suites",
+      "fix": "Recognize static reasons and suite calls with neighboring unexplained-skip controls",
+      "tags": [
+        "precision",
+        "regression"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T20:42:23.164Z"
+    },
+    {
+      "id": "bug-306",
+      "timestamp": "2026-09-11T20:42:23.164Z",
+      "error_message": "Worker bindings missing or confused by lexical shadowing",
+      "file": "cli/shared-source.mjs",
+      "root_cause": "Worker handler scope and lexical declarations were not modeled",
+      "fix": "Resolve bindings using optional existing Babel parser and conservative tested fallback",
+      "tags": [
+        "precision",
+        "regression"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T20:42:23.164Z"
+    },
+    {
+      "id": "bug-307",
+      "timestamp": "2026-09-11T20:42:23.164Z",
+      "error_message": "Custom document layout bypassed writer and path boundaries",
+      "file": "cli/shared-doc-roles.mjs",
+      "root_cause": "Hardcoded writers and direct readers did not share role validation",
+      "fix": "Validate role paths including symlinks and private aliases; fence CLI and direct automatic writers",
+      "tags": [
+        "precision",
+        "regression"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T20:42:23.164Z"
+    },
+    {
+      "id": "bug-308",
+      "timestamp": "2026-09-11T20:42:23.164Z",
+      "error_message": "Zero matches could imply comprehensive successful checks",
+      "file": "cli/commands/guard.mjs",
+      "root_cause": "Applicability and document inventory were conflated with evidence coverage",
+      "fix": "Expose check states and reasons independently of legacy gate status",
+      "tags": [
+        "precision",
+        "regression"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T20:42:23.164Z"
+    },
+    {
+      "id": "bug-309",
+      "timestamp": "2026-09-11T20:42:23.164Z",
+      "error_message": "Missing test annotation mislabeled behavioral coverage; spec checks coupled to canonical folder",
+      "file": "cli/validators/traceability.mjs",
+      "root_cause": "Annotation absence treated as proof and missing canonical folder stopped unrelated spec checks",
+      "fix": "Describe annotation uncertainty, scan spec artifacts independently, avoid duplicate default-file warnings and non-test hints",
+      "tags": [
+        "precision",
+        "regression"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T20:42:23.164Z"
+    },
+    {
+      "id": "bug-310",
+      "timestamp": "2026-09-11T20:42:23.164Z",
+      "error_message": "Concurrent demo tests raced and kept fixtures leaked",
+      "file": "tests/demo-command.test.mjs",
+      "root_cause": "Global temporary directory counts plus swallowed ESM require error",
+      "fix": "Use isolated temporary roots and imported rmSync with finally cleanup",
+      "tags": [
+        "precision",
+        "regression"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T20:42:23.164Z"
     }
   ]
-}
+}

{docguard_cli-0.35.0 → docguard_cli-0.36.0}/.wolf/cerebrum.md

@@ -116,3 +116,7 @@
 - **2026-06-03** — Pattern for non-trivial validator tests: provoke the deterministic always-emitted section (`tech-stack` in ARCHITECTURE, `memory-plan.mjs:243`) and assert with a **control** (unpinned→stale) + **fix** (pinned→exempt). Same control discipline used for B4 (.agent created by full generate, not by --plan) and F1 (cli→low, api→normal). Keeps tests non-vacuous.
 - **2026-06-23** — Field report #6 (websec-validator): guard A+/"Accurate 100%" over a wrong "16 extractors". Its DIAGNOSIS was right (the Accurate pillar never fact-checked; the literal cause was a missing vocab noun) — but its PRESCRIPTION ("validate every claim in every doc, default-on, as warnings") was REJECTED as recall-maximizing. It re-introduces exactly the FP floods prior field reports forced us to scope away (wu-whatsappinbox ~39 FPs; Bug #2 subject-binding; changelog skipping; the explicit "precision over recall" header in semantic-claims.mjs). Chose the precision-first subset: (1) honesty fix to the `Accurate` label — display-only, gating grade untouched; (2) opt-in `config.collections` for deterministic count-drift; (3) non-gating coverage + unverified-claim VISIBILITY (surface what was NOT checked rather than deep-scan everything). Explicitly did NOT build universal prose-claim inference. Verified: headline grade unchanged (100/100 A+), ALCOA dropped 9/9→8/9 (honest), 5 new tests, no regressions (805/805 prior). Held release per user — accumulating into next version; full detail in CHANGELOG [Unreleased]. Reusable principle: a correct bug report can still carry an over-scoped fix — separate the diagnosis from the prescription.
 - **2026-06-23 (follow-up)** — "Should a clearly-documentation folder be auto-tracked, and should we UPDATE a wrong doc or SUGGEST?" Decisions: (1) Auto-detect conventional doc-home NAMES (extend-not-replace via `config.docs.dirs`, exclude via `.docguardignore`) — answers "treat all clearly-doc folders as docs" without the arbitrary-subdir FP flood. (2) Remediation policy = DocGuard detects DIVERGENCE, not which side is right (the doc may be correct intent and the CODE regressed — the CDD premise). So: auto-fix ONLY the provably-mechanical class (counts bound to a collection) and ONLY via explicit `fix --write` (provenance, fail-closed, git-reversible, never silent); everything semantic/prose is SUGGEST-only (finding + `verify --semantic`), because the deterministic core can't author correct prose and must not assume code is the source of truth. Enrichment/rewriting is an agent task the human approves — NOT a validator silently editing docs. Recorded in CHANGELOG [Unreleased] "Remediation policy".
+
+- **2026-09-11 (documentation trust)** — Structural score and surface alignment do not establish factual accuracy. Preserve null/unverified across score, CI, report, diagnose, and agent prompts; zero extracted claims does not prove prose correctness. Content-aware plan identity fixes stale uncommitted source results at a measurable hashing cost. Treat fixture strings separately from actual requirement annotations. Public feedback drafts carry registry metadata only; private source context stays local, and submission remains voluntary. `init --with ci` scaffolds a maintained workflow; installing a workflow does not enable branch protection. See docs-implementation/TRUST-ROADMAP.md for researched acceptance gates and deferred empirical work.
+
+- **2026-09-11 (enterprise precision)** — Compare baseline and current on identical disposable source snapshots. Keep originals untouched; concurrent consumer commits are not our changes. A lower warning total is not precision: new review scope can increase findings. OpenAPI absence is not implementation absence. Pair every exception with a true-defect control; source syntax and lexical ownership beat broad line matching. Custom doc roles need both direct-call and CLI write fences. Missing annotations leave behavioral coverage unknown; Python architecture coverage remains explicitly unsupported. Full-suite temp assertions must isolate process-owned fixtures and always clean up with ESM-safe imports. See docs-implementation/PRECISION-VALIDATION.md.

{docguard_cli-0.35.0 → docguard_cli-0.36.0}/AGENTS.md

@@ -1,6 +1,6 @@
 # AI Agent Instructions — DocGuard
 
-<!-- docguard:last-reviewed 2026-07-03 -->
+<!-- docguard:last-reviewed 2026-09-11 -->
 
 > This project follows **Canonical-Driven Development (CDD)**.
 > Documentation is the source of truth. Read before coding.
@@ -154,3 +154,7 @@ extensions/spec-kit-docguard/
 ### CI/CD
 - Never write a workflow using `pull_request_target` with checkout of PR-controlled refs.
 - Always pin third-party GitHub Actions to commit SHA, not @v1 or @main.
+
+## Evidence and contributions
+
+A structural score is a maturity proxy. Preserve `assurance` and nullable factual accuracy in automation; a clean guard does not establish arbitrary prose correctness. Review human intent separately from generated code facts. To challenge any finding, run `docguard feedback --code <CODE> --preview`, inspect the metadata-only public draft, and check the supplied search link for existing open and closed work. Contribute a synthetic failing example paired with a neighboring valid case. Submission remains opt-in.

{docguard_cli-0.35.0 → docguard_cli-0.36.0}/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.36.0] - 2026-09-11
+
+### Fixed
+
+- Catalog submission drafts leave verification checkboxes unchecked, remove unsupported exclusivity claims, and require release-specific evidence before submission.
+
+- Enterprise precision: preserve implementation evidence when API contracts omit routes; avoid formatting-only drift, negated technology claims, explained-skip noise, and narrowly identified synthetic mock passwords. Paired true-defect controls prevent broad suppression.
+
+- **CI scaffolding**: `init --with ci` now writes the maintained workflow instead of executing a CI check; preserves existing files and rejects unsafe paths.
+
+- Independent review fixes bound disk-cache promotion, reject malformed cached plans, preserve unknown report states, and report feedback persistence failures explicitly.
+- Memory-plan caches invalidate on relevant source/document/configuration content and scanner changes, including ordinary uncommitted edits and fresh-process reads. Partial identities bypass reuse; disk writes are atomic and cache paths avoid symlink/private targets.
+- Generated Git enforcement hooks parse formatted JSON, prefer installed local tools, and block unavailable or failed runtimes. Warning policy stays explicit. The Spec Kit after-implementation hook matches its mandatory contract.
+- Traceability distinguishes requirement annotations and test labels from fixture strings. Freshness covers configured/nested docs and source additions/deletions, batches history reads, and rejects future review dates. Watch mode handles asynchronous errors and cleans up resources.
+- CI templates use verified action commit pins, a fixed CLI version, full history, and checked JSON/exit status. The repository CI matrix explicitly emits TAP for its runtime budget.
+
+### Changed
+
+- Score, diagnose, CI, and report identify the grade as structural maturity and expose unverified factual accuracy. **Machine-contract correction:** score JSON now returns null for memory.accuracy; the former proxy is memory.structuralAlignment. Category axes use structuralAlignment. Numeric score thresholds are unchanged. Consumers must preserve unknown values.
+- Canonical documentation now reflects the Babel dependency, HTTP MCP security boundary, auxiliary files, current score contract, and limits of coverage claims. CI recipes refer to maintained templates; generated audit/probe artifacts have explicit analysis exclusions.
+
+### Added
+
+- Explicit validator applicability/check coverage, bounded Worker binding extraction, and canonical document-role mappings for existing Markdown layouts. Custom mappings support validation/read-only plans; legacy automatic writes fail closed.
+- Freshness emits low-confidence review tasks; explicit historical/superseded/deprecated documents retain their recorded intent without currentness assertions.
+
+- Feedback selection with --code or --all, including confident findings, plus --preview to skip feedback-record writes. Public issue drafts contain metadata only, and search links help contributors check open and closed issues/PRs. Test-only synthetic reproductions are documented as a contribution path.
+- Stable semantic-claim identifiers and bounded snapshot evidence for agent tasks; revision/dirty metadata and explicit uncertainty in context packs. Hashes identify inputs rather than assert review or correctness.
+- A research-backed trust roadmap with competitor capabilities, proposed evaluations, contribution economics, and staged acceptance criteria.
+
+### Migration
+
+- Regenerate installed Git hooks and update installed Spec Kit registrations to receive their new behavior. Enforcement requires an installed local DocGuard or a binary on PATH; hooks no longer fetch a package through npx. Review nullable accuracy handling in JSON consumers before upgrading automation.
+
 ## [0.35.0] - 2026-09-11
 
 ### Added

{docguard_cli-0.35.0 → docguard_cli-0.36.0}/CLAUDE.md

@@ -1,5 +1,9 @@
+<!-- docguard:last-reviewed 2026-09-11 -->
+
 # OpenWolf
 
 @.wolf/OPENWOLF.md
 
 This project uses OpenWolf for context management. Read and follow .wolf/OPENWOLF.md every session. Check .wolf/cerebrum.md before generating code. Check .wolf/anatomy.md before reading files.
+
+Follow AGENTS.md for the project workflow and current evidence contract. OpenWolf supplies historical context; current canonical requirements govern behavior.

{docguard_cli-0.35.0 → docguard_cli-0.36.0}/CONTRIBUTING.md

@@ -156,3 +156,18 @@ The following papers directly influenced DocGuard's design:
 ## License
 
 By contributing, you agree that your contributions will be licensed under the MIT License.
+
+## Turn a finding into a regression test
+
+A report or a test-only contribution is useful even when you cannot fix the detector. Start with `docguard feedback --code <CODE> --preview` for a disputed finding, or `docguard feedback --all --preview` to review active findings. Confidence is a tool estimate; high-confidence findings can still be wrong.
+
+1. Open the generated search link and check existing issues and pull requests, including closed work. Add evidence to a matching discussion instead of opening a duplicate. A previously fixed issue needs a current reproduction before it is treated as a regression.
+2. State expected behavior and actual behavior. Distinguish a false positive, a missed defect, unsupported syntax, and a policy preference. A suppression by itself does not demonstrate a bug.
+3. Create the smallest synthetic project that preserves the behavior. Use invented names and values. Include the tool version, runtime version, minimal configuration, exact command, and expected finding code. Avoid attaching the full local feedback record: it can contain private project details.
+4. Add a test in `tests/` using `node:test` and temporary directories. A false-positive case should stay clean; a neighboring real defect must still emit the finding. For a missed detection, assert the expected finding and include a similar valid case.
+5. Run the focused test against the affected version. Describe the reproduction result honestly. A test that never exercised the intended parser path is not evidence of a fix.
+6. Submit the reviewed example or a test-only PR. Mark a deliberately failing reproducer clearly; maintainers can incorporate it with the fix. Follow the repository's changelog and canonical-documentation rules when changing behavior.
+
+Maintainers should acknowledge reproducible reports, preserve contributor attribution with consent, and record the causal defect family in the regression test. Reproduction success and triage time matter more than issue volume. Do not execute arbitrary submitted scripts with repository credentials. Security-sensitive reports belong in the private channel described by SECURITY.md.
+
+The public issue draft contains metadata only. Opening a link is optional, and DocGuard never submits a report automatically.

{docguard_cli-0.35.0 → docguard_cli-0.36.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docguard-cli
-Version: 0.35.0
+Version: 0.36.0
 Summary: The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation. No Python dependencies (requires Node.js 18+).
 Project-URL: Homepage, https://github.com/raccioly/docguard
 Project-URL: Documentation, https://github.com/raccioly/docguard#readme
@@ -126,20 +126,13 @@ graph TD
 
 ## Why DocGuard?
 
-Documentation that drifts from code is worse than no documentation — it
-confidently misleads humans and AI agents alike. DocGuard treats your canonical
-docs as an enforced contract: deterministic validators diff what the docs claim
-against what the code does, on every commit, with no LLM required. The full
-thesis (and the research behind it) lives in [PHILOSOPHY.md](PHILOSOPHY.md);
-recent feature highlights moved [below](#-whats-new).
-
-The field data backs the enforcement-over-instructions bet: an ETH Zurich
-study across 138 repos / 5,694 agent PRs found the most popular style of
-agent-instruction file *hurts* agent performance, and practitioners keep
-converging on the same lesson — written rules are routinely ignored;
-programmatic checks are what agents (and humans) actually respect. That is
-exactly the layer DocGuard provides: not another instructions file, but the
-validator suite that makes the instructions and docs verifiably true.
+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. Factual accuracy stays explicitly unverified until the relevant claims have supporting evidence. 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](https://arxiv.org/abs/2602.11988v2).
+
+The development plan prioritizes accurate detection, reproducible evidence, and contributor-supplied regression cases. See [the trust roadmap](docs-implementation/TRUST-ROADMAP.md) for implementation status, proposed experiments, and acceptance criteria.
 
 ---
 
@@ -239,7 +232,7 @@ DocGuard splits drift into two kinds and is explicit about which is which:
 
 `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.
 
-### Hands-off loop (set and forget)
+### Continuous documentation workflow
 
 ```
 guard ──▶ fix --write (mechanical, auto) ──▶ guard ──▶ diagnose (agent prompts for the rest)