@caiqueoak/flow 0.4.0 → 0.5.0

package/src/commands/migrate.mjs

@@ -0,0 +1,189 @@
+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 move(from, to) {
+  if (!fs.existsSync(from)) return;
+  if (fs.existsSync(to)) throw new Error(`Migration destination already exists: ${to}`);
+  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')) fs.unlinkSync(oldFile);
+  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');
+  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 };
+  } finally {
+    // Retain the original backup if even rollback failed; never delete the only copy.
+    if (!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.'
+  );
+}

package/src/commands/route.mjs

@@ -0,0 +1,135 @@
+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 { readConfig } from '../shared/project-config.mjs';
+import { parseBacklog, deriveExecutionStatus } from '../artifacts/backlog.mjs';
+import { parseTasks, qualifiedTaskId } from '../artifacts/tasks.mjs';
+import { validateEngineeringDocument } from '../artifacts/engineering.mjs';
+import { validatePrdDocument } from '../artifacts/prd.mjs';
+import { validateImplementationPlan } from '../artifacts/implementation-plan.mjs';
+import { parseState } from '../artifacts/state.mjs';
+
+function step(phase, instruction, extra = {}) {
+  return { action: 'continue', phase, instruction, ...extra };
+}
+function awaitApproval(phase, instruction, extra = {}) {
+  return { action: 'stop', reason: 'consequential_decision', phase, instruction, ...extra };
+}
+function artifactApproval(file, validator, phase, draftInstruction, approvalInstruction) {
+  if (!fs.existsSync(file)) return step(phase, draftInstruction);
+  const result = validator(fs.readFileSync(file, 'utf8'));
+  if (result.errors.length) return step(phase, draftInstruction, { details: result.errors });
+  if (result.status !== 'approved') return awaitApproval(phase, approvalInstruction);
+  return null;
+}
+export function routeProject(root) {
+  const flow = path.join(root, '.flow');
+  const config = readConfig(root);
+  if (!config) return { action: 'stop', reason: 'unrecoverable_blocker', details: 'Run npx --no-install flow init.' };
+  if (config.schema_version !== 2)
+    return { action: 'stop', reason: 'unrecoverable_blocker', details: 'Run npx --no-install flow migrate.' };
+  const read = (relative) => fs.readFileSync(path.join(flow, relative), 'utf8');
+  const exists = (relative) => fs.existsSync(path.join(flow, relative));
+  const state = exists('state.yaml') ? parseState(read('state.yaml')) : null;
+  if (state?.migration.status === 'pending_reconciliation')
+    return step('migration_reconciliation', 'migration/step-01-reconcile.md', {
+      required_context: [
+        'backlog.yaml',
+        'docs/prd.md',
+        'docs/legacy-state.md',
+        'docs/legacy-decisions.md',
+        'docs/legacy-engineering.md'
+      ]
+        .filter(exists)
+        .map((file) => `.flow/${file}`)
+    });
+  if (state?.stop_reason && state.stop_reason !== 'finished')
+    return { action: 'stop', reason: state.stop_reason, phase: state.execution.phase, step: state.execution.step };
+  const productRoute = artifactApproval(
+    path.join(flow, 'docs/prd.md'),
+    validatePrdDocument,
+    'discovery',
+    'discovery/step-01-project.md',
+    'discovery/step-02-await-approval.md'
+  );
+  if (productRoute) return productRoute;
+  const engineeringRoute = artifactApproval(
+    path.join(flow, 'docs/engineering.md'),
+    validateEngineeringDocument,
+    'engineering',
+    'engineering/step-02-synthesize.md',
+    'engineering/step-05-present.md'
+  );
+  if (engineeringRoute) return engineeringRoute;
+  const engineeringText = read('docs/engineering.md');
+  const planning = () =>
+    step('backlog_planning', 'planning/step-01-plan-work-item.md', {
+      required_context: ['.flow/docs/prd.md', '.flow/docs/engineering.md']
+    });
+  if (!exists('backlog.yaml')) return planning();
+  const backlog = parseBacklog(read('backlog.yaml'));
+  for (const item of backlog.work_items) {
+    if (!exists(`work-items/${item.folder}/spec.md`) || !exists(`work-items/${item.folder}/tasks.yaml`))
+      return planning();
+    parseTasks(read(`work-items/${item.folder}/tasks.yaml`), { expectedWorkItem: item.id });
+  }
+  const byId = new Map(backlog.work_items.map((item) => [item.id, item]));
+  const active = backlog.work_items.find((item) => item.state === 'in_progress');
+  if (active && deriveExecutionStatus(active, byId).status === 'blocked')
+    return {
+      action: 'stop',
+      reason: 'external_action',
+      work_item: active.id,
+      details: deriveExecutionStatus(active, byId).reasons
+    };
+  const item =
+    active ??
+    backlog.work_items
+      .filter((item) => deriveExecutionStatus(item, byId).status === 'ready')
+      .sort((a, b) => a.priority - b.priority || Number(a.id.slice(1)) - Number(b.id.slice(1)))[0];
+  if (!item)
+    return {
+      action: 'stop',
+      reason: backlog.work_items.every((item) => item.state === 'completed') ? 'finished' : 'external_action'
+    };
+  const base = `work-items/${item.folder}`;
+  const context = ['.flow/docs/engineering.md', `.flow/${base}/spec.md`, `.flow/${base}/tasks.yaml`];
+  const tasks = parseTasks(read(`${base}/tasks.yaml`), { expectedWorkItem: item.id });
+  const extra = { work_item: item.id, required_context: context };
+  const prepare = () => step('work_item_plan_approval', 'planning/step-02-prepare-plan.md', extra);
+  if (!exists(`${base}/implementation-plan.md`)) return prepare();
+  const plan = validateImplementationPlan(read(`${base}/implementation-plan.md`), {
+    workItem: item.id,
+    engineeringText,
+    specText: read(`${base}/spec.md`)
+  });
+  if (plan.errors.length) return prepare();
+  if (plan.status !== 'approved')
+    return awaitApproval('work_item_plan_approval', 'planning/step-03-await-approval.md', extra);
+  context.push(`.flow/${base}/implementation-plan.md`);
+  const taskById = new Map(tasks.tasks.map((task) => [task.id, task]));
+  const task =
+    tasks.tasks.find((task) => task.state === 'in_progress') ??
+    tasks.tasks
+      .filter(
+        (task) => task.state === 'pending' && task.depends_on.every((id) => taskById.get(id).state === 'completed')
+      )
+      .sort((a, b) => Number(a.id.slice(1)) - Number(b.id.slice(1)))[0];
+  if (task)
+    return step('implementation', 'build/step-01-execute-task.md', {
+      ...extra,
+      task: qualifiedTaskId(item.id, task.id)
+    });
+  if (tasks.tasks.every((task) => task.state === 'completed'))
+    return step('work_item_review', 'review/step-01-review-work-item.md', extra);
+  return step('reconcile', 'reconcile/step-01-reconcile.md', extra);
+}
+export function runRoute({ args }) {
+  const result = routeProject(projectRoot(args));
+  info(
+    args.includes('--json')
+      ? JSON.stringify(result, null, 2)
+      : `${result.action}: ${result.phase ?? result.reason}${result.work_item ? ` ${result.work_item}` : ''}`
+  );
+}

