docguard-cli 0.41.3__tar.gz → 0.41.4__tar.gz

{docguard_cli-0.41.3 → docguard_cli-0.41.4}/.agent/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.4
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.41.3 -->
+<!-- docguard:version: 0.41.4 -->
 
 # DocGuard Fix Skill
 

{docguard_cli-0.41.3/extensions/spec-kit-docguard → docguard_cli-0.41.4/.agent}/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.4
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.41.3 -->
+<!-- docguard:version: 0.41.4 -->
 
 # DocGuard Guard Skill
 

{docguard_cli-0.41.3/extensions/spec-kit-docguard → docguard_cli-0.41.4/.agent}/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.4
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.41.3 -->
+<!-- docguard:version: 0.41.4 -->
 
 # DocGuard Review Skill
 

{docguard_cli-0.41.3/extensions/spec-kit-docguard → docguard_cli-0.41.4/.agent}/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.4
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.41.3 -->
+<!-- docguard:version: 0.41.4 -->
 
 # DocGuard Score Skill
 

{docguard_cli-0.41.3/extensions/spec-kit-docguard → docguard_cli-0.41.4/.agent}/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.4
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.41.3 -->
+<!-- docguard:version: 0.41.4 -->
 
 # DocGuard Sync Skill
 

{docguard_cli-0.41.3 → docguard_cli-0.41.4}/.wolf/buglog.json

@@ -6313,6 +6313,64 @@
       "related_bugs": [],
       "occurrences": 2,
       "last_seen": "2026-09-15T17:02:00.000Z"
+    },
+    {
+      "id": "bug-380",
+      "timestamp": "2026-09-15T20:22:00.000Z",
+      "error_message": "Validator-count findings changed when a consumer disabled validators, and Canonical-Sync disagreed with Metrics-Consistency by counting an inlined guard sub-check as another validator",
+      "file": "cli/validators/metrics-consistency.mjs; cli/validators/canonical-sync.mjs",
+      "root_cause": "Package capability was derived from enabled guard orchestration rather than the installed validator-module surface, with two validators maintaining incompatible counting rules",
+      "fix": "Count shipped cli/validators modules through cli/shared-validator-surface.mjs, retain run-specific guard results only for check counts, and align CSY003 wording and all self-documentation",
+      "tags": [
+        "metrics",
+        "canonical-sync",
+        "false-positive",
+        "package-surface",
+        "field-report"
+      ],
+      "related_bugs": [
+        "bug-378"
+      ],
+      "occurrences": 1,
+      "last_seen": "2026-09-15T20:22:00.000Z"
+    },
+    {
+      "id": "bug-381",
+      "timestamp": "2026-09-15T20:22:00.000Z",
+      "error_message": "Instruction pointer basename resolution treated ignored disposable worktree copies as primary repository files and reported false ambiguity",
+      "file": "cli/shared-ignore.mjs; cli/scanners/instruction-audit.mjs",
+      "root_cause": "The custom basename walk used only DocGuard ignore rules and continued through nested Git roots, bypassing Git's authoritative ignore semantics",
+      "fix": "Use one bounded Git ignored-path filter for pointer indexing and prune nested .git file or directory boundaries before their descendants are read",
+      "tags": [
+        "instruction-audit",
+        "gitignore",
+        "worktree",
+        "false-positive",
+        "field-report"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-15T20:22:00.000Z"
+    },
+    {
+      "id": "bug-382",
+      "timestamp": "2026-09-15T20:22:00.000Z",
+      "error_message": "TRC004 correctly rejected a planned lifecycle registry that was new, removed from the Git index, or awaiting commit but suggested adding a test marker, obscuring the actual Git-state prerequisite",
+      "file": "cli/scanners/spec-registry.mjs; cli/validators/traceability.mjs",
+      "root_cause": "Trusted lifecycle loading discarded all non-clean Git state, leaving traceability with no safe way to distinguish a structurally current planned registry from ordinary missing lifecycle evidence",
+      "fix": "Expose structurally current planned entries from every non-clean Git state only as advisory context; preserve enforcement, explain restore-or-commit remediation, and prohibit marker-only remediation",
+      "tags": [
+        "traceability",
+        "spec-registry",
+        "lifecycle",
+        "remediation",
+        "field-report"
+      ],
+      "related_bugs": [
+        "bug-377"
+      ],
+      "occurrences": 1,
+      "last_seen": "2026-09-15T20:22:00.000Z"
     }
   ]
 }

{docguard_cli-0.41.3 → docguard_cli-0.41.4}/.wolf/cerebrum.md

