@caiqueoak/flow 0.6.0 → 0.8.0

package/src/cli.mjs

@@ -1,62 +0,0 @@
-#!/usr/bin/env node
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { CliError, info } from './shared/cli-io.mjs';
-
-const currentFile = fileURLToPath(import.meta.url);
-const packageRoot = path.resolve(path.dirname(currentFile), '..');
-const packageManifest = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
-const commands = {
-  init: async (context) => (await import('./commands/init.mjs')).runInit(context),
-  graph: async (context) => (await import('./commands/graph.mjs')).runGraph(context),
-  status: async (context) => (await import('./commands/status.mjs')).runStatus(context),
-  validate: async (context) => (await import('./commands/validate.mjs')).runValidate(context),
-  route: async (context) => (await import('./commands/route.mjs')).runRoute(context),
-  trace: async (context) => (await import('./commands/trace.mjs')).runTrace(context),
-  migrate: async (context) => (await import('./commands/migrate.mjs')).runMigrate(context)
-};
-
-function help() {
-  const commandHelp = (message) =>
-    info(
-      message
-        .replace(
-          'validate   Check schemas, approvals, DAGs, traceability and deterministic gates.',
-          'validate   Check schemas, approvals, DAGs and traceability; --gates runs project checks.'
-        )
-        .replace(
-          'validate options: --json --pre-commit W015-T003',
-          'validate options: --json --gates --pre-commit W015-T003'
-        )
-    );
-  commandHelp(
-    `Flow ${packageManifest.version}\n\nUse the project-local installation: npx --no-install flow <command>\n\nCommands:\n  init       Configure Flow and install/refresh local agent integrations.\n  migrate    Normalize older artifacts; /flow then reconciles legacy decisions.\n  status     Show progress and dependency/external blockers.\n  validate   Check schemas, approvals, DAGs, traceability and deterministic gates.\n  graph      Regenerate the derived work-item dependency graph.\n  route      Return the next repository-resumable agent step (--json available).\n  trace      Resolve W015-T003 to a HEAD-reachable commit with both Flow trailers.\n\nCommon options: --path <project>, --help, --version\ninit options: --runtime codex,claude --profile readability-first --existing-code improve|preserve\n  Readability First: reusable preferences for SRP, semantic naming, cohesion and simple vertical slices.\n  improve: recommend clearer structure while retaining behavior and external contracts.\n  preserve: retain consistent existing conventions unless a concrete problem warrants change.\n  Neither option authorizes refactoring; engineering changes require human approval.\nvalidate options: --json --pre-commit W015-T003\ntrace options: W015-T003 --json\n\nDiscovery → PRD approval → engineering approval → complete backlog → implementation-plan approval → serial implementation → review.\nUse /flow for agent workflows and engineering changes. Approved engineering.md is authoritative.\nUpdate the npm package with your package manager, then rerun init to refresh integrations.`
-  );
-}
-
-export async function runCli(args = process.argv.slice(2)) {
-  if (!args.length || args.includes('--help') || args.includes('-h')) return help();
-  if (args.includes('--version') || args.includes('-v')) return info(packageManifest.version);
-  const command = commands[args[0]];
-  if (!command) throw new CliError(`unknown command '${args[0]}'. Run flow --help.`);
-  return command({
-    args: args.slice(1),
-    packageRoot,
-    packageName: packageManifest.name,
-    version: packageManifest.version
-  });
-}
-
-try {
-  await runCli();
-} catch (error) {
-  if (error?.code === 'ABORT_ERR') {
-    info('\nFlow command canceled.');
-    process.exitCode = 130;
-  } else if (error instanceof CliError) {
-    console.error(`flow: ${error.message}`);
-    process.exitCode = error.exitCode || 1;
-  } else throw error;
-}

package/src/commands/gates.mjs

