docguard-cli 0.41.4 → 0.41.6

package/CHANGELOG.md

@@ -7,6 +7,98 @@ 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`.
+
+### Changed
+
+- fix: four tool defects from a downstream field report (#410)
+- chore: use generic project references and stop tracking .wolf/ (#411)
+
+
+### Changed
+
+- Replaced named third-party project references in source comments, tests and
+  changelog history with generic terms. Field-test provenance is still recorded;
+  the projects are no longer identified by name. Stopped tracking `.wolf/`
+  (local agent working notes, never part of the published package).
+
+### Fixed
+
+- Stop counting a review stamp as a content change. Adding or updating
+  `<!-- docguard:last-reviewed -->` in a spec artifact changed its registry
+  digest, so the review that Freshness (FRS002) asks for immediately made the
+  spec registry `STALE` and demanded `specs --write` — the tool created the work
+  it then reported. That marker is now excluded from the digest source;
+  `docguard:version` and `docguard:status` still re-digest, because those are
+  substantive lifecycle edits. Registries written by earlier releases keep their
+  trust (both digest forms are accepted); a project whose specs already carry a
+  review stamp needs one `docguard specs --write` to settle.
+- Stop reporting a document as "review due" while it is staged in the commit
+  being checked. A pre-commit hook runs `guard` against the very change being
+  made, so an author updating `AGENTS.md` was told to review `AGENTS.md`. Being
+  edited in this commit is now treated as the strongest freshness signal and
+  outranks the repository-wide commit-count heuristic.
+- Stop leaving `.docguard-specs.json.bak` behind. `specs --write` regenerates a
+  Git-tracked, fully derived file, so the backup was noise that DocGuard then
+  reported as an undocumented config file (DCV001). DocGuard also no longer
+  raises DCV001 for any `.bak` it wrote itself.
+- Report what `specs --write` actually did. It printed the pre-write differences
+  under a "Differences:" heading after reporting `WRITTEN`, reading as though the
+  drift were still outstanding; resolved differences are now labelled as resolved.
+
+
 ## [0.41.4] - 2026-09-17
 
 Automated weekly release — batches everything merged since `v0.41.3`.
@@ -1233,7 +1325,7 @@ Context7 identified in the platform review).
   `website/docs/`) are now claim-scanned and counted as "tracked" **without being
   enrolled** in `requiredFiles.canonical`. A folder literally named `documentation/`
   is unambiguously a doc home DocGuard governs; this stays distinct from the
-  arbitrary-subdir walk the wu-whatsappinbox scoping fix removed (a number buried
+  arbitrary-subdir walk the downstream-project scoping fix removed (a number buried
   in `security/wolf-archive/` is still never scanned). `config.docs.dirs` EXTENDS
   the set with non-standard homes (it never replaces auto-detection); use
   `.docguardignore` to exclude a conventional dir. The doc-home set is now a single
@@ -1401,7 +1493,7 @@ dogfooding.
 ## [0.27.0] - 2026-06-19
 
 Acting on a third end-to-end LLM field report (a coding agent ran DocGuard on a
-Vite+Vitest WhatsApp-inbox repo). The headline is architectural: DocGuard is a
+Vite+Vitest downstream repo). The headline is architectural: DocGuard is a
 tool *for LLMs*, so every run should end with a suggested next action and every
 finding it surfaces should be addressable, suppressible, and — when uncertain —
 reportable. This release introduces structured **findings** (stable codes +
@@ -1767,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
@@ -2691,7 +2783,7 @@ and adds a cross-cutting "no validator throws" safety net. **22 validators,
 ### Fixed
 
 - **B-5: Freshness validator crashed with `getLastCommitDate is not defined`.** A an enterprise client project install of v0.13.0 produced this ReferenceError despite all the imports being correct in source — we couldn't reproduce locally, but the user's report was clear. Fix: defensive dynamic import in `freshness.mjs` that falls back to the pre-v0.13 inline implementation if `../shared-git.mjs` ever fails to load. Worst-case behavior is now "rename detection silently disabled" instead of "validator crashes with useless message". Also added an inline fallback for the same defensive layering. Reported by an enterprise client project.
-- **B-6: Cross-Reference didn't URL-decode link target paths.** A markdown link like `[name](../WU%20Documentation/foo.md)` (where the directory has a space) was looked up with `existsSync('../WU%20Documentation/foo.md')` literally — the filesystem stores the decoded form. Now: `resolveTarget` tries BOTH the literal path (for paths that legitimately contain `%`) and the URL-decoded form. **Effect on an enterprise client project: Cross-Reference went from 28/28 to 101/101 checks — 73 previously-broken refs now resolve correctly.** Reported by an enterprise client project.
+- **B-6: Cross-Reference didn't URL-decode link target paths.** A markdown link like `[name](../Client%20Documentation/foo.md)` (where the directory has a space) was looked up with `existsSync('../Client%20Documentation/foo.md')` literally — the filesystem stores the decoded form. Now: `resolveTarget` tries BOTH the literal path (for paths that legitimately contain `%`) and the URL-decoded form. **Effect on an enterprise client project: Cross-Reference went from 28/28 to 101/101 checks — 73 previously-broken refs now resolve correctly.** Reported by an enterprise client project.
 - **Cross-cutting safety net**: new `tests/guard-no-throw.test.mjs` runs guard against a fixture repo and asserts no validator leaks a ReferenceError / TypeError / "is not defined" / "is not a function" / "Cannot read properties of undefined" pattern into user-facing output. Found a *second* lurking bug while writing the test: Structure validator threw `Cannot read properties of undefined (reading 'some')` when `config.requiredFiles.agentFile` was missing — fixed with defensive array-or-string coercion + skip-when-missing for `changelog` too. This safety net runs in CI, catching the entire class of developer-error-leaks before release.
 
 ### Added

package/cli/commands/diff.mjs

@@ -203,7 +203,7 @@ export function diffEntities(dir, config = {}) {
 
 // v0.16-P4 (revised in v0.17.1): conservative denylist of system env vars
 // that appear in prose ("the venv `PATH`") but are never user-set app env
-// vars. v0.17.1-B7: trimmed to TRULY-system-only after wu feedback —
+// vars. v0.17.1-B7: trimmed to TRULY-system-only after downstream feedback —
 // NODE_ENV / CI / GITHUB_* are legitimately app env vars when read via
 // process.env. Including them caused diff to falsely flag `NODE_ENV` as
 // "in code but not docs" even when ENVIRONMENT.md documented it.

package/cli/commands/guard.mjs

@@ -224,7 +224,7 @@ function renderableItems(v) {
 // .md could drift forever while guard stayed green — the human had to REMEMBER to
 // enroll each doc, which is exactly the step that fails silently. We deliberately
 // do NOT deep-scan every doc for claims (that floods false positives — see the
-// wu-whatsappinbox scar in metrics-consistency). Instead we cheaply report what's
+// downstream-project scar in metrics-consistency). Instead we cheaply report what's
 // under a validation tier and what isn't, turning silent non-coverage into a
 // visible nudge. Pure visibility — never gates the build.
 //
@@ -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/specs.mjs

@@ -7,9 +7,8 @@
 
 import { createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { safeWrite } from '../writers/generate-io.mjs';
 import { commitFileTransaction } from '../writers/file-transaction.mjs';
 import { appendImplementationOutcome } from '../writers/spec-outcomes.mjs';
 import { serializeLifecycleContext } from '../scanners/lifecycle-context.mjs';
@@ -227,7 +226,9 @@ function printResult(result) {
   console.log(`Registry: ${SPEC_REGISTRY_PATH}`);
   console.log(`Specs: ${result.specs}; tombstones: ${result.tombstones}`);
   if (result.differences?.length) {
-    console.log('Differences:');
+    // After --write the registry already matches; listing the pre-write diff
+    // under "Differences" read as though the drift were still outstanding.
+    console.log(result.status === 'WRITTEN' ? 'Resolved by this write:' : 'Differences:');
     for (const difference of result.differences) {
       console.log(`  ${difference.path}: ${difference.message}`);
     }
@@ -264,7 +265,10 @@ export function runSpecs(projectDir, config, flags = {}) {
     }
     let status = projection.current ? 'CURRENT' : projection.exists ? 'STALE' : 'MISSING';
     if (flags.write && !projection.current) {
-      safeWrite(resolve(projectDir, SPEC_REGISTRY_PATH), projection.serialized);
+      // Deliberately not safeWrite: that keeps a .bak, and the registry is
+      // generated and Git-tracked, so the backup is noise DocGuard then reports
+      // as an undocumented config file.
+      writeFileSync(resolve(projectDir, SPEC_REGISTRY_PATH), projection.serialized, 'utf-8');
       status = 'WRITTEN';
     }
     const result = {

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/scanners/spec-registry.mjs

@@ -33,6 +33,22 @@ const STOP_TERMS = new Set(['must', 'should', 'with', 'from', 'that', 'this', 'h
 
 const posix = path => path.split(sep).join('/').replace(/^\.\//, '');
 const digest = content => `sha256:${createHash('sha256').update(content).digest('hex')}`;
+
+// A review stamp is not a content change. `docguard:last-reviewed` is written by
+// reviewing a document — the very thing Freshness (FRS002) asks for — so letting
+// it reach the digest made every review a registry change: review the doc, then
+// `specs --write` to settle the registry the review just invalidated. Strip only
+// that marker; `docguard:version` and `docguard:status` are substantive lifecycle
+// edits and must keep re-digesting.
+const REVIEW_STAMP_RE = /^[ \t]*<!--[ \t]*docguard:last-reviewed[^>]*-->[ \t]*\r?\n?/gim;
+export const digestSource = content => content.replace(REVIEW_STAMP_RE, '');
+const contentDigest = content => digest(digestSource(content));
+
+// Registries written before the review stamp was excluded carry a digest over the
+// raw bytes. Accept either so upgrading does not silently drop trust in an
+// otherwise untouched spec; the next `specs --write` migrates the entry.
+const digestMatches = (recorded, content) =>
+  recorded === contentDigest(content) || recorded === digest(content);
 const sortedUnique = values => [...new Set(values)].sort((a, b) => a.localeCompare(b));
 
 function registryDifferences(left, right) {
@@ -281,7 +297,7 @@ export function trustedSpecLifecycleIndex(projectDir) {
     try { content = readFileSync(resolve(projectDir, entry.path), 'utf8'); } catch { continue; }
     if (parseSpecId(content) !== entry.specId) continue;
     const artifact = entry.observed?.artifacts?.find(item => item.path === entry.path);
-    if (!artifact || artifact.digest !== digest(content)) continue;
+    if (!artifact || !digestMatches(artifact.digest, content)) continue;
     if (entry.reviewed?.lifecycle?.context !== 'current' || entry.reviewed.lifecycle.storage !== 'working_tree') continue;
     trusted.set(`${entry.specId}\0${entry.path}`, entry.reviewed.lifecycle);
   }
@@ -307,7 +323,7 @@ export function uncommittedPlannedSpecLifecycleIndex(projectDir) {
     try { content = readFileSync(resolve(projectDir, entry.path), 'utf8'); } catch { continue; }
     if (parseSpecId(content) !== entry.specId) continue;
     const artifact = entry.observed?.artifacts?.find(item => item.path === entry.path);
-    if (!artifact || artifact.digest !== digest(content)) continue;
+    if (!artifact || !digestMatches(artifact.digest, content)) continue;
     if (entry.reviewed.lifecycle.context !== 'current' || entry.reviewed.lifecycle.storage !== 'working_tree') continue;
     candidates.set(`${entry.specId}\0${entry.path}`, entry.reviewed.lifecycle);
   }
@@ -494,7 +510,7 @@ export function projectSpecRegistry(projectDir, config = {}, options = {}) {
     const artifacts = artifactsForFeature
       .map(artifact => ({
         path: posix(relative(projectDir, artifact)),
-        digest: digest(readFileSync(artifact, 'utf8')),
+        digest: contentDigest(readFileSync(artifact, 'utf8')),
       }));
     specs.push({
       specId,

package/cli/shared.mjs

@@ -289,7 +289,7 @@ import { resolve, relative } from 'node:path';
  * Conventional documentation-home directory names. A folder named one of these
  * is unambiguously "docs DocGuard governs" — distinct from arbitrary markdown
  * buried in a non-doc subdir (security/wolf-archive/, vendored toolkits), which
- * the wu-whatsappinbox scoping fix deliberately excludes. We auto-track the
+ * the downstream-project scoping fix deliberately excludes. We auto-track the
  * former and never blanket-walk the latter.
  */
 export const DEFAULT_DOC_DIRS = [

package/cli/validators/cross-reference.mjs

@@ -295,9 +295,9 @@ function editDistance(a, b) {
 function resolveTarget(sourcePath, targetRel, projectDir) {
   if (!targetRel) return null;
   // B-6: try BOTH the literal path and the URL-decoded form. CommonMark
-  // accepts `[name](../WU%20Documentation/foo.md)` for paths with spaces,
-  // and the decoded form (`../WU Documentation/foo.md`) is what hits the
-  // filesystem. The angle-bracket form `<../WU Documentation/foo.md>` is
+  // accepts `[name](../Client%20Documentation/foo.md)` for paths with spaces,
+  // and the decoded form (`../Client Documentation/foo.md`) is what hits the
+  // filesystem. The angle-bracket form `<../Client Documentation/foo.md>` is
   // already non-URL-encoded by the time it reaches us. Try literal first
   // (handles paths that legitimately contain `%`), then decoded.
   const candidates = [targetRel];

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,10 +56,15 @@ 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) {
+  // `.bak` is written by DocGuard's own safeWrite before it overwrites a file.
+  // Reporting it as an undocumented config file made the tool flag its own
+  // backup (field report: `specs --write` -> DCV001 on
+  // `.docguard-specs.json.bak`).
+  if (name.endsWith('.bak')) return true;
   return GENERATED_DOTFILE_PREFIXES.some(p => name === p || name.startsWith(p + '.'));
 }
 

package/cli/validators/environment.mjs

@@ -139,7 +139,7 @@ export function validateEnvironment(projectDir, config) {
     const varRe = /`([A-Z][A-Z0-9_]*[A-Z0-9])`/g;
     // v0.16-P4 (revised in v0.17.1-B7): skip backticked SYSTEM env vars
     // (PATH, HOME, USER, etc.) that appear in ENVIRONMENT.md prose. Trimmed
-    // to TRULY-system-only after wu feedback — NODE_ENV / CI / GITHUB_* were
+    // to TRULY-system-only after downstream feedback — NODE_ENV / CI / GITHUB_* were
     // causing asymmetric flagging between diff and this validator. Apps
     // legitimately treat NODE_ENV as app config; keep the list to vars that
     // no sane application would read as runtime config.

package/cli/validators/freshness.mjs

@@ -188,6 +188,24 @@ function getCodeHistory(dir, ignored) {
   }).filter(commit => commit.paths.length);
 }
 
+/**
+ * Documents staged in the commit currently being checked.
+ *
+ * A pre-commit hook runs guard against the very change being made, so a doc the
+ * author is updating right now was still being reported "review due" — the work
+ * the finding asks for is in the index (field report: AGENTS.md flagged while
+ * staged). Returns POSIX-relative paths; empty when git is unavailable.
+ */
+function getStagedPaths(dir) {
+  try {
+    const out = execFileSync('git', ['diff', '--cached', '--name-only', '-z'],
+      { cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+    return new Set(out.split('\0').filter(Boolean));
+  } catch {
+    return new Set();
+  }
+}
+
 /**
  * Check if git is available in this project.
  */
@@ -256,9 +274,18 @@ export function validateFreshness(dir, config) {
   const REVIEW_THRESHOLD_DAYS = 30; // Repository-wide trigger, not proof of drift
   const WARNING_THRESHOLD_COMMITS = 10; // Repository-wide review trigger
 
+  const stagedPaths = getStagedPaths(dir);
+
   for (const docFile of docFiles) {
     const docPath = resolve(dir, docFile);
     if (!existsSync(docPath)) continue;
+    // Being edited in this very commit is the strongest possible freshness
+    // signal; a repository-wide commit count cannot override it.
+    if (stagedPaths.has(relPosix(dir, docPath))) {
+      results.push({ status: 'skip', doc: docFile,
+        message: `${docFile} is staged in this change — review not due; the document is being updated now` });
+      continue;
+    }
     const docStatus = readDocStatus(docPath);
     if (['historical', 'superseded', 'deprecated'].includes(docStatus)) {
       results.push({ status: 'skip', doc: docFile,

package/cli/validators/metrics-consistency.mjs

@@ -308,7 +308,7 @@ function findMarkdownFiles(dir, config = {}) {
   // The old code recursively walked the WHOLE repo from the root, so it swept in
   // OpenWolf session archives (security/wolf-archive/**/memory.md) and vendored
   // toolkit READMEs whose unrelated "N checks" prose was then reported as the
-  // USER's drift (field test: wu-whatsappinbox, ~39 false warnings the author
+  // USER's drift (field test: downstream-project, ~39 false warnings the author
   // could not act on). Scoping to the docs DocGuard actually governs fixes it.
   try {
     for (const entry of readdirSync(dir)) {
@@ -323,7 +323,7 @@ function findMarkdownFiles(dir, config = {}) {
   // conventional doc dirs (docs/, documentation/, guides/, …) or honors an
   // explicit config.docs.dirs. NAMED dirs only — code/tooling dirs (security/,
   // backend/, src/, …) and arbitrary subdirs are still NEVER walked (the
-  // wu-whatsappinbox false-positive flood the scoping fix removed).
+  // downstream-project false-positive flood the scoping fix removed).
   const canonical = config && config.requiredFiles && Array.isArray(config.requiredFiles.canonical)
     ? config.requiredFiles.canonical : [];
   for (const rel of canonical) {

package/cli/validators/test-spec.mjs

@@ -78,7 +78,7 @@ export function validateTestSpec(projectDir, config) {
     // different shapes (Controllers, Services, an "Integration Tests" inventory
     // like `| test-file | what it covers |`). Without this guard a prose
     // "what it covers" cell — "Health endpoint with real dependencies" — gets
-    // checked as a missing test file (false positive; field test: wu-whatsappinbox).
+    // checked as a missing test file (false positive; field test: downstream-project).
     const isPathLike = (v) => !!v && !/\s/.test(v) && (/[\\/]/.test(v) || /\.[A-Za-z0-9]{1,6}$/.test(v));
 
     for (const row of pipeRows.slice(1)) { // skip the header row

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