@chenguangyao/devflow-kit 0.1.43

package/src/cli/commands/status.js

@@ -0,0 +1,925 @@
+'use strict';
+const fs = require('fs/promises');
+const fsSync = require('fs');
+const path = require('path');
+const log = require('../../utils/log.js');
+const paths = require('../../core/paths.js');
+const change = require('../../core/change.js');
+const state = require('../../core/state.js');
+const checkpoint = require('../../core/checkpoint.js');
+const workflowCheck = require('../../core/workflow-check.js');
+const workflowVerify = require('../../core/workflow-verify.js');
+const aggregate = require('../../reports/aggregate.js');
+const helpers = require('./_helpers.js');
+
+const CORE_ARTIFACTS = [
+  'proposal.md',
+  'requirement.md',
+  'design.md',
+  'plan.md',
+  'review.md',
+  'verify.md',
+];
+
+const OPTIONAL_ARTIFACTS = [
+  'tests.md',
+  'knowledge.md',
+];
+
+async function run({ positional = [], flags = {}, cwd }) {
+  const root = cwd || process.cwd();
+  if (!fsSync.existsSync(paths.devflowDir(root))) {
+    log.warn('not a devflow project. run "devflow init" first.');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (positional[0] === 'set-level') {
+    await runSetLevel(root, positional.slice(1), flags);
+    return;
+  }
+  if (positional[0] === 'risk') {
+    await runRisk(root, positional.slice(1), flags);
+    return;
+  }
+
+  const slug = positional[0] || flags.slug || (await change.getCurrent(root));
+  if (!slug) {
+    log.warn('no change found. run "devflow ingest <input>" or "devflow new <slug>".');
+    return;
+  }
+
+  let st;
+  try { st = await state.read(root, slug); } catch (e) {
+    log.error(`cannot read state for ${slug}: ${e.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (flags.json === true) {
+    log.raw(JSON.stringify(buildStatusSurface(root, slug, st), null, 2));
+    return;
+  }
+
+  const { colors } = log;
+  log.raw('');
+  log.raw(`change ${colors.bold(slug)}  level=${colors.cyan(st.level)}  phase=${colors.magenta(st.currentPhase)}`);
+  if (st.title && st.title !== slug) log.dim(`  title: ${st.title}`);
+  if (st.source && st.source.ref) log.dim(`  source: ${st.source.type}:${st.source.ref}`);
+  let workflowCheckResult = null;
+  if (st.workflow && st.workflow.baseRecipe) {
+    const wf = st.workflow;
+    const next = nextWorkflowStep(wf);
+    log.dim(`  workflow: ${wf.baseRecipe.label || wf.baseRecipe.id} (${wf.baseRecipe.id}) status=${wf.status || 'draft'} current=${wf.currentStep || '-'} next=${next || '-'}`);
+    const overrides = summarizeWorkflowOverrides(wf);
+    if (overrides.length) log.dim(`  overrides: ${overrides.join('; ')}`);
+    if ((wf.status || 'draft') !== 'confirmed') {
+      workflowCheckResult = workflowCheck.checkWorkflow(root, slug, st);
+      renderWorkflowCheck(slug, workflowCheckResult);
+    }
+  }
+  log.raw('');
+
+  log.raw(colors.bold('phases'));
+  for (const p of state.PHASES) {
+    const ps = (st.phases && st.phases[p]) || { status: 'pending' };
+    const sym = ps.status === 'completed' ? colors.green('✓')
+              : ps.status === 'in_progress' ? colors.yellow('●')
+              : ps.status === 'skipped' ? colors.dim('-')
+              : colors.dim('·');
+    log.raw(`  ${sym} ${p.padEnd(12)} ${colors.dim(ps.ts || '')}`);
+  }
+
+  log.raw('');
+  log.raw(colors.bold('core artifacts'));
+  const cdir = change.resolveChangeDir(root, slug);
+  for (const name of CORE_ARTIFACTS) {
+    const exists = fsSync.existsSync(path.join(cdir, name));
+    log.raw(`  ${exists ? colors.green('✓') : colors.dim('·')} ${name}`);
+  }
+  log.raw(colors.bold('optional artifacts'));
+  for (const name of OPTIONAL_ARTIFACTS) {
+    const exists = fsSync.existsSync(path.join(cdir, name));
+    log.raw(`  ${exists ? colors.green('✓') : colors.dim('·')} ${name}`);
+  }
+  // delta dir
+  const deltaDir = path.join(cdir, 'delta');
+  const deltaCnt = fsSync.existsSync(deltaDir) ? fsSync.readdirSync(deltaDir).filter((f) => f.endsWith('.md')).length : 0;
+  log.raw(`  ${deltaCnt > 0 ? colors.green('✓') : colors.dim('·')} delta/  (${deltaCnt} file${deltaCnt === 1 ? '' : 's'})`);
+  // reports dir
+  const reportsDir = path.join(cdir, 'reports');
+  const reportCnt = fsSync.existsSync(reportsDir) ? fsSync.readdirSync(reportsDir).filter((f) => f.endsWith('.md')).length : 0;
+  log.raw(`  ${reportCnt > 0 ? colors.green('✓') : colors.dim('·')} reports/  (${reportCnt} file${reportCnt === 1 ? '' : 's'})`);
+
+  // Apply tasks (worktree swarm)
+  const applyTasks = (st.phases && st.phases.apply && st.phases.apply.tasks) || [];
+  if (applyTasks.length) {
+    log.raw('');
+    log.raw(colors.bold(`apply tasks`) + colors.dim(`  (iterations=${(st.iterations && st.iterations.apply) || 0})`));
+    for (const t of applyTasks) {
+      const sym = t.status === 'done' ? colors.green('✓')
+                : t.status === 'in_progress' ? colors.yellow('●')
+                : t.status === 'failed' ? colors.red('×')
+                : t.status === 'skipped' ? colors.dim('-')
+                : colors.dim('·');
+      const wt = t.worktree ? path.relative(root, t.worktree) : '(no worktree)';
+      log.raw(`  ${sym} ${String(t.id).padEnd(12)} ${colors.dim(t.status.padEnd(12))} ${colors.cyan(t.branch || '')}`);
+      log.dim(`      ${wt}  ·  ${t.title || ''}  ·  notes=${(t.notes || []).length}`);
+    }
+  }
+
+  // Review rounds
+  const review = (st.phases && st.phases.review) || {};
+  const rounds = review.rounds || [];
+  if (rounds.length || review.status !== 'pending') {
+    log.raw('');
+    const header = `review rounds` + colors.dim(`  (${rounds.length}/${review.max_rounds || 3}, status=${review.status || 'pending'})`);
+    log.raw(colors.bold(header));
+    for (const r of rounds) {
+      const sym = r.outcome === 'pass' ? colors.green('✓')
+                : r.outcome === 'blocked' ? colors.red('×')
+                : r.outcome === 'back_to_apply' ? colors.yellow('↺')
+                : colors.dim('·');
+      const tail = r.source === 'force-pass' ? colors.magenta(`  force-pass: ${r.reason || ''}`) : '';
+      log.raw(`  ${sym} round ${r.round}  must=${r.must || 0}  should=${r.should || 0}  nit=${r.nit || 0}  ${colors.dim(r.outcome)}${tail}`);
+    }
+    if (review.status === 'blocked') {
+      log.raw('');
+      log.raw(colors.red('  review BLOCKED. options:'));
+      log.dim(`    - fix remaining MUSTs + devflow review --slug=${slug} --round --continue-rounds`);
+      log.dim(`    - devflow review --slug=${slug} --force-pass --reason="..."  (audited)`);
+    }
+  }
+
+  if (st.checkpoints && st.checkpoints.length) {
+    log.raw('');
+    log.raw(colors.bold('checkpoints'));
+    for (const c of st.checkpoints) {
+      const status = c.status || 'pending';
+      const sym = status === 'passed' || status === 'resolved' ? colors.green('✓')
+                : status === 'pending' ? colors.yellow('●')
+                : colors.red('×');
+      log.raw(`  ${sym} ${c.name || c.id || c.type} ${colors.dim(status)}`);
+      if (c.question) log.dim(`      ${c.question}`);
+    }
+  }
+
+  const risks = st.riskSignals || [];
+  if (risks.length) {
+    log.raw('');
+    log.raw(colors.bold('risk signals'));
+    for (const r of risks) {
+      const status = r.status || 'open';
+      const sym = status === 'resolved' ? colors.green('✓')
+                : status === 'accepted' ? colors.magenta('!')
+                : colors.yellow('●');
+      log.raw(`  ${sym} ${String(r.type).padEnd(22)} ${colors.dim(status)}  ${r.reason || ''}`);
+    }
+  }
+
+  log.raw('');
+  hintNext(st, colors, slug, workflowCheckResult);
+  const pending = checkpoint.latestPending(st);
+  if (pending) {
+    log.raw('');
+    log.raw(checkpoint.renderNextStepCard(pending));
+  }
+  log.raw('');
+}
+
+async function runRisk(root, positional = [], flags = {}) {
+  const action = positional[0] || 'list';
+  const type = positional[1] || flags.type;
+  const slug = flags.slug || positional[2] || (await change.getCurrent(root));
+  if (!slug) {
+    log.warn('no change found. pass --slug=<slug>.');
+    process.exitCode = 1;
+    return;
+  }
+
+  let st;
+  try { st = await state.read(root, slug); } catch (e) {
+    log.error(`cannot read state for ${slug}: ${e.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (action === 'list') {
+    const risks = st.riskSignals || [];
+    if (!risks.length) {
+      log.dim('no risk signals.');
+      return;
+    }
+    for (const r of risks) log.raw(`  - ${r.type}  status=${r.status || 'open'}  reason=${r.reason || '-'}`);
+    return;
+  }
+
+  if (!type) {
+    log.error('usage: devflow status risk <add|resolve|accept|list> <type> --slug=<slug> [--reason="..."]');
+    process.exitCode = 2;
+    return;
+  }
+
+  const reason = flags.reason && flags.reason !== true ? flags.reason : '';
+  if (action === 'add') {
+    if (!reason) {
+      log.error('status risk add requires --reason="..."');
+      process.exitCode = 2;
+      return;
+    }
+    state.addRiskSignal(st, { type, reason, source: flags.source || 'cli' });
+    state.logEvent(st, 'risk_signal.add', { type, reason, source: flags.source || 'cli' });
+    await state.write(root, slug, st);
+    log.ok(`risk signal added: ${type}`);
+    return;
+  }
+
+  if (action === 'resolve') {
+    state.resolveRiskSignal(st, type, { reason: reason || 'resolved via CLI', evidence: parseEvidence(flags.evidence) });
+    state.logEvent(st, 'risk_signal.resolve', { type, reason: reason || 'resolved via CLI' });
+    await state.write(root, slug, st);
+    log.ok(`risk signal resolved: ${type}`);
+    return;
+  }
+
+  if (action === 'accept') {
+    if (!reason) {
+      log.error('status risk accept requires --reason="..."');
+      process.exitCode = 2;
+      return;
+    }
+    state.acceptRiskSignal(st, type, { reason, evidence: parseEvidence(flags.evidence) });
+    state.logEvent(st, 'risk_signal.accept', { type, reason });
+    await state.write(root, slug, st);
+    log.warn(`risk signal accepted: ${type}`);
+    return;
+  }
+
+  log.error('usage: devflow status risk <add|resolve|accept|list> <type> --slug=<slug> [--reason="..."]');
+  process.exitCode = 2;
+}
+
+function parseEvidence(v) {
+  if (!v || v === true) return [];
+  if (Array.isArray(v)) return v.flatMap(parseEvidence);
+  return String(v).split(',').map((s) => s.trim()).filter(Boolean);
+}
+
+async function runSetLevel(root, positional = [], flags = {}) {
+  const nextLevel = positional[0] || flags.level;
+  if (!['L0', 'L1', 'L2', 'L3'].includes(nextLevel)) {
+    log.error('usage: devflow status set-level <L0|L1|L2|L3> --slug=<slug> --reason="..."');
+    process.exitCode = 2;
+    return;
+  }
+  const reason = flags.reason;
+  if (!reason || reason === true) {
+    log.error('status set-level requires --reason="..."');
+    process.exitCode = 2;
+    return;
+  }
+
+  const slug = flags.slug || positional[1] || (await change.getCurrent(root));
+  if (!slug) {
+    log.warn('no change found. run "devflow ingest <input>" or "devflow new <slug>".');
+    process.exitCode = 1;
+    return;
+  }
+
+  let st;
+  try { st = await state.read(root, slug); } catch (e) {
+    log.error(`cannot read state for ${slug}: ${e.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const previousLevel = st.level || 'L2';
+  const wasMicro = st.mode === 'micro' || previousLevel === 'L0';
+  st.level = nextLevel;
+  st.enabled = state.applyLevelDefaults(nextLevel, { ...state.DEFAULT_ENABLED });
+
+  if (nextLevel === 'L0') {
+    st.mode = 'micro';
+    setRawPhase(st, 'requirement', 'skipped', 'micro mode');
+    setRawPhase(st, 'design', 'skipped', 'micro mode');
+    setRawPhase(st, 'archive', 'skipped', 'micro mode');
+    state.setPhase(st, 'plan', 'in_progress');
+  } else if (wasMicro) {
+    delete st.mode;
+    setRawPhase(st, 'requirement', 'pending');
+    setRawPhase(st, 'design', 'pending');
+    setRawPhase(st, 'archive', 'pending');
+    st.currentPhase = 'requirement';
+  }
+
+  state.logEvent(st, 'level changed', { from: previousLevel, to: nextLevel, reason });
+  await state.write(root, slug, st);
+  log.ok(`level: ${previousLevel} -> ${nextLevel}`);
+  if (wasMicro && nextLevel !== 'L0') {
+    log.dim('next: run devflow requirement to enter the standard route.');
+  }
+}
+
+function setRawPhase(st, phase, status, reason) {
+  st.phases = st.phases || {};
+  st.phases[phase] = { status, ts: new Date().toISOString() };
+  if (reason) st.phases[phase].reason = reason;
+}
+
+function renderWorkflowCheck(slug, result) {
+  const errors = result.errors || [];
+  const warnings = result.warnings || [];
+  const issueCount = errors.length + warnings.length;
+  log.dim(`  workflow card: devflow flow card --slug=${slug} --json`);
+  log.dim(`  workflow card: ok=${result.ok} status=${result.status || '-'} errors=${errors.length} warnings=${warnings.length}`);
+  for (const item of [...errors, ...warnings].slice(0, 3)) {
+    log.dim(`    - ${item.code}: ${item.summary}`);
+  }
+  if (issueCount > 3) log.dim(`    - ... ${issueCount - 3} more`);
+  if (result.nextAction) log.dim(`    nextAction: ${result.nextAction}`);
+  if (result.ok && result.confirmationCard) helpers.renderWorkflowConfirmationCard(result.confirmationCard);
+}
+
+function buildStatusSurface(root, slug, st) {
+  const wf = st.workflow || null;
+  const workflowCheckResult = wf && wf.baseRecipe
+    ? workflowCheck.checkWorkflow(root, slug, st)
+    : null;
+  const pending = checkpoint.latestPending(st);
+  const cdir = change.resolveChangeDir(root, slug);
+  const checkpointConfirmationCard = pending ? checkpoint.buildConfirmationCard(pending, checkpointCardOptions(pending)) : null;
+  const guidance = buildStatusGuidance(slug, st, workflowCheckResult, pending, checkpointConfirmationCard);
+  return {
+    type: 'change_status_surface',
+    slug,
+    title: st.title || slug,
+    level: st.level || null,
+    phase: st.currentPhase || null,
+    source: st.source || null,
+    phases: buildPhaseSurface(st),
+    artifacts: buildArtifactSurface(cdir),
+    apply: buildApplySurface(st),
+    review: buildReviewSurface(st),
+    verify: buildVerifySurface(st, cdir),
+    riskSignals: buildRiskSignalSurface(st),
+    workflow: wf ? {
+      status: wf.status || null,
+      baseRecipe: wf.baseRecipe || null,
+      currentStep: wf.currentStep || null,
+      nextStep: nextWorkflowStep(wf),
+      overrides: summarizeWorkflowOverrides(wf),
+      check: workflowCheckResult,
+      actions: {
+        card: `devflow flow card --slug=${slug} --json`,
+        picker: `devflow flow picker --slug=${slug} --json`,
+        confirm: `devflow flow confirm --slug=${slug}`,
+      },
+    } : null,
+    pendingCheckpoint: pending ? checkpoint.summarizeCheckpoint(pending) : null,
+    checkpointConfirmationCard,
+    primaryPanel: guidance.primaryPanel,
+    blockingReason: guidance.blockingReason,
+    availableActions: guidance.availableActions,
+    nextAction: guidance.nextAction,
+  };
+}
+
+function buildStatusGuidance(slug, st, workflowCheckResult, pending, checkpointConfirmationCard) {
+  if (pending) {
+    const actions = [
+      surfaceAction('show-checkpoint', '查看确认卡', `devflow checkpoint show --slug=${slug} --json`, {
+        primary: true,
+        kind: 'open-surface',
+      }),
+      ...actionsFromConfirmationCard(checkpointConfirmationCard, 'checkpoint-decision'),
+    ];
+    return {
+      primaryPanel: {
+        type: 'checkpoint',
+        title: checkpointConfirmationCard ? checkpointConfirmationCard.title : '确认下一步',
+        status: 'needs_input',
+        reasonCode: 'pending-checkpoint',
+        checkpointType: pending.type,
+        checkpointId: pending.id,
+        actionIds: actions.map((action) => action.id),
+      },
+      blockingReason: {
+        code: 'pending-checkpoint',
+        source: 'checkpoint',
+        severity: 'blocker',
+        message: pending.summary || `pending ${pending.type} checkpoint`,
+      },
+      availableActions: actions,
+      nextAction: `devflow checkpoint show --slug=${slug} --json`,
+    };
+  }
+
+  const workflowIssues = workflowCheckIssues(workflowCheckResult);
+  const wf = st.workflow || null;
+  if (workflowCheckResult && workflowIssues.length) {
+    const issue = workflowIssues[0];
+    const action = actionFromCommand('fix-workflow', workflowIssueActionLabel(issue), workflowCheckResult.nextAction, { primary: true, kind: 'workflow' });
+    const actions = compactActions([
+      action,
+      surfaceAction('edit-workflow', '调整编排', `devflow flow picker --slug=${slug} --json`, { kind: 'open-surface' }),
+      surfaceAction('view-workflow-card', '查看 workflow 卡片', `devflow flow card --slug=${slug} --json`, { kind: 'open-surface' }),
+    ]);
+    return {
+      primaryPanel: {
+        type: 'workflow_check',
+        title: '调整 workflow',
+        status: 'needs_input',
+        reasonCode: issue.code || 'workflow-check-failed',
+        actionIds: actions.map((item) => item.id),
+      },
+      blockingReason: {
+        code: issue.code || 'workflow-check-failed',
+        source: 'workflow',
+        severity: workflowCheckResult.errors && workflowCheckResult.errors.length ? 'blocker' : 'warning',
+        message: issue.summary || issue.message || 'workflow check failed',
+      },
+      availableActions: actions,
+      nextAction: workflowCheckResult.nextAction || null,
+    };
+  }
+
+  if (wf && (wf.status || 'draft') !== 'confirmed') {
+    const actions = [
+      surfaceAction('confirm-workflow', '确认 workflow', `devflow flow confirm --slug=${slug}`, { primary: true, kind: 'workflow' }),
+      surfaceAction('edit-workflow', '调整编排', `devflow flow picker --slug=${slug} --json`, { kind: 'open-surface' }),
+      surfaceAction('view-workflow-card', '查看 workflow 卡片', `devflow flow card --slug=${slug} --json`, { kind: 'open-surface' }),
+    ];
+    return {
+      primaryPanel: {
+        type: 'workflow_confirm',
+        title: '确认本次 workflow',
+        status: 'needs_input',
+        reasonCode: 'workflow-unconfirmed',
+        actionIds: actions.map((action) => action.id),
+      },
+      blockingReason: {
+        code: 'workflow-unconfirmed',
+        source: 'workflow',
+        severity: 'blocker',
+        message: 'change workflow is not confirmed',
+      },
+      availableActions: actions,
+      nextAction: `devflow flow confirm --slug=${slug}`,
+    };
+  }
+
+  const review = (st.phases && st.phases.review) || {};
+  if (review.status === 'blocked') {
+    const actions = [
+      surfaceAction('continue-review', '继续 review 返工', `devflow review --slug=${slug} --round --continue-rounds`, { primary: true, kind: 'phase' }),
+      surfaceAction('force-pass-review', '带原因强制通过 review', `devflow review --slug=${slug} --force-pass --reason="..."`, {
+        kind: 'risk-acceptance',
+        danger: true,
+        requiresReason: true,
+      }),
+    ];
+    return {
+      primaryPanel: {
+        type: 'review_blocked',
+        title: 'Review blocked',
+        status: 'needs_input',
+        reasonCode: 'review-blocked',
+        actionIds: actions.map((action) => action.id),
+      },
+      blockingReason: {
+        code: 'review-blocked',
+        source: 'review',
+        severity: 'blocker',
+        message: 'review is blocked by unresolved MUST findings',
+      },
+      availableActions: actions,
+      nextAction: actions[0].command,
+    };
+  }
+
+  const pendingVerifyStart = checkpoint.latestPendingByType(st, 'verify_start');
+  if (pendingVerifyStart) {
+    const command = pendingVerifyStart.nextAction || `devflow checkpoint resolve --id=${pendingVerifyStart.id} --decision=start-verify`;
+    const actions = [
+      surfaceAction('start-verify', '允许进入 verify', command, { primary: true, kind: 'checkpoint-decision' }),
+      surfaceAction('show-checkpoint', '查看确认卡', `devflow checkpoint show --slug=${slug} --json`, { kind: 'open-surface' }),
+    ];
+    return {
+      primaryPanel: {
+        type: 'verify_start',
+        title: '确认进入 verify',
+        status: 'needs_input',
+        reasonCode: 'pending-verify-start',
+        checkpointId: pendingVerifyStart.id,
+        actionIds: actions.map((action) => action.id),
+      },
+      blockingReason: {
+        code: 'pending-verify-start',
+        source: 'checkpoint',
+        severity: 'blocker',
+        message: pendingVerifyStart.summary || 'verify requires explicit confirmation',
+      },
+      availableActions: actions,
+      nextAction: command,
+    };
+  }
+
+  if (wf && wf.status === 'confirmed' && wf.currentStep) {
+    const command = workflowCommand(wf.currentStep, slug);
+    if (command) {
+      const actions = [surfaceAction('run-current-step', '运行当前 step', command, { primary: true, kind: 'phase' })];
+      return {
+        primaryPanel: {
+          type: 'current_step',
+          title: '继续当前 workflow step',
+          status: 'ready',
+          step: wf.currentStep,
+          actionIds: actions.map((action) => action.id),
+        },
+        blockingReason: null,
+        availableActions: actions,
+        nextAction: command,
+      };
+    }
+  }
+
+  if (review.status === 'completed') {
+    const actions = [surfaceAction('start-verify', '开始 verify', `devflow verify --slug=${slug}`, { primary: true, kind: 'phase' })];
+    return readyGuidance('verify_ready', '开始 verify', actions);
+  }
+
+  const apply = (st.phases && st.phases.apply) || {};
+  const tasks = apply.tasks || [];
+  const openTasks = tasks.filter((task) => task.status !== 'done' && task.status !== 'skipped');
+  if (openTasks.length) {
+    const actions = [surfaceAction('continue-apply-task', '继续 apply task', `devflow apply --slug=${slug} --task=<id> --done`, { primary: true, kind: 'phase' })];
+    return readyGuidance('apply_tasks', '继续 apply task', actions);
+  }
+
+  if (apply.status === 'completed') {
+    const actions = [surfaceAction('start-review', '开始 review', `devflow review --slug=${slug} --round`, { primary: true, kind: 'phase' })];
+    return readyGuidance('review_ready', '开始 review', actions);
+  }
+
+  return {
+    primaryPanel: {
+      type: 'phase_hint',
+      title: '继续当前阶段',
+      status: 'ready',
+      phase: st.currentPhase || null,
+      actionIds: [],
+    },
+    blockingReason: null,
+    availableActions: [],
+    nextAction: null,
+  };
+}
+
+function readyGuidance(type, title, actions) {
+  return {
+    primaryPanel: {
+      type,
+      title,
+      status: 'ready',
+      actionIds: actions.map((action) => action.id),
+    },
+    blockingReason: null,
+    availableActions: actions,
+    nextAction: actions[0] ? actions[0].command : null,
+  };
+}
+
+function workflowCheckIssues(result) {
+  if (!result) return [];
+  return [...(result.errors || []), ...(result.warnings || [])];
+}
+
+function workflowIssueActionLabel(issue) {
+  if (!issue) return '修复 workflow';
+  if (issue.code === 'missing-risk-step') return '按风险推荐补充 workflow';
+  if (issue.code === 'verify-below-level-default') return '恢复 verify 默认要求';
+  if (issue.code === 'pending-workflow-policy') return '查看 workflow 风险确认';
+  return '修复 workflow';
+}
+
+function actionsFromConfirmationCard(card, kind) {
+  if (!card) return [];
+  return compactActions([
+    card.primaryAction ? actionFromCardAction(card.primaryAction, { primary: true, kind }) : null,
+    ...((card.secondaryActions || []).map((action) => actionFromCardAction(action, { kind }))),
+  ]);
+}
+
+function actionFromCardAction(action, options = {}) {
+  return surfaceAction(action.id, action.label || action.id, action.command || null, {
+    kind: options.kind || 'command',
+    primary: options.primary === true,
+    description: action.description || '',
+  });
+}
+
+function actionFromCommand(id, label, command, options = {}) {
+  if (!command) return null;
+  return surfaceAction(id, label, command, options);
+}
+
+function surfaceAction(id, label, command, options = {}) {
+  return {
+    id,
+    label,
+    command,
+    kind: options.kind || 'command',
+    primary: options.primary === true,
+    danger: options.danger === true,
+    requiresReason: options.requiresReason === true,
+    description: options.description || '',
+  };
+}
+
+function compactActions(actions) {
+  return actions.filter(Boolean);
+}
+
+function buildPhaseSurface(st) {
+  const items = state.PHASES.map((id) => {
+    const phase = (st.phases && st.phases[id]) || { status: 'pending' };
+    return {
+      id,
+      status: phase.status || 'pending',
+      ts: phase.ts || null,
+      current: st.currentPhase === id,
+    };
+  });
+  return {
+    current: items.find((item) => item.current) || null,
+    items,
+    summary: countStatuses(items),
+  };
+}
+
+function buildArtifactSurface(cdir) {
+  return {
+    core: CORE_ARTIFACTS.map((name) => artifactInfo(cdir, name)),
+    optional: OPTIONAL_ARTIFACTS.map((name) => artifactInfo(cdir, name)),
+    directories: {
+      delta: directoryInfo(cdir, 'delta'),
+      reports: directoryInfo(cdir, 'reports'),
+    },
+  };
+}
+
+function artifactInfo(cdir, name) {
+  return {
+    name,
+    path: name,
+    exists: fsSync.existsSync(path.join(cdir, name)),
+  };
+}
+
+function directoryInfo(cdir, name) {
+  const dir = path.join(cdir, name);
+  const files = fsSync.existsSync(dir)
+    ? fsSync.readdirSync(dir).filter((file) => file.endsWith('.md')).sort()
+    : [];
+  return { path: `${name}/`, exists: fsSync.existsSync(dir), count: files.length, files };
+}
+
+function buildApplySurface(st) {
+  const apply = (st.phases && st.phases.apply) || {};
+  const tasks = (apply.tasks || []).map((task) => ({
+    id: task.id,
+    title: task.title || '',
+    status: task.status || 'pending',
+    branch: task.branch || null,
+    worktree: task.worktree || null,
+    notesCount: (task.notes || []).length,
+  }));
+  const summary = {
+    total: tasks.length,
+    done: tasks.filter((task) => task.status === 'done').length,
+    inProgress: tasks.filter((task) => task.status === 'in_progress').length,
+    failed: tasks.filter((task) => task.status === 'failed').length,
+    open: tasks.filter((task) => task.status !== 'done' && task.status !== 'skipped').length,
+  };
+  return {
+    status: apply.status || 'pending',
+    currentTask: apply.currentTask || null,
+    iterations: (st.iterations && st.iterations.apply) || 0,
+    tasks,
+    summary,
+  };
+}
+
+function buildReviewSurface(st) {
+  const review = (st.phases && st.phases.review) || {};
+  const rounds = review.rounds || [];
+  return {
+    status: review.status || 'pending',
+    maxRounds: review.max_rounds || review.maxRounds || 3,
+    rounds: rounds.map((round) => ({
+      round: round.round,
+      outcome: round.outcome || null,
+      must: round.must || 0,
+      should: round.should || 0,
+      nit: round.nit || 0,
+      source: round.source || null,
+      reason: round.reason || null,
+    })),
+    latestRound: rounds.length ? rounds[rounds.length - 1] : null,
+    mustTotal: sumRounds(rounds, 'must'),
+    shouldTotal: sumRounds(rounds, 'should'),
+    nitTotal: sumRounds(rounds, 'nit'),
+  };
+}
+
+function buildVerifySurface(st, cdir) {
+  const verify = (st.phases && st.phases.verify) || {};
+  const reportsDir = path.join(cdir, 'reports');
+  const requiredReports = workflowVerify.requiredReportsForState(st);
+  const reports = listReports(reportsDir);
+  const presentReports = [...new Set(reports.map((report) => report.name).filter(Boolean))].sort();
+  return {
+    status: verify.status || 'pending',
+    requiredReports,
+    presentReports,
+    missingReports: requiredReports.filter((name) => !presentReports.includes(name)),
+    reports,
+  };
+}
+
+function listReports(reportsDir) {
+  const out = [];
+  const seen = new Set();
+  const aggregateReport = aggregate.readAggregate(reportsDir);
+  for (const report of aggregateReport.reports || []) {
+    const name = reportNameFromKind(report.kind);
+    seen.add(name);
+    out.push({
+      kind: report.kind,
+      name,
+      status: report.status || 'pending',
+      total: report.total,
+      passed: report.passed,
+      failed: report.failed,
+      failureType: report.failureType || null,
+      file: report.file || 'test-report.md',
+      section: report.section || report.kind,
+      ts: report.ts || null,
+    });
+  }
+  let files = [];
+  try { files = fsSync.readdirSync(reportsDir).filter((file) => file.endsWith('.md')).sort(); } catch (_) { files = []; }
+  for (const file of files) {
+    if (file === 'test-report.md' || seen.has(file)) continue;
+    out.push({
+      kind: workflowVerify.reportKindFromName(file),
+      name: file,
+      status: readReportStatus(path.join(reportsDir, file)),
+      total: null,
+      passed: null,
+      failed: null,
+      failureType: null,
+      file,
+      section: null,
+      ts: null,
+    });
+  }
+  return out;
+}
+
+function reportNameFromKind(kind) {
+  return kind === 'self-test' ? 'self-test.md' : `${kind}-test.md`;
+}
+
+function readReportStatus(file) {
+  let text = '';
+  try { text = fsSync.readFileSync(file, 'utf8'); } catch (_) { return 'pending'; }
+  const match = text.match(/^status:\s*(.+)$/m);
+  return match ? match[1].trim() : 'pending';
+}
+
+function buildRiskSignalSurface(st) {
+  const items = (st.riskSignals || []).map((risk) => ({
+    type: risk.type,
+    status: risk.status || 'open',
+    reason: risk.reason || '',
+    source: risk.source || null,
+    evidence: risk.evidence || [],
+    createdAt: risk.createdAt || null,
+    updatedAt: risk.updatedAt || null,
+  }));
+  return { items, summary: countStatuses(items) };
+}
+
+function countStatuses(items) {
+  const summary = { total: items.length };
+  for (const item of items) {
+    const key = statusSummaryKey(item.status || 'pending');
+    summary[key] = (summary[key] || 0) + 1;
+  }
+  return summary;
+}
+
+function statusSummaryKey(status) {
+  if (status === 'in_progress') return 'inProgress';
+  return String(status || 'pending').replace(/_([a-z])/g, (_, ch) => ch.toUpperCase());
+}
+
+function sumRounds(rounds, field) {
+  return rounds.reduce((sum, round) => sum + (Number(round[field]) || 0), 0);
+}
+
+function checkpointCardOptions(cp) {
+  if (cp.type === 'workflow_policy') {
+    return {
+      type: 'workflow_policy_confirm',
+      title: '确认 workflow 风险',
+      primaryActionId: 'accept-risk',
+    };
+  }
+  return {};
+}
+
+function statusNextAction(slug, st, workflowCheckResult, pending) {
+  if (pending) return `devflow checkpoint show --slug=${slug} --json`;
+  if (workflowCheckResult && workflowCheckResult.nextAction) return workflowCheckResult.nextAction;
+  if (st.workflow && st.workflow.status === 'confirmed' && st.workflow.currentStep) {
+    const cmd = workflowCommand(st.workflow.currentStep, slug);
+    if (cmd) return cmd;
+  }
+  return null;
+}
+
+function hintNext(st, colors, slug, workflowCheck = null) {
+  if (workflowCheck && workflowCheck.nextAction) {
+    log.raw(colors.dim('next: ') + colors.bold(workflowCheck.nextAction));
+    return;
+  }
+  if (st.workflow && st.workflow.status === 'confirmed' && st.workflow.currentStep) {
+    const cmd = workflowCommand(st.workflow.currentStep, slug);
+    if (cmd) {
+      log.raw(colors.dim('next: ') + colors.bold(cmd));
+      return;
+    }
+  }
+  const apply = (st.phases && st.phases.apply) || {};
+  const review = (st.phases && st.phases.review) || {};
+  const pendingVerifyStart = checkpoint.latestPendingByType(st, 'verify_start');
+  const tasks = apply.tasks || [];
+  const openTasks = tasks.filter(t => t.status !== 'done' && t.status !== 'skipped');
+  if (review.status === 'blocked') {
+    log.raw(colors.dim('next: ') + 'fix MUSTs & ' + colors.bold(`devflow review --slug=${slug} --round --continue-rounds`) + ' OR ' + colors.bold(`devflow review --slug=${slug} --force-pass --reason="..."`));
+    return;
+  }
+  if (pendingVerifyStart) {
+    log.raw(colors.dim('next: ') + colors.bold(pendingVerifyStart.nextAction || `devflow checkpoint resolve --id=${pendingVerifyStart.id} --decision=start-verify`));
+    return;
+  }
+  if (review.status === 'completed') {
+    log.raw(colors.dim('next: ') + colors.bold(`devflow verify --slug=${slug}`));
+    return;
+  }
+  if (openTasks.length) {
+    log.raw(colors.dim('next: ') + `continue ${openTasks.length} open task${openTasks.length===1?'':'s'} — ` + colors.bold(`devflow apply --slug=${slug} --task=<id> --done`));
+    return;
+  }
+  if (apply.status === 'completed') {
+    log.raw(colors.dim('next: ') + colors.bold(`devflow review --slug=${slug} --round`));
+    return;
+  }
+  log.raw(colors.dim('next: ') + 'follow the current phase. see ' + colors.bold('devflow help') + ' for commands.');
+}
+
+function nextWorkflowStep(wf) {
+  const steps = wf.steps || [];
+  const currentIdx = steps.findIndex((s) => s.id === wf.currentStep);
+  for (let i = currentIdx + 1; i < steps.length; i += 1) {
+    if (steps[i].status !== 'disabled' && steps[i].status !== 'completed') return steps[i].id;
+  }
+  return null;
+}
+
+function summarizeWorkflowOverrides(wf) {
+  return (wf.overrides || []).map((item) => {
+    if (item.type === 'add-step') return `add-step ${item.step}`;
+    if (item.type === 'disable-step') return `disable-step ${item.step}`;
+    if (item.type === 'move-step') return `move-step ${item.step}`;
+    return `${item.type || 'override'} ${item.step || ''}`.trim();
+  });
+}
+
+function workflowCommand(step, slug) {
+  const commands = {
+    requirement: `devflow requirement --slug=${slug}`,
+    design: `devflow design --slug=${slug}`,
+    plan: `devflow plan --slug=${slug}`,
+    apply: `devflow apply --slug=${slug}`,
+    review: `devflow review --slug=${slug} --round`,
+    verify: `devflow verify --slug=${slug}`,
+    deliver: `devflow deliver --slug=${slug}`,
+    archive: `devflow archive --slug=${slug}`,
+  };
+  return commands[step] || null;
+}
+
+module.exports = { run };