@@ -1,71 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { spawnSync } from 'node:child_process';
-import { fail } from '../shared/cli-io.mjs';
-import { parseGates } from '../artifacts/gates.mjs';
-
-function runCommandGate(root, gate) {
-  const shell = process.platform === 'win32' ? process.env.ComSpec || 'cmd.exe' : '/bin/sh';
-  const args = process.platform === 'win32' ? ['/d', '/s', '/c', gate.command] : ['-lc', gate.command];
-  const result = spawnSync(shell, args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
-  return {
-    id: gate.id,
-    kind: gate.kind,
-    blocking: gate.blocking,
-    status: result.status === 0 ? 'passed' : 'failed',
-    exit_code: result.status,
-    stdout: result.stdout,
-    stderr: result.stderr
-  };
-}
-
-function runBuiltinGate(root, gate) {
-  if (gate.rule !== 'kebab-case-files')
-    return {
-      id: gate.id,
-      kind: gate.kind,
-      blocking: gate.blocking,
-      status: 'unsupported',
-      message: `Unknown builtin rule '${gate.rule}'.`
-    };
-  const excluded = new Set(['.git', '.flow', 'node_modules']);
-  const violations = [];
-  function walk(directory) {
-    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
-      if (excluded.has(entry.name)) continue;
-      const full = path.join(directory, entry.name);
-      if (entry.isDirectory()) {
-        walk(full);
-        continue;
-      }
-      if (entry.name.startsWith('.')) continue;
-      const ext = path.extname(entry.name);
-      const stem = ext ? entry.name.slice(0, -ext.length) : entry.name;
-      if (/^[A-Z0-9_.-]+$/.test(entry.name)) continue;
-      const valid = stem.split('.').every((segment) => /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(segment));
-      if (!valid) violations.push(path.relative(root, full));
-    }
-  }
-  walk(root);
-  return {
-    id: gate.id,
-    kind: gate.kind,
-    blocking: gate.blocking,
-    status: violations.length ? 'failed' : 'passed',
-    violations
-  };
-}
-
-export function evaluateGates(root) {
-  const file = path.join(root, '.flow', 'gates.yaml');
-  if (!fs.existsSync(file)) fail('gates.yaml does not exist.');
-  const { gates } = parseGates(fs.readFileSync(file, 'utf8'));
-  return gates.map((gate) => {
-    const startedAt = performance.now();
-    let result;
-    if (gate.kind === 'command') result = runCommandGate(root, gate);
-    else if (gate.kind === 'builtin') result = runBuiltinGate(root, gate);
-    else throw new Error(`Unsupported gate kind '${gate.kind}'.`);
-    return { ...result, duration_ms: Math.round(performance.now() - startedAt) };
-  });
-}

package/src/commands/graph.mjs

