docguard-cli 0.36.2 → 0.37.0

package/cli/commands/trace.mjs

@@ -433,7 +433,17 @@ function featureBar(score) {
 function collectTestReferencedIds(projectDir) {
   const projectFiles = [];
   scanDir(projectDir, projectDir, projectFiles);
-  return scanTestFilesForReferences(projectDir, projectFiles, [FEATURE_REQ_RE]);
+  const references = scanTestFilesForReferences(projectDir, projectFiles, [FEATURE_REQ_RE]);
+  // Feature completion evidence must survive spec retirement and ID reuse.
+  // Bare FR-001 references can be useful navigation for the repo-wide matrix,
+  // but they can rebind to a different feature after the original spec leaves
+  // the working tree. Keep only document-qualified identities here.
+  const qualified = new Map();
+  for (const [id, refs] of references) {
+    const scoped = refs.filter(ref => ref.scope);
+    if (scoped.length > 0) qualified.set(id, scoped);
+  }
+  return qualified;
 }
 
 /**

package/cli/config.mjs

@@ -79,6 +79,8 @@ export function loadConfig(projectDir) {
       security: false,
       environment: true,
       freshness: true,
+      documentLifecycle: true,
+      specRegistry: true,
       // v0.31.0 — all three default ON. Soft (confidence:low, never break CI),
       // heuristic (field cases require ongoing precision checks), and quiet when
       // not applicable (no diff / no API-reference doc). api-doc-smells is

package/cli/docguard.mjs

@@ -51,6 +51,8 @@ import { runMemory } from './commands/memory.mjs';
 import { runDemo } from './commands/demo.mjs';
 import { runAgent } from './commands/agent.mjs';
 import { runMcp } from './commands/mcp.mjs';
+import { runArchive } from './commands/retire.mjs';
+import { runSpecs } from './commands/specs.mjs';
 import { ensureSkills } from './ensure-skills.mjs';
 
 // ── Shared constants (imported to break circular dependencies) ──────────
@@ -97,6 +99,8 @@ ${c.bold}Tools (situational, but day-to-day useful)${c.reset}
   ${c.green}report${c.reset}     Compliance-evidence bundle — guard + score + ALCOA+ + integrity hash (${c.cyan}--format json${c.reset}, ${c.cyan}--out <file>${c.reset})
   ${c.green}ci${c.reset}         Pipeline gate: guard + score in one command (${c.cyan}--threshold <n>${c.reset}, ${c.cyan}--fail-on-warning${c.reset}, ${c.cyan}--format json${c.reset}; records score history)
   ${c.green}memory${c.reset}     Show what DocGuard remembers (${c.cyan}--diff${c.reset} drills into drift)
+  ${c.green}retire${c.reset}     Remove reviewed docs from active AI context (${c.cyan}--plan${c.reset}; explicit ${c.cyan}--write --path${c.reset})
+  ${c.green}specs${c.reset}      Track spec lifecycle and evidence (${c.cyan}--check|--write${c.reset}; ${c.cyan}preflight --path <spec>${c.reset})
   ${c.green}trace${c.reset}      Requirements traceability matrix (${c.cyan}--reverse${c.reset} for code→doc map, ${c.cyan}--features${c.reset} for per-feature adherence)
   ${c.green}upgrade${c.reset}    Migrate ${c.cyan}.docguard.json${c.reset} schema + CLI (${c.cyan}--apply --pr${c.reset} for team-wide PR)
   ${c.green}watch${c.reset}      Live mode: re-run guard on file changes
@@ -109,12 +113,12 @@ ${c.bold}init --with <name>${c.reset} ${c.dim}— optional scaffolders, picked a
   ${c.dim}llms${c.reset}       llms.txt generation
   ${c.dim}publish${c.reset}    External doc-site scaffold (Mintlify) ${c.dim}— experimental${c.reset}
 
-${c.bold}Deprecation aliases${c.reset} ${c.dim}— still work in v0.20.x with a yellow warning${c.reset}
+${c.bold}Deprecation aliases${c.reset} ${c.dim}— supported until v1.0 with a yellow warning${c.reset}
   ${c.dim}setup${c.reset} → ${c.cyan}init --wizard${c.reset}
   ${c.dim}agents · hooks · badge · llms · publish${c.reset} → ${c.cyan}init --with <name>${c.reset}
   ${c.dim}impact${c.reset} → ${c.cyan}diff --since <ref>${c.reset}
   ${c.dim}audit${c.reset} → ${c.green}guard${c.reset} ${c.dim}(permanent — no warning, no removal planned)${c.reset}
-  ${c.dim}See docs-implementation/MIGRATION-v0.20.md for the full timeline.${c.reset}
+  ${c.dim}Run the legacy form to see its replacement.${c.reset}
 
 ${c.bold}Options:${c.reset}
   --dir <path>    Project directory (default: current directory)
@@ -129,9 +133,9 @@ ${c.bold}Options:${c.reset}
   --threshold <n> Minimum score for CI pass (used with ci command)
   --fail-on-warning  Fail CI on warnings (used with ci command)
   --auto          Auto-fix what's possible (used with fix command)
-  --write         Apply deterministic fixes in place (fix command): removes
-                  documented endpoints the OpenAPI spec confirms are gone.
-                  Only edits docguard:generated docs unless --force.
+  --write         Apply a command's explicit deterministic write path. For fix,
+                  only edits docguard:generated docs unless --force; specs
+                  refreshes observed registry evidence; retire requires --path.
   --plan          AI-powered Generate (generate command): scan any project
                   (JS/Python/Rust/Go/Java/…), emit the agent task manifest +
                   code-truth skeleton. Add --write to scaffold, --format json
@@ -308,6 +312,35 @@ const COMMAND_HELP = {
     ],
     examples: ['docguard verify --semantic', 'docguard verify --semantic --format json'],
   },
+  retire: {
+    summary: 'Remove reviewed docs from active AI context while preserving recovery from a retained Git ref.',
+    usage: 'docguard retire [--plan|--check] | --write --path <document> [--path <document>...] --reason <text> [--superseded-by <document>] [--evidence <document>...] [--retention-ref <ref>]',
+    flags: [
+      ['--plan', 'Read-only lifecycle candidate inventory (default behavior)'],
+      ['--check', 'Exit 2 when high-confidence lifecycle candidates remain'],
+      ['--fail-on-warning', 'With --check: also gate low-confidence review candidates'],
+      ['--write', 'Retire only the explicitly selected clean tracked documents'],
+      ['--path <path>', 'Documentation file or document-only directory; repeatable'],
+      ['--reason <text>', 'Required explanation recorded in the archive manifest'],
+      ['--superseded-by <path>', 'Current document that replaces the archived material'],
+      ['--evidence <path>', 'Clean current document that contains the consolidated outcome; repeatable'],
+      ['--retention-ref <ref>', 'Branch ref that must retain the source revision'],
+      ['--format json', 'Machine-readable plan or result'],
+    ],
+    examples: ['docguard retire --plan', 'docguard retire --check --format json', 'docguard retire --write --path specs/001-done --reason "Implemented in v1.2"'],
+  },
+  specs: {
+    summary: 'Maintain the deterministic spec lifecycle and evidence registry.',
+    usage: 'docguard specs [--check|--write] | docguard specs preflight [--path <spec>] [--format json]',
+    flags: [
+      ['--check', 'Exit 2 when the committed registry is missing, stale, or inconsistent'],
+      ['--write', 'Refresh observed evidence while preserving reviewed lifecycle fields'],
+      ['preflight', 'Brief prior specs, or gate a generated draft with --path'],
+      ['--path <spec>', 'Generated spec to compare against current lifecycle state'],
+      ['--format json', 'Machine-readable registry or preflight result'],
+    ],
+    examples: ['docguard specs --check', 'docguard specs --write', 'docguard specs preflight', 'docguard specs preflight --path specs/007-feature/spec.md'],
+  },
 };
 
 function printCommandHelp(command) {
@@ -535,8 +568,26 @@ async function main() {
       flags.apiKey = args[i + 1];
       i++;
     } else if (args[i] === '--path' && args[i + 1]) {
-      // mcp --transport http: HTTP mount path (default /mcp).
-      flags.path = args[i + 1];
+      if (command === 'retire' || command === 'archive') {
+        flags.paths = flags.paths || [];
+        flags.paths.push(args[i + 1]);
+      } else {
+        // mcp --transport http: HTTP mount path (default /mcp).
+        flags.path = args[i + 1];
+      }
+      i++;
+    } else if (args[i] === '--reason' && args[i + 1]) {
+      flags.reason = args[i + 1];
+      i++;
+    } else if (args[i] === '--superseded-by' && args[i + 1]) {
+      flags.supersededBy = args[i + 1];
+      i++;
+    } else if (args[i] === '--evidence' && args[i + 1]) {
+      flags.evidencePaths = flags.evidencePaths || [];
+      flags.evidencePaths.push(args[i + 1]);
+      i++;
+    } else if (args[i] === '--retention-ref' && args[i + 1]) {
+      flags.retentionRef = args[i + 1];
       i++;
     } else if (args[i] === '--code') {
       flags.code = args[i + 1] && !args[i + 1].startsWith('--') ? args[++i] : '';
@@ -624,7 +675,7 @@ async function main() {
   // `diff`/`impact` only read; `demo` runs against a throwaway fixture.)
   const READ_ONLY_COMMANDS = new Set([
     'guard', 'audit', 'score', 'diff', 'impact',
-    'diagnose', 'trace', 'explain', 'memory', 'demo', 'agent',
+    'diagnose', 'trace', 'explain', 'memory', 'demo', 'agent', 'retire', 'archive', 'specs',
     // feedback only writes its own .docguard/feedback/ — it must NOT scaffold
     // skills or touch source, so it's gated out of ensureSkills like the rest.
     'feedback',
@@ -659,10 +710,9 @@ async function main() {
     ensureSkills(projectDir, flags);
   }
 
-  // v0.20: deprecation aliases. The legacy command keeps working through v0.20
+  // v0.20: deprecation aliases. The legacy command keeps working until v1.0
   // and emits a yellow stderr warning suggesting the new shape. Quiet mode
   // (e.g. inside hooks) suppresses the warning so CI output stays clean.
-  // The full deprecation timeline is in docs-implementation/MIGRATION-v0.20.md.
   const DEPRECATED_COMMANDS = {
     setup:   { since: '0.20', replacement: 'docguard init --wizard' },
     agents:  { since: '0.20', replacement: 'docguard init --with agents' },
@@ -694,7 +744,7 @@ async function main() {
   if (DROPPED_ALIASES[command]) {
     console.error(`${c.red}Unknown command: ${command}${c.reset}`);
     console.error(`${c.yellow}Hint: this alias was removed in v0.20. Try ${c.cyan}docguard ${DROPPED_ALIASES[command]}${c.yellow}.${c.reset}`);
-    console.error(`${c.dim}See docs-implementation/MIGRATION-v0.20.md for the full list.${c.reset}`);
+    console.error(`${c.dim}Use the replacement shown above; removed aliases are not restored.${c.reset}`);
     process.exit(1);
   }
 
@@ -703,7 +753,7 @@ async function main() {
   if (DEPRECATED_COMMANDS[command] && !flags.quiet && !(command === 'hooks' && flags.claude)) {
     const { since, replacement } = DEPRECATED_COMMANDS[command];
     console.error(`${c.yellow}⚠ Deprecated since v${since}:${c.reset} ${c.cyan}docguard ${command}${c.reset} → use ${c.cyan}${replacement}${c.reset}`);
-    console.error(`${c.dim}  The old form still works in v0.20.x but will be removed in v1.0. See MIGRATION-v0.20.md.${c.reset}`);
+    console.error(`${c.dim}  The old form remains compatible until v1.0.${c.reset}`);
   }
 
   switch (command) {
@@ -830,6 +880,13 @@ async function main() {
     case 'memory':
       runMemory(projectDir, config, flags);
       break;
+    case 'retire':
+    case 'archive': // Development alias; `retire` avoids collision with Spec Kit Archive.
+      runArchive(projectDir, config, flags);
+      break;
+    case 'specs':
+      runSpecs(projectDir, config, flags);
+      break;
     case 'demo':
       // v0.21: zero-install "ah-ha" moment — runs guard against a baked-in
       // fixture (templates/demo-fixture/) and prints curated drift findings

package/cli/findings.mjs

@@ -486,6 +486,60 @@ export const CODES = {
     help: 'Guard reports at most 10 phantom-completion findings (SPK008) per run to avoid noise; this line counts the remainder. Fix or uncheck the reported tasks and re-run guard to surface more, or set `"specKit": { "phantomCheck": false }` in .docguard.json to disable the check.',
     suppress: null,
   },
+  DLC001: {
+    validator: 'documentLifecycle',
+    title: 'Terminal document remains in active context',
+    help: 'A tracked Markdown file declares itself superseded, deprecated, obsolete, or archived but remains searchable as current repository context. Confirm its outcomes are represented in current docs, then use `docguard retire --write --path <path> --reason <reason>`.',
+    suppress: null,
+  },
+  DLC002: {
+    validator: 'documentLifecycle',
+    title: 'Completed task list needs lifecycle review',
+    help: 'A spec has checked tasks and no open tasks. This is a review signal, not proof that the feature shipped. Confirm release evidence and current documentation before archiving the spec.',
+    suppress: null,
+  },
+  DLC003: {
+    validator: 'documentLifecycle',
+    title: 'Document lifecycle coverage incomplete',
+    help: 'DocGuard could not enumerate or read every tracked Markdown document. Fix Git access or file readability and rerun guard; an incomplete lifecycle scan must not be interpreted as a clean result.',
+    suppress: null,
+  },
+  DLC004: {
+    validator: 'documentLifecycle',
+    title: 'Retired document remains active',
+    help: 'The retirement manifest records this path, but the document still exists in the working tree. Remove it through the reviewed retirement transaction or remove the incorrect manifest event; the two states must agree.',
+    suppress: null,
+  },
+  SPR001: {
+    validator: 'specRegistry',
+    title: 'Spec registry missing or stale',
+    help: 'The committed `.docguard-specs.json` does not match the deterministic projection of current specs, tasks, tests, and archive tombstones. Run `docguard specs --write`, review the diff, and commit it with the behavior change.',
+    suppress: null,
+  },
+  SPR002: {
+    validator: 'specRegistry',
+    title: 'Spec identity missing or reused',
+    help: 'Every active spec needs one immutable lowercase Spec ID in authoritative metadata. IDs survive moves and retirement and may never be reused. Add `**Spec ID**: ` followed by a unique namespaced ID in backticks.',
+    suppress: null,
+  },
+  SPR003: {
+    validator: 'specRegistry',
+    title: 'Spec registry is invalid',
+    help: 'The registry is malformed or contains an unsupported lifecycle value. DocGuard refuses to overwrite invalid reviewed state. Repair the named field, then run `docguard specs --write`.',
+    suppress: null,
+  },
+  SPR004: {
+    validator: 'specRegistry',
+    title: 'Spec lifecycle contradicts storage',
+    help: 'Working-tree presence, lifecycle context, storage state, and the recovery archive disagree. Active specs must be current/working_tree; retired specs must be retired/git_history with a reason and matching archive event.',
+    suppress: null,
+  },
+  SPR005: {
+    validator: 'specRegistry',
+    title: 'New spec overlaps prior intent',
+    help: 'Preflight found lexical overlap with a prior spec. This is a review hint, never proof of duplication or delivery. Inspect the prior lifecycle and evidence before adding an explicit supersedes or related relationship.',
+    suppress: null,
+  },
   XRF001: {
     validator: 'crossReference',
     title: 'Broken doc link',

package/cli/scanners/document-lifecycle.mjs

@@ -0,0 +1,184 @@
+/**
+ * Read-only document lifecycle signals shared by `retire` and guard.
+ * Signals identify review candidates; they never authorize deletion.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { shouldIgnore } from '../shared-ignore.mjs';
+
+const RETIRED_STATUSES = new Set(['archived', 'deprecated', 'obsolete', 'superseded']);
+const COMPLETION_STATUSES = new Set(['complete', 'completed']);
+const EXCLUDED_PREFIXES = ['.git', '.local', '.docguard'];
+const MANIFEST_PATH = '.docguard-archive.json';
+
+export function readRetirementManifest(projectDir) {
+  const path = resolve(projectDir, MANIFEST_PATH);
+  if (!existsSync(path)) return { ok: true, paths: new Set(), entries: [], retention: null, error: null };
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (parsed?.schemaVersion !== 1 || parsed?.strategy !== 'git-history' || !Array.isArray(parsed.entries)) {
+      throw new Error('unsupported schema');
+    }
+    const globalRecovery = parsed.retention?.recoverability === 'verified'
+      && typeof parsed.retention?.ref === 'string'
+      && /^(?:sha1|sha256)$/.test(parsed.retention?.objectFormat || '');
+    for (const entry of parsed.entries) {
+      const path = entry?.path;
+      const entryRecovery = entry?.recoverability === 'verified'
+        && typeof entry?.retentionRef === 'string'
+        && /^(?:sha1|sha256)$/.test(entry?.objectFormat || '');
+      if (typeof path !== 'string' || !path || path.startsWith('/')
+        || path.replaceAll('\\', '/').split('/').includes('..')
+        || typeof entry?.archivedFrom !== 'string'
+        || !/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(entry.archivedFrom)
+        || typeof entry?.blob !== 'string'
+        || !/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(entry.blob)
+        || typeof entry?.reason !== 'string' || !entry.reason.trim()
+        || (entry?.requirementIds !== undefined && (!Array.isArray(entry.requirementIds)
+          || entry.requirementIds.some(id => typeof id !== 'string' || !id || id.length > 128 || /[\s#\0]/.test(id))))
+        || (entry?.specId !== undefined && (typeof entry.specId !== 'string'
+          || !/^[a-z0-9][a-z0-9._-]{2,127}$/.test(entry.specId)))
+        || (!globalRecovery && !entryRecovery)) {
+        throw new Error(`invalid recovery entry for ${path || '<unknown path>'}`);
+      }
+    }
+    return {
+      ok: true,
+      paths: new Set(parsed.entries.map(entry => entry.path)),
+      entries: parsed.entries,
+      retention: parsed.retention || null,
+      error: null,
+    };
+  } catch (error) {
+    return { ok: false, paths: new Set(), entries: [], retention: null, error: `${MANIFEST_PATH}: ${error.message}` };
+  }
+}
+
+function trackedFiles(projectDir) {
+  const result = spawnSync('git', ['ls-files', '-z'], {
+    cwd: projectDir,
+    encoding: 'utf8',
+    maxBuffer: 8 * 1024 * 1024,
+  });
+  if (result.status !== 0) {
+    const error = result.error?.message || result.stderr || result.stdout || 'git ls-files failed';
+    return {
+      ok: false,
+      files: [],
+      reason: /not a git repository|must be run in a work tree/i.test(error)
+        ? 'not-git'
+        : 'git-unavailable',
+      error: error.trim(),
+    };
+  }
+  return { ok: true, files: result.stdout.split('\0').filter(Boolean), reason: null, error: null };
+}
+
+export function parseLifecycleStatus(content) {
+  const header = content.split('\n').slice(0, 40).join('\n');
+  const match = header.match(/(?:^|\n)\s*(?:#{1,6}\s*)?(?:\*\*)?Status(?::)?(?:\*\*)?\s*:?\s*(?:\*\*)?([^*\n]+)/i);
+  return match?.[1]?.trim() || null;
+}
+
+function completedTaskSignal(projectDir, path, content, tracked) {
+  let taskContent = content;
+  if (!/(?:^|\n)\s*- \[[ xX]\]/.test(taskContent) && /(?:^|\/)spec\.md$/i.test(path)) {
+    const taskRel = `${dirname(path)}/tasks.md`;
+    const taskPath = resolve(projectDir, taskRel);
+    if (tracked.has(taskRel) && existsSync(taskPath)) taskContent = readFileSync(taskPath, 'utf8');
+  }
+  const checked = taskContent.match(/(?:^|\n)\s*- \[[xX]\]/g)?.length || 0;
+  const open = taskContent.match(/(?:^|\n)\s*- \[ \]/g)?.length || 0;
+  return checked > 0 && open === 0 ? { checked, open } : null;
+}
+
+export function scanDocumentLifecycle(projectDir, config = {}) {
+  const inventory = trackedFiles(projectDir);
+  const retired = readRetirementManifest(projectDir);
+  if (!inventory.ok || !retired.ok) {
+    return {
+      scanned: 0,
+      candidates: [],
+      coverage: {
+        status: 'unavailable',
+        reason: inventory.ok ? 'manifest-invalid' : inventory.reason,
+        error: inventory.error || retired.error,
+        unreadable: [],
+      },
+    };
+  }
+  const tracked = new Set(inventory.files);
+  const markdown = inventory.files.filter(path => /\.md$/i.test(path));
+  const candidates = [];
+  const unreadable = [];
+  let scanned = 0;
+  for (const path of retired.paths) {
+    if (existsSync(resolve(projectDir, path))) {
+      candidates.push({
+        code: 'DLC004',
+        path,
+        confidence: 'high',
+        status: 'retired',
+        reason: 'retirement manifest records this path but it remains in the working tree',
+      });
+    }
+  }
+  for (const path of markdown) {
+    if (EXCLUDED_PREFIXES.some(prefix => path === prefix || path.startsWith(`${prefix}/`))) continue;
+    if (shouldIgnore(path, config, 'documentLifecycle')) continue;
+    if (retired.paths.has(path) && !existsSync(resolve(projectDir, path))) continue;
+    let content;
+    try { content = readFileSync(resolve(projectDir, path), 'utf8'); } catch {
+      unreadable.push(path);
+      continue;
+    }
+    scanned++;
+    const status = parseLifecycleStatus(content);
+    const normalizedStatus = status?.trim().toLowerCase() || null;
+    if (normalizedStatus && RETIRED_STATUSES.has(normalizedStatus)) {
+      candidates.push({
+        code: 'DLC001',
+        path,
+        confidence: 'high',
+        status,
+        reason: `explicit lifecycle status: ${status}`,
+      });
+      continue;
+    }
+    if (normalizedStatus && COMPLETION_STATUSES.has(normalizedStatus)) {
+      candidates.push({
+        code: 'DLC002',
+        path: /(?:^|\/)spec\.md$/i.test(path) ? dirname(path) : path,
+        confidence: 'review',
+        status,
+        reason: `artifact maturity is ${status}; verify persistence policy and backreferences before retirement`,
+      });
+      continue;
+    }
+    if (path.startsWith('specs/') && /(?:^|\/)spec\.md$/i.test(path)) {
+      const tasks = completedTaskSignal(projectDir, path, content, tracked);
+      if (tasks) {
+        candidates.push({
+          code: 'DLC002',
+          path: dirname(path),
+          confidence: 'review',
+          status,
+          reason: `${tasks.checked} checked tasks and no open tasks; confirm the outcome is documented`,
+        });
+      }
+    }
+  }
+  return {
+    scanned,
+    candidates: [...new Map(candidates.map(candidate => [candidate.path, candidate])).values()]
+      .sort((a, b) => a.path.localeCompare(b.path)),
+    coverage: {
+      status: unreadable.length > 0 ? 'partial' : 'complete',
+      reason: unreadable.length > 0 ? 'unreadable-files' : null,
+      error: null,
+      unreadable,
+    },
+  };
+}

package/cli/scanners/requirement-evidence.mjs

@@ -0,0 +1,126 @@
+/** Pure requirement-reference evidence shared by validators and registry projections. */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { extname, resolve } from 'node:path';
+import { TEST_PATTERNS } from '../shared-trace-patterns.mjs';
+import { parseJsTs, walk } from './js-ast.mjs';
+
+export function isTestSource(file) {
+  return /\.(?:[cm]?[jt]sx?|py|go|rs|java|kt|rb|php|sh)$/.test(file)
+    && (TEST_PATTERNS.some(pattern => pattern.test(file)) || /(?:^|\/)(?:__tests__|tests?)\//.test(file));
+}
+
+export function resolveRequirementReferences(definitions, references, retiredDefinitions = new Set()) {
+  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);
+  }
+  for (const key of retiredDefinitions) {
+    const id = key.slice(key.lastIndexOf('#') + 1);
+    if (!byId.has(id)) byId.set(id, []);
+    if (!byId.get(id).includes(key)) byId.get(id).push(key);
+  }
+  const resolved = new Map();
+  for (const [id, refs] of references) {
+    const candidates = byId.get(id) || [];
+    for (const ref of refs) {
+      let key = null;
+      if (ref.scope) {
+        const direct = `${ref.scope}#${id}`;
+        if (definitions.has(direct)) key = direct;
+        else {
+          const aliases = candidates.filter(candidate => definitions.get(candidate)?.specId === ref.scope);
+          if (aliases.length === 1) key = aliases[0];
+        }
+      } else if (candidates.length === 1) key = candidates[0];
+      if (!key || !definitions.has(key)) continue;
+      if (!resolved.has(key)) resolved.set(key, []);
+      resolved.get(key).push(ref);
+    }
+  }
+  return resolved;
+}
+
+function testDeclarations(content, filename) {
+  const declarations = [];
+  const comment = (text, line) => {
+    for (const [offset, raw] of text.split('\n').entries()) {
+      const body = raw.replace(/^\s*\*?\s*/, '');
+      if (/^(?:@(?:req|task|covers)\s|Testing\s)/i.test(body)) declarations.push({ text: body, line: line + offset });
+    }
+  };
+  const labelName = /^(?:test|it|describe|context|specify|Run|DisplayName)$/;
+  const ext = extname(filename);
+  if (/^\.(?:[cm]?[jt]s|[jt]sx)$/.test(ext)) {
+    const { ast, ok } = parseJsTs(content, filename);
+    if (ok) {
+      for (const c of ast.comments || []) comment(c.value, c.loc.start.line);
+      const isLabelCall = callee => {
+        if (callee?.type === 'Identifier') return labelName.test(callee.name);
+        if (callee?.type !== 'MemberExpression' || callee.computed) return false;
+        return labelName.test(callee.property.name)
+          || (/^(?:only|skip|todo|concurrent|serial)$/.test(callee.property.name) && isLabelCall(callee.object));
+      };
+      walk(ast.program, node => {
+        if (node.type !== 'CallExpression' || !isLabelCall(node.callee)) return;
+        const label = node.arguments[0];
+        if (label?.type === 'StringLiteral' || (label?.type === 'TemplateLiteral' && label.expressions.length === 0)) {
+          declarations.push({ text: content.slice(label.start + 1, label.end - 1), line: label.loc.start.line });
+        }
+      });
+      return declarations.sort((a, b) => a.line - b.line);
+    }
+  }
+
+  const tokens = /\/\*[\s\S]*?(?:\*\/|$)|\/\/[^\n]*|\#[^\n]*|"""[\s\S]*?(?:"""|$)|'''[\s\S]*?(?:'''|$)|"(?:\\[\s\S]|[^"\\])*"|'(?:\\[\s\S]|[^'\\])*'|`(?:\\[\s\S]|[^`\\])*`/g;
+  const hashComments = /\.(?:py|rb|php|sh)$/.test(ext);
+  let end = 0;
+  let line = 1;
+  let code = '';
+  for (const token of content.matchAll(tokens)) {
+    const gap = content.slice(end, token.index);
+    line += (gap.match(/\n/g) || []).length;
+    code += gap;
+    const text = token[0];
+    if (text.startsWith('//') || text.startsWith('/*') || (hashComments && text.startsWith('#'))) {
+      comment(text.replace(/^(?:\/\/|\/\*|#)/, ''), line);
+    } else if (/^["'`]/.test(text)
+      && /\b(?:test|it|describe|context|specify|Run|DisplayName)(?:\.(?:only|skip|todo|concurrent|serial))*\s*\(?\s*$/.test(code)) {
+      declarations.push({ text: text.slice(1, -1), line });
+    }
+    line += (text.match(/\n/g) || []).length;
+    code = text.startsWith('/') || text.startsWith('#') ? code + ' ' : ';';
+    end = token.index + text.length;
+  }
+  return declarations;
+}
+
+export function scanTestFilesForReferences(projectDir, projectFiles, patterns) {
+  const testRefs = new Map();
+  for (const relPath of projectFiles.filter(isTestSource)) {
+    const fullPath = resolve(projectDir, relPath);
+    if (!existsSync(fullPath)) continue;
+    let content;
+    try { content = readFileSync(fullPath, 'utf8'); } catch { continue; }
+    const hasMatch = patterns.some(pattern => { pattern.lastIndex = 0; return pattern.test(content); });
+    if (!hasMatch) continue;
+    for (const declaration of testDeclarations(content, relPath)) {
+      for (const pattern of patterns) {
+        pattern.lastIndex = 0;
+        let match;
+        while ((match = pattern.exec(declaration.text)) !== null) {
+          if (!match[0]) { pattern.lastIndex++; continue; }
+          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;
+          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 });
+        }
+      }
+    }
+  }
+  return testRefs;
+}