docguard-cli 0.41.5 → 0.41.6

package/CHANGELOG.md

@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.41.6] - 2026-09-18
+
+Automated weekly release — batches everything merged since `v0.41.5`.
+
+### Changed
+
+- test: make this suite probeable by TestGuard, and close the gap it found (#415)
+- fix: do not block projects that never adopted DocGuard; protect hook backups (#414)
+- chore: complete the pass to generic project references (#413)
+
+
+### Added
+
+- TestGuard claim probing for this repository: `testguard.claims.json` plus
+  `tools/node-test-json-reporter.mjs`, which translates `node --test` output into
+  the Jest-shape JSON TestGuard reads (node:test ships no `json` reporter). The
+  first claim covers `backupFile`; probing it found a real gap — one guard was
+  masked by another, so its fault survived while every test stayed green — and
+  the missing case is now covered.
+
+### Changed
+
+- Completed the pass to generic project references: the earlier sweep matched a
+  narrower pattern than the one used to find them, so sixteen mentions survived
+  in source comments, tests and changelog prose. Two references are deliberately
+  kept: `.docguard-archive.json` records an archived spec path plus the
+  `git restore` command that recovers it, and renaming that string would point
+  the restore at a path that never existed.
+
+### Fixed
+
+- Stop blocking commits in projects that never adopted DocGuard. A Git hook
+  lives in the common `.git/hooks` and governs every linked worktree, while
+  `.docguard.json` is a branch-local tracked file — during adoption the two
+  cannot be consistent, so a hook installed on one branch blocked commits on
+  every other branch and worktree, where `guard` exited 1 for missing canonical
+  docs. `guard` now exits **3** ("not initialised") instead of 1 when there is
+  no `.docguard.json`, and the generated hooks skip enforcement and allow the
+  operation. Exit 3 is still non-zero, so a CI gate that fails on any non-zero
+  status is unchanged, and an adopted project with real findings still exits 1
+  and still blocks. Existing installed hooks do not self-heal — re-run
+  `docguard hooks` to pick this up.
+- Stop spending the single backup slot on a no-op. Re-installing a byte-identical
+  managed hook wrote a redundant `.bak`; with `--force` a second install
+  overwrote the backup holding the user's own original hook, which is
+  unrecoverable because a `.git/hooks` file is not in version control. Identical
+  writes are now skipped, and a `.bak` DocGuard did not write is preserved
+  alongside a timestamped copy rather than replaced.
+
+
 ## [0.41.5] - 2026-09-17
 
 Automated weekly release — batches everything merged since `v0.41.4`.
@@ -1809,7 +1859,7 @@ Python, and AWS/AppSync projects.
   longer scans `commands/docguard.*.md` (DocGuard's slash-command docs, which it
   installs into the project) for count claims. A stale "N validators" baked into
   those shipped docs was being reported as the *user's* drift in every project
-  that had them (field test: quick-recon-tool, hugocross). A user's own
+  that had them (field test: a downstream project, a downstream project). A user's own
   `commands/<name>.md` is unaffected.
 - **Dogfooding closure** — Canonical-Sync now scans **AGENTS.md** in addition to
   README for "ships N commands"/"N validators" surface claims (it only checked

package/cli/commands/guard.mjs

@@ -664,12 +664,23 @@ export function runGuard(projectDir, config, flags) {
 
   const data = runGuardInternal(projectDir, config);
 
+  // A project with no .docguard.json has not adopted DocGuard. Its "failures"
+  // are missing canonical docs, which is not the same fact as "this project
+  // failed its checks" — and consumers need to tell them apart. Exit 3 says
+  // "not initialised": still non-zero, so a CI gate that fails on any non-zero
+  // status is unchanged, but the generated Git hook can let the commit through
+  // instead of blocking a project that never adopted the tool.
+  const uninitialised = !existsSync(resolvePath(projectDir, '.docguard.json'));
+  const exitFor = d => (d.effectiveErrors > 0
+    ? (uninitialised ? 3 : 1)
+    : d.effectiveWarnings > 0 ? 2 : 0);
+
   // ── SARIF output (2.1.0) ──
   // Same flush discipline as the JSON branch below (bug-105): set exitCode and
   // write+return so a piped consumer never gets a truncated payload.
   if (flags.format === 'sarif') {
     const sarif = toSarif(data, { projectDir });
-    process.exitCode = data.effectiveErrors > 0 ? 1 : data.effectiveWarnings > 0 ? 2 : 0;
+    process.exitCode = exitFor(data);
     process.stdout.write(JSON.stringify(sarif, null, 2) + '\n');
     return;
   }
@@ -680,7 +691,7 @@ export function runGuard(projectDir, config, flags) {
   // Exit-code semantics identical to sarif/json.
   if (flags.format === 'junit') {
     const xml = toJUnit(data);
-    process.exitCode = data.effectiveErrors > 0 ? 1 : data.effectiveWarnings > 0 ? 2 : 0;
+    process.exitCode = exitFor(data);
     process.stdout.write(xml + '\n');
     return;
   }
@@ -689,7 +700,7 @@ export function runGuard(projectDir, config, flags) {
   if (flags.format === 'json') {
     // Use severity-aware effective counts for exit code; raw counts stay in the JSON
     // for display tools that want to show the full picture.
-    const code = data.effectiveErrors > 0 ? 1 : data.effectiveWarnings > 0 ? 2 : 0;
+    const code = exitFor(data);
     // v0.28: set exitCode + return instead of process.exit(). A large JSON
     // payload (>~8 KB) written to a PIPE flushes asynchronously; an immediate
     // process.exit() truncates it mid-string, so a CI consumer parsing stdout
@@ -991,5 +1002,5 @@ export function runGuard(projectDir, config, flags) {
   // v0.28: exitCode + return (not process.exit) so the buffered text output
   // flushes to a pipe before the process exits — same truncation fix as the
   // JSON path above.
-  process.exitCode = data.effectiveErrors > 0 ? 1 : data.effectiveWarnings > 0 ? 2 : 0;
+  process.exitCode = exitFor(data);
 }

package/cli/commands/hooks.mjs

@@ -105,6 +105,17 @@ import { listCanonicalDocs } from '../shared-ignore.mjs';
 
 // Git enforcement is offline and fail-closed; agent nudges stay best-effort.
 const ENFORCEMENT_RUNTIME = `
+# A Git hook is repo-wide (it lives in the common .git/hooks and is shared by
+# every linked worktree), but .docguard.json is a branch-local tracked file.
+# During adoption the two cannot be consistent: the hook is already active
+# everywhere while the config exists on one branch only. A project that has not
+# adopted DocGuard must not be blocked by a hook installed from another branch.
+if [ ! -f ".docguard.json" ]; then
+  echo "DocGuard: not initialised here (no .docguard.json) — skipping."
+  echo "          Adopt it with: docguard init"
+  exit 0
+fi
+
 if ! command -v node >/dev/null 2>&1; then
   echo "❌ Node.js runtime not found — operation blocked" >&2
   exit 1
@@ -136,7 +147,10 @@ ${ENFORCEMENT_RUNTIME}
 "$DOCGUARD" guard
 EXIT_CODE=$?
 
-if [ "$EXIT_CODE" -ne 0 ] && [ "$EXIT_CODE" -ne 2 ]; then
+if [ "$EXIT_CODE" -eq 3 ]; then
+  echo ""
+  echo "DocGuard: project not initialised — commit allowed"
+elif [ "$EXIT_CODE" -ne 0 ] && [ "$EXIT_CODE" -ne 2 ]; then
   echo ""
   echo "❌ DocGuard guard FAILED — commit blocked"
   echo "   Fix the errors above, then try again."
@@ -265,7 +279,10 @@ fi
 "$DOCGUARD" guard
 EXIT_CODE=$?
 
-if [ "$EXIT_CODE" -ne 0 ] && [ "$EXIT_CODE" -ne 2 ]; then
+if [ "$EXIT_CODE" -eq 3 ]; then
+  echo ""
+  echo "DocGuard: project not initialised — commit allowed"
+elif [ "$EXIT_CODE" -ne 0 ] && [ "$EXIT_CODE" -ne 2 ]; then
   echo ""
   echo "❌ DocGuard guard FAILED — commit blocked."
   echo "   Remaining issues need an AI agent (content rewrites, not mechanical):"

package/cli/commands/trace.mjs

@@ -26,7 +26,7 @@ const CODE_EXTENSIONS = new Set([
 
 // v0.16-P2: language-aware patterns. The original JS/TS-only sets created
 // false-negative warnings on Python/Rust/Go/Java projects (reported by the
-// quick-recon-tool Python user: TEST-SPEC.md was flagged unlinked even
+// a downstream project Python user: TEST-SPEC.md was flagged unlinked even
 // though Python tests existed because `.test.mjs` didn't match `test_*.py`).
 import { TEST_PATTERNS, TRACE_MAP, isTraceableSource } from '../shared-trace-patterns.mjs';
 

package/cli/scanners/api-doc.mjs

@@ -32,7 +32,7 @@ const HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', '
  *   optional c-all  `/shop/[[...filters]]`  → `/shop/{}`
  * Without the bracket rule, a doc written in Next.js `[id]` syntax never matched
  * the code-scan's `:id`, so every dynamic route double-fired as both
- * "documented-but-absent" and "undocumented" (field test: hugocross_revamp).
+ * "documented-but-absent" and "undocumented" (field test: a downstream project).
  * @param {string} raw
  * @returns {string} normalized path (e.g. "/api/users/{}") or '' if not a path
  */

package/cli/validators/diff-suspicion.mjs

@@ -47,7 +47,7 @@ const GENERIC_TOKENS = new Set([
   'font', 'color', 'colors', 'tracking', 'surface', 'auto', 'full', 'next',
   'body', 'sans', 'blue', 'accent', 'size', 'spacing', 'margin', 'padding',
   'width', 'height', 'flex', 'grid', 'bold', 'bg', 'rounded',
-  // HTTP / REST / handler plumbing — generic across any API route (globalshares
+  // HTTP / REST / handler plumbing — generic across any API route (a downstream project
   // corpus: a route-inventory doc + heavy rewrites flooded findings with these)
   'code', 'json', 'err', 'error', 'message', 'auth', 'get', 'put', 'post',
   'patch', 'delete', 'req', 'res', 'route', 'routes', 'handler', 'endpoint',

package/cli/validators/docs-coverage.mjs

@@ -56,7 +56,7 @@ const COMMON_DOTFILES = new Set([
 // Generated tool artifacts (caches, coverage data, lock-data) that land at the
 // repo root but are NOT configuration a human authors or documents. Treating
 // them as "undocumented config files" is a false positive (field test:
-// quick-recon-tool flagged pytest's `.coverage` SQLite data file). Matched by
+// a downstream project flagged pytest's `.coverage` SQLite data file). Matched by
 // exact name OR prefix (`.coverage.<host>.<pid>` is coverage.py's parallel form).
 const GENERATED_DOTFILE_PREFIXES = ['.coverage', '.eslintcache', '.stylelintcache', '.tsbuildinfo'];
 function isGeneratedArtifact(name) {

package/cli/writers/generate-io.mjs

@@ -14,15 +14,33 @@ import { resolve, dirname } from 'node:path';
  * Create a .bak backup of an existing file before --force overwrites it.
  * Only backs up if the file exists and has content.
  */
-export function backupFile(filePath) {
-  if (existsSync(filePath)) {
-    try {
-      const content = readFileSync(filePath, 'utf-8');
-      if (content.trim().length > 0) {
-        copyFileSync(filePath, filePath + '.bak');
+export function backupFile(filePath, nextContent = null) {
+  if (!existsSync(filePath)) return;
+  try {
+    const content = readFileSync(filePath, 'utf-8');
+    if (content.trim().length === 0) return;
+
+    // Nothing to preserve when the file is already what we are about to write.
+    // Backing it up anyway produced a redundant .bak and, worse, consumed the
+    // single backup slot that may still hold the user's own original.
+    if (nextContent !== null && content === nextContent) return;
+
+    // The backup slot is single and unversioned. Overwriting it destroys the
+    // previous backup, which on a second forced install is the user's ORIGINAL
+    // file — unrecoverable, because a .git/hooks file is not in version control.
+    // Only ever replace a .bak we wrote ourselves; otherwise keep it and write
+    // a timestamped sibling.
+    const bak = filePath + '.bak';
+    if (existsSync(bak)) {
+      const prior = readFileSync(bak, 'utf-8');
+      if (prior !== content) {
+        const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+        copyFileSync(filePath, `${filePath}.${stamp}.bak`);
+        return;
       }
-    } catch { /* backup failure is non-fatal */ }
-  }
+    }
+    copyFileSync(filePath, bak);
+  } catch { /* backup failure is non-fatal */ }
 }
 
 /**
@@ -31,7 +49,7 @@ export function backupFile(filePath) {
  */
 export function safeWrite(filePath, content) {
   mkdirSync(dirname(filePath), { recursive: true });
-  backupFile(filePath);
+  backupFile(filePath, content);
   writeFileSync(filePath, content, 'utf-8');
 }
 

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.5"
+  version: "0.41.6"
   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.5
+  version: 0.41.6
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.41.5 -->
+<!-- docguard:version: 0.41.6 -->
 
 # 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.5
+  version: 0.41.6
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.41.5 -->
+<!-- docguard:version: 0.41.6 -->
 
 # 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.5
+  version: 0.41.6
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.41.5 -->
+<!-- docguard:version: 0.41.6 -->
 
 # 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.5
+  version: 0.41.6
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.41.5 -->
+<!-- docguard:version: 0.41.6 -->
 
 # 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.5
+  version: 0.41.6
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.41.5 -->
+<!-- docguard:version: 0.41.6 -->
 
 # 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.5
+        uses: raccioly/docguard@v0.41.6
         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.5
+        run: npm install --global --ignore-scripts docguard-cli@0.41.6
 
       - name: Run DocGuard
         shell: bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.41.5",
+  "version": "0.41.6",
   "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.5
+        run: npm install --global --ignore-scripts docguard-cli@0.41.6
 
       - name: Run DocGuard
         shell: bash