docguard-cli 0.38.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,14 +290,15 @@ 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` | Report likely false positives back to DocGuard — local-first record + a 1-click prefilled, redacted GitHub issue (zero typing) |
+| `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. |
 | `retire` | Find completed or superseded planning material (`--plan`/`--check`; `--fail-on-warning` gates advisory candidates) and explicitly remove clean tracked documentation from active AI context. `.docguard-archive.json` records recovery metadata and retired requirement identities, and `--retention-ref` proves the source revision remains reachable. This is separate from the Spec Kit Archive extension, which consolidates feature documents. |
 | `reconcile` | Build a read-only code↔spec review graph since a Git ref. Classifies mechanical facts, approved intent, decisions, unrelated changes, and unsupported evidence; `--write` applies only mechanical generated-section refreshes. |
-| `specs` | Maintain the versioned spec registry, preflight new specs, and apply evidence-gated completion transactions with bounded outcomes and active-context regeneration. |
+| `specs` | Maintain the versioned spec registry, preflight new specs, and apply evidence-gated completion transactions with bounded outcomes and active-context regeneration. Verified living specs can record later reviewed maintenance without reopening or duplicating the specification. |
 | `specs --check` / `specs --write` | Validate or refresh `.docguard-specs.json`, the byte-stable index of immutable spec IDs, reviewed lifecycle/lineage/scope, artifact digests, task state, explicitly scoped test evidence, and archive tombstones. Refreshes preserve the reviewed block. |
 | `specs preflight [--path <spec>]` | Before specification, print current spec lifecycle and evidence. Before planning, check the generated draft for structural blockers and report semantic overlap as review-only evidence. |
 | `mcp` | MCP server — exposes guard/score/explain/verify/report/diagnose as native tools for Claude, Cursor, and any MCP client. Stdio: `claude mcp add docguard -- npx docguard-cli mcp`. Team-shared HTTP: `docguard mcp --transport http --port 8585` (loopback by default; non-loopback binds require `--api-key`) |
@@ -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/feedback.mjs

@@ -12,15 +12,23 @@
  *
  * Nothing is transmitted automatically. This command never scaffolds skills
  * or edits source files. Zero npm dependencies — pure Node.js built-ins.
+ * @implements docguard.precision-evidence-loop#FR-012
+ * @implements docguard.precision-evidence-loop#FR-015
+ * @implements docguard.precision-evidence-loop#FR-016
  */
 
-import { existsSync, mkdirSync, readFileSync } from 'node:fs';
-import { resolve, dirname } from 'node:path';
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { resolve, dirname, join, relative, sep } from 'node:path';
+import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { c } from '../shared.mjs';
 import { CODES } from '../findings.mjs';
 import { safeWrite } from '../writers/generate-io.mjs';
 import { runGuardInternal } from './guard.mjs';