package/src/commands/status.mjs

@@ -0,0 +1,32 @@
+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 { deriveExecutionStatus, parseBacklog } from '../artifacts/backlog.mjs';
+import { routeProject } from './route.mjs';
+
+export function runStatus({ args }) {
+  const root = projectRoot(args);
+  if (!fs.existsSync(path.join(root, '.flow', 'backlog.yaml')))
+    return info(`Next: ${routeProject(root).phase ?? 'setup'}`);
+  const backlog = parseBacklog(fs.readFileSync(path.join(root, '.flow', 'backlog.yaml'), 'utf8'));
+  const byId = new Map(backlog.work_items.map((item) => [item.id, item]));
+  const groups = new Map(['in_progress', 'ready', 'blocked', 'completed'].map((status) => [status, []]));
+  for (const item of backlog.work_items) {
+    const derived = deriveExecutionStatus(item, byId);
+    groups.get(derived.status).push({ ...item, reasons: derived.reasons });
+  }
+  const lines = [];
+  for (const [status, items] of groups) {
+    if (!items.length) continue;
+    lines.push(status.replace('_', ' ').replace(/^./, (c) => c.toUpperCase()));
+    for (const item of items) {
+      const deps = item.reasons.filter((r) => r.type === 'dependency').map((r) => r.ref);
+      lines.push(`  ${item.id} — ${item.title}${deps.length ? ` ← ${deps.join(', ')}` : ''}`);
+      for (const reason of item.reasons.filter((reason) => reason.type !== 'dependency'))
+        lines.push(`    ${reason.type}: ${reason.description} [${reason.id}]`);
+    }
+    lines.push('');
+  }
+  info(lines.join('\n').trim());
+}

