docguard-cli 0.39.0 → 0.40.1

package/cli/commands/score.mjs

@@ -1,5 +1,6 @@
 import { applyDocRoles, remapDocPath, resolveDocRole } from '../shared-doc-roles.mjs';
 /**
+ * @implements docguard.evidence-scoped-verification#FR-012
  * Score Command — Calculate CDD maturity score (0-100)
  * Shows category breakdown with weighted scoring.
  */
@@ -14,6 +15,7 @@ import { extractSemanticClaims } from '../scanners/semantic-claims.mjs';
 import { assessAgentReadability } from '../scanners/agent-readability.mjs';
 import { loadHistory, sparkline } from '../writers/history.mjs';
 import { listCanonicalDocs } from '../shared-ignore.mjs';
+import { coverSemanticClaims, evaluateEvidence } from '../evidence/evaluate.mjs';
 
 /**
  * Detect whether the project configures a test runner (the "Check 3" of the
@@ -415,11 +417,21 @@ export function runScoreInternal(projectDir, config) {
 /** Evidence boundary shared by human, CI, report, and MCP score consumers. */
 export function buildScoreAssurance(projectDir, config) {
   let unverifiedClaims = null;
-  try { unverifiedClaims = extractSemanticClaims(projectDir, config).length; } catch { /* unknown, never zero on failure */ }
+  let declaredEvidence = null;
+  try {
+    const claims = extractSemanticClaims(projectDir, config);
+    const evaluated = evaluateEvidence(projectDir, config);
+    unverifiedClaims = coverSemanticClaims(claims, evaluated).unverified;
+  } catch { /* unknown, never zero on failure */ }
+  try {
+    const evaluated = evaluateEvidence(projectDir, config);
+    declaredEvidence = { configured: evaluated.exists, status: evaluated.status, summary: evaluated.summary };
+  } catch { /* unknown, never clean on failure */ }
   return {
     status: 'unverified',
     factualAccuracy: null,
     unverifiedClaims,
+    declaredEvidence,
     limitation: 'Structural maturity is not factual accuracy. Claim discovery is heuristic; uncaptured prose remains unverified.',
   };
 }

package/cli/commands/sync.mjs

@@ -1,4 +1,4 @@
-import { assertDefaultDocWrites } from '../shared-doc-roles.mjs';
+import { isMappedDocPath } from '../shared-doc-roles.mjs';
 /**
  * Sync Command — keep the documentation memory ALWAYS UP TO DATE.
  *
@@ -15,12 +15,13 @@ import { assertDefaultDocWrites } from '../shared-doc-roles.mjs';
  * @implements docguard.document-lifecycle#FR-010
  */
 
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { c } from '../shared.mjs';
 import { buildMemoryPlan } from '../scanners/memory-plan.mjs';
-import { getSection, replaceSection } from '../writers/sections.mjs';
+import { assertOwnedCodeSection, getSection, inspectSections, replaceSection } from '../writers/sections.mjs';
+import { safeWrite } from '../writers/generate-io.mjs';
 import { hasGeneratedMarker } from '../writers/api-reference.mjs';
 import { runSyncTests } from './sync-tests.mjs';
 import { sectionTouchedByChanges } from '../shared-sync-scope.mjs';
