docguard-cli 0.41.2__tar.gz → 0.41.4__tar.gz

{docguard_cli-0.41.2 → docguard_cli-0.41.4}/.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.41.2
+  version: 0.41.4
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.41.2 -->
+<!-- docguard:version: 0.41.4 -->
 
 # DocGuard Fix Skill
 

{docguard_cli-0.41.2/extensions/spec-kit-docguard → docguard_cli-0.41.4/.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.41.2
+  version: 0.41.4
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.41.2 -->
+<!-- docguard:version: 0.41.4 -->
 
 # DocGuard Guard Skill
 

{docguard_cli-0.41.2/extensions/spec-kit-docguard → docguard_cli-0.41.4/.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.41.2
+  version: 0.41.4
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.41.2 -->
+<!-- docguard:version: 0.41.4 -->
 
 # DocGuard Review Skill
 

{docguard_cli-0.41.2/extensions/spec-kit-docguard → docguard_cli-0.41.4/.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.41.2
+  version: 0.41.4
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.41.2 -->
+<!-- docguard:version: 0.41.4 -->
 
 # DocGuard Score Skill
 

{docguard_cli-0.41.2/extensions/spec-kit-docguard → docguard_cli-0.41.4/.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.41.2
+  version: 0.41.4
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.41.2 -->
+<!-- docguard:version: 0.41.4 -->
 
 # DocGuard Sync Skill
 

{docguard_cli-0.41.2 → docguard_cli-0.41.4}/.docguard-specs.json

@@ -860,12 +860,12 @@
           {
             "requirementId": "FR-018",
             "file": "tests/hooks-contract.test.mjs",
-            "line": 13
+            "line": 17
           },
           {
             "requirementId": "FR-019",
             "file": "tests/hooks-contract.test.mjs",
-            "line": 14
+            "line": 18
           },
           {
             "requirementId": "FR-020",

{docguard_cli-0.41.2 → docguard_cli-0.41.4}/.wolf/buglog.json

@@ -6199,6 +6199,178 @@
       "related_bugs": [],
       "occurrences": 1,
       "last_seen": "2026-09-15T16:21:14.288Z"
+    },
+    {
+      "id": "bug-374",
+      "timestamp": "2026-09-15T16:39:17.000Z",
+      "error_message": "Reinstalling a managed hook nested a second BEGIN/END marker pair",
+      "file": "cli/commands/hooks.mjs",
+      "root_cause": "The install path wrapped the raw hook body before passing it to a splice helper that also added managed markers",
+      "fix": "Pass raw hook content to the splice boundary, replace the outermost marker range, and repair already-nested hooks on reinstall or removal",
+      "tags": [
+        "hooks",
+        "managed-block",
+        "idempotency",
+        "field-report"
+      ],
+      "related_bugs": [
+        "bug-354"
+      ],
+      "occurrences": 1,
+      "last_seen": "2026-09-15T16:39:17.000Z"
+    },
+    {
+      "id": "bug-375",
+      "timestamp": "2026-09-15T16:39:17.000Z",
+      "error_message": "A successful DocGuard managed hook exited before user-owned postlude commands could run",
+      "file": "cli/commands/hooks.mjs",
+      "root_cause": "Generated hook bodies ended in exit 0 even though managed blocks are designed to compose inside a larger hook file",
+      "fix": "Retain explicit blocking exits and end successful managed bodies with the no-op command so execution falls through to the surrounding hook",
+      "tags": [
+        "hooks",
+        "composition",
+        "postlude",
+        "field-report"
+      ],
+      "related_bugs": [
+        "bug-374"
+      ],
+      "occurrences": 1,
+      "last_seen": "2026-09-15T16:39:17.000Z"
+    },
+    {
+      "id": "bug-376",
+      "timestamp": "2026-09-15T16:39:17.000Z",
+      "error_message": "docguard verify --evidence exited 0 when its JSON status was contradicted",
+      "file": "cli/commands/verify.mjs",
+      "root_cause": "The direct evidence command rendered evaluator states but never mapped them to the CLI process-status contract",
+      "fix": "Exit 1 for contradicted or invalid, 2 for attention-required, and 0 for verified or unconfigured evidence, with subprocess regressions for every class",
+      "tags": [
+        "evidence",
+        "exit-code",
+        "ci",
+        "false-green",
+        "field-report"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-15T16:39:17.000Z"
+    },
+    {
+      "id": "bug-377",
+      "timestamp": "2026-09-15T16:39:17.000Z",
+      "error_message": "docguard specs --check reported STALE for array ordering without identifying the changed field",
+      "file": "cli/scanners/spec-registry.mjs; cli/commands/specs.mjs; cli/validators/spec-registry.mjs",
+      "root_cause": "Registry currency used an all-or-nothing serialized comparison and discarded the reason for a mismatch",
+      "fix": "Expose bounded value-safe field paths and difference kinds, including an explicit order-only canonicalization reason",
+      "tags": [
+        "spec-registry",
+        "diagnostics",
+        "ordering",
+        "clarity",
+        "field-report"
+      ],
+      "related_bugs": [
+        "bug-355"
+      ],
+      "occurrences": 1,
+      "last_seen": "2026-09-15T16:39:17.000Z"
+    },
+    {
+      "id": "bug-378",
+      "timestamp": "2026-09-15T16:39:17.000Z",
+      "error_message": "README What’s New still described the current v0.40 release line after v0.41 shipped",
+      "file": "README.md",
+      "root_cause": "A hand-maintained release-line label was coupled to automated package releases",
+      "fix": "Use version-independent recent-release wording while leaving exact release history in CHANGELOG",
+      "tags": [
+        "documentation",
+        "version-drift",
+        "readme",
+        "field-report"
+      ],
+      "related_bugs": [
+        "bug-356",
+        "bug-373"
+      ],
+      "occurrences": 1,
+      "last_seen": "2026-09-15T16:39:17.000Z"
+    },
+    {
+      "id": "bug-379",
+      "timestamp": "2026-09-15T17:02:00.000Z",
+      "error_message": "Subprocess-heavy contract tests intermittently failed with ETIMEDOUT during parallel full-suite execution",
+      "file": "tests/hooks-contract.test.mjs; tests/spec-kit-helper-json.test.mjs",
+      "root_cause": "Five- and ten-second process deadlines left no scheduler-contention margin when Node ran many integration suites concurrently",
+      "fix": "Retain finite process deadlines but raise them to 15 and 20 seconds for the shell-hook and Spec Kit helper integration fixtures",
+      "tags": [
+        "tests",
+        "timeout",
+        "parallel-ci",
+        "false-failure",
+        "reliability"
+      ],
+      "related_bugs": [],
+      "occurrences": 2,
+      "last_seen": "2026-09-15T17:02:00.000Z"
+    },
+    {
+      "id": "bug-380",
+      "timestamp": "2026-09-15T20:22:00.000Z",
+      "error_message": "Validator-count findings changed when a consumer disabled validators, and Canonical-Sync disagreed with Metrics-Consistency by counting an inlined guard sub-check as another validator",
+      "file": "cli/validators/metrics-consistency.mjs; cli/validators/canonical-sync.mjs",
+      "root_cause": "Package capability was derived from enabled guard orchestration rather than the installed validator-module surface, with two validators maintaining incompatible counting rules",
+      "fix": "Count shipped cli/validators modules through cli/shared-validator-surface.mjs, retain run-specific guard results only for check counts, and align CSY003 wording and all self-documentation",
+      "tags": [
+        "metrics",
+        "canonical-sync",
+        "false-positive",
+        "package-surface",
+        "field-report"
+      ],
+      "related_bugs": [
+        "bug-378"
+      ],
+      "occurrences": 1,
+      "last_seen": "2026-09-15T20:22:00.000Z"
+    },
+    {
+      "id": "bug-381",
+      "timestamp": "2026-09-15T20:22:00.000Z",
+      "error_message": "Instruction pointer basename resolution treated ignored disposable worktree copies as primary repository files and reported false ambiguity",
+      "file": "cli/shared-ignore.mjs; cli/scanners/instruction-audit.mjs",
+      "root_cause": "The custom basename walk used only DocGuard ignore rules and continued through nested Git roots, bypassing Git's authoritative ignore semantics",
+      "fix": "Use one bounded Git ignored-path filter for pointer indexing and prune nested .git file or directory boundaries before their descendants are read",
+      "tags": [
+        "instruction-audit",
+        "gitignore",
+        "worktree",
+        "false-positive",
+        "field-report"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-15T20:22:00.000Z"
+    },
+    {
+      "id": "bug-382",
+      "timestamp": "2026-09-15T20:22:00.000Z",
+      "error_message": "TRC004 correctly rejected a planned lifecycle registry that was new, removed from the Git index, or awaiting commit but suggested adding a test marker, obscuring the actual Git-state prerequisite",
+      "file": "cli/scanners/spec-registry.mjs; cli/validators/traceability.mjs",
+      "root_cause": "Trusted lifecycle loading discarded all non-clean Git state, leaving traceability with no safe way to distinguish a structurally current planned registry from ordinary missing lifecycle evidence",
+      "fix": "Expose structurally current planned entries from every non-clean Git state only as advisory context; preserve enforcement, explain restore-or-commit remediation, and prohibit marker-only remediation",
+      "tags": [
+        "traceability",
+        "spec-registry",
+        "lifecycle",
+        "remediation",
+        "field-report"
+      ],
+      "related_bugs": [
+        "bug-377"
+      ],
+      "occurrences": 1,
+      "last_seen": "2026-09-15T20:22:00.000Z"
     }
   ]
 }

{docguard_cli-0.41.2 → docguard_cli-0.41.4}/.wolf/cerebrum.md

@@ -5,6 +5,7 @@
 
 ## User Preferences
 
+- **2026-09-15** — Batch improvements and wait between public releases. Publish only after a materially significant set is ready or a critical correctness defect requires a release; avoid creating a visible release for each small merged change.
 - **2026-07-03** — **NO VS Code extension. Ever (until Ricardo says otherwise).** He built one before, it was deeply problematic ("a shit show"), and he removed it. Do not propose, scaffold, or build a VS Code extension for DocGuard. SARIF + Problems-panel via existing SARIF viewers is the sanctioned path to editor visibility. All OTHER distribution channels approved 2026-07-03: pre-commit, MCP registries (official/Smithery/mcp.so/Glama), awesome lists, Homebrew tap, GitLab CI component, Actions Marketplace (his click). #286 catalog submission SENT as-is — sharpened description goes into release.yml sync-catalog for the NEXT release, don't touch the submitted issue.
 - **2026-07-03** — Keep the LOCAL main tree (`/Users/ricardoaccioly/Repo_claude/canonical-spec-kit`) always up to date with origin/main. After any merge/push to main (releases especially), sync it in the same session: `git -C <main> status --short` first (never clobber unrecognized work — stash leftovers with a message, surface real WIP), then `git -C <main> pull --ff-only`. Sessions run in auto-worktrees, so the main tree silently falls behind otherwise (it sat at v0.25 while origin hit v0.29).
 
@@ -14,6 +15,7 @@
 
 ## Key Learnings
 
+- **2026-09-15 — Composition and process status are public contracts.** A hook test that preserves postlude text does not prove the postlude executes, and an evaluator-state test does not prove a direct CLI command gates CI. Execute generated hooks with commands on both sides, assert exact marker cardinality after reinstall, and spawn every machine command to verify its exit status agrees with its JSON status.
 - **2026-09-15 — A successful Spec Kit install does not prove manifest correctness.** The v0.40.4 ZIP passed validation and installed, yet `fix` resolved to `generate`, `review` resolved to `diagnose`, three shipped command files were absent from `provides.commands`, and its description exceeded the documented 200-character limit. Treat the manifest as an executable public API: require unique names and files, match every `speckit.docguard.<verb>` to `commands/<verb>.md`, compare declarations with the complete shipped directory, keep catalog metadata byte-aligned, and inspect the installed inventory before catalog submission.
 
 - **2026-09-14 — Release-generated skill parity:** The scheduled release updates extension skill metadata through `fix --write`, whose headless mode correctly skips setup. It must then run an explicit managed-agent sync before tests and staging; otherwise `.agent/skills` remains one release behind. A repository parity test should compare every managed copy byte-for-byte with its extension source.
@@ -76,6 +78,7 @@
 
 ## Do-Not-Repeat
 
+- **2026-09-15** — Never treat preserved hook text as proof of composition or a correct evaluator object as proof of CI behavior. Run the resulting script and spawn the CLI process; assertions must cover externally observable control flow and exit codes.
 - **2026-09-14** — Never put Markdown backticks inside a double-quoted shell command passed to `zsh -lc`; command substitution executes the text. Use single-quoted search patterns, and perform exact cleanup through a bounded script when destructive shell forms are rejected.
 - **2026-09-14** — Never treat a Git object ID as durable recovery by itself; unreachable commits and blobs can be garbage-collected after squash merges or branch deletion. Require the source revision to be an ancestor of a recorded retention ref and report recoverability explicitly.
 - **2026-09-14** — Never count a bare requirement ID as feature-completion evidence. Once the original spec is retired, a formerly ambiguous `FR-012` can become unique and silently rebind to another feature. Feature gates require a qualified stable identity; retired identities remain tombstoned.
@@ -158,3 +161,5 @@
 
 - **2026-09-15 — Living-spec completion and durable evidence:** A living verification contract may omit `tasks.md` only when every requirement has qualified source/test evidence; declared empty or incomplete ledgers and all other persistence models still fail closed. Maintenance of released living specs must preserve `released → released`. Because squash changes the candidate commit, durable implementation outcomes are recorded in a post-merge transaction against reachable main history; generated outcome churn cannot qualify itself.
 - **2026-09-15 — Packed version assertions:** A release smoke test that accepts any semantic version is a false-green. Execute the extracted tarball and compare `--version` exactly to that tarball's `package.json`; run registry installation probes from a fresh directory because `npx` inside the package checkout can select a stale local binary.
+
+- **2026-09-15 — Adoption precision follow-up:** A package capability claim must derive from the shipped package surface, never from one consumer's enabled guard results or from a secondary check emitted by a validator module. Keep every validator that governs the same claim on one shared count primitive. Instruction basename indexes must honor Git's ignore semantics and stop at nested Git boundaries before reading duplicate worktrees. Lifecycle evidence remains fail-closed: a structurally current planned registry that is new, removed from the Git index, or modified pending commit may improve the explanation, never defer traceability or prompt an artificial test marker. Pair each field replay with a real-project read-only run and before/after Git-status snapshots; no-release hardening batches stay unpublished until the user calls for a material release.

{docguard_cli-0.41.2 → docguard_cli-0.41.4}/.wolf/memory.md

@@ -1334,3 +1334,5 @@
 | 14:56 | Edited .github/workflows/release.yml | expanded (+53 lines) | ~845 |
 | 14:56 | Edited README.md | expanded (+19 lines) | ~245 |
 | 12:18 | Fixed living-spec completion and released maintenance; merged PRs #398–#400; published and independently verified v0.41.1; removed 348 temp artifacts | specs lifecycle, registry, roadmap, release | 1,866 tests + Node 18/20/22/24 + OSV + all publication targets passed | ~43000 tok |
+| 12:39 | Reproduced and fixed field-report hook composition, evidence exit, registry explanation, and README drift defects; classified four other v0.40.5 items as already fixed | hooks, verify, spec registry, canonical docs, tests | focused behavioral regressions added; v0.41.2 publication completed before release-cadence correction | ~18000 tok |
+| 20:22 | Hardened three v0.41.3 adoption reports and reconciled validator-count sources; replayed read-only consumer scans | metrics, canonical sync, instruction audit, lifecycle traceability, docs, tests | 1,879 tests, self-guard 618/618, package dry-run, seven repos unchanged; no release requested | ~26000 tok |

{docguard_cli-0.41.2 → docguard_cli-0.41.4}/CHANGELOG.md

@@ -7,6 +7,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.41.4] - 2026-09-17
+
+Automated weekly release — batches everything merged since `v0.41.3`.
+
+### Changed
+
+- fix: correct the validator-surface claim and document DOCGUARD_API_KEY (#408)
+- fix: harden adoption precision boundaries (#406)
+
+
+### Fixed
+
+- Document `DOCGUARD_API_KEY` in the canonical environment doc. `ENVIRONMENT.md`
+  claimed DocGuard uses "no API keys" and needs no environment variables, which
+  contradicted `SECURITY.md` and the HTTP MCP server, where the variable is
+  required to bind a non-loopback host. Core CLI commands still need no credential.
+- Enforce the published validator count in `npm test`. Canonical-Sync and
+  Metrics-Consistency already detect a stale "N validators" claim, but they emit
+  warnings and the CI self-scan deliberately tolerates guard's warnings-only exit,
+  so a wrong count could reach `main` with every check green. The count is now
+  asserted against the shipped `cli/validators/*.mjs` modules, and README explains
+  why guard prints 30 result rows for 29 validators.
+- Count DocGuard validator claims from one shared source of truth: the
+  validator modules shipped in the installed package. A consumer's intentionally
+  disabled validators and extra guard checks cannot create a false MET001 or
+  CSY003 finding, or an unsafe count rewrite.
+- Keep instruction-pointer basename resolution out of Git-ignored directories
+  and nested Git checkouts, including linked worktree copies.
+- Keep planned lifecycle registries that are new, removed from the Git index,
+  or modified pending commit non-authoritative for TRC004 while explaining how
+  to restore or commit the registry and current spec artifacts; the remediation
+  no longer suggests adding an artificial `@req` marker.
+
+## [0.41.3] - 2026-09-15
+
+Automated weekly release — batches everything merged since `v0.41.2`.
+
+### Changed
+
+- fix: preserve hook composition and evidence gates (#404)
+
+
+### Fixed
+
+- Increased the bounded subprocess deadlines in the hook and Spec Kit helper contract suites so parallel CI load does not misreport healthy integrations as `ETIMEDOUT` failures.
+- Make managed Git hook reinstall idempotent, repair nested marker pairs written
+  by affected releases, and allow successful DocGuard blocks to continue into
+  user-owned postlude commands.
+- Make direct `verify --evidence` suitable for CI by exiting 1 for contradictions
+  and invalid manifests, 2 for unresolved evidence, and 0 for verified or
+  unconfigured evidence.
+- Explain deterministic spec-registry drift with bounded field paths and identify
+  order-only canonicalization instead of returning an unexplained `STALE` state.
+- Replace the README's release-line label with version-independent wording so it
+  cannot become stale on the next automated release.
+
 ## [0.41.2] - 2026-09-15
 
 Automated weekly release — batches everything merged since `v0.41.1`.

{docguard_cli-0.41.2 → docguard_cli-0.41.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docguard-cli
-Version: 0.41.2
+Version: 0.41.4
 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
@@ -101,7 +101,7 @@ graph TD
     Commands --> setup["setup wizard"]
     Commands --> other["diff · init · fix · trace · impact · sync · reconcile · retire · specs<br/>explain · memory · upgrade · agents · hooks · badge · ci · watch"]
 
-    guard --> Validators["Validators (30)"]
+    guard --> Validators["Validators (29)"]
     generate --> Scanners["Scanners (4)<br/>routes · schemas · doc-tools · speckit"]
     score --> Scoring["Weighted Scoring<br/>8 categories"]
     diagnose --> Validators
@@ -299,7 +299,7 @@ DocGuard ships **23 commands** (the "Daily 5" + 18 situational tools, including
 | Command | What It Does |
 |:--------|:-------------|
 | `init`  | Bootstrap a project (`--wizard` for interactive · `--with <name>` for scaffolders) |
-| `guard` | Validate against canonical docs — 30 validators |
+| `guard` | Validate against canonical docs — 29 validators |
 | `diff`  | Show gaps between docs and code (`--since <ref>` for impact mode) |
 | `sync`  | Refresh code-truth doc sections — keeps memory always up to date |
 | `score` | Structural CDD maturity score (0-100; not a guard verdict; `--diff` for delta between refs) |
@@ -435,7 +435,13 @@ $ npx docguard-cli generate
 
 ## 🔍 Validators
 
-DocGuard runs **30 automated validators** on every `guard` check. Source-facing validators are language-aware where their evidence model applies; repository and document validators operate independently of source language.
+DocGuard runs **29 automated validators** on every `guard` check. Source-facing validators are language-aware where their evidence model applies; repository and document validators operate independently of source language.
+
+> **Counting note:** `guard` prints 30 result rows, not 29. `Structure` emits a
+> second check result (`Doc Sections`) under the same validator key, so rows are
+> checks, not validators. The published number is the count of shipped
+> `cli/validators/*.mjs` modules and is enforced by tests — don't derive it by
+> counting output rows.
 
 | # | Validator | What It Checks | Default |
 |:--|:----------|:--------------|:--------|
@@ -568,7 +574,7 @@ DocGuard provides AI agent slash commands for integrated workflows. Installed au
 | Command | What It Does |
 |:--------|:-------------|
 | `/docguard.init` | Initialize Canonical-Driven Development in a new or existing project |
-| `/docguard.guard` | Run quality validation — check all 30 validators |
+| `/docguard.guard` | Run quality validation — check all 29 validators |
 | `/docguard.review` | Analyze doc quality and suggest improvements |
 | `/docguard.fix` | Generate targeted fix prompts for specific issues |
 | `/docguard.update` | Update canonical docs after code changes — detect drift and sync documentation |
@@ -738,7 +744,7 @@ Two ready-to-use templates ship with the Spec Kit extension and as standalone fi
 
 ## ✨ What's New
 
-Highlights through the current v0.40 release line:
+Highlights from recent releases:
 
 - **Adoption baseline** — `guard --update-baseline` freezes a legacy repo's existing findings
   into a committed `.docguard.baseline.json`; guard/ci then gate only NEW drift, with suppression

{docguard_cli-0.41.2 → docguard_cli-0.41.4}/README.md

@@ -77,7 +77,7 @@ graph TD
     Commands --> setup["setup wizard"]
     Commands --> other["diff · init · fix · trace · impact · sync · reconcile · retire · specs<br/>explain · memory · upgrade · agents · hooks · badge · ci · watch"]
 
-    guard --> Validators["Validators (30)"]
+    guard --> Validators["Validators (29)"]
     generate --> Scanners["Scanners (4)<br/>routes · schemas · doc-tools · speckit"]
     score --> Scoring["Weighted Scoring<br/>8 categories"]
     diagnose --> Validators
@@ -275,7 +275,7 @@ DocGuard ships **23 commands** (the "Daily 5" + 18 situational tools, including
 | Command | What It Does |
 |:--------|:-------------|
 | `init`  | Bootstrap a project (`--wizard` for interactive · `--with <name>` for scaffolders) |
-| `guard` | Validate against canonical docs — 30 validators |
+| `guard` | Validate against canonical docs — 29 validators |
 | `diff`  | Show gaps between docs and code (`--since <ref>` for impact mode) |
 | `sync`  | Refresh code-truth doc sections — keeps memory always up to date |
 | `score` | Structural CDD maturity score (0-100; not a guard verdict; `--diff` for delta between refs) |
@@ -411,7 +411,13 @@ $ npx docguard-cli generate
 
 ## 🔍 Validators
 
-DocGuard runs **30 automated validators** on every `guard` check. Source-facing validators are language-aware where their evidence model applies; repository and document validators operate independently of source language.
+DocGuard runs **29 automated validators** on every `guard` check. Source-facing validators are language-aware where their evidence model applies; repository and document validators operate independently of source language.
+
+> **Counting note:** `guard` prints 30 result rows, not 29. `Structure` emits a
+> second check result (`Doc Sections`) under the same validator key, so rows are
+> checks, not validators. The published number is the count of shipped
+> `cli/validators/*.mjs` modules and is enforced by tests — don't derive it by
+> counting output rows.
 
 | # | Validator | What It Checks | Default |
 |:--|:----------|:--------------|:--------|
@@ -544,7 +550,7 @@ DocGuard provides AI agent slash commands for integrated workflows. Installed au
 | Command | What It Does |
 |:--------|:-------------|
 | `/docguard.init` | Initialize Canonical-Driven Development in a new or existing project |
-| `/docguard.guard` | Run quality validation — check all 30 validators |
+| `/docguard.guard` | Run quality validation — check all 29 validators |
 | `/docguard.review` | Analyze doc quality and suggest improvements |
 | `/docguard.fix` | Generate targeted fix prompts for specific issues |
 | `/docguard.update` | Update canonical docs after code changes — detect drift and sync documentation |
@@ -714,7 +720,7 @@ Two ready-to-use templates ship with the Spec Kit extension and as standalone fi
 
 ## ✨ What's New
 
-Highlights through the current v0.40 release line:
+Highlights from recent releases:
 
 - **Adoption baseline** — `guard --update-baseline` freezes a legacy repo's existing findings
   into a committed `.docguard.baseline.json`; guard/ci then gate only NEW drift, with suppression

{docguard_cli-0.41.2 → docguard_cli-0.41.4}/VALIDATION.md

@@ -85,7 +85,7 @@ tuning; the levers that mattered:
 ## Standing verification
 
 - Built-in `node:test`, with Node 18/20/22/24 in the supported CI matrix. Per-change validation records contain measured test totals.
-- **Self-guarded:** every push runs all 30 validators against DocGuard's own
+- **Self-guarded:** every push runs all 29 validators against DocGuard's own
   docs; count claims in this README family are machine-governed
   (Canonical-Sync), so the validator count is checked, not remembered.
 - **Deterministic core:** no LLM calls at validation time, one pinned

{docguard_cli-0.41.2 → docguard_cli-0.41.4}/cli/commands/hooks.mjs

@@ -24,6 +24,19 @@ import { existsSync, mkdirSync, chmodSync, readFileSync, unlinkSync } from 'node
 // pre-existing hooks), behavior falls back to the existing --force flow.
 const BEGIN_MARKER = '# BEGIN DOCGUARD MANAGED — do not edit between these markers';
 const END_MARKER   = '# END DOCGUARD MANAGED';
+const escapeRegExp = value => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+function managedBounds(content) {
+  const starts = [...content.matchAll(new RegExp(`^${escapeRegExp(BEGIN_MARKER)}\\r?$`, 'gm'))]
+    .map(match => match.index);
+  const ends = [...content.matchAll(new RegExp(`^${escapeRegExp(END_MARKER)}\\r?$`, 'gm'))]
+    .map(match => match.index);
+  const start = starts[0];
+  const end = ends.at(-1);
+  return Number.isInteger(start) && Number.isInteger(end) && end > start
+    ? { start, end }
+    : null;
+}
 
 /**
  * Wrap a hook body in BEGIN/END markers so future re-installs can splice
@@ -44,15 +57,18 @@ function wrapManaged(body) {
  * the BEGIN/END markers. Returns the new file content (string) or null
  * when the markers aren't found (caller falls back to legacy behavior).
  */
-function spliceManagedBlock(existing, newBody) {
-  const startIdx = existing.indexOf(BEGIN_MARKER);
-  const endIdx   = existing.indexOf(END_MARKER);
-  if (startIdx === -1 || endIdx === -1 || endIdx < startIdx) return null;
+function spliceManagedBlock(existing, rawBody) {
+  const bounds = managedBounds(existing);
+  if (!bounds) return null;
+  const startIdx = bounds.start;
+  // Use the outermost end marker so one reinstall also repairs hooks written
+  // by v0.40.5-v0.41.2, which accidentally nested a second managed block.
+  const endIdx = bounds.end;
   const before = existing.slice(0, startIdx);
   const after  = existing.slice(endIdx + END_MARKER.length);
-  // newBody has its own shebang — strip it since we're splicing into the
+  // rawBody has its own shebang — strip it since we're splicing into the
   // middle of an existing file (which already has one).
-  const bodyNoShebang = newBody.replace(/^#!.*\n/, '');
+  const bodyNoShebang = rawBody.replace(/^#!.*\n/, '');
   return `${before}${BEGIN_MARKER}\n${bodyNoShebang.replace(/\n+$/, '')}\n${END_MARKER}${after}`;
 }
 
@@ -62,18 +78,21 @@ function hookState(name, hooksDir) {
   let content;
   try { content = readFileSync(path, 'utf-8'); }
   catch { return { kind: 'unreadable', path, content: '' }; }
-  if (content.includes(BEGIN_MARKER) && content.includes(END_MARKER)) {
+  if (managedBounds(content)) {
     return { kind: 'managed', path, content };
   }
-  const legacySignature = new RegExp(`^# DocGuard ${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')} hook(?: \\(auto-fix mode\\))?$`, 'm');
+  const legacySignature = new RegExp(`^# DocGuard ${escapeRegExp(name)} hook(?: \\(auto-fix mode\\))?$`, 'm');
   if (legacySignature.test(content)) return { kind: 'legacy', path, content };
   return { kind: 'foreign', path, content };
 }
 
 function removeManagedBlock(content) {
-  const start = content.indexOf(BEGIN_MARKER);
-  const end = content.indexOf(END_MARKER);
-  if (start === -1 || end === -1 || end < start) return null;
+  const bounds = managedBounds(content);
+  if (!bounds) return null;
+  const start = bounds.start;
+  // Match spliceManagedBlock's outermost recovery boundary so removal also
+  // cleans up already-nested blocks from affected releases.
+  const end = bounds.end;
   const remaining = `${content.slice(0, start)}${content.slice(end + END_MARKER.length)}`
     .replace(/\n{3,}/g, '\n\n');
   return remaining;
@@ -128,7 +147,7 @@ elif [ $EXIT_CODE -eq 2 ]; then
   echo "⚠️  DocGuard guard found warnings — commit allowed"
 fi
 
-exit 0
+:
 `,
   },
 
@@ -179,7 +198,7 @@ if [ "$SCORE" -lt "$MIN_SCORE" ]; then
 fi
 
 echo "   ✅ Score meets minimum threshold"
-exit 0
+:
 `,
   },
 
@@ -215,7 +234,7 @@ if ! echo "$COMMIT_MSG" | head -1 | grep -qE "$PATTERN"; then
   exit 1
 fi
 
-exit 0
+:
 `,
   },
 };
@@ -256,7 +275,7 @@ if [ "$EXIT_CODE" -ne 0 ] && [ "$EXIT_CODE" -ne 2 ]; then
 elif [ $EXIT_CODE -eq 2 ]; then
   echo "⚠️  DocGuard guard found warnings — commit allowed"
 fi
-exit 0
+:
 `;
 
 export function runHooks(projectDir, config, flags) {
@@ -356,7 +375,8 @@ export function runHooks(projectDir, config, flags) {
   for (const name of hookTypes) {
     const hookPath = resolve(hooksDir, name);
     const useAutofix = name === 'pre-commit' && flags.autoFix;
-    const newContent = wrapManaged(useAutofix ? PRE_COMMIT_AUTOFIX : HOOKS[name].content);
+    const rawContent = useAutofix ? PRE_COMMIT_AUTOFIX : HOOKS[name].content;
+    const newContent = wrapManaged(rawContent);
     const desc = useAutofix ? 'Apply mechanical fixes (fix --write) then guard' : HOOKS[name].description;
 
     if (existsSync(hookPath)) {
@@ -366,7 +386,7 @@ export function runHooks(projectDir, config, flags) {
       // preserve everything outside it. The user can extend the hook with
       // their own commands above/below the markers without losing them on
       // re-install.
-      const spliced = spliceManagedBlock(existing, newContent);
+      const spliced = spliceManagedBlock(existing, rawContent);
       if (spliced !== null) {
         safeWrite(hookPath, spliced);
         chmodSync(hookPath, 0o755);

{docguard_cli-0.41.2 → docguard_cli-0.41.4}/cli/commands/specs.mjs

@@ -226,6 +226,12 @@ function printResult(result) {
   console.log(`Spec registry: ${result.status}`);
   console.log(`Registry: ${SPEC_REGISTRY_PATH}`);
   console.log(`Specs: ${result.specs}; tombstones: ${result.tombstones}`);
+  if (result.differences?.length) {
+    console.log('Differences:');
+    for (const difference of result.differences) {
+      console.log(`  ${difference.path}: ${difference.message}`);
+    }
+  }
   if (result.issues.length) printIssues(result.issues);
 }
 
@@ -268,6 +274,7 @@ export function runSpecs(projectDir, config, flags = {}) {
       specs: projection.registry.specs.length,
       tombstones: projection.registry.tombstones.length,
       issues: projection.issues,
+      differences: projection.differences,
     };
     if (flags.format === 'json') console.log(JSON.stringify(result, null, 2));
     else printResult(result);