package/src/commands/trace.mjs

@@ -0,0 +1,44 @@
+import { execFileSync } from 'node:child_process';
+import { info, fail } from '../shared/cli-io.mjs';
+import { projectRoot } from '../shared/project-path.mjs';
+
+export function traceTask(root, qualifiedTaskId) {
+  if (!/^W\d{3,}-T\d{3,}$/.test(qualifiedTaskId))
+    fail(`invalid qualified task ID '${qualifiedTaskId}'. Expected W015-T003.`);
+  let output;
+  try {
+    output = execFileSync(
+      'git',
+      ['log', 'HEAD', '--fixed-strings', `--grep=Flow-Task: ${qualifiedTaskId}`, '--format=%H%x1f%s%x1f%B%x1e'],
+      { cwd: root, encoding: 'utf8' }
+    );
+  } catch {
+    fail('git history is unavailable; task traceability requires a Git repository.');
+  }
+  const trailerPattern = new RegExp(`^Flow-Task:\\s*${qualifiedTaskId}\\s*$`, 'm');
+  const matches = output
+    .split('\x1e')
+    .filter(Boolean)
+    .map((record) => {
+      const [sha, subject, ...bodyParts] = record.replace(/^\n+|\n+$/g, '').split('\x1f');
+      return { sha, subject, body: bodyParts.join('\x1f') };
+    })
+    .filter(
+      (entry) =>
+        trailerPattern.test(entry.body) &&
+        new RegExp(`^Flow-Work-Item:\\s*${qualifiedTaskId.split('-')[0]}\\s*$`, 'm').test(entry.body)
+    );
+  if (!matches.length) return { task: qualifiedTaskId, commits: [], status: 'missing' };
+  if (matches.length > 1) return { task: qualifiedTaskId, commits: matches, status: 'ambiguous' };
+  return { task: qualifiedTaskId, commit: matches[0], commits: matches, status: 'resolved' };
+}
+
+export function runTrace({ args }) {
+  const task = args.find((arg) => !arg.startsWith('--'));
+  if (!task) fail('flow trace requires a qualified task ID, e.g. W015-T003.');
+  const result = traceTask(projectRoot(args), task);
+  if (args.includes('--json')) return info(JSON.stringify(result, null, 2));
+  if (result.status === 'missing') fail(`No reachable commit declares Flow-Task: ${task}.`);
+  if (result.status === 'ambiguous') fail(`Multiple reachable commits declare Flow-Task: ${task}.`);
+  info(`${task} -> ${result.commit.sha}\n${result.commit.subject}`);
+}

package/src/commands/validate.mjs

