docguard-cli 0.41.3 → 0.41.5

package/CHANGELOG.md

@@ -7,6 +7,81 @@ 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`.
+
+### Changed
+
+- fix: correct the validator-surface claim and document DOCGUARD_API_KEY (#408)
+- fix: harden adoption precision boundaries (#406)
+
+
+### Fixed
+
+- Document `DOCGUARD_API_KEY` in the canonical environment doc. `ENVIRONMENT.md`
+  claimed DocGuard uses "no API keys" and needs no environment variables, which
+  contradicted `SECURITY.md` and the HTTP MCP server, where the variable is
+  required to bind a non-loopback host. Core CLI commands still need no credential.
+- Enforce the published validator count in `npm test`. Canonical-Sync and
+  Metrics-Consistency already detect a stale "N validators" claim, but they emit
+  warnings and the CI self-scan deliberately tolerates guard's warnings-only exit,
+  so a wrong count could reach `main` with every check green. The count is now
+  asserted against the shipped `cli/validators/*.mjs` modules, and README explains
+  why guard prints 30 result rows for 29 validators.
+- Count DocGuard validator claims from one shared source of truth: the
+  validator modules shipped in the installed package. A consumer's intentionally
+  disabled validators and extra guard checks cannot create a false MET001 or
+  CSY003 finding, or an unsafe count rewrite.
+- Keep instruction-pointer basename resolution out of Git-ignored directories
+  and nested Git checkouts, including linked worktree copies.
+- Keep planned lifecycle registries that are new, removed from the Git index,
+  or modified pending commit non-authoritative for TRC004 while explaining how
+  to restore or commit the registry and current spec artifacts; the remediation
+  no longer suggests adding an artificial `@req` marker.
+
 ## [0.41.3] - 2026-09-15
 
 Automated weekly release — batches everything merged since `v0.41.2`.
@@ -1200,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
@@ -1368,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 +
@@ -2658,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/README.md

@@ -77,7 +77,7 @@ graph TD
     Commands --> setup["setup wizard"]
     Commands --> other["diff · init · fix · trace · impact · sync · reconcile · retire · specs<br/>explain · memory · upgrade · agents · hooks · badge · ci · watch"]
 
-    guard --> Validators["Validators (30)"]
+    guard --> Validators["Validators (29)"]
     generate --> Scanners["Scanners (4)<br/>routes · schemas · doc-tools · speckit"]
     score --> Scoring["Weighted Scoring<br/>8 categories"]
     diagnose --> Validators
@@ -275,7 +275,7 @@ DocGuard ships **23 commands** (the "Daily 5" + 18 situational tools, including
 | Command | What It Does |
 |:--------|:-------------|
 | `init`  | Bootstrap a project (`--wizard` for interactive · `--with <name>` for scaffolders) |
-| `guard` | Validate against canonical docs — 30 validators |
+| `guard` | Validate against canonical docs — 29 validators |
 | `diff`  | Show gaps between docs and code (`--since <ref>` for impact mode) |
 | `sync`  | Refresh code-truth doc sections — keeps memory always up to date |
 | `score` | Structural CDD maturity score (0-100; not a guard verdict; `--diff` for delta between refs) |
@@ -411,7 +411,13 @@ $ npx docguard-cli generate
 
 ## 🔍 Validators
 
-DocGuard runs **30 automated validators** on every `guard` check. Source-facing validators are language-aware where their evidence model applies; repository and document validators operate independently of source language.
+DocGuard runs **29 automated validators** on every `guard` check. Source-facing validators are language-aware where their evidence model applies; repository and document validators operate independently of source language.
+
+> **Counting note:** `guard` prints 30 result rows, not 29. `Structure` emits a
+> second check result (`Doc Sections`) under the same validator key, so rows are
+> checks, not validators. The published number is the count of shipped
+> `cli/validators/*.mjs` modules and is enforced by tests — don't derive it by
+> counting output rows.
 
 | # | Validator | What It Checks | Default |
 |:--|:----------|:--------------|:--------|
@@ -544,7 +550,7 @@ DocGuard provides AI agent slash commands for integrated workflows. Installed au
 | Command | What It Does |
 |:--------|:-------------|
 | `/docguard.init` | Initialize Canonical-Driven Development in a new or existing project |
-| `/docguard.guard` | Run quality validation — check all 30 validators |
+| `/docguard.guard` | Run quality validation — check all 29 validators |
 | `/docguard.review` | Analyze doc quality and suggest improvements |
 | `/docguard.fix` | Generate targeted fix prompts for specific issues |
 | `/docguard.update` | Update canonical docs after code changes — detect drift and sync documentation |

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/docguard.mjs

@@ -341,7 +341,7 @@ const COMMAND_HELP = {
     summary: 'Maintain the deterministic spec lifecycle and evidence registry.',
     usage: 'docguard specs [--check|--write] | docguard specs preflight [--path <spec>] | docguard specs complete --id <spec-id> [--since <ref>] [--write --reason <text>]',
     flags: [
-      ['--check', 'Exit 2 when the committed registry is missing, stale, or inconsistent'],
+      ['--check', 'Exit 2 when the committed registry is missing, stale, or inconsistent; planned lifecycle deferral requires a clean tracked registry'],
       ['--write', 'Refresh observed evidence while preserving reviewed lifecycle fields'],
       ['preflight', 'Brief prior specs, or gate a generated draft with --path'],
       ['complete', 'Plan or apply the implemented→verified evidence transaction'],

package/cli/findings.mjs

@@ -425,7 +425,7 @@ export const CODES = {
   CSY003: {
     validator: 'canonicalSync',
     title: 'Stale "N validators" claim',
-    help: "A surface doc (README.md/AGENTS.md) states a validator count that does not match guard's actual count (validator files + the inlined Doc Sections validator). Update the claim.",
+    help: 'A surface doc (README.md/AGENTS.md) states a validator count that does not match the validator modules shipped in the package. Guard can emit multiple check results from one module; those do not increase the public validator count. Update the claim.',
     suppress: null,
   },
   CSY004: {

package/cli/scanners/instruction-audit.mjs

@@ -34,7 +34,13 @@
 import { readFileSync, readdirSync, lstatSync, realpathSync } from 'node:fs';
 import { resolve, join, dirname, relative, isAbsolute, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { buildIgnoreFilter, loadDocguardIgnore, DEFAULT_IGNORE_DIRS, relPosix } from '../shared-ignore.mjs';
+import {
+  buildIgnoreFilter,
+  loadDocguardIgnore,
+  loadGitIgnoredFilter,
+  DEFAULT_IGNORE_DIRS,
+  relPosix,
+} from '../shared-ignore.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -165,6 +171,7 @@ function basenameIndex(projectDir, wanted, config = {}) {
   let root;
   try { root = realpathSync(projectDir); }
   catch { return { matches, complete: false, visited: 0, reason: 'repository-unavailable' }; }
+  const gitIgnored = loadGitIgnoredFilter(root);
   let visited = 0;
   let complete = true;
   let reason = null;
@@ -177,12 +184,22 @@ function basenameIndex(projectDir, wanted, config = {}) {
       if (DEFAULT_IGNORE_DIRS.has(entry.name) || entry.name === '.local' || /^\.env(?:\.|$)/i.test(entry.name)) continue;
       const full = resolve(dir, entry.name);
       const rel = relPosix(root, full);
-      if (ignored(rel)) continue;
+      if (ignored(rel) || (gitIgnored && gitIgnored(rel))) continue;
       let stat;
       try { stat = lstatSync(full); }
       catch { complete = false; reason ||= 'unreadable-entry'; continue; }
       if (stat.isSymbolicLink()) continue;
-      if (stat.isDirectory()) { walk(full); if (reason === 'entry-budget') return; }
+      if (stat.isDirectory()) {
+        // A linked Git worktree has a `.git` FILE; a nested checkout has a
+        // `.git` directory. Neither is part of this repository's primary
+        // instruction-pointer namespace, even when its parent was not added
+        // to .gitignore. Stop before reading duplicate checkout contents.
+        try {
+          if (lstatSync(join(full, '.git')).isFile() || lstatSync(join(full, '.git')).isDirectory()) continue;
+        } catch { /* ordinary directory: keep walking */ }
+        walk(full);
+        if (reason === 'entry-budget') return;
+      }
       else if (stat.isFile() && matches.has(entry.name)) matches.get(entry.name).push(rel);
     }
   };

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,13 +297,39 @@ 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);
   }
   return trusted;
 }
 
