docguard-cli 0.39.0 → 0.40.0

package/README.md

@@ -77,7 +77,7 @@ graph TD
     Commands --> setup["setup wizard"]
     Commands --> other["diff · init · fix · trace · impact · sync · reconcile · retire · specs<br/>explain · memory · upgrade · agents · hooks · badge · ci · watch"]
 
-    guard --> Validators["Validators (29)"]
+    guard --> Validators["Validators (30)"]
     generate --> Scanners["Scanners (4)<br/>routes · schemas · doc-tools · speckit"]
     score --> Scoring["Weighted Scoring<br/>8 categories"]
     diagnose --> Validators
@@ -104,7 +104,7 @@ graph TD
 
 DocGuard checks declared documentation facts against repository evidence and gives agents structured repair tasks. Deterministic checks cover supported facts, references, and generated sections. Human-authored requirements and architectural decisions retain their authority when implementation diverges.
 
-A guard result describes the checks performed. The CDD grade measures structural maturity. Factual accuracy stays explicitly unverified until the relevant claims have supporting evidence. Coverage and unresolved claims remain visible, so teams can choose an appropriate enforcement policy.
+A guard result describes the checks performed. The CDD grade measures structural maturity. Exact declarations in `.docguard-evidence.json` can verify selected statements against current local evidence; every other statement remains unverified. Coverage and unresolved claims remain visible, so teams can choose an appropriate enforcement policy.
 
 Research motivates evaluation of this approach. A 2026 study found that repository context files did not generally improve task success and increased inference cost in its evaluated settings. It also found agents generally followed the instructions. These results support testing concise, relevant context and measuring actual task outcomes; they do not establish DocGuard's effectiveness. [Evaluating AGENTS.md, revised June 2026](https://arxiv.org/abs/2602.11988v2).
 
