docguard-cli 0.41.4 → 0.41.5

package/CHANGELOG.md

@@ -7,6 +7,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +1275,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 +1443,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 +
@@ -2691,7 +2733,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.
 //

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/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/docs-coverage.mjs

@@ -60,6 +60,11 @@ const COMMON_DOTFILES = new Set([
 // 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/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.5"
   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.5
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.41.4 -->
+<!-- docguard:version: 0.41.5 -->
 
 # 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.5
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.41.4 -->
+<!-- docguard:version: 0.41.5 -->
 
 # 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.5
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.41.4 -->
+<!-- docguard:version: 0.41.5 -->
 
 # 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.5
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.41.4 -->
+<!-- docguard:version: 0.41.5 -->
 
 # 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.5
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.41.4 -->
+<!-- docguard:version: 0.41.5 -->
 
 # 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.5
         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.5
 
       - name: Run DocGuard
         shell: bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.41.4",
+  "version": "0.41.5",
   "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.5
 
       - name: Run DocGuard
         shell: bash