dflow-sdd-ddd 0.13.0 → 0.15.0

package/lib/init.js

@@ -4,6 +4,7 @@ const readline = require('node:readline');
 const { TextDecoder } = require('node:util');
 
 const pkg = require('../package.json');
+const doctorChecks = require('./doctor-checks');
 
 const MIN_NODE_VERSION = '22.0.0';
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
@@ -23,6 +24,33 @@ const CODEX_TRIGGER_SECTION_END = '<!-- dflow-generated: codex-command-triggers
 // freeze the pre-marker shim template for back-compat.
 const AGENT_SHIM_SECTION_START = '<!-- dflow-generated: agent-shim START -->';
 const AGENT_SHIM_SECTION_END = '<!-- dflow-generated: agent-shim END -->';
+// PROPOSAL-058: the packaged guide templates wrap their Dflow-canonical body in
+// this pair; configure-agents refreshes the region in place on upgrade and never
+// touches content outside it ("## Project Context" and anything else the user
+// keeps there).
+const GUIDE_CANONICAL_SECTION_START = '<!-- dflow-generated: guide-canonical START -->';
+const GUIDE_CANONICAL_SECTION_END = '<!-- dflow-generated: guide-canonical END -->';
+const AI_AGENT_GUIDE_DEST = 'dflow/specs/shared/AI-AGENT-GUIDE.md';
+// PROPOSAL-090 (route B3): the Git principles starter is user-owned — projects
+// write their own AI-collaboration policy and CI/CD sections into it — but
+// sections 1-5 are Dflow-canonical and three trunk flow files read them, so a
+// starter frozen at its init version leaves those flows pointing at rules the
+// project never received. Measured 2026-08-18 on a project whose upgrade
+// process was otherwise flawless: 65 lines behind, and not polish.
+// ⚠ A SEPARATE marker pair from the guide's, deliberately: the guide-canonical
+// START string is also used as a section-boundary terminator in
+// `projectContextSectionBounds`, so sharing the token would tie two unrelated
+// mechanisms to one string.
+const GIT_PRINCIPLES_CANONICAL_START = '<!-- dflow-generated: git-principles-canonical START -->';
+const GIT_PRINCIPLES_CANONICAL_END = '<!-- dflow-generated: git-principles-canonical END -->';
+// The two headings that bound the canonical region. Verified stable across
+// v0.9.0..HEAD in all four starters (2 editions x 2 policies), which is what
+// makes marker adoption on a pre-marker file decidable rather than a guess.
+// ⚠ Anchor on the exact heading text, never on "the next `## `": the gitflow
+// starters carry a `## [1.2.3] — {YYYY-MM-DD}` CHANGELOG example inside a
+// fenced block.
+const GIT_PRINCIPLES_CANONICAL_FIRST_HEADING = '## 1. Branch Structure';
+const GIT_PRINCIPLES_CANONICAL_AFTER_HEADING = '## 6. AI Collaboration Rules (Project Policy)';
 const WORKFLOW_BUNDLE_DEST = 'dflow/specs/shared/dflow-workflows';
 const WORKFLOW_BUNDLE_MANIFEST_PATH = `${WORKFLOW_BUNDLE_DEST}/.dflow-bundle-manifest.json`;
 const COMMON_SKILL_SOURCE_REL = 'common/skill/SKILL.md';
@@ -32,7 +60,14 @@ const COMMON_SKILL_SOURCE_REL = 'common/skill/SKILL.md';
 // and configure-agents stale-removal would then DELETE the already-installed
 // copy from the user's project (it diffs as "retired"). PROPOSAL-064 fresh-gate
 // finding. Guarded before any stale cleanup / manifest write.
