docguard-cli 0.35.0 → 0.36.0

package/README.md

@@ -102,20 +102,13 @@ graph TD
 
 ## Why DocGuard?
 
-Documentation that drifts from code is worse than no documentation — it
-confidently misleads humans and AI agents alike. DocGuard treats your canonical
-docs as an enforced contract: deterministic validators diff what the docs claim
-against what the code does, on every commit, with no LLM required. The full
-thesis (and the research behind it) lives in [PHILOSOPHY.md](PHILOSOPHY.md);
-recent feature highlights moved [below](#-whats-new).
-
-The field data backs the enforcement-over-instructions bet: an ETH Zurich
-study across 138 repos / 5,694 agent PRs found the most popular style of
-agent-instruction file *hurts* agent performance, and practitioners keep
-converging on the same lesson — written rules are routinely ignored;
-programmatic checks are what agents (and humans) actually respect. That is
-exactly the layer DocGuard provides: not another instructions file, but the
-validator suite that makes the instructions and docs verifiably true.
+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.
+
+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).
+
+The development plan prioritizes accurate detection, reproducible evidence, and contributor-supplied regression cases. See [the trust roadmap](docs-implementation/TRUST-ROADMAP.md) for implementation status, proposed experiments, and acceptance criteria.
 
 ---
 
@@ -215,7 +208,7 @@ DocGuard splits drift into two kinds and is explicit about which is which:
 
 `docguard fix --write` only touches docs marked `<!-- docguard:generated true -->` (override with `--force`), is idempotent, and prints exactly what changed. It never rewrites prose — that stays with the agent.
 
-### Hands-off loop (set and forget)
+### Continuous documentation workflow
 
 ```
 guard ──▶ fix --write (mechanical, auto) ──▶ guard ──▶ diagnose (agent prompts for the rest)

package/cli/commands/agent.mjs

@@ -23,6 +23,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';
 
 const PHASES = ['config', 'canonical-docs', 'verify'];
 
@@ -31,8 +33,8 @@ function docSlug(path) {
 }
 
 /**
- * Transform a memory plan into the ordered agent task graph. Pure — no I/O — so
- * it is unit-testable and reused by both the command and `generate`.
+ * Transform a memory plan into the ordered agent task graph, with bounded
+ * read-only input snapshots. Evidence records inputs, never completed review.
  */
 export function buildAgentTaskGraph(projectDir, config, plan) {
   const profileName = config.profile || 'standard';
@@ -69,7 +71,13 @@ export function buildAgentTaskGraph(projectDir, config, plan) {
           ? `Insert the pre-filled "${sec.id}" content into ${doc.path} verbatim — it is extracted from your code. Only fill any \`<!-- … -->\` placeholders.`
           : sec.task,
         grounding: sec.grounding || null,
-        acceptance: { verify: 'docguard guard --format json', expect: `no missing/stale finding for ${doc.path}` },
+        acceptance: {
+          verify: 'docguard guard --format json',
+          expect: `no missing/stale finding for ${doc.path}; ${isCode ? 'compare generated content with current sources' : 'review prose against sources and project intent separately'}`,
+          scope: 'structural-only',
+          reviewRequired: true,
+          factualAccuracy: 'unknown',
+        },
         confidence: isCode ? 'high' : 'requires-human',
       });
     }
@@ -81,15 +89,27 @@ export function buildAgentTaskGraph(projectDir, config, plan) {
     phase: 'verify',
     file: null,
     kind: 'verify',
-    instruction: 'Run `docguard guard --format json`. Resolve every error and warning, then re-run until clean. Run `docguard score` to confirm the maturity grade.',
+    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.',
     prefilled: null,
     grounding: null,
-    acceptance: { verify: 'docguard guard --format json', expect: '0 errors' },
+    acceptance: { verify: 'docguard guard --format json', expect: '0 errors', warnings: 'triage-and-report', scope: 'structural-only', factualAccuracy: 'unknown' },
     confidence: 'high',
   });
 
