docguard-cli 0.36.1 → 0.36.2

package/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.');
 

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

package/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);

package/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 */ }

package/cli/validators/schema-sync.mjs

@@ -10,15 +10,14 @@ import { docRolePath, resolveDocRole } from '../shared-doc-roles.mjs';
  * Zero NPM runtime dependencies — pure Node.js built-ins only.
  */
 
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { resolve, join, relative, extname, basename } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve, relative, basename } from 'node:path';
 import { resolveSourceRoots } from '../shared-source.mjs';
-import { walkFiles as sharedWalkFiles } from '../shared-ignore.mjs';
+import { DEFAULT_IGNORE_DIRS, relPosix, shouldIgnore, walkFiles as sharedWalkFiles } from '../shared-ignore.mjs';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 const IGNORE_DIRS = new Set([
-  'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
-  '.cache', '__pycache__', '.venv', 'vendor', '.turbo', '.vercel',
+  ...DEFAULT_IGNORE_DIRS,
   '.amplify-hosting', '.serverless',
 ]);
 
@@ -192,7 +191,8 @@ function detectAllModels(projectDir, config = {}) {
  * Find schema files for a given detector configuration.
  */
 function findSchemaFiles(projectDir, detector, config = {}) {
-  const files = [];
+  // Deduplicate files, not model names: separate schemas may share a name.
+  const files = new Set();
 
   // Monorepo-aware: resolve each searchDir against the project root AND every
   // configured source root (config.sourceRoot + workspaces), so schemas under
@@ -203,19 +203,24 @@ function findSchemaFiles(projectDir, detector, config = {}) {
   for (const base of bases) {
     for (const searchDir of detector.searchDirs) {
       const dir = resolve(base, searchDir);
-      if (seenDirs.has(dir) || !existsSync(dir)) continue;
+      const rel = relPosix(projectDir, dir);
+      if (seenDirs.has(dir) || !existsSync(dir) ||
+          rel.split('/').some(part => IGNORE_DIRS.has(part)) ||
+          shouldIgnore(rel + '/', config)) continue;
       seenDirs.add(dir);
-      scanSchemaDir(dir, detector.filePattern, files);
+      scanSchemaDir(dir, detector.filePattern, files, projectDir, config);
     }
   }
 
-  return files;
+  return [...files];
 }
 
 // v0.29 consolidation: traversal delegates to the shared canonical walker.
-function scanSchemaDir(dir, filePattern, files) {
+function scanSchemaDir(dir, filePattern, files, projectDir, config) {
   sharedWalkFiles(dir, (full) => {
-    if (filePattern.test(basename(full))) files.push(full);
+    if (filePattern.test(basename(full)) && !shouldIgnore(relPosix(projectDir, full), config)) {
+      files.add(full);
+    }
   }, { ignoreDirs: IGNORE_DIRS });
 }
 

package/cli/validators/traceability.mjs

@@ -297,6 +297,9 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
 
   // ── Step 2: Scan test files for requirement ID references ──
   const testRefs = scanTestFilesForReferences(projectDir, projectFiles, patterns);
+  const resolvedRefs = resolveRequirementReferences(reqIds, testRefs);
+  const definitionCounts = new Map();
+  for (const def of reqIds.values()) definitionCounts.set(def.id, (definitionCounts.get(def.id) || 0) + 1);
 
   // ── Step 3: Report traceability results ──
 
@@ -308,14 +311,15 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
   let testCorpus = null;
 
   // Check each documented requirement has at least one test reference
-  for (const [reqId, location] of reqIds) {
+  for (const [key, location] of reqIds) {
+    const reqId = location.id;
     total++;
-    if (testRefs.has(reqId)) {
+    if (resolvedRefs.has(key)) {
       passed++;
     } else {
       // Try to recover a likely-but-unannotated test via TF-IDF cosine.
       let softHint = '';
-      let softText = `Review existing tests for this requirement. If a test verifies it, add an @req ${reqId} annotation or requirement ID test label; write a test only if behavioral coverage is actually missing.`;
+      let softText = `Review existing tests for this requirement. If a test verifies it, add an @req ${key} annotation or requirement ID test label; write a test only if behavioral coverage is actually missing.`;
       const queryText = location.text && location.text.length > reqId.length ? location.text : reqId;
       if (testCorpus === null) testCorpus = buildTestCorpus(projectDir, projectFiles);
       if (testCorpus.length > 0) {
@@ -324,14 +328,14 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
         if (top && top.score >= softThreshold) {
           const pct = (top.score * 100).toFixed(0);
           softHint = ` — IR soft-match: ${top.id} (${pct}% similar) may already cover it`;
-          softText = `Review ${top.id} as a candidate (${pct}% text similarity, not coverage evidence). Add @req ${reqId} only if it verifies the requirement; otherwise inspect other tests before deciding a new test is needed.`;
+          softText = `Review ${top.id} as a candidate (${pct}% text similarity, not coverage evidence). Add @req ${key} only if it verifies the requirement; otherwise inspect other tests before deciding a new test is needed.`;
         }
       }
       findings.push(mkFinding({
         code: 'TRC004',
         validator: 'traceability',
         severity: 'warn',
-        message: `Requirement ${reqId} (${location.file}:${location.line}) has no recognized test annotation or label; behavioral coverage is unknown.${softHint}`,
+        message: `Requirement ${reqId} (${location.file}:${location.line}) has no recognized test annotation or label; behavioral coverage is unknown.${definitionCounts.get(reqId) > 1 ? ` This ID occurs in multiple documents; use ${key} to disambiguate test references.` : ""}${softHint}`,
         location: `${location.file}:${location.line}`,
         suggestion: { kind: 'review', text: softText },
       }));
@@ -340,15 +344,16 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
 
   // Check for orphaned test refs (tests referencing non-existent requirements)
   for (const [reqId, refs] of testRefs) {
-    if (!reqIds.has(reqId)) {
+    const orphan = refs.find(ref => ref.scope ? !reqIds.has(`${ref.scope}#${reqId}`) : !definitionCounts.has(reqId));
+    if (orphan) {
       total++;
       findings.push(mkFinding({
         code: 'TRC005',
         validator: 'traceability',
         severity: 'warn',
-        message: `Test references ${reqId} (${refs[0].file}:${refs[0].line}) but no requirement ` +
+        message: `Test references ${orphan.scope ? `${orphan.scope}#` : ""}${reqId} (${orphan.file}:${orphan.line}) but no requirement ` +
           `with this ID exists in documentation. Remove the reference or add the requirement to docs`,
-        location: `${refs[0].file}:${refs[0].line}`,
+        location: `${orphan.file}:${orphan.line}`,
         suggestion: { kind: 'review', text: 'Remove the stale reference, or add the requirement to the documentation' },
       }));
     }
@@ -357,7 +362,7 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
   return { findings, passed, total };
 }
 
-function collectRequirementIds(projectDir, config, patterns) {
+export function collectRequirementIds(projectDir, config, patterns = DEFAULT_REQ_PATTERNS) {
   const reqIds = new Map(); // reqId → { file, line }
   const docSearchPaths = getRequirementDocPaths(projectDir, config);
 
@@ -371,7 +376,7 @@ function collectRequirementIds(projectDir, config, patterns) {
     if (!hasMatch) continue;
 
     const lines = content.split('\n');
-    const docName = relative(projectDir, docPath);
+    const docName = relative(projectDir, docPath).replaceAll("\\", "/");
 
     let fence = null;
     let exampleLevel = null;
@@ -418,8 +423,9 @@ function collectRequirementIds(projectDir, config, patterns) {
           }
           const reqId = match[0];
           if (!reqId.length) { pattern.lastIndex++; continue; }
-          if (!reqIds.has(reqId)) {
-            reqIds.set(reqId, { file: docName, line: i + 1, text: line.trim() });
+          const key = `${docName}#${reqId}`;
+          if (!reqIds.has(key)) {
+            reqIds.set(key, { id: reqId, file: docName, line: i + 1, text: line.trim() });
           }
         }
       }
@@ -429,6 +435,26 @@ function collectRequirementIds(projectDir, config, patterns) {
   return reqIds;
 }
 
+/** Resolve positive test links without sharing evidence between document scopes. */
+export function resolveRequirementReferences(definitions, references) {
+  const byId = new Map();
+  for (const [key, definition] of definitions) {
+    if (!byId.has(definition.id)) byId.set(definition.id, []);
+    byId.get(definition.id).push(key);
+  }
+  const resolved = new Map();
+  for (const [id, refs] of references) {
+    const candidates = byId.get(id) || [];
+    for (const ref of refs) {
+      const key = ref.scope ? `${ref.scope}#${id}` : candidates.length === 1 ? candidates[0] : null;
+      if (!key || !definitions.has(key)) continue;
+      if (!resolved.has(key)) resolved.set(key, []);
+      resolved.get(key).push(ref);
+    }
+  }
+  return resolved;
+}
+
 // A mention in fixture data is not a coverage declaration. Keep the same ID
 // patterns, but apply them only to annotations and test labels. In particular,
 // prose discussing an annotation ("never annotates @req ...") is not one.
@@ -495,7 +521,14 @@ function testDeclarations(content, filename) {
   return declarations;
 }
 
-function scanTestFilesForReferences(projectDir, projectFiles, patterns) {
+/**
+ * Read explicit requirement annotations and test labels from eligible test sources.
+ * Shared by validation and feature scoring; fixture data is not linkage evidence.
+ * Callers supply project-relative candidate paths and global requirement regexes.
+ * No files are written and no findings or suppression policy are consulted.
+ * @returns {Map<string, Array<{file: string, line: number}>>} ID to declaration locations
+ */
+export function scanTestFilesForReferences(projectDir, projectFiles, patterns) {
   const testFiles = projectFiles.filter(isTestSource);
 
   const testRefs = new Map(); // reqId → [{ file, line }]
@@ -520,7 +553,12 @@ function scanTestFilesForReferences(projectDir, projectFiles, patterns) {
           const reqId = match[0];
           if (!testRefs.has(reqId)) testRefs.set(reqId, []);
           const line = declaration.line + (declaration.text.slice(0, match.index).match(/\n/g) || []).length;
-          testRefs.get(reqId).push({ file: relPath, line });
+          // A document qualifier is repository-relative and exact; never fall
+          // back to a bare ID when a supplied qualifier fails to resolve.
+          const prefix = declaration.text.slice(0, match.index);
+          const qualifier = prefix.match(/([^\s`"'<>()[\]{}]+)#$/);
+          const scope = qualifier ? qualifier[1].replaceAll('\\', '/').replace(/^\.\//, '') : null;
+          testRefs.get(reqId).push({ file: relPath, line, scope });
         }
       }
     }

package/docs/configuration.md

@@ -198,3 +198,18 @@ These statuses skip currentness assertions; they do not hide structural or other
 Guard JSON includes checkCoverage and an applicability record per validator. States distinguish checked, partial, disabled, not-applicable, missing-prerequisite, unsupported, no-matches, and error. A passing gate means the selected policy passed; it does not mean unsupported languages or unmatched inputs were examined. CI and reports preserve this disclosure. Python import-graph analysis remains unsupported; mixed Python/JS projects disclose partial architecture coverage.
 
 Wrangler configuration supplies evidence for Worker classification. Supported typed Worker bindings participate in environment extraction without executing configuration or application code. Dynamic names, alias/dataflow tracking, and unsupported forms remain outside this bounded analysis. The existing optional Babel parser resolves lexical bindings; the fallback covers ordinary tested scopes and has lower syntax coverage.
+
+### Evidence boundaries in documentation and schema scans
+
+Documentation-coverage filename checks search supported Markdown in conventional and explicitly configured homes, mapped role files, and supported extension metadata. Configured homes extend the defaults. Excluded files, private paths and symlinks cannot satisfy a documentation reference. This search does not establish absence of an explanation in external sites, RST, or unsupported formats.
+
+A parsed direct file-read/write call supplies stronger path evidence than a path construction or existence check. Ambiguous paths remain low-confidence review signals; a directory name alone does not establish a configuration file. The bounded detector does not resolve arbitrary import aliases or dynamic paths. Schema synchronization applies source exclusions and deduplicates overlapping roots by source file, preserving models in distinct files even when names match.
+
+Feature requirement scoring recognizes eligible test annotations and labels using the validator parser. An arbitrary fixture string is not linkage evidence, and a recognized link is not proof of behavioral coverage. Duplicate requirement IDs across separate specifications remain a known scoping limitation.
+
+
+### Requirement identity across documents
+
+Requirement definitions are identified by repository-relative document path plus ID. A bare test annotation such as `@req FR-001` earns linkage credit only when that ID is defined in one document. When features reuse an ID, qualify the declaration: `@req specs/payments/spec.md#FR-001`. The same spelling works in a test label. Use forward slashes; an optional leading `./` is accepted. Qualifiers are exact repository-relative paths, not paths relative to the test file.
+
+Validation and `trace --features` share definition parsing and reference resolution. A qualified reference credits only its target document. Ambiguous bare references credit neither feature and produce a review finding for each unresolved definition. A wrong qualifier is an orphan reference and never falls back to a bare match. Repeated mentions within one document do not create additional identities. Linkage remains evidence of a declaration, not proof of behavioral correctness; lifecycle and arbitrary verification-link semantics are separate concerns.

package/extensions/spec-kit-docguard/extension.yml

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.36.1"
+  version: "0.36.2"
   description: "Canonical-Driven Development enforcement as a true spec-kit extension. LLM-first design with automated validators, 4 AI behavior skills, spec-kit skill chaining, and workflow hooks. One pinned runtime dependency (@babel/parser); pure Node.js otherwise."
   author: "Ricardo Accioly"
   repository: "https://github.com/raccioly/docguard"

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

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

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

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

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

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

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

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

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

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

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

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

package/package.json

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

package/templates/ci/github-actions.yml

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