@@ -0,0 +1,174 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { info, fail } from '../shared/cli-io.mjs';
+import { projectRoot } from '../shared/project-path.mjs';
+import { readConfig } from '../shared/project-config.mjs';
+import { parseBacklog, deriveExecutionStatus } from '../artifacts/backlog.mjs';
+import { parseTasks, qualifiedTaskId } from '../artifacts/tasks.mjs';
+import { parseState } from '../artifacts/state.mjs';
+import { parseGates } from '../artifacts/gates.mjs';
+import { validateEngineeringDocument } from '../artifacts/engineering.mjs';
+import { validatePrdDocument } from '../artifacts/prd.mjs';
+import { validateImplementationPlan } from '../artifacts/implementation-plan.mjs';
+import { traceTask } from './trace.mjs';
+import { generateGraphMarkdown } from './graph.mjs';
+import { evaluateGates } from './gates.mjs';
+
+export function validateProject(root, { preCommitTask = null, skipTrace = false } = {}) {
+  const findings = [];
+  const error = (code, message) => findings.push({ level: 'error', code, message });
+  const flow = path.join(root, '.flow');
+  const exists = (relative) => fs.existsSync(path.join(flow, relative));
+  const read = (relative) => fs.readFileSync(path.join(flow, relative), 'utf8');
+  let config;
+  try {
+    config = readConfig(root);
+  } catch (failure) {
+    error('CONFIG', failure.message);
+  }
+  if (!config || config.schema_version !== 2) {
+    error('CONFIG', 'Initialize Flow or migrate the existing project.');
+    return findings;
+  }
+  if (
+    config.engineering.profile !== 'flow/readability-first@1' ||
+    !['improve', 'preserve', 'not_applicable'].includes(config.engineering.existing_code_policy)
+  )
+    error('CONFIG', 'Invalid engineering bootstrap preferences.');
+  for (const name of ['STATE.md', 'DECISIONS.md', 'SUMMARY.md', 'BACKLOG.yaml', 'PRD.md', 'ENGINEERING.md', 'GRAPH.md'])
+    if (exists(name)) error('LEGACY', `${name} must be migrated.`);
+  let state;
+  try {
+    state = exists('state.yaml') ? parseState(read('state.yaml')) : null;
+  } catch (failure) {
+    error('STATE', failure.message);
+  }
+  const migrationPending = state?.migration.status === 'pending_reconciliation';
+  const backlogRequired = [
+    'backlog_planning',
+    'work_item_plan_approval',
+    'implementation',
+    'work_item_review',
+    'complete'
+  ].includes(state?.execution.phase);
+  if (!exists('backlog.yaml')) {
+    if (backlogRequired) error('MISSING', 'Missing backlog.yaml.');
+    return findings;
+  }
+  let backlog;
+  try {
+    backlog = parseBacklog(read('backlog.yaml'));
+  } catch (failure) {
+    error('BACKLOG', failure.message);
+    return findings;
+  }
+  const anyStarted = backlog.work_items.some((item) => item.state !== 'pending');
+  if (!migrationPending) {
+    for (const [name, validator] of [
+      ['prd.md', validatePrdDocument],
+      ['engineering.md', validateEngineeringDocument]
+    ]) {
+      if (!exists(`docs/${name}`)) {
+        error('MISSING', `Missing docs/${name}.`);
+        continue;
+      }
+      const document = validator(read(`docs/${name}`));
+      for (const message of document.errors) error('DOCUMENT', `${name}: ${message}`);
+      if (anyStarted && document.status !== 'approved')
+        error('APPROVAL', `${name} must be approved before implementation.`);
+    }
+  }
+  const byId = new Map(backlog.work_items.map((item) => [item.id, item]));
+  let activeTasks = 0;
+  for (const item of backlog.work_items) {
+    const base = `work-items/${item.folder}`;
+    const missing = ['spec.md', 'tasks.yaml'].filter((name) => !exists(`${base}/${name}`));
+    if (missing.length) {
+      if (!(migrationPending && item.state === 'pending'))
+        error('WORK_ITEM', `${item.id} is missing ${missing.join(', ')}.`);
+      continue;
+    }
+    let tasks;
+    try {
+      tasks = parseTasks(read(`${base}/tasks.yaml`), { expectedWorkItem: item.id });
+    } catch (failure) {
+      error('TASKS', failure.message);
+      continue;
+    }
+    const historical = tasks.tasks.length > 0 && tasks.tasks.every((task) => task.implementation === 'legacy');
+    activeTasks += tasks.tasks.filter((task) => task.state === 'in_progress').length;
+    if (tasks.tasks.some((task) => task.state === 'in_progress') && item.state !== 'in_progress')
+      error('STATE', `${item.id}: active task requires active work item.`);
+    if (item.state === 'completed' && tasks.tasks.some((task) => task.state !== 'completed'))
+      error('STATE', `${item.id}: completed work has incomplete tasks.`);
+    if (item.state === 'in_progress' && deriveExecutionStatus(item, byId).status === 'blocked')
+      error('STATE', `${item.id}: active work is blocked.`);
+    if (!historical && !migrationPending) {
+      const spec = read(`${base}/spec.md`);
+      for (const heading of [
+        '## Status',
+        '## Goal',
+        '## Scope',
+        '## Non-goals',
+        '## Requirements',
+        '## Acceptance criteria',
+        '## Decisions'
+      ])
+        if (!spec.split(/\r?\n/).includes(heading)) error('SPEC', `${item.id} missing ${heading}.`);
+      const planPath = `${base}/implementation-plan.md`;
+      if (!exists(planPath)) {
+        if (item.state !== 'pending') error('PLAN', `${item.id} requires an approved implementation plan.`);
+      } else if (exists('docs/engineering.md')) {
+        const plan = validateImplementationPlan(read(planPath), {
+          workItem: item.id,
+          engineeringText: read('docs/engineering.md'),
+          specText: spec,
+          checkRevisions: item.state !== 'completed'
+        });
+        for (const message of plan.errors) error('PLAN', `${item.id}: ${message}`);
+        if (item.state !== 'pending' && plan.status !== 'approved') error('PLAN', `${item.id}: plan is not approved.`);
+      }
+    }
+    for (const task of tasks.tasks) {
+      if (task.state !== 'completed' || task.implementation !== 'commit' || skipTrace) continue;
+      const qualified = qualifiedTaskId(item.id, task.id);
+      if (qualified === preCommitTask) continue;
+      try {
+        if (traceTask(root, qualified).status !== 'resolved')
+          error('TRACE', `${qualified}: expected exactly one HEAD-reachable commit with both Flow trailers.`);
+      } catch (failure) {
+        error('TRACE', failure.message);
+      }
+    }
+  }
+  if (activeTasks > 1) error('STATE', 'Only one mutating task may be active across the project.');
+  if (exists('gates.yaml')) {
+    try {
+      parseGates(read('gates.yaml'));
+      if (!migrationPending)
+        for (const gate of evaluateGates(root))
+          if (gate.blocking && ['failed', 'unsupported'].includes(gate.status))
+            error('GATE', `${gate.id}: ${gate.status}`);
+    } catch (failure) {
+      error('GATES', failure.message);
+    }
+  } else if (!migrationPending) error('MISSING', 'Missing gates.yaml.');
+  if (!exists('docs/graph.md') || read('docs/graph.md') !== generateGraphMarkdown(read('backlog.yaml')))
+    error('GRAPH', 'Graph is stale; run npx --no-install flow graph.');
+  return findings;
+}
+export function runValidate({ args }) {
+  const index = args.indexOf('--pre-commit');
+  const findings = validateProject(projectRoot(args), {
+    preCommitTask: index < 0 ? null : args[index + 1],
+    skipTrace: args.includes('--skip-trace')
+  });
+  if (args.includes('--json')) {
+    info(JSON.stringify({ valid: findings.length === 0, findings }, null, 2));
+    if (findings.length) process.exitCode = 1;
+    return;
+  }
+  if (!findings.length) return info('Flow project is valid.');
+  for (const finding of findings) info(`${finding.code}: ${finding.message}`);
+  fail(`${findings.length} validation finding(s).`);
+}