@@ -1,92 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { info } from '../shared/cli-io.mjs';
-import { projectRoot } from '../shared/project-path.mjs';
-import {
-  ArtifactValidationError,
-  deriveExecutionStatus,
-  parseBacklog,
-  topologicalOrder
-} from '../artifacts/backlog.mjs';
-
-export { ArtifactValidationError as GraphValidationError };
-
-function escapeMermaid(text) {
-  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-}
-
-const CLASSES = [
-  '  classDef completed fill:#dcfce7,stroke:#16a34a,color:#14532d;',
-  '  classDef in_progress fill:#dbeafe,stroke:#2563eb,color:#1e3a8a;',
-  '  classDef ready fill:#fef3c7,stroke:#d97706,color:#78350f;',
-  '  classDef blocked fill:#fee2e2,stroke:#dc2626,color:#7f1d1d;'
-];
-
-const LINK_STYLES = {
-  completed: 'stroke:#16a34a,stroke-width:2px',
-  in_progress: 'stroke:#2563eb,stroke-width:3px',
-  ready: 'stroke:#d97706,stroke-width:2px,stroke-dasharray:6 4',
-  blocked: 'stroke:#dc2626,stroke-width:2px,stroke-dasharray:2 3'
-};
-
-export function generateGraphMarkdown(backlogText) {
-  const { work_items: items } = parseBacklog(backlogText);
-  const ordered = topologicalOrder(items);
-  const byId = new Map(items.map((item) => [item.id, item]));
-  const statuses = new Map(items.map((item) => [item.id, deriveExecutionStatus(item, byId).status]));
-  const edges = ordered.flatMap((source) =>
-    ordered
-      .filter((target) => target.depends_on.includes(source.id))
-      .map((target) => ({ source: source.id, target: target.id }))
-  );
-  const lines = [
-    '# Work-item dependency graph',
-    '',
-    '> Derived from `../backlog.yaml`. Do not edit this file manually.',
-    '',
-    '## Status',
-    '',
-    '- 🟩 **Completed** — accepted work.',
-    '- 🟦 **In Progress** — currently executing.',
-    '- 🟨 **Ready** — pending work with all dependencies satisfied.',
-    '- 🟥 **Blocked** — pending work with at least one incomplete work-item dependency.',
-    '',
-    '```mermaid',
-    "%%{init: {'flowchart': {'curve': 'linear', 'nodeSpacing': 32, 'rankSpacing': 54}} }%%",
-    'flowchart TD'
-  ];
-  for (const item of ordered) lines.push(`  ${item.id}["${escapeMermaid(item.id)}<br/>${escapeMermaid(item.title)}"]`);
-  lines.push('');
-  for (const edge of edges) lines.push(`  ${edge.source} --> ${edge.target}`);
-  lines.push('');
-  edges.forEach((edge, index) => lines.push(`  linkStyle ${index} ${LINK_STYLES[statuses.get(edge.source)]};`));
-  lines.push('', ...CLASSES);
-  for (const status of ['completed', 'in_progress', 'ready', 'blocked']) {
-    const ids = ordered.filter((item) => statuses.get(item.id) === status).map((item) => item.id);
-    if (ids.length) lines.push(`  class ${ids.join(',')} ${status};`);
-  }
-  lines.push(
-    '```',
-    '',
-    'Dependency arrows are authoritative for execution ordering. Flow executes one mutating task at a time; independent read-only research or review may run in parallel.',
-    ''
-  );
-  return lines.join('\n');
-}
-
-export function writeGraph(root) {
-  const backlogPath = path.join(root, '.flow', 'backlog.yaml');
-  if (!fs.existsSync(backlogPath)) throw new ArtifactValidationError(`Backlog not found: ${backlogPath}`);
-  const graphPath = path.join(root, '.flow', 'docs', 'graph.md');
-  fs.mkdirSync(path.dirname(graphPath), { recursive: true });
-  const markdown = generateGraphMarkdown(fs.readFileSync(backlogPath, 'utf8'));
-  const temporaryPath = `${graphPath}.${process.pid}.${Date.now()}.tmp`;
-  fs.writeFileSync(temporaryPath, markdown, 'utf8');
-  fs.renameSync(temporaryPath, graphPath);
-  return { graphPath, markdown };
-}
-
-export function runGraph({ args }) {
-  const result = writeGraph(projectRoot(args));
-  info(`Generated ${result.graphPath}`);
-}

package/src/commands/init.mjs