@@ -161,3 +161,5 @@
 
 - **2026-09-15 — Living-spec completion and durable evidence:** A living verification contract may omit `tasks.md` only when every requirement has qualified source/test evidence; declared empty or incomplete ledgers and all other persistence models still fail closed. Maintenance of released living specs must preserve `released → released`. Because squash changes the candidate commit, durable implementation outcomes are recorded in a post-merge transaction against reachable main history; generated outcome churn cannot qualify itself.
 - **2026-09-15 — Packed version assertions:** A release smoke test that accepts any semantic version is a false-green. Execute the extracted tarball and compare `--version` exactly to that tarball's `package.json`; run registry installation probes from a fresh directory because `npx` inside the package checkout can select a stale local binary.
+
+- **2026-09-15 — Adoption precision follow-up:** A package capability claim must derive from the shipped package surface, never from one consumer's enabled guard results or from a secondary check emitted by a validator module. Keep every validator that governs the same claim on one shared count primitive. Instruction basename indexes must honor Git's ignore semantics and stop at nested Git boundaries before reading duplicate worktrees. Lifecycle evidence remains fail-closed: a structurally current planned registry that is new, removed from the Git index, or modified pending commit may improve the explanation, never defer traceability or prompt an artificial test marker. Pair each field replay with a real-project read-only run and before/after Git-status snapshots; no-release hardening batches stay unpublished until the user calls for a material release.

{docguard_cli-0.41.3 → docguard_cli-0.41.4}/.wolf/memory.md

@@ -1335,3 +1335,4 @@
 | 14:56 | Edited README.md | expanded (+19 lines) | ~245 |
 | 12:18 | Fixed living-spec completion and released maintenance; merged PRs #398–#400; published and independently verified v0.41.1; removed 348 temp artifacts | specs lifecycle, registry, roadmap, release | 1,866 tests + Node 18/20/22/24 + OSV + all publication targets passed | ~43000 tok |
 | 12:39 | Reproduced and fixed field-report hook composition, evidence exit, registry explanation, and README drift defects; classified four other v0.40.5 items as already fixed | hooks, verify, spec registry, canonical docs, tests | focused behavioral regressions added; v0.41.2 publication completed before release-cadence correction | ~18000 tok |
+| 20:22 | Hardened three v0.41.3 adoption reports and reconciled validator-count sources; replayed read-only consumer scans | metrics, canonical sync, instruction audit, lifecycle traceability, docs, tests | 1,879 tests, self-guard 618/618, package dry-run, seven repos unchanged; no release requested | ~26000 tok |

{docguard_cli-0.41.3 → docguard_cli-0.41.4}/CHANGELOG.md

@@ -7,6 +7,39 @@ 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`.

{docguard_cli-0.41.3 → docguard_cli-0.41.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docguard-cli
-Version: 0.41.3
+Version: 0.41.4
 Summary: The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation. No Python dependencies (requires Node.js 18+).
 Project-URL: Homepage, https://github.com/raccioly/docguard
 Project-URL: Documentation, https://github.com/raccioly/docguard#readme
@@ -101,7 +101,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
@@ -299,7 +299,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) |
@@ -435,7 +435,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 |
 |:--|:----------|:--------------|:--------|
@@ -568,7 +574,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 |

{docguard_cli-0.41.3 → docguard_cli-0.41.4}/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 |

{docguard_cli-0.41.3 → docguard_cli-0.41.4}/VALIDATION.md

@@ -85,7 +85,7 @@ tuning; the levers that mattered:
 ## Standing verification
 
 - Built-in `node:test`, with Node 18/20/22/24 in the supported CI matrix. Per-change validation records contain measured test totals.
-- **Self-guarded:** every push runs all 30 validators against DocGuard's own
+- **Self-guarded:** every push runs all 29 validators against DocGuard's own
   docs; count claims in this README family are machine-governed
   (Canonical-Sync), so the validator count is checked, not remembered.
 - **Deterministic core:** no LLM calls at validation time, one pinned

{docguard_cli-0.41.3 → docguard_cli-0.41.4}/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'],

{docguard_cli-0.41.3 → docguard_cli-0.41.4}/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: {

{docguard_cli-0.41.3 → docguard_cli-0.41.4}/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);
     }
   };

{docguard_cli-0.41.3 → docguard_cli-0.41.4}/cli/scanners/spec-registry.mjs

@@ -288,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');

{docguard_cli-0.41.3 → docguard_cli-0.41.4}/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.
  *

docguard_cli-0.41.4/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;
+  }
+}

{docguard_cli-0.41.3 → docguard_cli-0.41.4}/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 {

{docguard_cli-0.41.3 → docguard_cli-0.41.4}/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'];

{docguard_cli-0.41.3 → docguard_cli-0.41.4}/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.
  *