docguard-cli 0.36.0__tar.gz → 0.36.2__tar.gz

{docguard_cli-0.36.0 → docguard_cli-0.36.2}/.wolf/buglog.json

@@ -5110,6 +5110,152 @@
       "related_bugs": [],
       "occurrences": 1,
       "last_seen": "2026-09-11T20:42:23.164Z"
+    },
+    {
+      "id": "bug-311",
+      "timestamp": "2026-09-11T21:26:46.402Z",
+      "error_message": "Published Spec Kit installation displayed an obsolete validator count",
+      "file": "extensions/spec-kit-docguard/extension.yml",
+      "root_cause": "Descriptive metadata and skill prose hardcoded a count outside synchronized documentation checks",
+      "fix": "Remove the hardcoded count from all three extension surfaces and verify the published ZIP after installation",
+      "tags": [
+        "release",
+        "metadata",
+        "documentation"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T21:26:46.402Z"
+    },
+    {
+      "id": "bug-312",
+      "timestamp": "2026-09-11T21:33:22.758Z",
+      "error_message": "Spec Kit verbose helper emitted malformed JSON for current CLI output",
+      "file": "extensions/spec-kit-docguard/scripts/bash/docguard-check-docs.sh",
+      "root_cause": "Legacy regex parsing expected compact score fields and prose guard output; CLI lookup missed installed docguard and did not quote paths",
+      "fix": "Parse and validate structured JSON and exit status; prefer local installs, safely quote executable paths, and refuse implicit npx downloads",
+      "tags": [
+        "release",
+        "json",
+        "hooks"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T21:33:22.758Z"
+    },
+    {
+      "id": "bug-313",
+      "timestamp": "2026-09-13T00:29:54.315Z",
+      "error_message": "Documented config remains DCV004 with docs.dirs configured",
+      "file": "cli/validators/docs-coverage.mjs",
+      "root_cause": "Fixed document collector discarded configuration; path construction was also treated as proof of a file",
+      "fix": "Honor configured scoped document evidence; distinguish direct IO from unverified paths with paired controls",
+      "tags": [
+        "precision",
+        "oss-assessment",
+        "regression"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-13T00:29:54.368Z"
+    },
+    {
+      "id": "bug-314",
+      "timestamp": "2026-09-13T00:29:54.368Z",
+      "error_message": "Excluded models are counted and overlapping roots duplicate one model",
+      "file": "cli/validators/schema-sync.mjs",
+      "root_cause": "Schema traversal did not apply file excludes or deduplicate resolved files",
+      "fix": "Filter through shared ignores and deduplicate by source file, preserving equal model names in separate files",
+      "tags": [
+        "precision",
+        "oss-assessment",
+        "regression"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-13T00:29:54.368Z"
+    },
+    {
+      "id": "bug-315",
+      "timestamp": "2026-09-13T00:29:54.368Z",
+      "error_message": "Fixture JSON containing FR-001 creates feature coverage",
+      "file": "cli/commands/trace.mjs",
+      "root_cause": "Feature scoring scanned arbitrary text unlike the validator",
+      "fix": "Reuse positive annotation and label extraction from the validator",
+      "tags": [
+        "precision",
+        "oss-assessment",
+        "regression"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-13T00:29:54.368Z"
+    },
+    {
+      "id": "bug-316",
+      "timestamp": "2026-09-13T00:29:54.368Z",
+      "error_message": "Freshness review emits incomplete docguard fix --doc",
+      "file": "cli/commands/diagnose.mjs",
+      "root_cause": "Generic repair routing converted review heuristics to document rewrites",
+      "fix": "Leave freshness repair commands unset and preserve review-first guidance; executable CLI regression uses at least three Git commits",
+      "tags": [
+        "precision",
+        "oss-assessment",
+        "regression"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-13T00:29:54.368Z"
+    },
+    {
+      "id": "bug-317",
+      "timestamp": "2026-09-14T14:22:14.613Z",
+      "error_message": "agents --check scaffolds files and invokes Spec Kit",
+      "file": "cli/docguard.mjs",
+      "root_cause": "The check flag bypassed neither automatic setup nor the deprecated agents alias dispatch through init",
+      "fix": "Skip automatic setup and dispatch checks directly to runAgents; snapshot repositories and trap setup tooling with an explicit-setup control",
+      "tags": [
+        "read-only",
+        "cli",
+        "regression"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-14T14:22:14.613Z"
+    },
+    {
+      "id": "bug-318",
+      "timestamp": "2026-09-14T14:25:08.472Z",
+      "error_message": "Badge CLI tests refresh generated skills in the source checkout",
+      "file": "tests/commands.test.mjs",
+      "root_cause": "Tests used the default repository cwd for a deprecated alias that initializes skills",
+      "fix": "Run both badge cases in disposable projects using process.execPath, closed tooling PATH and test cleanup",
+      "tags": [
+        "tests",
+        "isolation"
+      ],
+      "related_bugs": [
+        "bug-317"
+      ],
+      "occurrences": 1,
+      "last_seen": "2026-09-14T14:25:08.472Z"
+    },
+    {
+      "id": "bug-319",
+      "timestamp": "2026-09-14T14:57:06.826Z",
+      "error_message": "Repeated requirement IDs across documents share coverage incorrectly",
+      "file": "cli/validators/traceability.mjs",
+      "root_cause": "Definitions and feature coverage were indexed by bare IDs across the entire project",
+      "fix": "Use document-qualified definition keys and shared resolution; only unique bare IDs or exact qualified references earn credit",
+      "tags": [
+        "traceability",
+        "false-assurance"
+      ],
+      "related_bugs": [
+        "bug-315"
+      ],
+      "occurrences": 1,
+      "last_seen": "2026-09-14T14:57:06.826Z"
     }
   ]
 }

{docguard_cli-0.36.0 → docguard_cli-0.36.2}/.wolf/cerebrum.md

@@ -120,3 +120,13 @@
 - **2026-09-11 (documentation trust)** — Structural score and surface alignment do not establish factual accuracy. Preserve null/unverified across score, CI, report, diagnose, and agent prompts; zero extracted claims does not prove prose correctness. Content-aware plan identity fixes stale uncommitted source results at a measurable hashing cost. Treat fixture strings separately from actual requirement annotations. Public feedback drafts carry registry metadata only; private source context stays local, and submission remains voluntary. `init --with ci` scaffolds a maintained workflow; installing a workflow does not enable branch protection. See docs-implementation/TRUST-ROADMAP.md for researched acceptance gates and deferred empirical work.
 
 - **2026-09-11 (enterprise precision)** — Compare baseline and current on identical disposable source snapshots. Keep originals untouched; concurrent consumer commits are not our changes. A lower warning total is not precision: new review scope can increase findings. OpenAPI absence is not implementation absence. Pair every exception with a true-defect control; source syntax and lexical ownership beat broad line matching. Custom doc roles need both direct-call and CLI write fences. Missing annotations leave behavioral coverage unknown; Python architecture coverage remains explicitly unsupported. Full-suite temp assertions must isolate process-owned fixtures and always clean up with ESM-safe imports. See docs-implementation/PRECISION-VALIDATION.md.
+
+- **2026-09-11 (release verification)** — Install the actual release ZIP in a disposable Spec Kit project before updating the catalog: CLI tests and self-guard did not catch obsolete counts in extension install descriptions. Catalog draft checkboxes are evidence to fill after testing, not automatic assertions. Reuse the existing open submission issue; refresh MCP Registry identity auth when its JWT expires. Preserve published versions and use a patch release for post-publication corrections.
+
+- **2026-09-13 — Independent OSS warning triage:** SvelteKit configured docs dirs exposed docsCoverage using a fixed collector; Django exposed schema ignores and overlapping-root duplicates; Astro showed directory construction and plain skip reasons misrepresented as factual defects. FastAPI is a neutral directory-fix holdout, not evidence of improved recall. Count setup requirements, review signals, unsupported formats and true defects separately. Feature scores must use positive annotation/label evidence rather than arbitrary fixture text; freshness diagnosis must not prescribe rewriting before intent review.
+
+- **2026-09-14 — Read-only alias dispatch:** agents --check requires both an automatic-setup exemption and direct dispatch around runInit. Quiet/headless alone is insufficient because init installs skills independently. Regression fixtures use a closed PATH with specify and which traps, reset after intentional setup, and assert full tree snapshots plus unchanged tooling logs. Preserve normal setup as a positive control.
+
+- **2026-09-14 — Badge test isolation:** legacy badge aliases run init and may refresh skills even when testing output. Keep their fixtures outside the source checkout; use the current Node executable and prevent global setup tooling from entering tests. Read-only audit/score tests remain separate from mutating alias tests.
+
+- **2026-09-14 — Scoped requirement identity:** validator and feature scoring share document-qualified definitions and positive reference resolution. Bare IDs resolve only when unique; an invalid qualifier never falls back. Repeated definitions in one document collapse; cross-document IDs remain separate. Qualified paths are repository-relative with forward slashes.

{docguard_cli-0.36.0 → docguard_cli-0.36.2}/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.36.2] - 2026-09-14
+
+### Fixed
+
+- Requirement identities include the defining document, preventing duplicate IDs across specs from sharing test coverage. Validator and feature scores share resolution; unique bare IDs remain compatible, and qualified references target exactly one document.
+
+- Legacy badge command tests run in disposable projects with host setup tooling excluded, preventing source-checkout mutations during the test suite.
+
+- `agents --check` preserves the repository and never bootstraps skills or invokes Spec Kit; stale managed files still exit 2, and explicit setup remains available.
+- Documentation coverage honors configured documentation directories and raw role mappings, while excluded/private/symlinked documents cannot supply evidence. Reproduced against a pinned SvelteKit checkout.
+- Configuration path construction and existence checks produce low-confidence review signals instead of asserting that directories are undocumented config files. Parsed comments and example strings do not establish file usage; findings identify the scanned documentation scope.
+- Schema synchronization honors file exclusions and counts each source file once across overlapping roots, preserving separate models with the same name. Verified against a pinned Django checkout.
+- Feature trace scoring uses the validator's explicit test annotations and labels; fixture JSON and incidental source strings no longer inflate requirement linkage. This does not yet solve duplicate requirement identities across specs.
+- Diagnosis preserves freshness as a review task instead of suggesting incomplete or automatic document rewrites, and its AI prompt no longer demands removal of every warning.
+
+## [0.36.1] - 2026-09-11
+
+### Fixed
+
+- Removed stale validator counts from the Spec Kit extension installation description, README, and repair skill. Found by installing the published v0.36.0 ZIP in a disposable Spec Kit project. The validation engine is unchanged.
+- The Spec Kit verbose helper reads structured score/guard JSON, preserves PASS/WARN/FAIL, and rejects malformed reports. CLI resolution prefers local installs, quotes paths safely, and requires an installed CLI instead of fetching through npx.
+
+
 ## [0.36.0] - 2026-09-11
 
 ### Fixed

{docguard_cli-0.36.0 → docguard_cli-0.36.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docguard-cli
-Version: 0.36.0
+Version: 0.36.2
 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

{docguard_cli-0.36.0 → docguard_cli-0.36.2}/cli/commands/diagnose.mjs

@@ -101,10 +101,8 @@ const FIX_INSTRUCTIONS = {
     autoFixable: false,
   },
   'Freshness': {
-    action: 'Review stale documents',
-    command: 'docguard fix --doc',
-    llmCommand: '/docguard.fix --doc',
-    description: 'Documents haven\'t been reviewed since recent code changes. Re-run fix --doc for each stale doc.',
+    action: 'Review document evidence against relevant changes',
+    description: 'Review signals do not establish incorrect documentation. Check whether the documentation or implementation needs a change; preserve approved intent.',
     autoFixable: false,
   },
   // ── Routed (Phase F): these used to fall through to a generic "Manual review needed" ──
@@ -257,23 +255,6 @@ export function runDiagnose(projectDir, config, flags) {
     }
   }
 
-  // Detect stale docs from freshness and map to specific fix --doc targets
-  for (const issue of issues) {
-    if (issue.validator === 'Freshness' && !issue.docTarget) {
-      const match = issue.message.match(/([\w-]+\.md)/i);
-      if (match) {
-        const docName = match[1].toLowerCase().replace('.md', '');
-        const docMap = { 'architecture': 'architecture', 'data-model': 'data-model', 'security': 'security', 'test-spec': 'test-spec', 'environment': 'environment' };
-        issue.docTarget = docMap[docName] || null;
-        if (issue.docTarget) {
-          issue.command = agentMode === 'llm'
-            ? `/docguard.fix --doc ${issue.docTarget}`
-            : `docguard fix --doc ${issue.docTarget}`;
-        }
-      }
-    }
-  }
-
   // ── Step 4: Output ──
   if (flags.format === 'json') {
     outputJSON(guardData, scoreData, issues);
@@ -497,7 +478,7 @@ function outputPrompt(projectDir, guardData, scoreData, issues, flags, agentMode
   } else {
     lines.push('After making all fixes, run: docguard guard');
   }
-  lines.push('Expected result: All checks pass (0 errors, 0 warnings)');
+  lines.push('Expected result: Resolve verified defects; explain remaining review signals and unsupported checks. Do not rewrite correct documents merely to remove warnings.');
   lines.push(`Structural baseline: ${scoreData.score}/100. Resolve evidenced defects; verify material claims separately.`);
   lines.push('Preserve approved requirements when implementation disagrees. A higher score is not proof of factual correctness.');
 

{docguard_cli-0.36.0 → docguard_cli-0.36.2}/cli/commands/trace.mjs

@@ -10,6 +10,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname, basename, relative, dirname } from 'node:path';
 import { c } from '../shared.mjs';
 import { detectSpecKit } from '../scanners/speckit.mjs';
+import { scanTestFilesForReferences, collectRequirementIds, resolveRequirementReferences } from '../validators/traceability.mjs';
 import { listCanonicalDocs } from '../shared-ignore.mjs';
 
 const IGNORE_DIRS = new Set([
@@ -378,7 +379,7 @@ function scanDir(rootDir, dir, files) {
 // repo-wide scores that `docguard score` produces. Deterministic signals only —
 // no LLM judgment:
 //
-//   reqCoverage          40%  FR-/SC- IDs in spec.md referenced by any test file
+//   reqCoverage          40%  FR-/SC- IDs in spec.md explicitly annotated or labeled in test sources
 //   taskCompletion       25%  checked/total `- [x]` tasks in tasks.md
 //   taskEvidence         20%  checked tasks whose line names an existing file
 //   artifactCompleteness 15%  spec.md (40%) + plan.md (30%) + tasks.md (30%)
@@ -425,34 +426,21 @@ function featureBar(score) {
 }
 
 /**
- * Collect every FR-/SC- ID referenced anywhere in a test file, once for the
- * whole project. Test-file discovery mirrors the traceability validator's
- * scanTestFilesForReferences(): TEST_PATTERNS ∪ __tests__/ ∪ tests?/ dirs, and
- * any occurrence of the ID in file content counts (not just @req lines).
+ * Collect declared FR-/SC- test links once for the whole project, using the
+ * validator's source eligibility and annotation/label parser. This is positive
+ * linkage evidence, independent of validator findings or suppression policy.
  */
 function collectTestReferencedIds(projectDir) {
   const projectFiles = [];
   scanDir(projectDir, projectDir, projectFiles);
-  const testFiles = projectFiles.filter(f =>
-    TEST_PATTERNS.some(p => p.test(f)) || /__tests__\//.test(f) || /tests?\//.test(f)
-  );
-
-  const ids = new Set();
-  for (const rel of testFiles) {
-    let content;
-    try { content = readFileSync(resolve(projectDir, rel), 'utf-8'); } catch { continue; }
-    FEATURE_REQ_RE.lastIndex = 0;
-    let m;
-    while ((m = FEATURE_REQ_RE.exec(content)) !== null) ids.add(m[0]);
-  }
-  return ids;
+  return scanTestFilesForReferences(projectDir, projectFiles, [FEATURE_REQ_RE]);
 }
 
 /**
  * Compute the four adherence signals for one detected spec-kit feature.
  * Each signal: { applicable, value (0..1 | null), ...n/m detail fields }.
  */
-function computeFeatureSignals(projectDir, feature, testRefIds) {
+function computeFeatureSignals(projectDir, feature, testRefIds, definitions) {
   // ── artifactCompleteness — always measurable ──
   const artifactValue = (feature.hasSpec ? 0.4 : 0)
     + (feature.hasPlan ? 0.3 : 0)
@@ -483,21 +471,11 @@ function computeFeatureSignals(projectDir, feature, testRefIds) {
     }
   }
 
-  // ── reqCoverage — spec.md IDs that appear in ANY test file ──
-  const specIds = [];
-  if (feature.hasSpec && feature.specPath) {
-    try {
-      const spec = readFileSync(feature.specPath, 'utf-8');
-      const seen = new Set();
-      FEATURE_REQ_RE.lastIndex = 0;
-      let m;
-      while ((m = FEATURE_REQ_RE.exec(spec)) !== null) {
-        if (!seen.has(m[0])) { seen.add(m[0]); specIds.push(m[0]); }
-      }
-    } catch { /* unreadable spec → no IDs */ }
-  }
-  const covered = specIds.filter(id => testRefIds.has(id));
-  const uncovered = specIds.filter(id => !testRefIds.has(id));
+  // ── reqCoverage — spec.md IDs declared in eligible test annotations or labels ──
+  const specPath = feature.specPath ? relative(projectDir, feature.specPath).replaceAll('\\', '/') : null;
+  const specIds = [...definitions.values()].filter(def => def.file === specPath).map(def => def.id);
+  const covered = specIds.filter(id => testRefIds.has(`${specPath}#${id}`));
+  const uncovered = specIds.filter(id => !testRefIds.has(`${specPath}#${id}`));
 
   return {
     reqCoverage: {
@@ -606,10 +584,11 @@ export function runTraceFeatures(projectDir, config, flags) {
     return;
   }
 
-  const testRefIds = collectTestReferencedIds(projectDir);
+  const definitions = collectRequirementIds(projectDir, config, [FEATURE_REQ_RE]);
+  const testRefIds = resolveRequirementReferences(definitions, collectTestReferencedIds(projectDir));
 
   const features = speckit.specs.map(f => {
-    const signals = computeFeatureSignals(projectDir, f, testRefIds);
+    const signals = computeFeatureSignals(projectDir, f, testRefIds, definitions);
     const score = scoreFromSignals(signals);
     const weakest = weakestSignal(signals);
     const needsFix = weakest !== null && signals[weakest].value < 1;

{docguard_cli-0.36.0 → docguard_cli-0.36.2}/cli/docguard.mjs

@@ -652,6 +652,8 @@ async function main() {
     command !== 'setup' &&
     command !== 'init' &&
     !READ_ONLY_COMMANDS.has(command) &&
+    // Agent-family staleness checks must not bootstrap skills or Spec Kit.
+    !(command === 'agents' && flags.check) &&
     !headless
   ) {
     ensureSkills(projectDir, flags);
@@ -733,8 +735,9 @@ async function main() {
       }
       break;
     case 'agents':
-      // v0.20: deprecated → dispatches through init --with
-      await runInit(projectDir, config, { ...flags, with: ['agents'], skipPrompts: true });
+      // A staleness check must bypass init's scaffolding and skill installation.
+      if (flags.check) runAgents(projectDir, config, flags);
+      else await runInit(projectDir, config, { ...flags, with: ['agents'], skipPrompts: true });
       break;
     case 'generate':
       runGenerate(projectDir, config, flags);

{docguard_cli-0.36.0 → docguard_cli-0.36.2}/cli/validators/docs-coverage.mjs

@@ -19,10 +19,12 @@ import { docRolePath, resolveDocRole } from '../shared-doc-roles.mjs';
  * existing tests are unaffected; guard just renders richer output.
  */
 
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { resolve, join, relative, basename, extname } from 'node:path';
+import { existsSync, readFileSync, readdirSync, statSync, lstatSync } from 'node:fs';
+import { resolve, join, relative, basename, extname, isAbsolute } from 'node:path';
 import { resolveSourceRoots } from '../shared-source.mjs';
-import { shouldIgnore, walkFiles as sharedWalkFiles, listCanonicalDocs } from '../shared-ignore.mjs';
+import { shouldIgnore, walkFiles as sharedWalkFiles, buildIgnoreFilter, mergeIgnoreFile, DEFAULT_IGNORE_DIRS } from '../shared-ignore.mjs';
+import { resolveDocDirs } from '../shared.mjs';
+import { parseJsTs, walk } from '../scanners/js-ast.mjs';
 import { detectIaC, hasInfrastructureHeading, buildIaCWarning } from '../scanners/iac.mjs';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
 
@@ -73,7 +75,7 @@ export function validateDocsCoverage(projectDir, config) {
   let total = 0;
 
   // Collect all doc content for searching
-  const allDocContent = collectDocContent(projectDir);
+  const allDocContent = collectDocContent(projectDir, config);
   if (!allDocContent) {
     // Literal legacy shape (no findings key) — tests deepEqual this exact object.
     return { errors: [], warnings: [], passed: 0, total: 0 };
@@ -172,7 +174,7 @@ function checkConfigFiles(projectDir, allDocContent, config = {}) {
         code: 'DCV001',
         validator: 'docsCoverage',
         severity: 'warn',
-        message: `Config file "${entry}" exists but is not mentioned in any documentation. Document its purpose in ARCHITECTURE.md or README.md`,
+        message: `Config file "${entry}" exists but is not mentioned in scanned supported Markdown or extension YAML documentation. Document its purpose in ARCHITECTURE.md or README.md`,
         location: entry,
         suggestion: { kind: 'fix', text: 'Explain what this config file does in ARCHITECTURE.md or README.md' },
       }));
@@ -372,42 +374,60 @@ function checkIaCDocumentation(projectDir, iac, config = {}) {
 }
 
 /**
- * Check 4: Config files that code actually READS are documented.
- *
- * Scans source code for resolve(dir, '.configname') and existsSync('.configname')
- * patterns — these are configs the project USES. Avoids matching config names
- * sitting in arrays (scan patterns for detecting other projects' configs).
+ * Check 4: Distinguish direct file IO from config-like path expressions.
+ * Parsed calls exclude comments and example strings. Unparsed text supplies
+ * review candidates only; it cannot establish file IO or documentation need.
  */
 function checkCodeReferencedConfigs(projectDir, allDocContent, config = {}) {
   const findings = [];
   let passed = 0;
   let total = 0;
-
   const lowerDocContent = allDocContent.toLowerCase();
-  const foundConfigs = new Set();
-
-  // Only match config filenames inside function calls that actually USE the file:
-  // resolve(dir, '.docguardignore'), existsSync('.env.example'), readFileSync('vitest.config.ts')
-  const usageRegex = /(?:resolve|join|existsSync|readFileSync|accessSync|writeFileSync)\s*\([^)]*['"`]([^'"`\n]{2,})['"`]/g;
+  const foundConfigs = new Map();
+  const methods = new Set(['resolve', 'join', 'existsSync', 'accessSync', 'readFileSync', 'writeFileSync']);
+  const directIO = new Set(['readFileSync', 'writeFileSync']);
 
   const scanFile = (filePath) => {
-    const ext = extname(filePath);
-    if (!['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx'].includes(ext)) return;
+    if (!['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx'].includes(extname(filePath))) return;
     let content;
     try { content = readFileSync(filePath, 'utf-8'); } catch { return; }
-
-    usageRegex.lastIndex = 0;
-    let match;
-    while ((match = usageRegex.exec(content)) !== null) {
-      const name = match[1];
-      // Must be a dotfile (.something) or *.config.* — not a path
-      if (name.includes('/') || name.startsWith('..')) continue;
-      const isDotConfig = name.startsWith('.') && name.length > 2;
-      const isNamedConfig = /^[\w-]+\.config\.\w+$/.test(name);
-      if (!isDotConfig && !isNamedConfig) continue;
-      // Skip bare extensions
-      if (/^\.[a-z]{1,4}$/i.test(name)) continue;
-      foundConfigs.add(name);
+    if (!/(?:resolve|join|existsSync|accessSync|readFileSync|writeFileSync)\s*\(/.test(content)) return;
+    // Parsing cannot yield a config candidate without a matching literal prefix.
+    // Keep every escaped source conservatively: escapes may encode that prefix.
+    if (!/['"\x60](?:\.(?![./])|[\w-]+\.config\.)|\\/.test(content)) return;
+    const source = relative(projectDir, filePath).split('\\').join('/');
+    const record = (name, method, line, parsed) => {
+      if (typeof name !== 'string' || name.includes('/') || name.includes('\\') || name.startsWith('..')) return;
+      if (!(name.startsWith('.') && name.length > 2) && !/^[\w-]+\.config\.\w+$/.test(name)) return;
+      if (/^\.[a-z]{1,4}$/i.test(name) || COMMON_DOTFILES.has(name)) return;
+      const direct = parsed && directIO.has(method);
+      // Prefer concrete IO when the same name also occurs in a path expression.
+      if (!foundConfigs.has(name) || (direct && !foundConfigs.get(name).direct)) {
+        foundConfigs.set(name, { direct, parsed, method, source: source + ':' + line });
+      }
+    };
+    const { ast, ok } = parseJsTs(content, filePath);
+    if (ok && !ast.errors?.length) {
+      walk(ast, node => {
+        if (node.type !== 'CallExpression') return;
+        const callee = node.callee;
+        const method = callee.type === 'Identifier' ? callee.name
+          : callee.type === 'MemberExpression' && !callee.computed ? callee.property.name : null;
+        if (!methods.has(method)) return;
+        // IO and existence checks use argument one as the path; join/resolve
+        // may supply a filename in any segment. No dynamic-path evaluation.
+        const args = ['join', 'resolve'].includes(method) ? node.arguments : node.arguments.slice(0, 1);
+        for (const arg of args) {
+          const value = arg.type === 'StringLiteral' ? arg.value
+            : arg.type === 'TemplateLiteral' && arg.expressions.length === 0 ? arg.quasis[0].value.cooked : null;
+          record(value, method, node.loc.start.line, true);
+        }
+      });
+    } else {
+      const pattern = /\b(resolve|join|existsSync|accessSync|readFileSync|writeFileSync)\s*\([^)]*?['"\x60]([^'"\x60\n]{2,})['"\x60]/g;
+      for (const match of content.matchAll(pattern)) {
+        record(match[2], match[1], content.slice(0, match.index).split('\n').length, false);
+      }
     }
   };
 
@@ -415,19 +435,26 @@ function checkCodeReferencedConfigs(projectDir, allDocContent, config = {}) {
     walkFiles(rootDir, scanFile);
   }
 
-  for (const configName of foundConfigs) {
-    if (COMMON_DOTFILES.has(configName)) continue;
+  for (const [configName, evidence] of foundConfigs) {
     total++;
     if (lowerDocContent.includes(configName.toLowerCase())) {
       passed++;
     } else {
+      const scope = 'scanned supported Markdown or extension YAML documentation';
+      const context = evidence.parsed ? evidence.method + ' call' : 'unparsed source text (parser unavailable or failed)';
       findings.push(mkFinding({
         code: 'DCV004',
         validator: 'docsCoverage',
         severity: 'warn',
-        message: `Code references config file "${configName}" but no documentation mentions it. Add it to README.md or ARCHITECTURE.md`,
+        confidence: evidence.direct ? 'high' : 'low',
+        message: evidence.direct
+          ? 'Direct ' + context + ' references config file "' + configName + '" at ' + evidence.source + ', but it is not mentioned in ' + scope + '.'
+          : 'Config-like path "' + configName + '" appears in ' + context + ' at ' + evidence.source + '; file use and documentation need are unverified. No mention was found in ' + scope + '.',
+        // Preserve the published filename location; source context is in the message.
         location: configName,
-        suggestion: { kind: 'fix', text: 'Describe this config file (purpose and format) in README.md or ARCHITECTURE.md' },
+        suggestion: evidence.direct
+          ? { kind: 'fix', text: 'Describe this config file (purpose and format) in a supported documentation file' }
+          : { kind: 'review', text: 'Inspect this source reference: it may be a directory, generated output, or example. Document it only if appropriate.' },
       }));
     }
   }
@@ -500,36 +527,59 @@ function checkReadmeSections(projectDir) {
 /**
  * Collect all documentation content into a single searchable string.
  */
-function collectDocContent(projectDir) {
-  const docPaths = [];
-
-  const rootDocs = ['README.md', 'AGENTS.md', 'CLAUDE.md', 'CONTRIBUTING.md', 'STANDARD.md'];
-  for (const doc of rootDocs) {
-    const p = resolve(projectDir, doc);
-    if (existsSync(p)) docPaths.push(p);
-  }
-
-  for (const doc of listCanonicalDocs(projectDir)) docPaths.push(doc.abs); // recursive
-
-  const extDir = resolve(projectDir, 'extensions');
-  if (existsSync(extDir)) {
-    walkFiles(extDir, (f) => {
-      if (f.endsWith('.md') || f.endsWith('.yml') || f.endsWith('.yaml')) {
-        docPaths.push(f);
+function collectDocContent(projectDir, config = {}) {
+  const docPaths = new Set();
+  const visited = new Set();
+  const isIgnored = buildIgnoreFilter(mergeIgnoreFile(projectDir, { ...config }).ignore);
+
+  // Check every ancestor before traversal: the shared walker follows symlinks.
+  // Explicit homes must remain scoped inside the project, including private aliases.
+  const safePath = (path) => {
+    const normalized = path.replace(/\\/g, '/');
+    if (isAbsolute(normalized) || /^[A-Za-z]:/.test(normalized) || normalized.includes('\0')) return null;
+    const parts = normalized.split('/').filter(p => p && p !== '.');
+    if (!parts.length || parts.some(p => p === '..' || ['.local', '.git'].includes(p.toLowerCase())
+        || /^\.env(?:\.|$)/i.test(p) || DEFAULT_IGNORE_DIRS.has(p) || IGNORE_DIRS.has(p))) return null;
+    let current = resolve(projectDir);
+    let rel = '';
+    try {
+      for (const part of parts) {
+        rel = rel ? rel + '/' + part : part;
+        if (isIgnored(rel) || isIgnored(rel + '/')) return null;
+        current = join(current, part);
+        if (lstatSync(current).isSymbolicLink()) return null;
       }
-    });
-  }
-
-  for (const docsDir of ['docs', 'docs-implementation']) {
-    const d = resolve(projectDir, docsDir);
-    if (existsSync(d)) {
-      walkFiles(d, (f) => {
-        if (f.endsWith('.md')) docPaths.push(f);
-      });
+      return current;
+    } catch { return null; }
+  };
+  const addDoc = (rel) => {
+    const abs = safePath(rel);
+    if (abs && lstatSync(abs).isFile()) docPaths.add(abs);
+  };
+  const walkDocs = (rel) => {
+    const dir = safePath(rel);
+    if (!dir || visited.has(dir)) return;
+    visited.add(dir);
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue;
+      const path = relative(projectDir, join(dir, entry.name)).split('\\').join('/');
+      if (entry.isDirectory() && !entry.name.startsWith('.')) walkDocs(path);
+      else if (entry.isFile() && (/\.md$/i.test(entry.name)
+          || (path.startsWith('extensions/') && /\.ya?ml$/i.test(entry.name)))) addDoc(path);
     }
+  };
+
+  for (const doc of ['README.md', 'AGENTS.md', 'CLAUDE.md', 'CONTRIBUTING.md', 'STANDARD.md']) addDoc(doc);
+  for (const dir of resolveDocDirs(projectDir, config)) walkDocs(dir);
+  // Resolve roles directly so raw callers get the same boundaries as loadConfig.
+  for (const role of Object.keys(config.docs?.roles || {})) {
+    const abs = resolveDocRole(projectDir, config, role);
+    addDoc(relative(projectDir, abs));
   }
 
-  if (docPaths.length === 0) return null;
+  if (docPaths.size === 0) return null;
   const parts = [];
   for (const p of docPaths) {
     try { parts.push(readFileSync(p, 'utf-8')); } catch { /* skip */ }