-const REQUIRED_COMMON_BUNDLE_FILES = ['references/ddd-modeling-guide.md'];
+// Frozen because it is exported: an unfrozen array could be emptied by any
+// consumer (`REQUIRED_COMMON_BUNDLE_FILES.length = 0`), silently turning the
+// completeness guard into a no-op for the rest of the process.
+const REQUIRED_COMMON_BUNDLE_FILES = Object.freeze([
+  'references/ddd-modeling-guide.md',
+  'references/dflow-feedback-flow.md',
+  'references/flow-rationale-registry.md'
+]);
 const EXPECTED_COMMAND_IDS = [
   'new-feature',
   'modify-existing',
@@ -197,6 +232,31 @@ const DEFERRED_COMMON = [
     relativePath: 'dflow/specs/domain/{context}/rules.md',
     reason: 'Needs a real bounded context.'
   },
+  {
+    relativePath: 'dflow/specs/domain/{context}/analysis.md',
+    reason: 'Needs a real bounded context.'
+  },
+  {
+    relativePath: 'dflow/specs/domain/analysis.md',
+    reason: 'Created the first time a session records a cross-context flow, role reach, or other knowledge no single context owns.'
+  }
+];
+
+// ⚠ EDITION-SPECIFIC DEFERRALS, and the reason this list exists is that the
+// other one is named COMMON. The ADR row used to sit in DEFERRED_COMMON while
+// `dflow/specs/architecture/` is a greenfield-only tree — brownfield records
+// architecture decisions under `dflow/specs/migration/` and never creates
+// `architecture/` at all. So every brownfield `dflow init` printed a promise to
+// create a directory the CLI will never create (`debt20-tut-y5`, confirmed by
+// `debt20-tut-y6`). `buildDeferredItems` only ever ADDED to the common list, so
+// nothing could subtract a row that did not apply — the fix is to stop putting
+// edition-specific rows in the shared list rather than to add a subtraction
+// step. Anything that is true for one edition only belongs here.
+const DEFERRED_GREENFIELD_ONLY = [
+  {
+    relativePath: 'dflow/specs/domain/{context}/events.md',
+    reason: 'Greenfield only, but still needs a real bounded context.'
+  },
   {
     relativePath: 'dflow/specs/architecture/decisions/ADR-*.md',
     reason: 'ADRs are created when a real architecture decision exists.'
@@ -367,14 +427,52 @@ async function runConfigureAgents(options = {}) {
       }
     }
 
-    const plan = await buildConfigureAgentsPlan(cwd, {
+    // PROPOSAL-058: adoption offers are decided by planning the run twice. The
+    // first plan flags what is offer-able (a recognizable pre-marker guide, a
+    // guide-referencing agent file Dflow does not manage); an interactive run
+    // then asks, and only a granted consent triggers a re-plan. A non-TTY run
+    // never asks and never consumes a stdin slot (the PROPOSAL-074 contract:
+    // existing piped answer sequences must run unchanged), so it keeps the
+    // skip + warn behavior. Deriving the offers from the plan itself keeps the
+    // question conditions and the plan branches from ever drifting apart.
+    const interactive = Boolean(stdin.isTTY && stdout.isTTY);
+    let adoptGuideMarkers = false;
+    let adoptGitPrinciplesMarkers = false;
+    const adoptShimAgents = [];
+    const buildPlan = () => buildConfigureAgentsPlan(cwd, {
       ...projectContext,
       aiAgents,
       commandAdapters: Boolean(options.commandAdapters),
       skills: Boolean(options.skills),
-      skillAgents
+      skillAgents,
+      adoptGuideMarkers,
+      adoptGitPrinciplesMarkers,
+      adoptShimAgents
     });
 
+    let plan = await buildPlan();
+
+    if (interactive) {
+      const offersGuide = plan.items.some((item) => item.offerGuideAdoption);
+      const shimOffers = dedupe(
+        plan.items.filter((item) => item.offerShimAdoption).map((item) => item.offerShimAdoption)
+      );
+      if (offersGuide) {
+        adoptGuideMarkers = await askGuideMarkerAdoption(rl, stdout);
+      }
+      if (plan.items.some((item) => item.offerGitPrinciplesAdoption)) {
+        adoptGitPrinciplesMarkers = await askGitPrinciplesMarkerAdoption(rl, stdout);
+      }
+      for (const agent of shimOffers) {
+        if (await askShimBlockAdoption(rl, stdout, agent)) {
+          adoptShimAgents.push(agent);
+        }
+      }
+      if (adoptGuideMarkers || adoptGitPrinciplesMarkers || adoptShimAgents.length > 0) {
+        plan = await buildPlan();
+      }
+    }
+
     const warnings = plan.warnings || [];
     renderPreview(stdout, plan, warnings);
     const confirmed = await askConfirmation(rl, 'Create these files? (y/N) ');
@@ -752,18 +850,19 @@ async function inferProjectContext(cwd, rl, stdout, stderr) {
   };
 }
 
+// The machine-readable line patterns and value parse live in lib/doctor-checks.js
+// so the doctor "machine format" findings and this inference can never drift
+// apart (PROPOSAL-058).
 async function inferGitPolicy(cwd) {
   const conventionsPath = path.join(cwd, 'dflow/specs/shared/_conventions.md');
   const content = await fs.readFile(conventionsPath, 'utf8').catch(() => '');
-  const match = content.match(/Selected Git policy:\s*`([^`]+)`/);
-  return match ? match[1] : null;
+  return doctorChecks.parseContextLine(content, doctorChecks.GIT_POLICY_LINE_RE);
 }
 
 async function inferAiCommitMarker(cwd) {
   const conventionsPath = path.join(cwd, 'dflow/specs/shared/_conventions.md');
   const content = await fs.readFile(conventionsPath, 'utf8').catch(() => '');
-  const match = content.match(/AI commit marker:\s*`([^`]+)`/);
-  return match ? match[1] : null;
+  return doctorChecks.parseContextLine(content, doctorChecks.AI_COMMIT_MARKER_LINE_RE);
 }
 
 async function inferExistingEdition(cwd) {
@@ -782,22 +881,43 @@ async function inferExistingEdition(cwd) {
 async function inferProseLanguage(cwd) {
   const conventionsPath = path.join(cwd, 'dflow/specs/shared/_conventions.md');
   const content = await fs.readFile(conventionsPath, 'utf8').catch(() => '');
-  const match = content.match(/Project prose language:\s*`([^`]+)`/);
-  return match ? match[1] : 'unknown';
+  return doctorChecks.parseContextLine(content, doctorChecks.PROSE_LANGUAGE_LINE_RE) ?? 'unknown';
 }
 
+// PROPOSAL-076: the machine-readable record of the init Q2/Q3 answers is the
+// guide's "## Project Context" table — init substitutes them into the
+// `| Tech stack |` / `| Migration / legacy context |` rows there. (The
+// pre-076 code looked for those rows in _overview.md, which never carried
+// them in any packaged template, so inference always fell back.) Only the
+// Project Context section is parsed: it is the contractual user region
+// (PROPOSAL-058), so a same-name row anywhere else in the guide can never
+// shadow it.
 async function inferTechStackSummary(cwd) {
-  const overviewPath = path.join(cwd, 'dflow/specs/shared/_overview.md');
-  const content = await fs.readFile(overviewPath, 'utf8').catch(() => '');
-  const match = content.match(/\|\s*Tech stack\s*\|\s*([^|\n]+?)\s*\|/i);
-  return match ? match[1].trim() : 'unknown';
+  return (await inferGuideProjectContextValue(cwd, doctorChecks.TECH_STACK_ROW_RE)) ?? 'unknown';
 }
 
 async function inferMigrationContext(cwd) {
-  const overviewPath = path.join(cwd, 'dflow/specs/shared/_overview.md');
-  const content = await fs.readFile(overviewPath, 'utf8').catch(() => '');
-  const match = content.match(/\|\s*Migration \/ legacy context\s*\|\s*([^|\n]+?)\s*\|/i);
-  return match ? match[1].trim() : 'none';
+  return (await inferGuideProjectContextValue(cwd, doctorChecks.MIGRATION_CONTEXT_ROW_RE)) ?? 'none';
+}
+
+async function inferGuideProjectContextValue(cwd, re) {
+  const guidePath = path.join(cwd, AI_AGENT_GUIDE_DEST);
+  const content = await fs.readFile(guidePath, 'utf8').catch(() => '');
+  const slice = projectContextParseSlice(toLf(content));
+  return slice === null ? null : doctorChecks.parseContextLine(slice, re);
+}
+
+// The parseable slice of the "## Project Context" section: fenced examples
+// inside the section are blanked so a decoy row in a fence can neither supply
+// nor shadow a value (PROPOSAL-076 gate G2) — fence state is clean at the
+// heading because the fence-aware bounds scan would not have matched a heading
+// inside a fence. Inference and the doctor row check must both parse through
+// this slice so they can never disagree.
+function projectContextParseSlice(lfContent) {
+  const bounds = projectContextSectionBounds(lfContent);
+  if (!bounds) return null;
+  const section = bounds.lines.slice(bounds.start, bounds.end).join('\n');
+  return doctorChecks.blankFencedBlocks(section).join('\n');
 }
 
 async function askSelect(rl, stdout, stderr, config) {
@@ -1221,19 +1341,19 @@ async function buildConfigureAgentsPlan(cwd, answers) {
   const items = [];
   const warnings = [];
 
-  let content = await readPackagedTemplate(answers.edition, 'scaffolding/AI-AGENT-GUIDE.md');
-  content = substitutePlaceholders(content, substitution);
-  items.push({
-    relativePath: 'dflow/specs/shared/AI-AGENT-GUIDE.md',
-    source: `packaged:${answers.edition}/scaffolding/AI-AGENT-GUIDE.md`,
-    notes: 'canonical AI agent guide',
-    content
-  });
+  let packagedGuide = await readPackagedTemplate(answers.edition, 'scaffolding/AI-AGENT-GUIDE.md');
+  packagedGuide = substitutePlaceholders(packagedGuide, substitution);
+  await addCanonicalGuideItem(cwd, items, warnings, packagedGuide, answers);
+  await addGitPrinciplesItem(cwd, items, warnings, answers);
 
-  const commandRegistry = answers.commandAdapters ? parseDflowCommandRegistry(content) : [];
+  const commandRegistry = answers.commandAdapters ? parseDflowCommandRegistry(packagedGuide) : [];
 
   for (const agent of answers.aiAgents) {
-    await addAiAgentShim(cwd, items, agent, substitution, { commandRegistry, warnings });
+    await addAiAgentShim(cwd, items, agent, substitution, {
+      commandRegistry,
+      warnings,
+      adoptShimAgents: answers.adoptShimAgents || []
+    });
   }
 
   if (answers.commandAdapters) {
@@ -1260,6 +1380,15 @@ async function buildConfigureAgentsPlan(cwd, answers) {
   await addWorkflowBundleItems(cwd, items, bundleWarnings, answers.edition);
   warnings.push(...bundleWarnings);
 
+  // Last plan item on purpose: the write phase runs in plan order and aborts on
+  // the first failure, so the last-reconciled version line only advances when
+  // everything this run re-projects was written. Guarded skips do not abort the
+  // write phase, so the item additionally carries requiresFullApply — the write
+  // phase drops it (with a warning) when any earlier planned change was skipped
+  // unexpectedly (changed after preview, vanished target, unexpected existing
+  // target).
+  await addConventionsVersionReconcileItem(cwd, items);
+
   return {
     items,
     deferred: [],
@@ -1296,15 +1425,65 @@ async function finalizePlanItems(cwd, items) {
 // source trees, so the merged dest path / manifest entry never collide or
 // shadow each other. Pure (no I/O) so it is unit-testable on a synthetic list.
 function assertNoBundleCollision(files) {
+  // Keyed case-INSENSITIVELY. The merged set is projected onto the adopter's
+  // filesystem, where Windows and default macOS treat `Foo.md` and `foo.md` as
+  // one path: two source trees differing only in case would ship two logical
+  // files that overwrite each other there, while an exact-match key reports no
+  // collision at all. A case-sensitive dev checkout or CI can create that pair,
+  // so the guard cannot rely on the authoring filesystem to prevent it.
+  // Case-folded and NFC-normalised. ⚠ The guard's two halves have DIFFERENT
+  // reach, and collapsing them into one sentence has produced a wrong comment
+  // twice — once claiming adopters are protected everywhere, once claiming the
+  // guard is silent everywhere. Both were generalised from a probe that only
+  // covered one half. Measured on a case-insensitive (Windows) host:
+  //
+  //   * CROSS-ROOT pair (templates/common/… vs templates/{edition}/…) — the two
+  //     files sit in DIFFERENT directories, so both spellings exist on any
+  //     filesystem. readdir yields a descriptor from each root and this guard
+  //     throws before anything is projected. Probe: common/x.md + greenfield/X.md
+  //     both present, guard fires. Real runtime protection, Windows included,
+  //     and the case this guard mainly exists for.
+  //   * SAME-TREE pair (two spellings in ONE directory) — reach depends on WHICH
+  //     axis differs, because the key folds two of them and filesystems do not
+  //     treat them alike:
+  //
+  //       axis \ host   | Linux (case-sens, norm-sens) | Windows (case-INsens, norm-SENS) | macOS default (both INsens)
+  //       case pair     | coexists -> canary           | collapses -> silent              | collapses -> silent
+  //       NFD/NFC pair  | coexists -> canary           | COEXISTS -> guard fires          | collapses -> silent
+  //
+  //     Probes on Windows: `Foo.md` then `foo.md` leaves readdir count=1 (and
+  //     the FIRST name survives carrying the SECOND write's content); an
+  //     NFD/NFC pair leaves count=2 and this guard throws. NTFS is
+  //     case-insensitive but normalization-SENSITIVE — so the normalisation is
+  //     not defensive dressing, it is the one axis with runtime reach here.
+  //     ⚠ The macOS column is inference from documented APFS/HFS+ behaviour,
+  //     not measured; the other two columns are measured on this host.
+  //
+  // Guarding the source filenames themselves — OS-special forms such as a
+  // Windows ADS `name.md:stream` — is a wider job, filed as
+  // `bundle-name-validity` in planning/opt-in-backlog.md.
+  //
+  // The real key set is ASCII today, which is exactly why the normalisation has
+  // to be written here rather than assumed.
   const seenBy = new Map();
   for (const f of files) {
-    const prior = seenBy.get(f.sourceRel);
-    if (prior && prior !== f.sourceRoot) {
+    const key = f.sourceRel.normalize('NFC').toLowerCase();
+    const prior = seenBy.get(key);
+    // Two spellings collide REGARDLESS of which tree they came from. Keying on
+    // sourceRoot alone would miss the same hazard inside one tree — two files
+    // in templates/common/ differing only in case are equally one path on the
+    // adopter's filesystem, and would project two manifest entries onto it.
+    if (prior && (prior.sourceRoot !== f.sourceRoot || prior.sourceRel !== f.sourceRel)) {
+      const where = prior.sourceRoot === f.sourceRoot
+        ? `twice in templates/${f.sourceRoot}/ (as "${prior.sourceRel}" and "${f.sourceRel}")`
+        : prior.sourceRel === f.sourceRel
+          ? `in both templates/${prior.sourceRoot}/ and templates/${f.sourceRoot}/`
+          : `in both templates/${prior.sourceRoot}/ (as "${prior.sourceRel}") and templates/${f.sourceRoot}/ (as "${f.sourceRel}")`;
       throw new InitError(
-        `Internal error: workflow bundle file "${f.sourceRel}" exists in both templates/${prior}/ and templates/${f.sourceRoot}/. A bundle file name must be unique across the common and edition source trees.`
+        `Internal error: workflow bundle file "${f.sourceRel}" exists ${where}. A bundle file name must be unique across the common and edition source trees — compared case-insensitively, because the projected destination lands on filesystems that treat "Foo.md" and "foo.md" as one path.`
       );
     }
-    seenBy.set(f.sourceRel, f.sourceRoot);
+    seenBy.set(key, f);
   }
 }
 
@@ -1313,10 +1492,14 @@ function assertNoBundleCollision(files) {
 // (templates/) — the common tree must NOT mask a broken edition (a vanished
 // templates/{edition}/references/ would otherwise be hidden by common's
 // non-empty references/). Enforced in the scanner (not only the projector) so
-// BOTH callers are covered: the projector hard-fails, and doctor's existing
-// try/catch around listBundleSourceFiles degrades to skipping the orphan scan
-// rather than mis-reporting every projected flow file as orphaned. Pure (no
-// I/O) so it is unit-testable on a synthetic list.
+// BOTH callers are covered: the projector hard-fails, and doctor skips the orphan
+// scan rather than mis-reporting every projected flow file as orphaned.
+// ⚠ That skip is no longer SILENT, and this sentence used to read as permission for
+// it to be: doctor now also emits a `warn` naming the broken install
+// (see checkWorkflowBundleSourceAndOrphans). A maintainer who restores a bare
+// `catch { return; }` on the strength of "degrades gracefully" reintroduces the
+// exact false-clean this repo spent four review rounds closing. Pure (no I/O) so it
+// is unit-testable on a synthetic list.
 function assertEditionBundleComplete(files, edition) {
   const hasEditionRefs = files.some((f) => f.sourceRoot === edition && f.dir === 'references');
   const hasEditionTemplates = files.some((f) => f.sourceRoot === edition && f.dir === 'templates');
@@ -1353,32 +1536,38 @@ function assertCommonBundleComplete(files) {
 // at the same dflow/.../references/<name> path in every edition. The scanner
 // validates the merged set (collision + complete-edition guards) before
 // returning, so both callers (projector, doctor) get a trustworthy list.
-async function listBundleSourceFiles(edition) {
-  const bundleDirs = ['references', 'templates'];
-  const sourceRoots = ['common', edition];
+async function scanBundleSourceRoot(sourceRoot) {
   const files = [];
-
-  for (const sourceRoot of sourceRoots) {
-    for (const dir of bundleDirs) {
-      const sourceDir = path.join(TEMPLATE_ROOT, sourceRoot, dir);
-      let entries;
-      try {
-        entries = await fs.readdir(sourceDir);
-      } catch (error) {
-        if (error.code === 'ENOENT') {
-          continue;
-        }
-        throw error;
+  for (const dir of ['references', 'templates']) {
+    const sourceDir = path.join(TEMPLATE_ROOT, sourceRoot, dir);
+    let entries;
+    try {
+      entries = await fs.readdir(sourceDir);
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        continue;
       }
-      for (const entry of entries) {
-        const sourcePath = path.join(sourceDir, entry);
-        const stat = await fs.stat(sourcePath);
-        if (stat.isFile()) {
-          files.push({ sourceRel: `${dir}/${entry}`, dir, name: entry, sourceRoot });
-        }
+      throw error;
+    }
+    for (const entry of entries) {
+      const sourcePath = path.join(sourceDir, entry);
+      const stat = await fs.stat(sourcePath);
+      if (stat.isFile()) {
+        files.push({ sourceRel: `${dir}/${entry}`, dir, name: entry, sourceRoot });
       }
     }
   }
+  return files;
+}
+
+async function listBundleSourceFiles(edition) {
+  // Order is preserved from when this was one nested loop over
+  // ['common', edition] x ['references', 'templates'] — the extraction is
+  // mechanical, and callers that key on array order see no change.
+  const files = [
+    ...(await scanBundleSourceRoot('common')),
+    ...(await scanBundleSourceRoot(edition))
+  ];
 
   assertNoBundleCollision(files);
   assertEditionBundleComplete(files, edition);
@@ -1386,6 +1575,8 @@ async function listBundleSourceFiles(edition) {
   return files;
 }
 
+const BUNDLE_EDITIONS = Object.freeze(['greenfield', 'brownfield']);
+
 // Reads the per-project workflow bundle manifest, distinguishing "absent"
 // (normal: fresh init / first projection) from "corrupt" (unreadable or invalid
 // shape). A corrupt manifest must NOT be treated as absent: that would silently
@@ -1623,6 +1814,483 @@ async function readPackagedBundleFile(sourceRoot, sourceRel) {
   }
 }
 
+// PROPOSAL-090 route B3 — refresh the Dflow-canonical half of the Git
+// principles starter. Same decision table as the guide above (user decision
+// 2026-06-08: skip + warn + offer; never rewrite unasked):
+//   - well-formed markers        -> replace the marked region in place
+//   - no markers, recognizable   -> skip + warn, flag for interactive adoption
+//   - no markers, unrecognizable -> skip + warn
+//   - malformed marker pair      -> skip + warn (never guess)
+//
+// ⚠ The region is sections 1-5 only. Sections 6+ (AI Collaboration Rules,
+// CI / CD) are project policy, and the file header carries a project-filled
+// `> Created: {YYYY-MM-DD}` — both stay outside. Known cost, accepted when the
+// route was chosen: canonical material that sits BELOW section 6 keeps drifting
+// (`## Related Documents` in all four; `## 7. Hotfixes under Trunk-based` in the
+// greenfield trunk starter, which is a drift that has actually happened).
+async function addGitPrinciplesItem(cwd, items, warnings, answers) {
+  const policy = answers.gitPolicy === 'gitflow' || answers.gitPolicy === 'trunk' ? answers.gitPolicy : null;
+  if (!policy) {
+    // ⚠ Say so rather than doing nothing. The policy comes from
+    // `_conventions.md` § Git Policy, and a missing section silently disables
+    // every downstream consumer — the defect PROPOSAL-091 exists to fix. A
+    // silent no-op here would add one more.
+    warnings.push(
+      'Could not determine the selected Git policy from `dflow/specs/shared/_conventions.md`, so `Git-principles-*.md` was not refreshed. Restore its `## Git Policy` section (`Selected Git policy: \`gitflow\`` or `\`trunk\``) and re-run.'
+    );
+    return;
+  }
+
+  const relativePath = `dflow/specs/shared/Git-principles-${policy}.md`;
+  const source = `packaged:${answers.edition}/scaffolding/Git-principles-${policy}.md`;
+  const absolute = path.join(cwd, relativePath);
+
+  let packaged = null;
+  let packagedError = null;
+  try {
+    packaged = await readPackagedTemplate(answers.edition, `scaffolding/Git-principles-${policy}.md`);
+  } catch (error) {
+    packagedError = error;
+  }
+  // ⚠⚠ AN UNREADABLE PACKAGED STARTER IS A BROKEN INSTALL, NOT A NO-OP. This
+  // used to be `catch { packaged = null; }` followed by a silent `return`, and
+  // `p090-b3-y1` executed what that bought: with the packaged starter deleted,
+  // `doctor` printed "`dflow configure-agents` fails on this package before
+  // writing a byte" while `configure-agents` exited 0, said nothing about Git
+  // principles, left stale canonical content in place, and still advanced the
+  // `> Dflow Version:` reconciliation line. The doctor sentence was a FALSE
+  // CLAIM ABOUT ANOTHER COMMAND — the precise failure this whole line of work
+  // exists to remove, committed while removing it.
+  // ⚠ It throws rather than warns, for the same reason the malformed-marker
+  // case below does: both mean the shipped package cannot answer what this
+  // function is for, and the four starters all ship, so neither state is
+  // reachable on a healthy install. Failing loudly keeps the two commands
+  // saying the same thing about one package.
+  if (packaged === null) {
+    throw new InitError(
+      `Internal error: packaged Git-principles-${policy}.md could not be read (${packagedError && packagedError.message ? packagedError.message : packagedError}).`
+    );
+  }
+
+  const packagedRegion = classifyMarkedRegion(
+    packaged,
+    GIT_PRINCIPLES_CANONICAL_START,
+    GIT_PRINCIPLES_CANONICAL_END
+  );
+  if (packagedRegion.state !== 'present') {
+    throw new InitError(
+      `Internal error: packaged Git-principles-${policy}.md has no well-formed git-principles-canonical markers.`
+    );
+  }
+
+  if (!(await pathExists(absolute))) {
+    // Seeding is `dflow init`'s job (it picks the policy). If the file is gone,
+    // doctor reports it; configure-agents does not silently re-create it,
+    // because a project that deleted it may have meant to.
+    return;
+  }
+
+  const existingContent = await fs.readFile(absolute, 'utf8');
+  const eol = detectDominantEol(existingContent);
+  const lf = toLf(existingContent);
+  const region = classifyMarkedRegion(lf, GIT_PRINCIPLES_CANONICAL_START, GIT_PRINCIPLES_CANONICAL_END);
+
+  const skipItem = (notes) => {
+    items.push({
+      relativePath,
+      source,
+      notes,
+      content: packaged,
+      action: 'skip',
+      intentionalSkip: true,
+      size: Buffer.byteLength(packaged, 'utf8')
+    });
+  };
+
+  if (region.state === 'present') {
+    const refreshed =
+      lf.slice(0, region.startIdx) +
+      packaged.slice(packagedRegion.startIdx, packagedRegion.endIdx) +
+      lf.slice(region.endIdx);
+    if (refreshed === lf) {
+      return;
+    }
+    pushRootInjectItem(items, {
+      relativePath,
+      source,
+      notes: 'refreshed Dflow-canonical Git principles (sections 1-5; your own sections kept)',
+      content: applyEol(refreshed, eol),
+      expectedContent: existingContent
+    });
+    return;
+  }
+
+  if (region.state === 'malformed') {
+    warnings.push(
+      `Existing ${relativePath} contains malformed git-principles-canonical markers; left it untouched. Repair or remove the stray markers and re-run so Dflow can refresh the canonical sections.`
+    );
+    skipItem('Git principles starter, malformed git-principles-canonical markers; left untouched');
+    return;
+  }
+
+  const bounds = gitPrinciplesCanonicalBounds(lf);
+  if (bounds) {
+    if (answers.adoptGitPrinciplesMarkers) {
+      // ⚠ The separators are rebuilt explicitly, not inherited from either side.
+      // `bounds` names the two heading lines and the packaged region is bounded
+      // by the marker text, so a naive three-way concat glues
+      // `<!-- ... END -->` onto `## 6.` and silently restructures a section this
+      // path promises to keep. (Whole-file EOL is normalized to the dominant
+      // ending either way — pre-existing shared behaviour, so the promise is
+      // content preservation, not byte equality, on a mixed-ending file.)
+      // Caught by review round
+      // `p090-b3-x1` as a critical finding, with a fixture that reproduced it.
+      const nl = String.fromCharCode(10);
+      const adopted =
+        lf.slice(0, bounds.start) +
+        nl +
+        packaged.slice(packagedRegion.startIdx, packagedRegion.endIdx) +
+        nl +
+        nl +
+        lf.slice(bounds.end);
+      pushRootInjectItem(items, {
+        relativePath,
+        source,
+        notes: 'adopted git-principles-canonical markers (kept your sections 6+ and the file header)',
+        content: applyEol(adopted, eol),
+        expectedContent: existingContent
+      });
+      return;
+    }
+    warnings.push(
+      `${relativePath} predates Dflow's git-principles-canonical markers, so its canonical sections stay at the Dflow version that wrote them. Re-run \`dflow configure-agents\` on an interactive terminal and accept the marker-adoption offer, or reconcile manually against a fresh \`dflow init\`.`
+    );
+    skipItem('Git principles starter, no git-principles-canonical markers; left untouched');
+    items[items.length - 1].offerGitPrinciplesAdoption = true;
+    return;
+  }
+
+  warnings.push(
+    `Existing ${relativePath} is not recognizable as a Dflow Git principles starter (its \`${GIT_PRINCIPLES_CANONICAL_FIRST_HEADING}\` / \`${GIT_PRINCIPLES_CANONICAL_AFTER_HEADING}\` headings were not both found); left it untouched.`
+  );
+  skipItem('Git principles starter, not recognizable; left untouched');
+}
+
+// The byte span sections 1-5 occupy in a pre-marker file: from the start of the
+// `## 1.` heading line to the start of the `## 6.` heading line.
+// ⚠ Search the MASK, slice the ORIGINAL — same rule as `classifyMarkedRegion`.
+// A heading shown inside a fenced example is documentation, not a boundary.
+// Returns null unless BOTH anchors are found exactly once, in order; anything
+// else is unrecognizable and must not be guessed at.
+function gitPrinciplesCanonicalBounds(lfContent) {
+  const searchable = doctorChecks.maskCodeBlocks(lfContent);
+  const nl = String.fromCharCode(10);
+  const first = nl + GIT_PRINCIPLES_CANONICAL_FIRST_HEADING + nl;
+  const after = nl + GIT_PRINCIPLES_CANONICAL_AFTER_HEADING + nl;
+  if (countOccurrences(searchable, first) !== 1 || countOccurrences(searchable, after) !== 1) {
+    return null;
+  }
+  // `start` lands ON the newline that precedes `## 1.` and `end` on the `#` of
+  // `## 6.`, so the caller owns every separator between the three pieces it
+  // joins. Making both point at the `#` is what produced the glued
+  // `<!-- ... END -->## 6.` that review round `p090-b3-x1` reproduced.
+  const start = searchable.indexOf(first);
+  const end = searchable.indexOf(after) + 1;
+  if (start >= end) {
+    return null;
+  }
+  return { start, end };
+}
+
+// PROPOSAL-058: the canonical AI agent guide is user-owned (it embeds the
+// project's "## Project Context"), but most of its body is Dflow-canonical
+// content that upgrades must be able to refresh — a guide frozen at its init
+// version leaves the re-projected workflow bundle § referencing sections the
+// guide does not have. The packaged template wraps the canonical body in
+// guide-canonical START/END markers. Decision table for an existing guide
+// (user decision 2026-06-08: skip + warn + offer; never rewrite unasked):
+//   - well-formed markers        -> replace the marked region in place (idempotent)
+//   - no markers, recognizable   -> skip + warn, and flag the item so an
+//     interactive run can offer marker adoption. Adoption replaces everything
+//     outside "## Project Context" with this version's canonical guide content;
+//     it is consent-gated because historical canonical text cannot be verified
+//     against the current package — only the user knows whether they customized
+//     sections outside Project Context.
+//   - no markers, unrecognizable -> skip + warn
+//   - malformed marker pair      -> skip + warn (never guess)
+async function addCanonicalGuideItem(cwd, items, warnings, packagedGuide, answers) {
+  const source = `packaged:${answers.edition}/scaffolding/AI-AGENT-GUIDE.md`;
+  const guidePath = path.join(cwd, AI_AGENT_GUIDE_DEST);
+
+  if (!(await pathExists(guidePath))) {
+    items.push({
+      relativePath: AI_AGENT_GUIDE_DEST,
+      source,
+      notes: 'canonical AI agent guide',
+      content: packagedGuide
+    });
+    return;
+  }
+
+  const packagedRegion = classifyMarkedRegion(
+    packagedGuide,
+    GUIDE_CANONICAL_SECTION_START,
+    GUIDE_CANONICAL_SECTION_END
+  );
+  if (packagedRegion.state !== 'present') {
+    throw new InitError('Internal error: packaged AI-AGENT-GUIDE.md has no well-formed guide-canonical markers.');
+  }
+
+  const existingContent = await fs.readFile(guidePath, 'utf8');
+  const eol = detectDominantEol(existingContent);
+  const lf = toLf(existingContent);
+  const region = classifyMarkedRegion(lf, GUIDE_CANONICAL_SECTION_START, GUIDE_CANONICAL_SECTION_END);
+
+  const skipItem = (notes) => {
+    items.push({
+      relativePath: AI_AGENT_GUIDE_DEST,
+      source,
+      notes,
+      content: packagedGuide,
+      action: 'skip',
+      intentionalSkip: true,
+      size: Buffer.byteLength(packagedGuide, 'utf8')
+    });
+  };
+
+  if (region.state === 'present') {
+    const refreshed =
+      lf.slice(0, region.startIdx) +
+      packagedGuide.slice(packagedRegion.startIdx, packagedRegion.endIdx) +
+      lf.slice(region.endIdx);
+    pushRootInjectItem(items, {
+      relativePath: AI_AGENT_GUIDE_DEST,
+      source,
+      notes: 'refreshed Dflow-canonical guide content (content outside the markers kept)',
+      content: applyEol(refreshed, eol),
+      expectedContent: existingContent
+    });
+    return;
+  }
+
+  if (region.state === 'malformed') {
+    warnings.push(
+      `Existing ${AI_AGENT_GUIDE_DEST} contains malformed guide-canonical markers; left it untouched. Repair or remove the stray markers and re-run so Dflow can refresh the canonical content.`
+    );
+    skipItem('canonical AI agent guide, malformed guide-canonical markers; left untouched');
+    return;
+  }
+
+  if (isRecognizableDflowGuide(lf)) {
+    if (answers.adoptGuideMarkers) {
+      pushRootInjectItem(items, {
+        relativePath: AI_AGENT_GUIDE_DEST,
+        source,
+        notes: 'adopted guide-canonical markers (kept your "## Project Context" section)',
+        content: applyEol(transplantProjectContext(packagedGuide, lf), eol),
+        expectedContent: existingContent
+      });
+      return;
+    }
+    warnings.push(
+      `${AI_AGENT_GUIDE_DEST} predates Dflow's guide-canonical markers, so its canonical sections stay at the Dflow version that wrote them. Re-run \`dflow configure-agents\` on an interactive terminal and accept the marker-adoption offer, or reconcile manually against a fresh \`dflow init\`.`
+    );
+    const item = 'canonical AI agent guide, no guide-canonical markers; left untouched';
+    skipItem(item);
+    items[items.length - 1].offerGuideAdoption = true;
+    return;
+  }
+
+  warnings.push(
+    `Existing ${AI_AGENT_GUIDE_DEST} is not recognizable as a Dflow guide; left it untouched.`
+  );
+  skipItem('canonical AI agent guide, not recognizable as a Dflow guide; left untouched');
+}
+
+// Fence-aware, and deliberately the same predicate transplantProjectContext
+// relies on: recognizability must imply locatable Project Context bounds, or
+// an accepted adoption offer would abort on the internal error below
+// (PROPOSAL-076 gate G3 — a guide whose only "## Project Context" heading sat
+// inside a fenced example was offered adoption and then crashed the run).
+// \u26A0 The title test compares the heading TEXT the shared classification produces,
+// rather than matching the raw line. That closes the last hand-rolled heading
+// rule outside `doctor-checks.js`, and it moves the behaviour twice, in opposite
+// directions \u2014 both deliberate, both pinned:
+//   - WIDER: a 0-3 space indent is a heading to CommonMark, and this line now
+//     accepts one. The old `^#` refused it while `projectContextSectionBounds`
+//     one function below already allowed it, so a guide indented by one space
+//     had a locatable Project Context and an unrecognizable title \u2014 the two
+//     halves of this very expression disagreeing.
+//   - NARROWER: the old `\s*$` also tolerated a trailing U+00A0 / form feed /
+//     vertical tab. CommonMark strips only spaces and tabs, so such a title is
+//     genuinely a different heading, and it is now reported as unrecognizable
+//     instead of being silently accepted. That direction is safe by
+//     construction: the caller's response to "not recognizable" is a warning
+//     plus leaving the user's file untouched, which is a loud, actionable
+//     failure rather than a silent rewrite of a file we misread.
+function isRecognizableDflowGuide(lfContent) {
+  const content = lfContent.replace(/^\uFEFF/, ''); // a BOM must not defeat the title line (gate G4)
+  const scan = doctorChecks.blankFencedBlocks(content);
+  const titled = doctorChecks.classifyLines(scan)
+    .some((c) => c.heading && c.heading.level === 1 && c.heading.text === 'Dflow AI Agent Guide');
+  return titled && projectContextSectionBounds(content) !== null;
+}
+
+// Bounds of the "## Project Context" section in LF content: the heading line up
+// to (exclusive) the next "## " heading, the guide-canonical START marker, or EOF.
+// Fence-aware (PROPOSAL-076 gate G1): headings or markers inside ``` / ~~~
+// examples are content, not structure — the boundary scan runs on a
+// fence-blanked shadow while the returned lines stay the real content.
+// \u26A0 Heading detection here goes through `doctorChecks.classifyLines`, and that
+// is the point rather than a tidy-up. This function used to hand-roll its own
+// ATX rules, which made it a FOURTH place deciding what a heading is; `g5`
+// finding 2 caught it a patch behind its siblings \u2014 it had taken the 0-3 space
+// indent but not the "space or tab after the hashes" rule, so a bare `##` did
+// not end the section and a `| Tech stack |` row below it was read as though it
+// were still inside Project Context. Routing it through the classification is
+// what makes that class of lag impossible rather than merely fixed once.
+//
+// Two consequences of using the shared rules, both verified against the
+// packaged guides in `test/upgrade-drift.mjs`:
+//   - the section now also ends at a LEVEL-1 heading, not only an H2. Both
+//     packaged guides carry exactly one H1 and it is line 1, above Project
+//     Context, so nothing packaged moves; an adopter's guide with an H1 further
+//     down now ends the section there, which is what CommonMark says.
+//   - `## Project Context ##` and a setext-underlined `Project Context` are now
+//     found, where the old literal test saw neither.
+function projectContextSectionBounds(lfContent) {
+  const stripped = lfContent.replace(/^\uFEFF/, ''); // keep BOM out of the line-0 heading match (gate G4)
+  const lines = stripped.split('\n');
+  const scan = doctorChecks.blankFencedBlocks(stripped);
+  const info = doctorChecks.classifyLines(scan);
+  // ⚠⚠ `heading.start`, NOT the array index. `classifyLines` reports a SETEXT
+  // heading at its UNDERLINE line, and carries the real first line in
+  // `heading.start`. Using the index here — while this function had just been
+  // widened to recognize setext headings at all — meant the returned slice began
+  // at the underline: `transplantProjectContext` then dropped the heading text
+  // `Project Context`, swallowed the NEXT section's heading text into the kept
+  // region, and wrote the result to the user's guide. Re-parsing that output
+  // returns null, so the guide becomes permanently unrecognizable and
+  // `configure-agents` refuses to touch it again — all behind an interactive
+  // offer whose text promises "your Project Context section is kept".
+  // CONTENT LOSS, on disk. `conventionsSectionBodies` had this right; this
+  // function was widened without taking the same field with it.
+  const at = info.findIndex((c) => c.heading && c.heading.level === 2 && c.heading.text === 'Project Context');
+  if (at < 0) return null;
+  const start = info[at].heading.start;
+  let end = scan.length;
+  for (let i = at + 1; i < scan.length; i += 1) {
+    if (info[i].heading && info[i].heading.level <= 2) {
+      end = info[i].heading.start;
+      break;
+    }
+    if (scan[i].startsWith(GUIDE_CANONICAL_SECTION_START)) {
+      end = i;
+      break;
+    }
+  }
+  return { lines, start, end };
+}
+
+// PROPOSAL-058 bootstrap: rebuild the guide from the packaged template, carrying
+// over the project's own "## Project Context" section (trailing blank lines normalized; the only
+// user-specific region by contract). Everything else — including any prose the
+// user kept outside Project Context — is replaced; the interactive offer says so
+// and defaults to No.
+function transplantProjectContext(packagedGuide, existingLf) {
+  const existing = projectContextSectionBounds(existingLf);
+  const packaged = projectContextSectionBounds(packagedGuide);
+  if (!existing || !packaged) {
+    throw new InitError('Internal error: cannot locate "## Project Context" while adopting guide markers.');
+  }
+  const existingSection = existing.lines.slice(existing.start, existing.end);
+  // ⚠ `BLANK_LINE_RE` and not `.trim()`: a line holding only a U+00A0 is NOT
+  // blank to CommonMark, and `.trim()` would pop it off the end of a section
+  // this function is about to write back to a user-owned file.
+  // ⚠ Imported rather than written inline. The first fix here spelled
+  // `/^[ \t]*$/` by hand, which made it a THIRD copy of the rule while the
+  // commit message claimed there were only two — the same "two expressions, one
+  // rule" shape the whole rewrite exists to remove.
+  while (existingSection.length > 0
+    && doctorChecks.BLANK_LINE_RE.test(existingSection[existingSection.length - 1])) {
+    existingSection.pop();
+  }
+  return [
+    ...packaged.lines.slice(0, packaged.start),
+    ...existingSection,
+    '',
+    ...packaged.lines.slice(packaged.end)
+  ].join('\n');
+}
+
+// PROPOSAL-058: the interactive adoption questions. Only a TTY run ever asks
+// (the PROPOSAL-074 non-TTY contract: never consume a stdin slot); blank answers
+// mean No because both offers rewrite a user-owned file.
+async function askGuideMarkerAdoption(rl, stdout) {
+  stdout.write(
+    `\nYour ${AI_AGENT_GUIDE_DEST} predates Dflow's managed canonical markers, so\n` +
+    'upgrades cannot refresh its canonical sections in place. Adopting the markers\n' +
+    'replaces everything OUTSIDE "## Project Context" with this Dflow version\'s\n' +
+    'canonical guide content (your Project Context section is kept).\n' +
+    'Answer N if you customized any other guide section.\n'
+  );
+  return askConfirmation(rl, 'Adopt the managed guide markers now? (y/N) ');
+}
+
+async function askGitPrinciplesMarkerAdoption(rl, stdout) {
+  const nl = String.fromCharCode(10);
+  stdout.write(
+    nl +
+    "Your Git-principles-*.md predates Dflow's managed canonical markers, so" + nl +
+    'upgrades cannot refresh its canonical sections in place. Adopting the markers' + nl +
+    "replaces sections 1-5 with this Dflow version's content; your file header and" + nl +
+    'everything from "## 6. AI Collaboration Rules (Project Policy)" down —' + nl +
+    'including your CI / CD section — is kept as you wrote it. (Line endings are' + nl +
+    'unified to whichever this file already uses most, as on every write.)' + nl +
+    'Answer N if you customized any of sections 1-5.' + nl
+  );
+  return askConfirmation(rl, 'Adopt the managed Git principles markers now? (y/N) ');
+}
+
+async function askShimBlockAdoption(rl, stdout, agent) {
+  const relativePath = getAiAgentTarget(agent).relativePath;
+  stdout.write(
+    `\n${relativePath} references the Dflow guide but is not Dflow-managed (no markers),\n` +
+    'so upgrades cannot refresh any Dflow wording inside it. Dflow can append its\n' +
+    'managed, marker-delimited block at the end of the file; afterwards remove any\n' +
+    'older Dflow wording you keep above the block.\n'
+  );
+  return askConfirmation(rl, `Append the managed Dflow block to ${relativePath}? (y/N) `);
+}
+
+// PROPOSAL-058 (user decision 2026-06-08, OQ2): `> Dflow Version:` in
+// _conventions.md means "the Dflow version this project last reconciled with",
+// so a successful configure-agents run must advance it — before this it froze at
+// the init version, which was a bug, not a design. Narrow single-line rewrite of
+// a user-owned file: previewed like every plan item, guarded by the rootInject
+// raw-equality check, and never *added* when the line is absent (doctor reports
+// that case instead).
+async function addConventionsVersionReconcileItem(cwd, items) {
+  const relativePath = 'dflow/specs/shared/_conventions.md';
+  const absolute = path.join(cwd, relativePath);
+  if (!(await pathExists(absolute))) return;
+  const existingContent = await fs.readFile(absolute, 'utf8');
+  const lf = toLf(existingContent);
+  const match = lf.match(/^> Dflow Version:[ \t]*(.*)$/m);
+  if (!match || match[1].trim() === pkg.version) return;
+  const eol = detectDominantEol(existingContent);
+  const updated = lf.replace(/^> Dflow Version:[ \t]*.*$/m, `> Dflow Version: ${pkg.version}`);
+  pushRootInjectItem(items, {
+    relativePath,
+    source: 'generated:dflow-version-reconcile',
+    notes: `update Dflow Version line to ${pkg.version} (last reconciled)`,
+    content: applyEol(updated, eol),
+    expectedContent: existingContent
+  });
+  // See the call-site comment: never advance the line over a guarded skip.
+  items[items.length - 1].requiresFullApply = true;
+}
+
 // PROPOSAL-054: configure a tool's root agent file. A non-guide existing file used
 // to be parked as a side merge snippet ("hand-merge this yourself"); it is now an
 // auto-injected, marker-delimited Dflow block shown in the confirmation preview.
@@ -1673,7 +2341,7 @@ async function addAiAgentShim(cwd, items, agent, substitution, options = {}) {
 
   const existingContent = await fs.readFile(targetPath, 'utf8');
   const eol = detectDominantEol(existingContent);
-  const lf = existingContent.replace(/\r\n/g, '\n');
+  const lf = toLf(existingContent);
   const agentRegion = classifyMarkedRegion(lf, AGENT_SHIM_SECTION_START, AGENT_SHIM_SECTION_END);
   // Classify the Codex trigger region on EVERY AGENTS.md run (not only when we are
   // about to manage the trigger): even a non---command-adapters run replaces the
@@ -1779,7 +2447,40 @@ async function addAiAgentShim(cwd, items, agent, substitution, options = {}) {
   // marker-managed (a guide-configured file the user wrote / heavily edited). Keep
   // the base shim skipped so we never duplicate their guide pointer. Under Codex
   // --command-adapters still install / update the self-delimited trigger block (OQ#6c).
+  // PROPOSAL-058: any Dflow wording inside such a file is frozen (old canonical
+  // prose and user prose cannot be told apart mechanically), so an interactive run
+  // offers to append the managed block instead — with consent the file becomes
+  // marker-managed (future runs refresh it via case 2b) and the user removes their
+  // older Dflow wording; without consent (or non-TTY) the 2d behavior is unchanged.
   if (contentReferencesAiAgentGuide(existingContent)) {
+    const adoptShimAgents = options.adoptShimAgents || [];
+    if (adoptShimAgents.includes(agent)) {
+      let updated = appendBlockLf(lf, agentShimBlock);
+      if (wantsTrigger) {
+        updated = upsertCodexTriggerBlock(updated, triggerBlock);
+      }
+      if (warnings) {
+        warnings.push(
+          `Appended the managed Dflow block to ${target.relativePath}; future upgrades refresh it in place. Review the file and remove any older Dflow wording outside the marked block.`
+        );
+      }
+      pushRootInjectItem(items, {
+        relativePath: target.relativePath,
+        source,
+        notes: `selected, appended managed Dflow block to existing ${target.relativePath}`,
+        content: applyEol(updated, eol),
+        expectedContent: existingContent
+      });
+      return;
+    }
+    // No consent (declined, or a non-interactive run): keep the 2d skip, but say
+    // so — the docs promise "skip and warn", and the frozen Dflow wording is
+    // exactly the drift this proposal makes visible.
+    if (warnings) {
+      warnings.push(
+        `${target.relativePath} references the Dflow guide but is not marker-managed; Dflow wording inside it stays frozen on upgrade. Re-run \`dflow configure-agents\` on an interactive terminal to accept the managed-block offer, or keep maintaining the file yourself (\`dflow doctor\` reports this state).`
+      );
+    }
     if (wantsTrigger) {
       pushRootInjectItem(items, {
         relativePath: target.relativePath,
@@ -1788,6 +2489,7 @@ async function addAiAgentShim(cwd, items, agent, substitution, options = {}) {
         content: applyEol(upsertCodexTriggerBlock(lf, triggerBlock), eol),
         expectedContent: existingContent
       });
+      items[items.length - 1].offerShimAdoption = agent;
     } else {
       items.push({
         relativePath: target.relativePath,
@@ -1796,6 +2498,7 @@ async function addAiAgentShim(cwd, items, agent, substitution, options = {}) {
         content: fullShim,
         action: 'skip',
         intentionalSkip: true,
+        offerShimAdoption: agent,
         size: Buffer.byteLength(fullShim, 'utf8')
       });
     }
@@ -1879,7 +2582,7 @@ function appendBlockLf(lfContent, block) {
 // dominant EOL (the approved EOL policy), so a pure LF / pure CRLF user prefix
 // round-trips byte-for-byte. `blocks` are LF strings.
 function appendDflowBlocks(existingContent, blocks, eol) {
-  const lf = existingContent.replace(/\r\n/g, '\n');
+  const lf = toLf(existingContent);
   return applyEol(appendBlockLf(lf, blocks.join('\n\n')), eol);
 }
 
@@ -1907,14 +2610,23 @@ function extractCodexTriggerBlock(content) {
 // The markers are single-line HTML comments, so classification is identical on raw or
 // LF-normalized content; callers slice on whichever string they passed in.
 function classifyMarkedRegion(content, startMarker, endMarker) {
-  const startCount = countOccurrences(content, startMarker);
-  const endCount = countOccurrences(content, endMarker);
+  // ⚠ SEARCH THE MASK, SLICE THE ORIGINAL. A marker shown inside a fenced or
+  // indented code example is documentation, not a region boundary — treating it
+  // as one overwrote a user's own example with generated content, silently
+  // (`p082-b3-k3` finding 1). `maskCodeBlocks` preserves every offset, so the
+  // indices returned here still address `content`.
+  // ⚠ This is the same defect class as the one the conventions checks had: a
+  // consumer deciding a structural question by not asking the classifier. It is
+  // fixed here by asking.
+  const searchable = doctorChecks.maskCodeBlocks(content);
+  const startCount = countOccurrences(searchable, startMarker);
+  const endCount = countOccurrences(searchable, endMarker);
   if (startCount === 0 && endCount === 0) {
     return { state: 'absent' };
   }
   if (startCount === 1 && endCount === 1) {
-    const startIdx = content.indexOf(startMarker);
-    const endInner = content.indexOf(endMarker);
+    const startIdx = searchable.indexOf(startMarker);
+    const endInner = searchable.indexOf(endMarker);
     if (startIdx < endInner) {
       return { state: 'present', startIdx, endIdx: endInner + endMarker.length };
     }
@@ -1963,6 +2675,30 @@ function codexTriggerMarkersStraddle(content, start, end) {
 // Dominant line ending of a user file, so injected blocks match it (Windows projects
 // may be CRLF). The repo's own LF policy (.gitattributes) governs repo files only, not
 // an adopter's project files.
+// Normalize any line ending to LF — CRLF **and a lone CR**, CommonMark's third
+// form. The lone-CR half is not pedantry. `lfContent` / `existingLf` are threaded
+// through the guide pipeline as a PROMISE that the content is LF, and
+// `projectContextSectionBounds` splits it on newline while its fence-aware scan
+// goes through `blankFencedBlocks`. While both sides ignored a lone CR they were
+// wrong together and therefore harmless — such a guide simply was not
+// recognized. Fixing only the scan side (`p082-b3-g1` finding 3) made them
+// DISAGREE: a CR-only guide became "recognizable", its Project Context sliced to
+// nothing, and `configure-agents` exited 0 having transplanted an EMPTY section
+// — silently discarding the one region that whole path exists to preserve.
+// Caught by `p082-b3-g2` finding 1, a regression this batch introduced.
+//
+// The lesson is the one this batch keeps paying for: a normalization is a
+// contract between everyone who reads the value, so it needs ONE definition.
+// Six call sites had each spelled the CRLF replacement out by hand, so "is this
+// LF now?" had six answers that agreed only by luck.
+//
+// ⚠ Consequence worth knowing: a CR-only file is rewritten with LF endings.
+// `detectDominantEol` only distinguishes CRLF from LF and already returned LF
+// for such a file, so this makes existing behaviour honest rather than new.
+function toLf(content) {
+  return String(content).replace(/\r\n|\r/g, '\n');
+}
+
 function detectDominantEol(content) {
   const crlf = (content.match(/\r\n/g) || []).length;
   const lfOnly = (content.match(/\n/g) || []).length - crlf;
@@ -1970,7 +2706,7 @@ function detectDominantEol(content) {
 }
 
 function applyEol(content, eol) {
-  const normalized = content.replace(/\r\n/g, '\n');
+  const normalized = toLf(content);
   return eol === '\r\n' ? normalized.replace(/\n/g, '\r\n') : normalized;
 }
 
@@ -1993,10 +2729,14 @@ function getAiAgentTarget(agent) {
   return targets[agent];
 }
 
-function buildAiAgentShim(targetPath, commandRegistry = []) {
-  const title = targetPath === '.github/copilot-instructions.md'
+function shimTitle(targetPath) {
+  return targetPath === '.github/copilot-instructions.md'
     ? 'GitHub Copilot Repository Instructions'
     : `${targetPath} - Dflow Project Instructions`;
+}
+
+function buildAiAgentShim(targetPath, commandRegistry = []) {
+  const title = shimTitle(targetPath);
 
   const commandTriggerHint = targetPath === 'AGENTS.md' && commandRegistry.length > 0
     ? buildCodexCommandTriggerSection(commandRegistry)
@@ -2012,8 +2752,17 @@ domain behavior, a new requirement, or a bug-fix workflow — read and follow:
 - \`dflow/specs/shared/AI-AGENT-GUIDE.md\` — command registry, routing rules, and project context.
 - \`dflow/specs/shared/dflow-workflows/\` — vendored workflow bundle with executable step definitions.
 
-For routine work (refactors, renames, chores, formatting, dependency bumps, or
-general code questions), proceed normally; you need not read the guide first.
+For routine work (refactors, renames, chores, formatting, routine dependency
+bumps, or general code questions), proceed normally; you need not read the guide
+first. **Routine is narrower than it sounds** — it excludes anything a product
+audience perceives (UI, email, exports, public docs such as a product README or
+API reference, and operator surfaces like dashboard labels and alerts), where
+**size is not the test**: a single-element wording or appearance change still
+counts. It also excludes anything touching architecture, data structure, a
+machine-consumed contract, a BR-ID, operational semantics (security / CVE,
+safety, resilience, compliance, payment), or deliberate performance / resource /
+SLA work. When unsure, read the guide's § Ceremony Scaling —
+it decides, not this page.
 
 Keep tool-specific instruction files small. The guide and workflow bundle are
 the authoritative sources for Dflow workflow rules, slash-command behavior,
@@ -2021,17 +2770,82 @@ spec locations, and SDD/DDD constraints.${commandTriggerHint}
 `;
 }
 
-// Frozen pre-scoping shim body (the wording shipped through v0.9.0 and the
-// Phase-2 @import-removal interim: "Before planning or editing code ..."). Used
-// ONLY by isPristineDflowAgentsShim so an adopter's older whole-file shim is
-// still recognized as Dflow-generated and regenerated to the current scoped
-// wording. Changing buildAiAgentShim's body without updating this matcher would
-// strand old shims on the guide-reference skip path — they would keep the old
-// body, and for CLAUDE.md the legacy @import.
+// ⚠⚠ READ BEFORE EDITING ANY VERSION NUMBER BELOW. The version→body map has now
+// been corrected in three consecutive review rounds, each time in a new way:
+// first the whole oldest body was missing; then the range was written as
+// starting at v0.1.0 (it starts at v0.1.1); then the handover to the next body
+// was pinned to v0.9.0 (it is 0.8.0). Per this repo's rule that a thing rewritten
+// three times is a design question rather than a fourth patch, the cause is
+// named here instead of the numbers being nudged again:
+//
+//   **`git tag` is NOT the list of releases.** 0.8.0 shipped to npm and has no
+//   tag — `git tag` jumps v0.7.0 → v0.9.0 — so any range re-derived from tags
+//   alone will silently skip it.
+//
+//   ⚠ `CHANGELOG.md` is not the list either, and an earlier version of this note
+//   sent people there: it has no `## 0.13.0` heading — that entry was folded
+//   away by the 0.14.0 release prep — so the same kind of hole reappears one
+//   version along. Nor does `-S'"version": "0.X.0"'` enumerate: it can only
+//   confirm a version you already suspect, and `X` is the unknown.
+//
+//   **The one command that actually enumerates** (15 bumps, including untagged
+//   0.8.0 and CHANGELOG-less 0.13.0):
+//
+//       git log -G'"version": "0\.' --oneline -- package.json
+//
+//   Then read `buildAiAgentShim` at that release commit — not at the nearest tag.
+//
+// Nothing in the runtime depends on these numbers: `.some()` short-circuits over
+// the builders and no two shipped bodies normalize equal. They exist so a
+// maintainer can tell whether the list reaches all the way back — which is
+// exactly why being wrong about them has cost three rounds.
+//
+// Frozen pre-bundle shim body: the oldest body `buildAiAgentShim` ever
+// generated, carried by v0.1.1 through v0.7.0. One guide bullet, no
+// workflow-bundle bullet, and a "The Dflow guide above is the single source of
+// truth" tail. Introduced by `eabee5c` (earliest release tag v0.1.1) and
+// replaced by `5498120` (PROPOSAL-039, vendored workflow bundle), which first
+// shipped in **0.8.0** (release commit `66681d6`, untagged).
+//
+// ⚠ NOT "the first body Dflow ever shipped", and the range does not reach
+// v0.1.0. At v0.1.0 `lib/init.js` did not reference the guide at all — it wrote
+// CLAUDE.md from the packaged `CLAUDE-md-snippet.md` via a different code path,
+// producing a two-H2 `System Context` / `Development Workflow` document with
+// per-project values substituted in. That body is deliberately NOT in this list
+// and cannot be: a frozen builder matches a fixed string, and a
+// placeholder-substituted document has no fixed form to match. A v0.1.0 project
+// therefore degrades to the not-marker-managed branch, which is correct
+// behaviour for a file whose content is partly the developer's.
+//
+// It was missing from the frozen set until 2026-08-03, and the omission was
+// live: a project still carrying this body failed the match, fell to the
+// "not marker-managed" branch and kept the v0.1-v0.7 wording permanently.
+// Confirmed by planting it in a real project and running `configure-agents`.
+// The list comment said "oldest first" while starting at the second-oldest.
+function buildPreBundleAgentShimBody(targetPath) {
+  const title = shimTitle(targetPath);
+
+  return `# ${title}
+
+This project uses Dflow for spec-first AI-assisted development.
+
+Before planning or editing code, read and follow:
+
+- \`dflow/specs/shared/AI-AGENT-GUIDE.md\`
+
+Keep tool-specific instruction files small. The Dflow guide above is the
+single source of truth for project workflow rules, slash-command behavior,
+spec locations, and SDD/DDD constraints.
+`;
+}
+
+// Frozen pre-scoping shim body: shipped in **0.8.0 and v0.9.0** (and the
+// Phase-2 @import-removal interim) — "Before planning or editing code ...".
+// Its old wording is INTENTIONAL — this function exists to recognize it. See
+// FROZEN_SHIM_BODY_BUILDERS below for why, and the ⚠⚠ note above
+// buildPreBundleAgentShimBody before touching the version numbers.
 function buildLegacyAgentShimBody(targetPath) {
-  const title = targetPath === '.github/copilot-instructions.md'
-    ? 'GitHub Copilot Repository Instructions'
-    : `${targetPath} - Dflow Project Instructions`;
+  const title = shimTitle(targetPath);
 
   return `# ${title}
 
@@ -2048,6 +2862,79 @@ spec locations, and SDD/DDD constraints.
 `;
 }
 
+// Frozen unqualified-routine shim body (shipped 0.10.0 through 0.14.0): the
+// scoped wording before PROPOSAL-082 narrowed "routine". Its routine paragraph
+// waved through the classes the cascade calls tracked — a security dep bump, an
+// operational-axis refactor, a Domain rename — and told the agent not to read
+// the guide, so the shim contradicted the guide it points at.
+function buildUnqualifiedRoutineShimBody(targetPath) {
+  const title = shimTitle(targetPath);
+
+  return `# ${title}
+
+This project uses Dflow for spec-first AI-assisted development.
+
+For spec-impacting work — a new feature, a change to product, user-facing, or
+domain behavior, a new requirement, or a bug-fix workflow — read and follow:
+
+- \`dflow/specs/shared/AI-AGENT-GUIDE.md\` — command registry, routing rules, and project context.
+- \`dflow/specs/shared/dflow-workflows/\` — vendored workflow bundle with executable step definitions.
+
+For routine work (refactors, renames, chores, formatting, dependency bumps, or
+general code questions), proceed normally; you need not read the guide first.
+
+Keep tool-specific instruction files small. The guide and workflow bundle are
+the authoritative sources for Dflow workflow rules, slash-command behavior,
+spec locations, and SDD/DDD constraints.
+`;
+}
+
+// Every shim body Dflow has shipped, oldest first. Used ONLY by
+// isPristineDflowAgentsShim, so an adopter carrying any previously-generated
+// whole-file shim is still recognized as Dflow-generated and regenerated to the
+// current wording.
+//
+// ⚠ CHANGING buildAiAgentShim's BODY MEANS APPENDING THE OUTGOING BODY HERE, in
+// the same commit. Miss it and every adopter on the previous release is stranded
+// on the guide-reference skip path: their shim stops matching, degrades to the
+// "not marker-managed" branch, and keeps the superseded body forever — plus, for
+// CLAUDE.md, the legacy @import. The failure is silent on the maintainer's box,
+// because a freshly-generated shim always matches the body it was just built
+// from; only an upgrade from a real older project shows it.
+//
+// The rule has exactly one exception, and it follows from that failure mode: an
+// outgoing body that **never appeared in a release** has no adopters to strand,
+// so it does not go in the list. ⚠ Establish that from the version-bump history
+// (the enumerating command in the ⚠⚠ note above), NOT from `git tag --contains`
+// — that note says why `git tag` is not the list of releases, and a body
+// introduced and replaced *between* two releases is exactly where the tag test
+// and the truth diverge. Taking the exception is not free: a project scaffolded
+// from this repo while the orphan body was current carries it, and
+// `configure-agents` then refuses to regenerate that file in place — loudly,
+// via the "not marker-managed" warning, leaving the file untouched.
+//
+// This is a list rather than a single fallback because the one-body form had to
+// be edited correctly at exactly the moment a body changed, which is the moment
+// attention is on the new wording. `test/agent-inject.mjs` carries one upgrade
+// case per entry (§3b / §3e / §3f, plus §3g for the AGENTS.md+trigger
+// composition) — NOT upgrade-drift.mjs, which has no
+// shim-body case at all.
+//
+// ⚠ Adding a builder here means adding its case there in the same commit. That
+// pairing is not machine-enforced; the list can grow without a test.
+//
+// The v0.1-v0.7 entry was missing from the first version of this list, so the
+// list shipped one release while contradicting its own "oldest first" label and
+// stranding the very adopters it names. Order is documentation only —
+// `.some()` short-circuits and no two shipped bodies normalize equal — but the
+// label has to be true, because it is what tells the next maintainer whether
+// the list reaches all the way back.
+const FROZEN_SHIM_BODY_BUILDERS = [
+  buildPreBundleAgentShimBody,
+  buildLegacyAgentShimBody,
+  buildUnqualifiedRoutineShimBody
+];
+
 function addCommandAdapterItems(items, aiAgents, commandRegistry) {
   if (aiAgents.includes('claude')) {
     for (const command of commandRegistry) {
@@ -2231,12 +3118,11 @@ ${argHint}
 }
 
 function normalizeCommandAdapterFingerprint(content) {
-  return String(content).replace(/\r\n/g, '\n');
+  return toLf(content);
 }
 
 function normalizeShimForMatch(content) {
-  return String(content)
-    .replace(/\r\n/g, '\n')
+  return toLf(content)
     .split('\n')
     .map((line) => line.replace(/[ \t]+$/, ''))
     .join('\n')
@@ -2283,12 +3169,13 @@ function isPristineDflowAgentsShim(existingContent, baseShim, relativePath) {
   if (existing === target) {
     return true;
   }
-  // Back-compat: older Dflow shims (v0.9.0 / Phase-2 interim) used different body
-  // wording ("Before planning or editing code ..."). Recognize that frozen
-  // wording as pristine so configure-agents regenerates it to the current scoped
-  // wording (and, for CLAUDE.md, drops the legacy @import already stripped above).
-  // Without this, the body reword would strand old shims on the skip path.
-  return existing === normalizeShimForMatch(buildLegacyAgentShimBody(relativePath));
+  // Back-compat: every shim body Dflow has previously shipped counts as pristine,
+  // so configure-agents regenerates it to the current wording (and, for CLAUDE.md,
+  // drops the legacy @import already stripped above). Without this, each body
+  // reword would strand the previous release's shims on the skip path.
+  return FROZEN_SHIM_BODY_BUILDERS.some(
+    (buildFrozenBody) => existing === normalizeShimForMatch(buildFrozenBody(relativePath))
+  );
 }
 
 function buildCodexCommandTriggerSection(commandRegistry) {
@@ -2462,13 +3349,13 @@ function validateDflowCommandRegistryRow(command, seen) {
   }
 }
 
+// Greenfield: the five common rows then `events.md` and the ADR row — the same
+// seven paths, in the same order, that `test/upgrade-drift.mjs` pins.
+// Brownfield: the five common rows only.
 function buildDeferredItems(edition) {
   const deferred = [...DEFERRED_COMMON];
   if (edition === 'greenfield') {
-    deferred.splice(3, 0, {
-      relativePath: 'dflow/specs/domain/{context}/events.md',
-      reason: 'Greenfield only, but still needs a real bounded context.'
-    });
+    deferred.push(...DEFERRED_GREENFIELD_ONLY);
   }
   return deferred;
 }
@@ -2517,8 +3404,13 @@ function buildSubstitutionMap(cwd, answers) {
     ['{系統名稱}', systemName],
     ['{project-type}', answers.projectType],
     ['{edition}', answers.edition],
-    ['{tech-stack-summary}', answers.techStackSummary],
-    ['{migration-context}', answers.migrationContext],
+    // These two land in the guide's "## Project Context" table cells (their
+    // only template use), so bare `|` in the free-text answers must be escaped
+    // or the row gains phantom cells and inference later truncates the value —
+    // escapeTableCell is the exact inverse of parseContextLine's unescape
+    // (PROPOSAL-076 gate G2 round-trip fix).
+    ['{tech-stack-summary}', escapeTableCell(answers.techStackSummary)],
+    ['{migration-context}', escapeTableCell(answers.migrationContext)],
     ['{prose-language}', answers.proseLanguage],
     ['{dflow-version}', pkg.version],
     ['{Language}', extracted.language || '{Language}'],
@@ -2543,6 +3435,28 @@ function buildSubstitutionMap(cwd, answers) {
   return map;
 }
 
+// Every placeholder token `substitutePlaceholders` can replace, derived from the
+// map itself so it cannot go stale. Exported for the guard that keeps
+// marker-delimited canonical regions substitution-free: those regions are
+// compared and rewritten as RAW PACKAGED BYTES, so a substituted token inside
+// one makes a freshly-projected file differ from its own packaged source.
+// ⚠ The answers are deliberately irrelevant here. `p090-b3-y1` caught the first
+// version of that guard proving only what its fixed init answers happened to
+// substitute: `{ORM / persistence}` maps to ITSELF when no ORM is named, so it
+// survived projection unchanged and the byte-comparison passed over it — while
+// an adopter who does name an ORM would get exactly the reported defect.
+function placeholderTokens() {
+  const probe = buildSubstitutionMap(process.cwd(), {
+    techStackSummary: '',
+    migrationContext: '',
+    proseLanguage: '',
+    projectType: '',
+    edition: '',
+    gitPolicy: null
+  });
+  return [...probe.keys()];
+}
+
 function substitutePlaceholders(content, substitution) {
   let result = content;
   for (const [placeholder, value] of substitution.entries()) {
@@ -2693,6 +3607,20 @@ function extractTestFramework(text) {
   return null;
 }
 
+// ⚠ THIS FAMILY DELIBERATELY DOES NOT GO THROUGH `doctorChecks.classifyLines`,
+// and the boundary is worth stating because the rest of this file just moved the
+// other way (see `projectContextSectionBounds`). `ensureProseLanguageSection`,
+// `stripProseLanguageSections` and `stripNamedSections` only ever see content
+// this process generated moments earlier — `readPackagedTemplate` followed by
+// `substitutePlaceholders`, at the single call site in `addTemplate` — so the
+// heading shapes they must handle are the ones the packaged templates contain,
+// not the ones an adopter might type. They also fail LOUDLY on a mis-parse: the
+// `count !== 1` assertion below throws rather than writing a wrong file.
+//
+// The functions that DID move are the ones that read USER-OWNED files and ask
+// the same questions doctor asks. That is the line: parse a file someone else
+// wrote, use the shared classification; reshape a string you just rendered
+// yourself, a literal match is honest and the assertion covers it.
 function ensureProseLanguageSection(content, proseLanguage) {
   const section = buildProseLanguageSection(proseLanguage);
   let stripped = stripProseLanguageSections(content);
@@ -2861,10 +3789,28 @@ async function writeFilePlan(cwd, plan) {
     warnings: []
   };
 
+  // PROPOSAL-058: an item flagged requiresFullApply (the `> Dflow Version:`
+  // last-reconciled advance) may only run when every previewed change actually
+  // applied. Guarded skips — changed-after-preview, vanished / non-file
+  // targets, unexpected existing targets — mean the previewed reconciliation
+  // is incomplete, so the flagged item is skipped with a warning instead of
+  // overstating the reconciled version. Intentional skips (already current /
+  // already configured) do not block it, and neither does removing a stale
+  // file that is already gone (the desired end state holds).
+  let unexpectedSkip = false;
+
   for (const item of plan.items) {
     const targetPath = path.join(cwd, item.relativePath);
 
     try {
+      if (item.requiresFullApply && unexpectedSkip) {
+        result.skipped.push(item.relativePath);
+        result.warnings.push(
+          `Skipped the Dflow Version update in ${item.relativePath} because earlier planned changes were skipped after the preview; re-run \`dflow configure-agents\`.`
+        );
+        continue;
+      }
+
       if (item.action === 'remove') {
         let stats;
         try {
@@ -2879,6 +3825,7 @@ async function writeFilePlan(cwd, plan) {
         }
 
         if (!stats.isFile()) {
+          unexpectedSkip = true;
           result.skipped.push(item.relativePath);
           result.warnings.push(`Skipped stale removal because target is not a file: ${item.relativePath}`);
           continue;
@@ -2886,6 +3833,7 @@ async function writeFilePlan(cwd, plan) {
 
         const currentContent = await fs.readFile(targetPath, 'utf8');
         if (normalizeCommandAdapterFingerprint(currentContent) !== normalizeCommandAdapterFingerprint(item.expectedContent || '')) {
+          unexpectedSkip = true;
           result.skipped.push(item.relativePath);
           result.warnings.push(`Skipped stale removal because content changed after preview: ${item.relativePath}`);
           continue;
@@ -2908,6 +3856,7 @@ async function writeFilePlan(cwd, plan) {
           stats = await fs.stat(targetPath);
         } catch (error) {
           if (error.code === 'ENOENT') {
+            unexpectedSkip = true;
             result.skipped.push(item.relativePath);
             result.warnings.push(`Skipped Dflow block update because ${item.relativePath} no longer exists; re-run to inject the Dflow block.`);
             continue;
@@ -2915,12 +3864,14 @@ async function writeFilePlan(cwd, plan) {
           throw error;
         }
         if (!stats.isFile()) {
+          unexpectedSkip = true;
           result.skipped.push(item.relativePath);
           result.warnings.push(`Skipped Dflow block update because ${item.relativePath} is no longer a regular file; re-run to inject the Dflow block.`);
           continue;
         }
         const currentRaw = await fs.readFile(targetPath, 'utf8');
         if (currentRaw !== item.expectedContent) {
+          unexpectedSkip = true;
           result.skipped.push(item.relativePath);
           result.warnings.push(`Skipped Dflow block update because ${item.relativePath} changed after the preview; re-run to inject the Dflow block.`);
           continue;
@@ -2948,6 +3899,7 @@ async function writeFilePlan(cwd, plan) {
         // already-current Dflow block) is expected, not a problem — don't emit the
         // generic "skipped existing target" warning for it.
         if (!item.intentionalSkip) {
+          unexpectedSkip = true;
           result.warnings.push(`Skipped existing target: ${item.relativePath}`);
         }
         if (item.relativePath === 'dflow/specs/shared/_conventions.md') {
@@ -2989,6 +3941,10 @@ async function writeFilePlan(cwd, plan) {
         }
 
         if (targetExists) {
+          // A previewed create raced against a concurrent creation — the
+          // previewed change did not apply, so it blocks requiresFullApply
+          // items exactly like the pre-write guard skips above.
+          unexpectedSkip = true;
           result.skipped.push(item.relativePath);
           result.warnings.push(`Skipped existing target: ${item.relativePath}`);
           continue;
@@ -3205,8 +4161,21 @@ async function runDoctor(options = {}) {
     }
 
     const findings = [];
+    await checkConventionsParserUncertainty(cwd, findings);
     await checkConventionsDflowVersion(cwd, findings);
-    await checkOrphanedWorkflowBundleFiles(cwd, findings);
+    await checkConventionsVersionReconciled(cwd, findings);
+    await checkConventionsPolicyFormat(cwd, findings);
+    await checkGuideCanonicalState(cwd, findings);
+    await checkGuideProjectContextFormat(cwd, findings);
+    await checkGuideSectionRefs(cwd, findings);
+    await checkInitOnlyStarters(cwd, findings);
+    await checkFeatureIndexShape(cwd, findings);
+    await checkDocumentShapes(cwd, findings);
+    await checkSpecTableConventionComment(cwd, findings);
+    await checkRootAgentShims(cwd, findings);
+    await checkAdapterAndSkillState(cwd, findings);
+    await checkWorkflowBundleSourceAndOrphans(cwd, findings);
+    await checkBundleManifestVersion(cwd, findings);
 
     printDoctorReport(stdout, cwd, findings);
     return 0;
@@ -3220,11 +4189,300 @@ async function runDoctor(options = {}) {
   }
 }
 
-async function checkConventionsDflowVersion(cwd, findings) {
+// FOUR doctor checks read `dflow/specs/shared/_conventions.md`, and each used to
+// decide separately what an unusable file was. They agreed about ABSENT (all
+// early-returned) and disagreed about BLANK: the drift check in
+// `checkInitOnlyStarters` deliberately collapses a blank file to one finding —
+// its comment says three fingerprint findings about a file with no content is
+// noise — while these three carried on and emitted four more. So the
+// suppression was defeated by its own siblings and a blank file produced five
+// findings, which `p082-b3-g1` finding 1 caught.
+//
+// ⚠ THE COUPLING THIS CREATES IS THE THING TO WATCH. Returning null here means
+// these three checks say NOTHING about an absent or blank file, and that is only
+// safe because `checkInitOnlyStarters` always runs and always reports it. Both
+// facts are load-bearing: `runDoctor` calls it unconditionally, and its
+// `conventionsAbsent || !conventions.trim()` branch has no early return in front
+// of it. Break either and the worst state of the file becomes silent everywhere
+// — the exact failure this subsystem exists to prevent. `test/upgrade-drift.mjs`
+// pins the count for absent and blank so the coupling cannot rot quietly.
+async function readConventionsForCheck(cwd) {
   const conventionsPath = path.join(cwd, 'dflow', 'specs', 'shared', '_conventions.md');
-  if (!(await pathExists(conventionsPath))) return;
+  if (!(await pathExists(conventionsPath))) return null;
   const content = await fs.readFile(conventionsPath, 'utf8').catch(() => '');
-  if (!/^> Dflow Version:/m.test(content)) {
+  return content.trim() ? content : null;
+}
+
+// PROPOSAL-084. Two `affects` sets, split because the gaps fail through two
+// different mechanisms and merging them would overstate one of them.
+//
+// VISIBILITY gaps change which TEXT counts as live, so everything that reads the
+// file through `visibleTextLines` is affected.
+const CONVENTIONS_VISIBILITY_AFFECTS = [
+  'the `_conventions.md` convention-drift fingerprints',
+  'whether the `## Git Policy` / `## AI Commit Policy` / `## Prose Language` sections are present, and the policy values read from them',
+  // ⚠ ADDED after `p084-y1` finding 4 measured it: the starter checks are DOWNSTREAM
+  // of the policy value, not a sibling of it. `We use trunk here <!-- Selected Git
+  // policy: `gitflow` -->` makes `parseContextLine` return `gitflow`, which passes
+  // the value check, and `checkInitOnlyStarters` then reports on
+  // `Git-principles-gitflow.md` while saying nothing about the file the project
+  // actually uses. Naming the value but not what the value drives understates the
+  // blast radius, and this list is printed to users as measured fact.
+  'the `Git-principles-*.md` starter checks, which are driven off the Git policy value',
+  'dangling `§` references from `_conventions.md` into `AI-AGENT-GUIDE.md`'
+];
+// BOUNDARY gaps move where a SECTION ends. The policy VALUES are read line-wise
+// by `parseContextLine` and do not depend on section extent, so they are named as
+// unaffected rather than quietly folded in — an `affects` list is read as
+// measured, and padding it is the same false-precision this state exists to stop.
+const CONVENTIONS_BOUNDARY_AFFECTS = [
+  'the `_conventions.md` convention-drift fingerprints',
+  'whether the `## Git Policy` / `## AI Commit Policy` / `## Prose Language` sections are present (the policy VALUES are read line-wise and this shape does not affect them)'
+];
+
+// ⚠ SCOPE: the two files whose CONTENT doctor makes claims about —
+// `_conventions.md` and `AI-AGENT-GUIDE.md` — and the boundary is measured rather
+// than cautious. Running these over the packaged tree finds the inline-comment
+// shape in both tracks' `phase-spec.md` templates, where `## Problem Description
+// <!-- Fill timing: ... -->` is a deliberate authoring convention, so widening the
+// scan to every spec file would make every project report uncertain forever —
+// which is how a disclosure becomes noise the user learns to skip. The two scanned
+// files are clean in every PACKAGED copy, so a fresh init is silent
+// (invariant 4).
+//
+// ⚠ The guide was EXCLUDED in the first draft, on the stated ground that its
+// false-positive cost "has not been measured". `p084-y1` finding 8 measured it —
+// 0 hits across all seven guides in this tree, for all four detectors — and
+// demonstrated the silent pass the exclusion was leaving open: a commented-out
+// value in the `## Project Context` table makes `parseContextLine` return the
+// comment text itself as the live value, `configure-agents` writes that into
+// generated prose, and a reader sees an empty cell. Once the reason for a boundary
+// is falsified the boundary goes, rather than the reason being rewritten to fit.
+const GUIDE_UNCERTAINTY_AFFECTS = [
+  'the `## Project Context` values (`Tech stack`, `Migration / legacy context`) that `dflow configure-agents` reads back when it regenerates guide prose',
+  'whether the `## Project Context` section is found at all, and the drift report about its rows',
+  // ⚠ ADDED after `p084-xv1` measured the omission. The dangling-`§` check resolves
+  // workflow-bundle references against THIS file's headings, via
+  // `extractHeadings` -> the same classification a shape can disturb. Listing only
+  // the Project Context concerns told the user the rest of the guide's checks were
+  // still trustworthy, which is the precise false reassurance an `affects` list
+  // exists to prevent.
+  'whether `AI-AGENT-GUIDE.md § ...` references from the workflow bundle resolve, since that check reads this file\'s headings'
+];
+// ⚠⚠ THE `<textarea>` MITIGATION, SPELLED ONCE AND PREFIXED TO BOTH COMMENT IDS.
+// A `<textarea>` comment is reported deliberately (see the block comment above
+// `THERE IS NO TEXTAREA EXEMPTION HERE` in `doctor-checks` — grep that phrase — for
+// why the exemption was removed rather than patched a fourth time), so the *only* thing standing between the user and an edit
+// that hides their visible text is this sentence.
+// ⚠ It has to be on BOTH ids, and putting it on one was a real defect
+// (`p084-xv11` finding 1): `<textarea><!-- rule --></textarea>` on ONE line does not
+// start its line's content, so the partition correctly calls it `inline-html-comment`
+// — and that id's action says "move the comment to a line of its own at column 0",
+// which is exactly the edit that turns displayed raw text into a hidden comment.
+// The multi-line form routes to `comment-inside-container` and was safe. One shape,
+// two ids, one of them unprotected.
+// ⚠ Spelled once and shared, not copied into both strings: two copies of a rule is
+// this codebase's oldest defect class, and this rule has already been rewritten
+// three times. The first-hit warning matters because each detector emits at most one
+// finding per file: a harmless textarea hit can shadow a later, genuinely hidden hit.
+const TEXTAREA_LEAVE_IT_ALONE = '⚠ FIRST, if the cited comment sits inside a `<textarea>`: leave that line alone. A `<textarea>` holds raw text, so moving it out would hide text the reader can already see. But do NOT ignore the overall uncertainty result or treat the affected checks as trusted: Dflow reports only the first occurrence of each shape in a file, so this harmless line can precede and shadow a genuinely hidden comment with the same id. Inspect the rest of the cited file for other apparent comment openers before treating those checks as reliable. For a non-`<textarea>` occurrence: ';
+// ⚠ This scope is part of the repair contract. The markerless continuation case
+// deliberately follows the renderer Dflow ships; CommonMark-family renderers can
+// expose the apparent opener instead, so universal "the reader sees nothing" prose
+// would send some users to edit content their actual publishing path displays.
+const MARKED_COMMENT_CALIBRATION = '⚠ A markerless continuation of list-owned raw HTML is calibrated to the renderer Dflow ships (`dflow render`, powered by Marked). Another Markdown renderer may expose an escaped apparent opener there; if you publish through a different renderer, inspect its rendered output before applying this repair. ';
+const CONVENTIONS_UNCERTAINTY_DETECTORS = [
+  {
+    id: 'inline-html-comment',
+    title: 'an HTML comment begins part-way through a line',
+    locate: (content) => doctorChecks.inlineHtmlCommentLine(content),
+    detail: 'Dflow classifies Markdown one line at a time, so a comment that opens mid-line is not a block to it and its contents are counted as live document text — while `dflow render` normally shows no comment text there. A rule, policy value or heading word sitting inside such a comment therefore reads as still present after it has been switched off.',
+    // ⚠⚠ THIS ACTION USED TO SEND THE USER INTO AN UNDISCLOSED SILENT PASS
+    // (`p084-y1` finding 1). It said "move the comment onto a line of its own",
+    // full stop — and the natural way to do that inside a list item is to indent
+    // it under the item, where NOTHING fires and the text is still read. The
+    // column matters, so the column is now what the sentence says.
+    action: TEXTAREA_LEAVE_IT_ALONE + MARKED_COMMENT_CALIBRATION + 'move the comment to a line of its own that starts at column 0, outside any CONTAINER — a list item, a block quote, or an HTML block such as `<details>`. There it opens a real HTML block of its own and its contents stop being read. Deleting it works too. ⚠ Indenting it under a list item is NOT enough: it stays inside the item, where Dflow still reads it. ⚠ And if the comment is inside an HTML block, column 0 alone is NOT enough either — you are still inside the block, and `comment-inside-container` will report it on the next run. The explainer page section for that id has the per-tag rule for leaving an HTML block.',
+    affects: CONVENTIONS_VISIBILITY_AFFECTS
+  },
+  {
+    id: 'comment-inside-container',
+    title: 'an HTML comment sits inside a container whose interior Dflow does not parse, where its text is still read',
+    // ⚠ REPLACES `unclosed-html-in-container`, which asked the wrong question.
+    // That one fired on an UNTERMINATED comment the document-level scan had
+    // missed; measured, any later `-->` in the file silenced it — including the
+    // one `unclosed-html-block`'s own action tells the user to add — while the
+    // hidden rule stayed hidden. Termination was never the issue: a properly
+    // closed comment inside a list item hides its text from a reader just as
+    // completely, and Dflow reads it either way.
+    locate: (content) => doctorChecks.containerHtmlCommentLine(content),
+    detail: 'Dflow does not parse the interior of a container as its own sequence of blocks — a list item and a block quote are the common cases, and an HTML block such as `<details>` behaves the same way. A comment opened inside one therefore never opens an HTML block as far as Dflow is concerned: `dflow render` normally shows no comment text there, while Dflow goes on counting the comment\'s contents as live document text. This holds whether or not the comment is closed, and whatever the container turns out to be.',
+    // ⚠⚠ THE HTML-BLOCK HALF NAMES THE TAG, and a blanket rule here was wrong for
+    // two of them (`p084-xv3`). "A blank line ends the block, a closing tag does
+    // not" is CommonMark's TYPE-6 rule. `<pre>` and `<textarea>` are type 1: they
+    // end at their own closing tag, and they reach this id — measured, a comment
+    // inside `<pre>` reports, adding the blank line the old sentence prescribed
+    // does NOT clear it, and moving below `</pre>` (which the old sentence said
+    // would not work) does. So the shipped repair was exactly backwards for them.
+    // `<script>` and `<style>` are type 1 too but never reach here — their
+    // interiors are already invisible, so nothing is hidden from a reader that was
+    // not hidden anyway — which is why they are not named.
+    // ⚠⚠ `<textarea>` WAS named here as a repair case for one round and that was
+    // wrong twice over (`p084-xv4` finding 1): it holds raw text, so the comment is
+    // displayed and there is nothing to disclose, and the advice given for it —
+    // move below the closing tag — is the one edit that would genuinely hide it.
+    // ⚠⚠⚠ EVERY `<textarea>` COMMENT IS NOW REPORTED, and the leading clause in the
+    // action is the whole mitigation. Three rounds were spent suppressing that false
+    // positive and each attempt produced a SILENT PASS instead (`p084-xv5`, `xv9`,
+    // `xv10`); the exemption was removed rather than patched a fourth time. The full
+    // account is under `THERE IS NO TEXTAREA EXEMPTION HERE` in `doctor-checks`.
+    // Reporting is the NOISY direction, which the maintainer twice chose in this same
+    // area (2026-08-09). **Do not "tidy" the `<textarea>` clause away** — without it
+    // the finding sends a user to make the one edit that genuinely hides their text.
+    // ⚠ The outermost-container sentence is not decoration either: with a `<pre>`
+    // inside a list item, applying only the `<pre>` rule leaves the comment in the
+    // list item and the finding fires again on the next run.
+    // ⚠ Concatenation, not a template literal: this string carries backticked code
+    // spans (`<pre>`, `>`), which end a template literal on the spot.
+    action: TEXTAREA_LEAVE_IT_ALONE + MARKED_COMMENT_CALIBRATION + 'move the comment out of the enclosing container — or delete it. Leaving the container is the whole repair. ⚠ When the comment sits inside MORE THAN ONE container — a `<pre>` inside a list item, a `<details>` inside a block quote — the OUTERMOST one is the one you have to leave: repair only the inner one and the finding comes back unchanged. For a list item or block quote, put the comment on a line of its own at column 0 with no list marker or `>` before it. For an HTML block the rule depends on the tag — `<pre>` ends at its own `</pre>`, so move the comment below that; every other block (`<details>`, `<div>`, …) ends at a BLANK LINE and not at a closing tag, so put a blank line between the block and the comment, or move the comment above the block entirely. Re-indenting the COMMENT inside the container never helps. (One thing that does help, and only for the fenced-example case the explainer page describes: un-indenting the FENCE itself to three spaces or fewer.)',
+    affects: CONVENTIONS_VISIBILITY_AFFECTS
+  },
+  {
+    id: 'html-block-type-7',
+    title: 'a bare custom tag stands at the start of a block, directly above a `---` or `===` line',
+    locate: (content) => doctorChecks.htmlBlockType7Line(content),
+    detail: 'A complete tag whose name is not one of CommonMark\'s known block tags, alone on a line, is HTML block type 7 — the only type that cannot interrupt a paragraph, and the only one that needs a real tag parser to recognise. Dflow does not implement it, so where this shape meets a following underline it ends the section earlier than a renderer does. This one is usually loud — it reports drift that is not there — but it is NOT only loud: ending the section early also drops the tail of it, so a retired row below the shape stops being seen and its finding disappears. Treat results about that section as unknown in both directions.',
+    action: 'Put a blank line between the tag and the underline, or fence the tag as an example if it is being shown rather than used.',
+    affects: CONVENTIONS_BOUNDARY_AFFECTS
+  }
+];
+
+// ⚠⚠ `table-delimiter-cell-count` USED TO BE THE FIFTH ENTRY HERE, AND ITS REMOVAL
+// IS A DECISION, NOT AN OVERSIGHT (user, 2026-08-12). It reported a table whose
+// delimiter row carried a different number of cells from its header, on the
+// grounds that Dflow and the renderer can then disagree about where the section
+// ends. That harm is real and is still real — it is recorded, with owner and
+// gate, as `doctor-section-boundary-arbiter` in `planning/opt-in-backlog.md`.
+// What could not be made to work was the DETECTOR. Six consecutive review rounds
+// each found a document it stayed silent on, and silence here is the direction
+// that prints `All checks passed` over a drifted file:
+//   `x7` bare pair, `y3` multi-line dash, `y4` equals family, `x13`/`y5`
+//   underline-shaped first prose line, `x14`/`y6` indented first prose line,
+//   `y7` single-hyphen delimiter row.
+// Narrowing it to measured shapes failed five times; widening it back to every
+// mismatch failed on the sixth, because the remaining enumeration had moved into
+// the delimiter-row recogniser. And `y6` measured the same silent false clean
+// with a delimiter row whose cell count was CORRECT — so this detector's scope
+// was a strict subset of the harm and no version of it could close it.
+// ⚠ The durable fix is a different instrument, not a better shape list: `marked`
+// is already a runtime dependency, so the section boundary can be taken FROM the
+// renderer instead of guessed alongside it. That is a design change with its own
+// review, which is why this ships as a stated gap instead of a sixth repair.
+// Both explainer pages name it under "shapes that are known and deliberately not
+// reported", beside the table-indent gap it now sits next to.
+
+
+// The document-level unclosed block is a condition on the whole file rather than
+// one of the narrower shape detectors. It still runs through the same two-file
+// target loop: both `_conventions.md` and `AI-AGENT-GUIDE.md` feed the classifier.
+const UNCLOSED_HTML_BLOCK_ID = 'unclosed-html-block';
+
+function unclosedHtmlBlockUncertainty(rel, line, affects) {
+  return uncertainFinding({
+    id: UNCLOSED_HTML_BLOCK_ID,
+    title: `${rel} has an unclosed HTML block at line ${line}`,
+    // BOTH DIRECTIONS: text below the opener can produce artefact findings, and
+    // genuine drift can disappear because the checks no longer see that text.
+    detail: `Everything from that line to the end of the file is inside that block, so it is not ordinary document content and Dflow cannot assess results below it. This cuts both ways: a finding below this one may be caused by the unclosed block rather than by real drift, AND a rule that genuinely has drifted below it can go unreported entirely, because the block hides the text the check would have read. Treat every result about content below this line as unknown — not as passing.`,
+    affects,
+    action: 'Close the block (for an HTML comment, add `-->`), then re-run `dflow doctor`.'
+  });
+}
+
+// ⚠ Every id doctor can print, in one place, because each one is a PROMISE that
+// `docs/doctor-uncertainty.md` / `.en.md` carries a section explaining that
+// shape. A shipped message pointing at a page section that does not exist is
+// precisely the failure this proposal was created to retire — the durable fix was
+// moving the per-container explanation onto a page that can be revised, and that
+// only works while the id and the section agree. `test/upgrade-drift.mjs` asserts
+// the correspondence in both directions against both languages.
+// PROPOSAL-092 D4: a spec doc whose `<!-- dflow-shape: … -->` line cannot be read.
+// Emitted by `checkDocumentShapes`, not by the two-file loop below.
+const SHAPE_MARKER_UNREADABLE_ID = 'unreadable-shape-marker';
+
+const DOCTOR_UNCERTAINTY_IDS = [
+  UNCLOSED_HTML_BLOCK_ID,
+  ...CONVENTIONS_UNCERTAINTY_DETECTORS.map((d) => d.id),
+  SHAPE_MARKER_UNREADABLE_ID
+];
+
+// PROPOSAL-084: report the shapes this module is known to read unreliably, so a
+// project containing one never receives the same `All checks passed` a genuinely
+// clean project gets. Reads the same guarded content the sibling checks read, so
+// an absent or blank file stays the drift check's single finding rather than
+// picking up four more (the coupling described above `readConventionsForCheck`).
+async function checkConventionsParserUncertainty(cwd, findings) {
+  // ⚠⚠ PUSH ORDER HERE DOES NOT DECIDE PRINT ORDER, and two review rounds reached
+  // OPPOSITE conclusions about that, so the measurement is recorded rather than
+  // the argument. `unclosed-html-block` moved into this loop, and the comment that
+  // moved with it claimed the finding had to be emitted BEFORE the drift findings
+  // "because it changes what they mean". `p084gate-y5` read the relocation as
+  // having reversed a deliberate contract and filed it as a must-fix regression;
+  // `p084gate-y4` had already called the same deletion a correction.
+  // Measured 2026-08-12 on a project carrying BOTH a retired rule row and an
+  // unclosed block, run through the real CLI on this tree and on the tree before
+  // this batch: **identical output order in both** — `[warn]` first, `[uncertain]`
+  // fourth lines later. `runDoctor` groups by category and prints assessed before
+  // uncertain regardless of the order anything is pushed here, and did so before
+  // this batch too. So the contract the old comment stated was never honoured by
+  // the printer, the relocation changed nothing about it, and there is no
+  // regression to repair. If you want that ordering, it has to be implemented in
+  // the printer — a comment here cannot buy it.
+  //
+  // ⚠ Same detectors, two files, DIFFERENT `affects` — the shape is a property of
+  // the Markdown, but which checks it blinds is a property of the file. Sharing
+  // one list across both would put a claim about `_conventions.md`'s drift
+  // fingerprints into a finding about the guide.
+  const targets = [
+    {
+      rel: 'dflow/specs/shared/_conventions.md',
+      content: await readConventionsForCheck(cwd),
+      affects: null // per-detector; the conventions lists distinguish visibility from boundary
+    },
+    {
+      rel: AI_AGENT_GUIDE_DEST,
+      content: (await fs.readFile(path.join(cwd, AI_AGENT_GUIDE_DEST), 'utf8').catch(() => '')) || null,
+      affects: GUIDE_UNCERTAINTY_AFFECTS
+    }
+  ];
+  for (const target of targets) {
+    if (target.content === null || !target.content.trim()) continue;
+    const unclosedAt = doctorChecks.unclosedHtmlBlockLine(target.content);
+    if (unclosedAt !== -1) {
+      findings.push(unclosedHtmlBlockUncertainty(
+        target.rel,
+        unclosedAt,
+        target.affects || CONVENTIONS_VISIBILITY_AFFECTS
+      ));
+    }
+    for (const detector of CONVENTIONS_UNCERTAINTY_DETECTORS) {
+      const line = detector.locate(target.content);
+      if (line === -1) continue;
+      findings.push(uncertainFinding({
+        id: detector.id,
+        title: `${target.rel}, line ${line}: ${detector.title}`,
+        detail: detector.detail,
+        affects: target.affects || detector.affects,
+        action: detector.action
+      }));
+    }
+  }
+}
+
+async function checkConventionsDflowVersion(cwd, findings) {
+  const content = await readConventionsForCheck(cwd);
+  if (content === null) return;
+  if (!/^> Dflow Version:/m.test(content)) {
     findings.push({
       level: 'info',
       title: 'dflow/specs/shared/_conventions.md missing Dflow Version line',
@@ -3234,6 +4492,1922 @@ async function checkConventionsDflowVersion(cwd, findings) {
   }
 }
 
+// PROPOSAL-058 (user decision 2026-06-08, OQ2): `> Dflow Version:` records the
+// Dflow version this project last reconciled with (`dflow configure-agents`
+// advances it). Behind the CLI means the Dflow-managed layers may be stale and
+// the user-owned layers unreviewed since the upgrade.
+async function checkConventionsVersionReconciled(cwd, findings) {
+  const content = await readConventionsForCheck(cwd);
+  if (content === null) return;
+  const match = content.match(/^> Dflow Version:[ \t]*(.*)$/m);
+  if (!match) return; // absence is checkConventionsDflowVersion's finding
+  const recorded = match[1].trim();
+  // Prerelease suffixes are valid package versions (the smoke test's own
+  // Dflow-Version assertion allows them), so they must not read as "not a
+  // version" noise on a fresh init of a prerelease build.
+  if (!/^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/.test(recorded)) {
+    findings.push({
+      level: 'info',
+      title: `_conventions.md Dflow Version line is not a plain x.y.z version: \`${recorded}\``,
+      detail: 'The line records which Dflow version the project last reconciled with; doctor cannot compare this value against the CLI.',
+      action: `Set it to the Dflow version the project is actually aligned to; \`dflow configure-agents\` keeps it current from then on (CLI is ${pkg.version}).`
+    });
+    return;
+  }
+  if (recorded === pkg.version) return;
+  if (compareVersions(recorded, pkg.version) < 0) {
+    findings.push({
+      level: 'info',
+      title: `Project last reconciled with Dflow ${recorded}; this CLI is ${pkg.version}`,
+      detail: 'Dflow-managed layers (workflow bundle, guide canonical content, adapters) may be stale, and user-owned layers may need review against the newer version.',
+      action: 'Run `dflow configure-agents` to re-project the Dflow-managed layers and update the line, then review the upgrade guide for user-owned surfaces: https://github.com/weilung/dflow-sdd-ddd/blob/main/docs/upgrading.en.md (offline copy: docs/upgrading.en.md in the installed package).'
+    });
+  } else {
+    findings.push({
+      level: 'info',
+      title: `Project was reconciled with Dflow ${recorded}, newer than this CLI (${pkg.version})`,
+      detail: 'Running an older CLI against a newer project layout can re-project older content over newer files.',
+      action: 'Upgrade the dflow package before re-running `dflow init` / `dflow configure-agents` here.'
+    });
+  }
+}
+
+// PROPOSAL-058 direction 2 (b): the policy sections are machine-read — context
+// inference for configure-agents parses the exact line formats in
+// lib/doctor-checks.js. A section that drifted from the canonical format makes
+// inference return null, and code paths that need a policy default a null to
+// `trunk` / `none`, so drift here risks a silent policy flip on any future
+// re-projection that writes these sections.
+async function checkConventionsPolicyFormat(cwd, findings) {
+  const content = await readConventionsForCheck(cwd);
+  if (content === null) return;
+
+  const sections = [
+    {
+      heading: '## Git Policy',
+      key: 'Git Policy',
+      re: doctorChecks.GIT_POLICY_LINE_RE,
+      values: doctorChecks.GIT_POLICY_VALUES,
+      example: 'Selected Git policy: `gitflow`',
+      // ⚠ "defaults to `trunk` wherever a policy value is required" was too
+      // broad, and the gate-1 disclosure put the overstatement next to its own
+      // contradiction in the same report. Verified by running both commands:
+      // `init` does fall back to trunk (`buildFilePlan`), but `configure-agents`
+      // does NOT — `addGitPrinciplesItem` reports the missing section and
+      // returns without touching any Git principles file. Say which is which.
+      nullEffect: 'a null Git policy falls back to `trunk` where init needs a value, while `dflow configure-agents` instead declines to refresh `Git-principles-*.md` at all'
+    },
+    {
+      heading: '## AI Commit Policy',
+      key: 'AI Commit Policy',
+      re: doctorChecks.AI_COMMIT_MARKER_LINE_RE,
+      values: doctorChecks.AI_COMMIT_MARKER_VALUES,
+      example: 'AI commit marker: `none`',
+      nullEffect: 'an unrecognized marker value falls back to `none`'
+    },
+    {
+      heading: '## Prose Language',
+      key: 'Prose Language',
+      re: doctorChecks.PROSE_LANGUAGE_LINE_RE,
+      values: null,
+      example: 'Project prose language: `en`',
+      nullEffect: 'prose-generating flows lose the project language setting'
+    }
+  ];
+
+  // Locate the section through the SAME recognizer the drift check uses, not a
+  // bespoke `^## X$`. That regex demanded an unindented heading of exactly
+  // level 2, while `doctor-checks.headingAt` follows CommonMark and accepts a
+  // 1-3 space indent — so `   ## Git Policy` was reported missing by this check
+  // and found by the other, on a file whose policy line `parseContextLine` read
+  // perfectly well (`p082-b3-g1` finding 2).
+  //
+  // ⚠ This deliberately WIDENS what counts as present, including to other
+  // heading levels, and that is not a loosening of the contract being enforced:
+  // inference (`parseContextLine`) is a whole-file match that never looks at the
+  // heading at all. The heading test is only a locator for "is this section
+  // here", so demanding a level and an indent was stricter than the thing it
+  // protects — it produced false "missing" reports, not extra safety.
+  for (const section of sections) {
+    if (doctorChecks.conventionsSectionBodies(content, section.key).length === 0) {
+      findings.push({
+        level: 'warn',
+        title: `_conventions.md is missing the ${section.heading} section`,
+        detail: 'Newer Dflow init projects always carry it; existing projects are not auto-migrated (user-owned file).',
+        action: `Copy the section from a fresh \`dflow init\` project and set your value (canonical line: \`${section.example}\`).`
+      });
+      continue;
+    }
+    const value = doctorChecks.parseContextLine(content, section.re);
+    if (value === null || (section.values && !section.values.has(value))) {
+      findings.push({
+        level: 'warn',
+        title: `_conventions.md ${section.heading} line is not machine-readable`,
+        detail: `Dflow parses a \`${section.example}\`-style line to infer project context; as written, inference returns null and ${section.nullEffect}.`,
+        action: `Restore the canonical line format, e.g. \`${section.example}\`.`
+      });
+    }
+  }
+}
+
+// PROPOSAL-058 direction 2 (a): guide manageability + canonical staleness. The
+// canonical region is substitution-free by design (a test guards that), so a
+// current projection equals the packaged region byte-for-byte after LF
+// normalization.
+async function checkGuideCanonicalState(cwd, findings) {
+  const guidePath = path.join(cwd, AI_AGENT_GUIDE_DEST);
+  if (!(await pathExists(guidePath))) {
+    if (await pathExists(path.join(cwd, WORKFLOW_BUNDLE_DEST))) {
+      findings.push({
+        level: 'warn',
+        title: `${AI_AGENT_GUIDE_DEST} is missing but the workflow bundle is projected`,
+        detail: 'Bundle flow files § reference the guide; without it agents lose routing, ceremony, and transparency rules.',
+        action: 'Run `dflow configure-agents` to project the guide.'
+      });
+    }
+    return;
+  }
+  // ⚠⚠ PRESENT-BUT-UNREADABLE IS NOT EMPTY, AND THE OLD `.catch(() => '')` MADE
+  // IT SO. An empty string classifies as `absent` markers and then fails the
+  // recognizable-guide test, so a guide that is perfectly current — but locked
+  // by permissions, or replaced by a directory — was reported as "not
+  // recognizable as a Dflow guide", a verdict on bytes this function never read,
+  // with an action telling the reader to REBUILD an intact file. The canonical
+  // comparison also vanished in the same breath, unannounced.
+  // ⚠ The remedy is already written twice in this file — `checkInitOnlyStarters`
+  // splits `unreadable` out for this exact reason, and so does
+  // `checkAdapterAndSkillState`. This was the third site, left as it was.
+  let rawGuide = null;
+  let guideReadError = null;
+  try {
+    rawGuide = await fs.readFile(guidePath, 'utf8');
+  } catch (error) {
+    guideReadError = error;
+  }
+  if (rawGuide === null) {
+    findings.push({
+      level: 'warn',
+      title: `${AI_AGENT_GUIDE_DEST} could not be read`,
+      detail: `It exists but this check could not read it (${guideReadError && (guideReadError.code || guideReadError.message)}), so nothing can be said about its markers or whether its canonical region is current.`,
+      action: 'Check the path\'s permissions and that it is a file rather than a directory, then re-run `dflow doctor`.'
+    });
+    return;
+  }
+  const content = toLf(rawGuide);
+  const region = classifyMarkedRegion(content, GUIDE_CANONICAL_SECTION_START, GUIDE_CANONICAL_SECTION_END);
+  if (region.state === 'malformed') {
+    findings.push({
+      level: 'warn',
+      title: `${AI_AGENT_GUIDE_DEST} has malformed guide-canonical markers`,
+      detail: '`dflow configure-agents` cannot locate the canonical region and will not refresh it.',
+      action: 'Repair or remove the stray `<!-- dflow-generated: guide-canonical ... -->` markers, then re-run `dflow configure-agents`.'
+    });
+    return;
+  }
+  if (region.state === 'absent') {
+    // Mirror the configure-agents bootstrap split: the adoption offer only
+    // exists for a recognizable Dflow guide, so pointing an unrecognizable file
+    // at the offer would be impossible advice.
+    if (isRecognizableDflowGuide(content)) {
+      findings.push({
+        level: 'info',
+        title: `${AI_AGENT_GUIDE_DEST} predates managed guide-canonical markers`,
+        detail: 'Its canonical sections stay at the Dflow version that wrote them; upgrades cannot refresh them in place.',
+        action: 'Re-run `dflow configure-agents` on an interactive terminal and accept the marker-adoption offer (your "## Project Context" is kept), or reconcile manually against a fresh `dflow init`.'
+      });
+    } else {
+      findings.push({
+        level: 'info',
+        title: `${AI_AGENT_GUIDE_DEST} is not recognizable as a Dflow guide`,
+        detail: 'It has no guide-canonical markers and lacks the Dflow guide shape (`# Dflow AI Agent Guide` title plus `## Project Context`), so `configure-agents` will not offer marker adoption and workflow-bundle § references may dangle.',
+        action: 'If it should be Dflow-managed, rebuild it from a fresh `dflow init` comparison (carry your project notes over), or keep maintaining it yourself.'
+      });
+    }
+    return;
+  }
+  // ⚠⚠ PROPOSAL-091 gates 4, 5 and 6 — this function carried all three of the
+  // shapes `checkInitOnlyStarters`'s comment had already named and removed next
+  // door, untouched.
+  //
+  // GATE 4 (`if (!edition) return`) — route (B). The project's own canonical
+  // region is bytes this function already holds; an unknown edition says nothing
+  // about whether those bytes are stale. The edition set is closed, so compare
+  // against every track and report only when the region matches none.
+  // GATE 5 (`catch { return }`) and GATE 6 (packaged region absent) — route (A),
+  // and both must report. A packaged guide that cannot be read, or that carries
+  // no canonical markers, is a damaged INSTALL. Reported with the same title as
+  // the sibling package findings so one broken package reads as one problem.
+  const edition = await inferProjectBundleEdition(cwd);
+  const candidateEditions = edition ? [edition] : [...BUNDLE_EDITIONS];
+  const usable = [];
+  const damaged = [];
+  for (const candidate of candidateEditions) {
+    let packaged = null;
+    let readError = null;
+    try {
+      // ⚠ `toLf` BEFORE CLASSIFYING, exactly as `checkInitOnlyStarters` does one
+      // function away. Without it a CRLF checkout of the package (npm link with
+      // `core.autocrlf=true`) had its markers masked away by the code-block
+      // masker, and doctor reported an intact package as "carries no well-formed
+      // guide-canonical markers" — a false statement about the packaged file.
+      // It also keeps the byte comparison below honest: the project side is
+      // normalized, so the packaged side has to be too, or every CRLF install
+      // reports drift that is only a line ending.
+      packaged = toLf(await readPackagedTemplate(candidate, 'scaffolding/AI-AGENT-GUIDE.md'));
+    } catch (error) {
+      readError = error;
+    }
+    const packagedRegion = packaged === null
+      ? null
+      : classifyMarkedRegion(packaged, GUIDE_CANONICAL_SECTION_START, GUIDE_CANONICAL_SECTION_END);
+    if (packagedRegion && packagedRegion.state === 'present') {
+      usable.push({ edition: candidate, packaged, region: packagedRegion });
+    } else {
+      const cause = packaged === null
+        ? `could not be read (${readError && readError.message ? readError.message : readError})`
+        : 'carries no well-formed guide-canonical markers';
+      damaged.push(`\`templates/${candidate}/scaffolding/AI-AGENT-GUIDE.md\` ${cause}`);
+    }
+  }
+  if (damaged.length > 0) {
+    const scope = edition
+      ? ''
+      : ' This project does not say which track it uses, so every shipped track was checked.';
+    findings.push({
+      level: 'warn',
+      title: 'The installed dflow package looks incomplete',
+      detail: `Its packaged agent guide is unusable: ${damaged.join('; ')}.${scope} This report therefore cannot say whether ${AI_AGENT_GUIDE_DEST}'s canonical region is current.`,
+      action: 'Reinstall dflow (e.g. `npm install -g dflow-sdd-ddd@latest`, or re-link your local checkout). This is a problem with the installed package, not with anything in your project.'
+    });
+  }
+  // ⚠⚠ ANY damaged candidate stops the COMPARISON, not just all of them. This
+  // said `usable.length === 0` and that was a false-clean's mirror image — a
+  // false DIRTY. With the edition unknown and one packaged guide unreadable, the
+  // remaining track was compared alone and a pristine project guide matching the
+  // UNREADABLE track was reported as drifted. The finding this function has
+  // already pushed by now says, in its own words, that this report "cannot say
+  // whether the canonical region is current" — and the next line said it anyway.
+  //
+  // The premise of the drift claim is "it matches NONE of the shipped tracks".
+  // One unreadable candidate leaves that unestablished, so the honest output is
+  // the package finding alone. Same evidence bar `checkInitOnlyStarters` reaches
+  // by a different route: it compares only against `resolvedEdition`, because
+  // naming a specific packaged file in a drift claim requires knowing which one.
+  if (damaged.length > 0) return;
+  const projectCanonical = content.slice(region.startIdx, region.endIdx);
+  // ⚠ Matching ANY candidate clears it. With the track unknown the project could
+  // legitimately be either one, so "differs from greenfield" alone is not drift.
+  if (usable.some((candidate) => projectCanonical === candidate.packaged.slice(candidate.region.startIdx, candidate.region.endIdx))) return;
+  findings.push({
+    level: 'info',
+    title: `${AI_AGENT_GUIDE_DEST} canonical content differs from this CLI version`,
+    detail: usable.length === 1
+      ? 'The marker-guarded canonical region does not match what this Dflow version projects.'
+      : 'The marker-guarded canonical region does not match what this Dflow version projects. This project does not say which track it uses, so every shipped track was checked and the region matches none of them.',
+    action: 'Run `dflow configure-agents` to refresh the canonical region in place (content outside the markers is kept).'
+  });
+}
+
+// PROPOSAL-076: the guide's "## Project Context" rows are the machine-readable
+// source context inference reads (tech stack / migration context). Unlike the
+// _overview.md rows the pre-076 inference looked for — which never existed in
+// any packaged template, so their absence is canonical — these rows have
+// shipped in every projected guide, so a missing or unparseable row here IS
+// drift worth reporting. Info-level only: the inference fallback
+// ('unknown'/'none') is benign, and rewriting Project Context is the user's
+// designed freedom (PROPOSAL-058 boundary).
+async function checkGuideProjectContextFormat(cwd, findings) {
+  const guidePath = path.join(cwd, AI_AGENT_GUIDE_DEST);
+  if (!(await pathExists(guidePath))) return; // missing guide is checkGuideCanonicalState's finding
+  const content = toLf(await fs.readFile(guidePath, 'utf8').catch(() => ''));
+  // Judge marker-managed guides and recognizable pre-marker guides. Anything
+  // else already gets its own unrecognizable / malformed finding, where
+  // row-level advice would be impossible advice. Deliberately NOT only the
+  // adoption predicate: a marker-managed guide whose "## Project Context" was
+  // deleted has fine markers and fails recognizability, yet inference just
+  // lost its source — that is a finding, not a skip (gate G5).
+  const markers = classifyMarkedRegion(content, GUIDE_CANONICAL_SECTION_START, GUIDE_CANONICAL_SECTION_END);
+  if (markers.state !== 'present' && !isRecognizableDflowGuide(content)) return;
+  const section = projectContextParseSlice(content);
+  if (section === null) {
+    // ⚠ REPORT THE CAUSE WHEN THERE IS ONE (`p082-b3-k3` gap G). An unclosed
+    // `<!--` above the heading puts it inside an HTML block, so `classifyLines`
+    // does not see a heading and the section reads as absent — while it is
+    // sitting right there in the file. `_conventions.md` already names this
+    // cause and gives the line number; the guide gave the opaque message below
+    // instead, whose action ("restore the section") is impossible advice for a
+    // file that already has one, and whose "ignore this if you removed it on
+    // purpose" invites dismissing a real malformation. Same cause, same
+    // reporting.
+    // ⚠⚠ WHY THE PREDICATE IS THE SYMPTOM AND NOT `unclosedHtmlBlockLine`,
+    // measured on a real init'd guide before this was written. The obvious
+    // version — reuse the `_conventions.md` unclosed-block reporting, which is
+    // what the review recommended — almost never fires here: `## Project
+    // Context` sits ABOVE the guide-canonical markers, and those marker lines
+    // contain `-->`, so a `<!--` left open above the heading is CLOSED by the
+    // marker below it. The block is well-formed at EOF, `unclosedHtmlBlockLine`
+    // returns -1, and the heading is still inside that block, still invisible to
+    // `classifyLines`, still reported by the opaque message below. A cause check
+    // that cannot fire in the shipped file's own shape is worse than none: it
+    // reports nothing while looking like coverage.
+    // So ask the question that actually distinguishes the two states: is the
+    // heading IN the file while the parser cannot see it? Fenced examples are
+    // blanked first, so a heading inside a ```md block does not count as the
+    // section — this branch deliberately names no block for it.
+    // ⚠ It does NOT follow that such a file returned earlier. `debt212223-y3`
+    // finding 2 measured the opposite: the early return above is a CONJUNCTION,
+    // `markers.state !== 'present' && !isRecognizableDflowGuide(content)`, so any
+    // guide written by a current `dflow init` — markers present — runs through here
+    // however unrecognizable its body is, and lands on the generic finding below.
+    // The decision was right; the reason written under it was not, and in a module
+    // where these comments are the contract that is the expensive kind of wrong.
+    const scan = doctorChecks.blankFencedBlocks(content.replace(/^\uFEFF/, ''));
+    const classified = doctorChecks.classifyLines(scan);
+    // ⚠⚠ ASK `parseAtxHeading`, DO NOT WRITE A FIFTH ATX RULE (`debt212223-y1`
+    // finding 1). The first version tested `/^ {0,3}##[ \t]+Project Context[ \t]*#*[ \t]*$/`,
+    // which accepts `## Project Context###` — CommonMark strips a closing sequence
+    // only when a space precedes it, so `parseAtxHeading` reads that line's text as
+    // `Project Context###` and the file does NOT have the heading. The finding
+    // claimed it did, and the repair it suggested provably did not clear it.
+    // `projectContextSectionBounds`, two functions above, carries a ⚠ recording that
+    // it was moved OFF hand-rolled ATX rules for exactly this: it had become a
+    // fourth place deciding what a heading is, a patch behind its siblings. This
+    // was the fifth. There is now one rule and it lives in `doctor-checks`.
+    // ⚠ BOUNDARY, stated rather than left to be discovered: this recognises the
+    // **ATX** form only. A setext-underlined `Project Context` that is hidden by an
+    // HTML block falls through to the generic finding below, whose action covers the
+    // hidden case in words rather than by naming the block.
+    const rawHeadingAt = scan.findIndex((line) => {
+      const parsed = doctorChecks.parseAtxHeading(line);
+      return parsed !== null && parsed.level === 2 && parsed.text === 'Project Context';
+    });
+    if (rawHeadingAt !== -1 && classified[rawHeadingAt] && classified[rawHeadingAt].type === 'html') {
+      // ⚠⚠ THE OPENING LINE COMES FROM THE CLASSIFIER, NOT FROM A SCAN OF OUR OWN.
+      // Three consecutive review rounds each defeated a reverse-scan version of this
+      // (`debt212223-xv1` F2 → `xv2` F1 → `xv3` F1): walking back over contiguous
+      // `html` lines crossed into the block above; requiring a line-start `<!--`
+      // still named comment- or tag-shaped lines that sit INSIDE an open block
+      // (`prose <!-- y`, `<p>x</p>`), because "can this line open a block" is not a
+      // property of the line — it depends on cross-line state only `classifyLines`
+      // holds. Three rounds on one predicate is this repo's signal to change the
+      // shape rather than add a fourth patch, so `classifyLines` now carries
+      // `blockStart` and this reads it. The fallback is only for a classifier that
+      // did not supply it; it cannot be reached through `type === 'html'` today.
+      const openerAt = typeof classified[rawHeadingAt].blockStart === 'number'
+        ? classified[rawHeadingAt].blockStart
+        : rawHeadingAt;
+      const openerLine = scan[openerAt].trim();
+      const shownOpener = openerLine.length > 60 ? `${openerLine.slice(0, 60)}…` : openerLine;
+      // ⚠⚠ ONE DECISION POINT, AND IT IS THE LINE-START RULE — not `includes('<!--')`
+      // (`debt212223-xv4` finding 1). `<details><!-- note` opens a **type-6 tag**
+      // block that merely contains a comment marker; advising `-->` there is advice
+      // that does not work, and the reviewer confirmed by running it that the
+      // heading stays inside the `<details>` afterwards and doctor repeats the same
+      // finding. This is the SECOND site of this same rule in this change — the
+      // opener scan was corrected for it one round earlier and this branch was left
+      // behind, which is exactly the "fixed one member of the class" failure this
+      // repo keeps paying for. Whoever touches either site greps for both.
+      const openerIsComment = /^ {0,3}<!--/.test(scan[openerAt]);
+      // ⚠⚠ IT REPORTS THE SHAPE, NOT A DIAGNOSIS, and the level matches that
+      // (`debt212223-xv1` finding 1). The first version said "the section is
+      // present in the file … do not add a second one" at `warn` — which is a
+      // claim doctor cannot support: the same shape is produced by a comment left
+      // open by accident (a live section is being swallowed) AND by a section the
+      // adopter commented out on purpose (there is nothing to repair, and telling
+      // them not to re-add it is telling them not to undo their own edit). It also
+      // said "an HTML comment opens with `<!--` and runs until `-->`" on a block
+      // that may be a `<details>`, sending `-->` advice about a tag that has none.
+      // So: name the block that is actually there, quote its opening line, and let
+      // the reader say which situation it is.
+      findings.push({
+        level: 'info',
+        title: `${AI_AGENT_GUIDE_DEST} has a "## Project Context" heading at line ${rawHeadingAt + 1} that is inside an HTML block, so Dflow reads no Project Context section`,
+        detail: `The block opens at line ${openerAt + 1} (\`${shownOpener}\`) and the heading sits inside it, so the heading is block content rather than a heading — \`dflow configure-agents\` falls back to \`unknown\` / \`none\` for tech stack and migration context. Two different situations produce exactly this shape and doctor cannot tell them apart: a block left open by accident is swallowing a live section, or the section was commented out deliberately.`,
+        // ⚠⚠ THREE BRANCHES, BECAUSE "CLOSE IT" IS NOT ONE INSTRUCTION
+        // (`debt212223-y4` finding 1). The previous version had two and told every
+        // non-comment opener to "close it" — which is right for `<script>` / `<?` /
+        // `<![CDATA[` and **provably useless for `<details>` and `<div>`**: a type-6
+        // block ends at a BLANK LINE, so writing `</details>` above the heading
+        // leaves the finding exactly as it was, with nothing telling the adopter
+        // their repair was wrong. Measured both ways. And type 6 is precisely the
+        // class this branch exists to serve, so it was the same "fixed one member of
+        // the class" failure that `debt212223-xv4` had just closed one branch over.
+        // ⚠ The deciding fact comes from `classifyLines` (`blockEndsOnBlank`), not
+        // from re-inspecting the opener text here — that re-derivation is what cost
+        // three earlier rounds.
+        action: openerIsComment
+          ? `If the comment at line ${openerAt + 1} was left open mid-edit, close it with \`-->\` above the heading and re-run \`dflow doctor\`. If the section is commented out on purpose, nothing is broken — inference will keep falling back.`
+          : classified[rawHeadingAt].blockEndsOnBlank === true
+            ? `A \`<details>\` / \`<div>\`-style block ends at a BLANK LINE, not at a closing tag — writing \`</...>\` above the heading will not free it. If the block at line ${openerAt + 1} is not meant to contain the heading, put a blank line between them, or move the section above the block; then re-run \`dflow doctor\`. If the heading belongs inside it, nothing is broken — inference will keep falling back.`
+            : `Close the block opened at line ${openerAt + 1} with its own end marker (\`</script>\`, \`</style>\`, \`?>\`, \`]]>\`, \`>\`) above the heading, or move the section above the block; then re-run \`dflow doctor\`. If the heading belongs inside it, nothing is broken — inference will keep falling back.`
+      });
+      return;
+    }
+    findings.push({
+      level: 'info',
+      title: `${AI_AGENT_GUIDE_DEST} has no "## Project Context" section`,
+      // ⚠ THE ACTION MUST NOT BE IMPOSSIBLE ADVICE (`debt212223-y1` finding 2). The
+      // branch above names the HTML block for an ATX heading; a setext-underlined
+      // `Project Context` hidden the same way reaches HERE, and telling that adopter
+      // to "restore a section" they can see in their own file is the defect this
+      // whole item exists to remove. So this message carries the possibility in
+      // words: it costs a sentence and covers every heading syntax, including ones
+      // added later.
+      // ⚠ THE DETAIL STATES THE SHAPE; THE ACTION ENUMERATES (`debt212223-y4`
+      // finding 2). It used to lead with "an HTML block above it — most often an
+      // `<!--` left open" — a cause the branch above now takes for every ATX
+      // heading, so the only file that can reach this line with that cause is one
+      // with a setext-underlined heading. Naming it here pointed most readers at
+      // the one thing that is not their problem.
+      detail: '`dflow configure-agents` infers project context (tech stack, migration context) from that section\'s table rows; without it, inference falls back to `unknown` / `none`. Ignore this if you removed the section on purpose. ⚠ If the section IS in the file, then something is keeping that line from being read as a document-level heading — see the causes below.',
+      // ⚠ NON-EXHAUSTIVE ON PURPOSE (`debt212223-xv7`). The first version said "two
+      // things hide it" and named an HTML block or the heading line itself — but any
+      // container the heading ends up inside does it too: an unclosed fence, a
+      // blockquote, a list item, an indented code line, all reproduced. A closed
+      // enumeration in adopter-facing advice is the same defect as a closed
+      // enumeration in a rule: the reader who is in the (N+1)th case concludes the
+      // advice does not apply to them. State the shape and give examples.
+      action: 'If the section is not in the file, restore a "## Project Context" section above the guide-canonical markers, including the `| Tech stack | ... |` and `| Migration / legacy context | ... |` rows. If it IS there, then something is stopping that line from being a document-level `##` heading. Common causes: a container around it (an HTML block, an unclosed ``` fence, a blockquote, a list item, or a 4-space indent), or the heading line itself — a closing `###` with no space before it, a level other than `##`, or an invisible character in the text are all part of the heading and make it a different one.'
+    });
+    return;
+  }
+  const rows = [
+    { label: 'Tech stack', re: doctorChecks.TECH_STACK_ROW_RE, example: '| Tech stack | ASP.NET Core 9, EF Core, xUnit |', fallback: '`unknown`' },
+    { label: 'Migration / legacy context', re: doctorChecks.MIGRATION_CONTEXT_ROW_RE, example: '| Migration / legacy context | none |', fallback: '`none`' }
+  ];
+  const missing = rows.filter((row) => doctorChecks.parseContextLine(section, row.re) === null);
+  if (missing.length === 0) return;
+  findings.push({
+    level: 'info',
+    title: `${AI_AGENT_GUIDE_DEST} "## Project Context" is missing machine-readable row(s): ${missing.map((row) => row.label).join(', ')}`,
+    detail: `\`dflow configure-agents\` infers project context from these table rows; as written, inference falls back to ${missing.map((row) => row.fallback).join(' / ')}. Ignore this if you rewrote the section on purpose.`,
+    action: `Restore the table row format inside "## Project Context", e.g. \`${missing[0].example}\`.`
+  });
+}
+
+// PROPOSAL-058 direction 2 (a): dangling `AI-AGENT-GUIDE.md § Heading`
+// references — the drift class that motivated this proposal: a frozen guide plus
+// a refreshed workflow bundle leaves flow files pointing at guide sections that
+// do not exist.
+async function checkGuideSectionRefs(cwd, findings) {
+  const guidePath = path.join(cwd, AI_AGENT_GUIDE_DEST);
+  if (!(await pathExists(guidePath))) return; // missing guide reported above
+  const guideHeadings = doctorChecks.extractHeadings(await fs.readFile(guidePath, 'utf8').catch(() => ''));
+  if (guideHeadings.length === 0) return;
+
+  const scanFiles = [{ rel: 'dflow/specs/shared/_conventions.md', abs: path.join(cwd, 'dflow', 'specs', 'shared', '_conventions.md') }];
+  for (const dir of ['references', 'templates']) {
+    const absoluteDir = path.join(cwd, WORKFLOW_BUNDLE_DEST, dir);
+    let entries = [];
+    try {
+      entries = await fs.readdir(absoluteDir);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.endsWith('.md')) {
+        scanFiles.push({ rel: `${WORKFLOW_BUNDLE_DEST}/${dir}/${entry}`, abs: path.join(absoluteDir, entry) });
+      }
+    }
+  }
+
+  const dangling = [];
+  for (const file of scanFiles) {
+    const content = await fs.readFile(file.abs, 'utf8').catch(() => null);
+    if (content === null) continue;
+    for (const ref of doctorChecks.extractSectionRefs(content, 'AI-AGENT-GUIDE.md')) {
+      if (!doctorChecks.headingResolves(ref.headingText, guideHeadings)) {
+        dangling.push(`${file.rel}:${ref.line} § "${ref.headingText}"`);
+      }
+    }
+  }
+  if (dangling.length === 0) return;
+  const shown = dangling.slice(0, 8);
+  const more = dangling.length - shown.length;
+  findings.push({
+    level: 'warn',
+    title: `Dangling AI-AGENT-GUIDE.md § reference(s): ${dangling.length}`,
+    detail: `${shown.join('; ')}${more > 0 ? `; +${more} more` : ''} — the guide has no matching heading, usually because it is frozen at an older Dflow version than the workflow bundle.`,
+    action: 'Refresh the guide canonical content with `dflow configure-agents` (accept marker adoption if offered), or align the guide manually.'
+  });
+}
+
+// PROPOSAL-058 direction 2 (d), user decision 2026-06-08 OQ5: init-only starters
+// are user-owned and never re-projected — doctor only reports, never rewrites.
+async function checkInitOnlyStarters(cwd, findings) {
+  const conventions = await fs.readFile(path.join(cwd, 'dflow', 'specs', 'shared', '_conventions.md'), 'utf8').catch(() => '');
+  const parsedPolicy = doctorChecks.parseContextLine(conventions, doctorChecks.GIT_POLICY_LINE_RE);
+  const recordedPolicy = parsedPolicy && doctorChecks.GIT_POLICY_VALUES.has(parsedPolicy) ? parsedPolicy : null;
+  const edition = await inferProjectBundleEdition(cwd);
+
+  // ⚠⚠ PROPOSAL-091 gate 1 — route (B), with (A) as the fallback. `if (policy)`
+  // with no else was the seventh boundary drawn around a package check in this
+  // file, and it was the widest: a project with no `## Git Policy` section lost
+  // the WHOLE Git-principles block — presence and drift both — while the only
+  // thing doctor said was a separate warn about the missing section that never
+  // mentioned what it had switched off. That is the same lesson as the comment
+  // below: the policy value decides WHICH starter to compare against, and that
+  // is a fact about the project's shape. Which `Git-principles-*.md` files the
+  // project actually HAS is visible on disk, so when the value is missing we
+  // check every one of them instead of checking none.
+  //
+  // ⚠ The absent value really does stop one thing, and only one: with no policy
+  // recorded doctor cannot say a needed file is MISSING, because it does not
+  // know which one was needed. The loop below only ever visits policies whose
+  // file is present, so that branch is unreachable on this path by construction
+  // rather than by wording.
+  const presentPolicies = [];
+  for (const candidate of doctorChecks.GIT_POLICY_VALUES) {
+    if (await pathExists(path.join(cwd, 'dflow', 'specs', 'shared', `Git-principles-${candidate}.md`))) {
+      presentPolicies.push(candidate);
+    }
+  }
+  const policiesToCheck = recordedPolicy ? [recordedPolicy] : presentPolicies;
+
+  for (const policy of policiesToCheck) {
+    const relativePath = `dflow/specs/shared/Git-principles-${policy}.md`;
+    const absolute = path.join(cwd, relativePath);
+    const projectFileExists = await pathExists(absolute);
+    // ⚠⚠ WITHOUT A RECORDED POLICY, `configure-agents` REFUSES TO TOUCH ANY OF
+    // THESE FILES — `addGitPrinciplesItem` reports it and returns before writing
+    // a byte. So every action below that sends the reader there has to say what
+    // to do first. Promising a refresh the sibling command will decline is the
+    // false-claim-about-another-command class this check has already corrected
+    // twice (`p090-b3-z1`), and route (B) would otherwise re-introduce it at the
+    // exact boundary this proposal exists to be honest about.
+    // ⚠ Name THIS file's policy, not a fixed example. The loop is here because
+    // `Git-principles-<policy>.md` is on disk, so the value to restore is known
+    // — and a hardcoded `gitflow` in a finding about a trunk project reads as an
+    // instruction, which would have the reader write the wrong policy into their
+    // conventions. The sibling strings nearby hedge with "e.g." or "or `trunk`"
+    // precisely because they cannot know; this one can.
+    const restorePolicyFirst = recordedPolicy
+      ? ''
+      : `Restore the \`## Git Policy\` section of \`dflow/specs/shared/_conventions.md\` first — this file is the \`${policy}\` starter, so the canonical line is \`Selected Git policy: \`${policy}\`\`. While the section is missing, \`dflow configure-agents\` declines to refresh any Git principles file. Then: `;
+
+    // ⚠⚠ WHICH TRACKS COULD `configure-agents` READ? THE EDITION SET IS CLOSED,
+    // SO WHEN THE PROJECT CANNOT TELL US, CHECK THEM ALL. This is the fifth
+    // boundary guessed around a package check in this file and the fourth one
+    // that shipped as a false clean; the previous four are recorded on
+    // `checkWorkflowBundleSourceAndOrphans`, which reached exactly this shape
+    // and wrote down why. Each earlier guess here was narrower than the last —
+    // "the project file exists" (`p090-b3-x1r`), then "an edition is inferable"
+    // (`p090-b3-x2r`) — and each was reported as the fix.
+    // `p090-b3-x2r` executed it: strip the manifest and every structural signal
+    // from a `trunk` project, break BOTH packaged trunk starters, and doctor
+    // printed `All checks passed` while `configure-agents`, having asked the
+    // user which track to use, died on
+    // `Internal error: packaged Git-principles-trunk.md has no well-formed
+    // git-principles-canonical markers.`
+    //
+    // ⚠ The two resolvers do not agree in general — this check prefers the
+    // manifest, `configure-agents` resolves by structure — so a single track is
+    // assumed ONLY when both name the same one (`projgate-sol1`). Otherwise
+    // every track the selected policy could resolve to is a candidate.
+    const structureEdition = await inferExistingEdition(cwd);
+    const resolvedEdition = edition && edition === structureEdition ? edition : null;
+    const candidateEditions = resolvedEdition ? [resolvedEdition] : [...BUNDLE_EDITIONS];
+
+    const packagedByEdition = new Map();
+    for (const candidate of candidateEditions) {
+      let candidateTemplate = null;
+      let candidateError = null;
+      try {
+        candidateTemplate = await readPackagedTemplate(candidate, `scaffolding/Git-principles-${policy}.md`);
+      } catch (error) {
+        candidateError = error;
+      }
+      // ⚠ An UNREADABLE packaged starter belongs here too, not one branch
+      // earlier: the old `catch { template = null; }` plus `if (template)` made
+      // a missing packaged file the quietest state of all. Same damage, same
+      // remedy, so it is one finding with the cause named.
+      const candidateRegion = candidateTemplate === null
+        ? null
+        : classifyMarkedRegion(
+          toLf(candidateTemplate),
+          GIT_PRINCIPLES_CANONICAL_START,
+          GIT_PRINCIPLES_CANONICAL_END
+        );
+      packagedByEdition.set(candidate, {
+        template: candidateTemplate,
+        error: candidateError,
+        region: candidateRegion,
+        usable: candidateRegion !== null && candidateRegion.state === 'present'
+      });
+    }
+
+    const damagedEditions = candidateEditions.filter((candidate) => !packagedByEdition.get(candidate).usable);
+    if (damagedEditions.length > 0) {
+      // ⚠ Say the decisive thing only when it is true. `configure-agents` is
+      // certain to fail when EVERY track it could resolve to is damaged — which
+      // covers both "we know the track and it is broken" and "we do not know the
+      // track but all of them are broken". With only some damaged, the reader is
+      // told what is actually known instead of what sounds decisive.
+      const certain = damagedEditions.length === candidateEditions.length;
+      const causes = damagedEditions.map((candidate) => {
+        const entry = packagedByEdition.get(candidate);
+        const cause = entry.region === null
+          ? `could not be read (${entry.error && entry.error.message ? entry.error.message : entry.error})`
+          : 'carries no well-formed git-principles-canonical markers';
+        return `\`templates/${candidate}/scaffolding/Git-principles-${policy}.md\` ${cause}`;
+      });
+      const scope = resolvedEdition
+        ? ''
+        : ' This project does not say which track it uses, so every track the selected policy could resolve to was checked.';
+      // ⚠ THE THIRD SPELLING OF `alsoFails`, AND ROUTE (B) IS WHY. Both of the
+      // originals assume `configure-agents` will get as far as reading this
+      // starter — true only while a policy IS recorded. With none recorded it
+      // never gets there: `addGitPrinciplesItem` reports the missing section and
+      // returns before touching the package, so "fails on this package" would be
+      // a confident false statement about the sibling command on the one path
+      // this gate newly reaches.
+      const alsoFails = !recordedPolicy
+        ? '`dflow configure-agents` does not reach it either way: with no Git policy recorded it declines to refresh any Git principles file.'
+        : (certain
+          ? '`dflow configure-agents` fails on this package before writing a byte.'
+          : 'Whether `dflow configure-agents` also fails depends on which track it resolves this project to.');
+      findings.push({
+        level: 'warn',
+        title: 'The installed dflow package looks incomplete',
+        detail: `Its packaged Git principles starter is unusable: ${causes.join('; ')}.${scope} This report therefore cannot say whether ${relativePath}'s canonical sections are current.`,
+        action: `Reinstall dflow (e.g. \`npm install -g dflow-sdd-ddd@latest\`, or re-link your local checkout). This is a problem with the installed package, not with anything in your project — ${alsoFails}`
+      });
+    }
+
+    // ⚠⚠ THE COMPARISON IS ROUTE (B) NOW, NOT `resolvedEdition` ONLY — and the
+    // history of this line is worth keeping, because BOTH of its earlier forms
+    // were wrong in opposite directions.
+    //
+    // It once compared against whichever single track the manifest named.
+    // `p090-b3-y1` executed that gap: manifest forced to brownfield on a
+    // structurally greenfield project, doctor compared the greenfield file
+    // against the BROWNFIELD starter and reported drift that did not exist — a
+    // resolver disagreement wearing a content finding. The repair narrowed it to
+    // `resolvedEdition` (manifest and structure agreeing), which removed the
+    // false DIRTY and installed a false CLEAN in its place: with the edition
+    // uninferable the whole comparison vanished and said nothing. Measured on
+    // the same mutation — an edited canonical region reported when the edition
+    // was known, `All checks passed` when it was not.
+    //
+    // ⚠ And this proposal's own gate-1 work routed NEW traffic into that hole:
+    // route (B) now enters this loop when no policy is recorded, while the (A)
+    // fallback is suppressed exactly then (the starter file IS on disk, so
+    // `policiesToCheck` is non-empty). Policy unrecorded + edition uninferable +
+    // a drifted file produced neither the drift nor the "which checks did not
+    // run" disclosure.
+    //
+    // Comparing every candidate and clearing on ANY match answers both: the
+    // greenfield project matches the greenfield starter whatever the manifest
+    // claims, so `p090-b3-y1`'s false dirty stays fixed, and an unknown edition
+    // no longer decides whether we look. ⚠ The finding's own wording never named
+    // a packaged file — "differs from the current packaged starter", with the
+    // PROJECT's path in the title — so the old comment's justification for
+    // narrowing ("that sentence names a specific packaged file") was defending
+    // a sentence this code does not print.
+    //
+    // ⚠ Two editions really do ship different canonical regions for the same
+    // policy (measured: trunk 10602 vs 10601 bytes, gitflow 11414 vs 11089), so
+    // this is observable, not latent.
+    const comparableEditions = damagedEditions.length === 0 ? candidateEditions : [];
+
+    if (!projectFileExists) {
+      // ⚠ The recovery action may not send the reader to a scratch `dflow init`
+      // while we KNOW that init would read the damaged starter — it would hand
+      // them the same broken file and look like their own mistake. Same
+      // discipline as `alsoFails`: say the confident thing only when it is true.
+      findings.push({
+        level: 'warn',
+        title: `${relativePath} is missing`,
+        detail: `The selected Git policy (\`${policy}\`) names this principles file; runtime branch gates and finish-feature guidance read it.`,
+        // ⚠ The condition is "is every starter a scratch init could read
+        // damaged", not "do we know the track". `p090-b3-y1` caught the
+        // earlier `edition && !packagedUsable` form still sending the reader
+        // to a scratch init when the edition was unknown and BOTH candidate
+        // starters were broken — the one case where that advice is most
+        // certainly wrong, because whichever track init picks it is damaged.
+        action: damagedEditions.length > 0 && damagedEditions.length === candidateEditions.length
+          ? 'Reinstall dflow first — the packaged copy of this starter is itself unusable (reported above), so a scratch `dflow init` would reproduce the damage. Then recover the file from a fresh `dflow init` in a scratch directory.'
+          : 'Recover it from a fresh `dflow init` in a scratch directory.'
+      });
+    } else {
+      // ⚠⚠ THE PROJECT-SIDE CHECKS DO NOT HANG OFF `edition`, AND TWO OF THE
+      // THREE NEVER NEEDED IT. "Your markers are malformed" and "your file
+      // predates the markers" are properties of the PROJECT'S OWN FILE — they
+      // are decided by `classifyMarkedRegion` on bytes this function already
+      // has, and no packaged template is consulted to reach either verdict.
+      // Only the third branch, the canonical COMPARISON, needs the packaged
+      // side, and it carries its own guard.
+      //
+      // ⚠ Gating all three on `edition` was the sixth boundary drawn around
+      // this check and the last one still standing. `p090-b3-y2` executed it:
+      // strip the manifest and every structural signal but keep
+      // `_conventions.md` with its selected policy, and a pre-marker,
+      // malformed, or stale project file produced
+      // `All checks passed. No Dflow health findings detected.` — while
+      // `configure-agents`, which resolves the track by asking, went on to warn
+      // or refresh. An unknown edition is a fact about the PROJECT'S SHAPE; it
+      // says nothing about whether the adopter's own file is broken, so it must
+      // not decide whether we look.
+      let projected = '';
+      let unreadable = false;
+      try {
+        projected = await fs.readFile(absolute, 'utf8');
+      } catch {
+        unreadable = true;
+      }
+      // PROPOSAL-090 route B3: sections 1-5 are Dflow-canonical and
+      // `configure-agents` refreshes them in place; everything else in this
+      // file is the project's. Comparing the WHOLE file reported drift for
+      // every project that had ever filled in its own CI / CD section, which
+      // is the normal state — so the signal was noise and stayed unread.
+      // Four states, reported apart on purpose.
+      const region = classifyMarkedRegion(
+        toLf(projected),
+        GIT_PRINCIPLES_CANONICAL_START,
+        GIT_PRINCIPLES_CANONICAL_END
+      );
+      if (region.state === 'malformed') {
+        // ⚠ Never fold this into `absent`. A file whose markers were broken
+        // by an edit would then read as "predates the markers", and the
+        // adoption offer would replace sections 1-5 of a file nobody has
+        // looked at. Say what is actually wrong.
+        findings.push({
+          level: 'warn',
+          title: `${relativePath} has malformed git-principles-canonical markers`,
+          detail: 'The START / END pair is incomplete or out of order, so `configure-agents` cannot refresh the canonical sections and will leave the file untouched.',
+          action: `${restorePolicyFirst}Repair or remove the stray \`<!-- dflow-generated: git-principles-canonical ... -->\` markers, then re-run \`dflow configure-agents\`.`
+        });
+      } else if (region.state === 'absent') {
+        // ⚠⚠ ONLY PROMISE THE OFFER WHEN THE OFFER WILL ACTUALLY BE MADE.
+        // `configure-agents` offers marker adoption only for a file it can still
+        // recognise — both heading anchors present exactly once
+        // (`gitPrinciplesCanonicalBounds`). `p090-b3-z1` executed the gap: rename
+        // `## 1. Branch Structure` and doctor still said "accept the
+        // marker-adoption offer" while `configure-agents` never asked. That is a
+        // false claim about another command — the class this file has already
+        // corrected twice — and `docs/upgrading.*` documents the distinction the
+        // code was not making.
+        // ⚠ `unreadable` is split out for the same reason: a file we could not
+        // read produced an empty string, which classifies as `absent`, and doctor
+        // then reported "predates the markers" about content it never saw.
+        const recognizable = gitPrinciplesCanonicalBounds(toLf(projected)) !== null;
+        if (unreadable) {
+          findings.push({
+            level: 'warn',
+            title: `${relativePath} could not be read`,
+            detail: 'It exists but this check could not read it, so nothing can be said about whether its canonical sections are current.',
+            action: 'Check the file\'s permissions and encoding, then re-run `dflow doctor`.'
+          });
+        } else if (recognizable) {
+          findings.push({
+            level: 'info',
+            title: `${relativePath} predates managed git-principles-canonical markers`,
+            detail: 'Its canonical sections (1-5) stay at the Dflow version that seeded them, while the workflow flows that read them are re-projected on every upgrade.',
+            action: `${restorePolicyFirst}Re-run \`dflow configure-agents\` on an interactive terminal and accept the marker-adoption offer; it keeps your file header and everything from "## 6. AI Collaboration Rules (Project Policy)" down.`
+          });
+        } else {
+          findings.push({
+            level: 'info',
+            title: `${relativePath} is not recognizable as a Dflow Git principles starter`,
+            detail: `It has no git-principles-canonical markers, and its \`${GIT_PRINCIPLES_CANONICAL_FIRST_HEADING}\` / \`${GIT_PRINCIPLES_CANONICAL_AFTER_HEADING}\` headings were not both found exactly once, so Dflow cannot tell where its own sections end and yours begin.`,
+            action: 'No marker-adoption offer is made for this file. Restore both headings if it should be Dflow-managed, or keep maintaining it yourself.'
+          });
+        }
+      } else if (comparableEditions.length > 0) {
+        const projectedCanonical = toLf(projected).slice(region.startIdx, region.endIdx);
+        // Clearing on ANY candidate is the whole point: the project's file only
+        // has to be a current starter for SOME shipped track to be current.
+        const matchesSome = comparableEditions.some((candidate) => {
+          const entry = packagedByEdition.get(candidate);
+          return toLf(entry.template).slice(entry.region.startIdx, entry.region.endIdx) === projectedCanonical;
+        });
+        if (!matchesSome) {
+          findings.push({
+            level: 'info',
+            title: `${relativePath} canonical sections differ from the current packaged starter`,
+            detail: comparableEditions.length === 1
+              ? 'Only sections 1-5 are compared; your own sections are not. This is either your edit inside the managed region, or a starter that has not been refreshed yet.'
+              : 'Only sections 1-5 are compared; your own sections are not. This project does not say which track it uses, so every shipped track was checked and the sections match none of them. This is either your edit inside the managed region, or a starter that has not been refreshed yet.',
+            action: `${restorePolicyFirst}Run \`dflow configure-agents\` to refresh the canonical sections in place; content outside the markers is kept.`
+          });
+        }
+      }
+    }
+  }
+
+  // ⚠ (A), and only as the fallback route (B) cannot cover. With no policy
+  // recorded AND no `Git-principles-*.md` on disk there is genuinely nothing to
+  // compare, so this is the one shape where the missing value really does stop
+  // the check — and doctor reports by exception, so staying silent here would
+  // read as "those checks ran and found nothing".
+  if (!recordedPolicy && policiesToCheck.length === 0) {
+    // ⚠ "Add the section to the file" is the wrong instruction when the file is
+    // not there — and this branch is reached most easily in exactly that case,
+    // where the sibling finding below already tells the reader to recover the
+    // whole file. Two findings in one report that disagree about what the reader
+    // should do next is the confusion this proposal exists to remove, so ask
+    // which state it is rather than wording for the commoner one.
+    const conventionsMissing = !(await pathExists(path.join(cwd, 'dflow', 'specs', 'shared', '_conventions.md')));
+    findings.push({
+      level: 'info',
+      title: 'The Git-principles starter checks did not run',
+      detail: `${conventionsMissing
+        ? 'There is no `dflow/specs/shared/_conventions.md` to read a Git policy from'
+        : 'No Git policy is recorded in `dflow/specs/shared/_conventions.md`'}, and no \`dflow/specs/shared/Git-principles-*.md\` file was found to check on its own. Doctor cannot tell which principles file this project needs, so it checked neither its presence nor whether its canonical sections have drifted from the current packaged starter — and the runtime branch gates and finish-feature guidance read that file.`,
+      action: conventionsMissing
+        ? 'Recover `_conventions.md` first (see the finding about it below), keeping its `## Git Policy` section, then re-run `dflow configure-agents` and `dflow doctor`.'
+        : 'Add the `## Git Policy` section to `_conventions.md` (canonical line: `Selected Git policy: `gitflow``, or `trunk`), then re-run `dflow configure-agents` and `dflow doctor`. While the policy is unrecorded, `configure-agents` also declines to refresh Git principles.'
+    });
+  }
+
+  // PROPOSAL-082 G5 / PROPOSAL-083 §4 — report a `_conventions.md` whose
+  // sections predate the current contracts. User-owned: report only, never edit.
+  //
+  // `missing` and `stale` are reported at different levels on purpose.
+  // `### SPEC-ID Format` and `### Slug Conventions` were re-parented by `59e0eb2`
+  // on 2026-05-01 and no released version has ever projected them, so EVERY
+  // existing project is `missing` for that one — it is content the developer was
+  // never offered, not a health problem, and `info` says so without crying wolf.
+  // `stale` means the section IS there and states a rule the shipped flows no
+  // longer follow, which is a live contradiction inside their own conventions,
+  // so it warns.
+  // The file being GONE is the worst state of all, and it was the one state
+  // doctor said nothing about: every `_conventions` check early-returns on a
+  // missing path, and findConventionsDrift returns [] for empty input. Silence
+  // on the worst case is the "reports success" failure this check exists to
+  // avoid, so it is reported first and the drift scan is skipped (three
+  // fingerprint findings about a file that does not exist is noise).
+  // Present-but-empty is handled with absent, not with drift: a whitespace-only
+  // file would otherwise emit one finding per fingerprint, which is noise about
+  // a file that has no content at all. It must not fall through silently
+  // either — that was the gap, and it made an emptier file look healthier than
+  // a one-character one.
+  const conventionsPath = path.join(cwd, 'dflow', 'specs', 'shared', '_conventions.md');
+  const conventionsAbsent = !(await pathExists(conventionsPath));
+  // ⚠ THREE STATES, NOT TWO. The read at the top of this function collapses to
+  // '' on any error, so a file that is present with its contents intact — locked
+  // by permissions, or replaced by a directory — was reported as "is empty",
+  // and the action told the reader to recover it from a scratch init and retype
+  // their answers. That is destructive advice about a file whose content is
+  // still there. The `conventionsUnreadable` branch keeps the coupling this
+  // block is load-bearing for (three sibling checks stay silent about an absent
+  // or blank file ONLY because this one always reports it) — it still always
+  // reports, it just stops guessing which of the three it is.
+  const conventionsUnreadable = !conventionsAbsent && conventions === '' && await pathExists(conventionsPath)
+    ? !(await fs.readFile(conventionsPath, 'utf8').then(() => true).catch(() => false))
+    : false;
+  if (conventionsAbsent || conventionsUnreadable || !conventions.trim()) {
+    findings.push({
+      level: 'warn',
+      title: conventionsAbsent
+        ? 'dflow/specs/shared/_conventions.md is missing'
+        : (conventionsUnreadable
+          ? 'dflow/specs/shared/_conventions.md could not be read'
+          : 'dflow/specs/shared/_conventions.md is empty'),
+      detail: conventionsUnreadable
+        ? 'It exists but this check could not read it, so none of the conventions, Git policy or AI commit marker it records could be checked. Its contents may be perfectly intact.'
+        : 'It records this project\'s spec-writing conventions, Git policy and AI commit marker, and Dflow reads it to answer those questions. Without it, doctor cannot check any of them.',
+      action: conventionsUnreadable
+        ? 'Check that it is a file and that its permissions allow reading, then re-run `dflow doctor`. Do not recreate it until you have confirmed the content is actually lost.'
+        : 'Recover it from a fresh `dflow init` in a scratch directory and re-apply your project-specific answers; it is user-owned, so `dflow configure-agents` does not re-project it.'
+    });
+  } else {
+    const conventionsDrift = doctorChecks.findConventionsDrift(conventions, edition);
+    for (const drift of conventionsDrift) {
+      const missing = drift.state === 'missing';
+      // Say only what is known. A section can be absent because the project
+      // predates it OR because the heading was renamed, and doctor cannot tell
+      // which — an earlier version asserted the first, which is a false
+      // statement to show someone who merely retitled a heading.
+      const neverShipped = missing && drift.neverProjected
+        ? ' No released version before this one projected this section, so a project created earlier will not have it.'
+        : '';
+      const detail = {
+        missing: `Nothing under a heading matching "${drift.heading}" was found, so ${drift.rule} is not recorded. Either the section is absent or its heading was renamed.${neverShipped}`,
+        stale: `The section is present but does not carry ${drift.rule}. ${drift.consequence}`,
+        retired: `The section still carries ${drift.rule}, which PROPOSAL-082 retired. ${drift.consequence}`
+      }[drift.state];
+      // Titles must differ per finding: three retired fingerprints share the
+      // "Ceremony Scaling (Project Application)" heading, so a heading-only
+      // title printed the same line several times with only `detail` differing.
+      const title = {
+        missing: `dflow/specs/shared/_conventions.md has no § ${drift.heading} section`,
+        stale: `dflow/specs/shared/_conventions.md § ${drift.heading} is missing ${drift.rule}`,
+        retired: `dflow/specs/shared/_conventions.md § ${drift.heading} still carries ${drift.rule}`
+      }[drift.state];
+      findings.push({
+        level: drift.level,
+        title,
+        detail,
+        action: 'Compare against a fresh `dflow init` in a scratch directory and copy the section across; `_conventions.md` is yours and Dflow never rewrites it. See `docs/upgrading.md`.'
+      });
+    }
+  }
+
+  // No _overview.md machine-format check: no packaged _overview template has
+  // ever carried `| Tech stack |` / `| Migration / legacy context |` rows, so
+  // their absence there is the canonical state, not drift. The machine-readable
+  // home of those two context values is the guide's "## Project Context" table
+  // — inference reads it and checkGuideProjectContextFormat reports drift
+  // (PROPOSAL-076).
+}
+
+// PROPOSAL-058 direction 2 (e): template-shape drift for filled feature
+// dashboards. Detection + pointers only — migrating a filled document needs
+// judgment (old content into new sections), so the migration itself is
+// AI-assisted, and completed/ features are deliberately not scanned (they keep
+// their historical shape — BUG-001 decision).
+// The project's bundle version from its manifest when it is a plain `x.y.z`;
+// null when there is no readable manifest or the value is anything else. Both
+// shape checks read it: a bundle newer than this CLI means the CLI's packaged
+// templates are not the current ones.
+// The bundle's version, read with the rule `checkBundleManifestVersion` uses:
+// `x.y.z`, or a prerelease `x.y.z-…`. Dflow ships no prerelease, but a
+// hand-edited or forked manifest can carry one — and read as "no version", a
+// newer bundle had its docs judged against this CLI's older templates.
+async function readBundleVersion(cwd) {
+  const manifestResult = await readCurrentBundleManifest(cwd);
+  return manifestResult.kind === 'ok' && typeof manifestResult.manifest.version === 'string'
+    && /^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/.test(manifestResult.manifest.version) ? manifestResult.manifest.version : null;
+}
+
+// How a bundle version compares with this CLI's: by its numeric core, so a
+// prerelease with a newer core is newer. (`compareVersions` would read the
+// patch of `0.15.1-rc.1` as 0.)
+function compareBundleVersion(bundleVersion) {
+  return compareVersions(bundleVersion.replace(/-.*$/, ''), pkg.version);
+}
+
+async function checkFeatureIndexShape(cwd, findings) {
+  // ⚠⚠ PROPOSAL-091 gates 2 and 3. Both exits this function used to take were
+  // the shape `checkInitOnlyStarters` has already had corrected four times, so
+  // they are corrected here the same two ways it was.
+  //
+  // GATE 2 (`if (!edition) return`) — route (B), do not let the missing value
+  // decide whether we look. An unknown edition is a fact about the PROJECT'S
+  // SHAPE; it says nothing about whether the adopter's `_index.md` is stale. The
+  // edition set is closed, so when the project cannot tell us, every track is a
+  // candidate and a file is only reported when it matches NONE of them.
+  //
+  // GATE 3 (`catch { return }`) — route (A), and it must report. An unreadable
+  // packaged template means the installed package is damaged, not that the
+  // project is fine; `checkInitOnlyStarters` names this exact shape as "the
+  // quietest state of all" and `checkWorkflowBundleSourceAndOrphans` records
+  // that NOTHING may gate a package check. Same class, same remedy, same
+  // wording as the sibling finding so one damaged install does not read as two
+  // unrelated problems.
+  const edition = await inferProjectBundleEdition(cwd);
+  const candidateEditions = edition ? [edition] : [...BUNDLE_EDITIONS];
+  const templates = [];
+  const damaged = [];
+  for (const candidate of candidateEditions) {
+    try {
+      templates.push({ edition: candidate, template: await readPackagedTemplate(candidate, 'templates/_index.md') });
+    } catch (error) {
+      damaged.push(`\`templates/${candidate}/templates/_index.md\` could not be read (${error && error.message ? error.message : error})`);
+    }
+  }
+  if (damaged.length > 0) {
+    const scope = edition
+      ? ''
+      : ' This project does not say which track it uses, so every shipped track was checked.';
+    findings.push({
+      level: 'warn',
+      title: 'The installed dflow package looks incomplete',
+      detail: `Its packaged feature dashboard template is unusable: ${damaged.join('; ')}.${scope} This report therefore cannot say whether the \`_index.md\` files under \`dflow/specs/features/active/\` still match the current template shape.`,
+      action: 'Reinstall dflow (e.g. `npm install -g dflow-sdd-ddd@latest`, or re-link your local checkout). This is a problem with the installed package, not with anything in your project.'
+    });
+  }
+  // ⚠⚠ SAME RULE AS `checkGuideCanonicalState`, AND IT IS HERE BECAUSE OF THE
+  // SHAPE, NOT BECAUSE A ROUND CAUGHT IT HERE. A cross-family round reproduced
+  // the false-dirty comparison on the guide only; this function carried the
+  // identical `length === 0` guard, and fixing one of two identical siblings is
+  // the exact failure this proposal documents four times over
+  // ("the same defect was repaired four times while the one next door was left
+  // untouched"). ⚠ It is currently unobservable HERE — both editions' packaged
+  // `_index.md` happen to carry the same H2 set today, so a file matching one
+  // matches the other — which makes it latent rather than absent, and latent is
+  // why it has to be code and not a comment. The detail string is the part that
+  // would lie first: it says "every shipped track was checked" while only the
+  // readable one was.
+  if (damaged.length > 0) return;
+  // PROPOSAL-092 D4: with a bundle newer than this CLI, the packaged `_index.md`
+  // is an older template, so comparing against it would call a current dashboard
+  // older. `checkDocumentShapes` reports that state once, for both checks.
+  const bundleVersion = await readBundleVersion(cwd);
+  if (bundleVersion && compareBundleVersion(bundleVersion) > 0) return;
+  // ⚠⚠ ENOENT AND EVERYTHING ELSE ARE DIFFERENT ANSWERS. "There is no active/
+  // directory" means a project with no features in flight — nothing to report,
+  // and that is the reason PROPOSAL-091's exclusion list judged this exit sound.
+  // ⚠ But that reasoning only ever covered ENOENT: the same `catch` also
+  // swallowed "active/ is there and cannot be listed" (a file in its place,
+  // permissions), and doctor printed `All checks passed` over a feature set it
+  // never looked at. The exclusion was made having read half the state space.
+  const activeDir = path.join(cwd, 'dflow', 'specs', 'features', 'active');
+  let entries = [];
+  try {
+    entries = await fs.readdir(activeDir, { withFileTypes: true });
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return;
+    findings.push({
+      level: 'warn',
+      title: 'dflow/specs/features/active/ could not be listed',
+      detail: `It exists but this check could not read it (${error && (error.code || error.message)}), so no active feature dashboard was compared against the current template shape.`,
+      action: 'Check that it is a directory and that its permissions allow reading, then re-run `dflow doctor`.'
+    });
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const relativePath = `dflow/specs/features/active/${entry.name}/_index.md`;
+    // ⚠ Same split, per feature. A feature directory with no `_index.md` at all
+    // stays silent (the approved shape); one whose `_index.md` is there and
+    // unreadable is a check that disappeared, and says so.
+    let content = null;
+    let indexReadError = null;
+    try {
+      content = await fs.readFile(path.join(activeDir, entry.name, '_index.md'), 'utf8');
+    } catch (error) {
+      indexReadError = error;
+    }
+    if (content === null) {
+      if (indexReadError && indexReadError.code !== 'ENOENT') {
+        findings.push({
+          level: 'warn',
+          title: `${relativePath} could not be read`,
+          detail: `It exists but this check could not read it (${indexReadError.code || indexReadError.message}), so it was not compared against the current template shape.`,
+          action: 'Check that it is a file and that its permissions allow reading, then re-run `dflow doctor`.'
+        });
+      }
+      continue;
+    }
+    // PROPOSAL-092 D4: a dashboard carrying a shape marker is judged by its number
+    // in `checkDocumentShapes`. Comparing its sections here as well would report a
+    // deliberate difference as an older shape — the one distinction the marker
+    // exists to make. ANY marker-like line counts, readable or not: an unreadable
+    // one is reported there as `uncertain`, and a section comparison here would put
+    // a guess beside that honest answer.
+    if (doctorChecks.findShapeMarkerLines(content).length > 0) continue;
+    const perTrack = templates.map((candidate) => ({
+      edition: candidate.edition,
+      missing: doctorChecks.missingTemplateSections(candidate.template, content)
+    }));
+    // ⚠ "Missing from every candidate", not "missing from one of them". With the
+    // track unknown this file could legitimately be either shape, so a section
+    // present in one packaged template is not missing at all — reporting it
+    // would assert a track this project never named.
+    if (perTrack.some((track) => track.missing.length === 0)) continue;
+    const detail = perTrack.length === 1
+      ? `Missing section(s) vs the current template: ${perTrack[0].missing.join(', ')}. Ignore this if you removed them on purpose.`
+      : `This project does not say which track it uses, so every shipped track was checked and this file matches none of them — ${perTrack.map((track) => `${track.edition}: ${track.missing.join(', ')}`).join('; ')}. Ignore this if you removed them on purpose.`;
+    findings.push({
+      level: 'info',
+      title: `${relativePath} looks like an older _index.md template shape`,
+      detail,
+      action: 'Migrate with AI assistance: give your assistant this file plus the current template (`dflow/specs/shared/dflow-workflows/templates/_index.md` after re-projecting) and merge the existing content into the new shape. Completed features can stay as-is.'
+    });
+  }
+}
+
+// PROPOSAL-078 phase 1: delivery-gap detection for the table-cell formatting
+// convention (P-072). Scans user-authored spec surfaces — domain/,
+// architecture/, migration/, features/active/ + backlog/, and loose root
+// docs — and skips shared/ (Dflow-managed bundle, guide, conventions
+// machinery) plus features/completed/ (archived shape stays — same boundary
+// as checkFeatureIndexShape). Emits ONE aggregated info finding; doctor
+// never edits user-authored specs (the `_conventions.md` version-line
+// advance stays configure-agents' only exception, per MAINTAINERS).
+async function checkSpecTableConventionComment(cwd, findings) {
+  const specsRoot = path.join(cwd, 'dflow', 'specs');
+  const hits = [];
+  async function walk(dir, relParts) {
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const rel = [...relParts, entry.name];
+      if (entry.isDirectory()) {
+        if (relParts.length === 0 && entry.name === 'shared') continue;
+        if (relParts.length === 1 && relParts[0] === 'features' && entry.name === 'completed') continue;
+        await walk(path.join(dir, entry.name), rel);
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        const content = await fs.readFile(path.join(dir, entry.name), 'utf8').catch(() => null);
+        if (content === null) continue;
+        if (doctorChecks.hasTableWithoutConventionComment(content)) {
+          hits.push(`dflow/specs/${rel.join('/')}`);
+        }
+      }
+    }
+  }
+  await walk(specsRoot, []);
+  if (hits.length === 0) return;
+  hits.sort();
+  const shown = hits.slice(0, 5).join(', ');
+  const more = hits.length > 5 ? ` (and ${hits.length - 5} more)` : '';
+  findings.push({
+    level: 'info',
+    title: `${hits.length} spec doc(s) hold tables but lack the table-formatting convention comment`,
+    detail: `${shown}${more}. Docs seeded before Dflow 0.13 (or written from scratch) miss the in-file reminder to keep table cells concise (\`<br>\` between short items, long narrative out of cells), so their tables tend to grow hard-to-read walls.`,
+    // ⚠ "Only that one line", and PROPOSAL-092 is why: a template head also
+    // carries the template's `<!-- dflow-shape: … -->` line, and copying the head
+    // stamps the CURRENT number onto a doc of an older shape — a wrong number
+    // doctor then trusts and stays silent about.
+    action: 'With AI assistance, copy only the one-line `<!-- Formatting convention: keep table cells concise ... -->` comment from any current template (`dflow/specs/shared/dflow-workflows/templates/`) into each listed doc, near the top. Copy that line alone, not the template head around it: the head also carries the template\'s `<!-- dflow-shape: ... -->` line, and a doc gets its marker only through the procedure in docs/upgrading.en.md § Shape markers. Doctor never edits user-authored specs.'
+  });
+}
+
+// PROPOSAL-092: template shape markers. Every doc a flow creates from a template
+// inherits the template's `<!-- dflow-shape: {track}/{template} {n} -->` line, and
+// this compares that number with the CURRENT one — the number on the same line in
+// the template packaged with this CLI, not the project's bundle (the reference
+// `checkFeatureIndexShape` compares against too).
+//
+// Five outcomes, each at most ONE aggregated finding — one finding per file is the
+// noise PROPOSAL-078 already learned to fold (six OBTS `rules.md` files):
+//   same number — silent: every difference is the adopter's own decision
+//   older       — info: which docs, which numbers, and what the registry says
+//                 changed in between, split into "add this" and "decide this"
+//   newer       — warn: the doc is newer than this CLI
+//   no marker   — info (D5): doctor does not judge these, and says so
+//   unreadable  — uncertain, under the PROPOSAL-084 contract
+// ⚠⚠ A doc without a marker is NEVER compared against a template (D7, user
+// 2026-09-25). Every such comparison reports placeholder-only sections, frontmatter
+// and replaceable sections as missing on real projects — the noise that teaches
+// people to skip doctor. The one-time procedure on the upgrade page is that
+// comparison, done once, with a person judging each difference.
+// ⚠ Docs on a zero-phase host that has not closed out are listed apart: every fix
+// these findings suggest is an edit, and a minimal host allows none outside its
+// closed closeout list; at closeout the docs move to `features/completed/`, which
+// is not scanned.
+const DOC_SHAPES_REGISTRY_PATH = path.join(PACKAGE_ROOT, 'lib', 'doc-shapes.json');
+const SHAPE_MARKERS_DOC_URL = 'https://github.com/weilung/dflow-sdd-ddd/blob/main/docs/upgrading.en.md#shape-markers';
+// ⚠ Every path, never "(and N more)". These findings are the only record of which
+// docs doctor did not judge, and the one-time procedure works through the docs a
+// finding NAMES — a truncated list is an unjudged doc that nothing points at.
+function shapeDocList(entries, render = (e) => e.display) {
+  return entries.map(render).join(', ');
+}
+
+// PROPOSAL-092: the registry is packaged data doctor trusts to decide what is in
+// scope — an entry with no paths would make its docs vanish from every finding.
+// So its shape is checked before anything is read through it, and a damaged entry
+// is reported as a damaged package rather than skipped.
+function docShapeRegistryProblems(registry) {
+  const problems = [];
+  for (const [key, e] of Object.entries(registry.templates)) {
+    const where = `\`lib/doc-shapes.json\` entry \`${key}\``;
+    if (!/^(greenfield|brownfield)\/[A-Za-z0-9_.-]+\.md$/.test(key)) { problems.push(`${where} is not a {track}/{template} key`); continue; }
+    if (!e || typeof e !== 'object') { problems.push(`${where} is not an object`); continue; }
+    if (typeof e.source !== 'string' || !e.source) problems.push(`${where} has no source`);
+    if (!Array.isArray(e.paths) || e.paths.length === 0 || !e.paths.every((p) => typeof p === 'string' && p)) problems.push(`${where} has no usable paths`);
+    if (!Array.isArray(e.variable) || !Array.isArray(e.conditionalFields)) problems.push(`${where} has no variable / conditionalFields lists`);
+    const shapes = Array.isArray(e.shapes) ? e.shapes : [];
+    if (shapes.length === 0 || !shapes.every((s, i) => s && s.number === i + 1 && typeof s.digest === 'string' && Array.isArray(s.skeleton) && Array.isArray(s.changes))) {
+      problems.push(`${where} has no usable shapes`);
+    }
+  }
+  return problems;
+}
+
+// A change in the notes-and-order half of a shape: `>` notes and HTML comments
+// (added, removed, moved or `reworded`) and `reordered` headings. None of them
+// changes a doc's structure — PROPOSAL-092 D4's third class.
+function isShapeTextChange(change) {
+  return change.kind === 'reordered' || change.kind === 'reworded'
+    || doctorChecks.isShapeTextItem(change.item) || doctorChecks.isShapeTextItem(change.from);
+}
+
+function describeShapeChange(change) {
+  const d = doctorChecks.describeShapeItem;
+  if (change.kind === 'reordered') return `${doctorChecks.describeShapeOrder(change.parent)} changed`;
+  if (change.kind === 'reworded') return `${d(change.to)} changed`;
+  if (change.kind === 'added') return isShapeTextChange(change) ? `${d(change.item)} added` : d(change.item);
+  if (change.kind === 'removed') return `${d(change.item)} removed`;
+  if (change.kind === 'split') return `${d(change.from)} split into ${change.to.map(d).join(' + ')}`;
+  return `${d(change.from)} ${change.kind} to ${d(change.to)}`;
+}
+
+// Every doc under `dflow/specs/` a flow may have created from a template (D7):
+// `checkSpecTableConventionComment`'s boundary — `shared/` (Dflow-managed) and
+// frozen features skipped — plus `shared/_overview.md`, the one adopter-owned doc
+// under `shared/`, and with `features/` narrowed to `active/`: no flow writes a
+// template into `backlog/`, and `completed/` keeps its historical shape.
+// ⚠ A directory that cannot be listed is returned in `unreadable`, not skipped:
+// every doc under it goes unjudged, and saying nothing about it printed
+// `All checks passed` over docs doctor never opened. Only a missing
+// `dflow/specs/` itself is an empty scope.
+// ⚠ A symbolic link (a Windows junction too) is taken for what it points at, for
+// the same reason: skipping every entry that was not a plain file or directory
+// passed a linked `glossary.md` without opening it. A link that cannot be
+// followed is named as unread. A link back to a directory the walk is already
+// inside ends there instead of looping; any other alias is walked under its own
+// path, because its docs may sit at a flow path the other path does not.
+async function listShapeScopeDocuments(specsRoot) {
+  const docs = [];
+  const unreadable = [];
+  const failure = (error) => (error && (error.code || error.message)) || 'unknown error';
+  async function walk(dir, relParts, ancestors) {
+    let entries;
+    let real;
+    try {
+      real = await fs.realpath(dir);
+      if (ancestors.has(real)) return;
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch (error) {
+      if (!(relParts.length === 0 && error && error.code === 'ENOENT')) {
+        unreadable.push({ display: `dflow/specs/${relParts.join('/')}${relParts.length ? '/' : ''}`, code: failure(error) });
+      }
+      return;
+    }
+    const inside = new Set(ancestors).add(real);
+    for (const entry of entries) {
+      const rel = [...relParts, entry.name];
+      // `features/` holds feature directories, and only `active/` is in scope:
+      // a file directly under `features/` belongs to no feature, so it is out too.
+      if (relParts.length === 1 && relParts[0] === 'features' && entry.name !== 'active') continue;
+      let isDirectory = entry.isDirectory();
+      let isFile = entry.isFile();
+      if (entry.isSymbolicLink()) {
+        try {
+          const target = await fs.stat(path.join(dir, entry.name));
+          isDirectory = target.isDirectory();
+          isFile = target.isFile();
+        } catch (error) {
+          unreadable.push({ display: `dflow/specs/${rel.join('/')}`, code: failure(error) });
+          continue;
+        }
+      }
+      if (isDirectory) {
+        if (relParts.length === 0 && entry.name === 'shared') continue;
+        await walk(path.join(dir, entry.name), rel, inside);
+      } else if (isFile && entry.name.endsWith('.md')) {
+        docs.push(rel.join('/'));
+      }
+    }
+  }
+  await walk(specsRoot, [], new Set());
+  // Absent is fine; a link that points nowhere is a doc that cannot be read.
+  const overview = path.join(specsRoot, 'shared', '_overview.md');
+  let present = false;
+  try {
+    const entry = await fs.lstat(overview);
+    present = true;
+    if (entry.isSymbolicLink()) await fs.stat(overview);
+    docs.push('shared/_overview.md');
+  } catch (error) {
+    if (present || !(error && error.code === 'ENOENT')) {
+      unreadable.push({ display: 'dflow/specs/shared/_overview.md', code: failure(error) });
+    }
+  }
+  return { docs: docs.sort(), unreadable };
+}
+
+async function checkDocumentShapes(cwd, findings) {
+  const packageDamage = [];
+  let registry = null;
+  try {
+    registry = JSON.parse(await fs.readFile(DOC_SHAPES_REGISTRY_PATH, 'utf8'));
+    if (!registry || typeof registry.templates !== 'object' || registry.templates === null) {
+      throw new Error('it has no "templates" object');
+    }
+  } catch (error) {
+    registry = null;
+    packageDamage.push(`\`lib/doc-shapes.json\` could not be read (${error && error.message ? error.message : error})`);
+  }
+  if (registry) {
+    const problems = docShapeRegistryProblems(registry);
+    // Coverage in the other direction, by the covered set's own rule (D3) —
+    // every spec template under `templates/<track>/templates/`, and
+    // `scaffolding/_overview.md` — which is the rule `test/doc-shapes.mjs` holds
+    // the source tree to. Not by the markers: a template that lost its marker
+    // and its entry together was found by neither, and its unmarked docs dropped
+    // out of every finding. Any other packaged file that carries a marker needs
+    // an entry as well.
+    for (const track of BUNDLE_EDITIONS) {
+      for (const sub of ['templates', 'scaffolding']) {
+        let names;
+        try {
+          names = (await fs.readdir(path.join(TEMPLATE_ROOT, track, sub))).filter((n) => n.endsWith('.md'));
+        } catch (error) {
+          problems.push(`\`templates/${track}/${sub}/\` could not be listed (${(error && (error.code || error.message)) || 'unknown error'})`);
+          continue;
+        }
+        if (sub === 'scaffolding' && !names.includes('_overview.md')) {
+          problems.push(`\`templates/${track}/scaffolding/_overview.md\` is missing`);
+        }
+        for (const name of names) {
+          const covered = sub === 'templates' || name === '_overview.md';
+          if (!covered) {
+            const text = await fs.readFile(path.join(TEMPLATE_ROOT, track, sub, name), 'utf8').catch(() => '');
+            if (doctorChecks.findShapeMarkerLines(text).length === 0) continue;
+          }
+          const entry = registry.templates[`${track}/${name}`];
+          if (!entry || entry.source !== `${sub}/${name}`) {
+            problems.push(covered
+              ? `\`templates/${track}/${sub}/${name}\` is a template the shape check covers, but \`lib/doc-shapes.json\` has no entry for it`
+              : `\`templates/${track}/${sub}/${name}\` carries a shape marker but \`lib/doc-shapes.json\` has no entry for it`);
+          }
+        }
+      }
+    }
+    if (problems.length > 0) {
+      packageDamage.push(...problems);
+      registry = null;
+    }
+  }
+
+  // The current number of every template: its own marker, in THIS package.
+  const current = new Map();
+  for (const [key, entry] of Object.entries(registry ? registry.templates : {})) {
+    const track = key.split('/')[0];
+    let text;
+    try {
+      text = await readPackagedTemplate(track, entry.source);
+    } catch (error) {
+      packageDamage.push(`\`templates/${track}/${entry.source}\` could not be read (${error && error.message ? error.message : error})`);
+      continue;
+    }
+    const marker = doctorChecks.readShapeMarker(text);
+    if (marker.state !== 'ok' || `${marker.track}/${marker.template}` !== key) {
+      packageDamage.push(`\`templates/${track}/${entry.source}\` has no readable \`${key}\` shape marker`);
+      continue;
+    }
+    // The template's own number is the registry's last shape. Judging against
+    // any other pair would invent a transition the registry cannot describe.
+    if (marker.number !== entry.shapes.length) {
+      packageDamage.push(`\`templates/${track}/${entry.source}\` carries shape ${marker.number}, but \`lib/doc-shapes.json\` lists ${entry.shapes.length} shape(s) for \`${key}\``);
+      continue;
+    }
+    current.set(key, marker.number);
+  }
+  // Kept so the docs it leaves unjudged can be named once the scan has run.
+  let packageFinding = null;
+  if (packageDamage.length > 0) {
+    packageFinding = {
+      level: 'warn',
+      title: 'The installed dflow package looks incomplete',
+      detail: `Its template shape data is unusable: ${packageDamage.join('; ')}. This report therefore cannot say whether spec docs written from ${registry ? 'those templates' : 'any template'} are behind the current template shape.`,
+      action: 'Reinstall dflow (e.g. `npm install -g dflow-sdd-ddd@latest`, or re-link your local checkout). This is a problem with the installed package, not with anything in your project.'
+    };
+    findings.push(packageFinding);
+    if (!registry) return;
+  }
+
+  // D4: a bundle newer than this CLI means its templates are the current ones, and
+  // this CLI's are not — judging against them would call a current doc newer.
+  const bundleVersion = await readBundleVersion(cwd);
+  if (bundleVersion && compareBundleVersion(bundleVersion) > 0) {
+    findings.push({
+      level: 'warn',
+      title: `This project's workflow bundle comes from Dflow ${bundleVersion}, newer than this CLI (${pkg.version})`,
+      detail: 'The template shape check compares each spec doc\'s `<!-- dflow-shape: ... -->` number with the templates packaged in this CLI, which are older than the ones this project was projected from, so it would treat an older template as the current one. Both template shape checks were skipped: the shape markers, and the section comparison of feature \`_index.md\` files without one. (Usually another branch or another machine ran a newer Dflow.)',
+      action: 'Upgrade the CLI (e.g. `npm install -g dflow-sdd-ddd@latest`), then re-run `dflow doctor`.'
+    });
+    return;
+  }
+  const bundleOlder = Boolean(bundleVersion) && compareBundleVersion(bundleVersion) < 0;
+
+  const specsRoot = path.join(cwd, 'dflow', 'specs');
+  const { docs, unreadable: unlistable } = await listShapeScopeDocuments(specsRoot);
+  const contents = new Map();
+  const unread = [...unlistable];
+  for (const rel of docs) {
+    try {
+      contents.set(rel, await fs.readFile(path.join(specsRoot, rel), 'utf8'));
+    } catch (error) {
+      unread.push({ display: `dflow/specs/${rel}`, code: (error && (error.code || error.message)) || 'unknown error' });
+    }
+  }
+  if (unread.length > 0) {
+    findings.push({
+      level: 'warn',
+      title: `${unread.length} path(s) under dflow/specs/ could not be read, so the template shape of what they hold was not judged`,
+      detail: `${shapeDocList(unread, (e) => `${e.display} (${e.code})`)}. Doctor could not open these, so it cannot say whether any spec doc in them is behind the current template shape — or carries a shape marker at all.`,
+      action: 'Check that each is readable and of the right kind (a file where a file belongs, a directory where a directory belongs), then re-run `dflow doctor`.'
+    });
+  }
+  // Zero-phase hosts still open: `_index.md` with an empty `## Phase Specs` table
+  // AND no phase spec in the directory. An empty table beside a phase spec is a
+  // host doctor cannot place (PROPOSAL-092 D5): listed apart, with both ways out.
+  // A phase spec is whatever the registry says a phase spec's path is.
+  const phaseSpecPaths = Object.entries(registry.templates)
+    .filter(([key]) => key.endsWith('/phase-spec.md'))
+    .flatMap(([, entry]) => entry.paths);
+  const hostsWithPhaseSpec = new Set(docs
+    .filter((rel) => phaseSpecPaths.some((p) => doctorChecks.shapePathMatches(p, rel)))
+    .map((rel) => rel.split('/')[2]));
+  const openMinimalHosts = new Set();
+  const unclearHosts = new Set();
+  for (const [rel, content] of contents) {
+    const m = rel.match(/^features\/active\/([^/]+)\/_index\.md$/);
+    if (!m || doctorChecks.sectionTableRowCount(content, 'Phase Specs') !== 0) continue;
+    (hostsWithPhaseSpec.has(m[1]) ? unclearHosts : openMinimalHosts).add(m[1]);
+  }
+  const edition = await inferProjectBundleEdition(cwd);
+  const templateKeys = Object.keys(registry.templates).filter((key) => !edition || key.startsWith(`${edition}/`));
+
+  const older = [];
+  const newer = [];
+  const unmarked = [];
+  const unreadable = [];
+  // Marked docs whose template this package cannot give a current number for:
+  // never judged, so named in the package finding instead of skipped.
+  const damaged = [];
+  for (const [rel, content] of contents) {
+    const host = rel.match(/^features\/active\/([^/]+)\//);
+    const entry = {
+      display: `dflow/specs/${rel}`,
+      onOpenHost: Boolean(host) && openMinimalHosts.has(host[1]),
+      onUnclearHost: Boolean(host) && unclearHosts.has(host[1])
+    };
+    const marker = doctorChecks.readShapeMarker(content);
+    if (marker.state === 'absent') {
+      const mapped = templateKeys.some((key) => registry.templates[key].paths.some((p) => doctorChecks.shapePathMatches(p, rel)));
+      if (mapped) unmarked.push(entry);
+      continue;
+    }
+    if (marker.state === 'unreadable') {
+      if (marker.reason === 'multiple') entry.why = `marker lines at ${marker.lines.join(', ')}`;
+      else if (marker.reason === 'misplaced') {
+        entry.why = `line ${marker.lines[0]} mentions \`dflow-shape:\`, but a marker is read only from line ${marker.standard}`;
+        // The one cause doctor can name: a doc copied whole from the projected
+        // copy, whose first line is the bundle's own. Frontmatter under it is not
+        // frontmatter to `dflow render` either.
+        const firstLine = content.split(/\r?\n/)[0].replace(/^\uFEFF/, '').trim();
+        if (firstLine === WORKFLOW_BUNDLE_GENERATED_MARKER) {
+          entry.why += `; line 1 is \`${WORKFLOW_BUNDLE_GENERATED_MARKER}\`, copied from the template's projected copy — delete it and the blank line after it`;
+        }
+        // Frontmatter behind a byte-order mark is not frontmatter to render
+        // either, so the marker under it is not on its line.
+        if (marker.bomHidesFrontmatter) {
+          entry.why += '; the file starts with a byte-order mark (BOM), which hides its frontmatter from `dflow render` too — save it as UTF-8 without a BOM';
+        }
+      }
+      else entry.why = `line ${marker.lines[0]} is not a well-formed marker`;
+      unreadable.push(entry);
+      continue;
+    }
+    const key = `${marker.track}/${marker.template}`;
+    if (!registry.templates[key]) {
+      entry.why = `line ${marker.line} names \`${key}\`, which this CLI does not ship`;
+      unreadable.push(entry);
+      continue;
+    }
+    const now = current.get(key);
+    if (now === undefined) { damaged.push(entry); continue; }
+    if (marker.number === now) continue;
+    if (marker.number > now) newer.push({ ...entry, key, number: marker.number, now });
+    else older.push({ ...entry, key, from: marker.number, to: now });
+  }
+
+  if (packageFinding && damaged.length > 0) {
+    packageFinding.detail += ` Not judged because of it: ${shapeDocList(damaged)}.`;
+  }
+
+  const apart = (e) => e.onOpenHost || e.onUnclearHost;
+  // A doc on an open minimal host must not be touched before closeout (D5), so
+  // an action that says "edit these docs" says first which ones it leaves out —
+  // the detail naming them "leave alone" while the action said "add markers"
+  // gave the adopter two opposite instructions.
+  const hostAction = (entries) => {
+    const parts = [];
+    if (entries.some((e) => e.onOpenHost)) {
+      parts.push('Leave the docs listed as not yet closed out alone: at closeout they drop out of this check.');
+    }
+    if (entries.some((e) => e.onUnclearHost)) {
+      parts.push('For the docs whose feature doctor cannot place, first decide whether the feature is a minimal host; if it is, leave them alone too.');
+    }
+    return parts.length === 0 ? '' : `${parts.join(' ')} For every other doc: `;
+  };
+  const hostNote = (entries) => {
+    const render = (e) => e.why ? `${e.display} (${e.why})` : e.display;
+    const onHost = entries.filter((e) => e.onOpenHost);
+    const unclear = entries.filter((e) => e.onUnclearHost);
+    return [
+      onHost.length === 0 ? '' : ` Not yet closed out, so leave these alone for now — a minimal host allows no change outside its closeout list, and at closeout they move to features/completed/ and drop out of this check: ${shapeDocList(onHost, render)}.`,
+      unclear.length === 0 ? '' : ` Doctor cannot tell whether these belong to a minimal host that is still open — the feature's \`_index.md\` lists no phase under \`## Phase Specs\`, yet its directory holds a phase spec: ${shapeDocList(unclear, render)}. If the feature is a minimal host, leave them alone until closeout, like an open host; if it is not, handle them like the rest${entries === older ? ' (they are listed with the rest above)' : ''}.`
+    ].join('');
+  };
+
+  if (older.length > 0) {
+    const groups = new Map();
+    // A doc on a host doctor cannot place stays in its group: if the feature is
+    // not a minimal host, what changed is exactly what the adopter needs. The
+    // host note names it again, with the other way out.
+    for (const e of older.filter((x) => !x.onOpenHost)) {
+      const g = `${e.key} ${e.from} → ${e.to}`;
+      if (!groups.has(g)) groups.set(g, { ...e, docs: [] });
+      groups.get(g).docs.push(e);
+    }
+    const described = [...groups.entries()].map(([label, g]) => {
+      const changes = registry.templates[g.key].shapes
+        .filter((s) => s.number > g.from && s.number <= g.to)
+        .flatMap((s) => s.changes || []);
+      const structural = changes.filter((c) => !isShapeTextChange(c));
+      const add = structural.filter((c) => c.kind === 'added').map(describeShapeChange);
+      const decide = structural.filter((c) => c.kind !== 'added').map(describeShapeChange);
+      const text = changes.filter(isShapeTextChange).map(describeShapeChange);
+      const parts = [
+        add.length ? `added — ${add.join('; ')}` : '',
+        decide.length ? `renamed, split, moved or removed — ${decide.join('; ')}` : '',
+        text.length ? `notes, comments and section order, which do not change the doc's structure — ${text.join('; ')}` : ''
+      ].filter(Boolean).join('. ');
+      return `\`${label}\` (${shapeDocList(g.docs)}): ${parts || 'the registry lists no change'}.`;
+    });
+    const overview = older.some((e) => e.key.endsWith('/_overview.md'))
+      ? ' `_overview.md` is not projected into dflow-workflows/: compare it with `templates/<track>/scaffolding/_overview.md` in the installed package, or a fresh `dflow init` in a scratch directory.'
+      : '';
+    findings.push({
+      level: 'info',
+      title: `${older.length} spec doc(s) were written against an older template shape`,
+      detail: `${described.length > 0 ? described.join(' ') : 'None outside the minimal hosts listed next.'}${hostNote(older)}`,
+      action: `${hostAction(older)}${bundleOlder ? 'Run `dflow configure-agents` first, so the templates under dflow-workflows/ are the current ones. ' : ''}For each ADDED item, add it to the doc — the section, the column or the frontmatter field; give existing rows \`{TBD}\` and leave a comment above the table saying what the value is, when to backfill it and how to tell it is done. Add the shape, not the content. Renamed, split, moved and removed items are reported only: decide how to adapt the doc yourself, because filling them in blindly leaves the old and the new section side by side. Notes, comments and section order do not change the doc's structure: compare them with the current template and decide, with your AI assistant, whether to bring the doc in line — keeping yours is a valid answer. When a doc is handled — added to, brought in line, or a difference kept on purpose — change the number on its \`<!-- dflow-shape: ... -->\` line to the current one.${overview} Doctor never edits user-authored specs.`
+    });
+  }
+
+  if (newer.length > 0) {
+    findings.push({
+      level: 'warn',
+      title: `${newer.length} spec doc(s) carry a shape number newer than this CLI knows`,
+      detail: `${shapeDocList(newer, (e) => `${e.display} (\`${e.key}\` ${e.number}; this CLI: ${e.now})`)}. Usually another branch or another machine used a newer Dflow; this CLI cannot say what those numbers mean.`,
+      action: 'Upgrade the CLI (e.g. `npm install -g dflow-sdd-ddd@latest`), then re-run `dflow doctor`.'
+    });
+  }
+
+  if (unmarked.length > 0) {
+    const open = unmarked.filter((e) => !apart(e));
+    const listed = open.length > 0 ? `${shapeDocList(open)}.` : 'None outside the minimal hosts listed below.';
+    const editionNote = edition
+      ? ''
+      : ' This project does not say which track it uses (greenfield or brownfield), and a marker names one: confirm the track before adding markers.';
+    findings.push({
+      level: 'info',
+      title: `${unmarked.length} spec doc(s) have no shape marker, so doctor does not judge their template shape`,
+      detail: `${listed} Without the \`<!-- dflow-shape: ... -->\` line a doc takes from its template, doctor cannot tell a template that changed from a change you made on purpose, so it says nothing about these docs' shape rather than guess. Only docs at the paths Dflow's flows create them at are counted; a renamed or moved doc is not.${editionNote}${hostNote(unmarked)}`,
+      action: `${hostAction(unmarked)}Add the markers once, with AI assistance: compare each doc with the current template, keep what you changed on purpose, add what the template added later (shape, not content), decide yourself how to adapt what it renamed, split, moved or removed, then give the doc the template's marker line with the current number. The procedure: ${SHAPE_MARKERS_DOC_URL} (offline copy: docs/upgrading.en.md in the installed package).`
+    });
+  }
+
+  if (unreadable.length > 0) {
+    const open = unreadable.filter((e) => !apart(e));
+    findings.push(uncertainFinding({
+      id: SHAPE_MARKER_UNREADABLE_ID,
+      title: `${unreadable.length} spec doc(s) have a shape marker doctor cannot read`,
+      detail: `${open.length > 0 ? `${shapeDocList(open, (e) => `${e.display} (${e.why})`)}. ` : ''}A doc needs exactly one line mentioning \`dflow-shape:\` — its marker, on the first line (or, after frontmatter, on the line right after the closing \`---\`), of the form \`<!-- dflow-shape: {track}/{template} {number} -->\` (anything after the number is optional) naming a template this CLI ships. Doctor does not judge whether a marker-like line anywhere else — in a list, a quote, a comment or a code block — is live, and does not guess what a damaged line meant.${hostNote(unreadable)}`,
+      affects: ['the template shape check for these docs — whether each one is behind the current template shape'],
+      action: `${hostAction(unreadable)}Leave exactly one marker line in each doc, at that position. A marker quoted as an example, or an old one commented out, counts too: reword it so it no longer contains \`dflow-shape:\`. If you know which template and number the doc had, write the line back with that number (the line in the installed template carries the current number, which would mark an older doc as current); if you are not sure, treat the doc as having no marker and follow ${SHAPE_MARKERS_DOC_URL} (offline copy: docs/upgrading.en.md in the installed package).`
+    }));
+  }
+}
+
+// PROPOSAL-058: root agent shim manageability. Only existing files are
+// classified — which agents a project uses is not recorded, so an absent file is
+// not a finding; a file with no Dflow content at all is the user's own business.
+async function checkRootAgentShims(cwd, findings) {
+  for (const agent of ['agents', 'claude', 'copilot']) {
+    const target = getAiAgentTarget(agent);
+    const raw = await fs.readFile(path.join(cwd, target.relativePath), 'utf8').catch(() => null);
+    if (raw === null) continue;
+    const lf = toLf(raw);
+    // AGENTS.md can carry a second managed pair (the Codex command-trigger
+    // block); a malformed trigger pair blocks `--command-adapters` trigger
+    // management (snippet fallback) even when the agent-shim block is healthy.
+    if (agent === 'agents') {
+      const triggerRegion = classifyMarkedRegion(lf, CODEX_TRIGGER_SECTION_START, CODEX_TRIGGER_SECTION_END);
+      if (triggerRegion.state === 'malformed') {
+        findings.push({
+          level: 'warn',
+          title: `${target.relativePath} has malformed Dflow command-trigger markers`,
+          detail: '`dflow configure-agents --command-adapters` cannot manage the trigger block and falls back to a merge snippet.',
+          action: 'Remove the stray `<!-- dflow-generated: codex-command-triggers ... -->` markers, then re-run `dflow configure-agents --command-adapters`.'
+        });
+      }
+    }
+    const region = classifyMarkedRegion(lf, AGENT_SHIM_SECTION_START, AGENT_SHIM_SECTION_END);
+    if (region.state === 'malformed') {
+      findings.push({
+        level: 'warn',
+        title: `${target.relativePath} has malformed Dflow markers`,
+        detail: '`dflow configure-agents` cannot manage the Dflow block and falls back to a merge snippet.',
+        action: 'Remove the stray Dflow markers, then re-run `dflow configure-agents`.'
+      });
+      continue;
+    }
+    if (region.state === 'present') continue; // marker-managed: refreshed in place
+    const baseShim = buildAiAgentShim(target.relativePath);
+    if (isPristineDflowAgentsShim(raw, baseShim, target.relativePath)) continue; // regenerated in place
+    if (contentReferencesAiAgentGuide(raw)) {
+      findings.push({
+        level: 'info',
+        title: `${target.relativePath} references the Dflow guide but is not Dflow-managed`,
+        detail: 'Dflow wording inside it stays frozen on upgrade (no markers, and not a pristine Dflow shim).',
+        action: 'Re-run `dflow configure-agents` on an interactive terminal and accept the managed-block offer, then remove any older Dflow wording you keep outside the block.'
+      });
+    }
+  }
+}
+
+// PROPOSAL-091 problem 1, route R3 (user decision, 2026-08-29). Until this
+// check shipped, NOTHING in doctor read a single path under `.claude/`,
+// `.agents/` or `.github/prompts/`: an adopter could delete the entire command
+// adapter and skill layer and doctor's output did not change by one byte.
+//
+// ⚠⚠ THE NAME IS PART OF THE SPEC. Three of the seven rows below judge SKILL
+// files, and the skill row is the only one in this whole proposal with a
+// measured instance behind it (OBTS on `develop`: three `SKILL.md` files still
+// carrying the `0.14.0` description while `doctor` said `All checks passed`).
+// Calling this `checkCommandAdapters` is how the skill half gets dropped.
+//
+// ⚠⚠ IT ONLY JUDGES FILES THAT ARE ALREADY THERE. "One adapter and no skill at
+// all" is SILENT, deliberately, and that silence is a residual risk this
+// proposal accepted rather than an oversight — it is disclosed to adopters in
+// `docs/doctor-uncertainty.md` § "Shapes that are known and deliberately not
+// reported". Three attempts to detect absence were each specified and each
+// found to misfire on a legitimate population: `PROPOSAL-058` records that
+// "which agents a project uses is not recorded, so an absent file is not a
+// finding", and `PROPOSAL-037` (user-approved, 2026-05-22) actively RECOMMENDS
+// that adopters gitignore the adapters and regenerate them after a clone. Both
+// of the states doctor would have to separate — "I never wanted them" and "I
+// had them and they went" — look identical on disk. The superseding fix is a
+// product decision, not a better heuristic: `command-adapters-install-by-default`
+// in `planning/opt-in-backlog.md`. If that lands, revisit this comment and the
+// disclosure page together.
+//
+// ⚠ PER-AGENT, NOT PER-PROJECT, AND THE THREE AGENTS ARE NOT THE SAME SHAPE:
+//   claude  — `.claude/commands/dflow/<id>.md`, its own directory.
+//   copilot — `.github/prompts/dflow-<id>.prompt.md`, a SHARED namespace, so
+//             the `dflow-` glob is the unit and the directory is not.
+//   codex   — has NO command adapter at all (`addCommandAdapterItems` has only
+//             the claude and copilot branches; `PROPOSAL-037` § 6 is the
+//             user-approved decision not to generate them, so that absence is
+//             canonical). ⚠⚠ But codex DOES have a skill: `SKILL_ADAPTER_TARGETS`
+//             keys it `agents`, at `.agents/skills/dflow/SKILL.md`. Writing
+//             "codex is silent" wholesale deletes a third of the coverage of the
+//             one row that has a measurement behind it.
+async function checkAdapterAndSkillState(cwd, findings) {
+  // --- Rows 1 and 6: command adapters, for the two agents that have them ---
+  const commandSurfaces = [
+    {
+      label: '`.claude/commands/dflow/`',
+      relativePathFor: (id) => `.claude/commands/dflow/${id}.md`,
+      flag: '--command-adapters'
+    },
+    {
+      label: '`.github/prompts/dflow-*.prompt.md`',
+      relativePathFor: (id) => `.github/prompts/dflow-${id}.prompt.md`,
+      flag: '--command-adapters'
+    }
+  ];
+  for (const surface of commandSurfaces) {
+    const present = [];
+    const missing = [];
+    const notFiles = [];
+    for (const id of EXPECTED_COMMAND_IDS) {
+      // ⚠⚠ `pathExists` IS TOO WEAK FOR THIS ROW, and the gap was a silent pass
+      // of exactly the kind this check exists to close: it answers "is there
+      // something at this path", while the row is about command adapter FILES.
+      // A directory named `status.md` counted as installed, doctor printed
+      // `All checks passed`, and `configure-agents --command-adapters` then died
+      // EISDIR partway through rewriting the surface. Three states, not two.
+      // (`addLegacyCommandAdapterCleanupItems` already stats and refuses to act
+      //  on a non-file for the same reason — this row just had not caught up.)
+      const relativePath = surface.relativePathFor(id);
+      // eslint-disable-next-line no-await-in-loop
+      const stats = await fs.stat(path.join(cwd, relativePath)).catch(() => null);
+      if (stats === null) missing.push(id);
+      else if (stats.isFile()) present.push(id);
+      else notFiles.push(relativePath);
+    }
+    if (notFiles.length > 0) {
+      const shown = notFiles.slice(0, 3).join(', ');
+      const more = notFiles.length > 3 ? ` (and ${notFiles.length - 3} more)` : '';
+      findings.push({
+        level: 'warn',
+        title: `${notFiles.length} Dflow command adapter path(s) are not files`,
+        detail: `${shown}${more}. Something other than a command adapter file occupies these paths, so this surface cannot be used or regenerated as it stands.`,
+        action: `Remove or rename them, then run \`dflow configure-agents ${surface.flag}\`. Left in place, that command fails partway through rewriting this surface.`
+      });
+    }
+    // Row 5: not one of them is there. Silent — see the header comment.
+    if (present.length === 0) continue;
+    if (missing.length === 0) continue;
+    findings.push({
+      level: 'warn',
+      title: `${surface.label} has ${present.length} of ${EXPECTED_COMMAND_IDS.length} Dflow command adapters`,
+      // ⚠ Say both readings. Doctor cannot separate "I deleted the ones I do not
+      // use" from "the last generation was interrupted" — the files look the
+      // same either way — and this is the noisier level of the two, so the
+      // wording has to carry the ambiguity the level does not.
+      detail: `Missing: ${missing.join(', ')}. Either some were removed on purpose, or a generation run did not finish; the files on disk cannot tell doctor which.`,
+      action: `Run \`dflow configure-agents ${surface.flag}\` to regenerate the full set, or ignore this if you removed them deliberately.`
+    });
+  }
+
+  // --- Row 2: 0.5.0-era filenames left behind ---
+  // Derived from LEGACY_COMMAND_ADAPTERS rather than restated, so a future entry
+  // is picked up here without a second list to keep in sync. Reported on the
+  // file's own evidence: unlike the cleanup path in `configure-agents`, doctor
+  // has no selected-agent list to gate on, and does not need one — the file
+  // being there IS the finding.
+  for (const legacy of LEGACY_COMMAND_ADAPTERS) {
+    const stale = [];
+    for (const command of legacy.commands) {
+      const relativePath = legacy.pathPattern.replace('<id>', command.id);
+      // ⚠ Files only, same reason as the row above, and here it also keeps the
+      // finding's own wording true: it calls these "command adapters using the
+      // 0.5.0 filename", which is a claim about a file. A directory of that name
+      // is not one, and `configure-agents` would not remove it either — it stats
+      // and declines on a non-file.
+      // eslint-disable-next-line no-await-in-loop
+      const stats = await fs.stat(path.join(cwd, relativePath)).catch(() => null);
+      if (stats && stats.isFile()) stale.push(relativePath);
+    }
+    if (stale.length === 0) continue;
+    const shown = stale.slice(0, 3).join(', ');
+    const more = stale.length > 3 ? ` (and ${stale.length - 3} more)` : '';
+    findings.push({
+      level: 'warn',
+      title: `${stale.length} command adapter(s) still use the Dflow ${legacy.version} filename`,
+      detail: `${shown}${more}. Dflow ${legacy.version} wrote \`${legacy.pathPattern}\`; the current layout is \`${legacy.pathPattern.replace(`dflow-<id>`, '<id>')}\`, so these are duplicates that shadow nothing and can drift from the command registry.`,
+      action: `Run \`dflow configure-agents --command-adapters\`, which removes the ones it recognises as Dflow-generated and names any it will not touch.`
+    });
+  }
+
+  // --- Rows 3, 4 and 7: skill files, all three agents alike ---
+  // ⚠ The packaged skill is read ONLY once a marker-bearing project skill has
+  // been found, so a project with no skill at all cannot be told its install is
+  // broken — and a project that HAS one is never told nothing at all. The
+  // `catch { return }` this avoids is the shape `checkInitOnlyStarters` records
+  // as "the quietest state of all".
+  let packagedSkill = null;
+  let packagedSkillError = null;
+  for (const [agent, target] of Object.entries(SKILL_ADAPTER_TARGETS)) {
+    // ⚠⚠ ABSENT AND UNREADABLE ARE DIFFERENT STATES, and one `catch(() => null)`
+    // collapsed them. Row 5's silence is about a file that is NOT THERE; a file
+    // that IS there and cannot be read is the INV-1 shape — something to check
+    // exists, and the check disappeared. `checkInitOnlyStarters` splits exactly
+    // these two apart, for exactly this reason, 400 lines up in this same file;
+    // this loop was the one place that did not. Narrow in practice (invalid
+    // UTF-8 does not reach here — `readFile(…,'utf8')` substitutes U+FFFD — so
+    // it takes a permission or type error), which is an argument about how often
+    // it fires, not about whether the silence is wrong.
+    // ⚠ THIS SPLIT IS NOT APPLIED EVERYWHERE. Four checks this proposal did not
+    // touch — `checkGuideSectionRefs`, `checkSpecTableConventionComment`,
+    // `checkRootAgentShims`, `checkWorkflowBundleSourceAndOrphans` — still fold
+    // an unreadable path into the absent branch and report nothing at all
+    // (measured: each prints `All checks passed`). Declined by the maintainer
+    // 2026-08-30 as a user-system permission/lock condition rather than
+    // something Dflow claims to guard, and recorded as
+    // `doctor-unreadable-vs-absent-sweep` in `planning/opt-in-backlog.md`.
+    // ⚠ If you ever come to make those four consistent, this is the shape to
+    // copy — and that row is where the reasoning for leaving them lives.
+    const skillPath = path.join(cwd, target.relativePath);
+    let existing = null;
+    let unreadable = false;
+    try {
+      existing = await fs.readFile(skillPath, 'utf8');
+    } catch (error) {
+      if (error && error.code !== 'ENOENT') {
+        unreadable = true;
+        findings.push({
+          level: 'warn',
+          title: `${target.relativePath} could not be read`,
+          detail: `It exists but this check could not read it (${error.code || error.message}), so nothing can be said about whether it is the skill this Dflow version projects.`,
+          action: 'Check the path\'s permissions and that it is a file rather than a directory, then re-run `dflow doctor`.'
+        });
+      }
+    }
+    if (unreadable) continue;
+    // Row 5 again: no skill file for this agent. Silent.
+    if (existing === null) continue;
+    // Row 4: no Dflow marker means the overwrite guard in `addSkillAdapterItems`
+    // already treats it as the user's own file and leaves it alone. Doctor has
+    // no business reporting drift against a template it is not the source of.
+    if (!existing.includes(SKILL_ADAPTER_GENERATED_MARKER)) continue;
+    if (packagedSkill === null && packagedSkillError === null) {
+      // ⚠⚠ "READABLE" IS NOT "USABLE", AND THIS ONE HAD TEETH. The read-error
+      // branch alone is only half the rule `checkGuideCanonicalState` follows:
+      // there, a packaged template that is readable but structurally unusable
+      // (no marker region) is ALSO reported as package damage. Here a packaged
+      // skill of zero bytes, or one with the marker stripped, sailed past — and
+      // then every comparison below failed, so doctor told a project whose three
+      // `SKILL.md` files this very CLI had just projected that they "no longer
+      // match this version". That is a false statement about the reader's files
+      // (INV-2), with the blame pointed the wrong way: the sibling check would
+      // have said "a problem with the installed package, not with anything in
+      // your project".
+      //
+      // ⚠⚠ And the action it printed was destructive, which is what sets the
+      // severity. Measured end to end: with the packaged skill emptied, doctor
+      // said "Run `dflow configure-agents --skills` to regenerate it", and doing
+      // exactly that overwrote all three project files 1925 -> 0 bytes and
+      // exited 0. Doctor's advice destroyed the files it had just misdescribed.
+      // ⚠⚠ DECODE STRICTLY, the way `readPackagedTemplate` decodes every OTHER
+      // packaged file. `buildDflowSkillAdapter` is a plain
+      // `readFile(..., 'utf8')`, which never fails: invalid bytes become U+FFFD
+      // and the string sails through "non-empty" and "has the marker". Measured:
+      // four invalid bytes appended to the packaged skill made doctor tell a
+      // project whose three `SKILL.md` files it had just projected that they
+      // "no longer match this version", and following the printed action
+      // rewrote all three with replacement characters (1925 -> 1935 bytes,
+      // exit 0). Emptiness and a missing marker were only two of the ways this
+      // file can be unusable; corruption was the third and the loudest.
+      let candidate = null;
+      try {
+        const buffer = await fs.readFile(path.join(TEMPLATE_ROOT, COMMON_SKILL_SOURCE_REL));
+        candidate = new TextDecoder('utf-8', { fatal: true }).decode(buffer);
+      } catch (error) {
+        packagedSkillError = error;
+      }
+      // A projected skill is defined by its marker — the same token row 4 uses to
+      // decide a file is Dflow's rather than the user's — so a source without it
+      // cannot be the thing we compare against.
+      const usable = candidate !== null
+        && candidate.trim().length > 0
+        && candidate.includes(SKILL_ADAPTER_GENERATED_MARKER);
+      if (usable) {
+        packagedSkill = candidate;
+      } else {
+        if (packagedSkillError === null) packagedSkillError = new Error('unusable');
+        const cause = candidate === null
+          ? `could not be read as UTF-8 text (${packagedSkillError && packagedSkillError.message ? packagedSkillError.message : packagedSkillError})`
+          : (candidate.trim().length === 0
+            ? 'is empty'
+            : 'carries no `dflow-generated: skill-adapter` marker');
+        findings.push({
+          level: 'warn',
+          title: 'The installed dflow package looks incomplete',
+          // ⚠ The action below is the ONLY defence against this. The write side
+          // still projects an unusable packaged skill verbatim and exits 0 —
+          // declined by the maintainer 2026-08-30 (it takes an already-damaged
+          // install) and recorded as `configure-agents-writes-empty-skill` in
+          // `planning/opt-in-backlog.md`. So this wording is load-bearing:
+          // whoever reads it is the last thing standing between a broken
+          // package and three overwritten `SKILL.md` files.
+          detail: `Its packaged skill source ${cause}. This report therefore cannot say whether the Dflow-generated \`SKILL.md\` files in this project are current — and \`dflow configure-agents --skills\` would project this same unusable content over them.`,
+          action: 'Reinstall dflow (e.g. `npm install -g dflow-sdd-ddd@latest`, or re-link your local checkout), and do NOT run `configure-agents --skills` until you have. This is a problem with the installed package, not with anything in your project.'
+        });
+      }
+    }
+    if (packagedSkill === null) continue;
+    // Row 3 (and row 7, which is this row applied to codex). The `description`
+    // frontmatter in this file is the text a tool matches to decide whether to
+    // engage at all, so a stale copy is not a cosmetic lag — it is the natural
+    // language entry point still using the previous release's boundary.
+    if (doctorChecks.matchesTemplateWithPlaceholders(existing, packagedSkill)) continue;
+    findings.push({
+      level: 'info',
+      title: `${target.relativePath} differs from the skill this CLI projects`,
+      detail: 'It carries the Dflow skill marker, so Dflow generated it, and its content no longer matches this version. Its `description` frontmatter is what the tool matches on to auto-engage, so a stale copy keeps an older trigger boundary.',
+      action: `Run \`dflow configure-agents --skills\` to regenerate it (\`--skills\` is required: a flagless run does not refresh a skill that already exists). ${agent === 'agents' ? 'This is the Codex skill path.' : ''}`.trim()
+    });
+  }
+}
+
+// PROPOSAL-058 direction 2 (c) companion: the bundle manifest records which
+// Dflow version last projected the workflow bundle.
+async function checkBundleManifestVersion(cwd, findings) {
+  const manifestResult = await readCurrentBundleManifest(cwd);
+  // ⚠⚠ PROPOSAL-091 gate 7 — disclosure, and the two non-ok kinds are NOT one
+  // state. `readCurrentBundleManifest` already separates them and
+  // `configure-agents` already acts on that split (it reports the file and
+  // degrades on corrupt), so a single `kind !== 'ok'` return here made doctor
+  // the only one of the three that could not tell them apart. ABSENT is the
+  // legal state of a project whose bundle has never been projected — nothing to
+  // report. CORRUPT is damage, and it silently switches off both this check and
+  // the manifest half of `inferProjectBundleEdition`; saying nothing about it is
+  // the silent pass this proposal exists to close.
+  // ⚠ A manifest that IS readable but whose `version` field is absent or
+  // malformed still returns silently below. Deliberate, not an oversight:
+  // `buildBundleManifest` has always written the field, so reaching that state
+  // takes a hand edit of a Dflow-managed file. Declined by the maintainer
+  // 2026-08-30 and recorded as `p091-manifest-version-field-absent` in
+  // `planning/opt-in-backlog.md`, with what would reopen it.
+  if (manifestResult.kind === 'absent') return;
+  if (manifestResult.kind === 'corrupt') {
+    findings.push({
+      level: 'warn',
+      title: `${WORKFLOW_BUNDLE_MANIFEST_PATH} could not be read`,
+      detail: `${manifestResult.reason}. This check therefore cannot say which Dflow version projected the workflow bundle, and the edition the manifest records is unavailable to every check that asks for it. \`dflow configure-agents\` reports the same file and degrades: it skips stale cleanup and leaves the manifest untouched.`,
+      action: `Delete ${WORKFLOW_BUNDLE_MANIFEST_PATH} and run \`dflow configure-agents\` to rebuild it from the current bundle.`
+    });
+    return;
+  }
+  const version = manifestResult.manifest.version;
+  if (typeof version !== 'string' || !/^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/.test(version) || version === pkg.version) return;
+  if (compareVersions(version, pkg.version) < 0) {
+    findings.push({
+      level: 'info',
+      title: `Workflow bundle was projected by Dflow ${version}; this CLI is ${pkg.version}`,
+      detail: 'The references/ and templates/ files under dflow-workflows/ are from the older version.',
+      action: 'Run `dflow configure-agents` to re-project the bundle.'
+    });
+  }
+}
+
 // PROPOSAL-052 (c): read-only mop-up for the manifest-orphan edge. A
 // Dflow-generated bundle file that is no longer in the current package source
 // can linger if it was retired before generalized stale-removal shipped, or the
@@ -3243,19 +6417,185 @@ async function checkConventionsDflowVersion(cwd, findings) {
 // deleted by hand. Doctor detects and reports such files read-only (never
 // deletes). Detection requires a directory scan because, by definition, the
 // manifest no longer lists the orphan — but a read-only scan is safe here.
-async function checkOrphanedWorkflowBundleFiles(cwd, findings) {
-  const bundleDir = path.join(cwd, WORKFLOW_BUNDLE_DEST);
-  if (!(await pathExists(bundleDir))) return;
-
+async function checkWorkflowBundleSourceAndOrphans(cwd, findings) {
+  // ⚠ NOTHING GATES THE PACKAGE CHECK, and EVERY shipped edition is checked. Four
+  // repairs guessed at a boundary here before it was accepted that there isn't one —
+  // see the comment on the `for (const e of dependedOn)` loop below for what each
+  // guess let through. The last guess was the subtlest: checking only the project's
+  // OWN edition, which is exactly enough to answer "will this block me" and not
+  // enough to answer "is my install damaged". Those are different questions and the
+  // report now answers both.
   const edition = await inferProjectBundleEdition(cwd);
-  if (!edition) return;
+  // Needed before the catch, not after: the "your retired-file scan was lost" clause
+  // may only be said where that scan was actually going to run (`projgate-y1` F5).
+  const bundleDir = path.join(cwd, WORKFLOW_BUNDLE_DEST);
+  const bundleExists = await pathExists(bundleDir);
+
+  // ⚠⚠ TWO RESOLVERS, AND THEY DO NOT AGREE. `inferProjectBundleEdition` prefers the
+  // manifest (authoritative for what was PROJECTED, which is what the orphan scan
+  // below compares against). `configure-agents` resolves by STRUCTURE alone. On a
+  // project where they disagree — manifest says brownfield, the tree looks greenfield
+  // — doctor would name a track as unused while `configure-agents` was about to read
+  // exactly that track and hard-fail on it. `projgate-sol1` executed it: doctor said
+  // "does not use", configure exited 1 on the same damage. That is the original
+  // false-clean rebuilt through a different mechanism, and it is a claim this file
+  // only started making an hour earlier.
+  // So the project is treated as depending on ONE edition only when BOTH resolvers
+  // name the same one. Anything else — disagreement, or either resolver silent — and
+  // every edition counts as depended-upon. Conservative, and the cost is only that a
+  // damaged unused track reads as `warn` instead of `info` on an already-inconsistent
+  // project.
+  const structureEdition = await inferExistingEdition(cwd);
+  const resolvedEdition = edition && edition === structureEdition ? edition : null;
+  const dependedOn = resolvedEdition ? [resolvedEdition] : [...BUNDLE_EDITIONS];
+  const unused = BUNDLE_EDITIONS.filter((e) => !dependedOn.includes(e));
 
   let sourceFiles;
   try {
-    sourceFiles = await listBundleSourceFiles(edition);
-  } catch {
+  // ⚠⚠ THIS LOOP IS THE PACKAGE INTEGRITY CHECK, and the comment below is the only
+  // record of why it has the shape it has. It used to live on a named function that a
+  // later repair left unreachable; `projgate-y2r` caught that the pointer above landed
+  // on dead code a routine sweep would delete. Keep it attached to code that RUNS.
+  //
+  // ⚠⚠ THE HISTORY MATTERS, because three separate repairs each moved this boundary
+  // instead of removing it, and each one was reported as a fix. `projgate-x1`: the
+  // check sat behind "is a bundle projected". `projgate-x2`: behind "is an edition
+  // inferable". `projgate-y1`: a common-tree-only scan, which reached exactly ONE of
+  // the three integrity asserts — `assertEditionBundleComplete` never ran, and
+  // `assertNoBundleCollision` over one tree is close to a no-op, since `references/x`
+  // and `templates/x` cannot key-collide and one readdir cannot return two same-case
+  // names. So a cross-tree collision or a gutted edition tree still produced
+  // `All checks passed` beside a `configure-agents` that hard-failed on the same
+  // package. There is nothing to infer: the edition set is CLOSED and both trees
+  // always ship, so when the project cannot tell us, check them all.
+  //
+  // ⚠⚠ ONE PER EDITION, NEVER BOTH IN ONE LIST — and this is the part that looks like
+  // a style choice and is not. `assertNoBundleCollision` keys on `sourceRel` and
+  // deliberately NOT on `sourceRoot`, because its job is to catch one destination path
+  // claimed twice. Merging greenfield and brownfield into a single list therefore
+  // reports every same-named per-track file as a collision, which on the real tree is
+  // every flow reference there is. Measured on the healthy tree: the merged form
+  // throws on `references/drift-verification.md` — a FALSE POSITIVE shipped to every
+  // adopter, strictly worse than the defect it was meant to fix. `projgate-y1` found
+  // the gap correctly and prescribed exactly that merge; the prescription was checked
+  // before it was applied, which is the only reason it is not in this file.
+    for (const e of dependedOn) {
+      const files = await listBundleSourceFiles(e);
+      if (e === edition) sourceFiles = files;
+    }
+  } catch (error) {
+    // ⚠⚠ This catch used to be bare (`catch { return; }`) and it was a false-clean
+    // generator: the three source-integrity asserts inside listBundleSourceFiles
+    // (collision, complete edition tree, complete common tree) fire on a broken
+    // INSTALL, and swallowing them skipped the orphan scan in silence — so `doctor`
+    // printed `All checks passed` and exited 0 on a package whose `configure-agents`
+    // hard-fails before writing a byte. Reproduced end-to-end by `feedbackcommon-xv6`
+    // (2026-08-10): delete one required common file and the two commands disagree
+    // completely. Pre-existing, not introduced by the common-tree single-sourcing.
+    //
+    // ⚠⚠ THE FIRST VERSION OF THIS FIX SAT BELOW THE BUNDLE-DIRECTORY CHECK AND
+    // LEFT HALF THE DEFECT IN PLACE (`projgate-x1`, 2026-08-11). The reasoning then
+    // was: `All checks passed` is a claim about the PROJECT, so a directory with no
+    // projected bundle has abandoned no claim and deserves no warning. That
+    // conflated two different states — a bare directory that is not a Dflow project
+    // at all, and an INITIALIZED project whose bundle is missing. The second is a
+    // Dflow project, doctor does make a claim about it, and the reviewer reproduced
+    // exactly that: delete the project's bundle directory, break the package, and
+    // the old order printed `All checks passed` again. The repair then moved the
+    // gate to "can an edition be inferred" — and `projgate-x2` reached THAT state
+    // too (strip the manifest plus every structural signal). Two wrong guesses at
+    // the same boundary is the signal this repo records as a design question rather
+    // than a third patch — and the third guess (a common-tree-only scan) was wrong
+    // too, for a reason only the other model family saw — see the comment on the
+    // `for (const e of dependedOn)` loop above. The packaged source is now validated
+    // unconditionally, every edition of it.
+    //
+    // ⚠ Level is `warn`, not PROPOSAL-084 `uncertain`. Nothing here is uncertain: a
+    // named assert fired and the remedy is unambiguous. `warn` already suppresses
+    // `All checks passed` (see printDoctorReport), so `uncertain` would buy no extra
+    // honesty while putting a broken install onto an explainer page written for
+    // unreadable PROJECT shapes — and would drag in the id + affects + bilingual
+    // page contract for a state the reader cannot act on differently.
+    //
+    // ⚠ Nothing is rethrown. An unexpected read error must not turn a read-only
+    // health check into a non-zero exit, but it must not vanish either — that is
+    // the same silent-skip class, just with a different trigger.
+    // ⚠ The "and therefore the scan did not run" clause may only be said where that
+    // scan was actually going to run: it needs BOTH an inferred edition and a
+    // projected bundle to compare against. A doctor message that reports a loss which
+    // did not occur is the same class of false operational claim this whole fix
+    // exists to remove — one notch smaller, which is why the first version got the
+    // edition half right and the bundle half wrong (`projgate-y1` F5).
+    const scanLost = edition && bundleExists
+      ? ' The retired-bundle-file scan did not run, so this report cannot say whether your project holds retired bundle files.'
+      : '';
+    if (error instanceof InitError) {
+      // ⚠ "configure-agents will fail on this package too" is only TRUE when we know
+      // which edition THAT command will resolve to. Two rounds narrowed this: with no
+      // edition at all the damage may sit in a tree the project never reads
+      // (`projgate-x3`), and with the two resolvers disagreeing we do not know which
+      // tree it will read (`projgate-sol1`). Both collapse into the same test — say
+      // it flatly only when the resolvers agree. Say what is known, not what sounds
+      // decisive.
+      const alsoFails = resolvedEdition
+        ? '`dflow configure-agents` will fail on this package too.'
+        : 'Whether `dflow configure-agents` also fails depends on which track it resolves this project to.';
+      findings.push({
+        level: 'warn',
+        title: 'The installed dflow package looks incomplete',
+        detail: `An integrity check on its packaged workflow bundle source failed: ${error.message}${scanLost}`,
+        action: `Reinstall dflow (e.g. \`npm install -g dflow-sdd-ddd@latest\`, or re-link your local checkout). This is a problem with the installed package, not with anything in your project — ${alsoFails}`
+      });
+    } else {
+      findings.push({
+        level: 'warn',
+        title: 'Could not read the packaged workflow bundle source',
+        detail: `Reading it failed: ${error && error.message ? error.message : error}.${scanLost}`,
+        action: 'Check that the installed dflow package is readable (permissions, an interrupted install), then re-run `dflow doctor`.'
+      });
+    }
     return;
   }
+
+  // ⚠ DISCLOSE, DO NOT BLOCK (user decision, 2026-08-11). A track this project does
+  // not use can be damaged without anything here ever failing — `projgate-x3`
+  // measured it: a greenfield project on a package with a gutted brownfield tree has
+  // `doctor` and `configure-agents` BOTH succeeding, and both are right, because that
+  // project never reads that tree. So this is not the false-clean the `warn` above
+  // exists for; the two commands agree. What was wrong was only that the report
+  // implied a completeness it had not checked.
+  // The honest answer is a different question with a different level: "will this
+  // block you" is `warn`, "is your install damaged" is `info`. Raising this to `warn`
+  // would re-create the original disagreement in the opposite direction — doctor
+  // saying broken while `configure-agents` runs fine — which trades one false claim
+  // for another rather than removing it.
+  // ⚠ Reached only when the loop above did NOT throw: if the track you depend on is
+  // broken, "reinstall" already covers everything and a second finding is noise.
+  for (const other of unused) {
+    try {
+      await listBundleSourceFiles(other);
+    } catch (error) {
+      findings.push({
+        level: 'info',
+        title: `The installed dflow package is damaged in the ${other} track, which this project does not use`,
+        detail: `${error && error.message ? error.message : error}`,
+        // ⚠ `resolvedEdition`, not `edition`: this sentence is only reachable when both
+        // resolvers agreed, and naming the manifest's answer here when they had not
+        // would be the same false claim one line further down.
+        // ⚠ The install is shared. A global `dflow` serves every project on this
+        // machine, so "does not block THIS project" is not "harmless" — said without
+        // the second sentence it invites a reader to leave a damaged install in place
+        // for a sibling project that does use that track (`projgate-sol1` ITEM 2.1).
+        action: `Nothing here blocks this project — it uses the ${resolvedEdition} track, and neither \`dflow init\` nor \`dflow configure-agents\` reads the ${other} source tree for it. But this install is shared: any other project on this machine that uses the ${other} track will hit it. Reinstall dflow to clear it — and do so before you switch this project to the ${other} track.`
+      });
+    }
+  }
+
+  // Everything below is the ORPHAN SCAN, and it is the only part that needs both an
+  // edition (to know the full source set) and a projected bundle (to have something
+  // to compare against). Package integrity was settled above, independent of both.
+  if (!edition || !bundleExists) return;
+
   const sourceRel = new Set(sourceFiles.map((f) => `${WORKFLOW_BUNDLE_DEST}/${f.sourceRel}`));
 
   for (const dir of ['references', 'templates']) {
@@ -3297,27 +6637,136 @@ async function inferProjectBundleEdition(cwd) {
   return inferExistingEdition(cwd);
 }
 
+// PROPOSAL-084. The page is a mutable `blob/main` pointer, so it inherits
+// PROPOSAL-081's evergreen contract (MAINTAINERS.md § README Language Strategy):
+// it must stay usable by every published CLI that prints this line. The English
+// page is the runtime target and the zh page is one language-switch away, which
+// is the precedent `docs/upgrading.en.md` already set.
+const DOCTOR_UNCERTAINTY_DOC_URL = 'https://github.com/weilung/dflow-sdd-ddd/blob/main/docs/doctor-uncertainty.en.md';
+
+// PROPOSAL-084: the only way to build an `uncertain` finding. It exists so the
+// two fields the state MEANS cannot be dropped by a future caller copying the
+// bare `findings.push({ level, title, detail, action })` shape used everywhere
+// else in this file — the stable id (invariant 3) and the checks whose silence
+// must not be read as a pass (invariant 2). Omitting either throws here, in our
+// code, instead of rendering `undefined` into a user's health report. A crash
+// over a silently wrong answer is this subsystem's standing trade (see
+// `parseContextLine`'s type check for the same call).
+function uncertainFinding({ id, title, detail, affects, action }) {
+  if (!id || !Array.isArray(affects) || affects.length === 0) {
+    throw new Error(`PROPOSAL-084: an uncertain finding needs a stable id and a non-empty affects list (got id=${JSON.stringify(id)}, affects=${JSON.stringify(affects)})`);
+  }
+  return { level: 'uncertain', id, title, detail, affects, action };
+}
+
 function printDoctorReport(stdout, cwd, findings) {
   stdout.write(`Dflow Doctor ${pkg.version}\n`);
   stdout.write(`Project: ${cwd}\n\n`);
 
-  if (findings.length === 0) {
+  const uncertain = findings.filter((f) => f.level === 'uncertain');
+  const assessed = findings.filter((f) => f.level !== 'uncertain');
+
+  // ⚠⚠ PROPOSAL-084 INVARIANT 1 — this branch is the whole proposal.
+  // `All checks passed` is a claim about the WHOLE project. An uncertain finding
+  // says a part of it could not be read at all, so the claim is not available —
+  // not "available with a caveat printed underneath". The reviewer that was asked
+  // to argue AGAINST this proposal made that the condition of its worth: a
+  // disclosure the user can skim past just moves the silent pass from a wrong
+  // `current` to an unread warning.
+  //
+  // ⚠ BE EXACT ABOUT WHAT THIS SPELLING BUYS, because the first version of this
+  // comment overclaimed and the probe caught it. Against the ORIGINAL
+  // `findings.length === 0` the guard is not stronger — it is logically the same
+  // test, since `findings` is the union of the two arrays, and no fixture can
+  // separate them. What it defends is the refactor this very function just made
+  // tempting: now that `assessed` exists and reads like "the real findings", the
+  // natural shorthand here is `assessed.length === 0`, and THAT would print a
+  // clean bill of health over a project whose only finding is uncertain — the
+  // precise false claim this proposal exists to delete. `test/upgrade-drift.mjs`
+  // pins it with a fixture whose findings are uncertain and nothing else, which
+  // is the case that distinguishes those two, and the pin was verified to go red
+  // against the `assessed.length === 0` mutation rather than assumed to.
+  if (uncertain.length === 0 && assessed.length === 0) {
     stdout.write('All checks passed. No Dflow health findings detected.\n');
+    writeAdapterScopeNote(stdout);
+    stdout.write('Doctor is read-only and does not modify any files.\n');
     return;
   }
 
-  for (const finding of findings) {
+  for (const finding of assessed) {
     stdout.write(`[${finding.level}] ${finding.title}\n`);
     stdout.write(`        ${finding.detail}\n`);
     stdout.write(`        ${finding.action}\n\n`);
   }
 
+  for (const finding of uncertain) {
+    stdout.write(`[uncertain] ${finding.title} (${finding.id})\n`);
+    stdout.write(`        ${finding.detail}\n`);
+    // ⚠ INVARIANT 2, and it is doing more work than it looks like. Doctor reports
+    // by exception: a check that emits nothing reads as "that part is current".
+    // For the checks below, that silence is precisely what has stopped being
+    // trustworthy, so naming them converts an absence the user would have
+    // misread into a statement they can act on. Without this line the feature
+    // degrades into "something somewhere may be wrong".
+    // ⚠⚠ "Not evaluated" WAS A FALSE STATEMENT (`p084-xv6` finding 1). The affected
+    // checks still run — a user can see a `[warn]` from a check this very report
+    // called unevaluated, which is a contradiction printed at the exact boundary
+    // this feature exists to be honest about. What is true is weaker and is what
+    // this now says: they ran, and neither their silence nor their output can be
+    // trusted while the shape is present.
+    stdout.write(`        Ran, but cannot be trusted while this shape is present — their silence is NOT a pass, and anything they DO report may be an artefact of the shape: ${finding.affects.join('; ')}.\n`);
+    stdout.write(`        ${finding.action}\n\n`);
+  }
+
   const counts = { warn: 0, info: 0 };
   for (const f of findings) counts[f.level] = (counts[f.level] || 0) + 1;
-  stdout.write(`${findings.length} finding(s): ${counts.warn} warn, ${counts.info} info.\n`);
+  const uncertainTally = counts.uncertain ? `, ${counts.uncertain} uncertain` : '';
+  stdout.write(`${findings.length} finding(s): ${counts.warn} warn, ${counts.info} info${uncertainTally}.\n`);
+  if (uncertain.length > 0) {
+    stdout.write(`\nThis report is INCOMPLETE. Dflow found ${uncertain.length} shape(s) it is known to read unreliably, so the results of the checks named above — including their silence — cannot be trusted.\n`);
+    stdout.write(`What each id means, and how to rewrite around it: ${DOCTOR_UNCERTAINTY_DOC_URL} (offline copy: docs/doctor-uncertainty.en.md in the installed package).\n`);
+  }
+  writeAdapterScopeNote(stdout);
   stdout.write('Doctor is read-only and does not modify any files.\n');
 }
 
+// PROPOSAL-091 (d) — user decision, 2026-08-29. Two rules, and MAINTAINERS.md
+// § Rule Type requires both to be labelled for what they are:
+//
+//   BOUNDARY   — doctor states what it cannot judge. `checkAdapterAndSkillState`
+//                reports only on adapter and skill files that already exist;
+//                whether this project SHOULD have them is intent, and intent is
+//                recorded nowhere on disk.
+//   DELEGATION — it names who picks the question up: the AI running Dflow, which
+//                unlike doctor can simply ask.
+//
+// ⚠⚠ THE PARENTHESIS IS LOAD-BEARING AND MUST NOT BE DROPPED. Without it this
+// reads as a gate — "doctor does not check it, but the AI does, so it is
+// covered" — and nothing enforces that the AI checks, nor verifies afterwards
+// that it did. Describing a delegation as a guarantee is a defect this repo has
+// already paid to remove.
+//
+// ⚠ It prints on every run, and that placement is the whole reason it is cheap:
+// the moment someone asks "is my install complete?" IS the moment doctor is
+// running. The alternatives considered and rejected were the flow files (every
+// feature run pays) and `AI-AGENT-GUIDE.md` (every session pays).
+function writeAdapterScopeNote(stdout) {
+  // ⚠⚠ "their absence is never a finding here" WAS FALSE, and it was printed
+  // directly beneath a finding that contradicted it: with 10 of 11 adapters on
+  // disk, the same report names the missing one. Absence of a WHOLE surface is
+  // what goes unreported; absence of some members of a surface already in use is
+  // reported, and has to be, or the partial-set row would not exist. A scope note
+  // that overstates its own silence is the same defect as a check that overstates
+  // its own coverage — this note exists to be exact about the boundary.
+  // ⚠ "reported above" was wrong for the same reason the sentence before it was:
+  // this note is fixed text on every run, so any claim it makes about THIS
+  // report is false on the runs where that finding is not present. It is a
+  // statement of policy; keep it one.
+  stdout.write('\nScope: doctor does not judge whether this project SHOULD have the `/dflow:*` command files or a Dflow skill file — that is intent, and nothing records it. It judges only surfaces already in use: a partly installed set is reported, while a surface with nothing installed at all is passed over in silence rather than reported as missing.\n');
+  stdout.write('If you are unsure, ask the AI you run Dflow with to check this project once against the command list in AI-AGENT-GUIDE.md.\n');
+  stdout.write('(That is a delegation, not a guarantee: nothing makes it happen, and nothing verifies that it did.)\n');
+}
+
 module.exports = {
   runConfigureAgents,
   runDoctor,
@@ -3331,7 +6780,34 @@ module.exports = {
   writeFilePlan,
   // Exported for tests (PROPOSAL-064): pure bundle-source guards, unit-tested on
   // synthetic descriptor lists without touching the packaged templates/ tree.
+  // REQUIRED_COMMON_BUNDLE_FILES rides along so the tests can derive their
+  // fixtures from the real list instead of restating it: a hardcoded copy goes
+  // stale the moment a file joins the list, and it fails as a confusing
+  // assertion error in the *positive* case rather than as missing coverage.
+  REQUIRED_COMMON_BUNDLE_FILES,
   assertNoBundleCollision,
   assertEditionBundleComplete,
-  assertCommonBundleComplete
+  assertCommonBundleComplete,
+  // Exported for tests (PROPOSAL-076): context inference reads the guide's
+  // Project Context rows, but its only write consumer is whole-guide creation
+  // when the guide is missing — the real-value read has no black-box write to
+  // observe, so tests call these directly.
+  // Exported for tests (PROPOSAL-090): the canonical-region substitution-free
+  // guard must be answer-independent — see placeholderTokens.
+  placeholderTokens,
+  inferTechStackSummary,
+  inferMigrationContext,
+  // Exported for tests (PROPOSAL-084): the id set is the contract between a
+  // shipped `[uncertain]` line and the explainer page it sends the reader to.
+  // Derived from the detector registry rather than retyped, so a new detector
+  // cannot be added without the docs guard noticing it.
+  DOCTOR_UNCERTAINTY_IDS,
+  // Exported for tests (PROPOSAL-091): the route-(B) gates only take their
+  // multi-candidate path when the edition is uninferable, and a fixture cannot
+  // observe that through doctor's output — an unknown edition and a known one
+  // reach the same finding, only the wording differs. The first version of that
+  // fixture removed one of the three structural signals and stayed on the
+  // single-candidate path while claiming to test the other, so the test asserts
+  // the precondition directly instead of assuming it.
+  inferProjectBundleEdition
 };