@michaelxwb/code-flow 0.6.4 → 0.8.1

package/src/cli.js

@@ -8,10 +8,17 @@ const { spawnSync } = require('child_process');
 
 const pkg = require('../package.json');
 const specWorkflowMigration = require('./migrate/spec-workflow');
+const runtime = require('./runtime');
+const runtimeMigration = require('./migrate/runtime');
+const commandRegistry = JSON.parse(fs.readFileSync(path.join(__dirname, 'core/code-flow/runtime-commands.json'), 'utf8'));
+const runtimeFamilies = [...new Set(Object.keys(commandRegistry.commands).map(command => command.split(' ')[0]))];
+const installPlan = JSON.parse(fs.readFileSync(path.join(__dirname, 'adapters/install-plan.json'), 'utf8'));
 
 const usage = [
   'Usage: code-flow init [--force] [--platform=<claude|codex|costrict|opencode>] [--backup-dir=<path>]',
   '       code-flow migrate --spec-workflow <--dry-run|--prepare|--apply --plan <path>|--rollback <id>>',
+  '       code-flow migrate --runtime <--dry-run|--apply|--rollback <id>>',
+  `       code-flow <${runtimeFamilies.join('|')}> [action] [options]`,
   '       code-flow -v | --version',
   '       code-flow -h | --help'
 ].join('\n');
