docguard-cli 0.39.0 → 0.40.1

package/cli/writers/doc-generators.mjs

@@ -1,4 +1,7 @@
 /**
+ * @implements docguard.language-repository-coverage#FR-010
+ * @implements docguard.language-repository-coverage#FR-011
+ *
  * Document Generators — the seven doc emitters behind `docguard generate`:
  * ARCHITECTURE, API-REFERENCE, DATA-MODEL, ENVIRONMENT, TEST-SPEC, SECURITY,
  * plus the root files (AGENTS.md, CHANGELOG.md, DRIFT-LOG.md).
@@ -12,15 +15,17 @@ import { resolve, basename, extname } from 'node:path';
 import { c } from '../shared.mjs';
 import { generateERDiagram } from '../scanners/schemas.mjs';
 import { safeWrite, appendStandardsCitation } from './generate-io.mjs';
+import { assertMappedFullDocumentWrites, docRolePath, resolveDocRole } from '../shared-doc-roles.mjs';
 
 // ── Document Generators ────────────────────────────────────────────────────
 
 export function generateArchitecture(dir, config, stack, scan, flags, docTools) {
-  const path = resolve(dir, 'docs-canonical/ARCHITECTURE.md');
+  const path = resolveDocRole(dir, config, 'architecture');
   if (existsSync(path) && !flags.force) {
     console.log(`  ${c.dim}⏭️  ARCHITECTURE.md (exists)${c.reset}`);
     return false;
   }
+  assertMappedFullDocumentWrites(dir, config, ['architecture']);
 
   const techRows = Object.entries(stack)
     .filter(([, v]) => v)
@@ -182,7 +187,7 @@ See \\\`docs-canonical/ADR.md\\\` for the full decision log.
 ## 10. Quality Requirements
 <!-- arc42: §10 — Quality Requirements -->
 
-See \\\`docs-canonical/TEST-SPEC.md\\\` for test requirements and coverage targets.
+See \\\`${docRolePath(config, 'testSpec')}\\\` for test requirements and coverage targets.
 
 ## 11. Risks & Technical Debt
 <!-- arc42: §11 — Risk Assessment and Technical Debt -->
@@ -216,11 +221,12 @@ See \\\`docs-canonical/KNOWN-GOTCHAS.md\\\` for known issues.
 // ── API Reference Generator (NEW — from deep route scanning) ───────────────
 
 export function generateApiReference(dir, config, stack, deepRoutes, flags) {
-  const path = resolve(dir, 'docs-canonical/API-REFERENCE.md');
+  const path = resolveDocRole(dir, config, 'apiReference');
   if (existsSync(path) && !flags.force) {
     console.log(`  ${c.dim}⏭️  API-REFERENCE.md (exists)${c.reset}`);
     return false;
   }
+  assertMappedFullDocumentWrites(dir, config, ['apiReference']);
 
   // Group routes by resource (first path segment after /api/)
   const groups = {};
@@ -313,11 +319,12 @@ ${resourceSections}
 // ── Enhanced Data Model Generator ──────────────────────────────────────────
 
 export function generateDataModel(dir, config, stack, scan, flags, deepSchemas) {
-  const path = resolve(dir, 'docs-canonical/DATA-MODEL.md');
+  const path = resolveDocRole(dir, config, 'dataModel');
   if (existsSync(path) && !flags.force) {
     console.log(`  ${c.dim}⏭️  DATA-MODEL.md (exists)${c.reset}`);
     return false;
   }
+  assertMappedFullDocumentWrites(dir, config, ['dataModel']);
 
   // Use deep schemas if available, fallback to basic scan
   let entities = [];
@@ -466,11 +473,12 @@ ${erDiagram}
 }
 
 export function generateEnvironment(dir, config, stack, scan, flags) {
-  const path = resolve(dir, 'docs-canonical/ENVIRONMENT.md');
+  const path = resolveDocRole(dir, config, 'environment');
   if (existsSync(path) && !flags.force) {
     console.log(`  ${c.dim}⏭️  ENVIRONMENT.md (exists)${c.reset}`);
     return false;
   }
+  assertMappedFullDocumentWrites(dir, config, ['environment']);
 
   const envVarRows = scan.envVars.map(v =>
     `| \`${v.name}\` | ${categorizeEnvVar(v.name)} | Yes | \`${v.example}\` | |`
@@ -529,11 +537,12 @@ ${envVarRows || '| <!-- No .env.example found --> | | | | |'}
 }
 
 export function generateTestSpec(dir, config, stack, scan, flags) {
-  const path = resolve(dir, 'docs-canonical/TEST-SPEC.md');
+  const path = resolveDocRole(dir, config, 'testSpec');
   if (existsSync(path) && !flags.force) {
     console.log(`  ${c.dim}⏭️  TEST-SPEC.md (exists)${c.reset}`);
     return false;
   }
+  assertMappedFullDocumentWrites(dir, config, ['testSpec']);
 
   // Build service-to-test map
   const serviceMap = [];
@@ -614,11 +623,12 @@ ${serviceRows || '| <!-- No services found --> | | | |'}
 }
 
 export function generateSecurity(dir, config, stack, scan, flags) {
-  const path = resolve(dir, 'docs-canonical/SECURITY.md');
+  const path = resolveDocRole(dir, config, 'security');
   if (existsSync(path) && !flags.force) {
     console.log(`  ${c.dim}⏭️  SECURITY.md (exists)${c.reset}`);
     return false;
   }
+  assertMappedFullDocumentWrites(dir, config, ['security']);
 
   const content = `# Security
 
@@ -682,6 +692,15 @@ ${scan.envVars.filter(v => isSecretVar(v.name)).map(v =>
 export function generateRootFiles(dir, config, stack, scan, flags, docTools) {
   let created = 0;
   let skipped = 0;
+  const canonicalFiles = [
+    [docRolePath(config, 'architecture'), 'System design (arc42 aligned)'],
+    [docRolePath(config, 'apiReference'), 'API endpoint documentation'],
+    [docRolePath(config, 'dataModel'), 'Database schemas & entities'],
+    [docRolePath(config, 'security'), 'Auth & secrets'],
+    [docRolePath(config, 'testSpec'), 'Test requirements'],
+    [docRolePath(config, 'environment'), 'Environment setup'],
+  ];
+  const canonicalRows = canonicalFiles.map(([path, purpose]) => `| \`${path}\` | ${purpose} |`).join('\n');
 
   // AGENTS.md (AGENTS.md Standard compliant)
   const agentsPath = resolve(dir, 'AGENTS.md');
@@ -696,7 +715,7 @@ export function generateRootFiles(dir, config, stack, scan, flags, docTools) {
 
 ## Workflow
 
-1. **Read** \`docs-canonical/\` before suggesting changes
+1. **Read** the configured canonical files under **Key Files** before suggesting changes
 2. **Check** existing patterns in the codebase
 3. **Run** \`npx docguard-cli diagnose\` to see what needs fixing
 4. **Confirm** your approach before writing code
@@ -712,12 +731,7 @@ ${Object.entries(stack).filter(([, v]) => v).map(([k, v]) => `- **${k}**: ${v}`)
 
 | File | Purpose |
 |------|---------|
-| \`docs-canonical/ARCHITECTURE.md\` | System design (arc42 aligned) |
-| \`docs-canonical/API-REFERENCE.md\` | API endpoint documentation |
-| \`docs-canonical/DATA-MODEL.md\` | Database schemas & entities |
-| \`docs-canonical/SECURITY.md\` | Auth & secrets |
-| \`docs-canonical/TEST-SPEC.md\` | Test requirements |
-| \`docs-canonical/ENVIRONMENT.md\` | Environment setup |
+${canonicalRows}
 | \`AGENTS.md\` | AI agent instructions (this file) |
 | \`CHANGELOG.md\` | Change tracking |
 | \`DRIFT-LOG.md\` | Documented deviations |
@@ -729,7 +743,7 @@ ${Object.entries(stack).filter(([, v]) => v).map(([k, v]) => `- **${k}**: ${v}`)
 ### Allowed
 
 - Read any file in the repository
-- Modify files within \`src/\`, \`tests/\`, and \`docs-canonical/\`
+- Modify files within \`src/\`, \`tests/\`, and the configured canonical documentation paths
 - Run test commands (\`npm test\`, \`npx docguard-cli guard\`)
 - Create new files in appropriate directories
 
@@ -780,8 +794,8 @@ npx docguard-cli generate       # Generate docs from code
 
 - Never commit without updating CHANGELOG.md
 - If code deviates from docs, add \`// DRIFT: reason\`
-- Security rules in SECURITY.md are mandatory
-- Test requirements in TEST-SPEC.md must be met
+- Security rules in \`${docRolePath(config, 'security')}\` are mandatory
+- Test requirements in \`${docRolePath(config, 'testSpec')}\` must be met
 - Documentation changes must pass \`docguard guard\`
 `;
     safeWrite(agentsPath, content);

package/cli/writers/mechanical.mjs

@@ -1,4 +1,8 @@
 /**
+ * @implements docguard.language-repository-coverage#FR-009
+ * @implements docguard.language-repository-coverage#FR-010
+ * @implements docguard.language-repository-coverage#FR-011
+ *
  * Mechanical Fix Registry — applies deterministic, no-LLM fixes in place.
  *
  * Validators surface structured `fixes[]` actions; this module knows how to
@@ -37,16 +41,30 @@ try {
   _sectionsModule = null;
 }
 
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { removeEndpoints, hasGeneratedMarker } from './api-reference.mjs';
+import { safeWrite } from './generate-io.mjs';
+import { assertMappedFullDocumentWrites, isMappedDocPath, mappedRolesForPath } from '../shared-doc-roles.mjs';
+
+function authorizeMappedWholeDocument(projectDir, config, path) {
+  if (!isMappedDocPath(config, path)) return null;
+  try {
+    assertMappedFullDocumentWrites(projectDir, config, mappedRolesForPath(config, path));
+    return null;
+  } catch (error) {
+    return error.message;
+  }
+}
 
 const esc = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
 /** replace-count: "<found> <label>" → "<actual> <label>" in the file. */