@@ -1,111 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { fail, info, promptMultiSelect, promptSelect, promptText } from '../shared/cli-io.mjs';
-import { defaultConfig, readConfig, writeConfig } from '../shared/project-config.mjs';
-import { projectRoot, valueAfter } from '../shared/project-path.mjs';
-import { installRuntimeSkill } from '../shared/skill-installer.mjs';
-import { BROWNFIELD_POLICIES, ENGINEERING_PROFILES } from '../shared/profiles.mjs';
-
-const RUNTIME_DEFINITIONS = {
-  codex: { label: 'Codex', skillsPath: '.codex/skills' },
-  claude: { label: 'Claude Code', skillsPath: '.claude/skills' }
-};
-function parseRuntimeFlag(args) {
-  const raw = valueAfter(args, '--runtime');
-  return raw
-    ? raw
-        .split(',')
-        .map((v) => v.trim().toLowerCase())
-        .filter(Boolean)
-    : null;
-}
-function missingBuiltinRuntimes(existing) {
-  const types = new Set(existing.map((r) => r.type));
-  return Object.keys(RUNTIME_DEFINITIONS).filter((type) => !types.has(type));
-}
-async function selectRuntimes(existing) {
-  const types = new Set(existing.map((r) => r.type));
-  const options = Object.entries(RUNTIME_DEFINITIONS)
-    .filter(([type]) => !types.has(type))
-    .map(([value, d]) => ({ value, label: d.label }));
-  options.push({ value: 'custom', label: 'Custom coding agent / skills path' });
-  return promptMultiSelect({
-    title: existing.length ? 'Select coding agents to add:' : 'Select coding agents:',
-    options
-  });
-}
-async function resolveRuntime(type, existing) {
-  if (RUNTIME_DEFINITIONS[type]) return { type, skills_path: RUNTIME_DEFINITIONS[type].skillsPath };
-  if (type !== 'custom') fail(`unsupported runtime '${type}'. Use codex, claude, or custom.`);
-  const fallback = `custom-${existing.filter((r) => r.type.startsWith('custom')).length + 1}`;
-  const name = await promptText('Custom coding agent id', fallback);
-  while (true) {
-    const skillsPath = await promptText('Project-local skills directory', `.${name}/skills`);
-    if (!path.isAbsolute(skillsPath) && !skillsPath.split(/[\\/]/).includes('..'))
-      return { type: name, skills_path: skillsPath };
-    info('Skills path must be relative and remain inside the project.');
-  }
-}
-async function selectEngineering(args, root, config, existed) {
-  const profileFlag = valueAfter(args, '--profile');
-  const brownfieldFlag = valueAfter(args, '--existing-code');
-  if (args.includes('--brownfield'))
-    fail(
-      'Use --existing-code improve|preserve: improve recommends clearer structure; preserve keeps consistent conventions.'
-    );
-  if (existed && (profileFlag || brownfieldFlag))
-    fail('Change engineering through /flow and human approval, not init.');
-  if (profileFlag && !ENGINEERING_PROFILES[profileFlag]) fail(`unknown engineering profile '${profileFlag}'.`);
-  if (brownfieldFlag && !BROWNFIELD_POLICIES[brownfieldFlag]) fail(`unknown brownfield policy '${brownfieldFlag}'.`);
-  if (profileFlag) config.engineering.profile = ENGINEERING_PROFILES[profileFlag].id;
-  const hasProjectFiles = fs
-    .readdirSync(root)
-    .some((name) => ['src', 'app', 'lib', 'packages'].includes(name) || /\.(m?[jt]sx?|py|java|go|rs|cs)$/.test(name));
-  if (brownfieldFlag) config.engineering.existing_code_policy = brownfieldFlag;
-  else if (!existed && hasProjectFiles)
-    config.engineering.existing_code_policy = await promptSelect({
-      title: 'How should Flow treat existing code conventions?',
-      options: Object.entries(BROWNFIELD_POLICIES).map(([value, policy]) => ({
-        value,
-        label: policy.label,
-        description: policy.description
-      }))
-    });
-}
-
-export async function runInit({ args, packageRoot }) {
-  const root = projectRoot(args);
-  const flowDirectory = path.join(root, '.flow');
-  const existed = fs.existsSync(flowDirectory);
-  const config = readConfig(root) || defaultConfig();
-  if (config.schema_version !== 2)
-    fail('Existing Flow project requires npx --no-install flow migrate before init. No files were changed.');
-  if (existed) info('Flow project already exists. Canonical project artifacts will not be created or modified.');
-  await selectEngineering(args, root, config, existed);
-  const requested = parseRuntimeFlag(args);
-  if (existed && !requested && missingBuiltinRuntimes(config.runtimes).length === 0) {
-    writeConfig(root, config);
-    for (const runtime of config.runtimes) installRuntimeSkill(root, runtime, packageRoot);
-    info('All built-in coding agents are already configured. Configuration is up to date.');
-    return;
-  }
-  const selected = requested || (await selectRuntimes(config.runtimes));
-  const known = new Set(config.runtimes.map((r) => r.type));
-  const added = [];
-  for (const type of selected) {
-    if (known.has(type)) continue;
-    const runtime = await resolveRuntime(type, config.runtimes);
-    if (known.has(runtime.type)) continue;
-    config.runtimes.push(runtime);
-    known.add(runtime.type);
-    added.push(runtime);
-  }
-  fs.mkdirSync(flowDirectory, { recursive: true });
-  writeConfig(root, config);
-  for (const runtime of config.runtimes)
-    info(`✓ ${runtime.type}: ${path.relative(root, installRuntimeSkill(root, runtime, packageRoot))}`);
-  info(`Engineering profile: ${ENGINEERING_PROFILES[config.engineering.profile]?.label ?? config.engineering.profile}`);
-  info(
-    'Flow is ready. Invoke /flow; engineering bootstrap runs before implementation when no approved contract exists.'
-  );
-}

