dflow-sdd-ddd 0.9.0 → 0.11.0

package/lib/init.js

@@ -15,9 +15,24 @@ const SKILL_ADAPTER_GENERATED_MARKER = '<!-- dflow-generated: skill-adapter -->'
 const WORKFLOW_BUNDLE_GENERATED_MARKER = '<!-- dflow-generated: workflow-bundle -->';
 const CODEX_TRIGGER_SECTION_START = '<!-- dflow-generated: codex-command-triggers START -->';
 const CODEX_TRIGGER_SECTION_END = '<!-- dflow-generated: codex-command-triggers END -->';
+// PROPOSAL-054: marker pair that wraps the Dflow base shim when it is appended
+// into a user-owned root agent file (CLAUDE.md / AGENTS.md / copilot-instructions).
+// It is ONLY used for the in-user-file block; a whole-file Dflow shim (freshly
+// created, or a pristine 0.8.0/0.9.0 shim) stays marker-free and is recognized by
+// the normalized template match (isPristineDflowAgentsShim), so we never have to
+// 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 -->';
 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';
+// Files the common bundle tree (templates/common/) MUST provide. A missing
+// common file is a broken package, NOT a retired bundle file: without this guard
+// listBundleSourceFiles would return a smaller-but-"valid" set lacking the file,
+// 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'];
 const EXPECTED_COMMAND_IDS = [
   'new-feature',
   'modify-existing',
@@ -236,7 +251,7 @@ async function runInit(options = {}) {
     const detection = await detectProjectSignals(cwd);
     const answers = await promptForAnswers(rl, stdout, stderr, detection);
     const plan = await buildFilePlan(cwd, answers);
-    const warnings = [...preflight.warnings, ...buildDetectionWarnings(answers, detection), ...(plan.bundleWarnings || [])];
+    const warnings = [...preflight.warnings, ...buildDetectionWarnings(answers, detection), ...(plan.warnings || []), ...(plan.bundleWarnings || [])];
 
     renderPreview(stdout, plan, warnings);
     const confirmed = await askConfirmation(rl, 'Create these files? (y/N) ');
@@ -339,7 +354,8 @@ async function runConfigureAgents(options = {}) {
     result.warnings.push(...collectUnresolvedPlaceholderWarnings(plan, result.created));
 
     printResultReport(stdout, result, plan.deferred);
-    printConfigureAgentsNextSteps(stdout, Boolean(options.commandAdapters));
+    const usedSnippetFallback = plan.items.some((item) => item.snippetFallback);
+    printConfigureAgentsNextSteps(stdout, Boolean(options.commandAdapters), usedSnippetFallback);
     return 0;
   } catch (error) {
     if (rl) {
@@ -390,13 +406,6 @@ async function runPreflight(cwd) {
     warnings.push('Found empty dflow/specs/. Continuing because no initialized files were found.');
   }
 
-  const legacySpecsPath = path.join(cwd, 'specs');
-  if ((await pathExists(legacySpecsPath)) && (await containsInitializedContent(legacySpecsPath))) {
-    warnings.push(
-      'Detected legacy specs/. Dflow V1 will not migrate or modify it; new files will be created under dflow/specs/. See docs/migrating-to-dflow-v1.md for the manual migration checklist.'
-    );
-  }
-
   await assertWritableProjectRoot(cwd);
 
   if (compareVersions(process.versions.node, MIN_NODE_VERSION) < 0) {
@@ -531,7 +540,13 @@ async function detectConfiguredAgents(cwd) {
   // can default to them instead of re-asking from scratch on every invocation.
   // Order matches AI_AGENT_OPTIONS so the prompt numbering lines up.
   const detected = [];
-  if (await pathExists(path.join(cwd, 'AGENTS.md'))) {
+  if (
+    (await pathExists(path.join(cwd, 'AGENTS.md'))) ||
+    // PROPOSAL-056 Phase 1: a project-level Codex skill counts as configured so
+    // re-runs default to the `agents` target, matching the .claude/skills check
+    // below for Claude.
+    (await pathExists(path.join(cwd, '.agents/skills/dflow')))
+  ) {
     detected.push('agents');
   }
   if (
@@ -541,7 +556,12 @@ async function detectConfiguredAgents(cwd) {
   ) {
     detected.push('claude');
   }
-  if (await pathExists(path.join(cwd, '.github/copilot-instructions.md'))) {
+  if (
+    (await pathExists(path.join(cwd, '.github/copilot-instructions.md'))) ||
+    // A project-level Copilot skill counts as configured too (parity with the
+    // .claude/skills and .agents/skills checks above).
+    (await pathExists(path.join(cwd, '.github/skills/dflow')))
+  ) {
     detected.push('copilot');
   }
   return detected;
@@ -869,7 +889,7 @@ async function askAiAgents(rl, stdout, stderr, defaultKeys = []) {
     if (!parsed.valid) {
       failedAttempts += 1;
       if (failedAttempts >= 3) {
-        throw new InitError('Too many invalid attempts for Q6. Dflow init aborted.');
+        throw new InitError('Too many invalid attempts for Q8. Dflow init aborted.');
       }
       stderr.write(`${parsed.message} (${3 - failedAttempts} attempts left)\n`);
       continue;
@@ -1089,10 +1109,16 @@ async function buildFilePlan(cwd, answers) {
     await addTemplate('dflow/specs/shared/Git-principles-trunk.md', 'scaffolding/Git-principles-trunk.md', 'mandatory, selected Git policy');
   }
 
+  // PROPOSAL-054: agent-shim auto-inject can emit fallback warnings (marker
+  // conflict). init previously never plumbed these — buildConfigureAgentsPlan had
+  // a warnings accumulator but buildFilePlan did not — so a fallback during init
+  // was silent. Collect them here and surface them in runInit alongside the
+  // preflight / detection / bundle warnings.
+  const warnings = [];
   if (answers.aiAgents.length > 0) {
     await addTemplate('dflow/specs/shared/AI-AGENT-GUIDE.md', 'scaffolding/AI-AGENT-GUIDE.md', 'selected, canonical AI agent guide');
     for (const agent of answers.aiAgents) {
-      await addAiAgentShim(cwd, items, agent, substitution);
+      await addAiAgentShim(cwd, items, agent, substitution, { warnings });
     }
   }
 
@@ -1106,6 +1132,7 @@ async function buildFilePlan(cwd, answers) {
     items,
     deferred: buildDeferredItems(answers.edition),
     bundleWarnings,
+    warnings,
     unresolvedInitPlaceholders: Array.from(substitution.entries())
       .filter(([placeholder, value]) => placeholder === value)
       .map(([placeholder]) => placeholder)
@@ -1167,6 +1194,16 @@ async function buildConfigureAgentsPlan(cwd, answers) {
 
 async function finalizePlanItems(cwd, items) {
   for (const item of items) {
+    // PROPOSAL-054: items whose action was already decided at plan time from the
+    // existing file content (root agent-file append / replace / skip / fallback)
+    // must not be re-derived from overwrite+existence here — that would discard
+    // the marked-region decision. Just make sure size is populated.
+    if (item.action) {
+      if (item.size === undefined) {
+        item.size = Buffer.byteLength(item.content || '', 'utf8');
+      }
+      continue;
+    }
     const absolute = path.join(cwd, item.relativePath);
     const targetExists = await pathExists(absolute);
     item.action = targetExists ? (item.overwrite ? 'update' : 'skip') : 'create';
@@ -1177,42 +1214,148 @@ async function finalizePlanItems(cwd, items) {
   }
 }
 
+// A workflow bundle file name must be unique across the common and edition
+// 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) {
+  const seenBy = new Map();
+  for (const f of files) {
+    const prior = seenBy.get(f.sourceRel);
+    if (prior && prior !== f.sourceRoot) {
+      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.`
+      );
+    }
+    seenBy.set(f.sourceRel, f.sourceRoot);
+  }
+}
+
+// R3-02 (sharpened for the PROPOSAL-064 common merge): the EDITION tree itself
+// must contribute both the flow docs (references/) and the blank templates
+// (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.
+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');
+  if (!hasEditionRefs || !hasEditionTemplates) {
+    throw new InitError(
+      `Internal error: incomplete workflow bundle source for edition "${edition}" (expected files under both templates/${edition}/references/ and templates/${edition}/templates/). The installed dflow package looks incomplete.`
+    );
+  }
+}
+
+// Companion to assertEditionBundleComplete for the common tree: every file the
+// common bundle MUST provide has to be present. A common file silently missing
+// (broken package / tarball) would otherwise slip through as a smaller-but-valid
+// set and, on re-projection, be DELETED from the user's project by stale-removal
+// (the manifest diff would classify the still-installed copy as "retired").
+// Hard-fail here, before stale cleanup / manifest write. Pure (no I/O) so it is
+// unit-testable on a synthetic list.
+function assertCommonBundleComplete(files) {
+  const present = new Set(files.filter((f) => f.sourceRoot === 'common').map((f) => f.sourceRel));
+  for (const required of REQUIRED_COMMON_BUNDLE_FILES) {
+    if (!present.has(required)) {
+      throw new InitError(
+        `Internal error: missing required common workflow bundle file templates/common/${required}. The installed dflow package looks incomplete.`
+      );
+    }
+  }
+}
+
+// Bundle source files come from two trees, merged: the edition-neutral common
+// tree (templates/common/, PROPOSAL-064) and the per-edition tree
+// (templates/{edition}/). Each descriptor carries its sourceRoot so the reader
+// (readPackagedBundleFile) loads content from the right tree; the projected dest
+// path and the manifest stay keyed on sourceRel, so a common-sourced file lands
+// 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];
   const files = [];
 
-  for (const dir of bundleDirs) {
-    const sourceDir = path.join(TEMPLATE_ROOT, edition, dir);
-    let entries;
-    try {
-      entries = await fs.readdir(sourceDir);
-    } catch (error) {
-      if (error.code === 'ENOENT') {
-        continue;
+  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;
       }
-      throw error;
-    }
-    for (const entry of entries) {
-      const sourceRel = `${dir}/${entry}`;
-      const sourcePath = path.join(sourceDir, entry);
-      const stat = await fs.stat(sourcePath);
-      if (stat.isFile()) {
-        files.push({ sourceRel, dir, name: entry });
+      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 });
+        }
       }
     }
   }
 
+  assertNoBundleCollision(files);
+  assertEditionBundleComplete(files, edition);
+  assertCommonBundleComplete(files);
   return files;
 }
 
+// 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
+// disable stale cleanup and then overwrite the (recoverable) record. Callers
+// degrade on corrupt — skip cleanup, skip the manifest write, still project —
+// rather than hard-fail, because a corrupt project manifest is a user-project
+// state, not a broken package. An empty `files: []` is a valid manifest.
 async function readCurrentBundleManifest(cwd) {
   const manifestPath = path.join(cwd, WORKFLOW_BUNDLE_MANIFEST_PATH);
+  let raw;
+  try {
+    raw = await fs.readFile(manifestPath, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return { kind: 'absent' };
+    }
+    return { kind: 'corrupt', reason: `cannot read manifest (${error.code || error.message})` };
+  }
+
+  let parsed;
   try {
-    const raw = await fs.readFile(manifestPath, 'utf8');
-    return JSON.parse(raw);
+    parsed = JSON.parse(raw);
   } catch {
-    return null;
+    return { kind: 'corrupt', reason: 'manifest is not valid JSON' };
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { kind: 'corrupt', reason: 'manifest is not a JSON object' };
   }
+  if (!Array.isArray(parsed.files) || !parsed.files.every((entry) => typeof entry === 'string')) {
+    return { kind: 'corrupt', reason: 'manifest "files" is not an array of strings' };
+  }
+  return { kind: 'ok', manifest: parsed };
+}
+
+// True when a manifest `files` entry is a canonical, in-bundle, traversal-free
+// relative path. Manifest entries are produced canonically; a non-canonical
+// entry (hand-edited / corrupt manifest, e.g. one containing "..") is NOT acted
+// on, because (a) it cannot be reliably string-matched against the current
+// bundle set — so a path that *resolves* to a current file would otherwise be
+// scheduled for removal — and (b) it drives an unlink. Verifying canonical form
+// up front both blocks traversal and makes the newRelPaths string compare
+// reliable.
+function isCanonicalBundlePath(relPath) {
+  if (typeof relPath !== 'string' || relPath.length === 0) return false;
+  if (relPath.includes('\\')) return false;
+  if (path.posix.normalize(relPath) !== relPath) return false;
+  const prefix = `${WORKFLOW_BUNDLE_DEST}/`;
+  return relPath.startsWith(prefix) && relPath.length > prefix.length;
 }
 
 function buildBundleManifest(edition, version, files) {
@@ -1229,54 +1372,94 @@ function injectBundleMarker(content) {
 }
 
 async function addWorkflowBundleItems(cwd, items, warnings, edition) {
+  // listBundleSourceFiles merges templates/common/ + templates/{edition}/ and
+  // validates the merged set (collision + complete-edition guards) before
+  // returning, so the projector can trust a complete set here. A broken package
+  // throws (InitError) before any stale removal or manifest write.
   const bundleFiles = await listBundleSourceFiles(edition);
 
-  // Detect any previous manifest to handle edition-switch stale cleanup.
-  const existingManifest = await readCurrentBundleManifest(cwd);
-  const previousEdition = existingManifest ? existingManifest.edition : null;
+  const newRelPaths = new Set(bundleFiles.map((f) => `${WORKFLOW_BUNDLE_DEST}/${f.sourceRel}`));
 
-  // If the edition changed, schedule removal of stale generated files from prior edition.
-  if (previousEdition && previousEdition !== edition) {
-    const staleFiles = existingManifest.files || [];
-    for (const staleRelPath of staleFiles) {
+  // Read the previous manifest to drive stale cleanup. Distinguish absent
+  // (normal) from corrupt (degrade): on corrupt, skip cleanup AND skip the
+  // manifest write below — never hard-fail, since a corrupt project manifest is
+  // a user-project state (the package may be healthy and the user may be running
+  // configure-agents precisely to repair / update).
+  const manifestResult = await readCurrentBundleManifest(cwd);
+  const manifestCorrupt = manifestResult.kind === 'corrupt';
+  if (manifestCorrupt) {
+    warnings.push(
+      `Workflow bundle manifest is unreadable (${manifestResult.reason}); skipped stale cleanup and left the manifest untouched. Delete ${WORKFLOW_BUNDLE_MANIFEST_PATH} and re-run to rebuild it.`
+    );
+  }
+  const existingManifest = manifestResult.kind === 'ok' ? manifestResult.manifest : null;
+
+  // Stale removal (generalized from edition-change-only to a manifest diff):
+  // remove any path the previous manifest recorded but the current bundle source
+  // no longer includes. Edition change is just the case where the whole old set
+  // differs; a same-edition file-set shrink (e.g. a retired bundle file) is
+  // handled identically. The marker check (here) + content re-check (apply
+  // phase) still guard against deleting user-modified files.
+  if (existingManifest) {
+    const previousEdition = existingManifest.edition;
+    const editionChanged = Boolean(previousEdition) && previousEdition !== edition;
+    for (const staleRelPath of existingManifest.files) {
+      // Act only on canonical, in-bundle, traversal-free entries. A
+      // non-canonical entry (hand-edited / corrupt manifest) is skipped: acting
+      // on it would make the newRelPaths string compare unreliable (a path that
+      // resolves to a current bundle file could be scheduled for removal) and it
+      // drives an unlink. Checked FIRST so the membership compare below is sound.
+      if (!isCanonicalBundlePath(staleRelPath)) {
+        warnings.push(
+          `Ignored non-canonical workflow bundle manifest path: ${staleRelPath}`
+        );
+        continue;
+      }
+      // Still a current bundle file → it will be updated, not removed.
+      if (newRelPaths.has(staleRelPath)) {
+        continue;
+      }
       const staleAbsPath = path.join(cwd, staleRelPath);
-      let staleExists = false;
+      let staleStat = null;
       try {
-        await fs.stat(staleAbsPath);
-        staleExists = true;
+        staleStat = await fs.stat(staleAbsPath);
       } catch {
-        staleExists = false;
+        staleStat = null;
+      }
+      if (!staleStat) {
+        continue;
       }
-      if (!staleExists) {
+      // A non-file entry (e.g. a directory path in a hand-edited / corrupt
+      // manifest) must degrade gracefully, not crash readFile with EISDIR.
+      if (!staleStat.isFile()) {
+        warnings.push(`Ignored non-file workflow bundle manifest entry: ${staleRelPath}`);
         continue;
       }
       const staleContent = await fs.readFile(staleAbsPath, 'utf8');
       if (!staleContent.includes(WORKFLOW_BUNDLE_GENERATED_MARKER)) {
         warnings.push(
-          `Edition changed from ${previousEdition} to ${edition}; skipped removal of user-modified bundle file: ${staleRelPath}`
+          `Retired workflow bundle file is user-modified; left unchanged: ${staleRelPath}`
         );
         continue;
       }
-      // Check if this path is also in the new edition bundle — if so, it will be overwritten, not removed.
-      const newRelPaths = new Set(bundleFiles.map((f) => `${WORKFLOW_BUNDLE_DEST}/${f.sourceRel}`));
-      if (!newRelPaths.has(staleRelPath)) {
-        items.push({
-          relativePath: staleRelPath,
-          source: `stale-bundle:${previousEdition}`,
-          notes: `stale workflow bundle file from ${previousEdition} edition`,
-          action: 'remove',
-          size: Buffer.byteLength(staleContent, 'utf8'),
-          expectedContent: staleContent
-        });
-      }
+      items.push({
+        relativePath: staleRelPath,
+        source: editionChanged ? `stale-bundle:${previousEdition}` : 'stale-bundle:retired',
+        notes: editionChanged
+          ? `stale workflow bundle file from ${previousEdition} edition`
+          : 'retired workflow bundle file no longer in the package source',
+        action: 'remove',
+        size: Buffer.byteLength(staleContent, 'utf8'),
+        expectedContent: staleContent
+      });
     }
   }
 
   // Build items for current edition bundle files.
-  for (const { sourceRel } of bundleFiles) {
+  for (const { sourceRel, sourceRoot } of bundleFiles) {
     const relativePath = `${WORKFLOW_BUNDLE_DEST}/${sourceRel}`;
     const absolutePath = path.join(cwd, relativePath);
-    const sourceContent = await readPackagedBundleFile(edition, sourceRel);
+    const sourceContent = await readPackagedBundleFile(sourceRoot, sourceRel);
     const content = injectBundleMarker(sourceContent);
 
     let action;
@@ -1300,7 +1483,7 @@ async function addWorkflowBundleItems(cwd, items, warnings, edition) {
 
     items.push({
       relativePath,
-      source: `packaged-bundle:${edition}/${sourceRel}`,
+      source: `packaged-bundle:${sourceRoot}/${sourceRel}`,
       notes,
       content,
       action,
@@ -1309,32 +1492,40 @@ async function addWorkflowBundleItems(cwd, items, warnings, edition) {
     });
   }
 
-  // Add the manifest file.
-  const manifestContent = JSON.stringify(
-    buildBundleManifest(edition, pkg.version, bundleFiles),
-    null,
-    2
-  ) + '\n';
-  const manifestExists = await pathExists(path.join(cwd, WORKFLOW_BUNDLE_MANIFEST_PATH));
+  // Add the manifest file — unless the existing manifest is corrupt, in which
+  // case leave it untouched (overwriting would destroy the only recoverable
+  // record and silently recreate the manifest-orphan problem).
+  if (!manifestCorrupt) {
+    const manifestContent = JSON.stringify(
+      buildBundleManifest(edition, pkg.version, bundleFiles),
+      null,
+      2
+    ) + '\n';
+    const manifestExists = await pathExists(path.join(cwd, WORKFLOW_BUNDLE_MANIFEST_PATH));
 
-  items.push({
-    relativePath: WORKFLOW_BUNDLE_MANIFEST_PATH,
-    source: `generated:workflow-bundle-manifest`,
-    notes: 'workflow bundle manifest',
-    content: manifestContent,
-    action: manifestExists ? 'update' : 'create',
-    overwrite: true,
-    size: Buffer.byteLength(manifestContent, 'utf8')
-  });
+    items.push({
+      relativePath: WORKFLOW_BUNDLE_MANIFEST_PATH,
+      source: `generated:workflow-bundle-manifest`,
+      notes: 'workflow bundle manifest',
+      content: manifestContent,
+      action: manifestExists ? 'update' : 'create',
+      overwrite: true,
+      size: Buffer.byteLength(manifestContent, 'utf8')
+    });
+  }
 }
 
-async function readPackagedBundleFile(edition, sourceRel) {
-  const filePath = path.join(TEMPLATE_ROOT, edition, sourceRel);
-  const normalizedRoot = path.resolve(TEMPLATE_ROOT, edition);
+// Reads one bundle file's content from its source tree. sourceRoot is the
+// descriptor's tree ('common' or an edition) so a common-sourced file is read
+// from templates/common/, not templates/{edition}/ (PROPOSAL-064). The traversal
+// guard is re-rooted at templates/${sourceRoot}/ accordingly.
+async function readPackagedBundleFile(sourceRoot, sourceRel) {
+  const filePath = path.join(TEMPLATE_ROOT, sourceRoot, sourceRel);
+  const normalizedRoot = path.resolve(TEMPLATE_ROOT, sourceRoot);
   const normalizedFilePath = path.resolve(filePath);
 
   if (!normalizedFilePath.startsWith(`${normalizedRoot}${path.sep}`)) {
-    throw new InitError(`Internal error: packaged bundle file not found: templates/${edition}/${sourceRel}`);
+    throw new InitError(`Internal error: packaged bundle file not found: templates/${sourceRoot}/${sourceRel}`);
   }
 
   let buffer;
@@ -1342,90 +1533,367 @@ async function readPackagedBundleFile(edition, sourceRel) {
     buffer = await fs.readFile(normalizedFilePath);
   } catch (error) {
     if (error.code === 'ENOENT') {
-      throw new InitError(`Internal error: packaged bundle file not found: templates/${edition}/${sourceRel}`);
+      throw new InitError(`Internal error: packaged bundle file not found: templates/${sourceRoot}/${sourceRel}`);
     }
-    throw new InitError(`Internal error: cannot read packaged bundle file: templates/${edition}/${sourceRel}`);
+    throw new InitError(`Internal error: cannot read packaged bundle file: templates/${sourceRoot}/${sourceRel}`);
   }
 
   try {
     return new TextDecoder('utf-8', { fatal: true }).decode(buffer);
   } catch {
-    throw new InitError(`Internal error: invalid UTF-8 packaged bundle file: templates/${edition}/${sourceRel}`);
-  }
-}
-
+    throw new InitError(`Internal error: invalid UTF-8 packaged bundle file: templates/${sourceRoot}/${sourceRel}`);
+  }
+}
+
+// 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.
+// The snippet + warning survive only as a genuine-conflict fallback. Decision table
+// (read existing file content, then branch):
+//   1.  not exists                         -> create marker-free whole-file shim
+//   2a. pristine / prior whole-file shim   -> regenerate in place (idempotent / migrate)
+//   2b. one well-formed agent-shim block   -> replace that block (idempotent re-run)
+//   2c. malformed Dflow markers            -> snippet fallback + warning (file untouched)
+//   2d. references guide, not 2a/2b/2c     -> skip base shim (Codex: still upsert trigger, OQ#6c)
+//   2e. user-owned, non-guide existing     -> append the marked block(s)  <- core change
+// For Codex + --command-adapters the base-shim block and the trigger block are two
+// adjacent, independently-marked regions assembled into ONE plan item (per-item
+// writes are whole-file, so two items for one path would clobber each other).
 async function addAiAgentShim(cwd, items, agent, substitution, options = {}) {
   const target = getAiAgentTarget(agent);
   const targetPath = path.join(cwd, target.relativePath);
-  const targetExists = await pathExists(targetPath);
-  const targetConfigured = targetExists && await fileReferencesAiAgentGuide(targetPath);
   const commandRegistry = options.commandRegistry || [];
   const warnings = options.warnings;
-  const codexCommandAdapterSnippet = target.relativePath === 'AGENTS.md' && commandRegistry.length > 0 && targetExists;
-  const content = substitutePlaceholders(buildAiAgentShim(target.relativePath, options.commandRegistry), substitution);
+  const isCodex = target.relativePath === 'AGENTS.md';
+  const wantsTrigger = isCodex && commandRegistry.length > 0;
   const source = `generated:${agent}-shim`;
 
-  // PROPOSAL-046: when adding Codex command triggers and the existing AGENTS.md
-  // is an unmodified Dflow shim, inject the marked trigger section directly
-  // (zero manual merge) instead of parking a side snippet. A user-modified shim
-  // still degrades safely to the snippet + warning.
-  if (codexCommandAdapterSnippet && targetConfigured) {
-    const existingContent = await fs.readFile(targetPath, 'utf8');
-    const baseShim = substitutePlaceholders(buildAiAgentShim(target.relativePath), substitution);
-    if (isPristineDflowAgentsShim(existingContent, baseShim)) {
-      items.push({
-        relativePath: target.relativePath,
-        source,
-        notes: `selected, injected command trigger section into Dflow-generated ${target.relativePath}`,
-        content,
-        overwrite: true
-      });
-      return;
-    }
+  // Marker-free whole-file forms. `fullShim` is what a freshly created or regenerated
+  // file contains (for Codex + --command-adapters it already embeds the trigger).
+  // `baseShimBody` is the trigger-free shim wrapped in agent-shim markers when
+  // appended into a user-owned file.
+  const baseShimBody = substitutePlaceholders(buildAiAgentShim(target.relativePath), substitution);
+  const fullShim = substitutePlaceholders(buildAiAgentShim(target.relativePath, commandRegistry), substitution);
+  const agentShimBlock = wrapAgentShimBlock(baseShimBody);
+  const triggerBlock = wantsTrigger
+    ? substitutePlaceholders(buildCodexCommandTriggerSection(commandRegistry), substitution).trim()
+    : '';
+
+  // Case 1 — create the marker-free whole-file shim. A re-run recognizes it through
+  // the normalized template match (case 2a), so it needs no marker of its own.
+  if (!(await pathExists(targetPath))) {
+    items.push({
+      relativePath: target.relativePath,
+      source,
+      notes: 'selected, tool-specific shim',
+      content: fullShim,
+      action: 'create',
+      size: Buffer.byteLength(fullShim, 'utf8')
+    });
+    return;
+  }
+
+  const existingContent = await fs.readFile(targetPath, 'utf8');
+  const eol = detectDominantEol(existingContent);
+  const lf = existingContent.replace(/\r\n/g, '\n');
+  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
+  // agent-shim region, and a trigger region that overlaps it would be corrupted by
+  // that slice. We only need the region for the safety gate below; trigger writes
+  // still happen only when wantsTrigger.
+  const triggerRegion = isCodex
+    ? classifyMarkedRegion(lf, CODEX_TRIGGER_SECTION_START, CODEX_TRIGGER_SECTION_END)
+    : { state: 'absent' };
+
+  // Case 2c — Dflow markers cannot be edited safely; fall back to a previewed merge
+  // snippet + warning and leave the file untouched. Three unsafe shapes:
+  //   - the agent-shim marker pair is malformed (can't locate the block to manage);
+  //   - we are managing the trigger (--command-adapters) and the trigger pair is
+  //     malformed (can't locate the block to update);
+  //   - the agent-shim and trigger regions overlap / interleave, which the independent
+  //     region slices below would corrupt. This is checked on EVERY AGENTS.md run,
+  //     adapter or not, because case 2b slices the agent-shim region regardless.
+  // A malformed trigger on a NON-adapter run is deliberately NOT a blanket fallback: we
+  // never touch the trigger there. But slicing the agent-shim block IS unsafe when
+  // trigger markers straddle its boundary (some inside, some outside) — removing the
+  // inside one(s) can promote the remaining outside markers into a new well-formed
+  // trigger region wrapping the regenerated block. `triggerStraddlesAgent` catches that
+  // on every AGENTS.md run (a fully-inside set is cleaned with the block, a fully-
+  // outside set is untouched — both safe). The fallback ALWAYS warns (also closing the
+  // R2-02 asymmetry). When only the trigger pair is malformed in a guide-configured file
+  // under --command-adapters (no agent/overlap/straddle issue), the base shim is already
+  // present, so the fallback is the trigger-only snippet (OQ#6c).
+  const regionsOverlap = agentRegion.state === 'present' && triggerRegion.state === 'present' &&
+    agentRegion.startIdx < triggerRegion.endIdx && triggerRegion.startIdx < agentRegion.endIdx;
+  const triggerStraddlesAgent = isCodex && agentRegion.state === 'present' &&
+    codexTriggerMarkersStraddle(lf, agentRegion.startIdx, agentRegion.endIdx);
+  if (agentRegion.state === 'malformed' || (wantsTrigger && triggerRegion.state === 'malformed') ||
+      regionsOverlap || triggerStraddlesAgent) {
+    const triggerOnlyFallback = wantsTrigger && triggerRegion.state === 'malformed' &&
+      agentRegion.state !== 'malformed' && !regionsOverlap && !triggerStraddlesAgent &&
+      contentReferencesAiAgentGuide(existingContent);
+    const snippetPath = triggerOnlyFallback
+      ? 'dflow/specs/shared/AGENTS-md-command-adapters-snippet.md'
+      : target.snippetPath;
+    const snippetContent = triggerOnlyFallback
+      ? substitutePlaceholders(buildCodexCommandTriggerSection(commandRegistry), substitution)
+      : fullShim;
     if (warnings) {
       warnings.push(
-        `Existing ${target.relativePath} was modified after Dflow generated it; wrote the command trigger section to dflow/specs/shared/AGENTS-md-command-adapters-snippet.md for manual merge.`
+        `Existing ${target.relativePath} contains malformed Dflow markers; left it untouched and wrote ${snippetPath} for manual merge. Remove the stray Dflow markers and re-run to let Dflow manage the block.`
       );
     }
     items.push({
-      relativePath: 'dflow/specs/shared/AGENTS-md-command-adapters-snippet.md',
+      relativePath: snippetPath,
       source,
-      notes: `selected, ${target.relativePath} was modified after Dflow generated it; merge this command trigger snippet manually`,
-      content,
-      overwrite: true
+      notes: `selected, ${target.relativePath} has conflicting Dflow markers; merge this snippet manually`,
+      content: snippetContent,
+      overwrite: true,
+      snippetFallback: true
     });
     return;
   }
 
-  const relativePath = codexCommandAdapterSnippet
-    ? target.snippetPath
-    : (targetExists && !targetConfigured ? target.snippetPath : target.relativePath);
-  let notes = 'selected, tool-specific shim';
-  if (codexCommandAdapterSnippet) {
-    notes = `selected, ${target.relativePath} already exists; merge this command trigger snippet manually`;
-  } else if (targetConfigured) {
-    notes = `selected, ${target.relativePath} already points to AI-AGENT-GUIDE.md`;
-  } else if (targetExists) {
-    notes = `selected, ${target.relativePath} already exists; merge this snippet manually`;
+  // Case 2b — exactly one well-formed agent-shim block: replace it in place. For
+  // Codex + --command-adapters also (re)place the adjacent trigger block in the SAME
+  // item.
+  if (agentRegion.state === 'present') {
+    let updated = lf.slice(0, agentRegion.startIdx) + agentShimBlock + lf.slice(agentRegion.endIdx);
+    if (wantsTrigger) {
+      updated = upsertCodexTriggerBlock(updated, triggerBlock);
+    }
+    pushRootInjectItem(items, {
+      relativePath: target.relativePath,
+      source,
+      notes: `selected, updated Dflow block in existing ${target.relativePath}`,
+      content: applyEol(updated, eol),
+      expectedContent: existingContent
+    });
+    return;
+  }
+
+  // No agent-shim marker below.
+
+  // Case 2a — the whole file is a shim Dflow itself would generate (a pristine
+  // 0.8/0.9 shim, or an earlier whole-file injection): regenerate it (idempotent +
+  // migrate an older template forward), preserving the file's dominant EOL. When this
+  // run is not (re)generating a trigger, keep any trigger block the file already has.
+  if (isPristineDflowAgentsShim(existingContent, baseShimBody, target.relativePath)) {
+    let newWhole = fullShim;
+    if (!wantsTrigger && isCodex) {
+      const existingTrigger = extractCodexTriggerBlock(lf);
+      if (existingTrigger) {
+        newWhole = `${baseShimBody.replace(/\n+$/, '')}\n\n${existingTrigger.trim()}\n`;
+      }
+    }
+    pushRootInjectItem(items, {
+      relativePath: target.relativePath,
+      source,
+      notes: `selected, regenerated Dflow ${target.relativePath} shim`,
+      content: applyEol(newWhole, eol),
+      expectedContent: existingContent
+    });
+    return;
+  }
+
+  // Case 2d — the file already references the guide but is neither pristine nor
+  // 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).
+  if (contentReferencesAiAgentGuide(existingContent)) {
+    if (wantsTrigger) {
+      pushRootInjectItem(items, {
+        relativePath: target.relativePath,
+        source,
+        notes: `selected, installed Dflow command triggers into existing ${target.relativePath}`,
+        content: applyEol(upsertCodexTriggerBlock(lf, triggerBlock), eol),
+        expectedContent: existingContent
+      });
+    } else {
+      items.push({
+        relativePath: target.relativePath,
+        source,
+        notes: `selected, ${target.relativePath} already points to AI-AGENT-GUIDE.md`,
+        content: fullShim,
+        action: 'skip',
+        intentionalSkip: true,
+        size: Buffer.byteLength(fullShim, 'utf8')
+      });
+    }
+    return;
   }
 
+  // Case 2e — user-owned, non-guide existing file: append the marked Dflow block(s)
+  // at end of file (the core new behavior; replaces the old snippet-park). Append-only,
+  // previewed, reversible (delete the block to revert), idempotent on re-run (case 2b).
+  const blocks = wantsTrigger ? [agentShimBlock, triggerBlock] : [agentShimBlock];
+  pushRootInjectItem(items, {
+    relativePath: target.relativePath,
+    source,
+    notes: `selected, appended Dflow block to existing ${target.relativePath}`,
+    content: appendDflowBlocks(existingContent, blocks, eol),
+    expectedContent: existingContent
+  });
+}
+
+// Push one plan item that edits a user-owned root agent file. The write phase
+// (writeFilePlan rootInject branch) re-reads the file and requires raw-byte equality
+// with `expectedContent` before writing, so a file changed between preview and write
+// is never clobbered. When the computed content already equals the file, record a
+// quiet idempotent skip instead of a no-op write.
+function pushRootInjectItem(items, { relativePath, source, notes, content, expectedContent }) {
+  const size = Buffer.byteLength(content, 'utf8');
+  if (content === expectedContent) {
+    items.push({
+      relativePath,
+      source,
+      notes: `${notes}; already current`,
+      content,
+      action: 'skip',
+      intentionalSkip: true,
+      size
+    });
+    return;
+  }
   items.push({
     relativePath,
     source,
     notes,
     content,
-    overwrite: codexCommandAdapterSnippet
+    expectedContent,
+    action: 'update',
+    overwrite: true,
+    rootInject: true,
+    size
   });
 }
 
-async function fileReferencesAiAgentGuide(targetPath) {
-  try {
-    const content = await fs.readFile(targetPath, 'utf8');
-    return content.includes('dflow/specs/shared/AI-AGENT-GUIDE.md') ||
-      content.includes('dflow\\specs\\shared\\AI-AGENT-GUIDE.md');
-  } catch {
-    return false;
+function contentReferencesAiAgentGuide(content) {
+  return content.includes('dflow/specs/shared/AI-AGENT-GUIDE.md') ||
+    content.includes('dflow\\specs\\shared\\AI-AGENT-GUIDE.md');
+}
+
+function wrapAgentShimBlock(shimBody) {
+  const body = shimBody.replace(/\n+$/, '');
+  return `${AGENT_SHIM_SECTION_START}\n${body}\n${AGENT_SHIM_SECTION_END}`;
+}
+
+// Append `block` (LF) at end of `lfContent` (LF) with a one-blank-line separator,
+// preserving the existing content and its final-newline convention exactly — trailing
+// whitespace is never stripped. Returns LF.
+function appendBlockLf(lfContent, block) {
+  if (lfContent === '') {
+    return `${block}\n`;
+  }
+  if (lfContent.endsWith('\n\n')) {
+    return `${lfContent}${block}\n`;
+  }
+  if (lfContent.endsWith('\n')) {
+    return `${lfContent}\n${block}\n`;
+  }
+  return `${lfContent}\n\n${block}\n`;
+}
+
+// Append Dflow blocks at end of an existing user file. The user's content is kept in
+// full (never stripped or reordered) and the final-newline convention is preserved —
+// only a one-blank-line separator is added. The whole result is emitted in the file's
+// 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');
+  return applyEol(appendBlockLf(lf, blocks.join('\n\n')), eol);
+}
+
+// Replace an existing well-formed Codex trigger block, or append one at EOF preserving
+// the existing content + final-newline convention (no stripping). Assumes the trigger
+// markers are absent or a single well-formed pair (malformed is handled upstream as a
+// snippet fallback). `lfContent` / `triggerBlock` are LF strings.
+function upsertCodexTriggerBlock(lfContent, triggerBlock) {
+  const region = classifyMarkedRegion(lfContent, CODEX_TRIGGER_SECTION_START, CODEX_TRIGGER_SECTION_END);
+  if (region.state === 'present') {
+    return lfContent.slice(0, region.startIdx) + triggerBlock + lfContent.slice(region.endIdx);
+  }
+  return appendBlockLf(lfContent, triggerBlock);
+}
+
+function extractCodexTriggerBlock(content) {
+  const region = classifyMarkedRegion(content, CODEX_TRIGGER_SECTION_START, CODEX_TRIGGER_SECTION_END);
+  return region.state === 'present' ? content.slice(region.startIdx, region.endIdx) : null;
+}
+
+// Classify a START/END marker pair in `content`:
+//   'absent'    neither marker appears
+//   'present'   exactly one START and one END, in order (startIdx/endIdx returned)
+//   'malformed' any other shape (partial / duplicated / nested / reversed)
+// 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);
+  if (startCount === 0 && endCount === 0) {
+    return { state: 'absent' };
+  }
+  if (startCount === 1 && endCount === 1) {
+    const startIdx = content.indexOf(startMarker);
+    const endInner = content.indexOf(endMarker);
+    if (startIdx < endInner) {
+      return { state: 'present', startIdx, endIdx: endInner + endMarker.length };
+    }
+  }
+  return { state: 'malformed' };
+}
+
+function countOccurrences(haystack, needle) {
+  if (!needle) {
+    return 0;
+  }
+  let count = 0;
+  let index = haystack.indexOf(needle);
+  while (index !== -1) {
+    count += 1;
+    index = haystack.indexOf(needle, index + needle.length);
+  }
+  return count;
+}
+
+function markerPositions(content, marker) {
+  const positions = [];
+  let index = content.indexOf(marker);
+  while (index !== -1) {
+    positions.push(index);
+    index = content.indexOf(marker, index + marker.length);
   }
+  return positions;
+}
+
+// True when Codex trigger markers cross the [start, end) boundary — at least one inside
+// and at least one outside. Slicing [start, end) (the case-2b agent-shim replace) is
+// then unsafe: removing the inside marker(s) can leave the outside marker(s) forming a
+// new well-formed trigger region wrapping the regenerated block. All-inside (removed
+// with the block) and all-outside (untouched) are both safe; only a boundary cross is.
+function codexTriggerMarkersStraddle(content, start, end) {
+  const positions = [
+    ...markerPositions(content, CODEX_TRIGGER_SECTION_START),
+    ...markerPositions(content, CODEX_TRIGGER_SECTION_END)
+  ];
+  const inside = positions.some((position) => position >= start && position < end);
+  const outside = positions.some((position) => position < start || position >= end);
+  return inside && outside;
+}
+
+// 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.
+function detectDominantEol(content) {
+  const crlf = (content.match(/\r\n/g) || []).length;
+  const lfOnly = (content.match(/\n/g) || []).length - crlf;
+  return crlf > lfOnly ? '\r\n' : '\n';
+}
+
+function applyEol(content, eol) {
+  const normalized = content.replace(/\r\n/g, '\n');
+  return eol === '\r\n' ? normalized.replace(/\n/g, '\r\n') : normalized;
 }
 
 function getAiAgentTarget(agent) {
@@ -1456,9 +1924,36 @@ function buildAiAgentShim(targetPath, commandRegistry = []) {
     ? buildCodexCommandTriggerSection(commandRegistry)
     : '';
 
-  const importHint = targetPath === 'CLAUDE.md'
-    ? '\nIf your tool supports Markdown imports, the canonical guide is imported below:\n\n@dflow/specs/shared/AI-AGENT-GUIDE.md\n'
-    : '';
+  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.${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.
+function buildLegacyAgentShimBody(targetPath) {
+  const title = targetPath === '.github/copilot-instructions.md'
+    ? 'GitHub Copilot Repository Instructions'
+    : `${targetPath} - Dflow Project Instructions`;
 
   return `# ${title}
 
@@ -1471,7 +1966,7 @@ Before planning or editing code, read and follow:
 
 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.${commandTriggerHint}${importHint}
+spec locations, and SDD/DDD constraints.
 `;
 }
 
@@ -1554,52 +2049,84 @@ async function buildDflowSkillAdapter() {
   return fs.readFile(sourcePath, 'utf8');
 }
 
+// Project-level skill paths per AI agent. Claude, Codex (the `agents` key,
+// labeled "Codex / Copilot coding agent"), and GitHub Copilot each get the SAME
+// edition-neutral thin skill projected to their own canonical skill path.
+// PROPOSAL-056 generalized this; the Copilot native projection (`.github/skills`)
+// was un-deferred after a spike confirmed Copilot discovers and auto-triggers a
+// skill from its own path with the cross-read `.claude`/`.agents` paths removed.
+// Note: Copilot also cross-reads `.claude/skills` and `.agents/skills`, so a
+// project that selects Copilot alongside Claude/Codex may surface the same
+// `dflow` skill from more than one path. The copies Dflow *generates* are
+// byte-identical (same name, body, and marker), so duplicate generated copies
+// carry identical behavior — but this duplicate-discovery case is not spiked,
+// and a pre-existing non-Dflow skill at a cross-read path is left unchanged by
+// the overwrite guard below and could differ. Remove/rename such a file to
+// avoid a divergent same-name duplicate.
+const SKILL_ADAPTER_TARGETS = {
+  claude: { relativePath: '.claude/skills/dflow/SKILL.md', source: 'generated:claude-skill-adapter' },
+  agents: { relativePath: '.agents/skills/dflow/SKILL.md', source: 'generated:agents-skill-adapter' },
+  copilot: { relativePath: '.github/skills/dflow/SKILL.md', source: 'generated:copilot-skill-adapter' }
+};
+
 async function addSkillAdapterItems(cwd, items, aiAgents, skills, warnings) {
   if (!skills) {
     return;
   }
 
-  if (!aiAgents.includes('claude')) {
+  const skillTargets = aiAgents
+    .filter((agent) => SKILL_ADAPTER_TARGETS[agent])
+    .map((agent) => SKILL_ADAPTER_TARGETS[agent]);
+
+  if (skillTargets.length === 0) {
+    // No skill-capable agent was selected at all. Nothing to project.
     warnings.push(
-      'The --skills flag currently supports Claude Code only; no skill adapter was generated because Claude Code was not a selected target.'
+      'The --skills flag projects a project-level skill for Claude Code, Codex, and GitHub Copilot; no skill adapter was generated because none was a selected target.'
     );
     return;
   }
 
-  const relativePath = '.claude/skills/dflow/SKILL.md';
-  const targetPath = path.join(cwd, relativePath);
-
   // The thin skill is edition-neutral (it only points to the per-edition guide),
   // so there is nothing edition-specific to go stale — re-running just rewrites
   // the same marker-guarded file (idempotent). No LEGACY skill set exists yet
   // (skills are new in PROPOSAL-038); future skill cleanup would extend the same
   // LEGACY_* / addLegacyCommandAdapterCleanupItems marker-fingerprint pattern.
-  let existingContent;
-  try {
-    existingContent = await fs.readFile(targetPath, 'utf8');
-  } catch (error) {
-    if (error.code !== 'ENOENT') {
-      throw error;
+  const skillContent = await buildDflowSkillAdapter();
+
+  for (const target of skillTargets) {
+    const targetPath = path.join(cwd, target.relativePath);
+
+    let existingContent;
+    try {
+      existingContent = await fs.readFile(targetPath, 'utf8');
+    } catch (error) {
+      if (error.code !== 'ENOENT') {
+        throw error;
+      }
+      existingContent = undefined;
     }
-    existingContent = undefined;
-  }
 
-  if (existingContent !== undefined && !existingContent.includes(SKILL_ADAPTER_GENERATED_MARKER)) {
-    warnings.push(
-      'Existing .claude/skills/dflow/SKILL.md is not a Dflow-generated skill; left unchanged. Remove or rename it to let Dflow manage this skill.'
-    );
-    return;
-  }
+    if (existingContent !== undefined && !existingContent.includes(SKILL_ADAPTER_GENERATED_MARKER)) {
+      warnings.push(
+        `Existing ${target.relativePath} is not a Dflow-generated skill; left unchanged. Remove or rename it to let Dflow manage this skill.`
+      );
+      continue;
+    }
 
-  const skillContent = await buildDflowSkillAdapter();
-  items.push({
-    relativePath,
-    source: 'generated:claude-skill-adapter',
-    notes: 'skill adapter, thin skill pointing to AI-AGENT-GUIDE.md',
-    content: skillContent,
-    size: Buffer.byteLength(skillContent, 'utf8'),
-    overwrite: true
-  });
+    // addSkillAdapterItems runs AFTER finalizePlanItems, so these items never pass
+    // through that pass — set `action` explicitly here (the preview table and the
+    // result report read item.action directly). `overwrite: true` keeps the write
+    // phase rewriting an existing marker-stamped skill.
+    items.push({
+      relativePath: target.relativePath,
+      source: target.source,
+      notes: 'skill adapter, thin skill pointing to AI-AGENT-GUIDE.md',
+      content: skillContent,
+      size: Buffer.byteLength(skillContent, 'utf8'),
+      overwrite: true,
+      action: existingContent === undefined ? 'create' : 'update'
+    });
+  }
 }
 
 function buildLegacyCommandAdapterFingerprint(legacy, command) {
@@ -1647,16 +2174,43 @@ function stripCodexTriggerBlock(content) {
   return content.replace(re, '\n');
 }
 
-// An AGENTS.md is a safely-injectable Dflow shim when, after removing any
-// previously-injected trigger block, it matches the shim Dflow itself
-// generates. This covers both a pristine 0.8.0/0.9.0 shim (no marker, normalized
-// exact-template match) and a shim Dflow already injected into (idempotent
-// re-projection). A user-edited shim fails the match and degrades to a snippet.
-// (A future shim could carry its own generated-marker for a cheaper check, but
-// that would require freezing this pre-marker template for back-compat matching;
-// the normalized template match works for both eras without that.)
-function isPristineDflowAgentsShim(existingContent, baseShim) {
-  return normalizeShimForMatch(stripCodexTriggerBlock(existingContent)) === normalizeShimForMatch(baseShim);
+// Removes the pre-Phase-2 Markdown `@import` block that old CLAUDE.md shims
+// appended after the shim body. Operates on already-normalized content (LF, no
+// trailing whitespace, blank runs collapsed, trimmed — see normalizeShimForMatch),
+// so editor-added trailing spaces, CRLF, or an extra blank line in an old file
+// do not defeat the match.
+function stripLegacyImportSuffix(normalizedContent) {
+  return normalizedContent.replace(
+    /\n+If your tool supports Markdown imports, the canonical guide is imported below:\n+@dflow\/specs\/shared\/AI-AGENT-GUIDE\.md$/,
+    ''
+  );
+}
+
+// A CLAUDE.md / AGENTS.md is a safely-injectable Dflow shim when, after removing
+// any previously-injected trigger block, it matches the shim Dflow itself
+// generates. This covers a pristine 0.8.0/0.9.0 shim (no marker, normalized
+// template match) and a shim Dflow already injected into (idempotent
+// re-projection). For CLAUDE.md ONLY, a pre-Phase-2 shim that still carries the
+// legacy `@import` also counts and is regenerated WITHOUT it, so the
+// progressive-disclosure fix reaches existing projects. The import was only ever
+// generated into CLAUDE.md, so scoping the strip there avoids clobbering a
+// user-added import block in a hand-edited AGENTS.md / Copilot shim. A
+// user-edited shim otherwise fails the match and degrades to a snippet.
+function isPristineDflowAgentsShim(existingContent, baseShim, relativePath) {
+  const target = normalizeShimForMatch(baseShim);
+  let existing = normalizeShimForMatch(stripCodexTriggerBlock(existingContent));
+  if (relativePath === 'CLAUDE.md') {
+    existing = stripLegacyImportSuffix(existing);
+  }
+  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));
 }
 
 function buildCodexCommandTriggerSection(commandRegistry) {
@@ -2240,7 +2794,7 @@ async function writeFilePlan(cwd, plan) {
         } catch (error) {
           if (error.code === 'ENOENT') {
             result.skipped.push(item.relativePath);
-            result.warnings.push(`Skipped missing stale adapter: ${item.relativePath}`);
+            result.warnings.push(`Skipped missing stale file: ${item.relativePath}`);
             continue;
           }
           throw error;
@@ -2248,14 +2802,14 @@ async function writeFilePlan(cwd, plan) {
 
         if (!stats.isFile()) {
           result.skipped.push(item.relativePath);
-          result.warnings.push(`Skipped stale adapter removal because target is not a file: ${item.relativePath}`);
+          result.warnings.push(`Skipped stale removal because target is not a file: ${item.relativePath}`);
           continue;
         }
 
         const currentContent = await fs.readFile(targetPath, 'utf8');
         if (normalizeCommandAdapterFingerprint(currentContent) !== normalizeCommandAdapterFingerprint(item.expectedContent || '')) {
           result.skipped.push(item.relativePath);
-          result.warnings.push(`Skipped stale adapter removal because content changed after preview: ${item.relativePath}`);
+          result.warnings.push(`Skipped stale removal because content changed after preview: ${item.relativePath}`);
           continue;
         }
 
@@ -2264,6 +2818,45 @@ async function writeFilePlan(cwd, plan) {
         continue;
       }
 
+      // PROPOSAL-054: a user-owned root agent file edit (append / replace / regenerate).
+      // Re-read and require RAW-byte equality with the previewed content before writing,
+      // so a file the user changed (or deleted, or replaced with a non-file) between the
+      // preview and the write is never clobbered — skip + warn + ask them to re-run. Raw
+      // equality is intentionally stricter than the normalized compare used for stale
+      // removal: any whitespace / EOL change counts as "changed after preview".
+      if (item.rootInject) {
+        let stats;
+        try {
+          stats = await fs.stat(targetPath);
+        } catch (error) {
+          if (error.code === 'ENOENT') {
+            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;
+          }
+          throw error;
+        }
+        if (!stats.isFile()) {
+          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) {
+          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;
+        }
+        if (item.content === currentRaw) {
+          result.skipped.push(item.relativePath);
+          continue;
+        }
+        await fs.mkdir(path.dirname(targetPath), { recursive: true });
+        await fs.writeFile(targetPath, item.content);
+        result.updated.push(item.relativePath);
+        continue;
+      }
+
       if (await pathExists(targetPath)) {
         if (item.overwrite) {
           await fs.mkdir(path.dirname(targetPath), { recursive: true });
@@ -2273,7 +2866,12 @@ async function writeFilePlan(cwd, plan) {
         }
 
         result.skipped.push(item.relativePath);
-        result.warnings.push(`Skipped existing target: ${item.relativePath}`);
+        // PROPOSAL-054: an intentional skip (an already-configured agent file, or an
+        // already-current Dflow block) is expected, not a problem — don't emit the
+        // generic "skipped existing target" warning for it.
+        if (!item.intentionalSkip) {
+          result.warnings.push(`Skipped existing target: ${item.relativePath}`);
+        }
         if (item.relativePath === 'dflow/specs/shared/_conventions.md') {
           result.warnings.push(
             'Prose language was not written because dflow/specs/shared/_conventions.md already exists. Ensure it contains exactly one ## Prose Language section before running prose-generating flows.'
@@ -2282,6 +2880,15 @@ async function writeFilePlan(cwd, plan) {
         continue;
       }
 
+      // PROPOSAL-054: a plan item previewed as "skip" (an already-configured agent
+      // file, or an already-current Dflow block) must never write. If its target
+      // vanished between preview and write, do nothing — do NOT silently create a
+      // file the preview said would be left alone.
+      if (item.action === 'skip') {
+        result.skipped.push(item.relativePath);
+        continue;
+      }
+
       await fs.mkdir(path.dirname(targetPath), { recursive: true });
       await fs.writeFile(targetPath, item.content, { flag: 'wx' });
 
@@ -2396,20 +3003,25 @@ Recommended next steps:
 `);
 }
 
-function printConfigureAgentsNextSteps(stdout, commandAdapters = false) {
+function printConfigureAgentsNextSteps(stdout, commandAdapters = false, snippetFallback = 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'
     : '';
 
+  // PROPOSAL-054: Dflow now auto-injects the marker-delimited block into existing
+  // agent files, so the merge-snippet step is shown only when a genuine-conflict
+  // fallback snippet was actually written this run.
+  const snippetStep = snippetFallback
+    ? '- 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'
+    : '';
+
   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.
-- If a merge snippet was created, review it and merge the pointer into the existing tool instruction file.
-${commandAdapterStep}
-`);
+${snippetStep}${commandAdapterStep}`);
 }
 
 function printList(stdout, values) {
@@ -2508,9 +3120,8 @@ async function runDoctor(options = {}) {
     }
 
     const findings = [];
-    await checkLegacyRootSpecsDir(cwd, findings);
-    await checkLegacySharedDir(cwd, findings);
     await checkConventionsDflowVersion(cwd, findings);
+    await checkOrphanedWorkflowBundleFiles(cwd, findings);
 
     printDoctorReport(stdout, cwd, findings);
     return 0;
@@ -2524,36 +3135,6 @@ async function runDoctor(options = {}) {
   }
 }
 
-async function checkLegacyRootSpecsDir(cwd, findings) {
-  const legacyPath = path.join(cwd, 'specs');
-  if ((await pathExists(legacyPath)) && (await containsInitializedContent(legacyPath))) {
-    findings.push({
-      level: 'warn',
-      title: 'Legacy specs/ directory at project root',
-      detail: 'V1 layout uses dflow/specs/ instead. The CLI does not modify root specs/.',
-      action: 'See docs/migrating-to-dflow-v1.md (Step 1) for the manual migration steps.'
-    });
-  }
-}
-
-async function checkLegacySharedDir(cwd, findings) {
-  const candidates = [
-    path.join(cwd, 'dflow', 'specs', '_共用'),
-    path.join(cwd, 'specs', '_共用')
-  ];
-  for (const candidate of candidates) {
-    if (await pathExists(candidate)) {
-      const rel = normalizePath(path.relative(cwd, candidate));
-      findings.push({
-        level: 'warn',
-        title: `Legacy ${rel}/ directory`,
-        detail: 'V1 layout uses shared/ (canonical English directory name).',
-        action: 'See docs/migrating-to-dflow-v1.md (Step 2) for the rename steps.'
-      });
-    }
-  }
-}
-
 async function checkConventionsDflowVersion(cwd, findings) {
   const conventionsPath = path.join(cwd, 'dflow', 'specs', 'shared', '_conventions.md');
   if (!(await pathExists(conventionsPath))) return;
@@ -2568,12 +3149,75 @@ async function checkConventionsDflowVersion(cwd, findings) {
   }
 }
 
+// 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
+// project was projected from a pre-release / non-registry source whose manifest
+// later forgot it. configure-agents only auto-removes files the manifest still
+// lists; a manifest-orphaned file (the manifest no longer lists it) must be
+// 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;
+
+  const edition = await inferProjectBundleEdition(cwd);
+  if (!edition) return;
+
+  let sourceFiles;
+  try {
+    sourceFiles = await listBundleSourceFiles(edition);
+  } catch {
+    return;
+  }
+  const sourceRel = new Set(sourceFiles.map((f) => `${WORKFLOW_BUNDLE_DEST}/${f.sourceRel}`));
+
+  for (const dir of ['references', 'templates']) {
+    const projectedDir = path.join(bundleDir, dir);
+    let entries;
+    try {
+      entries = await fs.readdir(projectedDir);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const rel = `${WORKFLOW_BUNDLE_DEST}/${dir}/${entry}`;
+      if (sourceRel.has(rel)) continue;
+      const abs = path.join(projectedDir, entry);
+      const fileStat = await fs.stat(abs).catch(() => null);
+      if (!fileStat || !fileStat.isFile()) continue;
+      const content = await fs.readFile(abs, 'utf8').catch(() => '');
+      if (!content.includes(WORKFLOW_BUNDLE_GENERATED_MARKER)) continue;
+      findings.push({
+        level: 'info',
+        title: `Retired workflow bundle file: ${rel}`,
+        detail: 'A Dflow-generated bundle file that is no longer part of the package source for this edition (a retired file left behind).',
+        action: 'Delete it manually to remove it. (Re-running `dflow configure-agents` only auto-removes files the manifest still lists; a manifest-orphaned file must be deleted by hand.)'
+      });
+    }
+  }
+}
+
+// Infers the project's bundle edition for read-only checks: prefer the manifest
+// (authoritative for what was projected), fall back to project structure.
+async function inferProjectBundleEdition(cwd) {
+  const manifestResult = await readCurrentBundleManifest(cwd);
+  if (
+    manifestResult.kind === 'ok' &&
+    (manifestResult.manifest.edition === 'greenfield' || manifestResult.manifest.edition === 'brownfield')
+  ) {
+    return manifestResult.manifest.edition;
+  }
+  return inferExistingEdition(cwd);
+}
+
 function printDoctorReport(stdout, cwd, findings) {
   stdout.write(`Dflow Doctor ${pkg.version}\n`);
   stdout.write(`Project: ${cwd}\n\n`);
 
   if (findings.length === 0) {
-    stdout.write('All checks passed. No legacy artifacts detected.\n');
+    stdout.write('All checks passed. No Dflow health findings detected.\n');
     return;
   }
 
@@ -2595,5 +3239,14 @@ module.exports = {
   runInit,
   validateProseLanguage,
   ensureProseLanguageSection,
-  buildFilePlan
+  buildFilePlan,
+  // Exported for tests: the write phase enforces the PROPOSAL-054 raw-equality guard
+  // for user-owned root agent files (changed-after-preview -> skip), which cannot be
+  // exercised through the CLI because preview and write happen in one process.
+  writeFilePlan,
+  // Exported for tests (PROPOSAL-064): pure bundle-source guards, unit-tested on
+  // synthetic descriptor lists without touching the packaged templates/ tree.
+  assertNoBundleCollision,
+  assertEditionBundleComplete,
+  assertCommonBundleComplete
 };