@@ -45,6 +52,7 @@ function fileCategory(relPath) {
   if (p.startsWith('.agents/skills/')) return 'tool';
   if (p.startsWith('.opencode/commands/')) return 'tool';
   if (p.startsWith('.code-flow/scripts/')) return 'tool';
+  if (p === '.code-flow/runtime-commands.json') return 'tool';
   if (p === 'CLAUDE.md') return 'merge';
   if (p === 'AGENTS.md') return 'merge';
   if (p === '.claude/settings.local.json') return 'merge';
@@ -111,13 +119,9 @@ function writeAdapterVersions(cwd, versions) {
 
 // Marker dirs proving a platform was installed before per-platform tracking.
 function platformFilesExist(cwd, platform) {
-  const markers = {
-    claude: ['.claude/commands'],
-    codex: ['.agents/skills'],
-    costrict: ['.costrict/commands'],
-    opencode: ['.opencode/commands'],
-  };
-  return (markers[platform] || []).some(rel => fs.existsSync(path.join(cwd, rel)));
+  const spec = installPlan.platforms[platform];
+  const markers = spec ? spec.markers : [];
+  return markers.some(rel => fs.existsSync(path.join(cwd, rel)));
 }
 
 // --- Merge functions ---
@@ -129,11 +133,38 @@ function maskFencedCode(text) {
   return text.replace(/```[\s\S]*?```/g, block => block.replace(/[^\n]/g, ' '));
 }
 
+// A managed HTML marker (`<!-- code-flow:... start -->`) directly above a
+// section heading is part of that section. Slicing from the heading line
+// dropped the start marker, leaving an unpaired end marker that both blocked
+// future migrations (cf_spec_migrate needs both) and appended duplicate blocks.
+function managedSliceStart(masked, index) {
+  const before = masked.slice(0, index);
+  const marker = before.match(/<!-- code-flow:[\w-]+ schema=\d+ start -->[ \t]*\n$/);
+  return marker ? index - marker[0].length : index;
+}
+
+function repairManagedStartMarker(srcText, destText, destFile) {
+  // dest may already contain the managed section from an older merge that
+  // dropped the start marker. Restore it before the section heading so
+  // cf_spec_migrate._replace_managed can recognize the block again.
+  const srcStart = srcText.match(/<!-- code-flow:[\w-]+ schema=\d+ start -->/);
+  if (!srcStart || destText.includes(srcStart[0])) return [];
+  const endMatch = /<!-- code-flow:[\w-]+ schema=\d+ end -->/.exec(destText);
+  if (!endMatch) return [];
+  const headingAt = destText.lastIndexOf('\n## ', endMatch.index);
+  const insertAt = headingAt === -1 ? destText.lastIndexOf('\n', endMatch.index) + 1 : headingAt + 1;
+  const repaired = destText.slice(0, insertAt) + srcStart[0] + '\n' + destText.slice(insertAt);
+  fs.writeFileSync(destFile, repaired);
+  return ['repaired managed block start marker'];
+}
+
 function mergeClaudeMd(srcFile, destFile) {
   const srcText = fs.readFileSync(srcFile, 'utf8');
   const destText = fs.readFileSync(destFile, 'utf8');
+  const repaired = repairManagedStartMarker(srcText, destText, destFile);
+  const baseText = repaired.length > 0 ? fs.readFileSync(destFile, 'utf8') : destText;
   const srcMasked = maskFencedCode(srcText);
-  const destMasked = maskFencedCode(destText);
+  const destMasked = maskFencedCode(baseText);
 
   const sectionRegex = /^## .+$/gm;
   const srcSections = [];
@@ -149,20 +180,37 @@ function mergeClaudeMd(srcFile, destFile) {
   }
 
   const missing = srcSections.filter(s => !destSectionSet.has(s.heading));
-  if (missing.length === 0) return [];
+  if (missing.length === 0) return repaired;
 
   const additions = [];
   for (const { heading, index } of missing) {
-    // Find next real section heading using the masked text, then slice the
-    // original text by that offset so we keep any code-block content intact.
+    // Slice so a managed marker directly above the heading belongs to this
+    // section, and the marker above the NEXT heading does not leak into this
+    // section's tail (that produced duplicate start markers).
+    const start = managedSliceStart(srcMasked, index);
     const nextRel = srcMasked.slice(index + heading.length).search(/^## /m);
-    const end = nextRel === -1 ? srcText.length : index + heading.length + nextRel;
-    additions.push(srcText.slice(index, end).trimEnd());
+    const end = nextRel === -1
+      ? srcText.length
+      : managedSliceStart(srcMasked, index + heading.length + nextRel);
+    additions.push(srcText.slice(start, end).trimEnd());
   }
 
-  const merged = destText.trimEnd() + '\n\n' + additions.join('\n\n') + '\n';
+  const merged = baseText.trimEnd() + '\n\n' + additions.join('\n\n') + '\n';
   fs.writeFileSync(destFile, merged);
-  return missing.map(m => m.heading);
+  return [...repaired, ...missing.map(m => m.heading)];
+}
+
+// Managed hook scripts from older releases that are no longer shipped. Hook
+// registration is additive (user commands are never removed), so these stale
+// managed commands would otherwise keep firing on every event forever.
+const RETIRED_HOOK_SCRIPTS = [
+  'cf_inject_hook.py',
+  'cf_session_hook.py',
+  'cf_codex_user_prompt_hook.py',
+];
+
+function isManagedCommand(command) {
+  return typeof command === 'string' && RETIRED_HOOK_SCRIPTS.some(name => command.includes(name));
 }
 
 // Deep-merge a single hook event array. Each item has shape
@@ -171,9 +219,9 @@ function mergeClaudeMd(srcFile, destFile) {
 // dest items; for existing items we union the inner hooks array by command
 // string. User-added items / commands are never removed or rewritten — the
 // merge is purely additive, in line with cli/code-standards.md "合并策略
-// 必须保证用户自定义内容不被覆盖".
-// If a future release changes a managed hook command string, add an explicit
-// migration before merging; otherwise old and new commands will both run.
+// 必须保证用户自定义内容不被覆盖". The one exception is managed hook entries
+// for scripts that no longer exist: those are replaced by the current template
+// command for the same event/matcher (RETIRED_HOOK_SCRIPTS whitelist).
 function mergeHookEventArray(srcArr, destArr, eventName, added) {
   if (!Array.isArray(srcArr) || !Array.isArray(destArr)) return;
   for (const srcItem of srcArr) {
@@ -190,6 +238,15 @@ function mergeHookEventArray(srcArr, destArr, eventName, added) {
       continue;
     }
     if (!Array.isArray(destItem.hooks)) destItem.hooks = [];
+    const retired = destItem.hooks.filter(h => h && isManagedCommand(h.command));
+    if (retired.length > 0) {
+      destItem.hooks = destItem.hooks.filter(h => !(h && isManagedCommand(h.command)));
+      for (const name of RETIRED_HOOK_SCRIPTS) {
+        if (retired.some(h => String(h.command).includes(name))) {
+          added.push(`hook: ${eventName} -retired ${name}`);
+        }
+      }
+    }
     const destCmds = new Set(
       destItem.hooks.map(h => (h && typeof h.command === 'string' ? h.command : ''))
     );
@@ -237,6 +294,19 @@ function mergeSettingsJson(srcFile, destFile) {
   return added;
 }
 
+function mergeCodexHooksJson(srcFile, destFile) {
+  const dest = JSON.parse(fs.readFileSync(destFile, 'utf8'));
+  const managed = /\.code-flow\/scripts\/cf_(?:pre_tool_hook|post_hook|user_prompt_hook|stop_hook|codex_hook)\.py/;
+  for (const groups of Object.values(dest.hooks || {})) {
+    for (const group of groups) group.hooks = (group.hooks || []).filter(hook => !managed.test(hook.command || ''));
+  }
+  for (const event of Object.keys(dest.hooks || {})) {
+    dest.hooks[event] = dest.hooks[event].filter(group => group.hooks.length);
+  }
+  fs.writeFileSync(destFile, JSON.stringify(dest, null, 2) + '\n');
+  return mergeSettingsJson(srcFile, destFile);
+}
+
 // OpenCode v2 merge: migrate the v1 `plugin` key to `plugins`, drop the
 // auto-discovered local path (`.opencode/plugins/*` loads without config),
 // and union template `plugins` entries without overwriting user content.
@@ -394,6 +464,8 @@ function collectFiles(dir, base) {
   if (!fs.existsSync(dir)) return results;
   const entries = fs.readdirSync(dir, { withFileTypes: true });
   for (const entry of entries) {
+    // OS metadata junk must never be deployed into user projects.
+    if (entry.name === '.DS_Store' || entry.name === 'Thumbs.db') continue;
     const rel = path.join(base, entry.name);
     if (entry.isDirectory()) {
       results.push(...collectFiles(path.join(dir, entry.name), rel));
@@ -408,6 +480,7 @@ function copyDirRecursive(srcDir, destDir, overwrite) {
   fs.mkdirSync(destDir, { recursive: true });
   const entries = fs.readdirSync(srcDir, { withFileTypes: true });
   for (const entry of entries) {
+    if (entry.name === '.DS_Store' || entry.name === 'Thumbs.db') continue;
     const srcPath = path.join(srcDir, entry.name);
     const destPath = path.join(destDir, entry.name);
     if (entry.isDirectory()) {
@@ -512,9 +585,48 @@ const MANAGED_LEGACY_SKILL_NAMES = new Set([
   'cf-validate.md',
 ]);
 
-// --- pyyaml dependency: probe first, fall back through PEP 668 strategies ---
+// Runtime ignore list for the managed `.code-flow/.gitignore`.
+// npm never ships `.gitignore` files in tarballs, so `src/core/code-flow/.gitignore`
+// cannot reach `code-flow init` from a published package. The packaged
+// `scripts/runtime-resources.json` declaration is the single source shared with
+// cf_spec_migrate; a test keeps the source-tree template aligned with it.
+const RUNTIME_RESOURCES = JSON.parse(fs.readFileSync(
+  path.join(__dirname, 'core/code-flow/scripts/runtime-resources.json'), 'utf8'));
+const RUNTIME_IGNORE_START = RUNTIME_RESOURCES.gitignore.start;
+const RUNTIME_IGNORE_END = RUNTIME_RESOURCES.gitignore.end;
+const RUNTIME_GITIGNORE = [
+  RUNTIME_IGNORE_START,
+  ...RUNTIME_RESOURCES.gitignore.entries,
+  RUNTIME_IGNORE_END,
+  '',
+].join('\n');
+
+function ensureRuntimeGitignore(cwd, results) {
+  const dest = path.join(cwd, '.code-flow', '.gitignore');
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, RUNTIME_GITIGNORE);
+    results.created.push('.code-flow/.gitignore');
+    return;
+  }
+  // Existing managed block: add runtime entries introduced by later releases.
+  // Files without our markers are user-owned and left untouched.
+  const text = fs.readFileSync(dest, 'utf8');
+  const endMarker = RUNTIME_IGNORE_END;
+  if (!text.includes(RUNTIME_IGNORE_START) || !text.includes(endMarker)) return;
+  const lines = text.split('\n');
+  const missing = RUNTIME_RESOURCES.gitignore.entries.filter(
+    line => line && !lines.includes(line)
+  );
+  if (missing.length === 0) return;
+  const at = lines.indexOf(endMarker);
+  lines.splice(at, 0, ...missing);
+  fs.writeFileSync(dest, lines.join('\n'));
+  results.merged.push(`.code-flow/.gitignore — added: ${missing.join(', ')}`);
+}
 
 // --- pyyaml dependency: probe first, fall back through PEP 668 strategies ---
+
 // Bounded waits: each attempt carries its own timeout inside a total budget,
 // with progress on stderr. spawnFn/logFn/nowFn are injectable for tests.
 const PIP_PER_ATTEMPT_MS = 60000;
@@ -553,10 +665,26 @@ function ensurePyYaml(spawnFn, logFn, nowFn) {
 
 // --- Adapter file installer: shared by every platform branch ---
 
+// Run a merge function with a clear, actionable error instead of a raw stack
+// trace. A corrupt destination file must not abort init silently mid-way; the
+// operator gets the file name and the recovery step.
+function runMerge(mergeFn, src, dest, label) {
+  try {
+    return mergeFn(src, dest);
+  } catch (error) {
+    const message = error && error.message ? error.message : String(error);
+    throw new Error(
+      `${label}: merge failed (${message}). Fix or delete the file, then re-run init.`
+    );
+  }
+}
+
 // Install one adapter file with the standard create / force / upgrade /
-// skip semantics. `mergeFn` is consulted only on upgrade for `merge`-class
-// files; pass null for `tool`-class files (overwrite on upgrade) or for
-// fresh-only files (skip on upgrade).
+// skip semantics. `mergeFn` is consulted on upgrade for `merge`-class files
+// and also in fresh mode when the destination already exists (a pre-existing
+// AGENTS.md/CLAUDE.md must still receive the managed sections instead of
+// being silently skipped — otherwise the Spec Workflow protocol never lands).
+// Pass null for `tool`-class files or fresh-only files.
 function installAdapterFile(opts) {
   const { src, dest, label, mode, mergeFn, toolOnUpgrade, results } = opts;
   if (!fs.existsSync(dest)) {
@@ -570,6 +698,15 @@ function installAdapterFile(opts) {
     fs.copyFileSync(src, dest);
     return;
   }
+  if (mode === 'fresh' && mergeFn) {
+    const added = runMerge(mergeFn, src, dest, label);
+    if (added.length > 0) {
+      results.merged.push(`${label} — added: ${added.join(', ')}`);
+    } else {
+      results.skipped.push(label);
+    }
+    return;
+  }
   if (mode === 'upgrade') {
     if (toolOnUpgrade) {
       results.updated.push(label);
@@ -577,7 +714,7 @@ function installAdapterFile(opts) {
       return;
     }
     if (mergeFn) {
-      const added = mergeFn(src, dest);
+      const added = runMerge(mergeFn, src, dest, label);
       if (added.length > 0) {
         results.merged.push(`${label} — added: ${added.join(', ')}`);
       } else {
@@ -614,263 +751,144 @@ function parseStringFlag(args, name) {
   return '';
 }
 
-// --- Main init ---
+// --- Install orchestration driven by adapters/install-plan.json ---
 
-function runInit(force, platform, opts) {
-  const cwd = process.cwd();
-  const options = opts || {};
-  const installedVersion = readInstalledVersion(cwd);
-  if (installedVersion && compareVersions(installedVersion, '0.4.2') >= 0 && compareVersions(installedVersion, '0.6.0') < 0) {
-    process.stdout.write(`${JSON.stringify({ status: 'migration_required', version: installedVersion, command: 'code-flow migrate --spec-workflow --dry-run' })}\n`);
-    process.exit(3);
+function initResults() {
+  return { created: [], updated: [], merged: [], skipped: [], removed: [] };
+}
+
+const INSTALL_MERGERS = {
+  claudeMd: mergeClaudeMd,
+  settingsJson: mergeSettingsJson,
+  codexHooksJson: mergeCodexHooksJson,
+  codexConfigToml: mergeCodexConfigToml,
+  opencodeJson: mergeOpencodeJson,
+};
+
+// Track + copy helper for directory trees. Core files derive their category
+// per file; declared platform trees pass a single category.
+function installTree(opts) {
+  const { srcDir, destDir, prefix, mode, category, ensureDest, runtimeMigration, results } = opts;
+  if (ensureDest) fs.mkdirSync(destDir, { recursive: true });
+  if (!fs.existsSync(srcDir)) return;
+  for (const rel of collectFiles(srcDir, '')) {
+    installTreeEntry({
+      src: path.join(srcDir, rel),
+      dest: path.join(destDir, rel),
+      label: path.join(prefix, rel),
+      mode,
+      category,
+      runtimeMigration,
+      results,
+    });
   }
-  ensurePython3();
+}
 
-  const baseDir = __dirname;
-  const coreDir = path.join(baseDir, 'core');
-  const adaptersDir = path.join(baseDir, 'adapters');
+function installTreeEntry(opts) {
+  const { src, dest, label, mode, category, runtimeMigration, results } = opts;
+  const cat = category || fileCategory(label);
+  if (runtimeMigration && cat === 'user' && !fs.existsSync(dest)) return;
+  if (!fs.existsSync(dest)) {
+    results.created.push(label);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+  } else if (mode === 'force') {
+    results.updated.push(label);
+    fs.copyFileSync(src, dest);
+  } else if (mode === 'upgrade' && cat === 'tool') {
+    results.updated.push(label);
+    fs.copyFileSync(src, dest);
+  } else {
+    results.skipped.push(label);
+  }
+}
 
-  // Determine mode: global mode drives core files and messaging; each
-  // platform additionally resolves its own mode from per-platform records so
-  // upgrading one platform can never mask another platform's staleness.
-  // A global upgrade also refreshes the selected platform (previous behavior).
-  const mode = modeFor(installedVersion, force);
+function installPlatform(cwd, adaptersDir, platform, mode, runtimeMigration, results) {
+  const spec = installPlan.platforms[platform];
+  if (!spec) return;
+  for (const entry of spec.entries) {
+    if (entry.kind === 'file') {
+      installAdapterFile({
+        src: path.join(adaptersDir, entry.src),
+        dest: path.join(cwd, entry.dest),
+        label: entry.label,
+        mode,
+        mergeFn: INSTALL_MERGERS[entry.merger],
+        toolOnUpgrade: entry.category === 'tool',
+        results,
+      });
+    } else if (entry.kind === 'dir') {
+      installTree({
+        srcDir: path.join(adaptersDir, entry.src),
+        destDir: path.join(cwd, entry.dest),
+        prefix: entry.prefix,
+        mode,
+        category: entry.category,
+        ensureDest: Boolean(entry.ensure),
+        runtimeMigration,
+        results,
+      });
+    } else if (entry.kind === 'stamp') {
+      stampPackageVersion(path.join(cwd, entry.path));
+    }
+  }
+}
+
+function stampPackageVersion(file) {
+  if (!fs.existsSync(file)) return;
+  const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+  data.version = pkg.version;
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n');
+}
+
+function resolvePlatformMode(cwd, platform, mode, force, options) {
   const adapterVersions = readAdapterVersions(cwd);
   const adapterPrev = typeof adapterVersions.adapters[platform] === 'string'
     ? adapterVersions.adapters[platform]
     : null;
-  let platformMode;
-  if (force) {
-    platformMode = 'force';
-  } else if (!adapterPrev && !platformFilesExist(cwd, platform)) {
-    platformMode = 'fresh';
-  } else if (
+  if (options.runtimeMigration) return 'upgrade';
+  if (force) return 'force';
+  if (!adapterPrev && !platformFilesExist(cwd, platform)) return 'fresh';
+  if (
     (adapterPrev && compareVersions(adapterPrev, pkg.version) < 0) ||
     (!adapterPrev && platformFilesExist(cwd, platform)) ||
     mode === 'upgrade'
   ) {
-    platformMode = 'upgrade';
-  } else {
-    platformMode = 'current';
-  }
-
-  const created = [];
-  const updated = [];
-  const merged = [];
-  const skipped = [];
-  const removed = [];
-  const results = { created, updated, merged, skipped };
-
-  // Track + copy helper for directory trees. dirMode is resolved per area:
-  // core files follow the global mode, platform files follow platformMode.
-  const processDir = (srcDir, destDir, prefix, dirMode) => {
-    const effective = dirMode || mode;
-    if (!fs.existsSync(srcDir)) return;
-    const files = collectFiles(srcDir, '');
-    for (const rel of files) {
-      const src = path.join(srcDir, rel);
-      const dest = path.join(destDir, rel);
-      const label = path.join(prefix, rel);
-      const cat = fileCategory(label);
-
-      if (!fs.existsSync(dest)) {
-        created.push(label);
-        fs.mkdirSync(path.dirname(dest), { recursive: true });
-        fs.copyFileSync(src, dest);
-      } else if (effective === 'force') {
-        updated.push(label);
-        fs.copyFileSync(src, dest);
-      } else if (effective === 'upgrade' && cat === 'tool') {
-        updated.push(label);
-        fs.copyFileSync(src, dest);
-      } else {
-        skipped.push(label);
-      }
-    }
-  };
-
-  // Process .code-flow/ (core)
-  processDir(path.join(coreDir, 'code-flow'), path.join(cwd, '.code-flow'), '.code-flow', mode);
-
-  // Process Claude adapter
-  if (platform === 'claude') {
-    installAdapterFile({
-      src: path.join(adaptersDir, 'claude', 'CLAUDE.md'),
-      dest: path.join(cwd, 'CLAUDE.md'),
-      label: 'CLAUDE.md',
-      mode: platformMode,
-      mergeFn: mergeClaudeMd,
-      toolOnUpgrade: false,
-      results,
-    });
-
-    fs.mkdirSync(path.join(cwd, '.claude', 'commands'), { recursive: true });
-    processDir(
-      path.join(adaptersDir, 'claude', 'commands'),
-      path.join(cwd, '.claude', 'commands'),
-      '.claude/commands', platformMode
-    );
-
-    installAdapterFile({
-      src: path.join(adaptersDir, 'claude', 'settings.local.json'),
-      dest: path.join(cwd, '.claude', 'settings.local.json'),
-      label: '.claude/settings.local.json',
-      mode: platformMode,
-      mergeFn: mergeSettingsJson,
-      toolOnUpgrade: false,
-      results,
-    });
-  }
-
-  // Process Costrict adapter
-  if (platform === 'costrict') {
-    installAdapterFile({
-      src: path.join(adaptersDir, 'costrict', 'CLAUDE.md'),
-      dest: path.join(cwd, 'CLAUDE.md'),
-      label: 'CLAUDE.md',
-      mode: platformMode,
-      mergeFn: mergeClaudeMd,
-      toolOnUpgrade: false,
-      results,
-    });
-
-    fs.mkdirSync(path.join(cwd, '.costrict', 'commands'), { recursive: true });
-    processDir(
-      path.join(adaptersDir, 'costrict', 'commands'),
-      path.join(cwd, '.costrict', 'commands'),
-      '.costrict/commands', platformMode
-    );
-
-    installAdapterFile({
-      src: path.join(adaptersDir, 'costrict', 'settings.local.json'),
-      dest: path.join(cwd, '.costrict', 'settings.local.json'),
-      label: '.costrict/settings.local.json',
-      mode: platformMode,
-      mergeFn: mergeSettingsJson,
-      toolOnUpgrade: false,
-      results,
-    });
-  }
-
-  // Process Codex adapter
-  if (platform === 'codex') {
-    installAdapterFile({
-      src: path.join(adaptersDir, 'codex', 'AGENTS.md'),
-      dest: path.join(cwd, 'AGENTS.md'),
-      label: 'AGENTS.md',
-      mode: platformMode,
-      mergeFn: mergeClaudeMd,
-      toolOnUpgrade: false,
-      results,
-    });
-
-    installAdapterFile({
-      src: path.join(adaptersDir, 'codex', 'hooks.json'),
-      dest: path.join(cwd, '.codex', 'hooks.json'),
-      label: '.codex/hooks.json',
-      mode: platformMode,
-      mergeFn: mergeSettingsJson,
-      toolOnUpgrade: false,
-      results,
-    });
-
-    installAdapterFile({
-      src: path.join(adaptersDir, 'codex', 'config.toml'),
-      dest: path.join(cwd, '.codex', 'config.toml'),
-      label: '.codex/config.toml',
-      mode: platformMode,
-      mergeFn: mergeCodexConfigToml,
-      toolOnUpgrade: false,
-      results,
-    });
-
-    // Project-level .agents/skills/ (version-controlled, committed to repo)
-    processDir(
-      path.join(adaptersDir, 'codex', 'skills'),
-      path.join(cwd, '.agents', 'skills'),
-      '.agents/skills', platformMode
-    );
-  }
-
-  // Process OpenCode adapter
-  if (platform === 'opencode') {
-    installAdapterFile({
-      src: path.join(adaptersDir, 'opencode', 'AGENTS.md'),
-      dest: path.join(cwd, 'AGENTS.md'),
-      label: 'AGENTS.md',
-      mode: platformMode,
-      mergeFn: mergeClaudeMd,
-      toolOnUpgrade: false,
-      results,
-    });
-
-    // Plugin files under .opencode/plugins/code-flow/
-    processDir(
-      path.join(adaptersDir, 'opencode', 'plugins'),
-      path.join(cwd, '.opencode', 'plugins'),
-      '.opencode/plugins', platformMode
-    );
-
-    // Stamp main package version into the plugin's package.json
-    const pluginPkgPath = path.join(cwd, '.opencode', 'plugins', 'code-flow', 'package.json');
-    if (fs.existsSync(pluginPkgPath)) {
-      const pluginPkg = JSON.parse(fs.readFileSync(pluginPkgPath, 'utf8'));
-      pluginPkg.version = pkg.version;
-      fs.writeFileSync(pluginPkgPath, JSON.stringify(pluginPkg, null, 2) + '\n');
-    }
-
-    // Command files under .opencode/commands/
-    processDir(
-      path.join(adaptersDir, 'opencode', 'commands'),
-      path.join(cwd, '.opencode', 'commands'),
-      '.opencode/commands', platformMode
-    );
-
-    installAdapterFile({
-      src: path.join(adaptersDir, 'opencode', 'opencode.json'),
-      dest: path.join(cwd, 'opencode.json'),
-      label: 'opencode.json',
-      mode: platformMode,
-      mergeFn: mergeOpencodeJson,
-      toolOnUpgrade: false,
-      results,
-    });
+    return 'upgrade';
   }
+  return 'current';
+}
 
-  // Merge config.yml on upgrade
+function mergeConfigOnUpgrade(cwd, coreDir, mode, options, results) {
   const configSrc = path.join(coreDir, 'code-flow', 'config.yml');
   const configDest = path.join(cwd, '.code-flow', 'config.yml');
-  if (mode === 'upgrade' && fs.existsSync(configDest) && fs.existsSync(configSrc)) {
-    const added = mergeConfigYml(configSrc, configDest);
-    if (added.length > 0) {
-      // Replace the skipped entry with merged
-      const idx = skipped.indexOf('.code-flow/config.yml');
-      if (idx !== -1) skipped.splice(idx, 1);
-      merged.push(`.code-flow/config.yml — added: ${added.join(', ')}`);
-    }
-  }
-
-  // Clean up legacy .claude/skills/ (claude domain only; user-owned kept, managed backed up)
-  removeLegacyClaudeSkills(cwd, removed, { platform, backupDir: options.backupDir || '' });
-
-  // Clean up renamed orphan scripts (only meaningful on upgrade)
-  if (mode === 'upgrade' || mode === 'force') {
-    removeOrphanFiles(cwd, removed);
+  if (mode !== 'upgrade' || options.runtimeMigration ||
+      !fs.existsSync(configDest) || !fs.existsSync(configSrc)) {
+    return;
   }
+  const added = mergeConfigYml(configSrc, configDest);
+  if (added.length === 0) return;
+  // Replace the skipped entry with merged
+  const idx = results.skipped.indexOf('.code-flow/config.yml');
+  if (idx !== -1) results.skipped.splice(idx, 1);
+  results.merged.push(`.code-flow/config.yml — added: ${added.join(', ')}`);
+}
 
-  // Install pyyaml — probe first, fall back through PEP 668 strategies
-  ensurePyYaml();
-
-  // Write version (legacy global file kept for compatibility) + per-platform records
-  writeVersion(cwd, pkg.version);
+function recordInstall(cwd, platform) {
+  const adapterVersions = readAdapterVersions(cwd);
   adapterVersions.adapters[platform] = pkg.version;
   adapterVersions.core = pkg.version;
   writeAdapterVersions(cwd, adapterVersions);
+  runtime.writeInstall(cwd, Object.keys(adapterVersions.adapters));
+  writeVersion(cwd, pkg.version);
+}
 
-  // Output summary
+function printInitSummary(mode, platformMode, installedVersion, results) {
   if (mode === 'upgrade') {
     process.stdout.write(`\ncode-flow upgraded: ${installedVersion} → ${pkg.version}\n\n`);
-  } else if (mode === 'current' && platformMode === 'current' && created.length === 0 && updated.length === 0 && merged.length === 0) {
+  } else if (mode === 'current' && platformMode === 'current' &&
+             results.created.length === 0 && results.updated.length === 0 &&
+             results.merged.length === 0) {
     process.stdout.write(`code-flow v${pkg.version} already up to date.\n`);
     process.exit(0);
   } else if (mode === 'force') {
@@ -878,69 +896,81 @@ function runInit(force, platform, opts) {
   } else {
     process.stdout.write(`\ncode-flow v${pkg.version} initialized!\n\n`);
   }
-
-  if (updated.length > 0) {
-    process.stdout.write('Updated (tool-managed):\n');
-    for (const f of updated) process.stdout.write(`  ↑ ${f}\n`);
-  }
-  if (merged.length > 0) {
-    process.stdout.write('Merged (new sections added):\n');
-    for (const f of merged) process.stdout.write(`  ⊕ ${f}\n`);
+  for (const group of installPlan.summary) {
+    const items = results[group.key] || [];
+    if (items.length === 0) continue;
+    process.stdout.write(`${group.title}\n`);
+    for (const item of items) process.stdout.write(`  ${group.marker} ${item}\n`);
   }
-  if (created.length > 0) {
-    process.stdout.write('Created:\n');
-    for (const f of created) process.stdout.write(`  + ${f}\n`);
-  }
-  if (skipped.length > 0) {
-    process.stdout.write('Skipped (user-customized):\n');
-    for (const f of skipped) process.stdout.write(`  · ${f}\n`);
+}
+
+function printNextSteps(platform, mode) {
+  const spec = installPlan.platforms[platform];
+  const steps = spec && spec.next_steps[mode === 'fresh' ? 'fresh' : 'upgrade'];
+  if (!steps || steps.length === 0) return;
+  process.stdout.write('\nNext steps:\n');
+  for (const line of steps) process.stdout.write(`${line}\n`);
+}
+
+// --- Main init ---
+
+function runInit(force, platform, opts) {
+  const cwd = process.cwd();
+  const options = opts || {};
+  const installedVersion = readInstalledVersion(cwd);
+  if (!options.runtimeMigration && installedVersion && compareVersions(installedVersion, '0.6.0') >= 0 &&
+      !fs.existsSync(path.join(cwd, '.code-flow/runtime-commands.json'))) {
+    process.stdout.write(`${JSON.stringify({ status: 'migration_required', command: 'code-flow migrate --runtime --dry-run' })}\n`);
+    process.exit(3);
   }
-  if (removed.length > 0) {
-    process.stdout.write('Removed (deprecated):\n');
-    for (const f of removed) process.stdout.write(`  ✕ ${f}\n`);
+  if (installedVersion && compareVersions(installedVersion, '0.4.2') >= 0 && compareVersions(installedVersion, '0.6.0') < 0) {
+    process.stdout.write(`${JSON.stringify({ status: 'migration_required', version: installedVersion, command: 'code-flow migrate --spec-workflow --dry-run' })}\n`);
+    process.exit(3);
   }
+  ensurePython3();
 
-  process.stdout.write('\nNext steps:\n');
-  if (platform === 'codex') {
-    if (mode === 'fresh') {
-      process.stdout.write('  1. Edit AGENTS.md — fill in team/project info\n');
-      process.stdout.write('  2. Run /hooks in Codex CLI and trust the code-flow hooks if prompted\n');
-      process.stdout.write('  3. Run $cf-init in Codex CLI to auto-scan and populate specs\n');
-      process.stdout.write('     Or manually edit .code-flow/specs/ to fill in your coding standards\n');
-    } else {
-      process.stdout.write('  Run /hooks in Codex CLI and trust changed code-flow hooks if prompted\n');
-      process.stdout.write('  Run $cf-learn in Codex CLI to update specs with project conventions\n');
-      process.stdout.write('  Run $cf-learn --map to update retrieval maps\n');
-    }
-  } else if (platform === 'costrict') {
-    if (mode === 'fresh') {
-      process.stdout.write('  1. Edit CLAUDE.md — fill in team/project info\n');
-      process.stdout.write('  2. Run /cf-init in Costrict to auto-scan and populate specs\n');
-      process.stdout.write('     Or manually edit .code-flow/specs/ to fill in your coding standards\n');
-    } else {
-      process.stdout.write('  Run /cf-learn in Costrict to update specs with project conventions\n');
-      process.stdout.write('  Run /cf-learn --map to update retrieval maps\n');
-    }
-  } else if (platform === 'opencode') {
-    if (mode === 'fresh') {
-      process.stdout.write('  1. Edit AGENTS.md — fill in team/project info\n');
-      process.stdout.write('  2. Start opencode in this directory — the plugin auto-loads\n');
-      process.stdout.write('  3. Run /cf-init in OpenCode to auto-scan and populate specs\n');
-      process.stdout.write('     Or manually edit .code-flow/specs/ to fill in your coding standards\n');
-    } else {
-      process.stdout.write('  Run /cf-learn in OpenCode to update specs with project conventions\n');
-      process.stdout.write('  Run /cf-learn --map to update retrieval maps\n');
-    }
-  } else {
-    if (mode === 'fresh') {
-      process.stdout.write('  1. Edit CLAUDE.md — fill in team/project info\n');
-      process.stdout.write('  2. Run /cf-init in Claude Code to auto-scan and populate specs\n');
-      process.stdout.write('     Or manually edit .code-flow/specs/ to fill in your coding standards\n');
-    } else {
-      process.stdout.write('  Run /cf-learn in Claude Code to update specs with project conventions\n');
-      process.stdout.write('  Run /cf-learn --map to update retrieval maps\n');
-    }
+  const baseDir = __dirname;
+  const coreDir = path.join(baseDir, 'core');
+  const adaptersDir = path.join(baseDir, 'adapters');
+
+  // Determine mode: global mode drives core files and messaging; each
+  // platform additionally resolves its own mode from per-platform records so
+  // upgrading one platform can never mask another platform's staleness.
+  // A global upgrade also refreshes the selected platform (previous behavior).
+  const mode = options.runtimeMigration ? 'upgrade' : modeFor(installedVersion, force);
+  const platformMode = resolvePlatformMode(cwd, platform, mode, force, options);
+  const results = initResults();
+
+  // Process .code-flow/ (core)
+  installTree({
+    srcDir: path.join(baseDir, installPlan.core.source),
+    destDir: path.join(cwd, installPlan.core.dest),
+    prefix: installPlan.core.prefix,
+    mode,
+    runtimeMigration: options.runtimeMigration,
+    results,
+  });
+  // npm tarballs never include .gitignore, so the published package must write
+  // the runtime ignore list itself (or extend it on upgrade).
+  ensureRuntimeGitignore(cwd, results);
+  installPlatform(cwd, adaptersDir, platform, platformMode, options.runtimeMigration, results);
+  mergeConfigOnUpgrade(cwd, coreDir, mode, options, results);
+
+  // Clean up legacy .claude/skills/ (claude domain only; user-owned kept, managed backed up)
+  removeLegacyClaudeSkills(cwd, results.removed, { platform, backupDir: options.backupDir || '' });
+
+  // Clean up renamed orphan scripts (only meaningful on upgrade)
+  if (mode === 'upgrade' || mode === 'force') {
+    removeOrphanFiles(cwd, results.removed);
   }
+
+  // Install pyyaml — probe first, fall back through PEP 668 strategies
+  ensurePyYaml();
+
+  recordInstall(cwd, platform);
+
+  printInitSummary(mode, platformMode, installedVersion, results);
+  printNextSteps(platform, mode);
   process.exit(0);
 }
 
@@ -948,6 +978,10 @@ function runInit(force, platform, opts) {
 
 const args = process.argv.slice(2);
 
+if (runtimeFamilies.includes(args[0]) || runtime.projectCommandFamily(args[0])) {
+  process.exit(runtime.run(args));
+}
+
 function argumentValue(values, name) {
   const index = values.indexOf(name);
   return index >= 0 ? values[index + 1] || '' : '';
@@ -971,7 +1005,7 @@ function runMigrate(values) {
     if (actions[0] === '--apply') {
       const plan = argumentValue(values, '--plan');
       if (!plan) fail('Error: --apply requires --plan <path>.');
-      result = specWorkflowMigration.apply(path.resolve(plan));
+      result = specWorkflowMigration.apply(path.resolve(plan), { projectRoot: process.cwd() });
     }
     if (actions[0] === '--rollback') {
       const id = argumentValue(values, '--rollback');
@@ -1005,10 +1039,29 @@ if (args[0] === 'init') {
   if (platform !== 'claude' && platform !== 'codex' && platform !== 'costrict' && platform !== 'opencode') {
     fail(`Error: --platform must be "claude", "codex", "costrict", or "opencode", got "${platform}".`);
   }
-  runInit(force, platform, { backupDir: parseStringFlag(args, 'backup-dir') });
+  try {
+    const staging = process.env.CODE_FLOW_RUNTIME_STAGE === process.cwd() &&
+      fs.existsSync(path.join(process.cwd(), '.runtime-stage.json'));
+    runInit(force, platform, { backupDir: parseStringFlag(args, 'backup-dir'), runtimeMigration: staging });
+  } catch (error) {
+    // Report merge/IO failures as a readable error, never a raw JS stack.
+    const message = error && error.message ? error.message : String(error);
+    process.stderr.write(`Error: init failed — ${message}\n`);
+    process.exit(1);
+  }
 }
 
 if (args[0] === 'migrate') {
+  if (args[1] === '--runtime') {
+    try {
+      const result = runtimeMigration.run(process.cwd(), args.slice(2));
+      process.stdout.write(`${JSON.stringify(result)}\n`);
+      process.exit(result.status === 'rolled_back' ? 4 : 0);
+    } catch (error) {
+      process.stdout.write(`${JSON.stringify({ status: 'blocked', error: error.message })}\n`);
+      process.exit(3);
+    }
+  }
   runMigrate(args.slice(1));
 }