package/src/shared/cli-io.mjs

@@ -0,0 +1,86 @@
+import readline from 'node:readline/promises';
+import { stdin as inputStream, stdout as outputStream } from 'node:process';
+
+export class CliError extends Error {}
+export function fail(message, code = 1) {
+  const error = new CliError(message);
+  error.exitCode = code;
+  throw error;
+}
+export function info(message = '') {
+  console.log(message);
+}
+function abortedPromptError() {
+  const error = new Error('Prompt aborted.');
+  error.code = 'ABORT_ERR';
+  return error;
+}
+function question(readlineInterface, message) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (callback, value) => {
+      if (settled) return;
+      settled = true;
+      readlineInterface.removeListener('close', onClose);
+      callback(value);
+    };
+    const onClose = () => finish(reject, abortedPromptError());
+    readlineInterface.once('close', onClose);
+    readlineInterface.question(message).then(
+      (answer) => finish(resolve, answer),
+      (error) => finish(reject, error)
+    );
+  });
+}
+export 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();
+  }
+}
+export async function promptSelect({ title, options, defaultIndex = 0 }) {
+  info(title);
+  options.forEach((option, index) =>
+    info(
+      `  ${index === defaultIndex ? '›' : ' '} ${index + 1}. ${option.label}${option.description ? `\n     ${option.description}` : ''}`
+    )
+  );
+  const rl = readline.createInterface({ input: inputStream, output: outputStream });
+  try {
+    while (true) {
+      const answer = (await question(rl, `Selection [${defaultIndex + 1}]: `)).trim();
+      const index = answer ? Number.parseInt(answer, 10) - 1 : defaultIndex;
+      if (Number.isInteger(index) && index >= 0 && index < options.length) return options[index].value;
+      info('Choose a valid number.');
+    }
+  } finally {
+    rl.close();
+  }
+}
+export async function promptMultiSelect({ title, options }) {
+  info(title);
+  options.forEach((option, index) => info(`  [ ] ${index + 1}. ${option.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((value) => Number.parseInt(value.trim(), 10))
+            .filter(Number.isInteger)
+        )
+      ];
+      if (indices.length && indices.every((index) => index >= 1 && index <= options.length))
+        return indices.map((index) => options[index - 1].value);
+      info('Choose one or more valid numbers.');
+    }
+  } finally {
+    rl.close();
+  }
+}