docguard-cli 0.41.2 → 0.41.4

package/CHANGELOG.md

@@ -7,6 +7,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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`.
+
+### Changed
+
+- fix: preserve hook composition and evidence gates (#404)
+
+
+### Fixed
+
+- Increased the bounded subprocess deadlines in the hook and Spec Kit helper contract suites so parallel CI load does not misreport healthy integrations as `ETIMEDOUT` failures.
+- Make managed Git hook reinstall idempotent, repair nested marker pairs written
+  by affected releases, and allow successful DocGuard blocks to continue into
+  user-owned postlude commands.
+- Make direct `verify --evidence` suitable for CI by exiting 1 for contradictions
+  and invalid manifests, 2 for unresolved evidence, and 0 for verified or
+  unconfigured evidence.
+- Explain deterministic spec-registry drift with bounded field paths and identify
+  order-only canonicalization instead of returning an unexplained `STALE` state.
+- Replace the README's release-line label with version-independent wording so it
+  cannot become stale on the next automated release.
+
 ## [0.41.2] - 2026-09-15
 
 Automated weekly release — batches everything merged since `v0.41.1`.

package/README.md

@@ -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 |
@@ -714,7 +720,7 @@ Two ready-to-use templates ship with the Spec Kit extension and as standalone fi
 
 ## ✨ What's New
 
-Highlights through the current v0.40 release line:
+Highlights from recent releases:
 
 - **Adoption baseline** — `guard --update-baseline` freezes a legacy repo's existing findings
   into a committed `.docguard.baseline.json`; guard/ci then gate only NEW drift, with suppression

package/cli/commands/hooks.mjs

@@ -24,6 +24,19 @@ import { existsSync, mkdirSync, chmodSync, readFileSync, unlinkSync } from 'node
 // pre-existing hooks), behavior falls back to the existing --force flow.
 const BEGIN_MARKER = '# BEGIN DOCGUARD MANAGED — do not edit between these markers';
 const END_MARKER   = '# END DOCGUARD MANAGED';
+const escapeRegExp = value => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+function managedBounds(content) {
+  const starts = [...content.matchAll(new RegExp(`^${escapeRegExp(BEGIN_MARKER)}\\r?$`, 'gm'))]
+    .map(match => match.index);
+  const ends = [...content.matchAll(new RegExp(`^${escapeRegExp(END_MARKER)}\\r?$`, 'gm'))]
+    .map(match => match.index);
+  const start = starts[0];
+  const end = ends.at(-1);
+  return Number.isInteger(start) && Number.isInteger(end) && end > start
+    ? { start, end }
+    : null;
+}
 
 /**
  * Wrap a hook body in BEGIN/END markers so future re-installs can splice
@@ -44,15 +57,18 @@ function wrapManaged(body) {
  * the BEGIN/END markers. Returns the new file content (string) or null
  * when the markers aren't found (caller falls back to legacy behavior).
  */
-function spliceManagedBlock(existing, newBody) {
-  const startIdx = existing.indexOf(BEGIN_MARKER);
-  const endIdx   = existing.indexOf(END_MARKER);
-  if (startIdx === -1 || endIdx === -1 || endIdx < startIdx) return null;
+function spliceManagedBlock(existing, rawBody) {
+  const bounds = managedBounds(existing);
+  if (!bounds) return null;
+  const startIdx = bounds.start;
+  // Use the outermost end marker so one reinstall also repairs hooks written
+  // by v0.40.5-v0.41.2, which accidentally nested a second managed block.
+  const endIdx = bounds.end;
   const before = existing.slice(0, startIdx);
   const after  = existing.slice(endIdx + END_MARKER.length);
-  // newBody has its own shebang — strip it since we're splicing into the
+  // rawBody has its own shebang — strip it since we're splicing into the
   // middle of an existing file (which already has one).
-  const bodyNoShebang = newBody.replace(/^#!.*\n/, '');
+  const bodyNoShebang = rawBody.replace(/^#!.*\n/, '');
   return `${before}${BEGIN_MARKER}\n${bodyNoShebang.replace(/\n+$/, '')}\n${END_MARKER}${after}`;
 }
 
@@ -62,18 +78,21 @@ function hookState(name, hooksDir) {
   let content;
   try { content = readFileSync(path, 'utf-8'); }
   catch { return { kind: 'unreadable', path, content: '' }; }
-  if (content.includes(BEGIN_MARKER) && content.includes(END_MARKER)) {
+  if (managedBounds(content)) {
     return { kind: 'managed', path, content };
   }
-  const legacySignature = new RegExp(`^# DocGuard ${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')} hook(?: \\(auto-fix mode\\))?$`, 'm');
+  const legacySignature = new RegExp(`^# DocGuard ${escapeRegExp(name)} hook(?: \\(auto-fix mode\\))?$`, 'm');
   if (legacySignature.test(content)) return { kind: 'legacy', path, content };
   return { kind: 'foreign', path, content };
 }
 
 function removeManagedBlock(content) {
-  const start = content.indexOf(BEGIN_MARKER);
-  const end = content.indexOf(END_MARKER);
-  if (start === -1 || end === -1 || end < start) return null;
+  const bounds = managedBounds(content);
+  if (!bounds) return null;
+  const start = bounds.start;
+  // Match spliceManagedBlock's outermost recovery boundary so removal also
+  // cleans up already-nested blocks from affected releases.
+  const end = bounds.end;
   const remaining = `${content.slice(0, start)}${content.slice(end + END_MARKER.length)}`
     .replace(/\n{3,}/g, '\n\n');
   return remaining;
@@ -128,7 +147,7 @@ elif [ $EXIT_CODE -eq 2 ]; then
   echo "⚠️  DocGuard guard found warnings — commit allowed"
 fi
 
-exit 0
+:
 `,
   },
 
@@ -179,7 +198,7 @@ if [ "$SCORE" -lt "$MIN_SCORE" ]; then
 fi
 
 echo "   ✅ Score meets minimum threshold"
-exit 0
+:
 `,
   },
 