@@ -48,7 +49,6 @@ function gitChangedFiles(projectDir, since) {
  */
 
 export function runSync(projectDir, config, flags) {
-  if (flags.write) assertDefaultDocWrites(config);
   // v0.28 (field report #10): `--tests` reconciles the hand-maintained TEST-SPEC
   // Source-to-Test Map from disk (ghost-source removal + new co-located pairs) —
   // a distinct path from the generated code-truth section refresh below.
@@ -62,6 +62,7 @@ export function runSync(projectDir, config, flags) {
   const updates = [];   // { doc, section, status }
   const reviews = [];   // { doc, section, reason }
   const skipped = [];   // { doc, reason }
+  const pendingWrites = [];
 
   for (const doc of plan.docs) {
     const full = resolve(projectDir, doc.path);
@@ -70,7 +71,11 @@ export function runSync(projectDir, config, flags) {
       continue;
     }
     let content = readFileSync(full, 'utf-8');
-    if (!hasGeneratedMarker(content) && !flags.force) {
+    const mapped = isMappedDocPath(config, doc.path);
+    if (apply && mapped && inspectSections(content).issues.length) {
+      throw new Error(`${doc.path}: malformed or duplicate docguard:section markers; no write was applied.`);
+    }
+    if (!hasGeneratedMarker(content) && !flags.force && !mapped) {
       skipped.push({ doc: doc.path, reason: 'not marked docguard:generated (use --force to sync anyway)' });
       continue;
     }
@@ -98,7 +103,11 @@ export function runSync(projectDir, config, flags) {
       }
       codeSectionChanged = true;
       updates.push({ doc: doc.path, section: sec.id, status: apply ? 'updated' : 'stale' });
-      if (apply) { content = replaceSection(content, sec.id, sec.body).content; docChanged = true; }
+      if (apply) {
+        if (mapped) assertOwnedCodeSection(content, sec.id, doc.path);
+        content = replaceSection(content, sec.id, sec.body).content;
+        docChanged = true;
+      }
     }
 
     // If code changed, the prose around it may need an agent's eyes.
@@ -110,9 +119,13 @@ export function runSync(projectDir, config, flags) {
       }
     }
 
-    if (apply && docChanged) writeFileSync(full, content, 'utf-8');
+    if (apply && docChanged) pendingWrites.push({ full, content });
   }
 
+  // Authorization for every mapped target completed above. Only now expose
+  // writes, preserving backup behavior for both default and mapped layouts.
+  for (const pending of pendingWrites) safeWrite(pending.full, pending.content);
+
   const result = {
     project: config.projectName,
     since: flags.since || null,

package/cli/commands/verify.mjs

@@ -20,6 +20,7 @@
  * text is the human summary.
  *
  *   docguard verify [--semantic | --instructions] [--format json]
+ * @implements docguard.evidence-scoped-verification#FR-009
  */
 
 import { basename } from 'node:path';
@@ -29,6 +30,7 @@ import { extractSemanticClaims, buildSemanticVerifyTasks } from '../scanners/sem
 import { auditInstructions } from '../scanners/instruction-audit.mjs';
 import { isGitRepo, getDiffText } from '../shared-git.mjs';
 import { parseUnifiedDiff, activityLabeledDiff } from '../shared-diff.mjs';
+import { coverSemanticClaims, evaluateEvidence } from '../evidence/evaluate.mjs';
 
 const CHANGE_CODE_EXT = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|cs|swift|scala|dart)$/;
 
@@ -68,14 +70,30 @@ function taskTouchesChange(task, changedSet, changedBasenames) {
 }
 
 export function runVerify(projectDir, config, flags) {
+  const selectedModes = ['semantic', 'instructions', 'evidence'].filter(mode => flags[mode]);
+  if (selectedModes.length > 1) {
+    const message = `Choose exactly one verify mode; --${selectedModes.join(', --')} cannot be combined.`;
+    if (flags.format === 'json') {
+      console.log(JSON.stringify({ command: 'verify', status: 'error', error: { code: 'VERIFY_MODE_CONFLICT', message } }, null, 2));
+    } else {
+      console.error(`${c.red}Error: ${message}${c.reset}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
   if (flags.instructions) {
     runInstructionAudit(projectDir, config, flags);
     return;
   }
+  if (flags.evidence) {
+    runEvidenceVerification(projectDir, config, flags);
+    return;
+  }
 
   const isJson = flags.format === 'json';
   const claims = extractSemanticClaims(projectDir, config);
-  const tasks = buildSemanticVerifyTasks(claims);
+  const evidenceCoverage = coverSemanticClaims(claims, evaluateEvidence(projectDir, config));
+  const tasks = buildSemanticVerifyTasks(evidenceCoverage.remaining);
 
   // Change-aware staging (feat 6): if --since given, attach the structured diff
   // and flag which claims are about just-changed code (verify those first).
@@ -92,6 +110,9 @@ export function runVerify(projectDir, config, flags) {
     console.log(JSON.stringify({
       command: 'verify --semantic',
       project: config.projectName,
+      discoveredClaimCount: evidenceCoverage.total,
+      verifiedWithinScope: evidenceCoverage.verifiedWithinScope,
+      coveredClaimIds: evidenceCoverage.covered,
       claimCount: tasks.length,
       // How to act on this: each task is a claim to confirm against the code.
       howToVerify: changeContext
@@ -107,7 +128,10 @@ export function runVerify(projectDir, config, flags) {
   console.log(`${c.dim}   ${config.projectName} · documented numbers / limits / enums to check against code${c.reset}\n`);
 
   if (tasks.length === 0) {
-    console.log(`  ${c.green}✅ No semantic claims found in the canonical docs.${c.reset}`);
+    const message = evidenceCoverage.total > 0
+      ? `${evidenceCoverage.verifiedWithinScope} discovered claim(s) are already covered by unique current evidence declarations.`
+      : 'No semantic claims found in the canonical docs.';
+    console.log(`  ${c.green}✅ ${message}${c.reset}`);
     console.log(`  ${c.dim}(Looks for numbers with units — days/ms/req-s/GSIs/roles/… — and status/enum lists.)${c.reset}\n`);
     return;
   }
@@ -120,6 +144,9 @@ export function runVerify(projectDir, config, flags) {
   }
 
   console.log(`  ${c.yellow}${tasks.length} claim(s) to verify against the code:${c.reset}\n`);
+  if (evidenceCoverage.verifiedWithinScope > 0) {
+    console.log(`  ${c.green}✓ ${evidenceCoverage.verifiedWithinScope} additional discovered claim(s) have unique verified-within-scope declarations.${c.reset}\n`);
+  }
   if (changeContext) {
     const nChanged = tasks.filter(t => t.aboutChangedCode).length;
     console.log(`  ${c.cyan}⚡ ${nChanged} claim(s) are about code changed since ${flags.since}${c.reset} ${c.dim}— verify these first (structured diff in --format json).${c.reset}\n`);
@@ -140,6 +167,42 @@ export function runVerify(projectDir, config, flags) {
   console.log(`  ${c.dim}Get the machine task list: ${c.cyan}${cmd}${c.dim}, then read each cited file and confirm the value.${c.reset}\n`);
 }
 
+function runEvidenceVerification(projectDir, config, flags) {
+  const evaluation = evaluateEvidence(projectDir, config);
+  if (flags.format === 'json') {
+    console.log(JSON.stringify(evaluation, null, 2));
+    return;
+  }
+  console.log(`${c.bold}🔬 DocGuard Verify — declared evidence${c.reset}`);
+  console.log(`${c.dim}   ${config.projectName} · exact statement-to-source checks${c.reset}\n`);
+  if (!evaluation.exists) {
+    console.log(`  ${c.dim}No .docguard-evidence.json manifest is configured.${c.reset}`);
+    console.log(`  ${c.dim}Start from templates/evidence-manifest.json; heuristic discovery remains available with docguard verify --semantic.${c.reset}\n`);
+    return;
+  }
+  if (evaluation.errors.length) {
+    console.log(`  ${c.red}Invalid evidence manifest:${c.reset}`);
+    for (const error of evaluation.errors) console.log(`    ${c.red}✗${c.reset} ${error.message}`);
+    console.log('');
+    return;
+  }
+  const symbols = {
+    'verified-within-scope': `${c.green}✓${c.reset}`,
+    contradicted: `${c.red}✗${c.reset}`,
+    stale: `${c.yellow}↻${c.reset}`,
+    inconclusive: `${c.yellow}?${c.reset}`,
+    unsupported: `${c.yellow}◇${c.reset}`,
+  };
+  for (const state of ['contradicted', 'stale', 'inconclusive', 'unsupported', 'verified-within-scope']) {
+    const results = evaluation.results.filter(result => result.state === state);
+    if (!results.length) continue;
+    console.log(`  ${c.bold}${state}${c.reset} (${results.length})`);
+    for (const result of results) console.log(`    ${symbols[state]} ${result.declarationId} · ${result.location} · ${result.message}`);
+    console.log('');
+  }
+  console.log(`  ${c.dim}${evaluation.scopeLimitation}${c.reset}\n`);
+}
+
 // ── verify --instructions: agent-instruction drift/conflict audit ───────────
 
 function runInstructionAudit(projectDir, config, flags) {

package/cli/config.mjs

@@ -1,6 +1,7 @@
 import { hasWorkerConfig } from './shared-source.mjs';
 import { applyDocRoles } from './shared-doc-roles.mjs';
 /**
+ * @implements docguard.evidence-scoped-verification#FR-010
  * DocGuard — configuration loading.
  *
  * Extracted from docguard.mjs (v0.23.0) to break the demo.mjs → docguard.mjs
@@ -81,6 +82,7 @@ export function loadConfig(projectDir) {
       freshness: true,
       documentLifecycle: true,
       specRegistry: true,
+      evidence: 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
@@ -225,6 +227,7 @@ const _KNOWN_VALIDATORS = [
   'apiSurface', 'metadataSync', 'docsCoverage', 'docQuality', 'todoTracking',
   'schemaSync', 'specKit', 'crossReference', 'generatedStaleness',
   'canonicalSync', 'surfaceSync', 'metricsConsistency',
+  'evidence',
 ];
 
 function _kebabToCamel(k) {

package/cli/docguard.mjs

@@ -57,6 +57,7 @@ import { runArchive } from './commands/retire.mjs';
 import { runSpecs } from './commands/specs.mjs';
 import { runReconcile } from './commands/reconcile.mjs';
 import { ensureSkills } from './ensure-skills.mjs';
+import { detectRepositoryRootGuidance, renderRepositoryRootGuidance } from './repository-root.mjs';
 
 // ── Shared constants (imported to break circular dependencies) ──────────
 import { c, PROFILES } from './shared.mjs';
@@ -94,9 +95,9 @@ ${c.bold}Tools (situational, but day-to-day useful)${c.reset}
   ${c.green}diagnose${c.reset}   AI orchestrator — guard → emit fix prompts in one command
   ${c.green}fix${c.reset}        Generate AI fix instructions for specific docs
   ${c.green}generate${c.reset}   Reverse-engineer canonical docs from existing code (${c.cyan}--plan${c.reset} for AI scan)
-  ${c.green}agent${c.reset}      One-shot agent task graph — ordered tasks, pre-filled code-truth, per-task verify (${c.cyan}--format json${c.reset})
+  ${c.green}agent${c.reset}      Agent task graph or bounded task context (${c.cyan}--task <text>${c.reset}, ${c.cyan}--format json${c.reset})
   ${c.green}explain${c.reset}    Explain a validator key, warning text, or finding code (${c.cyan}docguard explain SEC001${c.reset})
-  ${c.green}verify${c.reset}     Extract documented numbers/limits/enums for an agent to check vs code (${c.cyan}--semantic${c.reset})
+  ${c.green}verify${c.reset}     Check declared local evidence or extract claims for review (${c.cyan}--evidence${c.reset}, ${c.cyan}--semantic${c.reset})
   ${c.green}feedback${c.reset}   Report likely false positives back to DocGuard (local-first + 1-click prefilled issue)
   ${c.green}mcp${c.reset}        MCP server over stdio — guard/score/explain/verify/report/diagnose as agent tools
   ${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})
@@ -125,7 +126,7 @@ ${c.bold}Deprecation aliases${c.reset} ${c.dim}— supported until v1.0 with a y
   ${c.dim}Run the legacy form to see its replacement.${c.reset}
 
 ${c.bold}Options:${c.reset}
-  --dir <path>    Project directory (default: current directory)
+  --dir <path>    Project directory (default: current directory; explicit paths suppress ancestor-root guidance)
   --verbose       Show detailed output
   --format json   Output results as JSON (for CI)
   --fix           Auto-create missing files from templates
@@ -138,7 +139,8 @@ ${c.bold}Options:${c.reset}
   --fail-on-warning  Fail CI on warnings (used with ci command)
   --auto          Auto-fix what's possible (used with fix command)
   --write         Apply a command's explicit deterministic write path. For fix,
-                  only edits docguard:generated docs unless --force; specs
+                  mapped human docs require unique source=code ownership and
+                  --force cannot grant ownership; 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 +
@@ -213,13 +215,14 @@ const COMMAND_HELP = {
     examples: ['docguard generate', 'docguard generate --plan', 'docguard generate --plan --write', 'docguard generate --plan --format json'],
   },
   agent: {
-    summary: 'One-shot agent task graph: ordered, dependency-aware, with pre-filled code-truth + per-task verify.',
-    usage: 'docguard agent [--profile <name>] [--format json]',
+    summary: 'Agent task graph, or a bounded evidence packet for one explicit task.',
+    usage: 'docguard agent [--task <text>] [--profile <name>] [--format json]',
     flags: [
-      ['--format json', 'Machine-readable task graph (the agent-executable artifact)'],
+      ['--task <text>', 'Select current task-linked requirements and evidence; abstain when relevance is weak'],
+      ['--format json', 'Machine-readable task graph or deterministic task packet'],
       ['--profile <name>', 'Preview a profile (cli/library/standard/…) without running init first'],
     ],
-    examples: ['docguard agent', 'docguard agent --format json', 'docguard agent --profile cli --format json'],
+    examples: ['docguard agent', 'docguard agent --task "Fix SEC001 in src/config.mjs"', 'docguard agent --task "Implement acme.feature#FR-001" --format json'],
   },
   guard: {
     summary: 'Validate code against canonical docs (all validators).',
@@ -307,14 +310,15 @@ const COMMAND_HELP = {
     examples: ['docguard feedback', 'docguard feedback --code TRC005 --preview', 'docguard feedback --fixture-manifest feedback.json --reduce --preview --format json'],
   },
   verify: {
-    summary: 'Extract the semantic claims in your canonical docs — documented numbers, limits, and enums (retention days, rate limits, GSI/role counts, status enums) — as a verification task list the agent checks against the code. This is the highest-value bug class (a doc value that drifted from code) and the one regex/AST cannot judge. DocGuard finds the claims; the LLM confirms them.',
-    usage: 'docguard verify [--semantic|--instructions] [--format json]',
+    summary: 'Verify exact declared evidence, extract heuristic semantic claims, or audit agent instructions.',
+    usage: 'docguard verify [--evidence|--semantic|--instructions] [--format json]',
     flags: [
+      ['--evidence', 'Evaluate `.docguard-evidence.json` using local bounded JSON, collection, oasdiff, and Buf evidence'],
       ['--semantic', 'Extract documented numbers/limits/enums to verify against code (the current — and default — mode)'],
       ['--instructions', 'Audit AGENTS.md/CLAUDE.md for duplicate, contradictory, and stale-pointer rules (deterministic findings + agent conflict tasks)'],
       ['--format json', 'Machine-readable task list (the agent-executable artifact)'],
     ],
-    examples: ['docguard verify --semantic', 'docguard verify --semantic --format json'],
+    examples: ['docguard verify --evidence', 'docguard verify --evidence --format json', 'docguard verify --semantic --format json'],
   },
   retire: {
     summary: 'Remove reviewed docs from active AI context while preserving recovery from a retained Git ref.',
@@ -391,6 +395,7 @@ async function main() {
   // Parse flags
   const flags = {
     dir: '.',
+    dirExplicit: false,
     verbose: false,
     format: 'text',
     fix: false,
@@ -401,6 +406,7 @@ async function main() {
   for (let i = 1; i < args.length; i++) {
     if (args[i] === '--dir' && args[i + 1]) {
       flags.dir = args[i + 1];
+      flags.dirExplicit = true;
       i++;
     } else if (args[i] === '--verbose') {
       flags.verbose = true;
@@ -438,6 +444,8 @@ async function main() {
       // v0.28 (field report #5): `docguard verify --semantic` extracts
       // documented numbers/enums/limits for the agent to check against code.
       flags.semantic = true;
+    } else if (args[i] === '--evidence') {
+      flags.evidence = true;
     } else if (args[i] === '--instructions') {
       // v0.30: `docguard verify --instructions` audits AGENTS.md/CLAUDE.md for
       // duplicate/contradictory/stale rules (MemoryLint-inspired).
@@ -544,6 +552,8 @@ async function main() {
       // v0.21: `docguard demo --keep` doesn't delete the temp fixture after
       // running (useful for poking around what DocGuard set up).
       flags.keep = true;
+    } else if (args[i] === '--task') {
+      flags.task = args[i + 1] && !args[i + 1].startsWith('--') ? args[++i] : '';
     } else if (!args[i].startsWith('--') && i > 0) {
       // Positional args go into flags.args for commands that take them (e.g.
       // `docguard trace --reverse <path>`). Skip the command itself (i === 0).
@@ -696,8 +706,18 @@ async function main() {
 
   if (!headless) printBanner();
 
+  const rootGuidance = detectRepositoryRootGuidance(projectDir, {
+    explicitDir: flags.dirExplicit,
+    argv: args,
+  });
+  if (rootGuidance) {
+    process.stderr.write(renderRepositoryRootGuidance(rootGuidance, { machine: jsonMode }) + '\n');
+  }
   const config = loadConfig(projectDir);
-  if (['init', 'setup', 'generate'].includes(command) && !(command === 'generate' && flags.plan && !flags.write) || ['sync', 'fix'].includes(command) && flags.write || command === 'diagnose' && flags.auto) assertDefaultDocWrites(config);
+  // Init and diagnose --auto can scaffold several unrelated files and retain
+  // their legacy default-layout contract. Generate, sync, and fix perform their
+  // own target/section authorization so mapped layouts can use bounded writers.
+  if (['init', 'setup'].includes(command) || command === 'diagnose' && flags.auto) assertDefaultDocWrites(config);
 
   // `--no-baseline` disables the committed adoption baseline for this run —
   // threaded through config so guard, ci, report, and mcp all honor it the
@@ -839,6 +859,7 @@ async function main() {
     case 'agent':
       // v0.26 (field report §2): one-shot, dependency-ordered task graph with
       // pre-filled code-truth + per-task verify. Read-only; JSON by default.
+      // @implements docguard.task-specific-agent-context#FR-010
       runAgent(projectDir, config, flags);
       break;
     case 'hooks':

package/cli/evidence/adapters.mjs

@@ -0,0 +1,200 @@
+/**
+ * File-only source adapters for evidence-scoped verification.
+ * @implements docguard.evidence-scoped-verification#FR-002
+ * @implements docguard.evidence-scoped-verification#FR-003
+ * @implements docguard.evidence-scoped-verification#FR-004
+ * @implements docguard.evidence-scoped-verification#FR-005
+ */
+
+import { lstatSync, readdirSync, realpathSync } from 'node:fs';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { buildIgnoreFilter, compileGlob, DEFAULT_IGNORE_DIRS, relPosix } from '../shared-ignore.mjs';
+
+const MAX_COLLECTION_FILES = 20_000;
+const MAX_REPORT_FINDINGS = 10_000;
+const OASDIFF_LEVELS = new Set(['ERR', 'WARN', 'INFO', 'NONE']);
+
+const answer = (status, reasonCode, message, extra = {}) => ({ ...extra, status, reasonCode, message });
+
+export function resolveJsonPointer(value, pointer) {
+  if (pointer === '') return { found: true, value };
+  if (typeof pointer !== 'string' || !pointer.startsWith('/')) return { found: false, reason: 'invalid-json-pointer' };
+  let current = value;
+  for (const raw of pointer.slice(1).split('/')) {
+    if (/~(?:[^01]|$)/.test(raw)) return { found: false, reason: 'invalid-json-pointer-escape' };
+    const token = raw.replace(/~1/g, '/').replace(/~0/g, '~');
+    if (Array.isArray(current)) {
+      if (!/^(?:0|[1-9][0-9]*)$/.test(token)) return { found: false, reason: 'invalid-array-index' };
+      const index = Number(token);
+      if (!Number.isSafeInteger(index) || index >= current.length) return { found: false, reason: 'unresolved-json-pointer' };
+      current = current[index];
+    } else if (current && typeof current === 'object' && Object.hasOwn(current, token)) {
+      current = current[token];
+    } else {
+      return { found: false, reason: 'unresolved-json-pointer' };
+    }
+  }
+  return { found: true, value: current };
+}
+
+function lexicalBase(pattern) {
+  const parts = [];
+  for (const part of pattern.split('/')) {
+    if (/[*?{]/.test(part)) break;
+    parts.push(part);
+  }
+  return parts.join('/') || '.';
+}
+
+/** Count regular, non-symlink files with a bounded walk and the shared ignore contract. */
+export function countEvidenceCollection(projectDir, pattern, config = {}) {
+  if (typeof pattern !== 'string' || pattern.startsWith('/') || /[\\:\0]/.test(pattern)
+    || pattern.split('/').some(part => part === '..' || part.toLowerCase() === '.local' || /^\.env(?:\.|$)/i.test(part))) {
+    return answer('inconclusive', 'unsafe-collection-base', 'Collection pattern is unsafe.');
+  }
+  let root;
+  try { root = realpathSync(projectDir); } catch { return answer('inconclusive', 'repository-unavailable', 'Repository root is unavailable.'); }
+  let matcher;
+  try { matcher = compileGlob(pattern); } catch { return answer('unsupported', 'unsupported-glob', 'Collection glob cannot be compiled.'); }
+  const ignored = buildIgnoreFilter(config.ignore || []);
+  const lexical = lexicalBase(pattern);
+  let base = root;
+  try {
+    for (const part of lexical.split('/').filter(item => item && item !== '.')) {
+      base = resolve(base, part);
+      if (lstatSync(base).isSymbolicLink()) return answer('inconclusive', 'symlink', 'Collection base traverses a symlink.');
+    }
+  } catch (error) {
+    if (error?.code === 'ENOENT') return answer('ok', 'collection-read', 'Collection evaluated.', { value: 0, inputHashes: [] });
+    return answer('inconclusive', 'collection-unavailable', 'Collection base is unavailable.');
+  }
+  const relBase = relative(root, base);
+  if (isAbsolute(relBase) || relBase === '..' || relBase.startsWith(`..${sep}`)) {
+    return answer('inconclusive', 'unsafe-collection-base', 'Collection base leaves the repository.');
+  }
+  let baseStat;
+  try { baseStat = lstatSync(base); } catch (error) {
+    if (error?.code === 'ENOENT') return answer('ok', 'collection-read', 'Collection evaluated.', { value: 0, inputHashes: [] });
+    return answer('inconclusive', 'collection-unavailable', 'Collection base is unavailable.');
+  }
+  if (baseStat.isSymbolicLink()) return answer('inconclusive', 'symlink', 'Collection base is a symlink.');
+  let visited = 0;
+  let matched = 0;
+  const walk = path => {
+    let entries;
+    try { entries = readdirSync(path, { withFileTypes: true }); }
+    catch { throw new Error('collection-unreadable'); }
+    for (const entry of entries) {
+      if (++visited > MAX_COLLECTION_FILES) throw new Error('collection-budget');
+      if (DEFAULT_IGNORE_DIRS.has(entry.name) || entry.name.startsWith('.')) continue;
+      const full = resolve(path, entry.name);
+      const rel = relPosix(root, full);
+      if (ignored(rel)) continue;
+      let stat;
+      try { stat = lstatSync(full); } catch { throw new Error('collection-unreadable'); }
+      if (stat.isSymbolicLink()) continue;
+      if (stat.isDirectory()) walk(full);
+      else if (stat.isFile() && matcher.test(rel)) matched++;
+    }
+  };
+  try {
+    if (baseStat.isFile()) matched = matcher.test(relPosix(root, base)) ? 1 : 0;
+    else if (baseStat.isDirectory()) walk(base);
+    else return answer('inconclusive', 'collection-not-file-or-directory', 'Collection base is not a regular file or directory.');
+  } catch (error) {
+    return answer('inconclusive', error.message, error.message === 'collection-budget'
+      ? `Collection exceeded the ${MAX_COLLECTION_FILES}-entry budget.`
+      : 'Collection could not be read completely.');
+  }
+  return answer('ok', 'collection-read', 'Collection evaluated.', { value: matched, inputHashes: [] });
+}
+
+function currentInputs(source, read) {
+  const hashes = [];
+  for (const input of source.inputs) {
+    const snapshot = read(input.path);
+    if (snapshot.content === null) {
+      return answer('inconclusive', `input-${snapshot.evidence.reason}`, `Cannot safely read declared input ${input.path}.`, { inputHashes: hashes });
+    }
+    hashes.push({ path: input.path, declared: input.sha256, current: snapshot.evidence.hash });
+  }
+  const stale = hashes.filter(input => input.declared !== input.current);
+  if (stale.length) return answer('stale', 'input-digest-mismatch', `${stale.length} declared input digest(s) no longer match.`, { inputHashes: hashes });
+  return answer('ok', 'inputs-current', 'Declared report inputs are current.', { inputHashes: hashes });
+}
+
+function readReport(source, read) {
+  if (source.adapterVersion !== 1) return answer('unsupported', 'adapter-version', `Adapter version ${source.adapterVersion} is unsupported.`);
+  const inputs = currentInputs(source, read);
+  if (inputs.status !== 'ok') return inputs;
+  const snapshot = read(source.path);
+  if (snapshot.content === null) {
+    return answer('inconclusive', `report-${snapshot.evidence.reason}`, `Cannot safely read saved ${source.adapter} report ${source.path}.`, { inputHashes: inputs.inputHashes });
+  }
+  return answer('ok', 'report-read', 'Saved report is current and readable.', {
+    content: snapshot.content,
+    sourceEvidence: snapshot.evidence,
+    inputHashes: inputs.inputHashes,
+  });
+}
+
+function oasdiffReport(source, read) {
+  if (!['breaking', 'changelog'].includes(source.command)) return answer('unsupported', 'oasdiff-command', `oasdiff command ${source.command} is unsupported.`);
+  const report = readReport(source, read);
+  if (report.status !== 'ok') return report;
+  let parsed;
+  try { parsed = JSON.parse(report.content); }
+  catch { return answer('inconclusive', 'malformed-oasdiff-json', 'Saved oasdiff report is not valid JSON.', report); }
+  if (!Array.isArray(parsed) || parsed.length > MAX_REPORT_FINDINGS) {
+    return answer('unsupported', 'unsupported-oasdiff-shape', 'Saved oasdiff report must be a bounded JSON array.', report);
+  }
+  const valid = parsed.every(change => change && typeof change === 'object' && !Array.isArray(change)
+    && typeof change.id === 'string' && change.id.length > 0
+    && (typeof change.level === 'number' || OASDIFF_LEVELS.has(change.level)));
+  if (!valid) return answer('unsupported', 'unsupported-oasdiff-change', 'Saved oasdiff report contains an unknown change shape.', report);
+  return answer('ok', 'oasdiff-report', 'Saved oasdiff report evaluated.', { ...report, value: parsed.length });
+}
+
+function bufReport(source, read) {
+  if (source.command !== 'breaking') return answer('unsupported', 'buf-command', `Buf command ${source.command} is unsupported.`);
+  const report = readReport(source, read);
+  if (report.status !== 'ok') return report;
+  const lines = report.content.split(/\r?\n/).filter(line => line.trim());
+  if (lines.length > MAX_REPORT_FINDINGS) return answer('unsupported', 'buf-finding-budget', `Saved Buf report exceeds ${MAX_REPORT_FINDINGS} findings.`, report);
+  for (const line of lines) {
+    let finding;
+    try { finding = JSON.parse(line); }
+    catch { return answer('inconclusive', 'malformed-buf-jsonl', 'Saved Buf report contains malformed JSON Lines.', report); }
+    if (!finding || typeof finding !== 'object' || Array.isArray(finding)
+      || typeof finding.path !== 'string' || !finding.path
+      || typeof finding.type !== 'string' || !finding.type
+      || typeof finding.message !== 'string' || !finding.message) {
+      return answer('unsupported', 'unsupported-buf-finding', 'Saved Buf report contains an unknown violation shape.', report);
+    }
+  }
+  return answer('ok', 'buf-report', 'Saved Buf report evaluated.', { ...report, value: lines.length });
+}
+
+export function readEvidenceSource(projectDir, declaration, read, config = {}) {
+  const source = declaration.source;
+  if (source.adapter === 'json-pointer') {
+    const snapshot = read(source.path);
+    if (snapshot.content === null) return answer('inconclusive', `source-${snapshot.evidence.reason}`, `Cannot safely read JSON source ${source.path}.`);
+    let parsed;
+    try { parsed = JSON.parse(snapshot.content); }
+    catch { return answer('inconclusive', 'malformed-source-json', `JSON source ${source.path} is malformed.`, { sourceEvidence: snapshot.evidence, inputHashes: [] }); }
+    const selected = resolveJsonPointer(parsed, source.pointer);
+    if (!selected.found) return answer('inconclusive', selected.reason, `JSON Pointer ${source.pointer || '<root>'} did not resolve.`, { sourceEvidence: snapshot.evidence, inputHashes: [] });
+    return answer('ok', 'json-pointer-resolved', 'JSON Pointer resolved.', { value: selected.value, sourceEvidence: snapshot.evidence, inputHashes: [] });
+  }
+  if (source.adapter === 'collection-count') {
+    const result = countEvidenceCollection(projectDir, source.glob, config);
+    if (result.status === 'ok' && result.value === 0 && !source.allowEmpty) {
+      return answer('inconclusive', 'empty-collection-not-allowed', 'Collection matched no files and allowEmpty is false.', result);
+    }
+    return result;
+  }
+  if (source.adapter === 'oasdiff') return oasdiffReport(source, read);
+  if (source.adapter === 'buf') return bufReport(source, read);
+  return answer('unsupported', 'unsupported-adapter', `Adapter ${source.adapter} is unsupported.`);
+}