dflow-sdd-ddd 0.12.0 → 0.14.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,13 @@ 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';
 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';
@@ -250,6 +258,14 @@ async function runInit(options = {}) {
 
     const detection = await detectProjectSignals(cwd);
     const answers = await promptForAnswers(rl, stdout, stderr, detection);
+    // PROPOSAL-074: skill question sits after the AI-agents question and before the
+    // preview; asked only when a skill-capable agent was selected, and only on TTY.
+    answers.skills = await resolveSkillInstall(
+      rl,
+      stdout,
+      Boolean(stdin.isTTY && stdout.isTTY),
+      answers.aiAgents.some((agent) => SKILL_ADAPTER_TARGETS[agent])
+    );
     const plan = await buildFilePlan(cwd, answers);
     const warnings = [...preflight.warnings, ...buildDetectionWarnings(answers, detection), ...(plan.warnings || []), ...(plan.bundleWarnings || [])];
 
@@ -268,7 +284,7 @@ async function runInit(options = {}) {
     result.warnings.push(...collectUnresolvedPlaceholderWarnings(plan, result.created));
 
     printResultReport(stdout, result, plan.deferred);
-    printNextSteps(stdout);
+    printNextSteps(stdout, answers.skills);
     return 0;
   } catch (error) {
     if (rl) {
@@ -331,13 +347,75 @@ async function runConfigureAgents(options = {}) {
       throw new UserAbort('No AI agents selected. Nothing changed.');
     }
 
-    const plan = await buildConfigureAgentsPlan(cwd, {
+    // PROPOSAL-074 (OQ2 branch b): without --skills, a selected agent that has no
+    // project-level skill yet gets the same default-yes install contract as init
+    // (TTY asks, non-TTY installs without reading stdin). Agents whose skill file
+    // already exists — Dflow-generated or user-owned — never re-ask and are NOT
+    // regenerated (skillAgents carries only the missing ones); explicit --skills
+    // keeps its original regenerate-all meaning.
+    let skillAgents = [];
+    if (options.skills) {
+      skillAgents = aiAgents;
+    } else {
+      const missingSkillAgents = [];
+      for (const agent of aiAgents) {
+        const target = SKILL_ADAPTER_TARGETS[agent];
+        if (target && !(await pathExists(path.join(cwd, target.relativePath)))) {
+          missingSkillAgents.push(agent);
+        }
+      }
+      const install = await resolveSkillInstall(
+        rl,
+        stdout,
+        Boolean(stdin.isTTY && stdout.isTTY),
+        missingSkillAgents.length > 0
+      );
+      if (install) {
+        skillAgents = missingSkillAgents;
+      }
+    }
+
+    // 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;
+    const adoptShimAgents = [];
+    const buildPlan = () => buildConfigureAgentsPlan(cwd, {
       ...projectContext,
       aiAgents,
       commandAdapters: Boolean(options.commandAdapters),
-      skills: Boolean(options.skills)
+      skills: Boolean(options.skills),
+      skillAgents,
+      adoptGuideMarkers,
+      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);
+      }
+      for (const agent of shimOffers) {
+        if (await askShimBlockAdoption(rl, stdout, agent)) {
+          adoptShimAgents.push(agent);
+        }
+      }
+      if (adoptGuideMarkers || adoptShimAgents.length > 0) {
+        plan = await buildPlan();
+      }
+    }
+
     const warnings = plan.warnings || [];
     renderPreview(stdout, plan, warnings);
     const confirmed = await askConfirmation(rl, 'Create these files? (y/N) ');
@@ -355,7 +433,7 @@ async function runConfigureAgents(options = {}) {
 
     printResultReport(stdout, result, plan.deferred);
     const usedSnippetFallback = plan.items.some((item) => item.snippetFallback);
-    printConfigureAgentsNextSteps(stdout, Boolean(options.commandAdapters), usedSnippetFallback);
+    printConfigureAgentsNextSteps(stdout, Boolean(options.commandAdapters), usedSnippetFallback, skillAgents.length > 0);
     return 0;
   } catch (error) {
     if (rl) {
@@ -715,18 +793,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) {
@@ -745,22 +824,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(content.replace(/\r\n/g, '\n'));
+  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) {
@@ -978,6 +1078,38 @@ async function askConfirmation(rl, prompt) {
   return answer === 'y' || answer === 'yes';
 }
 
+// PROPOSAL-074: dedicated default-yes contract for the skill-install question.
+// askConfirmation treats blank as false (final-confirmation semantics), so reusing
+// it under a `(Y/n)` prompt would invert the advertised default.
+async function askYesNoDefaultYes(rl, prompt) {
+  const answer = (await askLine(rl, prompt)).trim().toLowerCase();
+  return answer === '' || answer === 'y' || answer === 'yes';
+}
+
+// PROPOSAL-074: the project-level skill installs by default. Ask only on an
+// interactive terminal; a non-TTY run never consumes a stdin slot — existing piped
+// answer sequences end with the final confirmation `y`, and a new question before
+// it would swallow that `y` and turn the run into a silent no-op abort — so
+// non-TTY installs by default without reading stdin.
+async function resolveSkillInstall(rl, stdout, interactive, hasSkillTargets) {
+  if (!hasSkillTargets) {
+    return false;
+  }
+
+  if (!interactive) {
+    return true;
+  }
+
+  const install = await askYesNoDefaultYes(
+    rl,
+    '\nInstall the project-level Dflow skill for natural-language auto-trigger? (Y/n) '
+  );
+  if (!install) {
+    stdout.write('Skipped the project-level skill; add it later with `dflow configure-agents --skills`.\n');
+  }
+  return install;
+}
+
 function parseSelectAnswer(answer, options, defaultKey) {
   const trimmed = answer.trim();
   if (!trimmed && defaultKey) {
@@ -1124,6 +1256,11 @@ async function buildFilePlan(cwd, answers) {
 
   await finalizePlanItems(cwd, items);
 
+  // PROPOSAL-074: init projects the project-level skill by default; answers.skills
+  // carries the Q-flow / non-TTY resolution from runInit (absent = false, which
+  // keeps buildFilePlan backward-compatible for direct callers).
+  await addSkillAdapterItems(cwd, items, answers.aiAgents, answers.skills, warnings);
+
   // Always project the workflow bundle (required for /dflow:* workflows to be reachable).
   const bundleWarnings = [];
   await addWorkflowBundleItems(cwd, items, bundleWarnings, answers.edition);
@@ -1147,19 +1284,18 @@ 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);
 
-  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) {
@@ -1172,7 +1308,11 @@ async function buildConfigureAgentsPlan(cwd, answers) {
     await addLegacyCommandAdapterCleanupItems(cwd, items, answers.aiAgents, warnings);
   }
 
-  await addSkillAdapterItems(cwd, items, answers.aiAgents, answers.skills, warnings);
+  // PROPOSAL-074: skillAgents is the projection subset — all selected agents under
+  // --skills, only the missing ones on a flagless default install (existing skills
+  // are never regenerated without the flag).
+  const skillAgents = answers.skillAgents || (answers.skills ? answers.aiAgents : []);
+  await addSkillAdapterItems(cwd, items, skillAgents, skillAgents.length > 0, warnings);
 
   // Project the workflow bundle on configure-agents too, so pre-039 projects (no bundle)
   // and edition-switch repairs get the runtime references/templates reachable. The function
@@ -1182,6 +1322,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: [],
@@ -1545,6 +1694,219 @@ async function readPackagedBundleFile(sourceRoot, sourceRel) {
   }
 }
 
+// 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 = existingContent.replace(/\r\n/g, '\n');
+  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).
+function isRecognizableDflowGuide(lfContent) {
+  const content = lfContent.replace(/^\uFEFF/, ''); // a BOM must not defeat the title line (gate G4)
+  return doctorChecks.blankFencedBlocks(content).some((line) => /^# Dflow AI Agent Guide\s*$/.test(line)) &&
+    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.
+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 start = scan.findIndex((line) => /^## Project Context\s*$/.test(line));
+  if (start < 0) return null;
+  let end = scan.length;
+  for (let i = start + 1; i < scan.length; i += 1) {
+    if (/^## /.test(scan[i]) || 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);
+  while (existingSection.length > 0 && existingSection[existingSection.length - 1].trim() === '') {
+    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 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 = existingContent.replace(/\r\n/g, '\n');
+  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.
@@ -1701,7 +2063,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,
@@ -1710,6 +2105,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,
@@ -1718,6 +2114,7 @@ async function addAiAgentShim(cwd, items, agent, substitution, options = {}) {
         content: fullShim,
         action: 'skip',
         intentionalSkip: true,
+        offerShimAdoption: agent,
         size: Buffer.byteLength(fullShim, 'utf8')
       });
     }
@@ -2439,8 +2836,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}'],
@@ -2783,10 +3185,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 {
@@ -2801,6 +3221,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;
@@ -2808,6 +3229,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;
@@ -2830,6 +3252,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;
@@ -2837,12 +3260,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;
@@ -2870,6 +3295,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') {
@@ -2911,6 +3337,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;
@@ -2991,7 +3421,12 @@ function printResultReport(stdout, result, deferred) {
   }
 }
 
-function printNextSteps(stdout) {
+// PROPOSAL-074 / PROPOSAL-037: generated skill files are Dflow-managed derivatives;
+// the recommended default is gitignore + re-project after clone.
+const SKILL_VERSION_CONTROL_STEP = '- Project-level skill files (.claude/skills/, .agents/skills/, .github/skills/) are Dflow-managed derivatives: the recommended default is to gitignore them and re-run `dflow configure-agents --skills` after cloning; committing them also works if the team prefers.\n';
+
+function printNextSteps(stdout, skillsInstalled = false) {
+  const skillStep = skillsInstalled ? SKILL_VERSION_CONTROL_STEP : '';
   stdout.write(`
 Dflow init complete.
 
@@ -3000,10 +3435,10 @@ Recommended next steps:
 - For brownfield changes, use the Dflow modify-existing workflow when it becomes available as a CLI command.
 - Before generating more specs, make sure dflow/specs/shared/_conventions.md has the correct Prose Language section.
 - For stack-specific examples (.NET, Java/Spring, Node/TypeScript, Python, Go, PHP/Laravel), see docs/examples-by-stack.md in the Dflow repo.
-`);
+${skillStep}`);
 }
 
-function printConfigureAgentsNextSteps(stdout, commandAdapters = false, snippetFallback = false) {
+function printConfigureAgentsNextSteps(stdout, commandAdapters = false, snippetFallback = false, skillsInstalled = false) {
   const commandAdapterStep = commandAdapters
     ? '- Command adapters use tool-specific invocation names: Claude Code `/dflow:<id>`; GitHub Copilot prompt menu `/dflow-<id>` or canonical `/dflow:<id>` as text; Codex CLI plain text without a slash, such as `dflow:status`. Canonical `/dflow:*` names remain defined in dflow/specs/shared/AI-AGENT-GUIDE.md. If upgrading from Dflow 0.5.0, stale `.claude/commands/dflow/dflow-*.md` files generated by 0.5.0 are detected and listed for removal in the confirmation preview, so Claude Code does not show both old and new command names; edited or non-Dflow files are kept with a warning.\n'
     : '';
@@ -3015,13 +3450,15 @@ function printConfigureAgentsNextSteps(stdout, commandAdapters = false, snippetF
     ? '- A merge snippet was written because an existing agent file had conflicting Dflow markers; review it, fix or remove the stray markers, then merge the Dflow block into that file (or re-run to let Dflow manage it).\n'
     : '';
 
+  const skillStep = skillsInstalled ? SKILL_VERSION_CONTROL_STEP : '';
+
   stdout.write(`
 Dflow AI agent configuration complete.
 
 Recommended next steps:
 - Keep AI-agent-specific root files small.
 - Put durable workflow changes in dflow/specs/shared/AI-AGENT-GUIDE.md.
-${snippetStep}${commandAdapterStep}`);
+${snippetStep}${skillStep}${commandAdapterStep}`);
 }
 
 function printList(stdout, values) {
@@ -3121,7 +3558,16 @@ async function runDoctor(options = {}) {
 
     const findings = [];
     await checkConventionsDflowVersion(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 checkRootAgentShims(cwd, findings);
     await checkOrphanedWorkflowBundleFiles(cwd, findings);
+    await checkBundleManifestVersion(cwd, findings);
 
     printDoctorReport(stdout, cwd, findings);
     return 0;
@@ -3149,6 +3595,412 @@ 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 conventionsPath = path.join(cwd, 'dflow', 'specs', 'shared', '_conventions.md');
+  if (!(await pathExists(conventionsPath))) return;
+  const content = await fs.readFile(conventionsPath, 'utf8').catch(() => '');
+  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 caveat in the Dflow README for user-owned surfaces.'
+    });
+  } 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 conventionsPath = path.join(cwd, 'dflow', 'specs', 'shared', '_conventions.md');
+  if (!(await pathExists(conventionsPath))) return;
+  const content = await fs.readFile(conventionsPath, 'utf8').catch(() => '');
+
+  const sections = [
+    {
+      heading: '## Git Policy',
+      re: doctorChecks.GIT_POLICY_LINE_RE,
+      values: doctorChecks.GIT_POLICY_VALUES,
+      example: 'Selected Git policy: `gitflow`',
+      nullEffect: 'a null Git policy defaults to `trunk` wherever a policy value is required'
+    },
+    {
+      heading: '## 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',
+      re: doctorChecks.PROSE_LANGUAGE_LINE_RE,
+      values: null,
+      example: 'Project prose language: `en`',
+      nullEffect: 'prose-generating flows lose the project language setting'
+    }
+  ];
+
+  for (const section of sections) {
+    if (!new RegExp(`^${section.heading}\\s*$`, 'm').test(content)) {
+      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;
+  }
+  const content = (await fs.readFile(guidePath, 'utf8').catch(() => '')).replace(/\r\n/g, '\n');
+  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;
+  }
+  const edition = await inferProjectBundleEdition(cwd);
+  if (!edition) return;
+  let packaged;
+  try {
+    packaged = await readPackagedTemplate(edition, 'scaffolding/AI-AGENT-GUIDE.md');
+  } catch {
+    return;
+  }
+  const packagedRegion = classifyMarkedRegion(packaged, GUIDE_CANONICAL_SECTION_START, GUIDE_CANONICAL_SECTION_END);
+  if (packagedRegion.state !== 'present') return;
+  if (content.slice(region.startIdx, region.endIdx) !== packaged.slice(packagedRegion.startIdx, packagedRegion.endIdx)) {
+    findings.push({
+      level: 'info',
+      title: `${AI_AGENT_GUIDE_DEST} canonical content differs from this CLI version`,
+      detail: 'The marker-guarded canonical region does not match what this Dflow version projects.',
+      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 = (await fs.readFile(guidePath, 'utf8').catch(() => '')).replace(/\r\n/g, '\n');
+  // 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) {
+    findings.push({
+      level: 'info',
+      title: `${AI_AGENT_GUIDE_DEST} has no "## Project Context" section`,
+      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.',
+      action: 'Restore a "## Project Context" section above the guide-canonical markers, including the `| Tech stack | ... |` and `| Migration / legacy context | ... |` rows.'
+    });
+    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 policy = parsedPolicy && doctorChecks.GIT_POLICY_VALUES.has(parsedPolicy) ? parsedPolicy : null;
+  const edition = await inferProjectBundleEdition(cwd);
+
+  if (policy) {
+    const relativePath = `dflow/specs/shared/Git-principles-${policy}.md`;
+    const absolute = path.join(cwd, relativePath);
+    if (!(await pathExists(absolute))) {
+      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.`,
+        action: 'Recover it from a fresh `dflow init` in a scratch directory (init-only starter; `dflow configure-agents` does not re-project it).'
+      });
+    } else if (edition) {
+      let template = null;
+      try {
+        template = await readPackagedTemplate(edition, `scaffolding/Git-principles-${policy}.md`);
+      } catch {
+        template = null;
+      }
+      if (template) {
+        const projected = await fs.readFile(absolute, 'utf8').catch(() => '');
+        if (!doctorChecks.matchesTemplateWithPlaceholders(projected, template)) {
+          findings.push({
+            level: 'info',
+            title: `${relativePath} differs from the current packaged starter`,
+            detail: 'It is user-owned, so this may be your own edits — or an older Dflow starter shape.',
+            action: 'If you never customized it, compare against a fresh `dflow init` and update manually; Dflow never rewrites it.'
+          });
+        }
+      }
+    }
+  }
+
+  // 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).
+async function checkFeatureIndexShape(cwd, findings) {
+  const edition = await inferProjectBundleEdition(cwd);
+  if (!edition) return;
+  let template;
+  try {
+    template = await readPackagedTemplate(edition, 'templates/_index.md');
+  } catch {
+    return;
+  }
+  const activeDir = path.join(cwd, 'dflow', 'specs', 'features', 'active');
+  let entries = [];
+  try {
+    entries = await fs.readdir(activeDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const relativePath = `dflow/specs/features/active/${entry.name}/_index.md`;
+    const content = await fs.readFile(path.join(activeDir, entry.name, '_index.md'), 'utf8').catch(() => null);
+    if (content === null) continue;
+    const missing = doctorChecks.missingTemplateSections(template, content);
+    if (missing.length === 0) continue;
+    findings.push({
+      level: 'info',
+      title: `${relativePath} looks like an older _index.md template shape`,
+      detail: `Missing section(s) vs the current template: ${missing.join(', ')}. Ignore this if you removed them on purpose.`,
+      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-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 = raw.replace(/\r\n/g, '\n');
+    // 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-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);
+  if (manifestResult.kind !== 'ok') 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
@@ -3248,5 +4100,11 @@ module.exports = {
   // synthetic descriptor lists without touching the packaged templates/ tree.
   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.
+  inferTechStackSummary,
+  inferMigrationContext
 };