-function applyReplaceCount(projectDir, fix) {
+function applyReplaceCount(projectDir, fix, opts = {}) {
   const full = resolve(projectDir, fix.file);
   if (!existsSync(full)) return { applied: false };
+  const blocked = authorizeMappedWholeDocument(projectDir, opts.config, fix.file);
+  if (blocked) return { applied: false, skipped: blocked };
   // Bug #2 (fail-closed): NEVER overwrite a number without provenance proving
   // the "actual" describes the SAME subject. The Metrics-Consistency validator
   // stamps `actualSource` (e.g. "docguard.guard.checks") only for claims it
@@ -74,14 +92,16 @@ function applyReplaceCount(projectDir, fix) {
     return `${fix.actual}${tail}`;
   });
   if (!changed || next === content) return { applied: false };
-  writeFileSync(full, next, 'utf-8');
+  safeWrite(full, next);
   return { applied: true, detail: `${fix.file}: "${fix.found} ${fix.label}" → "${fix.actual} ${fix.label}"` };
 }
 
 /** replace-version: stale version → current, ONLY in actionable contexts. */
-function applyReplaceVersion(projectDir, fix) {
+function applyReplaceVersion(projectDir, fix, opts = {}) {
   const full = resolve(projectDir, fix.file);
   if (!existsSync(full)) return { applied: false };
+  const blocked = authorizeMappedWholeDocument(projectDir, opts.config, fix.file);
+  if (blocked) return { applied: false, skipped: blocked };
   const content = readFileSync(full, 'utf-8');
   const f = esc(fix.found);
   // Mirror metadata-sync's actionable detection so we never touch prose.
@@ -93,7 +113,7 @@ function applyReplaceVersion(projectDir, fix) {
   let next = content;
   for (const re of patterns) next = next.replace(re, `$1${fix.actual}`);
   if (next === content) return { applied: false };
-  writeFileSync(full, next, 'utf-8');
+  safeWrite(full, next);
   return { applied: true, detail: `${fix.file}: v${fix.found} → v${fix.actual}` };
 }
 
@@ -112,21 +132,23 @@ function applyInsertChangelogUnreleased(projectDir, fix) {
   }
   const block = idx > 0 && lines[idx - 1].trim() !== '' ? ['', '## [Unreleased]', ''] : ['## [Unreleased]', ''];
   lines.splice(idx, 0, ...block);
-  writeFileSync(full, lines.join('\n'), 'utf-8');
+  safeWrite(full, lines.join('\n'));
   return { applied: true, detail: `${fix.file}: added ## [Unreleased]` };
 }
 
 /** remove-endpoint: delegate to the API-REFERENCE writer (marker-gated). */
-function applyRemoveEndpoint(projectDir, fix, { force = false } = {}) {
+function applyRemoveEndpoint(projectDir, fix, { force = false, config = {} } = {}) {
   const full = resolve(projectDir, fix.doc || 'docs-canonical/API-REFERENCE.md');
   if (!existsSync(full)) return { applied: false };
+  const blocked = authorizeMappedWholeDocument(projectDir, config, fix.doc || 'docs-canonical/API-REFERENCE.md');
+  if (blocked) return { applied: false, skipped: blocked };
   const content = readFileSync(full, 'utf-8');
   if (!hasGeneratedMarker(content) && !force) {
     return { applied: false, skipped: `${fix.doc} not docguard:generated (use --force)` };
   }
   const { content: next, removed } = removeEndpoints(content, [{ method: fix.method, path: fix.path }]);
   if (removed.length === 0 || next === content) return { applied: false };
-  writeFileSync(full, next, 'utf-8');
+  safeWrite(full, next);
   return { applied: true, detail: `${fix.doc}: removed ${fix.method} ${fix.path}` };
 }
 
@@ -142,7 +164,7 @@ function applyRemoveEndpoint(projectDir, fix, { force = false } = {}) {
  *
  * fix shape: { type: 'regenerate-section', doc, sectionId, body }
  */
-function applyRegenerateSection(projectDir, fix) {
+function applyRegenerateSection(projectDir, fix, opts = {}) {
   if (!fix.doc || !fix.sectionId || fix.body == null) {
     return { applied: false, skipped: 'regenerate-section needs doc, sectionId, body' };
   }
@@ -152,17 +174,23 @@ function applyRegenerateSection(projectDir, fix) {
   // Lazy-import the section writer to avoid a top-level circular risk.
   // section APIs are synchronous and well-isolated; this works because
   // mechanical.mjs already uses top-level await for fix-memory.
-  const { getSection, replaceSection } = _sectionsModule || {};
-  if (typeof getSection !== 'function' || typeof replaceSection !== 'function') {
+  const { assertOwnedCodeSection, getSection, replaceSection } = _sectionsModule || {};
+  if (typeof getSection !== 'function' || typeof replaceSection !== 'function' || typeof assertOwnedCodeSection !== 'function') {
     return { applied: false, skipped: 'sections module unavailable' };
   }
   const existing = getSection(content, fix.sectionId);
   if (!existing) return { applied: false, skipped: `section ${fix.sectionId} not present in ${fix.doc}` };
+  if (isMappedDocPath(opts.config, fix.doc)) {
+    try { assertOwnedCodeSection(content, fix.sectionId, fix.doc); }
+    catch (error) { return { applied: false, skipped: error.message }; }
+  } else if (existing.source !== 'code') {
+    return { applied: false, skipped: `${fix.doc}: section ${fix.sectionId} is not source=code` };
+  }
   if (existing.body.trim() === String(fix.body).trim()) {
     return { applied: false, skipped: `${fix.doc} § ${fix.sectionId} already current` };
   }
   const next = replaceSection(content, fix.sectionId, fix.body).content;
-  writeFileSync(full, next, 'utf-8');
+  safeWrite(full, next);
   return { applied: true, detail: `${fix.doc}: regenerated § ${fix.sectionId}` };
 }
 
@@ -177,12 +205,14 @@ function applyRegenerateSection(projectDir, fix) {
  * forms — won't touch the broken slug if it happens to appear as plain text.
  * Idempotent: if no occurrence is found (already fixed), no-op.
  */
-function applyReplaceAnchor(projectDir, fix) {
+function applyReplaceAnchor(projectDir, fix, opts = {}) {
   if (!fix.doc || !fix.from || !fix.to) {
     return { applied: false, skipped: 'replace-anchor needs doc, from, to' };
   }
   const full = resolve(projectDir, fix.doc);
   if (!existsSync(full)) return { applied: false, skipped: `doc not found: ${fix.doc}` };
+  const blocked = authorizeMappedWholeDocument(projectDir, opts.config, fix.doc);
+  if (blocked) return { applied: false, skipped: blocked };
   const content = readFileSync(full, 'utf-8');
 
   // Match an anchor inside a markdown link: `](#from)` OR `](path#from)`.
@@ -194,7 +224,7 @@ function applyReplaceAnchor(projectDir, fix) {
   if (next === content) {
     return { applied: false, skipped: `${fix.doc}: anchor #${fix.from} not found (already fixed?)` };
   }
-  writeFileSync(full, next, 'utf-8');
+  safeWrite(full, next);
   return { applied: true, detail: `${fix.doc}: #${fix.from} → #${fix.to}` };
 }
 

package/cli/writers/sections.mjs

@@ -53,8 +53,14 @@ function parseAttrs(attrStr) {
  * @returns {Array<{ id, source, attrs, openLine, closeLine, body }>}
  */
 export function parseSections(content) {
+  return inspectSections(content).sections;
+}
+
+/** Parse sections and retain malformed-marker evidence for write authorization. */
+export function inspectSections(content) {
   const lines = String(content).split('\n');
   const sections = [];
+  const issues = [];
   let open = null;
 
   for (let i = 0; i < lines.length; i++) {
@@ -70,17 +76,39 @@ export function parseSections(content) {
           body: lines.slice(open.openLine + 1, i).join('\n'),
         });
         open = null;
-      }
-      // A close with no matching open is ignored.
+      } else issues.push({ code: 'unmatched-close', line: i + 1 });
       continue;
     }
     const om = line.match(OPEN_RE);
     if (om) {
       // Abandon any still-open (malformed) section; start fresh here.
+      if (open !== null) issues.push({ code: 'nested-or-unclosed', line: open.openLine + 1 });
       open = { attrs: parseAttrs(om[1] || ''), openLine: i };
     }
   }
-  return sections;
+  if (open !== null) issues.push({ code: 'unclosed', line: open.openLine + 1 });
+  const counts = new Map();
+  for (const section of sections) {
+    if (!section.id) issues.push({ code: 'missing-id', line: section.openLine + 1 });
+    counts.set(section.id, (counts.get(section.id) || 0) + 1);
+  }
+  for (const [id, count] of counts) if (id && count > 1) issues.push({ code: 'duplicate-id', id, count });
+  return { sections, issues };
+}
+
+/**
+ * Return the unique code-owned section or throw before a mapped write.
+ * @implements docguard.language-repository-coverage#FR-009
+ */
+export function assertOwnedCodeSection(content, id, path = 'document') {
+  const inspected = inspectSections(content);
+  if (inspected.issues.length) {
+    throw new Error(`${path}: malformed or duplicate docguard:section markers; no write was applied.`);
+  }
+  const matches = inspected.sections.filter(section => section.id === id);
+  if (matches.length !== 1) throw new Error(`${path}: section ${id} must exist exactly once before a bounded write.`);
+  if (matches[0].source !== 'code') throw new Error(`${path}: section ${id} is source=${matches[0].source}; only source=code is writable.`);
+  return matches[0];
 }
 
 /** Get a single section by id, or null. */

package/docs/ai-integration.md

@@ -18,6 +18,7 @@ what it finds. The division of labour never changes:
 | GitHub Code Scanning / SARIF dashboards | **SARIF output** | `npx docguard-cli guard --format sarif` |
 | A PR reviewer (human or bot) | **GitHub Action** | inline annotations + sticky doc-impact comment, default on |
 | An LLM reading the repo cold | **llms.txt / llms-full.txt / context pack** | `docguard llms`, `llms --full`, `memory --pack` |
+| An agent starting one concrete change | **Task context** | `docguard agent --task "Implement acme.feature#FR-001" --format json` |
 
 ## MCP server (native tools, no shelling out)
 
@@ -28,14 +29,16 @@ claude mcp add docguard -- npx docguard-cli mcp
 npx docguard-cli mcp
 ```
 
-Five tools, each accepting an optional `projectDir`:
+Seven tools, each accepting an optional `projectDir`:
 
 | Tool | Returns |
 |------|---------|
 | `docguard_guard` | The full guard JSON contract — status, findings (stable codes), coverage, unverified-claim count |
 | `docguard_score` | `{score, grade, categories}` |
 | `docguard_explain` | A finding code's contract: title, help, suppression pragma, owning validator |
+| `docguard_verify_evidence` | Exact declared statement-to-source checks with scoped verification states |
 | `docguard_verify_claims` | Documented numbers/limits/enums as verification tasks — **the caller checks each against the code** |
+| `docguard_report` | Commit-stamped compliance evidence with a tamper-evident integrity hash |
 | `docguard_diagnose` | Failing/warning validators with per-finding suggestions, shaped for action |
 
 The server is read-only (never scaffolds), keeps stdout as a pure JSON-RPC
@@ -108,10 +111,25 @@ and degrade gracefully on fork tokens and shallow clones.
 | `llms-full.txt` | `docguard llms --full` | Full doc bodies inlined — one fetch, per-doc 400-line cap |
 | `.docguard/context-pack.md` | `docguard memory --pack` | Compact session-start context: guard status, scanner-derived surface counts, doc index with review dates, your AGENTS.md rules verbatim, known drift. Everything derived from code — regenerable, hallucination-free |
 | `.docguard-specs.json` | `docguard specs --check` / `--write` | Committed spec lifecycle index: reviewed status and lineage plus deterministic artifact, task, and requirement-scoped test evidence. Requirement prose stays in each authoritative spec. |
+| Task-context JSON | `docguard agent --task <text> --format json` | Read-only, bounded excerpts from approved current evidence plus source/test pointers. It excludes retired and unsafe material and abstains when relevance is weak. |
 
 Load the context pack at agent session start; regenerate any time — it is
 never hand-edited.
 
+For a concrete change, task context can reduce discovery steps:
+
+```bash
+docguard agent --task "Implement acme.payments#FR-003 in src/payments.mjs" --format json
+```
+
+Treat the packet as a retrieval aid. Hashes prove which bytes were selected;
+they do not prove the prose is correct. Read additional code or documentation
+when the task requires it, and use the navigation map when the selector
+abstains. Protocol v1 preserved all 27 synthetic task outcomes and reduced
+median steps by 50% and latency by 17% versus `memory --pack`, but increased
+median uncached input tokens by 80%; teams optimizing token spend may prefer
+the context pack.
+
 ## One source of truth for agent files
 
 Teams hand-duplicate AGENTS.md into `CLAUDE.md`, `.cursor/rules/`,
@@ -135,7 +153,7 @@ is the canonical source.
 ## The agent workflow
 
 ```
-specs preflight → diagnose → fix (research + write) → guard → verify --semantic → done
+specs preflight → diagnose → fix (research + write) → guard → verify --evidence → verify --semantic → done
 ```
 
 1. **`docguard specs preflight`** — before specification, load the current intent
@@ -146,7 +164,10 @@ specs preflight → diagnose → fix (research + write) → guard → verify --s
 3. **`docguard fix --doc <name>`** — emits research steps + expected structure
    for one doc. Execute the research, write real content, no placeholders.
 4. **`docguard guard`** — verify. Loop until PASS.
-5. **`docguard verify --semantic`** — extract every checkable documented claim
+5. **`docguard verify --evidence`** — evaluate exact, typed declarations against
+   local JSON, bounded collections, or saved compatibility reports. Preserve
+   each state and its statement-level scope.
+6. **`docguard verify --semantic`** — extract every remaining checkable documented claim
    (counts, limits, enums) with the nearest cited code path. **You** compare
    each value against the code: a green guard asserts structure, not the truth
    of documented numbers. This is the highest-value step an agent can run.
@@ -183,9 +204,13 @@ integrity. Each failing metric names its fix.
    acting, suppress at the site with it, report false positives via `feedback`.
 3. **Run `guard` after every fix batch** — loop until PASS.
 4. **Never treat `na` as a pass** — "nothing to validate" is a coverage gap.
-5. **Check `semanticClaims.count` on green runs** — offer `verify --semantic`.
-6. **Respect the drift protocol** — deviating from canonical docs requires
+5. **Inspect `evidence` on every configured run** — resolve contradictions,
+   stale inputs, inconclusive targets, and unsupported formats before claiming
+   the selected statement is current.
+6. **Check `semanticClaims.count` on green runs** — run `verify --semantic` for
+   the claims that lack unique exact evidence.
+7. **Respect the drift protocol** — deviating from canonical docs requires
    `// DRIFT: reason` + a DRIFT-LOG.md entry, not a silent doc rewrite; the
    docs may be right and the code wrong.
-7. **`score --tax`** periodically — documentation should stay an asset, not a
+8. **`score --tax`** periodically — documentation should stay an asset, not a
    burden.

package/docs/commands.md

@@ -170,9 +170,11 @@ the same local ID commonly appears in several specs.
 
 The generated-spec preflight blocks missing or duplicate identity, stale
 registry state, unsafe paths, and broken lifecycle lineage. Text similarity is
-low-confidence review context and never blocks by itself. A future
-`specs complete` transaction will verify exact-revision implementation evidence,
-canonical outcomes, and context regeneration before marking a spec verified.
+low-confidence review context and never blocks by itself. `specs complete`
+verifies exact-revision implementation evidence, canonical outcomes, and context
+regeneration before marking a spec verified; `--write` requires a reviewed
+reason and performs the registry, spec outcome, and current-context writes as
+one rollback-safe transaction.
 
 ### `docguard retire`
 
@@ -219,6 +221,26 @@ npx docguard-cli fix --doc environment
 
 **Output includes:** TASK, PURPOSE, RESEARCH STEPS (what to grep/read), WRITE THE DOCUMENT (expected sections).
 
+### `docguard agent`
+
+**Build an agent task graph or select bounded evidence for one task.** Existing
+task-graph behavior is unchanged when `--task` is absent.
+
+```bash
+npx docguard-cli agent
+npx docguard-cli agent --format json
+npx docguard-cli agent --task "Implement acme.payments#FR-003 in src/payments.mjs"
+npx docguard-cli agent --task "Fix SEC001 in src/config.mjs" --format json
+```
+
+Task mode reads only configured canonical documents, approved current specs,
+project rules, and exact linked source/test pointers. It excludes retired,
+unapproved, digest-stale, private, unsafe, and symlinked material. JSON output
+uses `schemas/docguard-task-context.schema.json`, contains a task digest instead
+of raw task text, and reports retrieval-only assurance. When no excerpt reaches
+the frozen relevance threshold, it returns `selection.status: "abstained"` with
+a navigation map rather than weak context.
+
 ### `docguard agents`
 
 **Generate agent-specific config files** from AGENTS.md.
@@ -237,7 +259,8 @@ never touched without `--force`.
 
 **MCP server over stdio** — DocGuard's read-only core as native agent tools
 (`docguard_guard`, `docguard_score`, `docguard_explain`,
-`docguard_verify_claims`, `docguard_report`, `docguard_diagnose`).
+`docguard_verify_evidence`, `docguard_verify_claims`, `docguard_report`,
+`docguard_diagnose`).
 
 ```bash
 claude mcp add docguard -- npx docguard-cli mcp
@@ -248,6 +271,14 @@ claude mcp add docguard -- npx docguard-cli mcp
 **Extract documented claims** (counts, limits, enums) as a verification task
 list with cited code paths — the agent checks each value against the code.
 
+### `docguard verify --evidence`
+
+**Evaluate exact declared evidence** from `.docguard-evidence.json`. Supported
+sources are typed RFC 6901 JSON values, bounded repository collections, saved
+oasdiff JSON, and saved Buf JSON Lines. Output preserves
+`verified-within-scope`, `contradicted`, `stale`, `inconclusive`, and
+`unsupported`; a pass applies only to its selected Markdown statement.
+
 ### `docguard explain <CODE>`
 
 **Explain any finding code** (`STR001`, `ENV003`, …): what it means, how to fix
@@ -342,7 +373,7 @@ npx docguard-cli diff
 
 | Flag | Description |
 |------|-------------|
-| `--dir <path>` | Project directory (default: current directory) |
+| `--dir <path>` | Project directory (default: current directory); explicit selection suppresses ancestor-root guidance |
 | `--format <type>` | Output format: `text` (default), `json`, `prompt` |
 | `--verbose` | Show detailed output |
 | `--profile <name>` | Compliance profile: `starter`, `standard`, `enterprise` |
@@ -356,3 +387,10 @@ npx docguard-cli diff
 | `--force` | Overwrite existing files |
 | `--help` | Show help |
 | `--version` | Show version |
+
+Without `--dir`, a command remains scoped to the current directory. DocGuard
+reads only bounded ancestors for an owning `.docguard.json`, npm `workspaces`, or
+pnpm `packages` declaration. When one includes the selected package, human
+stderr prints an exact `--dir` rerun; JSON/SARIF/JUnit runs receive a typed JSON
+diagnostic on stderr. Stdout and the selected scan scope do not change. A nested
+Git root prevents a suggestion from crossing into an outer repository.

package/docs/configuration.md

@@ -177,7 +177,15 @@ Use explicit document roles to validate Markdown files in an existing layout. A
 
 Supported roles are architecture, dataModel, security, testSpec, environment, apiReference, and requirements. Paths must name Markdown files within the project; private directories, parent traversal, absolute paths, and symlink destinations are rejected. Several roles may reference one document. Each role's content checks still apply; a mapping is not a correctness attestation. Default roles remain unchanged unless explicitly mapped.
 
-This first version supports validation, scoring, and read-only planning. Legacy automatic document generation, sync writes, and repair writes refuse custom mappings before scaffolding or modifying files. This protects existing documents while writer behavior is extended and reviewed. Read-only plans identify mapped destinations; a human or agent can review the proposed work against the existing document structure.
+Mapped paths use an explicit ownership contract for writes:
+
+- A missing mapped target may be generated when exactly one role maps to it.
+- An existing file with `<!-- docguard:generated true -->` grants DocGuard full-document ownership. Generation and mechanical whole-document repair keep their normal backup behavior.
+- An existing human document grants bounded ownership only through one unique, well-formed `<!-- docguard:section id=<id> source=code -->` region. `generate --plan --write`, `sync --write`, and section regeneration may replace that region while preserving every surrounding byte.
+- Missing, duplicate, nested, unclosed, or `source=human` markers reject the write before mutation. Several roles mapped to one file also reject whole-document generation.
+- `--force` never grants ownership and cannot bypass these checks.
+
+Broad legacy scaffolding such as `diagnose --auto` remains unavailable for a mapped layout because it cannot select an operation-specific owned target safely. Read-only plans identify mapped destinations without requiring ownership markers.
 
 The docs.dirs setting extends document inventory and explicitly opts additional directories into freshness review. Inventory membership does not mean every detector checks every file. Semantic extraction covers canonical Markdown, explicitly mapped Markdown roles, README, and AGENTS within its safety and size limits; other prose remains unverified.
 
@@ -195,9 +203,9 @@ These statuses skip currentness assertions; they do not hide structural or other
 
 ## Understanding check coverage
 
-Guard JSON includes checkCoverage and an applicability record per validator. States distinguish checked, partial, disabled, not-applicable, missing-prerequisite, unsupported, no-matches, and error. A passing gate means the selected policy passed; it does not mean unsupported languages or unmatched inputs were examined. CI and reports preserve this disclosure. Python import-graph analysis remains unsupported; mixed Python/JS projects disclose partial architecture coverage.
+Guard JSON includes checkCoverage and an applicability record per validator. States distinguish checked, partial, disabled, not-applicable, missing-prerequisite, unsupported, no-matches, and error. A passing gate means the selected policy passed; it does not mean unsupported languages or unmatched inputs were examined. CI and reports preserve this disclosure. Python architecture analysis uses the installed Python interpreter's AST without importing project modules. It resolves unique repository-local modules in regular flat and `src/` packages plus explicit relative imports. Dynamic imports, runtime `sys.path` changes, parser failure or absence, and ambiguous modules remain partial or unsupported coverage while supported edges and findings are retained.
 
-Wrangler configuration supplies evidence for Worker classification. Supported typed Worker bindings participate in environment extraction without executing configuration or application code. Dynamic names, alias/dataflow tracking, and unsupported forms remain outside this bounded analysis. The existing optional Babel parser resolves lexical bindings; the fallback covers ordinary tested scopes and has lower syntax coverage.
+Wrangler configuration supplies static evidence for Worker classification and untyped official handler arguments; DocGuard never executes configuration or application code. With the optional Babel parser, environment extraction recognizes module-handler `env`, exported Pages `onRequest*` `context.env`, `this.env` on classes extending an entrypoint imported from `cloudflare:workers`, and `env` imported from that module. Lexical aliases are followed and shadows are excluded. Computed non-literal keys, indirect exports, user-defined lookalike classes, and other runtimes remain outside the bounded analysis. The fallback covers ordinary handler `env` scopes and reports AST-only forms as partial coverage.
 
 ### Evidence boundaries in documentation and schema scans
 

package/docs/quickstart.md

@@ -68,7 +68,7 @@ diagnose  →  AI reads prompts  →  AI fixes docs  →  guard verifies
 ## Verify
 
 ```bash
-npx docguard-cli guard        # Pass/fail check (29 validators)
+npx docguard-cli guard        # Pass/fail check (30 validators)
 npx docguard-cli score        # 0-100 maturity score
 ```
 

package/extensions/spec-kit-docguard/commands/fix.md

@@ -30,7 +30,9 @@ npx --yes docguard-cli@latest fix --write
 ```
 
 Output lists every applied fix. Idempotent: re-running is a no-op if nothing changed.
-Only edits `<!-- docguard:generated true -->` docs unless `--force`.
+Whole-document fixes require `<!-- docguard:generated true -->`. A mapped human
+document permits only a unique `source=code` section fix; `--force` cannot grant
+ownership.
 
 ### Step 2 — Identify remaining issues by kind
 
@@ -70,5 +72,5 @@ Iterate until clean (max 3 rounds; if still failing, report remaining issues).
 
 - `--write` — apply deterministic fixes in place (step 1).
 - `--doc <name>` — emit a research-grounded prompt for one specific document (step 3).
-- `--force` — for `--write`, edit docs that lack the generated marker.
+- `--force` — for `--write`, permit supported unmarked default-path fixes; mapped ownership checks remain mandatory.
 - `--format json` — machine-readable issue list (with `fixKind`).

package/extensions/spec-kit-docguard/commands/generate.md

@@ -18,6 +18,11 @@ Two modes:
 - **`--plan`** (AI-powered, recommended) — emits a structured agent task manifest + writes the code-truth skeleton inside `<!-- docguard:section -->` markers. The AI agent then writes the prose grounded in scanned facts. Human prose is preserved.
 - **default** — purely deterministic generation: writes templated docs with TODO placeholders. Use when no AI agent is available.
 
+With `docs.roles`, a missing or explicitly generated single-role target can
+receive a full document. Existing human documents receive only bounded updates
+inside unique `source=code` sections. Shared roles and malformed markers fail
+before any mapped document is written, even with `--force`.
+
 ## User Input
 
 $ARGUMENTS
@@ -70,4 +75,4 @@ npx --yes docguard-cli@latest generate $ARGUMENTS
 ## Flags
 
 - `--doc <name>` — Generate a specific document only
-- `--dir <path>` — Run on a different directory
+- `--dir <path>` — Run on a different directory; explicit selection suppresses ancestor-root guidance