package/src/commands/migrate.mjs

@@ -1,224 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { parse, stringify } from 'yaml';
-import { info } from '../shared/cli-io.mjs';
-import { projectRoot } from '../shared/project-path.mjs';
-import { emptyState, stringifyState } from '../artifacts/state.mjs';
-import { parseBacklog } from '../artifacts/backlog.mjs';
-import { parseTasks } from '../artifacts/tasks.mjs';
-import { generateGraphMarkdown } from './graph.mjs';
-import { readConfig, writeConfig, defaultConfig } from '../shared/project-config.mjs';
-
-const STATES = {
-  done: 'completed',
-  complete: 'completed',
-  completed: 'completed',
-  in_progress: 'in_progress',
-  blocked: 'pending',
-  pending: 'pending',
-  todo: 'pending'
-};
-function lifecycle(value) {
-  if (!STATES[value]) throw new Error(`Unknown legacy state '${value}'.`);
-  return STATES[value];
-}
-function number(value) {
-  const match = String(value).match(/\d+/);
-  if (!match) throw new Error(`Cannot normalize ID '${value}'.`);
-  return match[0].padStart(3, '0');
-}
-function temporarySibling(file) {
-  const directory = path.dirname(file);
-  const base = path.basename(file);
-  let attempt = 0;
-  let temporary;
-  do {
-    temporary = path.join(directory, `.${base}.flow-migration-${process.pid}-${Date.now()}-${attempt++}`);
-  } while (fs.existsSync(temporary));
-  return temporary;
-}
-function sameEntry(from, to) {
-  return fs.realpathSync.native(from) === fs.realpathSync.native(to);
-}
-function move(from, to) {
-  if (!fs.existsSync(from)) return;
-  if (path.resolve(from) === path.resolve(to)) return;
-  if (fs.existsSync(to)) {
-    if (!sameEntry(from, to)) throw new Error(`Migration destination already exists: ${to}`);
-    const temporary = temporarySibling(from);
-    fs.renameSync(from, temporary);
-    try {
-      fs.renameSync(temporary, to);
-    } catch (error) {
-      try {
-        fs.renameSync(temporary, from);
-      } catch (recoveryError) {
-        error.preserveRecoveryData = true;
-        error.recovery = { from, to, temporary, recoveryError };
-      }
-      throw error;
-    }
-    return;
-  }
-  fs.mkdirSync(path.dirname(to), { recursive: true });
-  fs.renameSync(from, to);
-}
-function normalizeTasks(file, item) {
-  const raw = parse(fs.readFileSync(file, 'utf8'));
-  const mapping = new Map();
-  const ids = new Set();
-  for (const task of raw.tasks ?? []) {
-    const match = String(task.id).match(/^(?:([A-Z]\d+)-)?T(\d+)$/);
-    if (!match || (match[1] && number(match[1]) !== item.id.slice(1)))
-      throw new Error(`Invalid/cross-work-item task ID '${task.id}'.`);
-    const id = `T${match[2].padStart(3, '0')}`;
-    if (ids.has(id)) throw new Error(`Task ID collision: ${id}`);
-    ids.add(id);
-    mapping.set(task.id, id);
-  }
-  const tasks = (raw.tasks ?? []).map((task) => {
-    const state = lifecycle(task.state ?? task.status ?? 'pending');
-    const result = {
-      ...task,
-      id: mapping.get(task.id),
-      state,
-      depends_on: (task.depends_on ?? []).map((dep) => {
-        if (!mapping.has(dep)) throw new Error(`Unknown task dependency '${dep}'.`);
-        return mapping.get(dep);
-      }),
-      implementation: state === 'completed' ? 'legacy' : task.implementation === 'none' ? 'none' : 'commit'
-    };
-    if (task.commit) result.legacy_commit = task.commit;
-    delete result.commit;
-    delete result.status;
-    delete result.execution_id;
-    return result;
-  });
-  const text = stringify({ schema_version: 1, work_item: item.id, tasks }, { lineWidth: 0 });
-  parseTasks(text, { expectedWorkItem: item.id });
-  fs.writeFileSync(file, text);
-}
-function migrateStaged(root) {
-  const flow = path.join(root, '.flow');
-  const oldConfig = readConfig(root);
-  const oldFile = path.join(flow, fs.existsSync(path.join(flow, 'BACKLOG.yaml')) ? 'BACKLOG.yaml' : 'backlog.yaml');
-  const raw = parse(fs.readFileSync(oldFile, 'utf8'));
-  const mapping = new Map();
-  const ids = new Set();
-  for (const item of raw.work_items ?? []) {
-    const id = `W${number(item.id)}`;
-    if (ids.has(id)) throw new Error(`Work-item ID collision: ${id}`);
-    ids.add(id);
-    mapping.set(item.id, id);
-  }
-  const original = new Map();
-  const work_items = (raw.work_items ?? []).map((item) => {
-    const id = mapping.get(item.id);
-    const folder = `${id}-${
-      String(item.folder ?? item.title)
-        .replace(/^(?:\d+[A-Za-z]|[A-Za-z]\d+)-?/, '')
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-|-$/g, '') || 'work-item'
-    }`;
-    original.set(id, item.folder);
-    return {
-      id,
-      folder,
-      title: item.title,
-      kind: item.kind,
-      state: lifecycle(item.state ?? item.status ?? 'pending'),
-      priority: item.priority ?? 1,
-      depends_on: (item.depends_on ?? []).map((dep) => {
-        if (!mapping.has(dep)) throw new Error(`Unknown work-item dependency '${dep}'.`);
-        return mapping.get(dep);
-      }),
-      blockers: []
-    };
-  });
-  const text = stringify({ schema_version: 2, work_items }, { lineWidth: 0 });
-  parseBacklog(text);
-  const workRoot = path.join(flow, 'work-items');
-  for (const item of work_items) {
-    const previous = path.join(workRoot, original.get(item.id) ?? item.folder);
-    const folder = path.join(workRoot, item.folder);
-    if (previous !== folder && fs.existsSync(previous)) move(previous, folder);
-    if (!fs.existsSync(folder)) {
-      if (item.state !== 'pending') throw new Error(`${item.id}: nonpending legacy work has no folder.`);
-      continue;
-    }
-    for (const [old, next] of [
-      ['SPEC.md', 'spec.md'],
-      ['TASKS.yaml', 'tasks.yaml'],
-      ['DECISIONS.md', 'legacy-decisions.md']
-    ])
-      move(path.join(folder, old), path.join(folder, next));
-    if (fs.existsSync(path.join(folder, 'tasks.yaml'))) normalizeTasks(path.join(folder, 'tasks.yaml'), item);
-  }
-  fs.mkdirSync(path.join(flow, 'docs'), { recursive: true });
-  fs.writeFileSync(path.join(flow, 'docs', 'legacy-backlog.yaml'), stringify(raw, { lineWidth: 0 }));
-  for (const [old, next] of [
-    ['PRD.md', 'prd.md'],
-    ['ENGINEERING.md', 'legacy-engineering.md'],
-    ['STATE.md', 'legacy-state.md'],
-    ['DECISIONS.md', 'legacy-decisions.md'],
-    ['SUMMARY.md', 'legacy-summary.md']
-  ])
-    move(path.join(flow, old), path.join(flow, 'docs', next));
-  if (fs.existsSync(path.join(flow, 'GRAPH.md'))) fs.unlinkSync(path.join(flow, 'GRAPH.md'));
-  if (oldFile.endsWith('BACKLOG.yaml')) move(oldFile, path.join(flow, 'backlog.yaml'));
-  fs.writeFileSync(path.join(flow, 'backlog.yaml'), text);
-  fs.writeFileSync(path.join(flow, 'docs', 'graph.md'), generateGraphMarkdown(text));
-  const state = emptyState();
-  state.execution.phase = 'migration_reconciliation';
-  state.migration.status = 'pending_reconciliation';
-  fs.writeFileSync(path.join(flow, 'state.yaml'), stringifyState(state));
-  if (!fs.existsSync(path.join(flow, 'gates.yaml')))
-    fs.writeFileSync(path.join(flow, 'gates.yaml'), 'schema_version: 1\ngates: []\n');
-  const config = defaultConfig();
-  config.runtimes = oldConfig?.runtimes ?? [];
-  config.engineering.existing_code_policy = 'improve';
-  writeConfig(root, config);
-}
-export function migrateProject(root) {
-  const flow = path.join(root, '.flow');
-  if (!fs.existsSync(flow)) throw new Error('.flow does not exist.');
-  const config = readConfig(root);
-  if (
-    config?.schema_version === 2 &&
-    fs.existsSync(path.join(flow, 'backlog.yaml')) &&
-    parse(fs.readFileSync(path.join(flow, 'backlog.yaml'), 'utf8')).schema_version === 2
-  )
-    return { unresolved: [], unchanged: true };
-  const staging = fs.mkdtempSync(path.join(root, '.flow-migration-'));
-  const backup = path.join(staging, 'backup');
-  const staged = path.join(staging, '.flow');
-  let preserveStaging = false;
-  try {
-    fs.cpSync(flow, staged, { recursive: true });
-    migrateStaged(staging);
-    fs.renameSync(flow, backup);
-    try {
-      fs.renameSync(staged, flow);
-    } catch (error) {
-      fs.renameSync(backup, flow);
-      throw error;
-    }
-    return { unresolved: ['semantic reconciliation'], unchanged: false };
-  } catch (error) {
-    preserveStaging = Boolean(error?.preserveRecoveryData);
-    throw error;
-  } finally {
-    // Retain the original backup if even rollback failed; never delete the only copy.
-    if (!preserveStaging && (!fs.existsSync(backup) || fs.existsSync(flow)))
-      fs.rmSync(staging, { recursive: true, force: true });
-  }
-}
-export function runMigrate({ args }) {
-  const result = migrateProject(projectRoot(args));
-  info(
-    result.unchanged
-      ? 'Already migrated; no files changed.'
-      : 'Structural migration complete. Invoke /flow for semantic reconciliation before implementation.'
-  );
-}