docguard-cli 0.41.2 → 0.41.3

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

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

package/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);

package/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);

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

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

package/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: {

package/extensions/spec-kit-docguard/extension.yml

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.41.2"
+  version: "0.41.3"
   description: "Documentation integrity for AI-assisted repositories: lifecycle registry, drift validation, traceability, safe archival, SARIF/JUnit, MCP, GitHub Actions, and Spec Kit hooks."
   author: "Ricardo Accioly"
   repository: "https://github.com/raccioly/docguard"

package/extensions/spec-kit-docguard/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
 

package/extensions/spec-kit-docguard/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
 

package/extensions/spec-kit-docguard/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
 

package/extensions/spec-kit-docguard/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
 

package/extensions/spec-kit-docguard/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
 

package/extensions/spec-kit-docguard/templates/github-workflows/docguard-autofix.yml

@@ -44,7 +44,7 @@ jobs:
           fetch-depth: 0
 
       - name: Run DocGuard fix --write + auto-commit + PR comment
-        uses: raccioly/docguard@v0.41.2
+        uses: raccioly/docguard@v0.41.3
         with:
           command: fix
           auto-commit: 'true'

package/extensions/spec-kit-docguard/templates/github-workflows/docguard-guard.yml

@@ -35,7 +35,7 @@ jobs:
           node-version: '20'
 
       - name: Install DocGuard
-        run: npm install --global --ignore-scripts docguard-cli@0.41.2
+        run: npm install --global --ignore-scripts docguard-cli@0.41.3
 
       - name: Run DocGuard
         shell: bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.41.2",
+  "version": "0.41.3",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {

package/templates/ci/github-actions.yml

@@ -31,7 +31,7 @@ jobs:
           node-version: '20'
 
       - name: Install DocGuard
-        run: npm install --global --ignore-scripts docguard-cli@0.41.2
+        run: npm install --global --ignore-scripts docguard-cli@0.41.3
 
       - name: Run DocGuard
         shell: bash