+  const read = createEvidenceReader(projectDir);
+  for (const task of tasks) {
+    const inputs = JSON.stringify({ instruction: task.instruction, prefilled: task.prefilled, grounding: task.grounding });
+    const citations = citedSources([read(task.file).content, task.prefilled, task.instruction].filter(Boolean).join('\n'));
+    task.evidence = taskEvidence(read, task.file, citations, inputs);
+  }
+
+  const assurance = buildScoreAssurance(projectDir, config);
+  assurance.limitation += ` ${SEMANTIC_COVERAGE_LIMITATION}`;
+
   return {
     project: config.projectName,
+    provenance: { kind: 'snapshot', git: gitEvidence(projectDir) },
+    assurance,
     profile: { name: profileName, kind: plan.profile.kind, languages: plan.profile.languages, frameworks: plan.profile.frameworks },
     order: PHASES,
     counts: {
@@ -106,7 +126,7 @@ export function runAgent(projectDir, config, flags) {
   // 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;
-  const plan = buildMemoryPlan(projectDir, cfg);
+  const plan = buildMemoryPlan(projectDir, { ...cfg, diskCache: false });
   const graph = buildAgentTaskGraph(projectDir, cfg, plan);
 
   if (flags.format === 'json') {
@@ -119,6 +139,7 @@ export function runAgent(projectDir, config, flags) {
   {
     console.log(`${c.bold}🤖 DocGuard Agent Task Graph — ${graph.project}${c.reset}`);
     console.log(`${c.dim}   profile: ${graph.profile.name} · kind: ${graph.profile.kind} · ${graph.counts.tasks} tasks (${graph.counts.codeTruth} code-truth, ${graph.counts.humanJudgment} human)${c.reset}\n`);
+    console.log(`  ${c.dim}Snapshot only · structural checks do not verify prose · ${graph.assurance.unverifiedClaims ?? 'unknown'} extracted claims await review.${c.reset}\n`);
     for (const phase of graph.order) {
       const inPhase = graph.tasks.filter(t => t.phase === phase);
       if (!inPhase.length) continue;

package/cli/commands/ci.mjs

@@ -62,6 +62,7 @@ export function runCI(projectDir, config, flags) {
       errors: guardData.errors,
       warnings: guardData.warnings,
       baselineSuppressed: guardData.baselineSuppressed || 0,
+        checkCoverage: guardData.checkCoverage,
       passed: guardData.passed,
       total: guardData.total,
       status,
@@ -74,6 +75,8 @@ export function runCI(projectDir, config, flags) {
       project: config.projectName,
       profile: config.profile || 'standard',
       projectType: config.projectType || 'unknown',
+      scoreKind: scoreData.scoreKind,
+      assurance: scoreData.assurance,
       score: scoreData.score,
       grade: scoreData.grade,
       guard: {

package/cli/commands/diagnose.mjs

@@ -1,3 +1,4 @@
+import { assertDefaultDocWrites } from '../shared-doc-roles.mjs';
 /**
  * Diagnose Command — The AI Orchestrator
  *
@@ -181,6 +182,7 @@ const FIX_INSTRUCTIONS = {
 };
 
 export function runDiagnose(projectDir, config, flags) {
+  if (flags.auto) assertDefaultDocWrites(config);
   // ── Step 0: Detect agent mode (LLM-first) ──
   const agentMode = detectAgentMode(projectDir);
 
@@ -347,6 +349,9 @@ function outputJSON(guardData, scoreData, issues) {
     status: guardData.status,
     score: scoreData.score,
     grade: scoreData.grade,
+    scoreKind: scoreData.scoreKind,
+    assurance: scoreData.assurance,
+    checkCoverage: guardData.checkCoverage,
     issueCount: issues.length,
     issues: issues.map(i => ({
       severity: i.severity,
@@ -493,7 +498,8 @@ function outputPrompt(projectDir, guardData, scoreData, issues, flags, agentMode
     lines.push('After making all fixes, run: docguard guard');
   }
   lines.push('Expected result: All checks pass (0 errors, 0 warnings)');
-  lines.push(`Target score: ≥${Math.min(scoreData.score + 5, 100)}/100`);
+  lines.push(`Structural baseline: ${scoreData.score}/100. Resolve evidenced defects; verify material claims separately.`);
+  lines.push('Preserve approved requirements when implementation disagrees. A higher score is not proof of factual correctness.');
 
   // Agent-aware: add explicit checklist for basic-tier agents
   if (agentTier === 'basic') {
@@ -581,7 +587,7 @@ function outputDebatePrompt(projectDir, guardData, scoreData, issues, agentMode
   lines.push('   c. What content to write (be specific, not vague)');
   const verifyCmd = agentMode === 'llm' ? '/docguard.guard' : 'docguard guard';
   lines.push(`4. After all fixes, verify with: ${verifyCmd}`);
-  lines.push(`5. Target score: ≥${Math.min(scoreData.score + 10, 100)}/100`);
+  lines.push('5. Verify repaired claims against their evidence and retain unresolved uncertainty. Structural score is a proxy.');
   lines.push('');
   lines.push('═══════════════════════════════════════════════════════');
   lines.push('Execute all three perspectives in sequence, then implement the Synthesizer\'s plan.');

package/cli/commands/feedback.mjs

@@ -1,32 +1,25 @@
 /**
- * Feedback Command — close the loop with the tool's maintainers (v0.27).
+ * Feedback Command — prepare opt-in detection feedback.
  *
- * DocGuard is a tool for LLMs: when it gets something wrong, the cheapest way to
- * make the NEXT release better is to capture that signal. This command turns the
- * low-confidence findings of a guard run (candidate false positives — and any
- * other finding DocGuard itself flagged as uncertain) into:
+ * Select uncertain findings by default, or challenge active findings with
+ * --code / --all. Full local records may contain private diagnostics;
+ * --preview skips feedback-record writes. Persistence outcomes are explicit.
  *
- *   1. a LOCAL-FIRST record under .docguard/feedback/<code>-<id>.json (full,
- *      reviewable, never sent anywhere automatically), and
- *   2. a one-click, PREFILLED GitHub issue URL that needs zero typing.
+ * Shared issue and search URLs contain only allowlisted finding identity,
+ * tool metadata, and contribution instructions. Paths, source text, messages,
+ * suggestions, and redactedContext are excluded. URLs are capped; users must
+ * review and supply a synthetic reproduction before submitting an issue.
  *
- * Hard constraints (learned the hard way — see commit 3b600fd, where an
- * oversized prefilled URL overflowed GitHub's ~8 KB limit and silently failed):
- *   - The URL is CAPPED well under the limit; bulk lives in the local file.
- *   - It is REDACTED: no source code, no secret values — only a basename, a line
- *     number, and the safe `redactedContext` the validator built.
- *   - It is OPT-IN: nothing is filed automatically; the human clicks (or not).
- *
- * Not read-only in the strict sense — it writes its own .docguard/feedback/ —
- * but it never scaffolds skills and never touches the user's source tree.
- *
- * Zero npm dependencies — pure Node.js built-ins.
+ * Nothing is transmitted automatically. This command never scaffolds skills
+ * or edits source files. Zero npm dependencies — pure Node.js built-ins.
  */
 
-import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
-import { resolve, dirname, basename } from 'node:path';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
 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';
 
 const _PKG = JSON.parse(
@@ -45,69 +38,54 @@ function shortId(str) {
   return h.toString(36).slice(0, 6);
 }
 
-/** Redact a finding location for the SHARED url: basename + line only. */
-function safeLocation(location) {
-  if (!location) return '(unknown)';
-  const [path, line] = String(location).split(/:(?=\d+$)/);
-  return line ? `${basename(path)}:${line}` : basename(path);
-}
-
-/**
- * Build a prefilled, capped issue URL. Drops optional body lines (longest-value
- * first) until under the cap; title + code + location always survive.
- */
-function buildIssueUrl(finding) {
-  const code = finding.code || 'FINDING';
-  const validator = finding.validator || 'unknown';
-  const shortMsg = (finding.message || '').replace(/\s+/g, ' ').slice(0, 70);
-  const title = `[feedback] ${code} (${validator}): ${shortMsg}`;
-
-  // Optional lines are ordered most→least droppable.
-  const required = [
-    `DocGuard v${CLI_VERSION} flagged this and it may be a false positive (or other feedback).`,
-    '',
+/** Shared output deliberately excludes every source-derived string. */
+export function buildIssueUrl(finding) {
+  const code = Object.hasOwn(CODES, finding.code || '') ? finding.code : 'FINDING';
+  const validator = CODES[code]?.validator || 'unknown';
+  const title = `[feedback] ${code} (${validator}): detection feedback`;
+  const confidence = ['high', 'medium', 'low'].includes(finding.confidence) ? finding.confidence : 'unknown';
+  const body = [
+    `DocGuard v${CLI_VERSION}`,
     `- Code: ${code}`,
     `- Validator: ${validator}`,
-    `- Location: ${safeLocation(finding.location)}`,
-    `- Confidence: ${finding.confidence}`,
-  ];
-  const optional = [];
-  if (finding.redactedContext) optional.push(`- Context: ${finding.redactedContext}`);
-  if (finding.suggestion && finding.suggestion.text) optional.push(`- Suggestion shown: ${finding.suggestion.text}`);
-  const footer = ['', 'Generated by `docguard feedback` — no source code or secret values are included.'];
-
-  const compose = (opt) => `${ISSUES_BASE}/new?labels=${encodeURIComponent('docguard-feedback')}` +
-    `&title=${encodeURIComponent(title)}` +
-    `&body=${encodeURIComponent([...required, ...opt, ...footer].join('\n'))}`;
-
-  let opt = [...optional];
-  let url = compose(opt);
-  while (url.length > URL_CAP && opt.length > 0) {
-    opt = opt.slice(0, -1);
-    url = compose(opt);
-  }
-  if (url.length > URL_CAP) {
-    // Even the required body is too long (pathological) — collapse to a stub.
-    url = `${ISSUES_BASE}/new?labels=${encodeURIComponent('docguard-feedback')}` +
-      `&title=${encodeURIComponent(title)}` +
-      `&body=${encodeURIComponent(`DocGuard v${CLI_VERSION} — ${code} (${validator}). Full details saved locally; please attach.`)}`;
-  }
-  return { url, title };
+    `- Confidence: ${confidence}`,
+    '',
+    'Expected behavior:',
+    'Actual behavior:',
+    'Minimal synthetic reproduction (review before attaching):',
+    '',
+    'Check existing open AND closed issues and pull requests before submitting.',
+    'A regression-test-only contribution is welcome; explain the expected behavior.',
+    '',
+    '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 searchUrl = `https://github.com/search?q=${encodeURIComponent(query)}&type=issues`;
+  return { url: url.length <= URL_CAP ? url : `${ISSUES_BASE}/new`, title, searchUrl };
 }
 
 export function runFeedback(projectDir, config, flags) {
   const data = runGuardInternal(projectDir, config);
-  const reportable = (data.findings || []).filter((f) => f.reportable);
+  const selectedCode = typeof flags.code === 'string' ? flags.code.toUpperCase() : null;
+  if (flags.code !== undefined && (!selectedCode || !Object.hasOwn(CODES, selectedCode))) {
+    const error = 'Unknown finding code. Run docguard explain <CODE> to inspect supported findings.';
+    if (flags.format === 'json') console.log(JSON.stringify({ error, reportable: [] }));
+    else console.error(error);
+    process.exitCode = 1;
+    return;
+  }
+  const reportable = (data.findings || []).filter(f => selectedCode ? f.code === selectedCode : flags.all || f.reportable);
   const isJson = flags.format === 'json';
 
   if (reportable.length === 0) {
     if (isJson) {
-      console.log(JSON.stringify({ reportable: [], message: 'no uncertain findings' }, null, 2));
+      console.log(JSON.stringify({ reportable: [], message: 'no matching findings; use --code <CODE> or --all to challenge confident findings' }, null, 2));
       return;
     }
     console.log(`${c.bold}📮 DocGuard Feedback${c.reset}`);
-    console.log(`${c.green}✅ Nothing to report — DocGuard is confident about everything it flagged.${c.reset}`);
-    console.log(`${c.dim}   (Feedback collects low-confidence findings, i.e. likely false positives.)${c.reset}\n`);
+    console.log(`${c.green}✅ No findings matched this selection. Confidence is not proof of correctness.${c.reset}`);
+    console.log(`${c.dim}   Use --code <CODE> or --all to challenge a confident finding; --preview avoids saving records.${c.reset}\n`);
     return;
   }
 
@@ -115,37 +93,51 @@ 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 } = buildIssueUrl(f);
+    const { url, title, searchUrl } = buildIssueUrl(f);
     const fileName = `${(f.code || 'finding').toLowerCase()}-${id}.json`;
     const filePath = resolve(feedbackDir, fileName);
-    return { finding: f, id, url, title, fileName, filePath };
+    return { finding: f, id, url, title, searchUrl, fileName, filePath, saved: false, error: null };
   });
 
-  if (isJson) {
-    console.log(JSON.stringify({
-      version: CLI_VERSION,
-      reportable: items.map((it) => ({ code: it.finding.code, location: it.finding.location, url: it.url, file: `.docguard/feedback/${it.fileName}` })),
-    }, null, 2));
-    // Still write the local records so the JSON path is not a dead end.
-  }
-
   let wrote = 0;
-  for (const it of items) {
+  for (const it of flags.preview ? [] : items) {
     try {
       if (!existsSync(feedbackDir)) mkdirSync(feedbackDir, { recursive: true });
-      writeFileSync(it.filePath, JSON.stringify({
+      safeWrite(it.filePath, JSON.stringify({
         capturedBy: `docguard feedback (v${CLI_VERSION})`,
         finding: it.finding,
         issueUrl: it.url,
-      }, null, 2) + '\n', 'utf-8');
+        searchUrl: it.searchUrl,
+        sharing: 'The finding record can contain private project information. Share only a reviewed synthetic reproduction.',
+      }, null, 2) + '\n');
+      it.saved = true;
       wrote++;
-    } catch { /* best-effort local capture */ }
+    } catch (err) {
+      it.error = `Unable to save feedback record (${err.code || 'write failed'}).`;
+    }
   }
 
-  if (isJson) return;
+  if (items.some(it => it.error)) process.exitCode = 1;
+
+  if (isJson) {
+    console.log(JSON.stringify({
+      version: CLI_VERSION,
+      preview: Boolean(flags.preview),
+      reportable: items.map(it => ({
+        code: it.finding.code,
+        location: it.finding.location,
+        url: it.url,
+        searchUrl: it.searchUrl,
+        file: it.saved ? `.docguard/feedback/${it.fileName}` : null,
+        saved: it.saved,
+        error: it.error,
+      })),
+    }, null, 2));
+    return;
+  }
 
   console.log(`${c.bold}📮 DocGuard Feedback${c.reset}`);
-  console.log(`${c.dim}   ${items.length} uncertain finding(s) — likely false positives. Saved locally to ${c.cyan}.docguard/feedback/${c.reset}\n`);
+  console.log(`${c.dim}   ${items.length} selected finding(s). ${flags.preview ? 'Preview only; no feedback records saved.' : `${wrote} local record(s) saved to .docguard/feedback/`}\n`);
 
   for (const it of items) {
     const f = it.finding;
@@ -153,9 +145,11 @@ export function runFeedback(projectDir, config, flags) {
     if (f.suggestion && f.suggestion.pragma) {
       console.log(`     ${c.dim}Suppress locally instead: ${f.suggestion.pragma}${c.reset}`);
     }
-    console.log(`     ${c.dim}Report (1 click, prefilled, redacted):${c.reset}`);
+    console.log(`     ${c.dim}Check for duplicates (including closed work): ${it.searchUrl}${c.reset}`);
+    console.log(`     ${c.dim}Report (review before submitting):${c.reset}`);
     console.log(`     ${c.cyan}${it.url}${c.reset}`);
-    console.log(`     ${c.dim}Local copy: .docguard/feedback/${it.fileName}${c.reset}\n`);
+    if (it.saved) console.log(`     ${c.dim}Local copy (may contain private project details): .docguard/feedback/${it.fileName}${c.reset}\n`);
+    if (it.error) console.error(`     ${c.red}${it.error}${c.reset}`);
   }
 
   console.log(`${c.dim}These reports help DocGuard stop flagging the same false positive in a future release.${c.reset}`);

package/cli/commands/fix.mjs

@@ -1,3 +1,4 @@
+import { assertDefaultDocWrites } from '../shared-doc-roles.mjs';
 /**
  * Fix Command — The AI Orchestrator
  * 
@@ -37,6 +38,7 @@ 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 : [];
@@ -273,6 +275,7 @@ 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 = [];
@@ -372,6 +375,7 @@ 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,3 +1,4 @@
+import { assertDefaultDocWrites } 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.
@@ -39,6 +40,7 @@ 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);
@@ -137,6 +139,7 @@ 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.