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

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

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

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

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

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

{docguard_cli-0.41.3 → docguard_cli-0.41.5}/.docguard-specs.json

@@ -153,7 +153,7 @@
         "artifacts": [
           {
             "path": "specs/012-adoption-workflow-integrity/spec.md",
-            "digest": "sha256:6f007a67be27b07599e058bd2dadc97031bc0753649ae296f95c4ea3b87ea821"
+            "digest": "sha256:b019d4b6af2f991d6bba8cef3a1c1f9a1bcf5c3cbfd4f65d900942d0a2f097d5"
           }
         ],
         "taskCompletion": {

{docguard_cli-0.41.3 → docguard_cli-0.41.5}/.gitignore

@@ -45,3 +45,4 @@ websec-out/
 
 # OpenWolf private session memory (machine-local, not shared)
 .claude/openwolf-memory/
+.wolf/

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docguard-cli
-Version: 0.41.3
+Version: 0.41.5
 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.5}/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.5}/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.5}/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.

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

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

{docguard_cli-0.41.3 → docguard_cli-0.41.5}/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.5}/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.5}/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.5}/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,

{docguard_cli-0.41.3 → docguard_cli-0.41.5}/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.5/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.5}/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 = [