dflow-sdd-ddd 0.7.0 → 0.9.0

package/lib/init.js

@@ -12,6 +12,12 @@ const COMMAND_REGISTRY_START = '<!-- dflow-command-registry:start -->';
 const COMMAND_REGISTRY_END = '<!-- dflow-command-registry:end -->';
 const COMMAND_ADAPTER_GENERATED_MARKER = '<!-- dflow-generated: command-adapter -->';
 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 -->';
+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';
 const EXPECTED_COMMAND_IDS = [
   'new-feature',
   'modify-existing',
@@ -106,16 +112,42 @@ const OPTIONAL_FILE_OPTIONS = [
     key: 'overview',
     label: '_overview.md - system overview',
     aliases: ['overview', '_overview.md']
+  }
+];
+
+// Git policy is a mandatory team choice (PROPOSAL-047): both options use feature
+// branches; the choice selects the finish-stage merge guidance and drives the
+// runtime branch gates / commit checkpoints.
+const GIT_POLICY_OPTIONS = [
+  {
+    key: 'gitflow',
+    label: 'Git Flow - long-lived develop/release branches',
+    aliases: ['gitflow', 'git flow', 'flow']
+  },
+  {
+    key: 'trunk',
+    label: 'Trunk / GitHub Flow - short-lived feature branches (lightest)',
+    aliases: ['trunk', 'trunk-based', 'github flow', 'githubflow']
+  }
+];
+
+// How AI-made commits are marked (PROPOSAL-047). Chosen once at init; the
+// runtime does not re-ask. None is the default.
+const AI_COMMIT_MARKER_OPTIONS = [
+  {
+    key: 'none',
+    label: 'None - AI commits look like any other commit',
+    aliases: ['none', 'off', 'no']
   },
   {
-    key: 'git-trunk',
-    label: 'Git principles - trunk-based',
-    aliases: ['git principles - trunk-based', 'trunk', 'trunk-based']
+    key: 'co-authored-by',
+    label: 'Co-Authored-By trailer (dflow-ai) - filterable / auditable',
+    aliases: ['co-authored-by', 'co-author', 'trailer', 'coauthored']
   },
   {
-    key: 'git-flow',
-    label: 'Git principles - Git Flow',
-    aliases: ['git principles - git flow', 'git flow', 'gitflow']
+    key: 'prefix',
+    label: '[ai-assisted] commit-message prefix - visible at a glance',
+    aliases: ['prefix', 'ai-assisted', '[ai-assisted]']
   }
 ];
 
