docguard-cli 0.30.1__tar.gz → 0.32.0__tar.gz

{docguard_cli-0.30.1/extensions/spec-kit-docguard → docguard_cli-0.32.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.30.0
+  version: 0.32.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.30.0 -->
+<!-- docguard:version: 0.32.0 -->
 
 # DocGuard Fix Skill
 

{docguard_cli-0.30.1 → docguard_cli-0.32.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.29.0
+  version: 0.32.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.29.0 -->
+<!-- docguard:version: 0.32.0 -->
 
 # DocGuard Guard Skill
 

{docguard_cli-0.30.1/extensions/spec-kit-docguard → docguard_cli-0.32.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.30.0
+  version: 0.32.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.30.0 -->
+<!-- docguard:version: 0.32.0 -->
 
 # DocGuard Review Skill
 

{docguard_cli-0.30.1/extensions/spec-kit-docguard → docguard_cli-0.32.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.30.0
+  version: 0.32.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.30.0 -->
+<!-- docguard:version: 0.32.0 -->
 
 # DocGuard Score Skill
 

{docguard_cli-0.30.1 → docguard_cli-0.32.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.29.0
+  version: 0.32.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.29.0 -->
+<!-- docguard:version: 0.32.0 -->
 
 # DocGuard Sync Skill
 

{docguard_cli-0.30.1 → docguard_cli-0.32.0}/.docguardignore

@@ -28,3 +28,13 @@ __pycache__/
 # current count would erase the historical record the audit exists to preserve.
 docs-canonical/SURFACE-AUDIT.md
 
+# Fixture/demo projects and packaging working notes — their .md files are
+# example content, not this project's documentation (doc-coverage tiering).
+# specs/ is deliberately NOT ignored: the Spec-Kit validator owns those.
+examples/
+examples/**
+templates/demo-fixture/
+templates/demo-fixture/**
+packaging/
+packaging/**
+

{docguard_cli-0.30.1 → docguard_cli-0.32.0}/.github/scripts/speckit-submission.py

@@ -63,7 +63,7 @@ def build(version: str, download_url: str):
             "description": (
                 "The only doc-integrity engine with an MCP server, SARIF "
                 "output, and a deterministic zero-LLM core. Validates, "
-                "scores, and traces documentation against code — 24 "
+                "scores, and traces documentation against code — 27 "
                 "validators, stable finding codes, GitHub Action with PR "
                 "annotations, spec-kit hooks. Pure Node.js, one pinned dep."
             ),

{docguard_cli-0.30.1 → docguard_cli-0.32.0}/.wolf/anatomy.md

@@ -1,7 +1,7 @@
 # anatomy.md
 
-> Auto-maintained by OpenWolf. Last scanned: 2026-07-06T14:46:58.012Z
-> Files: 670 tracked | Anatomy hits: 0 | Misses: 0
+> Auto-maintained by OpenWolf. Last scanned: 2026-07-11T17:47:57.144Z
+> Files: 681 tracked | Anatomy hits: 0 | Misses: 0
 
 ## ../../../../../../../tmp/
 
@@ -14,7 +14,7 @@
 ## ./
 
 - `.docguard.json` (~526 tok)
-- `.docguardignore` — # Python distribution artifacts (~199 tok)
+- `.docguardignore` — # Python distribution artifacts (~284 tok)
 - `.DS_Store` (~3818 tok)
 - `.gitignore` — Git ignore rules (~167 tok)
 - `.jules-setup.sh` — ========================================== (~631 tok)
@@ -23,7 +23,7 @@
 - `.pre-commit-hooks.yaml` — DocGuard hooks for the pre-commit framework (https://pre-commit.com). (~490 tok)
 - `action.yml` — Declares fs (~7591 tok)
 - `AGENTS.md` — AI Agent Instructions — DocGuard (~1827 tok)
-- `CHANGELOG.md` — Changelog (~45081 tok)
+- `CHANGELOG.md` — Changelog (~47879 tok)
 - `CLAUDE.md` — OpenWolf (~57 tok)
 - `CODE_OF_CONDUCT.md` — Contributor Covenant Code of Conduct (~532 tok)
 - `COMPARISONS.md` — Comparisons & Honest Limitations (~3053 tok)
@@ -40,7 +40,7 @@
 - `pr_description.md` (~260 tok)
 - `pyproject.toml` — The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project (~358 tok)
 - `README.es.md` — 🛡️ DocGuard (~1098 tok)
-- `README.md` — Project documentation (~8436 tok)
+- `README.md` — Project documentation (~8909 tok)
 - `README.pt-BR.md` — 🛡️ DocGuard (~1075 tok)
 - `ROADMAP.md` — DocGuard Roadmap (~2432 tok)
 - `SECURITY.md` — Security Policy (~357 tok)
@@ -51,6 +51,7 @@
 - `SUPPORT.md` — Support (~335 tok)
 - `test-draft.js` — Declares tmpDir (~192 tok)
 - `test-metrics.js` (~37 tok)
+- `VALIDATION.md` — Validation — how DocGuard's detectors earn their defaults (~1289 tok)
 
 ## .agent/
 
@@ -964,8 +965,8 @@
 ## cli/
 
 - `config.mjs` — DocGuard — configuration loading. (~3265 tok)
-- `docguard.mjs` — DocGuard CLI — The enforcement tool for Canonical-Driven Development (CDD) (~9606 tok)
-- `findings.mjs` — Findings — the structured, LLM-addressable result unit (v0.27). (~9698 tok)
+- `docguard.mjs` — DocGuard CLI — The enforcement tool for Canonical-Driven Development (CDD) (~10132 tok)
+- `findings.mjs` — Findings — the structured, LLM-addressable result unit (v0.27). (~10332 tok)
 - `shared-git.mjs` — Shared Git Utilities — single source of truth for `git log` plumbing (~1851 tok)
 - `shared-ignore.mjs` — Shared Ignore Utility — Unified file filtering for all validators. (~4132 tok)
 - `shared-source.mjs` — Shared Source Resolution — Monorepo-aware source discovery. (~4655 tok)
@@ -980,9 +981,11 @@
 - `feedback.mjs` — Feedback Command — close the loop with the tool's maintainers (v0.27). (~1920 tok)
 - `generate.mjs` — Generate Command — Reverse-engineer canonical docs from an existing codebase (~6250 tok)
 - `guard.mjs` — Guard Command — Validate project against its canonical documentation (~11608 tok)
+- `hooks.mjs` — Hooks Command — Generate pre-commit/pre-push hooks for DocGuard (~5102 tok)
+- `impact.mjs` — Impact Command — S-11 (~5302 tok)
 - `init.mjs` — Init Command — Initialize CDD documentation from templates (~7278 tok)
 - `llms.mjs` — llms Command — Generate llms.txt from canonical documentation (~2137 tok)
-- `mcp.mjs` — MCP Command — DocGuard as a Model Context Protocol server (stdio). (~3098 tok)
+- `mcp.mjs` — MCP Command — DocGuard as a Model Context Protocol server (stdio). (~4705 tok)
 - `memory.mjs` — Memory Command — v0.17-P2. (~2957 tok)
 - `score.mjs` — Score Command — Calculate CDD maturity score (0-100) (~12221 tok)
 - `setup.mjs` — Setup Command — Interactive onboarding wizard for DocGuard (~5280 tok)
@@ -993,22 +996,22 @@
 
 ## cli/scanners/
 
-- `agent-readability.mjs` — Agent Readability scanner — how well do this repo's docs serve an AI agent? (~2228 tok)
+- `agent-readability.mjs` — Agent Readability scanner — how well do this repo's docs serve an AI agent? (~2315 tok)
 - `instruction-audit.mjs` — Instruction Audit scanner — drift/conflict audit WITHIN agent instruction (~3668 tok)
 - `inventory.mjs` — Inventory scanners — code-truth the generator PRE-FILLS instead of leaving (~1699 tok)
 - `memory-plan.mjs` — Memory Plan — the orchestration artifact behind AI-powered Generate. (~5744 tok)
 - `project-type.mjs` — Project-Type Detection — the language-agnostic spine. (~4190 tok)
 - `routes.mjs` — Deep Route Scanner (~7712 tok)
-- `semantic-claims.mjs` — Semantic claim extractor (LLM field report #5). (~1998 tok)
+- `semantic-claims.mjs` — Semantic claim extractor (LLM field report #5). (~2120 tok)
 - `speckit.mjs` — Spec Kit Scanner — Detect, validate, and integrate with GitHub Spec Kit (~8882 tok)
 
 ## cli/validators/
 
 - `api-surface.mjs` — API-Surface Validator — Detects drift between the documented API surface (~5063 tok)
-- `architecture.mjs` — Architecture Validator — Enhanced with automatic import analysis (~3926 tok)
+- `architecture.mjs` — Architecture Validator — Enhanced with automatic import analysis (~4001 tok)
 - `canonical-sync.mjs` — Canonical-Sync Validator — v0.19-A. (~2947 tok)
 - `changelog.mjs` — Changelog Validator — Checks CHANGELOG.md has an [Unreleased] section, (~1050 tok)
-- `cross-reference.mjs` — Cross-Reference Validator — S-8 / K-7 (~4592 tok)
+- `cross-reference.mjs` — Cross-Reference Validator — S-8 / K-7 (~6034 tok)
 - `doc-quality.mjs` — Doc Quality Validator — Measures documentation writing quality (~6826 tok)
 - `docs-coverage.mjs` — Docs-Coverage Validator — Detects code features not referenced in docs. (~5516 tok)
 - `docs-diff.mjs` — Docs-Diff Validator — Checks alignment between canonical docs and code. (~3326 tok)
@@ -1019,6 +1022,7 @@
 - `generated-staleness.mjs` — Generated-Doc Staleness Validator — M-1 / S-7 (~2919 tok)
 - `metadata-sync.mjs` — Metadata Sync Validator — Detects stale version references across docs. (~2155 tok)
 - `metrics-consistency.mjs` — Metrics Consistency Validator — Detects stale hardcoded numbers in docs. (~3635 tok)
+- `reference-existence.mjs` — Two-Revision Reference-Existence validator (REF001) — v0.31.0. (~3577 tok)
 - `schema-sync.mjs` — Schema Sync Validator — Ensures database schemas are documented in DATA-MODEL.md (~2108 tok)
 - `security.mjs` — Security Validator — Basic checks for secrets in code (~2831 tok)
 - `spec-kit.mjs` — Spec-Kit Validator — Validates Spec Kit artifacts (specs/, plans/, tasks/, constitution). (~224 tok)
@@ -1026,7 +1030,7 @@
 - `surface-sync.mjs` — Surface-Sync Validator — item-level drift detection for enumerable surfaces. (~4219 tok)
 - `test-spec.mjs` — Test Spec Validator — Checks that tests exist per TEST-SPEC.md coverage rules (~4463 tok)
 - `todo-tracking.mjs` — TODO/FIXME Tracking Validator — Ensures code annotations are documented (~3916 tok)
-- `traceability.mjs` — Traceability Validator — Checks that canonical docs are linked to source code (~4324 tok)
+- `traceability.mjs` — Traceability Validator — Checks that canonical docs are linked to source code (~5647 tok)
 
 ## cli/writers/
 
@@ -1036,9 +1040,10 @@
 ## docs-canonical/
 
 - `ARCHITECTURE.md` — Architecture (~3029 tok)
-- `DATA-MODEL.md` — Data Model (~1668 tok)
+- `DATA-MODEL.md` — Data Model (~1741 tok)
 - `REQUIREMENTS.md` — Requirements (~673 tok)
 - `SURFACE-AUDIT.md` — DocGuard Surface Audit (~5703 tok)
+- `TEST-SPEC.md` — Test Specification (~1339 tok)
 
 ## docs/
 
@@ -1089,21 +1094,27 @@
 - `agents-sync.test.mjs` — CLI: run (~1367 tok)
 - `changelog.test.mjs` — Exports x, x (~1315 tok)
 - `commands.test.mjs` — DocGuard CLI Tests — Tests all commands and flags (~10442 tok)
+- `cross-reference.test.mjs` — Cross-Reference Validator — K-7 / S-8 (~4060 tok)
 - `ensure-skills-idempotent.test.mjs` — v0.24 — Skill install is idempotent (field report, Issue D). (~1133 tok)
-- `field-report-3-deferred.test.mjs` — v0.28 — the detection-gap items deferred from LLM field report #3. (~3122 tok)
+- `field-report-3-deferred.test.mjs` — v0.28 — the detection-gap items deferred from LLM field report #3. (~3325 tok)
 - `field-report-3.test.mjs` — v0.27 — LLM field report #3. (~3315 tok)
 - `freshness.test.mjs` — runGit: commitOldCode (~3536 tok)
 - `hooks.test.mjs` — Declares afterFirst (~2420 tok)
+- `impact.test.mjs` — S-11 — `docguard impact` command. (~4128 tok)
 - `instruction-audit.test.mjs` — Instruction Audit scanner tests (field report #11 — MemoryLint-inspired). (~2387 tok)
 - `inventory.test.mjs` — Declares make (~1048 tok)
 - `llms-full-pack.test.mjs` — CLI: run (~1304 tok)
+- `mcp-http.test.mjs` — MCP Streamable HTTP transport — `docguard mcp --transport http`. (~1412 tok)
 - `mcp.test.mjs` — MCP Server Tests — `docguard mcp` over stdio. (~2138 tok)
 - `mechanical.test.mjs` — Declares write (~1161 tok)
 - `memory-plan.test.mjs` — Exports u, Button (~1834 tok)
 - `metrics-consistency.test.mjs` — Declares guardResults (~3942 tok)
 - `metrics-dedup.test.mjs` — v0.14.1-N1 — Metrics-Consistency dedup. (~1450 tok)
+- `nudge-hook.test.mjs` — Agent nudge hook — `docguard hooks --claude` + `docguard nudge-hook`. (~1681 tok)
 - `project-type.test.mjs` — Declares make (~2140 tok)
+- `reference-existence.test.mjs` — Exports validateToken, getUserById, verifyToken, getUserById + 4 more (~1853 tok)
 - `sarif.test.mjs` — Declares CLI (~1455 tok)
 - `shared-source.test.mjs` — API routes: GET (4 endpoints) (~1714 tok)
 - `speckit-phantom.test.mjs` — Exports users, fetchUserRecords, retry, adapter + 2 more (~2500 tok)
 - `trace-features.test.mjs` — `trace --features` — per-feature spec-kit adherence scoring. (~2423 tok)
+- `traceability.test.mjs` — Exports foo, GET, x (~3729 tok)

{docguard_cli-0.30.1 → docguard_cli-0.32.0}/.wolf/buglog.json

@@ -3294,6 +3294,321 @@
       "related_bugs": [],
       "occurrences": 1,
       "last_seen": "2026-07-06T14:40:55.317Z"
+    },
+    {
+      "id": "bug-201",
+      "timestamp": "2026-07-07T00:00:00Z",
+      "error_message": "reference-existence (REF001) fabricated 3 false positives in DocGuard AGENTS.md (after_implement, before_tasks, after_tasks flagged as removed) — symbols actually still present in .github/scripts/",
+      "file": "cli/validators/reference-existence.mjs",
+      "root_cause": "Asymmetry between two presence checks: the fast in-memory HEAD set was built with walkFiles() which SKIPS dot-directories (.github, .specify) by default (skipDotEntries), while the historical presence check used `git grep` which does NOT skip dot-dirs. So a symbol living only in a dot-dir read as absent-at-HEAD (walk missed it) but present-at-doc-rev (git grep found it) → false removed finding.",
+      "fix": "Confirm every walk-miss with an authoritative `git grep HEAD` before flagging (symbolExistsAtRev at HEAD). Only symbols absent from BOTH the walk AND git grep proceed to the historical check. Reduced docguard-self FPs 3→0.",
+      "tags": [
+        "reference-existence",
+        "walkFiles",
+        "git-grep",
+        "dot-dir",
+        "false-positive",
+        "dogfooding",
+        "v0.31.0"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-07-07T00:00:00Z"
+    },
+    {
+      "id": "bug-202",
+      "timestamp": "2026-07-11T16:23:11.081Z",
+      "error_message": "Significant refactor of ",
+      "file": "cli/validators/reference-existence.mjs",
+      "root_cause": "3 lines replaced/restructured",
+      "fix": "Rewrote 9→19 lines (3 removed)",
+      "tags": [
+        "auto-detected",
+        "refactor",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-07-11T16:23:11.081Z"
+    },
+    {
+      "id": "bug-203",
+      "timestamp": "2026-07-11T16:23:40.321Z",
+      "error_message": "Missing error handling in commentIndex",
+      "file": "cli/validators/reference-existence.mjs",
+      "root_cause": "Code path had no error handling — exceptions would propagate uncaught",
+      "fix": "Added try/catch block",
+      "tags": [
+        "auto-detected",
+        "error-handling",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-07-11T16:23:40.321Z"
+    },
+    {
+      "id": "bug-204",
+      "timestamp": "2026-07-11T16:23:54.215Z",
+      "error_message": "Missing guard clause",
+      "file": "cli/validators/reference-existence.mjs",
+      "root_cause": "No early return/throw for edge case: !isGitRepo(projectDir",
+      "fix": "Added guard clause: if (!isGitRepo(projectDir)",
+      "tags": [
+        "auto-detected",
+        "guard-clause",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 2,
+      "last_seen": "2026-07-11T16:24:09.297Z"
+    },
+    {
+      "id": "bug-205",
+      "timestamp": "2026-07-11T16:32:18.404Z",
+      "error_message": "Missing error handling in unknown",
+      "file": "cli/validators/cross-reference.mjs",
+      "root_cause": "Code path had no error handling — exceptions would propagate uncaught",
+      "fix": "Added try/catch block",
+      "tags": [
+        "auto-detected",
+        "error-handling",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-07-11T16:32:18.404Z"
+    },
+    {
+      "id": "bug-206",
+      "timestamp": "2026-07-11T16:32:29.416Z",
+      "error_message": "Significant refactor of ",
+      "file": "cli/commands/impact.mjs",
+      "root_cause": "4 lines replaced/restructured",
+      "fix": "Rewrote 14→18 lines (4 removed)",
+      "tags": [
+        "auto-detected",
+        "refactor",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-07-11T16:32:29.416Z"
+    },
+    {
+      "id": "bug-207",
+      "timestamp": "2026-07-11T16:36:21.697Z",
+      "error_message": "Null/undefined access in ",
+      "file": "cli/commands/impact.mjs",
+      "root_cause": "Property access on potentially null/undefined value",
+      "fix": "Added null safety (optional chaining or null check)",
+      "tags": [
+        "auto-detected",
+        "null-safety",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-07-11T16:36:21.697Z"
+    },
+    {
+      "id": "bug-208",
+      "timestamp": "2026-07-11T16:37:27.018Z",
+      "error_message": "Incorrect value in code",
+      "file": "cli/commands/impact.mjs",
+      "root_cause": "Had `     ${c.dim}↳ describes${c.reset} ${ch.via} ${c.",
+      "fix": "Changed to `     ${c.dim}↳ describes${c.reset} ${ch.via}${c.d",
+      "tags": [
+        "auto-detected",
+        "wrong-value",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-07-11T16:37:27.018Z"
+    },
+    {
+      "id": "bug-209",
+      "timestamp": "2026-07-11T16:40:58.825Z",
+      "error_message": "Missing error handling in loadGraphifyDocLinks",
+      "file": "cli/validators/traceability.mjs",
+      "root_cause": "Code path had no error handling — exceptions would propagate uncaught",
+      "fix": "Added try/catch block",
+      "tags": [
+        "auto-detected",
+        "error-handling",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-07-11T16:40:58.825Z"
+    },
+    {
+      "id": "bug-210",
+      "timestamp": "2026-07-11T16:46:22.632Z",
+      "error_message": "Incorrect value in code",
+      "file": "README.md",
+      "root_cause": "Had `--history`",
+      "fix": "Changed to `--no-indirect`",
+      "tags": [
+        "auto-detected",
+        "wrong-value",
+        "md"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-07-11T16:46:22.632Z"
+    },
+    {
+      "id": "bug-211",
+      "timestamp": "2026-07-11T00:00:00Z",
+      "error_message": "REF002 (new ADR-citation check) flagged 5 findings on DocGuard itself — all false positives: the validator's own doc comments using ADR-012 as EXAMPLES, plus test-fixture citations",
+      "file": "cli/validators/reference-existence.mjs",
+      "root_cause": "Citation scan had no non-product scoping (tests/ counted) and the implementation's explanatory comments contained real-looking ADR-<digits> examples that match the detector's own regex",
+      "fix": "Applied isNonProductPath() to the citation walk (tests/fixtures/examples excluded, same scoping as surface scanners) and rewrote all in-source examples to digit-free placeholders (ADR-NNN). Self-guard back to baseline.",
+      "tags": [
+        "ref002",
+        "adr-citations",
+        "false-positive",
+        "dogfooding",
+        "self-guard",
+        "non-product-scoping"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-07-11T00:00:00Z"
+    },
+    {
+      "id": "bug-212",
+      "timestamp": "2026-07-11T17:16:42.634Z",
+      "error_message": "Significant refactor of ",
+      "file": "cli/scanners/semantic-claims.mjs",
+      "root_cause": "2 lines replaced/restructured",
+      "fix": "Rewrote 15→22 lines (2 removed)",
+      "tags": [
+        "auto-detected",
+        "refactor",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-07-11T17:16:42.634Z"
+    },
+    {
+      "id": "bug-212",
+      "timestamp": "2026-07-11T00:00:00Z",
+      "error_message": "guard reported 39 unverified semantic claims; 28 came from docs-canonical/SURFACE-AUDIT.md which is explicitly listed in .docguardignore",
+      "file": "cli/scanners/semantic-claims.mjs",
+      "root_cause": "claimSourceDocs() enumerated docs-canonical/ + README/AGENTS without consulting loadIgnorePatterns — the extractor predates the ignore-honoring convention and was never wired to it",
+      "fix": "claimSourceDocs now filters through loadIgnorePatterns(projectDir); regression test added (ignored doc contributes no claims). Self-repo unverified claims 39 → 12.",
+      "tags": [
+        "semantic-claims",
+        "docguardignore",
+        "ignore-wiring",
+        "false-positive",
+        "verify-semantic"
+      ],
+      "related_bugs": [
+        "bug-211"
+      ],
+      "occurrences": 1,
+      "last_seen": "2026-07-11T00:00:00Z"
+    },
+    {
+      "id": "bug-214",
+      "timestamp": "2026-07-11T17:29:21.685Z",
+      "error_message": "Missing error handling in isOurNudgeGroup",
+      "file": "cli/commands/hooks.mjs",
+      "root_cause": "Code path had no error handling — exceptions would propagate uncaught",
+      "fix": "Added try/catch block",
+      "tags": [
+        "auto-detected",
+        "error-handling",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-07-11T17:29:21.685Z"
+    },
+    {
+      "id": "bug-215",
+      "timestamp": "2026-07-11T17:30:20.058Z",
+      "error_message": "Wrong condition in logic",
+      "file": "cli/docguard.mjs",
+      "root_cause": "Condition was: if (DEPRECATED_COMMANDS[command] && !flags.quiet)",
+      "fix": "Changed to: if (DEPRECATED_COMMANDS[command] && !flags.quiet && !()",
+      "tags": [
+        "auto-detected",
+        "logic-fix",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-07-11T17:30:20.058Z"
+    },
+    {
+      "id": "bug-216",
+      "timestamp": "2026-07-11T17:30:35.535Z",
+      "error_message": "Incorrect value in code",
+      "file": "cli/docguard.mjs",
+      "root_cause": "Had 'agent'",
+      "fix": "Changed to `nudge-hook`",
+      "tags": [
+        "auto-detected",
+        "wrong-value",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-07-11T17:30:35.535Z"
+    },
+    {
+      "id": "bug-217",
+      "timestamp": "2026-07-11T17:37:01.314Z",
+      "error_message": "Missing await",
+      "file": "cli/commands/mcp.mjs",
+      "root_cause": "Async call without await — returned Promise instead of value",
+      "fix": "Added await to async call",
+      "tags": [
+        "auto-detected",
+        "async-fix",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-07-11T17:37:01.314Z"
+    },
+    {
+      "id": "bug-218",
+      "timestamp": "2026-07-11T17:39:48.041Z",
+      "error_message": "Missing error handling in computeDocConflicts",
+      "file": "cli/commands/impact.mjs",
+      "root_cause": "Code path had no error handling — exceptions would propagate uncaught",
+      "fix": "Added try/catch block",
+      "tags": [
+        "auto-detected",
+        "error-handling",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-07-11T17:39:48.041Z"
+    },
+    {
+      "id": "bug-219",
+      "timestamp": "2026-07-11T17:40:24.277Z",
+      "error_message": "Missing await",
+      "file": "tests/impact.test.mjs",
+      "root_cause": "Async call without await — returned Promise instead of value",
+      "fix": "Added await to async call",
+      "tags": [
+        "auto-detected",
+        "async-fix",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-07-11T17:40:24.277Z"
     }
   ]
 }

{docguard_cli-0.30.1 → docguard_cli-0.32.0}/.wolf/cerebrum.md

@@ -67,6 +67,12 @@
 
 ## Decision Log
 
+- **2026-07-11 (v0.32.0 assembled — full "do it all" session)** — After the detection batch, the user approved the whole follow-on list; everything landed on PR #314 (branch claude/graphify-docguard-review-8a64ca, 10 commits): housekeeping (doc tiers 30→11 outside; TEST-SPEC 10s→30s claim), `hooks --claude` agent nudge (opt-in PostToolUse in project .claude/settings.json; runtime `nudge-hook` is headless + in READ_ONLY_COMMANDS; silent-on-error; 30-min/file throttle in .docguard/nudge-state.json), MCP Streamable HTTP (`--transport http`; non-loopback bind REFUSES without --api-key; shared dispatchMessage for both transports), `impact --prs` (pure computeDocConflicts + gh at the edge), VALIDATION.md (corpus repos described by stack, never client names — public repo). NEW BUG CLASS FOUND (bug-212 family): scanners that enumerate docs WITHOUT loadIgnorePatterns — fixed semantic-claims + agent-readability; grep for readdirSync('docs-canonical') when adding any doc scanner. GOTCHA: `hooks` is a DEPRECATED alias routed through init --with hooks; `hooks --claude` bypasses via a flags.claude branch + deprecation-warning exemption. GOTCHA: the auto-mode classifier BLOCKED `gh pr merge` (self-approval) exactly as predicted — release is parked on the user clicking merge on #314; after merge: watch release.yml, bump homebrew-tap sha256, ff-only pull the main tree, submit spec-kit catalog form, remind mcp-publisher (server.json already at 0.32.0). Addressability metric left at 43% DELIBERATELY — the remaining >120-tok sections are schema tables/mermaid; fragmenting them = metric-gaming (ALCOA honesty lesson).
+- **2026-07-11 (graphify batch APPLIED — [Unreleased])** — Items from the graphify review shipped same-day: (1) REF002 ADR-citation check inside reference-existence (validator count stays 27 — deliberate, avoids the self-count split); comment-gate + non-product scoping + integer number compare; RFC out of scope. (2) Wikilinks in cross-reference (XRF001/002) + impact blast radius, gated on evidence (`.obsidian/` or ≥1 resolving target) because `[[name]]` is also a non-file convention (our own memory links!); plus query-string strip + angle-bracket targets. (3) `impact` indirect mode: reverse-import BFS (2 hops) over the EXPORTED `buildImportGraph` from architecture.mjs (one builder); hub suppression at out-degree >15 was REQUIRED — without it cli/docguard.mjs flagged 7 docs on a 3-commit range, with it 2 genuine chains; `--no-indirect` opt-out. (4) Traceability consumes committed `graphify-out/graph.json` as TRC002 evidence — EXTRACTED edges only, linked file must exist, evidence-only (never a finding). Item 5 (cache portability) audited = already clean (.docguard/ gitignored, mtime-keyed cache is inherently local). Item 6 (PreToolUse nudge hooks) DEFERRED — writes to user agent configs, trust-sensitive class, needs Ricardo's call. Empirical read-only validation on 5 real repos: 0 FPs everywhere; indirect impact gave 6 explainable chains on globalshares (74 changed files) and 1 on hugocross. Tests 937→959. GOTCHAS: (a) writing `ADR-<digits>` in DocGuard's own comments trips REF002 — use ADR-NNN placeholders (bug-211); (b) referencing a dotfile like `.obsidian` in validator code trips DCV004 until a user-facing doc (README table) mentions it — CHANGELOG doesn't count.
+- **2026-07-11 (Graphify-Labs/graphify review — idea harvest, no code)** — Reviewed graphify (YC S26, MIT, Python ~50k LOC): tree-sitter knowledge graph of code+docs, LLM only for docs/media. NOT a competitor — it answers "how is code connected", DocGuard answers "do docs match code". Adoptable (all zero-dep-compatible): (1) **ADR/RFC citation check** — graphify's `extract.py:1087` regex `\b(ADR[- ]?\d{1,5}|RFC[- ]?\d{1,5})\b` in code comments, normalized to `ADR-0011`; DocGuard ships an ADR template but never verifies code citations point to existing ADR docs → natural REF-family extension (code→doc direction of reference-existence). (2) **`[[wikilink]]` support** — graphify's markdown extractor resolves wikilinks (extension-less → sibling .md) + strips `#anchor`/`?query` before resolution + `(?<!\!)` image guard; audit cross-reference/impact link parsing for these cases (Obsidian-style vaults). (3) **code→doc impact** — `affected.py` pattern: seed + BFS over a typed-edge whitelist; could extend `impact` beyond doc→doc using architecture.mjs import graph + trace links. (4) **Optional graph.json interop** — if `graphify-out/graph.json` exists, consume it (plain JSON read, zero-dep) as extra traceability evidence — but ONLY edges tagged `EXTRACTED` (its doc-side edges can be LLM-INFERRED; importing those breaks the determinism anchor). (5) **PreToolUse nudge hooks as distribution** — graphify's per-platform installs write hooks that fire before search/read tools; DocGuard analog: nudge `docguard impact` when the agent edits canonical docs. (6) Hygiene: git union-merge driver for committed generated JSON; relative-path re-anchored cache keys (audit plan.cache.json portability). Rejected: tree-sitter/NetworkX engine (Python dep stack vs zero-dep Node), LLM in core (already rejected), embeddings-free-graph marketing frame is theirs.
+
+- **2026-07-07 (v0.31.0 accuracy release — 6 research-backed detectors, empirical keep/cut)** — Implemented the verified deep-research roadmap as one batched release (PR #311, 9 commits, validator count 24→27). Built on TWO zero-dep foundations reused across features: `cli/shared-diff.mjs` (unified-diff parser + identifier-aware tokenizer + activity-labeled diff) and `cli/shared-ir.mjs` (TF-IDF + cosine). Features: (1) `impact` doc→doc BLAST RADIUS incl. agent files — the flagship, unclaimed by competitors; (2) `reference-existence` REF001 two-revision check; (3) `diff-suspicion` DSP001 diff-overlap; (4) `api-doc-smells` APS001/2 Bloated/Lazy; (5) IR soft-link recovery folded into traceability TRC004; (6) `verify --since` structured-diff staging. **METHOD THE USER MANDATED (durable preference): don't pick validator defaults abstractly — build each, run it READ-ONLY against their real active repos (temp/no-writes), measure signal-vs-noise, KEEP/CUT/tune empirically, remove if no value.** Corpus: hugocross_revamp, taxes_helper, stablecoin-strategy-lab, Agent Ops Platform, globalshares_revamp (~/Repo_claude), Whatsapp_Inbox (~/GitHub). All 6 KEEP; all default-ON, all soft (`confidence:'low'`, never break CI). Precision levers that mattered: DSP001 needed path/module-only refs (drop basename) + generic/HTTP/CSS token filter + per-doc cap (globalshares route-inventory doc flooded 45→capped). Validation log lived in scratchpad/validation-log.md.
+- **2026-07-07 (Do-Not-Repeat: adding a default-OFF validator SPLITS DocGuard's self-count)** — `metrics-consistency` counts guard results where `status !== 'skipped'` (excludes a config-disabled validator), but `canonical-sync` counts the full validatorMap (includes it). So a validator added default-OFF makes the two self-counters disagree by 1 (26 vs 27), and DocGuard's own guard flags CSY003 + MET001 forever. Resolution chosen: default the validator ON (it was zero-FP + soft anyway) so both counters agree — cleaner than special-casing the count logic. If a future validator MUST be default-off, reconcile the two counters first. Also: `canonical-sync` CSY003 false-positives on a validators-TABLE row whose number collides with the word "validators" in its description (row `| 24 | Surface-Sync | …validators… |` read as "24 validators") — reword such descriptions (used "checks"). And `metrics-consistency` MET001 can't tell HISTORICAL counts ("v0.22 had 24 validators" in a changelog row) from current claims — reword historical rows to drop the bare number. `docguard fix --write` will wrongly rewrite those historical counts.
 - **2026-07-06 (Jules PR triage policy — established)** — How to handle the Google Jules bot's auto-PRs, applied to a batch of 5 (#299 #300 #305 #306 #307). Rule: judge each on merit against the persona's own evidence bar, adopt real fixes CLEANLY (re-apply in our own commit without Jules's auto-generated `.agent/skills` churn), close the rest with a specific technical reason so the bot/human learns the bar. Verdicts recorded: (a) **#307 hooks /dev/null fix = genuinely correct** (one-line getHooksDir guard + a reproducing test) → adopted cleanly in #308, closed as superseded. (b) **#300 "CRITICAL command injection" = FALSE positive** — every flagged `execSync` target is a static string literal (`which specify`, `git log --since=...`) with no user-input interpolation, so no injection surface; also on a stale base (setup.mjs isCliAvailable already removed in #296). Closed — but harvested the ONE real nugget (score.mjs `git log | wc -l` shell pipe → `execFileSync`, Windows-portable). (c) **#299 Bolt regex hoisting = no benchmark, negative-value** — `new RegExp()` runs once per file (O(files)), never inside the match loop, so the claimed "O(N·M) bottleneck" is fiction; hoisting to a shared stateful `g`-regex + manual `.lastIndex=0` is a footgun for zero measured gain. Closed per Bolt's own ">20% measured benchmark" rule. (d) **#305/#306 = +0/-0 status reports** ("babel up to date", "no flaky tests") — well-behaved (no spurious diff) but shouldn't be PRs; closed with thanks. Meta-lesson: the persona files (.jules/*.md) + AGENTS.md bot rules + the jules-triage.yml workflow set the bar; enforcing it consistently in close-comments is what actually trains the bot down from duplicate-PR floods. Two of five carried real value — Jules is worth keeping, not silencing.
 - **2026-07-05 (distribution flywheel — v0.30.0)** — Executed the full external-distribution push. Durable facts: (1) **Official MCP Registry** publish needs THREE things aligned: `server.json` at repo root (2025-12-11 camelCase schema, name `io.github.raccioly/docguard`), `mcpName` in the PUBLISHED npm package (registry validates the referenced package carries it — so a release must SHIP after adding mcpName; adding it to main isn't enough), and `mcp-publisher login github && mcp-publisher publish` run FROM THE REPO ROLE on the user's Mac (I can't run it — sandbox ≠ their terminal; their GitHub device-auth token is local). Registry is IMMUTABLE per version → "400 duplicate version" means it ALREADY published (success, not failure). Verify via `curl https://registry.modelcontextprotocol.io/v0/servers?search=docguard`. (2) **Glama** listing: submitted via their web form (browser); the quality Score has code-fixable items — `glama.json` (root, `{$schema, maintainers:[gh-user]}`) fixes "No glama.json"; read-only MCP tool `annotations` (readOnlyHint/openWorldHint:false) + `title` serve the tool-def-quality/safety scans; a `Dockerfile` running `docguard mcp` enables their build-based "Glama release" (the big score driver, but the Make-Release clicks are the user's). (3) **awesome-mcp-servers** requires the server live on Glama first (bot label missing-glama→has-glama on re-check after a `synchronize`/force-push); entry format = `[owner/repo](url) [![badge](glama .../badges/score.svg)](glama url) 📇 🏠 🍎 🪟 🐧 - desc \`npx cmd\`` (badge AFTER repo link per file convention, NOT after description as the bot template says). (4) **Homebrew tap**: separate public repo `raccioly/homebrew-tap` with `Formula/docguard.rb`; formula url = npm tarball, sha256 must be recomputed per version (`curl -sL <tgz>|shasum -a256`). Bump the tap formula each release. (5) **spec-kit catalog**: one OPEN submission issue at a time (latest version), close superseded ones — established pattern. (6) **PATH shadowing gotcha**: a stale `npm i -g docguard-cli` shadows Homebrew's copy; `docguard --version` shows the FIRST-in-PATH one → `npm i -g docguard-cli@latest` to reconcile.