@@ -215,7 +234,7 @@ if ! echo "$COMMIT_MSG" | head -1 | grep -qE "$PATTERN"; then
   exit 1
 fi
 
-exit 0
+:
 `,
   },
 };
@@ -256,7 +275,7 @@ if [ "$EXIT_CODE" -ne 0 ] && [ "$EXIT_CODE" -ne 2 ]; then
 elif [ $EXIT_CODE -eq 2 ]; then
   echo "⚠️  DocGuard guard found warnings — commit allowed"
 fi
-exit 0
+:
 `;
 
 export function runHooks(projectDir, config, flags) {
@@ -356,7 +375,8 @@ export function runHooks(projectDir, config, flags) {
   for (const name of hookTypes) {
     const hookPath = resolve(hooksDir, name);
     const useAutofix = name === 'pre-commit' && flags.autoFix;
-    const newContent = wrapManaged(useAutofix ? PRE_COMMIT_AUTOFIX : HOOKS[name].content);
+    const rawContent = useAutofix ? PRE_COMMIT_AUTOFIX : HOOKS[name].content;
+    const newContent = wrapManaged(rawContent);
     const desc = useAutofix ? 'Apply mechanical fixes (fix --write) then guard' : HOOKS[name].description;
 
     if (existsSync(hookPath)) {
@@ -366,7 +386,7 @@ export function runHooks(projectDir, config, flags) {
       // preserve everything outside it. The user can extend the hook with
       // their own commands above/below the markers without losing them on
       // re-install.
-      const spliced = spliceManagedBlock(existing, newContent);
+      const spliced = spliceManagedBlock(existing, rawContent);
       if (spliced !== null) {
         safeWrite(hookPath, spliced);
         chmodSync(hookPath, 0o755);

package/cli/commands/specs.mjs

@@ -226,6 +226,12 @@ function printResult(result) {
   console.log(`Spec registry: ${result.status}`);
   console.log(`Registry: ${SPEC_REGISTRY_PATH}`);
   console.log(`Specs: ${result.specs}; tombstones: ${result.tombstones}`);
+  if (result.differences?.length) {
+    console.log('Differences:');
+    for (const difference of result.differences) {
+      console.log(`  ${difference.path}: ${difference.message}`);
+    }
+  }
   if (result.issues.length) printIssues(result.issues);
 }
 
@@ -268,6 +274,7 @@ export function runSpecs(projectDir, config, flags = {}) {
       specs: projection.registry.specs.length,
       tombstones: projection.registry.tombstones.length,
       issues: projection.issues,
+      differences: projection.differences,
     };
     if (flags.format === 'json') console.log(JSON.stringify(result, null, 2));
     else printResult(result);

package/cli/commands/verify.mjs

@@ -169,6 +169,14 @@ export function runVerify(projectDir, config, flags) {
 
 function runEvidenceVerification(projectDir, config, flags) {
   const evaluation = evaluateEvidence(projectDir, config);
+  // Match guard's severity contract so this command is safe as a direct CI
+  // gate: contradictions and invalid manifests fail, while unresolved evidence
+  // uses the warning-only status shared by the rest of the CLI.
+  process.exitCode = evaluation.status === 'contradicted' || evaluation.status === 'invalid'
+    ? 1
+    : evaluation.status === 'attention-required'
+      ? 2
+      : 0;
   if (flags.format === 'json') {
     console.log(JSON.stringify(evaluation, null, 2));
     return;

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

@@ -35,6 +35,51 @@ const posix = path => path.split(sep).join('/').replace(/^\.\//, '');
 const digest = content => `sha256:${createHash('sha256').update(content).digest('hex')}`;
 const sortedUnique = values => [...new Set(values)].sort((a, b) => a.localeCompare(b));
 
+function registryDifferences(left, right) {
+  const differences = [];
+  let omitted = false;
+  const add = difference => {
+    if (differences.length < 25) differences.push(difference);
+    else omitted = true;
+  };
+  const memberKeys = values => values.map(value => JSON.stringify(value)).sort();
+  const visit = (actual, projected, path) => {
+    if (omitted) return;
+    if (Object.is(actual, projected)) return;
+    if (Array.isArray(actual) && Array.isArray(projected)) {
+      if (JSON.stringify(actual) === JSON.stringify(projected)) return;
+      const actualMembers = memberKeys(actual);
+      const projectedMembers = memberKeys(projected);
+      if (actualMembers.length === projectedMembers.length
+        && actualMembers.every((value, index) => value === projectedMembers[index])) {
+        add({ path, kind: 'order', message: 'Unordered values are not in canonical sort order.' });
+        return;
+      }
+      const length = Math.max(actual.length, projected.length);
+      for (let index = 0; index < length; index++) visit(actual[index], projected[index], `${path}[${index}]`);
+      return;
+    }
+    const actualObject = actual !== null && typeof actual === 'object' && !Array.isArray(actual);
+    const projectedObject = projected !== null && typeof projected === 'object' && !Array.isArray(projected);
+    if (actualObject && projectedObject) {
+      for (const key of [...new Set([...Object.keys(actual), ...Object.keys(projected)])].sort()) {
+        visit(actual[key], projected[key], `${path}.${key}`);
+      }
+      return;
+    }
+    const kind = actual === undefined ? 'missing'
+      : projected === undefined ? 'unexpected'
+        : 'value';
+    const message = kind === 'missing' ? 'Field is missing from the registry.'
+      : kind === 'unexpected' ? 'Field is not part of the deterministic projection.'
+        : 'Field value differs from the deterministic projection.';
+    add({ path, kind, message });
+  };
+  visit(left, right, '$');
+  if (omitted) differences.push({ path: '$', kind: 'truncated', message: 'Additional differences were omitted.' });
+  return differences;
+}
+
 function isSafeFile(projectDir, path) {
   try {
     const root = realpathSync(projectDir);
@@ -243,6 +288,32 @@ export function trustedSpecLifecycleIndex(projectDir) {
   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 || artifact.digest !== 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');
@@ -472,10 +543,14 @@ export function projectSpecRegistry(projectDir, config = {}, options = {}) {
   const current = existing.exists && !existing.error
     ? `${JSON.stringify(existing.value, null, 2)}\n` === serialized
     : false;
+  const differences = existing.exists && !existing.error
+    ? registryDifferences(existing.value, projected)
+    : [];
   return {
     registry: projected,
     serialized,
     current,
+    differences,
     exists: existing.exists,
     issues,
     detected: detected.specs.length,

package/cli/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/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/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'];

package/cli/validators/spec-registry.mjs

@@ -25,13 +25,16 @@ export function validateSpecRegistry(projectDir, config = {}) {
         },
   }));
   if (!projection.current && projection.issues.length === 0) {
+    const detail = projection.differences.slice(0, 3)
+      .map(difference => `${difference.path}: ${difference.message}`)
+      .join(' ');
     findings.push(mkFinding({
       code: 'SPR001',
       validator: 'specRegistry',
       severity: 'warn',
       confidence: 'high',
       message: projection.exists
-        ? `${SPEC_REGISTRY_PATH} does not match the current deterministic spec evidence projection.`
+        ? `${SPEC_REGISTRY_PATH} does not match the current deterministic spec evidence projection.${detail ? ` ${detail}` : ''}`
         : `${SPEC_REGISTRY_PATH} is missing while active specifications exist.`,
       location: SPEC_REGISTRY_PATH,
       suggestion: {

package/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.2"
+  version: "0.41.4"
   description: "Documentation integrity for AI-assisted repositories: lifecycle registry, drift validation, traceability, safe archival, SARIF/JUnit, MCP, GitHub Actions, and Spec Kit hooks."
   author: "Ricardo Accioly"
   repository: "https://github.com/raccioly/docguard"

package/extensions/spec-kit-docguard/skills/docguard-fix/SKILL.md

@@ -6,10 +6,10 @@ description: AI-driven documentation repair with structured research workflow, t
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.41.2
+  version: 0.41.4
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.41.2 -->
+<!-- docguard:version: 0.41.4 -->
 
 # DocGuard Fix Skill
 

package/extensions/spec-kit-docguard/skills/docguard-guard/SKILL.md

@@ -7,10 +7,10 @@ description: Run DocGuard guard validation against Canonical-Driven Development
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.41.2
+  version: 0.41.4
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.41.2 -->
+<!-- docguard:version: 0.41.4 -->
 
 # DocGuard Guard Skill
 

package/extensions/spec-kit-docguard/skills/docguard-review/SKILL.md

@@ -6,10 +6,10 @@ description: Cross-document consistency analysis and quality assessment. Perform
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.41.2
+  version: 0.41.4
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.41.2 -->
+<!-- docguard:version: 0.41.4 -->
 
 # DocGuard Review Skill
 

package/extensions/spec-kit-docguard/skills/docguard-score/SKILL.md

@@ -6,10 +6,10 @@ description: CDD maturity assessment with category-aware improvement roadmap. Ru
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.41.2
+  version: 0.41.4
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.41.2 -->
+<!-- docguard:version: 0.41.4 -->
 
 # DocGuard Score Skill
 

package/extensions/spec-kit-docguard/skills/docguard-sync/SKILL.md

@@ -4,10 +4,10 @@ description: Keep canonical documentation ALWAYS UP TO DATE. Refreshes code-trut
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.41.2
+  version: 0.41.4
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.41.2 -->
+<!-- docguard:version: 0.41.4 -->
 
 # DocGuard Sync Skill
 

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

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

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

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

package/package.json

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

package/templates/ci/github-actions.yml

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