+/**
+ * Planned lifecycle entries that are structurally current but cannot defer
+ * traceability because the registry is not a clean, tracked Git artifact.
+ * This includes a new registry, a registry removed from the index, and a
+ * modified registry awaiting a commit. It is advisory-only: callers may
+ * explain the state, never use it as evidence.
+ */
+export function uncommittedPlannedSpecLifecycleIndex(projectDir) {
+  const candidates = new Map();
+  const loaded = readSpecRegistry(projectDir);
+  if (loaded.error || loaded.value?.schemaVersion !== SPEC_REGISTRY_SCHEMA_VERSION) return candidates;
+  if (trackedAndClean(projectDir, SPEC_REGISTRY_PATH)) return candidates;
+  for (const entry of loaded.value.specs) {
+    if (entry?.reviewed?.lifecycle?.delivery !== 'planned' || !entry.specId || !entry.path) continue;
+    if (!trackedAndClean(projectDir, entry.path)) continue;
+    let content;
+    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 || !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);
+  }
+  return candidates;
+}
+
 function taskCompletion(path) {
   if (!path || !existsSync(path)) return { checked: 0, total: 0 };
   const content = readFileSync(path, 'utf8');
@@ -468,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-ignore.mjs

@@ -91,6 +91,7 @@ export function isNonProductPath(relPath, config = {}) {
  * Returns [] if the file is missing or unreadable — never throws.
  */
 import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import { resolve as resolvePath, relative as relativePath, join as joinPath, sep } from 'node:path';
 
 /**
@@ -122,6 +123,54 @@ export function loadDocguardIgnore(projectDir) {
   }
 }
 
+/**
+ * Return a predicate for paths Git currently classifies as ignored.
+ *
+ * This deliberately delegates pattern semantics (including nested
+ * `.gitignore` files and negation) to Git instead of maintaining a second,
+ * incomplete gitignore parser. `--directory` lets callers prune a wholly
+ * ignored directory before reading its descendants. A missing Git repository
+ * or an unreadable/overflowing result returns null so callers can retain their
+ * existing conservative traversal behavior.
+ *
+ * Only untracked ignored paths are returned by Git, which is intentional:
+ * tracked source remains part of the repository even if a later ignore rule
+ * happens to mention its name.
+ *
+ * @param {string} projectDir
+ * @returns {((relPath: string) => boolean)|null}
+ */
+export function loadGitIgnoredFilter(projectDir) {
+  let result;
+  try {
+    result = spawnSync('git', [
+      'ls-files', '--others', '--ignored', '--exclude-standard', '--directory', '-z',
+    ], {
+      cwd: projectDir,
+      encoding: 'utf8',
+      maxBuffer: 8 * 1024 * 1024,
+      windowsHide: true,
+    });
+  } catch {
+    return null;
+  }
+  if (result.status !== 0 || result.error || typeof result.stdout !== 'string') return null;
+
+  const exact = new Set();
+  const directories = [];
+  for (const raw of result.stdout.split('\0')) {
+    const path = raw.replace(/\\/g, '/').replace(/^\.\//, '');
+    if (!path) continue;
+    if (path.endsWith('/')) directories.push(path);
+    else exact.add(path);
+  }
+  if (exact.size === 0 && directories.length === 0) return () => false;
+  return relPath => {
+    const path = String(relPath || '').replace(/\\/g, '/').replace(/^\.\//, '');
+    return exact.has(path) || directories.some(directory => path.startsWith(directory));
+  };
+}
+
 /**
  * Merge `.docguardignore` patterns into a config object's `ignore` array.
  *

package/cli/shared-validator-surface.mjs

@@ -0,0 +1,17 @@
+/**
+ * Validator Surface — package capability facts shared by self-governance
+ * validators. A validator module is one shipped `cli/validators/*.mjs` file;
+ * guard may emit additional check results from a module, but those are not
+ * extra public validator modules.
+ */
+
+import { readdirSync } from 'node:fs';
+
+/** Return the number of validator modules in one package directory, or null. */
+export function countValidatorModules(validatorsDir) {
+  try {
+    return readdirSync(validatorsDir).filter(name => name.endsWith('.mjs')).length;
+  } catch {
+    return null;
+  }
+}

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/canonical-sync.mjs

@@ -15,9 +15,9 @@
  *
  * What it checks:
  *   1. README "ships N commands" matches `cli/commands/*.mjs` file count
- *   2. README "N validators" matches `runGuardInternal()` output length
- *      (or, if no guardResults passed, falls back to file count + the 2
- *      inlined validators: Doc Sections in structure.mjs + Spec-Kit)
+ *   2. README "N validators" matches the shipped `cli/validators/*.mjs`
+ *      module count. Guard may emit multiple check results from one module;
+ *      those are not extra public validator modules.
  *   3. Validator names enumerated inline in README appear in guard output
  *
  * What it explicitly skips:
@@ -41,6 +41,7 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { resolve, join } from 'node:path';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
+import { countValidatorModules } from '../shared-validator-surface.mjs';
 
 /**
  * Validate that README count claims about DocGuard's surface match code-truth.
@@ -118,19 +119,13 @@ export function validateCanonicalSync(projectDir, config, guardResults) {
   }
   const actualCommandCount = actualUserFacingCount;
 
-  // Validator count: always use the file-count truth source. It's run-order
-  // independent (canonical-sync runs BEFORE metrics-consistency at guard time,
-  // so guardResults.length would undercount by 1). File count + 1 for the
-  // single inlined validator (Doc Sections, exported alongside Structure from
-  // structure.mjs).
-  const validatorFiles = readdirSync(validatorsDir).filter(f => f.endsWith('.mjs'));
-  const actualValidatorCount = validatorFiles.length + 1; // +1 for Doc Sections inlined in structure.mjs
-
-  // Names list (currently unused for warnings, but kept for future Check 3
-  // where the README enumerates validator names inline).
-  let actualValidatorNames = [];
-  if (Array.isArray(guardResults) && guardResults.length > 0) {
-    actualValidatorNames = guardResults.map(r => r.name).filter(Boolean);
+  // Validator count is the package capability count used by
+  // Metrics-Consistency too. It is run-order independent and excludes extra
+  // sub-check results emitted by a validator module (for example, Doc Sections
+  // from structure.mjs), which are checks rather than shipped validators.
+  const actualValidatorCount = countValidatorModules(validatorsDir);
+  if (actualValidatorCount === null) {
+    return compose({ na: true, naReason: 'cli/validators could not be read' });
   }
 
   // ── Read surface docs (README.md + AGENTS.md) ──────────────────────
@@ -204,9 +199,9 @@ export function validateCanonicalSync(projectDir, config, guardResults) {
         code: 'CSY003',
         validator: 'canonicalSync',
         severity: 'warn',
-        message: `A surface doc (README.md/AGENTS.md) claims ${uniqueWrong.map(n => `"${n} validators"`).join(' / ')} but guard reports ${actualValidatorCount}. Update it.`,
+        message: `A surface doc (README.md/AGENTS.md) claims ${uniqueWrong.map(n => `"${n} validators"`).join(' / ')} but DocGuard ships ${actualValidatorCount} validator modules. Update it.`,
         location: null,
-        suggestion: { kind: 'fix', text: 'Update the "N validators" claim in README.md/AGENTS.md to match guard\'s count' },
+        suggestion: { kind: 'fix', text: 'Update the "N validators" claim in README.md/AGENTS.md to match DocGuard\'s shipped validator modules' },
       }));
     }
   } else {

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

@@ -7,8 +7,10 @@
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { resolve, join, relative } from 'node:path';
+import { resolve, join, relative, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { loadIgnorePatterns, resolveDocDirs } from '../shared.mjs';
+import { countValidatorModules } from '../shared-validator-surface.mjs';
 // v0.29 consolidation: walker + glob counting live in shared-ignore.mjs (the
 // single implementations) — this file previously carried private copies.
 import { walkFiles, countGlobFiles } from '../shared-ignore.mjs';
@@ -33,18 +35,19 @@ export function validateMetricsConsistency(projectDir, config, guardResults) {
   // ── Collect actual metrics ──
   const actuals = {};
 
-  // Guard check count (from guard results if available)
+  // Guard check count is configuration-dependent, so it comes from this run.
+  // Validator count is a package capability: it must not shrink when a project
+  // disables a validator. Resolve this module's installed directory rather
+  // than projectDir, which points at the consumer repository.
   if (guardResults && Array.isArray(guardResults)) {
     const totalChecks = guardResults.reduce((sum, r) => {
       if (r.status === 'skipped') return sum;
       return sum + (r.total || 0);
     }, 0);
-    // +1 because Metrics-Consistency itself hasn't been added to results yet
-    const validatorCount = guardResults.filter(r => r.status !== 'skipped').length + 1;
-
     actuals.checks = totalChecks;
-    actuals.validators = validatorCount;
   }
+  const shippedValidatorCount = countShippedValidators();
+  if (shippedValidatorCount !== null) actuals.validators = shippedValidatorCount;
 
   // Test count — count test files on disk
   const testFiles = findTestFiles(projectDir);
@@ -68,7 +71,7 @@ export function validateMetricsConsistency(projectDir, config, guardResults) {
   // subject before overwriting.
   const patterns = [
     { key: 'checks', regex: /(?<!\d\/)\b(\d{2,})\s+(?:automated\s+)?checks?\b/gi, label: 'checks', requireBind: true, subject: "DocGuard's own", actualSource: 'docguard.guard.checks' },
-    { key: 'validators', regex: /(?<!\d\/)\b(\d{2,})\s+validators?\b/gi, label: 'validators', requireBind: true, subject: "DocGuard's own", actualSource: 'docguard.guard.validators' },
+    { key: 'validators', regex: /(?<!\d\/)\b(\d{2,})\s+validators?\b/gi, label: 'validators', requireBind: true, subject: "DocGuard's shipped", actualSource: 'docguard.package.validators' },
   ];
 
   // v0.29 (field report #6): project-declared collections. `config.collections`
@@ -245,6 +248,15 @@ function isHistoricalMetricContext(content, index) {
   return /<!--\s*docguard:status\s+(?:historical|superseded|deprecated|archived)\s*-->/i.test(prefix);
 }
 
+/**
+ * Count validator modules shipped beside this file. This is deliberately
+ * package-local: a consumer's disabled validators or repository layout cannot
+ * alter a statement about DocGuard's own capability surface.
+ */
+function countShippedValidators() {
+  return countValidatorModules(dirname(fileURLToPath(import.meta.url)));
+}
+
 function findTestFiles(dir) {
   const tests = [];
   const testDirs = ['tests', 'test', '__tests__', 'spec', 'e2e'];
@@ -296,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)) {
@@ -311,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/validators/todo-tracking.mjs

@@ -1,8 +1,9 @@
 /**
  * TODO/FIXME Tracking Validator — Ensures code annotations are documented
  *
- * Scans source files for TODO:, FIXME:, HACK:, XXX: annotations and checks
- * if they are tracked in documentation (ROADMAP.md, CURRENT-STATE.md, etc.).
+ * Scans source files for debt tags (todo / fixme / hack / xxx, with a
+ * trailing colon or paren) and checks if they are tracked in documentation
+ * (ROADMAP.md, CURRENT-STATE.md, etc.).
  *
  * Also detects skipped tests without explanation.
  *

package/cli/validators/traceability.mjs

@@ -33,7 +33,11 @@ import {
   requirementPatterns,
 } from '../shared-requirements.mjs';
 import { readRetirementManifest } from '../scanners/retirement-manifest.mjs';
-import { parseSpecId, trustedSpecLifecycleIndex } from '../scanners/spec-registry.mjs';
+import {
+  parseSpecId,
+  trustedSpecLifecycleIndex,
+  uncommittedPlannedSpecLifecycleIndex,
+} from '../scanners/spec-registry.mjs';
 
 /**
  * Optional graphify interop (github.com/Graphify-Labs/graphify, MIT).
@@ -278,6 +282,7 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
   const reqIds = collectRequirementIds(projectDir, config, patterns);
   const retiredReqIds = loadRetiredRequirementIds(projectDir);
   const lifecycleIndex = trustedSpecLifecycleIndex(projectDir);
+  const uncommittedPlannedIndex = uncommittedPlannedSpecLifecycleIndex(projectDir);
 
   // ── Step 2: Scan test files for requirement ID references ──
   const testRefs = scanTestFilesForReferences(projectDir, projectFiles, patterns);
@@ -305,11 +310,13 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
   // digest-current reviewed lifecycle can defer their test linkage.
   for (const [key, location] of reqIds) {
     const reqId = location.id;
-    const lifecycle = location.specId ? lifecycleIndex.get(`${location.specId}\0${location.file}`) : null;
+    const lifecycleKey = location.specId ? `${location.specId}\0${location.file}` : null;
+    const lifecycle = lifecycleKey ? lifecycleIndex.get(lifecycleKey) : null;
     if (lifecycle?.delivery === 'planned') {
       deferred++;
       continue;
     }
+    const uncommittedPlanned = lifecycleKey && uncommittedPlannedIndex.has(lifecycleKey);
     if (location.specId && !lifecycle) lifecycleUnknown++;
     total++;
     if (resolvedRefs.has(key)) {
@@ -317,10 +324,12 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
     } else {
       // Try to recover a likely-but-unannotated test via TF-IDF cosine.
       let softHint = '';
-      let softText = `Review existing tests for this requirement. If a test verifies it, add an @req ${key} annotation or requirement ID test label; write a test only if behavioral coverage is actually missing.`;
+      let softText = uncommittedPlanned
+        ? 'The on-disk lifecycle registry says this requirement is planned, but .docguard-specs.json is not a clean tracked Git artifact. Restore it to its committed state, or commit the registry and its current spec artifacts, before treating the requirement as deferred; do not add an @req marker merely to silence this warning.'
+        : `Review existing tests for this requirement. If a test verifies it, add an @req ${key} annotation or requirement ID test label; write a test only if behavioral coverage is actually missing.`;
       const queryText = location.text && location.text.length > reqId.length ? location.text : reqId;
-      if (testCorpus === null) testCorpus = buildTestCorpus(projectDir, projectFiles);
-      if (testCorpus.length > 0) {
+      if (!uncommittedPlanned && testCorpus === null) testCorpus = buildTestCorpus(projectDir, projectFiles);
+      if (!uncommittedPlanned && testCorpus.length > 0) {
         const ranked = rankBySimilarity(tokenize(queryText), testCorpus);
         const top = ranked[0];
         if (top && top.score >= softThreshold) {

package/docs/quickstart.md

@@ -68,7 +68,7 @@ diagnose  →  AI reads prompts  →  AI fixes docs  →  guard verifies
 ## Verify
 
 ```bash
-npx docguard-cli guard        # Pass/fail check (30 validators)
+npx docguard-cli guard        # Pass/fail check (29 validators)
 npx docguard-cli score        # 0-100 maturity score
 ```
 

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