@@ -203,8 +235,8 @@ async function runInit(options = {}) {
 
     const detection = await detectProjectSignals(cwd);
     const answers = await promptForAnswers(rl, stdout, stderr, detection);
-    const warnings = [...preflight.warnings, ...buildDetectionWarnings(answers, detection)];
     const plan = await buildFilePlan(cwd, answers);
+    const warnings = [...preflight.warnings, ...buildDetectionWarnings(answers, detection), ...(plan.bundleWarnings || [])];
 
     renderPreview(stdout, plan, warnings);
     const confirmed = await askConfirmation(rl, 'Create these files? (y/N) ');
@@ -277,7 +309,8 @@ async function runConfigureAgents(options = {}) {
     await assertDflowInitialized(cwd);
 
     const projectContext = await inferProjectContext(cwd, rl, stdout, stderr);
-    const aiAgents = await askAiAgents(rl, stdout, stderr);
+    const detectedAgents = await detectConfiguredAgents(cwd);
+    const aiAgents = await askAiAgents(rl, stdout, stderr, detectedAgents);
 
     if (aiAgents.length === 0) {
       throw new UserAbort('No AI agents selected. Nothing changed.');
@@ -488,10 +521,32 @@ async function detectProjectSignals(cwd) {
   return {
     hasSourceTree: hasSourceTree || relNames.has('src'),
     trackHint,
-    stackHints
+    stackHints,
+    configuredAgents: await detectConfiguredAgents(cwd)
   };
 }
 
+async function detectConfiguredAgents(cwd) {
+  // Surface agents this project already has configured so init / configure-agents
+  // 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'))) {
+    detected.push('agents');
+  }
+  if (
+    (await pathExists(path.join(cwd, 'CLAUDE.md'))) ||
+    (await pathExists(path.join(cwd, '.claude/commands/dflow'))) ||
+    (await pathExists(path.join(cwd, '.claude/skills/dflow')))
+  ) {
+    detected.push('claude');
+  }
+  if (await pathExists(path.join(cwd, '.github/copilot-instructions.md'))) {
+    detected.push('copilot');
+  }
+  return detected;
+}
+
 async function collectProjectFiles(cwd, maxDepth, maxFiles) {
   const results = [];
   const ignored = new Set(['.git', 'node_modules', 'bin', 'obj', 'dflow']);
@@ -535,8 +590,8 @@ async function collectProjectFiles(cwd, maxDepth, maxFiles) {
 function buildDetectionWarnings(answers, detection) {
   const warnings = [];
 
-  if (answers.projectType === 'greenfield' && detection.hasSourceTree) {
-    warnings.push('Warning: source-tree signals already exist, but project type is Greenfield. Continuing with your selected project type.');
+  if (answers.projectType === 'greenfield' && detection.hasSourceTree && !detection.trackHint) {
+    warnings.push('Note: existing source files were detected (e.g. a src/ directory or a build manifest). This is expected if you just scaffolded a fresh project — Dflow will continue as Greenfield. If this is actually an existing codebase, consider re-running and selecting Brownfield.');
   }
 
   if (detection.trackHint && answers.projectType !== detection.trackHint) {
@@ -585,8 +640,22 @@ async function promptForAnswers(rl, stdout, stderr, detection) {
     proseLanguage = await askCustomProseLanguage(rl, stderr);
   }
 
+  const gitPolicy = await askSelect(rl, stdout, stderr, {
+    id: 'Q5',
+    question: 'Which Git policy does the team follow? (drives branch gates and finish-stage merge guidance)',
+    options: GIT_POLICY_OPTIONS,
+    defaultKey: null
+  });
+
+  const aiCommitMarker = await askSelect(rl, stdout, stderr, {
+    id: 'Q6',
+    question: 'How should AI-made commits be marked? (the AI offers to commit at checkpoints; you can always decline)',
+    options: AI_COMMIT_MARKER_OPTIONS,
+    defaultKey: 'none'
+  });
+
   const optionalFiles = await askOptionalFiles(rl, stdout, stderr);
-  const aiAgents = await askAiAgents(rl, stdout, stderr);
+  const aiAgents = await askAiAgents(rl, stdout, stderr, detection.configuredAgents || []);
 
   return {
     projectType,
@@ -594,6 +663,8 @@ async function promptForAnswers(rl, stdout, stderr, detection) {
     techStackSummary,
     migrationContext,
     proseLanguage,
+    gitPolicy,
+    aiCommitMarker,
     optionalFiles,
     aiAgents
   };
@@ -618,10 +689,26 @@ async function inferProjectContext(cwd, rl, stdout, stderr) {
     techStackSummary: await inferTechStackSummary(cwd),
     migrationContext: await inferMigrationContext(cwd),
     proseLanguage: await inferProseLanguage(cwd),
+    gitPolicy: await inferGitPolicy(cwd),
+    aiCommitMarker: await inferAiCommitMarker(cwd),
     optionalFiles: []
   };
 }
 
+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;
+}
+
+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;
+}
+
 async function inferExistingEdition(cwd) {
   if (await pathExists(path.join(cwd, 'dflow/specs/architecture/tech-debt.md'))) {
     return 'greenfield';
@@ -740,48 +827,44 @@ async function askOptionalFiles(rl, stdout, stderr) {
   while (true) {
     stdout.write('\nWhich optional starter files should Dflow seed?\n');
     OPTIONAL_FILE_OPTIONS.forEach((option, index) => {
-      const defaultMarker = option.key === 'overview' || option.key === 'git-trunk' ? ' (recommended)' : '';
+      const defaultMarker = option.key === 'overview' ? ' (recommended)' : '';
       stdout.write(`  ${index + 1}. ${option.label}${defaultMarker}\n`);
     });
 
-    const answer = await askLine(rl, 'Enter comma-separated choices, "none", or press Enter for recommended [1,2]: ');
-    const parsed = parseMultiselectAnswer(answer, OPTIONAL_FILE_OPTIONS, ['overview', 'git-trunk']);
+    const answer = await askLine(rl, 'Enter comma-separated choices, "none", or press Enter for recommended [1]: ');
+    const parsed = parseMultiselectAnswer(answer, OPTIONAL_FILE_OPTIONS, ['overview']);
 
     if (!parsed.valid) {
       failedAttempts += 1;
       if (failedAttempts >= 3) {
-        throw new InitError('Too many invalid attempts for Q5. Dflow init aborted.');
+        throw new InitError('Too many invalid attempts for Q7. Dflow init aborted.');
       }
       stderr.write(`${parsed.message} (${3 - failedAttempts} attempts left)\n`);
       continue;
     }
 
-    if (parsed.values.includes('git-trunk') && parsed.values.includes('git-flow')) {
-      const keepBoth = await askConfirmation(
-        rl,
-        'You selected both Git principles templates. Most projects choose one. Keep both? (y/N) '
-      );
-      if (!keepBoth) {
-        failedAttempts = 0;
-        continue;
-      }
-    }
-
     return parsed.values;
   }
 }
 
-async function askAiAgents(rl, stdout, stderr) {
+async function askAiAgents(rl, stdout, stderr, defaultKeys = []) {
   let failedAttempts = 0;
+  const validDefaults = AI_AGENT_OPTIONS
+    .filter((option) => defaultKeys.includes(option.key))
+    .map((option) => option.key);
 
   while (true) {
     stdout.write('\nWhich AI coding agents should Dflow configure?\n');
     AI_AGENT_OPTIONS.forEach((option, index) => {
-      stdout.write(`  ${index + 1}. ${option.label}\n`);
+      const marker = validDefaults.includes(option.key) ? '  (currently configured)' : '';
+      stdout.write(`  ${index + 1}. ${option.label}${marker}\n`);
     });
 
-    const answer = await askLine(rl, 'Enter comma-separated choices or "none" (default: none): ');
-    const parsed = parseMultiselectAnswer(answer || 'none', AI_AGENT_OPTIONS, []);
+    const defaultHint = validDefaults.length > 0
+      ? validDefaults.map((key) => AI_AGENT_OPTIONS.findIndex((option) => option.key === key) + 1).join(',')
+      : 'none';
+    const answer = await askLine(rl, `Enter comma-separated choices or "none" (default: ${defaultHint}): `);
+    const parsed = parseMultiselectAnswer(answer, AI_AGENT_OPTIONS, validDefaults);
 
     if (!parsed.valid) {
       failedAttempts += 1;
@@ -963,6 +1046,7 @@ async function buildFilePlan(cwd, answers) {
     content = substitutePlaceholders(content, substitution);
     if (options.injectProseLanguage) {
       content = ensureProseLanguageSection(content, answers.proseLanguage);
+      content = ensureConventionPolicySections(content, answers);
     }
     items.push({
       relativePath,
@@ -996,11 +1080,13 @@ async function buildFilePlan(cwd, answers) {
   if (answers.optionalFiles.includes('overview')) {
     await addTemplate('dflow/specs/shared/_overview.md', 'scaffolding/_overview.md', 'selected');
   }
-  if (answers.optionalFiles.includes('git-trunk')) {
-    await addTemplate('dflow/specs/shared/Git-principles-trunk.md', 'scaffolding/Git-principles-trunk.md', 'selected');
-  }
-  if (answers.optionalFiles.includes('git-flow')) {
-    await addTemplate('dflow/specs/shared/Git-principles-gitflow.md', 'scaffolding/Git-principles-gitflow.md', 'selected');
+
+  // PROPOSAL-047: the selected Git policy is mandatory — always project exactly
+  // the matching Git-principles file so the runtime branch gates have a policy.
+  if (answers.gitPolicy === 'gitflow') {
+    await addTemplate('dflow/specs/shared/Git-principles-gitflow.md', 'scaffolding/Git-principles-gitflow.md', 'mandatory, selected Git policy');
+  } else {
+    await addTemplate('dflow/specs/shared/Git-principles-trunk.md', 'scaffolding/Git-principles-trunk.md', 'mandatory, selected Git policy');
   }
 
   if (answers.aiAgents.length > 0) {
@@ -1012,9 +1098,14 @@ async function buildFilePlan(cwd, answers) {
 
   await finalizePlanItems(cwd, items);
 
+  // Always project the workflow bundle (required for /dflow:* workflows to be reachable).
+  const bundleWarnings = [];
+  await addWorkflowBundleItems(cwd, items, bundleWarnings, answers.edition);
+
   return {
     items,
     deferred: buildDeferredItems(answers.edition),
+    bundleWarnings,
     unresolvedInitPlaceholders: Array.from(substitution.entries())
       .filter(([placeholder, value]) => placeholder === value)
       .map(([placeholder]) => placeholder)
@@ -1041,7 +1132,7 @@ async function buildConfigureAgentsPlan(cwd, answers) {
   const commandRegistry = answers.commandAdapters ? parseDflowCommandRegistry(content) : [];
 
   for (const agent of answers.aiAgents) {
-    await addAiAgentShim(cwd, items, agent, substitution, { commandRegistry });
+    await addAiAgentShim(cwd, items, agent, substitution, { commandRegistry, warnings });
   }
 
   if (answers.commandAdapters) {
@@ -1056,6 +1147,14 @@ async function buildConfigureAgentsPlan(cwd, answers) {
 
   await addSkillAdapterItems(cwd, items, answers.aiAgents, answers.skills, 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
+  // is idempotent: it skips fresh bundle files, updates Dflow-generated ones, and warns
+  // (without overwriting) on user-modified bundle files.
+  const bundleWarnings = [];
+  await addWorkflowBundleItems(cwd, items, bundleWarnings, answers.edition);
+  warnings.push(...bundleWarnings);
+
   return {
     items,
     deferred: [],
@@ -1078,21 +1177,231 @@ async function finalizePlanItems(cwd, items) {
   }
 }
 
+async function listBundleSourceFiles(edition) {
+  const bundleDirs = ['references', 'templates'];
+  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;
+      }
+      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 });
+      }
+    }
+  }
+
+  return files;
+}
+
+async function readCurrentBundleManifest(cwd) {
+  const manifestPath = path.join(cwd, WORKFLOW_BUNDLE_MANIFEST_PATH);
+  try {
+    const raw = await fs.readFile(manifestPath, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function buildBundleManifest(edition, version, files) {
+  return {
+    edition,
+    version,
+    generatedBy: 'dflow-sdd-ddd',
+    files: files.map((f) => `${WORKFLOW_BUNDLE_DEST}/${f.sourceRel}`)
+  };
+}
+
+function injectBundleMarker(content) {
+  return `${WORKFLOW_BUNDLE_GENERATED_MARKER}\n\n${content}`;
+}
+
+async function addWorkflowBundleItems(cwd, items, warnings, edition) {
+  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;
+
+  // 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) {
+      const staleAbsPath = path.join(cwd, staleRelPath);
+      let staleExists = false;
+      try {
+        await fs.stat(staleAbsPath);
+        staleExists = true;
+      } catch {
+        staleExists = false;
+      }
+      if (!staleExists) {
+        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}`
+        );
+        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
+        });
+      }
+    }
+  }
+
+  // Build items for current edition bundle files.
+  for (const { sourceRel } of bundleFiles) {
+    const relativePath = `${WORKFLOW_BUNDLE_DEST}/${sourceRel}`;
+    const absolutePath = path.join(cwd, relativePath);
+    const sourceContent = await readPackagedBundleFile(edition, sourceRel);
+    const content = injectBundleMarker(sourceContent);
+
+    let action;
+    let notes = 'workflow bundle';
+    const targetExists = await pathExists(absolutePath);
+
+    if (targetExists) {
+      const existingContent = await fs.readFile(absolutePath, 'utf8');
+      if (existingContent.includes(WORKFLOW_BUNDLE_GENERATED_MARKER)) {
+        action = 'update';
+      } else {
+        action = 'skip';
+        notes = 'workflow bundle, user-modified — skipped; remove or rename to let Dflow manage';
+        warnings.push(
+          `Existing ${relativePath} is not a Dflow-generated bundle file; left unchanged. Remove or rename it to let Dflow manage this file.`
+        );
+      }
+    } else {
+      action = 'create';
+    }
+
+    items.push({
+      relativePath,
+      source: `packaged-bundle:${edition}/${sourceRel}`,
+      notes,
+      content,
+      action,
+      overwrite: action === 'update',
+      size: Buffer.byteLength(content, 'utf8')
+    });
+  }
+
+  // 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));
+
+  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);
+  const normalizedFilePath = path.resolve(filePath);
+
+  if (!normalizedFilePath.startsWith(`${normalizedRoot}${path.sep}`)) {
+    throw new InitError(`Internal error: packaged bundle file not found: templates/${edition}/${sourceRel}`);
+  }
+
+  let buffer;
+  try {
+    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: cannot read packaged bundle file: templates/${edition}/${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}`);
+  }
+}
+
 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 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;
+    }
+    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.`
+      );
+    }
+    items.push({
+      relativePath: 'dflow/specs/shared/AGENTS-md-command-adapters-snippet.md',
+      source,
+      notes: `selected, ${target.relativePath} was modified after Dflow generated it; merge this command trigger snippet manually`,
+      content,
+      overwrite: true
+    });
+    return;
+  }
+
   const relativePath = codexCommandAdapterSnippet
-    ? (targetConfigured ? 'dflow/specs/shared/AGENTS-md-command-adapters-snippet.md' : target.snippetPath)
+    ? target.snippetPath
     : (targetExists && !targetConfigured ? target.snippetPath : target.relativePath);
-  const content = substitutePlaceholders(buildAiAgentShim(target.relativePath, options.commandRegistry), substitution);
   let notes = 'selected, tool-specific shim';
-  if (codexCommandAdapterSnippet && targetConfigured) {
-    notes = `selected, ${target.relativePath} already points to AI-AGENT-GUIDE.md; merge this command trigger snippet manually`;
-  } else if (codexCommandAdapterSnippet) {
+  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`;
@@ -1102,7 +1411,7 @@ async function addAiAgentShim(cwd, items, agent, substitution, options = {}) {
 
   items.push({
     relativePath,
-    source: `generated:${agent}-shim`,
+    source,
     notes,
     content,
     overwrite: codexCommandAdapterSnippet
@@ -1157,10 +1466,11 @@ This project uses Dflow for spec-first AI-assisted development.
 
 Before planning or editing code, read and follow:
 
-- \`dflow/specs/shared/AI-AGENT-GUIDE.md\`
+- \`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.
 
-Keep tool-specific instruction files small. The Dflow guide above is the
-single source of truth for project workflow rules, slash-command behavior,
+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}
 `;
 }
@@ -1235,39 +1545,13 @@ async function addLegacyCommandAdapterCleanupItems(cwd, items, aiAgents, warning
   }
 }
 
-function buildDflowSkillAdapter() {
-  return `---
-name: dflow
-description: >
-  Dflow SDD/DDD workflow guardian for this project. PRIMARY: the canonical
-  /dflow:* commands (/dflow:new-feature, /dflow:modify-existing, /dflow:bug-fix,
-  /dflow:new-phase, /dflow:finish-feature, /dflow:pr-review, /dflow:verify,
-  /dflow:report-dflow-feedback, /dflow:status, /dflow:next, /dflow:cancel).
-  SECONDARY (auto-trigger safety net) — engage ONLY for: adding or changing
-  product/domain behavior, new requirements, a feature or bug-fix workflow, or
-  spec-impacting architecture/domain-model decisions. Do NOT engage for pure
-  refactors, infrastructure chores, formatting, or general code questions.
-  When engaged by natural language, DO NOT auto-enter a workflow: judge the
-  intent, suggest the matching /dflow: command, and wait for confirmation.
----
-
-${SKILL_ADAPTER_GENERATED_MARKER}
-
-# Dflow SDD/DDD Workflow Guardian
-
-This project uses Dflow for spec-first AI-assisted development. The canonical
-workflow contract, command registry, spec locations, and SDD/DDD rules live in:
-
-- \`dflow/specs/shared/AI-AGENT-GUIDE.md\`
-
-When this skill engages, read that guide and follow the matching \`/dflow:\`
-workflow or control command defined there. Do not duplicate or invent workflow
-steps here — the guide is the single source of truth.
-
-If engaged by natural language (not an explicit \`/dflow:\` command): identify
-which \`/dflow:\` command fits, suggest it, and wait for the developer to confirm
-before entering any workflow.
-`;
+// Edition-agnostic thin shell: a single canonical source at
+// templates/common/skill/SKILL.md (PROPOSAL-041 C1). Returns the file
+// verbatim — frontmatter, marker, and body all live in the source file so
+// the skill content can be edited without touching JS.
+async function buildDflowSkillAdapter() {
+  const sourcePath = path.join(TEMPLATE_ROOT, COMMON_SKILL_SOURCE_REL);
+  return fs.readFile(sourcePath, 'utf8');
 }
 
 async function addSkillAdapterItems(cwd, items, aiAgents, skills, warnings) {
@@ -1307,11 +1591,13 @@ async function addSkillAdapterItems(cwd, items, aiAgents, skills, warnings) {
     return;
   }
 
+  const skillContent = await buildDflowSkillAdapter();
   items.push({
     relativePath,
     source: 'generated:claude-skill-adapter',
     notes: 'skill adapter, thin skill pointing to AI-AGENT-GUIDE.md',
-    content: buildDflowSkillAdapter(),
+    content: skillContent,
+    size: Buffer.byteLength(skillContent, 'utf8'),
     overwrite: true
   });
 }
@@ -1343,6 +1629,36 @@ function normalizeCommandAdapterFingerprint(content) {
   return String(content).replace(/\r\n/g, '\n');
 }
 
+function normalizeShimForMatch(content) {
+  return String(content)
+    .replace(/\r\n/g, '\n')
+    .split('\n')
+    .map((line) => line.replace(/[ \t]+$/, ''))
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+function stripCodexTriggerBlock(content) {
+  const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(
+    `\\n*${escape(CODEX_TRIGGER_SECTION_START)}[\\s\\S]*?${escape(CODEX_TRIGGER_SECTION_END)}\\n*`
+  );
+  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);
+}
+
 function buildCodexCommandTriggerSection(commandRegistry) {
   const triggers = commandRegistry
     .map((command) => {
@@ -1353,6 +1669,8 @@ function buildCodexCommandTriggerSection(commandRegistry) {
 
   return `
 
+${CODEX_TRIGGER_SECTION_START}
+
 ## Dflow Text Triggers
 
 Codex does not install Dflow command files. When the developer asks for a
@@ -1367,6 +1685,8 @@ and execute it.
 Recognized canonical triggers:
 
 ${triggers}
+
+${CODEX_TRIGGER_SECTION_END}
 `;
 }
 
@@ -1381,7 +1701,8 @@ ${COMMAND_ADAPTER_GENERATED_MARKER}
 
 Execute the canonical \`${command.label}\` Dflow workflow or control command.
 
-Definition: \`dflow/specs/shared/AI-AGENT-GUIDE.md\`
+Registry and rules: \`dflow/specs/shared/AI-AGENT-GUIDE.md\`
+Workflow steps: \`dflow/specs/shared/dflow-workflows/\`
 
 ${argHint}
 `;
@@ -1555,8 +1876,7 @@ const PLACEHOLDER_ALIASES = {
 
 function buildSubstitutionMap(cwd, answers) {
   const extracted = extractTechStackPlaceholders(answers.techStackSummary);
-  const gitSelection = answers.optionalFiles.filter((key) => key === 'git-trunk' || key === 'git-flow');
-  const gitStyle = gitSelection.length === 1 ? (gitSelection[0] === 'git-trunk' ? 'trunk' : 'gitflow') : null;
+  const gitStyle = answers.gitPolicy === 'gitflow' ? 'gitflow' : (answers.gitPolicy === 'trunk' ? 'trunk' : null);
   const systemName = path.basename(cwd);
 
   const map = new Map([
@@ -1788,6 +2108,70 @@ function stripProseLanguageSections(content) {
   return kept.join('\n');
 }
 
+function stripNamedSections(content, headings) {
+  const set = new Set(headings.map((heading) => `## ${heading}`));
+  const kept = [];
+  let skipping = false;
+
+  for (const line of content.split(/\r?\n/)) {
+    if (set.has(line.trim())) {
+      skipping = true;
+      continue;
+    }
+    if (skipping && /^## /.test(line)) {
+      skipping = false;
+    }
+    if (!skipping) {
+      kept.push(line);
+    }
+  }
+
+  return kept.join('\n');
+}
+
+function buildGitPolicySection(gitPolicy) {
+  const policy = gitPolicy === 'gitflow' ? 'gitflow' : 'trunk';
+  return `## Git Policy
+
+Selected Git policy: \`${policy}\`
+
+Dflow runtime branch gates and finish-feature guidance follow this policy. Both
+policies use feature branches; the policy selects the finish-stage merge
+guidance — \`gitflow\` introduces merge-commit / release+develop flow, while
+\`trunk\` (GitHub Flow) favors squash or fast-forward back to the main branch
+with small, frequent merges.`;
+}
+
+function buildAiCommitPolicySection(aiCommitMarker) {
+  const marker = ['none', 'co-authored-by', 'prefix'].includes(aiCommitMarker) ? aiCommitMarker : 'none';
+  return `## AI Commit Policy
+
+AI commit marker: \`${marker}\`
+
+At lifecycle checkpoints the AI may offer to commit using your Git identity; you
+can always decline (Y / N). Completed and skipped checkpoints are recorded in
+each feature's Checkpoint Log. Marker modes:
+
+- \`none\`: AI-made commits carry no extra marker.
+- \`co-authored-by\`: append a \`Co-Authored-By: dflow-ai <noreply@dflow.local>\`
+  trailer (teams may customize the name/email).
+- \`prefix\`: prefix the commit subject with \`[ai-assisted]\`.`;
+}
+
+function ensureConventionPolicySections(content, answers) {
+  const stripped = stripNamedSections(content, ['Git Policy', 'AI Commit Policy']).replace(/\n{3,}/g, '\n\n');
+  const sections = `${buildGitPolicySection(answers.gitPolicy)}\n\n${buildAiCommitPolicySection(answers.aiCommitMarker)}`;
+  const markerMatch = stripped.match(/^## Filling the Templates/m);
+
+  if (markerMatch && typeof markerMatch.index === 'number') {
+    const before = stripped.slice(0, markerMatch.index).replace(/\s*$/, '\n\n');
+    const after = stripped.slice(markerMatch.index).replace(/^\s*/, '');
+    return `${before}${sections}\n\n${after}`;
+  }
+
+  return `${stripped.replace(/\s*$/, '\n\n')}${sections}\n`;
+}
+
 function buildProseLanguageSection(proseLanguage) {
   return `## Prose Language
 
@@ -1952,14 +2336,17 @@ function collectUnresolvedPlaceholderWarnings(plan, createdPaths) {
     return [];
   }
 
+  const placeholderFiles = new Set();
   for (const item of plan.items) {
     if (!createdSet.has(item.relativePath)) {
       continue;
     }
     const matches = item.content.match(/{[^{}\n]+}/g) || [];
-    matches
-      .filter((match) => unresolvedInitPlaceholders.has(match))
-      .forEach((match) => placeholders.add(match));
+    const hits = matches.filter((match) => unresolvedInitPlaceholders.has(match));
+    hits.forEach((match) => placeholders.add(match));
+    if (hits.length > 0) {
+      placeholderFiles.add(item.relativePath);
+    }
   }
 
   if (placeholders.size === 0) {
@@ -1969,7 +2356,10 @@ function collectUnresolvedPlaceholderWarnings(plan, createdPaths) {
   const sorted = Array.from(placeholders).sort();
   const shown = sorted.slice(0, 25).join(', ');
   const suffix = sorted.length > 25 ? `, and ${sorted.length - 25} more` : '';
-  return [`Unresolved placeholders remain for later SDD workflows: ${shown}${suffix}.`];
+  const files = Array.from(placeholderFiles).sort();
+  const filesShown = files.slice(0, 10).join(', ');
+  const filesSuffix = files.length > 10 ? `, and ${files.length - 10} more` : '';
+  return [`Unresolved placeholders remain for later SDD workflows: ${shown}${suffix}. Fill them in (or leave for the workflow to resolve) in: ${filesShown}${filesSuffix}.`];
 }
 
 function printResultReport(stdout, result, deferred) {
@@ -2086,6 +2476,9 @@ function normalizePath(value) {
 }
 
 function formatBytes(bytes) {
+  if (!Number.isFinite(bytes)) {
+    return '—';
+  }
   if (bytes < 1024) {
     return `${bytes} B`;
   }