+import {
+  buildTestOnlyContribution, feedbackFindingIdentity, feedbackSearchUrls, parseFeedbackFixture,
+  reduceFixtureDeterministically,
+} from '../feedback-fixture.mjs';
 
 const _PKG = JSON.parse(
   readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json'), 'utf-8')
@@ -39,16 +47,20 @@ function shortId(str) {
 }
 
 /** Shared output deliberately excludes every source-derived string. */
-export function buildIssueUrl(finding) {
+export function buildIssueUrl(finding, context = null) {
   const code = Object.hasOwn(CODES, finding.code || '') ? finding.code : 'FINDING';
   const validator = CODES[code]?.validator || 'unknown';
-  const title = `[feedback] ${code} (${validator}): detection feedback`;
+  const classification = context?.classification || 'false_positive';
+  const title = `[feedback] ${code} (${validator}): ${classification.replaceAll('_', ' ')}`;
   const confidence = ['high', 'medium', 'low'].includes(finding.confidence) ? finding.confidence : 'unknown';
   const body = [
     `DocGuard v${CLI_VERSION}`,
     `- Code: ${code}`,
     `- Validator: ${validator}`,
     `- Confidence: ${confidence}`,
+    `- Classification: ${classification}`,
+    ...(context?.parserTier ? [`- Parser tier: ${context.parserTier}`] : []),
+    ...(context?.duplicateIdentity ? [`- Duplicate identity: ${context.duplicateIdentity}`] : []),
     '',
     'Expected behavior:',
     'Actual behavior:',
@@ -60,12 +72,139 @@ export function buildIssueUrl(finding) {
     'Generated by docguard feedback. No project paths, messages, source code, or secret values are included.',
   ].join('\n');
   const url = `${ISSUES_BASE}/new?labels=docguard-feedback&title=${encodeURIComponent(title)}&body=${encodeURIComponent(body)}`;
-  const query = `repo:raccioly/docguard ${code}`;
+  const query = context?.duplicateIdentity ? `repo:raccioly/docguard "${context.duplicateIdentity}"` : `repo:raccioly/docguard ${code}`;
   const searchUrl = `https://github.com/search?q=${encodeURIComponent(query)}&type=issues`;
   return { url: url.length <= URL_CAP ? url : `${ISSUES_BASE}/new`, title, searchUrl };
 }
 
+const FEEDBACK_CLASSES = new Set(['false_positive', 'false_negative', 'unsupported_syntax', 'ambiguous', 'policy_disagreement']);
+
+function projectFile(projectDir, value, label) {
+  if (typeof value !== 'string' || !value || value.includes('\\')) throw new Error(`${label} must be a project-relative path.`);
+  const root = resolve(projectDir);
+  const path = resolve(root, value);
+  const rel = relative(root, path);
+  if (!rel || rel.startsWith(`..${sep}`) || rel === '..' || rel.split(sep).some(part => ['.git', '.local'].includes(part.toLowerCase()))) {
+    throw new Error(`${label} must remain in the project and outside protected directories.`);
+  }
+  return path;
+}
+
+function evaluateFileSet(manifest, fileSet) {
+  const root = mkdtempSync(join(tmpdir(), 'docguard-feedback-fixture-'));
+  try {
+    for (const file of fileSet.files) {
+      const target = resolve(root, file.path);
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, file.content, 'utf8');
+    }
+    const report = runGuardInternal(root, manifest.config);
+    const validator = (report.validators || []).find(item => item.key === manifest.detector.validator);
+    return {
+      identities: (report.findings || []).filter(item => item.code === manifest.detector.code).map(feedbackFindingIdentity).sort(),
+      applicability: validator?.applicability?.status || 'unknown',
+    };
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function predicateMatches(manifest, result) {
+  if (manifest.interestingness.predicate === 'finding_present') return result.identities.includes(manifest.expectedIdentity);
+  if (manifest.interestingness.predicate === 'finding_absent') return !result.identities.includes(manifest.expectedIdentity);
+  return result.applicability === 'unsupported';
+}
+
+function oppositeMatches(manifest, result) {
+  if (manifest.interestingness.predicate === 'finding_present') return result.identities.includes(manifest.expectedIdentity);
+  if (manifest.interestingness.predicate === 'finding_absent') return !result.identities.includes(manifest.expectedIdentity);
+  return result.applicability === 'checked';
+}
+
+function runFixtureFeedback(projectDir, flags) {
+  let manifest;
+  try {
+    const manifestPath = projectFile(projectDir, flags.fixtureManifest, '--fixture-manifest');
+    if (!existsSync(manifestPath) || lstatSync(manifestPath).isSymbolicLink()) throw new Error('Fixture manifest must be a regular non-symlink file.');
+    const text = readFileSync(manifestPath, 'utf8');
+    if (Buffer.byteLength(text) > 262_144) throw new Error('Fixture manifest exceeds 256 KiB.');
+    manifest = parseFeedbackFixture(JSON.parse(text));
+    if (flags.classification && flags.classification !== manifest.classification) throw new Error('--classification disagrees with the fixture manifest.');
+  } catch (error) {
+    console.log(JSON.stringify({ status: 'ERROR', error: error.message }, null, 2));
+    process.exitCode = 1;
+    return;
+  }
+
+  const initial = evaluateFileSet(manifest, manifest.fixture);
+  const control = evaluateFileSet(manifest, manifest.oppositeControl);
+  const reproduced = predicateMatches(manifest, initial);
+  const controlConfirmed = oppositeMatches(manifest, control);
+  if (!reproduced || !controlConfirmed) {
+    console.log(JSON.stringify({
+      status: 'NOT_REPRODUCED', classification: manifest.classification,
+      reproductionConfirmed: reproduced, controlConfirmed,
+      message: 'The explicit predicate and opposite control must both reproduce before reduction or contribution.',
+    }, null, 2));
+    process.exitCode = 1;
+    return;
+  }
+
+  let reduction = null;
+  if (flags.reduce) {
+    reduction = reduceFixtureDeterministically(manifest, candidate => predicateMatches(candidate, evaluateFileSet(candidate, candidate.fixture)));
+    manifest = reduction.manifest;
+  }
+  const searches = feedbackSearchUrls(manifest, ISSUES_BASE);
+  const issue = buildIssueUrl({ code: manifest.detector.code, confidence: 'unknown' }, {
+    classification: manifest.classification, parserTier: manifest.parserTier, duplicateIdentity: searches.identity,
+  });
+  const feedbackDir = resolve(projectDir, '.docguard', 'feedback');
+  let record = null;
+  let contribution = null;
+  let contributionPreview = null;
+  try {
+    if (!flags.preview) {
+      record = resolve(feedbackDir, `${searches.identity}.fixture.json`);
+      safeWrite(record, `${JSON.stringify(manifest, null, 2)}\n`);
+    }
+    if (flags.contribution) {
+      if (!/^tests\/[^/]+\.test\.mjs$/.test(flags.contribution)) {
+        throw new Error('--contribution must be a direct tests/<name>.test.mjs path.');
+      }
+      contributionPreview = buildTestOnlyContribution(manifest);
+      if (!flags.preview) {
+        contribution = projectFile(projectDir, flags.contribution, '--contribution');
+        safeWrite(contribution, contributionPreview);
+      }
+    }
+  } catch (error) {
+    console.log(JSON.stringify({ status: 'ERROR', error: error.message }, null, 2));
+    process.exitCode = 1;
+    return;
+  }
+  const output = {
+    status: 'READY', preview: Boolean(flags.preview), classification: manifest.classification,
+    reproductionConfirmed: true, controlConfirmed: true, reduction: reduction ? { status: reduction.status, attempts: reduction.attempts } : null,
+    duplicateIdentity: searches.identity, searchUrls: searches, issueUrl: issue.url,
+    record: record ? relative(projectDir, record).split(sep).join('/') : null,
+    contribution: contribution ? relative(projectDir, contribution).split(sep).join('/') : null,
+    contributionPreview: flags.preview && flags.contribution ? contributionPreview : undefined,
+  };
+  console.log(JSON.stringify(output, null, 2));
+}
+
 export function runFeedback(projectDir, config, flags) {
+  if (flags.fixtureManifest) return runFixtureFeedback(projectDir, flags);
+  const classification = flags.classification || 'false_positive';
+  if (!FEEDBACK_CLASSES.has(classification) || classification === 'false_negative' || classification === 'unsupported_syntax') {
+    const error = classification === 'false_negative' || classification === 'unsupported_syntax'
+      ? 'This classification requires --fixture-manifest with an explicit expected identity and opposite control.'
+      : 'Unknown feedback classification.';
+    if (flags.format === 'json') console.log(JSON.stringify({ error, reportable: [] })); else console.error(error);
+    process.exitCode = 1;
+    return;
+  }
   const data = runGuardInternal(projectDir, config);
   const selectedCode = typeof flags.code === 'string' ? flags.code.toUpperCase() : null;
   if (flags.code !== undefined && (!selectedCode || !Object.hasOwn(CODES, selectedCode))) {
@@ -93,7 +232,7 @@ export function runFeedback(projectDir, config, flags) {
   const feedbackDir = resolve(projectDir, '.docguard', 'feedback');
   const items = reportable.map((f) => {
     const id = shortId(`${f.code}|${f.location || f.message}`);
-    const { url, title, searchUrl } = buildIssueUrl(f);
+    const { url, title, searchUrl } = buildIssueUrl(f, { classification });
     const fileName = `${(f.code || 'finding').toLowerCase()}-${id}.json`;
     const filePath = resolve(feedbackDir, fileName);
     return { finding: f, id, url, title, searchUrl, fileName, filePath, saved: false, error: null };
@@ -105,6 +244,7 @@ export function runFeedback(projectDir, config, flags) {
       if (!existsSync(feedbackDir)) mkdirSync(feedbackDir, { recursive: true });
       safeWrite(it.filePath, JSON.stringify({
         capturedBy: `docguard feedback (v${CLI_VERSION})`,
+        classification,
         finding: it.finding,
         issueUrl: it.url,
         searchUrl: it.searchUrl,
@@ -123,6 +263,7 @@ export function runFeedback(projectDir, config, flags) {
     console.log(JSON.stringify({
       version: CLI_VERSION,
       preview: Boolean(flags.preview),
+      classification,
       reportable: items.map(it => ({
         code: it.finding.code,
         location: it.finding.location,

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;