docguard-cli 0.38.0 → 0.40.0

package/cli/commands/generate.mjs

@@ -1,4 +1,9 @@
-import { assertDefaultDocWrites } from '../shared-doc-roles.mjs';
+/**
+ * @implements docguard.language-repository-coverage#FR-009
+ * @implements docguard.language-repository-coverage#FR-010
+ * @implements docguard.language-repository-coverage#FR-011
+ */
+import { assertMappedFullDocumentWrites, docRolePath, isMappedDocPath, mappedRolesForPath, resolveDocRole } from '../shared-doc-roles.mjs';
 /**
  * Generate Command — Reverse-engineer canonical docs from an existing codebase
  * Scans source code and creates documentation templates pre-filled with project data.
@@ -6,7 +11,7 @@ import { assertDefaultDocWrites } from '../shared-doc-roles.mjs';
  * This is the "killer feature" — take any project and auto-generate CDD docs.
  */
 
-import { existsSync, readFileSync, mkdirSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { resolve, extname, basename, relative } from 'node:path';
 import { c } from '../shared.mjs';
 import { walkFiles as sharedWalkFiles } from '../shared-ignore.mjs';
@@ -14,7 +19,7 @@ import { detectDocTools } from '../scanners/doc-tools.mjs';
 import { scanRoutesDeep } from '../scanners/routes.mjs';
 import { scanSchemasDeep } from '../scanners/schemas.mjs';
 import { buildMemoryPlan } from '../scanners/memory-plan.mjs';
-import { upsertSection } from '../writers/sections.mjs';
+import { assertOwnedCodeSection, replaceSection, upsertSection } from '../writers/sections.mjs';
 import { safeWrite, registerGeneratedCanonicalDocs, surfaceConfidence } from '../writers/generate-io.mjs';
 import {
   generateArchitecture, generateApiReference, generateDataModel,
@@ -40,11 +45,32 @@ const CODE_EXTENSIONS = new Set([
  * inserted as agent-task placeholders), respecting human prose via markers.
  */
 export function runGeneratePlan(projectDir, config, flags) {
-  if (flags.write) assertDefaultDocWrites(config);
   // `--profile <name>` previews a profile's doc set without needing `init` first.
   if (flags.profile) config = { ...config, profile: flags.profile };
   const plan = buildMemoryPlan(projectDir, config);
 
+  // Existing mapped human documents grant ownership section-by-section. Check
+  // every target before the first write so one malformed later file cannot
+  // leave an earlier document partially updated.
+  if (flags.write) {
+    for (const doc of plan.docs) {
+      const full = resolve(projectDir, doc.path);
+      if (!isMappedDocPath(config, doc.path)) continue;
+      if (!existsSync(full)) {
+        if (mappedRolesForPath(config, doc.path).length > 1) {
+          throw new Error(`Mapped document ${doc.path} serves multiple roles; whole-document scaffolding is unavailable.`);
+        }
+        continue;
+      }
+      const content = readFileSync(full, 'utf8');
+      const fullyOwned = /^[ \t]*<!--\s*docguard:generated\s+true\s*-->[ \t]*$/mi.test(content);
+      if (fullyOwned) assertMappedFullDocumentWrites(projectDir, config, mappedRolesForPath(config, doc.path));
+      else for (const sec of doc.sections.filter(item => item.source === 'code')) {
+        assertOwnedCodeSection(content, sec.id, doc.path);
+      }
+    }
+  }
+
   if (flags.format === 'json') {
     console.log(JSON.stringify({
       project: config.projectName,
@@ -80,8 +106,6 @@ export function runGeneratePlan(projectDir, config, flags) {
 
   // --write: scaffold the skeleton docs with code sections + agent-task placeholders.
   if (flags.write) {
-    const docsDir = resolve(projectDir, 'docs-canonical');
-    if (!existsSync(docsDir)) mkdirSync(docsDir, { recursive: true });
     let wrote = 0;
     for (const doc of plan.docs) {
       const full = resolve(projectDir, doc.path);
@@ -89,11 +113,16 @@ export function runGeneratePlan(projectDir, config, flags) {
       let content = existsSync(full)
         ? readFileSync(full, 'utf-8')
         : `# ${title}\n\n<!-- docguard:generated true -->\n`;
+      const boundedMapped = isMappedDocPath(config, doc.path) && existsSync(full)
+        && !/^[ \t]*<!--\s*docguard:generated\s+true\s*-->[ \t]*$/mi.test(content);
       for (const sec of doc.sections) {
+        if (boundedMapped && sec.source !== 'code') continue;
         const body = sec.source === 'code'
           ? sec.body
           : `> **AI task:** ${sec.task}\n<!-- docguard:pending agent writes this section -->`;
-        content = upsertSection(content, sec.id, body, { source: sec.source }).content;
+        content = boundedMapped
+          ? replaceSection(content, sec.id, body).content
+          : upsertSection(content, sec.id, body, { source: sec.source }).content;
       }
       // Route through safeWrite: creates the parent dir (docs-implementation/ may
       // not exist yet — was an ENOENT crash) and snapshots a .bak before writing.
@@ -139,7 +168,6 @@ export function runGeneratePlan(projectDir, config, flags) {
 }
 
 export function runGenerate(projectDir, config, flags) {
-  if (!flags.plan || flags.write) assertDefaultDocWrites(config);
   // --plan: emit the AI-powered "memory plan" — the agent task manifest. The CLI
   // builds the code-truth skeleton (marked sections) + tells the agent exactly
   // what prose to write per section. This is the language-aware Generate path.
@@ -191,17 +219,23 @@ export function runGenerate(projectDir, config, flags) {
   console.log('');
 
   // ── 6. Generate Documents ──
-  const docsDir = resolve(projectDir, 'docs-canonical');
-  if (!existsSync(docsDir)) {
-    mkdirSync(docsDir, { recursive: true });
-  }
+  // Preflight every mapped whole-document target before the first generator
+  // writes. Existing targets are skipped unless --force, so they do not need
+  // ownership merely to run ordinary generation.
+  const candidateRoles = ['architecture', ...(deepRoutes.length > 0 ? ['apiReference'] : []),
+    'dataModel', 'environment', 'testSpec', 'security'];
+  const writableRoles = candidateRoles.filter(role => {
+    const target = resolveDocRole(projectDir, config, role);
+    return !existsSync(target) || flags.force;
+  });
+  assertMappedFullDocumentWrites(projectDir, config, writableRoles);
 
   // ── Safety: warn if --force will overwrite existing files ──
   if (flags.force) {
     const targetFiles = [
-      'docs-canonical/ARCHITECTURE.md', 'docs-canonical/API-REFERENCE.md',
-      'docs-canonical/DATA-MODEL.md', 'docs-canonical/ENVIRONMENT.md',
-      'docs-canonical/TEST-SPEC.md', 'docs-canonical/SECURITY.md',
+      docRolePath(config, 'architecture'), docRolePath(config, 'apiReference'),
+      docRolePath(config, 'dataModel'), docRolePath(config, 'environment'),
+      docRolePath(config, 'testSpec'), docRolePath(config, 'security'),
       'AGENTS.md', 'CHANGELOG.md', 'DRIFT-LOG.md',
     ];
     const existing = targetFiles.filter(f => existsSync(resolve(projectDir, f)));
@@ -248,9 +282,9 @@ export function runGenerate(projectDir, config, flags) {
   // B7: keep guard coherent — register the canonical docs we emitted so the
   // traceability validator doesn't flag the generator's own output.
   const registered = registerGeneratedCanonicalDocs(projectDir, [
-    'docs-canonical/ARCHITECTURE.md', 'docs-canonical/API-REFERENCE.md',
-    'docs-canonical/DATA-MODEL.md', 'docs-canonical/ENVIRONMENT.md',
-    'docs-canonical/TEST-SPEC.md', 'docs-canonical/SECURITY.md',
+    docRolePath(config, 'architecture'), docRolePath(config, 'apiReference'),
+    docRolePath(config, 'dataModel'), docRolePath(config, 'environment'),
+    docRolePath(config, 'testSpec'), docRolePath(config, 'security'),
   ]);
 
   console.log(`\n${c.bold}  ─────────────────────────────────────${c.reset}`);

package/cli/commands/guard.mjs

@@ -1,6 +1,7 @@
 import { describeCheckCoverage, summarizeCheckCoverage } from '../validator-coverage.mjs';
 import { applyDocRoles } from '../shared-doc-roles.mjs';
 /**
+ * @implements docguard.evidence-scoped-verification#FR-010
  * Guard Command — Validate project against its canonical documentation
  * Runs all enabled validators and reports results.
  *
@@ -157,6 +158,8 @@ import { validateReferenceExistence } from '../validators/reference-existence.mj
 import { validateApiDocSmells } from '../validators/api-doc-smells.mjs';
 import { validateDocumentLifecycle } from '../validators/document-lifecycle.mjs';
 import { validateSpecRegistry } from '../validators/spec-registry.mjs';
+import { validateEvidence } from '../validators/evidence.mjs';
+import { coverSemanticClaims } from '../evidence/evaluate.mjs';
 
 /**
  * Internal guard — returns structured data, no console output, no process.exit.
@@ -323,6 +326,7 @@ export function runGuardInternal(projectDir, config) {
     { key: 'specKit', name: 'Spec-Kit', fn: () => validateSpecKitIntegration(projectDir, config) },
     { key: 'documentLifecycle', name: 'Document-Lifecycle', fn: () => validateDocumentLifecycle(projectDir, config) },
     { key: 'specRegistry', name: 'Spec-Registry', fn: () => validateSpecRegistry(projectDir, config) },
+    { key: 'evidence', name: 'Evidence', fn: () => validateEvidence(projectDir, config) },
     { key: 'crossReference', name: 'Cross-Reference', fn: () => validateCrossReferences(projectDir, config) },
     { key: 'generatedStaleness', name: 'Generated-Staleness', fn: () => validateGeneratedStaleness(projectDir, config) },
     { key: 'surfaceSync', name: 'Surface-Sync', fn: () => validateSurfaceSync(projectDir, config) },
@@ -492,9 +496,14 @@ export function runGuardInternal(projectDir, config) {
   const lite = Array.isArray(config.changedFiles);
   let coverage = null;
   let semanticClaims = null;
+  const evidence = results.find(result => result.key === 'evidence')?.evidence || null;
   if (!lite) {
     try { coverage = computeDocCoverage(projectDir, config); } catch { coverage = null; }
-    try { semanticClaims = { count: extractSemanticClaims(projectDir, config).length }; }
+    try {
+      const claims = extractSemanticClaims(projectDir, config);
+      const scoped = coverSemanticClaims(claims, evidence);
+      semanticClaims = { count: scoped.unverified, discovered: scoped.total, verifiedWithinScope: scoped.verifiedWithinScope, coveredClaimIds: scoped.covered };
+    }
     catch { semanticClaims = null; }
   }
 
@@ -518,6 +527,7 @@ export function runGuardInternal(projectDir, config) {
     coverage,
     checkCoverage,
     semanticClaims,
+    evidence,
     validators: results,
     // Unknown keys in `docguard:validator … n/a` markers — typo protection so
     // a mistyped key doesn't silently fail to suppress. Surfaced by runGuard.
@@ -539,7 +549,7 @@ export function runGuardInternal(projectDir, config) {
  * Freshness (git log), Traceability (REQ scan), Doc-Quality (prose lint) —
  * stay off for speed.
  */
-export const CHANGED_ONLY_VALIDATORS = ['docsSync', 'environment', 'apiSurface', 'drift', 'todoTracking'];
+export const CHANGED_ONLY_VALIDATORS = ['docsSync', 'environment', 'apiSurface', 'drift', 'todoTracking', 'evidence'];
 
 /**
  * Build a validators map that enables the pre-commit-lite set — PLUS any
@@ -560,6 +570,7 @@ export function liteValidatorsConfig(config = {}) {
     'apiSurface', 'metadataSync', 'docsCoverage', 'docQuality', 'todoTracking',
     'schemaSync', 'specKit', 'crossReference', 'generatedStaleness',
     'canonicalSync', 'metricsConsistency',
+    'evidence',
   ];
   const userValidators = (config && config.validators) || {};
   const out = {};

package/cli/commands/mcp.mjs

@@ -1,8 +1,10 @@
 /**
+ * @implements docguard.evidence-scoped-verification#FR-009
+ * @implements docguard.evidence-scoped-verification#FR-012
  * MCP Command — DocGuard as a Model Context Protocol server (stdio).
  *
  * `docguard mcp` exposes the read-only core (guard / score / explain /
- * verify-claims / diagnose) as MCP tools any MCP client (Claude, Cursor,
+ * verify-evidence / verify-claims / diagnose) as MCP tools any MCP client (Claude, Cursor,
  * agent SDKs) can call over stdio. JSON-RPC 2.0, newline-delimited, per the
  * MCP stdio transport (protocol revision 2024-11-05).
  *
@@ -31,6 +33,7 @@ import { buildReport } from './report.mjs';
 import { loadConfig } from '../config.mjs';
 import { CODES } from '../findings.mjs';
 import { extractSemanticClaims, buildSemanticVerifyTasks } from '../scanners/semantic-claims.mjs';
+import { coverSemanticClaims, evaluateEvidence } from '../evidence/evaluate.mjs';
 
 const _PKG = JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json'), 'utf-8'));
 
@@ -101,6 +104,16 @@ const TOOLS = [
     },
     annotations: READONLY_ANNOTATIONS,
   },
+  {
+    name: 'docguard_verify_evidence',
+    title: 'Verify declared evidence',
+    description: 'Evaluate `.docguard-evidence.json` against bounded local sources. Returns explicit verified-within-scope, contradicted, stale, inconclusive, and unsupported states; verification applies only to each selected statement.',
+    inputSchema: {
+      type: 'object',
+      properties: { ...PROJECT_DIR_PROP },
+    },
+    annotations: READONLY_ANNOTATIONS,
+  },
   {
     name: 'docguard_verify_claims',
     title: 'Extract claims to verify',
@@ -173,13 +186,20 @@ const TOOL_HANDLERS = {
   docguard_verify_claims(args, defaultDir) {
     const { dir, config } = resolveTarget(args, defaultDir);
     const claims = extractSemanticClaims(dir, config);
+    const coverage = coverSemanticClaims(claims, evaluateEvidence(dir, config));
     return {
       claimCount: claims.length,
+      verifiedWithinScope: coverage.verifiedWithinScope,
       note: 'Deterministic discovery, LLM judgment — the caller verifies each claim against the code and reports any mismatch with both values.',
-      tasks: buildSemanticVerifyTasks(claims),
+      tasks: buildSemanticVerifyTasks(coverage.remaining),
     };
   },
 
+  docguard_verify_evidence(args, defaultDir) {
+    const { dir, config } = resolveTarget(args, defaultDir);
+    return evaluateEvidence(dir, config);
+  },
+
   docguard_report(args, defaultDir) {
     const { dir, config } = resolveTarget(args, defaultDir);
     return buildReport(dir, config);

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/specs.mjs

@@ -56,6 +56,13 @@ function archiveReadiness(spec, targetVerified = false) {
   return { status: 'READY', reason: 'Run the reviewed spec retirement flow after the verified state is committed and retained.' };
 }
 
+function completionTransition(spec) {
+  if (spec?.reviewed.lifecycle.delivery === 'verified') return 'verified→verified';
+  return spec?.reviewed.lifecycle.delivery === 'in_progress'
+    ? 'in_progress→implemented→verified'
+    : 'implemented→verified';
+}
+
 export function planSpecCompletion(projectDir, config, flags, options = {}) {
   const projection = projectSpecRegistry(projectDir, config);
   const loaded = readSpecRegistry(projectDir);
@@ -70,8 +77,12 @@ export function planSpecCompletion(projectDir, config, flags, options = {}) {
 
   let reconcile = null;
   if (spec) {
+    const maintenance = spec.reviewed.lifecycle.delivery === 'verified'
+      && spec.reviewed.lifecycle.persistenceModel === 'living';
     if (spec.reviewed.lifecycle.approval !== 'approved') blockers.push({ code: 'SPC002', message: 'Only an approved spec can become verified.' });
-    if (!['in_progress', 'implemented'].includes(spec.reviewed.lifecycle.delivery)) blockers.push({ code: 'SPC002', message: `Expected delivery=in_progress or implemented, found ${spec.reviewed.lifecycle.delivery}.` });
+    if (!['in_progress', 'implemented'].includes(spec.reviewed.lifecycle.delivery) && !maintenance) {
+      blockers.push({ code: 'SPC002', message: `Expected delivery=in_progress, implemented, or verified with persistenceModel=living; found ${spec.reviewed.lifecycle.delivery}/${spec.reviewed.lifecycle.persistenceModel || 'unset'}.` });
+    }
     const tasks = spec.observed.taskCompletion;
     if (!tasks.total || tasks.checked !== tasks.total) blockers.push({ code: 'SPC003', message: `All tasks must be checked (${tasks.checked}/${tasks.total}).` });
     if (spec.observed.implementationEvidence.length === 0) blockers.push({ code: 'SPC004', message: 'At least one qualified source implementation annotation is required.' });
@@ -92,6 +103,14 @@ export function planSpecCompletion(projectDir, config, flags, options = {}) {
       if (reconcile.status === 'UNSUPPORTED' || reconcile.status === 'BLOCKED') blockers.push({ code: 'SPC006', message: 'Reconciliation coverage is unsupported or blocked.' });
       const unresolved = reconcile.classifications.filter(item => item.disposition === 'unsupported_or_ambiguous');
       if (unresolved.length) blockers.push({ code: 'SPC006', message: `Unresolved changed files: ${unresolved.map(item => item.path).join(', ')}.` });
+      if (maintenance) {
+        const reviewable = reconcile.classifications.filter(item =>
+          item.specs.includes(spec.specId)
+          && ['source', 'test', 'canonical_doc', 'decision'].includes(item.kind));
+        if (revision === spec.reviewed.reconciliation.lastReviewedRevision || reviewable.length === 0) {
+          blockers.push({ code: 'SPC006', message: 'Living-spec maintenance requires a new linked source, test, canonical-document, or decision change since the last reviewed revision.' });
+        }
+      }
     }
   }
   const guard = options.guardResult || runGuardInternal(projectDir, config);
@@ -100,7 +119,7 @@ export function planSpecCompletion(projectDir, config, flags, options = {}) {
     status: blockers.length ? 'BLOCKED' : 'READY',
     specId: flags.id || null,
     revision,
-    transition: spec?.reviewed.lifecycle.delivery === 'in_progress' ? 'in_progress→implemented→verified' : 'implemented→verified',
+    transition: completionTransition(spec),
     blockers,
     reconciliation: reconcile,
     evidence: spec ? [...new Set([

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) {