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

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

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

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

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

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

{docguard_cli-0.41.2 → docguard_cli-0.41.3}/.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.3}/.wolf/buglog.json

@@ -6199,6 +6199,120 @@
       "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"
     }
   ]
 }

{docguard_cli-0.41.2 → docguard_cli-0.41.3}/.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.

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

@@ -1334,3 +1334,4 @@
 | 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 |

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

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docguard-cli
-Version: 0.41.2
+Version: 0.41.3
 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
@@ -738,7 +738,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.3}/README.md

@@ -714,7 +714,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.3}/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.3}/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);

{docguard_cli-0.41.2 → docguard_cli-0.41.3}/cli/commands/verify.mjs

@@ -169,6 +169,14 @@ export function runVerify(projectDir, config, flags) {
 
 function runEvidenceVerification(projectDir, config, flags) {
   const evaluation = evaluateEvidence(projectDir, config);
+  // Match guard's severity contract so this command is safe as a direct CI
+  // gate: contradictions and invalid manifests fail, while unresolved evidence
+  // uses the warning-only status shared by the rest of the CLI.
+  process.exitCode = evaluation.status === 'contradicted' || evaluation.status === 'invalid'
+    ? 1
+    : evaluation.status === 'attention-required'
+      ? 2
+      : 0;
   if (flags.format === 'json') {
     console.log(JSON.stringify(evaluation, null, 2));
     return;

{docguard_cli-0.41.2 → docguard_cli-0.41.3}/cli/scanners/spec-registry.mjs

@@ -35,6 +35,51 @@ const posix = path => path.split(sep).join('/').replace(/^\.\//, '');
 const digest = content => `sha256:${createHash('sha256').update(content).digest('hex')}`;
 const sortedUnique = values => [...new Set(values)].sort((a, b) => a.localeCompare(b));
 
+function registryDifferences(left, right) {
+  const differences = [];
+  let omitted = false;
+  const add = difference => {
+    if (differences.length < 25) differences.push(difference);
+    else omitted = true;
+  };
+  const memberKeys = values => values.map(value => JSON.stringify(value)).sort();
+  const visit = (actual, projected, path) => {
+    if (omitted) return;
+    if (Object.is(actual, projected)) return;
+    if (Array.isArray(actual) && Array.isArray(projected)) {
+      if (JSON.stringify(actual) === JSON.stringify(projected)) return;
+      const actualMembers = memberKeys(actual);
+      const projectedMembers = memberKeys(projected);
+      if (actualMembers.length === projectedMembers.length
+        && actualMembers.every((value, index) => value === projectedMembers[index])) {
+        add({ path, kind: 'order', message: 'Unordered values are not in canonical sort order.' });
+        return;
+      }
+      const length = Math.max(actual.length, projected.length);
+      for (let index = 0; index < length; index++) visit(actual[index], projected[index], `${path}[${index}]`);
+      return;
+    }
+    const actualObject = actual !== null && typeof actual === 'object' && !Array.isArray(actual);
+    const projectedObject = projected !== null && typeof projected === 'object' && !Array.isArray(projected);
+    if (actualObject && projectedObject) {
+      for (const key of [...new Set([...Object.keys(actual), ...Object.keys(projected)])].sort()) {
+        visit(actual[key], projected[key], `${path}.${key}`);
+      }
+      return;
+    }
+    const kind = actual === undefined ? 'missing'
+      : projected === undefined ? 'unexpected'
+        : 'value';
+    const message = kind === 'missing' ? 'Field is missing from the registry.'
+      : kind === 'unexpected' ? 'Field is not part of the deterministic projection.'
+        : 'Field value differs from the deterministic projection.';
+    add({ path, kind, message });
+  };
+  visit(left, right, '$');
+  if (omitted) differences.push({ path: '$', kind: 'truncated', message: 'Additional differences were omitted.' });
+  return differences;
+}
+
 function isSafeFile(projectDir, path) {
   try {
     const root = realpathSync(projectDir);
@@ -472,10 +517,14 @@ export function projectSpecRegistry(projectDir, config = {}, options = {}) {
   const current = existing.exists && !existing.error
     ? `${JSON.stringify(existing.value, null, 2)}\n` === serialized
     : false;
+  const differences = existing.exists && !existing.error
+    ? registryDifferences(existing.value, projected)
+    : [];
   return {
     registry: projected,
     serialized,
     current,
+    differences,
     exists: existing.exists,
     issues,
     detected: detected.specs.length,

{docguard_cli-0.41.2 → docguard_cli-0.41.3}/cli/validators/spec-registry.mjs

@@ -25,13 +25,16 @@ export function validateSpecRegistry(projectDir, config = {}) {
         },
   }));
   if (!projection.current && projection.issues.length === 0) {
+    const detail = projection.differences.slice(0, 3)
+      .map(difference => `${difference.path}: ${difference.message}`)
+      .join(' ');
     findings.push(mkFinding({
       code: 'SPR001',
       validator: 'specRegistry',
       severity: 'warn',
       confidence: 'high',
       message: projection.exists
-        ? `${SPEC_REGISTRY_PATH} does not match the current deterministic spec evidence projection.`
+        ? `${SPEC_REGISTRY_PATH} does not match the current deterministic spec evidence projection.${detail ? ` ${detail}` : ''}`
         : `${SPEC_REGISTRY_PATH} is missing while active specifications exist.`,
       location: SPEC_REGISTRY_PATH,
       suggestion: {

{docguard_cli-0.41.2 → docguard_cli-0.41.3}/docs-canonical/ARCHITECTURE.md

@@ -1,13 +1,13 @@
 # Architecture
 
-<!-- docguard:version 1.1.0 -->
+<!-- docguard:version 1.3.0 -->
 <!-- docguard:status active -->
 <!-- docguard:last-reviewed 2026-09-15 -->
 
 | Metadata | Value |
 |----------|-------|
 | **Status** | ![Status](https://img.shields.io/badge/status-active-brightgreen) |
-| **Version** | `1.0.0` |
+| **Version** | `1.3.0` |
 | **Last Updated** | 2026-09-15 |
 | **Project Size** | ~24K lines across `cli/` |
 
@@ -26,11 +26,12 @@ It targets development teams and AI coding agents that need to maintain document
 | **CLI Entry Point** | Argument parsing, config loading, command routing | `cli/` | `docguard.mjs` |
 | **Commands** | User-facing commands (the Daily 5 — init/guard/diff/sync/score — plus situational tools including reconcile, retire, specs, and `init --with` scaffolders) | `cli/commands/` | `*.mjs` |
 | **Document lifecycle** | Finds exact terminal-status docs and completed-task review candidates; explicit retirement removes documentation from active context only after its source revision is reachable from a retained Git ref | `cli/scanners/document-lifecycle.mjs`, `cli/validators/document-lifecycle.mjs`, `cli/commands/retire.mjs` | Scanner is read-only; retirement uses the shared multi-file transaction and remains explicit |
-| **Spec lifecycle registry** | Projects immutable spec identities, reviewed lifecycle/lineage/scope, artifact digests, task state, qualified implementation/test evidence, bounded outcomes, and recovery tombstones into one byte-stable control file | `cli/scanners/spec-registry.mjs`, `cli/scanners/requirement-evidence.mjs`, `cli/validators/spec-registry.mjs`, `cli/commands/specs.mjs` | `specs --write` preserves reviewed fields; `specs complete` is the only verified-delivery writer; generic retirement cannot bypass an active registered spec |
+| **Spec lifecycle registry** | Projects immutable spec identities, reviewed lifecycle/lineage/scope, artifact digests, task state, qualified implementation/test evidence, bounded outcomes, and recovery tombstones into one byte-stable control file | `cli/scanners/spec-registry.mjs`, `cli/scanners/requirement-evidence.mjs`, `cli/validators/spec-registry.mjs`, `cli/commands/specs.mjs` | `specs --write` preserves reviewed fields; stale checks identify bounded field paths and distinguish canonical ordering from changed content; `specs complete` is the only verified-delivery writer |
 | **Reconciliation graph** | Inventories changed paths independently from bounded patch text, maps them to direct spec evidence, and keeps mechanical facts, approved intent, decisions, unrelated changes, and unsupported evidence separate | `cli/shared-git.mjs`, `cli/scanners/reconciliation.mjs`, `cli/commands/reconcile.mjs` | Timeout, overflow, parse failure, or incomplete inventory blocks a ready result; planning is read-only and `--write` never rewrites requirements |
 | **Precision evidence** | Runs labelled synthetic and exact-commit public cases, separates deterministic results from observations, calculates null-safe quality metrics and confidence bounds, and compares case-first baselines | `benchmarks/`, `schemas/docguard-benchmark.schema.json` | External runs are explicit; third-party project code is never executed and disposable checkouts are removed by default |
 | **Feedback fixtures** | Validates synthetic reproductions and opposite controls, reduces them under an explicit predicate, derives duplicate identities, and emits test-only contributions | `cli/feedback-fixture.mjs`, `cli/commands/feedback.mjs`, `schemas/docguard-feedback-fixture.schema.json` | Publication remains user-controlled; contribution generation requires reviewed redaction, scope, and benchmark-delta evidence |
-| **Evidence-scoped verification** | Binds one exact Markdown statement to a typed JSON Pointer value, bounded file collection, static Python container literal, or saved upstream compatibility report and returns one of five explicit states | `cli/evidence/`, `cli/validators/evidence.mjs`, `schemas/docguard-evidence.schema.json` | Reads stay local, bounded, non-executable, and symlink/private-path safe; dynamic Python syntax abstains and a pass covers only the selected statement and captured evidence |
+| **Evidence-scoped verification** | Binds one exact Markdown statement to a typed JSON Pointer value, bounded file collection, static Python container literal, or saved upstream compatibility report and returns one of five explicit states | `cli/evidence/`, `cli/validators/evidence.mjs`, `cli/commands/verify.mjs`, `schemas/docguard-evidence.schema.json` | Reads stay local, bounded, non-executable, and symlink/private-path safe; direct verification exits 1 for contradiction/invalid input, 2 for unresolved evidence, and 0 only for verified or unconfigured evidence |
+| **Managed Git hooks** | Installs bounded DocGuard blocks while preserving user-owned hook commands before and after them | `cli/commands/hooks.mjs` | Reinstall and removal use one outer marker pair, repair nested markers from affected releases, fail closed on enforcement errors, and fall through after success so user postludes execute |
 | **Readiness assessment** | Combines guard enforcement and optional CI score policy without changing structural score semantics | `cli/assessment.mjs`, `cli/commands/ci.mjs`, `cli/commands/diagnose.mjs`, `cli/commands/report.mjs` | READY requires a passing guard and configured gates; ATTENTION carries advisory warnings; BLOCKED identifies failed enforcement |
 | **Task-specific agent context** | Ranks exact task paths, qualified requirements, finding codes, identifiers, and bounded lexical overlap across current governed evidence | `cli/scanners/task-context.mjs`, `cli/commands/agent.mjs`, `schemas/docguard-task-context.schema.json` | Read-only and deterministic; excludes retired, unapproved, digest-stale, private, and unsafe material; abstains on weak relevance and never upgrades prose accuracy |
 | **Cross-language import graph** | Resolves repository-local JS/TS and Python static imports for cycle and layer checks | `cli/validators/architecture.mjs`, `cli/scanners/py-ast.mjs` | Python supports regular flat/`src/` packages and explicit relatives; dynamic imports, runtime path changes, parse failures, missing interpreters, and ambiguous modules remain explicit limitations |
@@ -204,9 +205,10 @@ DocGuard declares one exact-pinned runtime dependency, `@babel/parser`. It loads
 
 | Version | Date | Author | Changes |
 |---------|------|--------|---------|
+| 1.3.0 | 2026-09-15 | DocGuard Team | Made managed hooks composable and self-repairing, aligned direct evidence exit codes with guard severity, and exposed field-level registry drift |
 | 1.2.0 | 2026-09-15 | DocGuard Team | Made router mounts symbol-aware and statically composable, retained negative scan evidence as review-only, and aligned monorepo/config/design-sync discovery boundaries |
-| 1.0.0 | 2026-09-14 | DocGuard Team | Added deterministic task-specific context selection, lifecycle and safe-reader boundaries, strict packet schema, and the frozen promotion benchmark |
 | 1.1.0 | 2026-09-15 | DocGuard Team | Added packed adoption qualification, independent diff inventory, exact finding-code policy, combined readiness assessment, lifecycle-aware traceability, static Python literal evidence, and transitive static router-mount resolution with test-client exclusion |
+| 1.0.0 | 2026-09-14 | DocGuard Team | Added deterministic task-specific context selection, lifecycle and safe-reader boundaries, strict packet schema, and the frozen promotion benchmark |
 | 0.9.0 | 2026-09-14 | DocGuard Team | Added strict evidence manifests, typed local adapters, five-state evaluation, exact semantic-claim coverage, and guard/agent assurance integration |
 | 0.8.0 | 2026-09-14 | DocGuard Team | Added transactional retirement/completion writes, reconciliation review graphs, qualified implementation evidence, bounded outcomes, active-context regeneration, and Spec Kit completion hooks |
 | 0.7.0 | 2026-09-14 | DocGuard Team | Added the deterministic spec lifecycle registry, immutable spec-ID resolution, shared requirement evidence scanner, recovery tombstones, and two-stage preflight boundary |

{docguard_cli-0.41.2 → docguard_cli-0.41.3}/docs-canonical/CI-RECIPES.md

@@ -24,6 +24,11 @@ visible warnings. Inspect the complete contract with:
 npx docguard-cli verify --evidence --format json
 ```
 
+This direct command exits 0 when every configured declaration is verified, 2
+when evidence is stale, inconclusive, or unsupported, and 1 when a declaration
+is contradicted or the manifest is invalid. CI that permits unresolved evidence
+must explicitly allow only status 2; a contradiction is always a failed gate.
+
 Generate oasdiff or Buf reports in an earlier pinned CI step, save their machine
 output, and declare SHA-256 identities for every repository input. DocGuard
 consumes those artifacts; it does not install or invoke either producer. Keep