@caiqueoak/flow 0.4.0 → 0.5.1

package/src/cli.mjs

@@ -2,331 +2,49 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import readline from 'node:readline/promises';
-import { stdin as inputStream, stdout as outputStream } from 'node:process';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const ROOT = path.resolve(__dirname, '..');
-const PACKAGE = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
-const VERSION = PACKAGE.version;
-const PACKAGE_NAME = PACKAGE.name;
-const args = process.argv.slice(2);
-
-const RUNTIME_DEFINITIONS = {
-  codex: { label: 'Codex', skillsPath: '.codex/skills' },
-  claude: { label: 'Claude Code', skillsPath: '.claude/skills' }
+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 fail(message, code = 1) { console.error(`flow: ${message}`); process.exit(code); }
-function info(message = '') { console.log(message); }
-function hasFlag(name) { return args.includes(name); }
-function valueAfter(name) { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; }
-function npmCommand() { return process.platform === 'win32' ? 'npm.cmd' : 'npm'; }
-function projectRoot() { return path.resolve(valueAfter('--path') || process.cwd()); }
-function configPath(root) { return path.join(root, '.flow', 'config.yaml'); }
-function packagePath(root) { return path.join(root, 'node_modules', '@caiqueoak', 'flow'); }
-
-function abortedPromptError() {
-  const error = new Error('Prompt aborted.');
-  error.code = 'ABORT_ERR';
-  return error;
-}
-
-function question(rl, message) {
-  return new Promise((resolve, reject) => {
-    let settled = false;
-    const finish = (callback, value) => {
-      if (settled) return;
-      settled = true;
-      rl.removeListener('close', onClose);
-      callback(value);
-    };
-    const onClose = () => finish(reject, abortedPromptError());
-    rl.once('close', onClose);
-    rl.question(message).then(
-      (answer) => finish(resolve, answer),
-      (error) => finish(reject, error)
-    );
-  });
-}
-
-function runNpm(npmArgs, options = {}) {
-  if (process.platform === 'win32') {
-    return execFileSync(process.env.ComSpec || 'cmd.exe', ['/d', '/s', '/c', npmCommand(), ...npmArgs], options);
-  }
-  return execFileSync(npmCommand(), npmArgs, {
-    ...options
-  });
-}
-
-function copyDir(source, target) {
-  fs.mkdirSync(target, { recursive: true });
-  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
-    const src = path.join(source, entry.name);
-    const dst = path.join(target, entry.name);
-    if (entry.isDirectory()) copyDir(src, dst);
-    else fs.copyFileSync(src, dst);
-  }
-}
-
-function quoteYaml(value) { return /^[A-Za-z0-9_.\/-]+$/.test(value) ? value : JSON.stringify(value); }
-function defaultConfig() {
-  return { frameworkVersion: VERSION, runtimes: [], continueAcrossWorkItems: true, workItemsConcurrency: 'auto', taskConcurrency: 'auto' };
-}
-
-function readConfig(root) {
-  const file = configPath(root);
-  if (!fs.existsSync(file)) return null;
-  const text = fs.readFileSync(file, 'utf8');
-  const cfg = defaultConfig();
-  const v = text.match(/^[ \t]*version:[ \t]*([^\s#]+)[ \t]*$/m);
-  if (v) cfg.frameworkVersion = v[1].replace(/^['"]|['"]$/g, '');
-  const runtimeBlock = text.match(/^runtimes:\s*\n([\s\S]*?)(?=^[A-Za-z_][A-Za-z0-9_]*:|\Z)/m)?.[1] || '';
-  const entries = runtimeBlock.split(/(?=^\s*-\s+type:)/m).filter((x) => /-\s+type:/.test(x));
-  for (const entry of entries) {
-    const type = entry.match(/-\s+type:\s*([^\s#]+)/)?.[1]?.replace(/^['"]|['"]$/g, '');
-    const skillsPath = entry.match(/skills_path:\s*([^\n#]+)/)?.[1]?.trim().replace(/^['"]|['"]$/g, '');
-    if (type && skillsPath) cfg.runtimes.push({ type, skills_path: skillsPath });
-  }
-  return cfg;
-}
-
-function writeConfig(root, config) {
-  const lines = ['schema_version: 1', 'framework:', '  name: flow', `  version: ${VERSION}`, 'runtimes:'];
-  if (!config.runtimes.length) lines.push('  []');
-  else for (const runtime of config.runtimes) {
-    lines.push(`  - type: ${quoteYaml(runtime.type)}`);
-    lines.push(`    skills_path: ${quoteYaml(runtime.skills_path)}`);
-  }
-  lines.push('autonomy:', '  continue_across_work_items: true', '  stop_on:', '    - consequential_decision', '    - external_approval', '    - unrecoverable_blocker', '    - no_ready_work', 'parallelism:', '  strategy: maximum_safe', '  max_concurrent_work_items: auto', '  max_concurrent_tasks_per_work_item: auto', 'efficiency:', '  token_usage: optimize', '  prefer_primary_orchestrator: true', '  delegate_only_when_beneficial: true', '');
-  fs.mkdirSync(path.join(root, '.flow'), { recursive: true });
-  fs.writeFileSync(configPath(root), lines.join('\n'), 'utf8');
-}
-
-function installRuntimeSkill(root, runtime, packageRoot = ROOT) {
-  const target = path.join(root, runtime.skills_path, 'flow');
-  copyDir(path.join(packageRoot, 'skills', 'flow'), target);
-  return target;
-}
-function parseRuntimeFlag() {
-  const raw = valueAfter('--runtime');
-  return raw ? raw.split(',').map((x) => x.trim().toLowerCase()).filter(Boolean) : null;
-}
-
-function missingBuiltinRuntimes(existing) {
-  const existingTypes = new Set(existing.map((r) => r.type));
-  return Object.keys(RUNTIME_DEFINITIONS).filter((type) => !existingTypes.has(type));
-}
-
-async function promptMultiSelect(existing) {
-  const existingTypes = new Set(existing.map((r) => r.type));
-  const options = Object.entries(RUNTIME_DEFINITIONS).filter(([type]) => !existingTypes.has(type)).map(([value, def]) => ({ value, label: def.label }));
-  options.push({ value: 'custom', label: 'Custom coding agent / skills path' });
-  info(existing.length ? 'Select coding agents to add:' : 'Select coding agents:');
-  options.forEach((opt, i) => info(`  [ ] ${i + 1}. ${opt.label}`));
-  info('  (Select multiple with comma-separated numbers, e.g. 1,2)');
-  const rl = readline.createInterface({ input: inputStream, output: outputStream });
-  try {
-    while (true) {
-      const answer = (await question(rl, 'Selection: ')).trim();
-      const indices = [...new Set(answer.split(',').map((v) => Number.parseInt(v.trim(), 10)).filter(Number.isInteger))];
-      if (indices.length && indices.every((n) => n >= 1 && n <= options.length)) return indices.map((n) => options[n - 1].value);
-      info('Choose one or more valid numbers.');
-    }
-  } finally { rl.close(); }
-}
-
-async function promptText(message, defaultValue = '') {
-  const rl = readline.createInterface({ input: inputStream, output: outputStream });
-  try {
-    const answer = (await question(rl, `${message}${defaultValue ? ` [${defaultValue}]` : ''}: `)).trim();
-    return answer || defaultValue;
-  } finally { rl.close(); }
-}
-
-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 initProject() {
-  const root = projectRoot();
-  const flowDir = path.join(root, '.flow');
-  const existed = fs.existsSync(flowDir);
-  const config = readConfig(root) || defaultConfig();
-  if (existed) {
-    info('Flow project already exists. Canonical project artifacts will not be created or modified.');
-    if (config.runtimes.length) info(`Configured coding agents: ${config.runtimes.map((r) => r.type).join(', ')}`);
-  }
-
-  const requested = parseRuntimeFlag();
-  if (existed && !requested && missingBuiltinRuntimes(config.runtimes).length === 0) {
-    info('All built-in coding agents are already configured. Nothing to add.');
-    info('Use --runtime custom only when you intentionally want to add a custom coding agent.');
-    return;
-  }
-
-  const selected = requested || await promptMultiSelect(config.runtimes);
-  const knownTypes = new Set(config.runtimes.map((r) => r.type));
-  const added = [];
-  for (const type of selected) {
-    if (knownTypes.has(type)) continue;
-    const runtime = await resolveRuntime(type, config.runtimes);
-    if (knownTypes.has(runtime.type)) continue;
-    config.runtimes.push(runtime); knownTypes.add(runtime.type); added.push(runtime);
-  }
-  fs.mkdirSync(flowDir, { recursive: true });
-  writeConfig(root, config);
-  for (const runtime of added) info(`✓ ${runtime.type}: ${path.relative(root, installRuntimeSkill(root, runtime))}`);
-  if (!added.length) info('No new coding-agent integration was added.');
-  else { info(); info('Flow is ready. Open a configured coding agent and invoke /flow.'); }
-}
-
-function containingNodeModules(packageRoot) {
-  let current = path.resolve(packageRoot);
-  while (true) {
-    if (path.basename(current).toLowerCase() === 'node_modules') return current;
-    const parent = path.dirname(current);
-    if (parent === current) return null;
-    current = parent;
-  }
-}
-
-function installedPackageVersion(packageRoot) {
-  const manifest = path.join(packageRoot, 'package.json');
-  if (!fs.existsSync(manifest)) return null;
-  return JSON.parse(fs.readFileSync(manifest, 'utf8')).version || null;
-}
-
-function lockedPackageVersion(root) {
-  const lockfile = path.join(root, 'package-lock.json');
-  if (!fs.existsSync(lockfile)) return null;
-  try {
-    return JSON.parse(fs.readFileSync(lockfile, 'utf8')).packages?.[`node_modules/${PACKAGE_NAME}`]?.version || null;
-  } catch { return null; }
-}
-
-function globalUpdatePlan(root) {
-  try {
-    const globalNodeModules = path.resolve(runNpm(['root', '--global'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim());
-    const globalPackageRoot = path.join(globalNodeModules, '@caiqueoak', 'flow');
-    if (path.resolve(ROOT).startsWith(`${globalNodeModules}${path.sep}`) && fs.existsSync(path.join(globalPackageRoot, 'package.json'))) {
-      return {
-        npmArgs: ['update', '--global', PACKAGE_NAME],
-        cwd: root,
-        packageRoot: globalPackageRoot,
-        mode: 'global'
-      };
-    }
-  } catch { /* fall through to local installation detection */ }
-  return null;
-}
-
-function updatePlan(root) {
-  const global = globalUpdatePlan(root);
-  if (global) return global;
-
-  const nodeModules = containingNodeModules(ROOT);
-  if (nodeModules) {
-    const installRoot = path.dirname(nodeModules);
-    return {
-      npmArgs: ['update', PACKAGE_NAME],
-      cwd: installRoot,
-      packageRoot: ROOT,
-      mode: 'local'
-    };
-  }
-
-  const projectPackageRoot = packagePath(root);
-  if (fs.existsSync(path.join(projectPackageRoot, 'package.json'))) {
-    return {
-      npmArgs: ['update', PACKAGE_NAME],
-      cwd: root,
-      packageRoot: projectPackageRoot,
-      mode: 'project'
-    };
-  }
-
-  fail('cannot determine how this Flow CLI was installed. Reinstall @caiqueoak/flow with npm, then run flow update again.');
-}
-
-function repairDivergentProjectInstall(plan) {
-  if (plan.mode === 'global') return;
-  const expected = lockedPackageVersion(plan.cwd);
-  const actual = installedPackageVersion(plan.packageRoot);
-  if (!expected || !actual || expected === actual) return;
-
-  const backup = path.join(plan.cwd, `.flow-update-backup-${process.pid}-${Date.now()}`);
-  info(`Repairing divergent ${PACKAGE_NAME} installation (${actual} on disk, ${expected} in package-lock.json)...`);
-  fs.renameSync(plan.packageRoot, backup);
-  try {
-    runNpm(['install'], { cwd: plan.cwd, stdio: 'inherit' });
-    if (installedPackageVersion(plan.packageRoot) !== expected) {
-      throw new Error(`npm install did not restore ${PACKAGE_NAME}@${expected}.`);
-    }
-    fs.rmSync(backup, { recursive: true, force: true });
-  } catch (error) {
-    try {
-      fs.rmSync(plan.packageRoot, { recursive: true, force: true });
-      fs.renameSync(backup, plan.packageRoot);
-    } catch { /* preserve the original npm error below */ }
-    throw error;
-  }
-}
-
-function update() {
-  const root = projectRoot();
-  const config = readConfig(root);
-  if (!config) fail('this project is not initialized. Run flow init first.');
-  if (!config.runtimes.length) fail('no coding agents are configured. Run flow init to add one.');
-
-  const plan = updatePlan(root);
-  info(`Updating ${PACKAGE_NAME} (${plan.mode} installation)...`);
-  try {
-    repairDivergentProjectInstall(plan);
-    runNpm(plan.npmArgs, { cwd: plan.cwd, stdio: 'inherit' });
-  } catch { fail('npm update failed. Existing project state and installed skills were not intentionally removed.'); }
-
-  if (!fs.existsSync(path.join(plan.packageRoot, 'package.json'))) fail(`updated package not found at ${plan.packageRoot}.`);
-  const latest = JSON.parse(fs.readFileSync(path.join(plan.packageRoot, 'package.json'), 'utf8'));
-  for (const runtime of config.runtimes) info(`✓ ${runtime.type}: ${path.relative(root, installRuntimeSkill(root, runtime, plan.packageRoot))}`);
-  const text = fs.readFileSync(configPath(root), 'utf8');
-  fs.writeFileSync(configPath(root), text.replace(/(^framework:\s*\n(?:.*\n)*?\s+version:\s*)[^\n]+/m, `$1${latest.version}`), 'utf8');
-  info(`Flow updated to ${latest.version}.`);
-}
-
-async function graph() {
-  const { writeGraph } = await import('./graph.mjs');
-  const result = writeGraph(projectRoot());
-  info(`Generated ${result.graphPath}`);
-}
-
 function help() {
-  info(`Flow ${VERSION}\n\nUsage:\n  flow init [--path <project>] [--runtime codex,claude]\n  flow update [--path <project>]\n  flow graph [--path <project>]\n  flow --version\n\nflow init creates only .flow/config.yaml and installs the project-local /flow skill for selected coding agents.\nIf .flow already exists, init only adds coding-agent integrations and exits without prompting when all built-in integrations are already configured.\nflow update updates the installation that provides the Flow CLI (project-local or global) and refreshes every configured project-local skill.\nflow graph deterministically projects .flow/BACKLOG.yaml into .flow/GRAPH.md. There is no flow install command and no automatic/background update mechanism.`);
+  info(
+    `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 {
-  if (!args.length || hasFlag('--help') || hasFlag('-h')) help();
-  else if (hasFlag('--version') || hasFlag('-v')) info(VERSION);
-  else if (args[0] === 'init') await initProject();
-  else if (args[0] === 'update') update();
-  else if (args[0] === 'graph') await graph();
-  else fail(`unknown command '${args[0]}'. Run flow --help.`);
+  await runCli();
 } catch (error) {
   if (error?.code === 'ABORT_ERR') {
     info('\nFlow command canceled.');
     process.exitCode = 130;
-  } else {
-    throw error;
-  }
+  } else if (error instanceof CliError) {
+    console.error(`flow: ${error.message}`);
+    process.exitCode = error.exitCode || 1;
+  } else throw error;
 }

package/src/commands/gates.mjs

@@ -0,0 +1,68 @@
+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) => {
+    if (gate.kind === 'command') return runCommandGate(root, gate);
+    if (gate.kind === 'builtin') return runBuiltinGate(root, gate);
+    throw new Error(`Unsupported gate kind '${gate.kind}'.`);
+  });
+}

package/src/commands/graph.mjs

@@ -0,0 +1,83 @@
+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;'
+];
+
+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 dependency or explicit external blocker.',
+    '',
+    '```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('', ...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

@@ -0,0 +1,111 @@
+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.'
+  );
+}