docguard-cli 0.38.0 → 0.40.0

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).',
@@ -301,20 +304,21 @@ const COMMAND_HELP = {
     examples: ['docguard memory', 'docguard memory --diff'],
   },
   feedback: {
-    summary: 'Review detection feedback locally. Select any finding with --code or --all, check duplicates, and prepare a metadata-only issue URL. Nothing is submitted automatically.',
-    usage: 'docguard feedback [--code <CODE> | --all] [--preview] [--format json]',
-    flags: [['--code <CODE>', 'Select a finding regardless of confidence'], ['--all', 'Select every active finding'], ['--preview', 'Skip local feedback-record writes'], ['--format json', 'Machine-readable selected findings and issue/search URLs']],
-    examples: ['docguard feedback', 'docguard feedback --code TRC005 --preview', 'docguard feedback --all --format json'],
+    summary: 'Review detection feedback locally, or validate and reduce a synthetic fixture manifest. Duplicate searches cover open and closed work; nothing is submitted automatically.',
+    usage: 'docguard feedback [--code <CODE> | --all] [--classification <class>] [--fixture-manifest <path> [--reduce] [--contribution <path>]] [--preview] [--format json]',
+    flags: [['--code <CODE>', 'Select a finding regardless of confidence'], ['--all', 'Select every active finding'], ['--classification <class>', 'false_positive, false_negative, unsupported_syntax, ambiguous, or policy_disagreement'], ['--fixture-manifest <path>', 'Validate a reviewed synthetic fixture and opposite control'], ['--reduce', 'Deterministically reduce a reproducing fixture'], ['--contribution <path>', 'Write a test-only contribution when required evidence is present'], ['--preview', 'Skip local writes and return contribution text inline'], ['--format json', 'Machine-readable evidence and issue/search URLs']],
+    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).
@@ -626,6 +636,17 @@ async function main() {
       flags.all = true;
     } else if (args[i] === '--preview') {
       flags.preview = true;
+    } else if (args[i] === '--classification' && args[i + 1]) {
+      flags.classification = args[i + 1].replaceAll('-', '_');
+      i++;
+    } else if (args[i] === '--fixture-manifest' && args[i + 1]) {
+      flags.fixtureManifest = args[i + 1];
+      i++;
+    } else if (args[i] === '--reduce') {
+      flags.reduce = true;
+    } else if (args[i] === '--contribution' && args[i + 1]) {
+      flags.contribution = args[i + 1];
+      i++;
     } else if (args[i] === '--signals') {
       flags.signals = true;
     } else if (args[i] === '--debate') {
@@ -685,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
@@ -828,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.`);
+}

package/cli/evidence/evaluate.mjs

@@ -0,0 +1,185 @@
+/**
+ * Five-state evidence evaluation and stable identities.
+ * @implements docguard.evidence-scoped-verification#FR-007
+ * @implements docguard.evidence-scoped-verification#FR-008
+ * @implements docguard.evidence-scoped-verification#FR-010
+ * @implements docguard.evidence-scoped-verification#FR-011
+ * @implements docguard.evidence-scoped-verification#FR-012
+ */
+
+import { createEvidenceReader, contentHash } from '../scanners/semantic-claims.mjs';
+import { loadEvidenceManifest } from './manifest.mjs';
+import { readEvidenceSource } from './adapters.mjs';
+import { parseDocumentValue, selectMarkdownStatement } from './markdown.mjs';
+
+export const EVIDENCE_SCOPE_LIMITATION = 'Verification applies only to the declared Markdown statement, source adapter, predicate, producer metadata, and captured local inputs. It does not establish whole-document, runtime, deployment, or compliance accuracy.';
+export const EVIDENCE_STATES = ['verified-within-scope', 'contradicted', 'stale', 'inconclusive', 'unsupported'];
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])]));
+  }
+  return value;
+}
+
+function identity(prefix, value) {
+  return `${prefix}.${contentHash(JSON.stringify(canonical(value))).slice(7)}`;
+}
+
+function resultState(declaration, selection, source, state, reasonCode, message, extra = {}) {
+  const selectedStatement = selection?.statement || declaration.target.statement;
+  const claimId = identity('claim', {
+    declaration,
+    selectedStatement,
+    sourceValue: source?.value,
+    sourceEvidence: source?.sourceEvidence || null,
+    inputHashes: source?.inputHashes || [],
+  });
+  const evidencePayload = {
+    claimId,
+    sourceEvidence: source?.sourceEvidence || null,
+    inputHashes: source?.inputHashes || [],
+    sourceValue: source?.value,
+  };
+  return {
+    declarationId: declaration.id,
+    state,
+    claimId,
+    evidenceId: identity('evidence', evidencePayload),
+    document: declaration.target.document,
+    location: selection?.line ? `${declaration.target.document}:${selection.line}` : declaration.target.document,
+    heading: declaration.target.heading,
+    statement: selectedStatement,
+    adapter: declaration.source.adapter,
+    predicate: declaration.predicate.kind,
+    inputHashes: source?.inputHashes || [],
+    evidenceHash: source?.sourceEvidence?.hash || identity('snapshot', evidencePayload),
+    reasonCode,
+    message,
+    scopeLimitation: EVIDENCE_SCOPE_LIMITATION,
+    ...extra,
+  };
+}
+
+function compare(declaration, selection, source) {
+  const predicate = declaration.predicate;
+  if (predicate.kind === 'no-findings') {
+    return source.value === 0
+      ? { match: true, documentValue: null, sourceValue: 0 }
+      : { match: false, documentValue: null, sourceValue: source.value };
+  }
+  const document = parseDocumentValue(selection.value, predicate);
+  if (!document.ok) return { unsupported: false, inconclusive: true, ...document };
+  if (predicate.kind === 'equals') {
+    const expectedType = predicate.valueType;
+    const actualType = source.value === null ? 'null' : typeof source.value;
+    if (actualType !== expectedType || (actualType === 'number' && !Number.isFinite(source.value))) {
+      return { unsupported: true, reasonCode: 'source-type-mismatch', message: `JSON source type ${actualType} does not match declared ${expectedType}.` };
+    }
+    return { match: Object.is(document.value, source.value), documentValue: document.value, sourceValue: source.value };
+  }
+  if (predicate.kind === 'set-equals') {
+    if (!Array.isArray(source.value) || source.value.some(item => typeof item !== 'string')) {
+      return { unsupported: true, reasonCode: 'source-set-shape', message: 'JSON source must be an array of strings for set-equals.' };
+    }
+    if (new Set(source.value).size !== source.value.length) {
+      return { unsupported: true, reasonCode: 'duplicate-source-set-item', message: 'JSON source set contains duplicate items.' };
+    }
+    const left = [...document.value].sort();
+    const right = [...source.value].sort();
+    return { match: left.length === right.length && left.every((item, index) => item === right[index]), documentValue: document.value, sourceValue: source.value };
+  }
+  if (predicate.kind === 'count-equals') {
+    if (!Number.isSafeInteger(source.value) || source.value < 0) {
+      return { unsupported: true, reasonCode: 'source-count-shape', message: 'Collection source did not produce a non-negative safe integer.' };
+    }
+    return { match: document.value === source.value, documentValue: document.value, sourceValue: source.value };
+  }
+  return { unsupported: true, reasonCode: 'unsupported-predicate', message: `Predicate ${predicate.kind} is unsupported.` };
+}
+
+function evaluateDeclaration(projectDir, config, declaration, read) {
+  const document = read(declaration.target.document);
+  if (document.content === null) {
+    return resultState(declaration, null, document, 'inconclusive', `document-${document.evidence.reason}`, `Cannot safely read ${declaration.target.document}.`);
+  }
+  const selection = selectMarkdownStatement(document.content, declaration.target, declaration.predicate.kind);
+  if (selection.status !== 'ok') {
+    return resultState(declaration, selection, document, 'inconclusive', selection.reasonCode, selection.message);
+  }
+  const source = readEvidenceSource(projectDir, declaration, read, config);
+  if (source.status !== 'ok') {
+    return resultState(declaration, selection, source, source.status, source.reasonCode, source.message);
+  }
+  const compared = compare(declaration, selection, source);
+  if (compared.unsupported) return resultState(declaration, selection, source, 'unsupported', compared.reasonCode, compared.message);
+  if (compared.inconclusive) return resultState(declaration, selection, source, 'inconclusive', compared.reasonCode, compared.message);
+  const state = compared.match ? 'verified-within-scope' : 'contradicted';
+  const message = compared.match
+    ? 'The selected statement matches its current declared evidence.'
+    : 'The selected statement contradicts its current declared evidence.';
+  return resultState(declaration, selection, source, state, compared.match ? 'predicate-satisfied' : 'predicate-mismatch', message, {
+    documentValue: compared.documentValue,
+  });
+}
+
+export function evaluateEvidence(projectDir, config = {}) {
+  const read = createEvidenceReader(projectDir);
+  const loaded = loadEvidenceManifest(projectDir, read);
+  if (!loaded.exists) {
+    return {
+      command: 'verify --evidence', exists: false, manifest: '.docguard-evidence.json',
+      status: 'not-configured', errors: [], results: [], summary: Object.fromEntries(EVIDENCE_STATES.map(state => [state, 0])),
+      scopeLimitation: EVIDENCE_SCOPE_LIMITATION,
+    };
+  }
+  if (loaded.errors.length) {
+    return {
+      command: 'verify --evidence', exists: true, manifest: '.docguard-evidence.json',
+      status: 'invalid', manifestEvidence: loaded.evidence, errors: loaded.errors, results: [],
+      summary: Object.fromEntries(EVIDENCE_STATES.map(state => [state, 0])), scopeLimitation: EVIDENCE_SCOPE_LIMITATION,
+    };
+  }
+  const results = loaded.manifest.declarations.map(declaration => evaluateDeclaration(projectDir, config, declaration, read));
+  const summary = Object.fromEntries(EVIDENCE_STATES.map(state => [state, results.filter(result => result.state === state).length]));
+  const status = summary.contradicted > 0 ? 'contradicted'
+    : summary.stale + summary.inconclusive + summary.unsupported > 0 ? 'attention-required'
+      : 'verified-within-scope';
+  return {
+    command: 'verify --evidence', exists: true, manifest: '.docguard-evidence.json', status,
+    manifestEvidence: loaded.evidence, errors: [], results, summary, scopeLimitation: EVIDENCE_SCOPE_LIMITATION,
+  };
+}
+
+/** Reduce heuristic work only when one verified declaration maps to one exact extracted claim. */
+export function coverSemanticClaims(claims, evaluation) {
+  const verified = evaluation?.results?.filter(result => result.state === 'verified-within-scope') || [];
+  const candidates = new Map();
+  for (const claim of claims) {
+    const matches = verified.filter(result => {
+      const line = Number(String(result.location).match(/:(\d+)$/)?.[1]);
+      if (result.document !== claim.doc || line !== claim.line || !String(claim.text).includes(result.statement)) return false;
+      if (Array.isArray(result.documentValue)) return claim.kind === 'enum' && result.documentValue.join('/') === claim.value;
+      if (result.documentValue === null) return false;
+      return String(result.documentValue) === String(claim.value);
+    });
+    candidates.set(claim.stableId, matches);
+  }
+  const resultUse = new Map();
+  for (const matches of candidates.values()) {
+    for (const result of matches) resultUse.set(result.claimId, (resultUse.get(result.claimId) || 0) + 1);
+  }
+  const covered = claims.filter(claim => {
+    const matches = candidates.get(claim.stableId) || [];
+    return matches.length === 1 && resultUse.get(matches[0].claimId) === 1;
+  });
+  const coveredIds = new Set(covered.map(claim => claim.stableId));
+  return {
+    total: claims.length,
+    verifiedWithinScope: covered.length,
+    unverified: claims.length - covered.length,
+    covered: covered.map(claim => claim.stableId),
+    remaining: claims.filter(claim => !coveredIds.has(claim.stableId)),
+  };
+}