@@ -275,7 +275,7 @@ DocGuard ships **23 commands** (the "Daily 5" + 18 situational tools, including
 | Command | What It Does |
 |:--------|:-------------|
 | `init`  | Bootstrap a project (`--wizard` for interactive · `--with <name>` for scaffolders) |
-| `guard` | Validate against canonical docs — 29 validators |
+| `guard` | Validate against canonical docs — 30 validators |
 | `diff`  | Show gaps between docs and code (`--since <ref>` for impact mode) |
 | `sync`  | Refresh code-truth doc sections — keeps memory always up to date |
 | `score` | CDD maturity score (0-100; `--diff` for delta between refs) |
@@ -290,8 +290,9 @@ DocGuard ships **23 commands** (the "Daily 5" + 18 situational tools, including
 | `fix --write` | Apply deterministic fixes (no AI — version bumps, counts, anchors, sections) |
 | `fix --history` | Audit log of every mechanical fix applied (from `.docguard/fixed.json`) |
 | `generate` | Reverse-engineer docs from existing codebase (`--plan` for AI scan) — includes auto-generated Mermaid ER diagrams from your detected schemas (Prisma/Drizzle/TypeORM/Sequelize/Django/Rails) in DATA-MODEL.md |
-| `agent` | One-shot agent task graph — ordered, pre-filled code-truth, per-task verify (`--format json`) |
+| `agent` | One-shot agent task graph, or a bounded current-evidence packet for one task (`--task <text>`, `--format json`) |
 | `explain <warning\|CODE>` | Paste any warning — or a finding code like `SEC001` — to get the validator's docstring, fix path, and how to suppress |
+| `verify --evidence` | Evaluate strict statement-to-source declarations for typed JSON values, bounded collection counts, saved oasdiff JSON, and saved Buf JSON Lines. Results distinguish scoped verification, contradiction, stale inputs, inconclusive evidence, and unsupported formats. |
 | `verify --semantic` | Extract documented numbers/limits/enums (retention days, rate limits, GSI/role counts, status enums) as a task list for an agent to check against code — the semantic-drift class regex/AST can't see |
 | `verify --instructions` | Audit AGENTS.md/CLAUDE.md themselves for drift: duplicate rules, never-vs-always contradictions, stale file pointers, unknown commands — plus clustered rule pairs as agent judgment tasks |
 | `feedback` | Review any finding or a synthetic false-positive/false-negative/unsupported fixture; verify its opposite control, reduce it deterministically, search open and closed duplicates, and optionally emit a test-only contribution. Nothing is submitted automatically. |
@@ -326,16 +327,23 @@ DocGuard ships **23 commands** (the "Daily 5" + 18 situational tools, including
 
 Run them solo (`docguard init --with hooks`) or stacked (`docguard init --with agents,hooks,badge,ci`).
 
+To declare an exact fact, copy `templates/evidence-manifest.json` to
+`.docguard-evidence.json`, point its literal Markdown template at one unique
+statement, and bind that value to a supported local source. Run
+`docguard verify --evidence --format json` before enabling the guard in CI.
+External compatibility declarations consume saved oasdiff or Buf output and
+require current SHA-256 identities for every declared repository input.
+
 **Deprecation aliases** — `setup` · `agents` · `hooks` · `badge` · `llms` · `publish` · `impact` remain compatible until v1.0 with a yellow stderr warning. `audit → guard` is permanent and silent; `ci` is a current first-class pipeline command.
 
 ### CLI Flags
 
 | Flag | Description | Commands |
 |:-----|:------------|:---------|
-| `--dir <path>` | Project directory (default: `.`) | All |
+| `--dir <path>` | Project directory (default: `.`); explicit selection suppresses ancestor-root guidance | All |
 | `--verbose` | Show detailed output | All |
 | `--quiet` / `-q` | Suppress banner — for hooks, CI loops, scripts | All |
-| `--format json` | Machine-readable output (clean JSON, no ANSI bleed) | guard, score, diff, trace, diagnose, memory, impact, explain, reconcile, retire, specs |
+| `--format json` | Machine-readable output (clean JSON, no ANSI bleed) | guard, score, diff, trace, diagnose, memory, impact, explain, verify, reconcile, retire, specs |
 | `--format sarif` | SARIF 2.1.0 output — findings as rules/results for GitHub Code Scanning and SARIF dashboards | guard |
 | `--format junit` | JUnit XML output — one testcase per validator, for GitLab CI (`artifacts:reports:junit`), Jenkins, Azure DevOps, CircleCI | guard |
 | `--update-baseline` | Adopt DocGuard on a legacy repo without a red day one: freeze today's findings into a committed `.docguard.baseline.json`; guard/ci then gate only NEW drift. Suppression is always visible ("N pre-existing finding(s) suppressed"), and `--no-baseline` shows the full picture | guard |
@@ -347,7 +355,7 @@ Run them solo (`docguard init --with hooks`) or stacked (`docguard init --with a
 | `--force-redo` | Bypass ping-pong suppression in `.docguard/fixed.json` | fix --write |
 | `--profile <name>` | Starter / standard / enterprise | init |
 | `--no-spec-kit` | Skip auto-init of `.specify/` / `.agent/` scaffolding | init |
-| `--changed-only [--since <ref>]` | Pre-commit lite mode (5 fast validators on changed files only) | guard |
+| `--changed-only [--since <ref>]` | Pre-commit lite mode (6 fast validators on changed files only) | guard |
 | `--timings` | Per-validator wall-time profile (slowest first) | guard |
 | `--show-failing` | Show warnings/errors even when status is PASS | guard |
 | `--pin` | Record running CLI version into `.docguard.json` (reproducibility) | guard |
@@ -361,6 +369,15 @@ Run them solo (`docguard init --with hooks`) or stacked (`docguard init --with a
 | `--transport http` `--port` `--host` `--api-key` `--path` | Serve MCP over Streamable HTTP instead of stdio (team-shared server; loopback-only unless an api-key is set) | mcp |
 | `--history` | Show fix audit log | fix |
 
+When run from a nested package without `--dir`, DocGuard checks only that
+selected directory. If a bounded ancestor scan finds a `.docguard.json` or an
+npm/pnpm workspace declaration that owns the package, stderr shows an exact
+repository-scope rerun command. DocGuard never changes scope automatically. JSON,
+SARIF, and JUnit stdout remain valid; machine runs receive one typed
+`docguard.repository-root-guidance` JSON diagnostic on stderr. A local config,
+an explicit `--dir`, an unmatched workspace, or a nested Git boundary suppresses
+the suggestion.
+
 ### Example Output
 
 ```
@@ -394,7 +411,7 @@ $ npx docguard-cli generate
 
 ## 🔍 Validators
 
-DocGuard runs **29 automated validators** on every `guard` check. Source-facing validators are language-aware where their evidence model applies; repository and document validators operate independently of source language.
+DocGuard runs **30 automated validators** on every `guard` check. Source-facing validators are language-aware where their evidence model applies; repository and document validators operate independently of source language.
 
 | # | Validator | What It Checks | Default |
 |:--|:----------|:--------------|:--------|
@@ -419,14 +436,15 @@ DocGuard runs **29 automated validators** on every `guard` check. Source-facing
 | 19 | **Spec-Kit** | Spec quality validation (FR-IDs, mandatory sections, phased tasks) | ✅ On |
 | 20 | **Document-Lifecycle** | Exact terminal states, advisory completion signals, incomplete coverage, and manifest/working-tree inconsistencies | ✅ On |
 | 21 | **Spec-Registry** | Immutable spec identities, byte-stable evidence projection, reviewed lifecycle preservation, and archive/storage consistency | ✅ On |
-| 22 | **Cross-Reference** | Internal markdown links + anchors resolve (with "did you mean?" hints); Obsidian wikilinks validated when the repo uses them as file links (`.obsidian` present or a target resolves) | ✅ On |
-| 23 | **Generated-Staleness** | `source=code` sections match scanner output; `status: draft` doc age | ✅ On |
-| 24 | **Canonical-Sync** | DocGuard's own README count claims match code-truth (DocGuard repo only — N/A elsewhere) | ✅ On |
-| 25 | **Metrics-Consistency** | Hardcoded numbers match actual counts | ✅ On |
-| 26 | **Surface-Sync** | Item-level enumerable drift — names in doc tables/lists (commands, checks, etc.) match code-truth (opt-in via `surfaceSync.surfaces`; N/A unless configured) | ✅ On |
-| 27 | **Diff-Suspicion** | Change-driven: a doc/agent-instruction file that references code changed since the ref AND shares removed domain symbols is flagged for review (arXiv 2010.01625, F1 74.7) | ✅ On |
-| 28 | **Reference-Existence** | Two-revision check: a backticked code symbol present when the doc was last updated but gone at HEAD is flagged as outdated (arXiv 2212.01479) | ✅ On |
-| 29 | **API-Doc-Smells** | Bloated (≥300 words) / Lazy (≤6 prose words) API documentation units, keyed on signature-headed sections (F1 0.90/0.95) | ✅ On |
+| 22 | **Evidence** | Exact declared Markdown statements match current typed JSON, bounded collections, or saved compatibility reports; unsupported and missing evidence stays visible | ✅ On |
+| 23 | **Cross-Reference** | Internal markdown links + anchors resolve (with "did you mean?" hints); Obsidian wikilinks validated when the repo uses them as file links (`.obsidian` present or a target resolves) | ✅ On |
+| 24 | **Generated-Staleness** | `source=code` sections match scanner output; `status: draft` doc age | ✅ On |
+| 25 | **Canonical-Sync** | DocGuard's own README count claims match code-truth (DocGuard repo only — N/A elsewhere) | ✅ On |
+| 26 | **Metrics-Consistency** | Hardcoded numbers match actual counts | ✅ On |
+| 27 | **Surface-Sync** | Item-level enumerable drift — names in doc tables/lists (commands, checks, etc.) match code-truth (opt-in via `surfaceSync.surfaces`; N/A unless configured) | ✅ On |
+| 28 | **Diff-Suspicion** | Change-driven: a doc/agent-instruction file that references code changed since the ref AND shares removed domain symbols is flagged for review (arXiv 2010.01625, F1 74.7) | ✅ On |
+| 29 | **Reference-Existence** | Two-revision check: a backticked code symbol present when the doc was last updated but gone at HEAD is flagged as outdated (arXiv 2212.01479) | ✅ On |
+| 30 | **API-Doc-Smells** | Bloated (≥300 words) / Lazy (≤6 prose words) API documentation units, keyed on signature-headed sections (F1 0.90/0.95) | ✅ On |
 
 **Per-validator controls** (in `.docguard.json`):
 ```json
@@ -517,7 +535,7 @@ DocGuard provides AI agent slash commands for integrated workflows. Installed au
 | Command | What It Does |
 |:--------|:-------------|
 | `/docguard.init` | Initialize Canonical-Driven Development in a new or existing project |
-| `/docguard.guard` | Run quality validation — check all 29 validators |
+| `/docguard.guard` | Run quality validation — check all 30 validators |
 | `/docguard.review` | Analyze doc quality and suggest improvements |
 | `/docguard.fix` | Generate targeted fix prompts for specific issues |
 | `/docguard.update` | Update canonical docs after code changes — detect drift and sync documentation |
@@ -703,11 +721,16 @@ Highlights of the current line (v0.29 → v0.33):
   agent tools: `claude mcp add docguard -- npx docguard-cli mcp`.
 - **Agent-file family sync** — `agents --sync` treats AGENTS.md as canonical and regenerates
   CLAUDE.md / `.cursor/rules` / Copilot / Gemini variants with drift-proof source-hash markers.
-- **`verify --semantic` and `verify --instructions`** — extract documented numbers/limits/enums
-  as agent verification tasks; audit the agent-instruction files themselves for contradictions
-  and stale pointers.
+- **`verify --evidence`, `verify --semantic`, and `verify --instructions`** — check exact local
+  evidence declarations first, extract remaining numbers/limits/enums as agent tasks, and audit
+  agent-instruction files for contradictions and stale pointers.
 - **`docguard agent`** — one-shot ordered task graph with pre-filled code-truth, collapsing ~10
   agent round-trips into one call.
+- **`docguard agent --task <text>`** — opt-in task context from approved current
+  specs and canonical docs, with hashed excerpts, source/test pointers, strict
+  budgets, and honest abstention. The frozen 27-run evaluation preserved every
+  tested behavior and cut median steps by 50% and latency by 17% versus the
+  context pack, while using 80% more uncached input tokens.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 

package/cli/commands/agent.mjs

@@ -1,4 +1,6 @@
 /**
+ * @implements docguard.evidence-scoped-verification#FR-012
+ * @implements docguard.task-specific-agent-context#FR-010
  * `docguard agent` — the one-shot agent task graph.
  *
  * Field report §2: an LLM told "run docguard and fix the docs" had to drive ~10
@@ -25,6 +27,8 @@ import { buildMemoryPlan } from '../scanners/memory-plan.mjs';
 import { c } from '../shared.mjs';
 import { createEvidenceReader, citedSources, taskEvidence, gitEvidence, SEMANTIC_COVERAGE_LIMITATION } from '../scanners/semantic-claims.mjs';
 import { buildScoreAssurance } from './score.mjs';
+import { evaluateEvidence } from '../evidence/evaluate.mjs';
+import { buildTaskContextPacket } from '../scanners/task-context.mjs';
 
 const PHASES = ['config', 'canonical-docs', 'verify'];
 
@@ -89,7 +93,7 @@ export function buildAgentTaskGraph(projectDir, config, plan) {
     phase: 'verify',
     file: null,
     kind: 'verify',
-    instruction: 'Run `docguard guard --format json`. Resolve every error, then re-run until there are 0 errors. Triage warnings and record unresolved warnings; warnings do not fail this acceptance gate. Run `docguard score` for structural maturity, and `docguard verify --semantic` to obtain unverified claim tasks for separate source review. Neither guard nor score verifies prose or factual accuracy.',
+    instruction: 'Run `docguard guard --format json`. Resolve every error, then re-run until there are 0 errors. Triage warnings and record unresolved warnings; warnings do not fail this acceptance gate. Run `docguard verify --evidence` for exact declared checks and `docguard verify --semantic` for remaining heuristic claim tasks. Run `docguard score` for structural maturity. Neither guard nor score verifies prose; scoped evidence verifies only its selected statements and does not establish whole-document factual accuracy.',
     prefilled: null,
     grounding: null,
     acceptance: { verify: 'docguard guard --format json', expect: '0 errors', warnings: 'triage-and-report', scope: 'structural-only', factualAccuracy: 'unknown' },
@@ -105,11 +109,13 @@ export function buildAgentTaskGraph(projectDir, config, plan) {
 
   const assurance = buildScoreAssurance(projectDir, config);
   assurance.limitation += ` ${SEMANTIC_COVERAGE_LIMITATION}`;
+  const evidence = evaluateEvidence(projectDir, config);
 
   return {
     project: config.projectName,
     provenance: { kind: 'snapshot', git: gitEvidence(projectDir) },
     assurance,
+    evidence,
     profile: { name: profileName, kind: plan.profile.kind, languages: plan.profile.languages, frameworks: plan.profile.frameworks },
     order: PHASES,
     counts: {
@@ -123,6 +129,46 @@ export function buildAgentTaskGraph(projectDir, config, plan) {
 }
 
 export function runAgent(projectDir, config, flags) {
+  if (flags.task !== undefined) {
+    let packet;
+    try {
+      packet = buildTaskContextPacket(projectDir, config, flags.task);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Task context input is invalid.';
+      if (flags.format === 'json') console.log(JSON.stringify({ status: 'error', code: 'TASK_CONTEXT_INPUT', message }, null, 2));
+      else console.error(`${c.red}Error:${c.reset} ${message}`);
+      process.exitCode = 1;
+      return null;
+    }
+    if (flags.format === 'json') {
+      console.log(JSON.stringify(packet, null, 2));
+      return packet;
+    }
+
+    console.log(`${c.bold}🎯 DocGuard Task Context — ${config.projectName}${c.reset}`);
+    console.log(`${c.dim}   ${packet.selection.status} · ${packet.selection.selectedExcerpts} excerpt(s) · task ${packet.task.digest}${c.reset}\n`);
+    console.log(`  ${c.dim}Retrieval only · factual accuracy remains unknown · verify before editing.${c.reset}\n`);
+    if (packet.selection.status === 'abstained') {
+      console.log(`  ${c.yellow}No evidence met the relevance threshold. Use the navigation map for normal repository discovery.${c.reset}\n`);
+    }
+    for (const excerpt of packet.excerpts) {
+      console.log(`  ${c.bold}${excerpt.path}:${excerpt.startLine}-${excerpt.endLine}${c.reset} ${c.dim}[${excerpt.kind} · score ${excerpt.score}]${c.reset}`);
+      for (const line of excerpt.content.split('\n')) console.log(`    ${line}`);
+      console.log('');
+    }
+    if (packet.pointers.length) {
+      console.log(`  ${c.bold}Evidence pointers${c.reset}`);
+      for (const pointer of packet.pointers) console.log(`    - ${pointer.path} (${pointer.kind}: ${pointer.reasons.join(', ')})`);
+      console.log('');
+    }
+    console.log(`  ${c.bold}Verify${c.reset}`);
+    for (const item of packet.verification) console.log(`    - ${item.command} — ${item.purpose}`);
+    console.log(`\n  ${c.bold}Limits${c.reset}`);
+    for (const limitation of packet.limitations) console.log(`    - ${limitation}`);
+    console.log(`\n  ${c.dim}Run with --format json for hashes, machine-readable reasons, assurance, and navigation.${c.reset}`);
+    return packet;
+  }
+
   // Allow `--profile <name>` to preview a profile's plan without having to run
   // `init` first (the field-report agent had no config yet on its first call).
   const cfg = flags.profile ? { ...config, profile: flags.profile } : config;

package/cli/commands/explain.mjs

@@ -1,4 +1,5 @@
 /**
+ * @implements docguard.evidence-scoped-verification#FR-013
  * Explain Command — v0.16-P6.
  *
  * Asked for by a user who'd spent 5-10 minutes per warning spelunking
@@ -278,6 +279,20 @@ const EXPLAINERS = {
     example: '`docguard specs preflight --path specs/007-feature/spec.md` blocks reused IDs and reports prior lifecycle/evidence before planning.',
     standard: 'Canonical-Driven Development lifecycle registry contract',
   },
+  evidence: {
+    title: 'Evidence — declared statements match bounded local sources',
+    what: 'Evaluates opt-in declarations in `.docguard-evidence.json`. Each declaration selects one exact statement under one Markdown heading, reads a bounded local JSON value, file collection, saved oasdiff report, or saved Buf report, and reports verified-within-scope, contradicted, stale, inconclusive, or unsupported.',
+    why: 'Structural checks can prove that documentation exists and is connected, but they cannot prove factual claims. Evidence declarations add reproducible checks for selected high-value statements without claiming that the whole document is accurate.',
+    triggers: [
+      ['Evidence manifest is invalid', 'Validate `.docguard-evidence.json` against `schemas/docguard-evidence.schema.json`; unknown fields and ambiguous declarations fail closed.'],
+      ['Declared evidence contradicts', 'Inspect the selected statement and source. Update the implementation when the canonical statement is still intended, or revise the statement through the normal reviewed documentation workflow.'],
+      ['Declared evidence is stale', 'Regenerate the saved external-tool report from the declared inputs and update their SHA-256 digests.'],
+      ['Declared evidence is inconclusive', 'Repair the missing or ambiguous heading/statement, unreadable source, unsafe collection, or malformed saved report before relying on the declaration.'],
+      ['Declared evidence uses an unsupported', 'Use a documented adapter version and command, or upgrade DocGuard when support for that producer shape becomes available.'],
+    ],
+    example: 'A retention statement under `## Policy` declares JSON Pointer `/retentionDays`; `docguard verify --evidence` reports verified-within-scope only when the exact typed values match.',
+    standard: 'RFC 6901 JSON Pointer; JSON Schema 2020-12; DocGuard evidence-scoping contract',
+  },
 
   // ── Backfilled in v0.24 (field report, Issue A) ─────────────────────────
   // These validators were registered in guard but had no explain entry, so
@@ -410,6 +425,7 @@ const DISPLAY_NAMES = {
   surfaceSync: 'Surface-Sync',
   canonicalSync: 'Canonical-Sync',
   metricsConsistency: 'Metrics-Consistency',
+  evidence: 'Evidence',
   diffSuspicion: 'Diff-Suspicion',
   referenceExistence: 'Reference-Existence',
   apiDocSmells: 'API-Doc-Smells',

package/cli/commands/fix.mjs

@@ -1,4 +1,8 @@
-import { assertDefaultDocWrites } from '../shared-doc-roles.mjs';
+/**
+ * @implements docguard.language-repository-coverage#FR-010
+ * @implements docguard.language-repository-coverage#FR-011
+ */
+import { assertMappedFullDocumentWrites, docRolePath, isMappedDocPath, resolveDocRole } from '../shared-doc-roles.mjs';
 /**
  * Fix Command — The AI Orchestrator
  * 
@@ -14,7 +18,7 @@ import { assertDefaultDocWrites } from '../shared-doc-roles.mjs';
  *   --auto          Create skeleton files (NOT content) via init
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { existsSync, readFileSync, mkdirSync } from 'node:fs';
 import { resolve, basename, dirname } from 'node:path';
 import { execSync, execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -23,10 +27,9 @@ import { computeApiSurfaceDrift } from '../validators/api-surface.mjs';
 import { removeEndpoints, hasGeneratedMarker } from '../writers/api-reference.mjs';
 import { applyMechanicalFixes } from '../writers/mechanical.mjs';
 import { loadFixMemory } from '../writers/fix-memory.mjs';
+import { safeWrite } from '../writers/generate-io.mjs';
 import { runGuardInternal } from './guard.mjs';
 
-const API_DOC = 'docs-canonical/API-REFERENCE.md';
-
 /**
  * Apply DETERMINISTIC, no-LLM API-surface fixes: remove endpoints documented in
  * API-REFERENCE.md that the OpenAPI spec confirms no longer exist. Removes the
@@ -38,13 +41,13 @@ const API_DOC = 'docs-canonical/API-REFERENCE.md';
  * @returns {{ applied: boolean, removed: Array<{method,path}>, skipped?: string }}
  */
 export function applyApiSurfaceWrites(projectDir, config, { force = false } = {}) {
-  assertDefaultDocWrites(config);
   const drift = computeApiSurfaceDrift(projectDir, config);
   // Only spec-confirmed absences are safe to delete deterministically.
   const removable = drift.confidence === 'spec' ? drift.documentedButAbsent : [];
   if (removable.length === 0) return { applied: false, removed: [] };
 
-  const apiDocPath = resolve(projectDir, API_DOC);
+  const apiDoc = docRolePath(config, 'apiReference');
+  const apiDocPath = resolveDocRole(projectDir, config, 'apiReference');
   if (!existsSync(apiDocPath)) return { applied: false, removed: [] };
 
   const content = readFileSync(apiDocPath, 'utf-8');
@@ -52,17 +55,18 @@ export function applyApiSurfaceWrites(projectDir, config, { force = false } = {}
     return {
       applied: false,
       removed: [],
-      skipped: `${API_DOC} is not marked '<!-- docguard:generated true -->'. ` +
+      skipped: `${apiDoc} is not marked '<!-- docguard:generated true -->'. ` +
         `Re-run with --force to edit it, or fix it via an AI agent (/docguard.fix --doc api-reference).`,
     };
   }
+  if (isMappedDocPath(config, apiDoc)) assertMappedFullDocumentWrites(projectDir, config, ['apiReference']);
 
   const { content: newContent, removed } = removeEndpoints(content, removable);
   if (removed.length === 0 || newContent === content) {
     return { applied: false, removed: [] }; // idempotent no-op
   }
 
-  writeFileSync(apiDocPath, newContent, 'utf-8');
+  safeWrite(apiDocPath, newContent);
   // Map removed keys back to {method,path} for reporting.
   const removedEndpoints = removable.filter(e => removed.includes(`${e.method.toUpperCase()} ${normalizeForKey(e.path)}`));
   return { applied: true, removed: removedEndpoints.length ? removedEndpoints : removable };
@@ -275,7 +279,6 @@ IMPORTANT: A new contributor should be able to follow this doc and have the proj
  * @returns {{ applied: object[], skipped: object[], total: number }}
  */
 export function applyAllMechanicalFixes(projectDir, config, opts = {}) {
-  assertDefaultDocWrites(config);
   const { force = false, forceRedo = false } = opts;
   const guardData = runGuardInternal(projectDir, config);
   const fixes = [];
@@ -284,7 +287,7 @@ export function applyAllMechanicalFixes(projectDir, config, opts = {}) {
   }
   // v0.14-P1: forwarding forceRedo so users with `--force-redo` can override
   // ping-pong suppression for a specific fix they actually want re-applied.
-  const { applied, skipped } = applyMechanicalFixes(projectDir, fixes, { force, forceRedo });
+  const { applied, skipped } = applyMechanicalFixes(projectDir, fixes, { force, forceRedo, config });
   return { applied, skipped, total: fixes.length };
 }
 
@@ -375,7 +378,6 @@ function runWriteMode(projectDir, config, flags) {
 // ── Main Entry ─────────────────────────────────────────────────────────────
 
 export function runFix(projectDir, config, flags) {
-  if (flags.write) assertDefaultDocWrites(config);
   const isJson = flags.format === 'json';
   const isPrompt = flags.format === 'prompt';
   const autoFix = flags.auto || false;

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