@chenguangyao/devflow-kit 0.1.43

package/src/cli/commands/flow.js

@@ -0,0 +1,645 @@
+'use strict';
+
+const log = require('../../utils/log.js');
+const config = require('../../core/config.js');
+const state = require('../../core/state.js');
+const checkpoint = require('../../core/checkpoint.js');
+const workflow = require('../../core/workflow.js');
+const workflowPolicy = require('../../core/workflow-policy.js');
+const workflowSuggest = require('../../core/workflow-suggest.js');
+const workflowVerify = require('../../core/workflow-verify.js');
+const workflowCheck = require('../../core/workflow-check.js');
+const workflowInit = require('../../core/workflow-init.js');
+const workflowPicker = require('../../core/workflow-picker.js');
+const helpers = require('./_helpers.js');
+
+async function run({ sub = null, positional = [], flags = {}, cwd }) {
+  const root = cwd || process.cwd();
+  const action = sub || positional[0] || 'current';
+  const args = sub ? positional : positional.slice(1);
+  const cfg = (await config.read(root)) || {};
+  if (action === 'validate') {
+    try { return await validate(root, cfg); }
+    catch (e) { log.error(e.message); process.exitCode = 2; return; }
+  }
+  if (action === 'preview') {
+    try { return await preview(root, cfg, args[0] || flags.recipe); }
+    catch (e) { log.error(e.message); process.exitCode = 2; return; }
+  }
+  const slug = await helpers.resolveSlug(root, flags, args);
+  if (!slug) { process.exitCode = 1; return; }
+  const st = await helpers.loadStateOrFail(root, slug);
+  if (!st) { process.exitCode = 1; return; }
+
+  try {
+    if (action === 'recommend') return await recommend(root, slug, st, cfg, flags);
+    if (action === 'draft') return await draft(root, slug, st, cfg, flags);
+    if (action === 'add-step') return await addStep(root, slug, st, args[0], flags);
+    if (action === 'disable-step') return await disableStep(root, slug, st, args[0], flags);
+    if (action === 'move-step') return await moveStep(root, slug, st, args[0], flags);
+    if (action === 'set-verify') return await setVerify(root, slug, st, flags);
+    if (action === 'suggest') return await suggest(root, slug, st, flags);
+    if (action === 'diff') return diff(st, flags);
+    if (action === 'picker') return picker(root, slug, st, flags);
+    if (action === 'apply-selection') return await applySelection(root, slug, st, flags);
+    if (action === 'card') return card(root, slug, st, flags);
+    if (action === 'check') return check(root, slug, st, flags);
+    if (action === 'confirm') return await confirm(root, slug, st);
+    if (action === 'current') return current(st);
+    if (action === 'next') return next(st);
+    if (action === 'explain') return explain(st, flags);
+    if (action === 'use') return await draft(root, slug, st, cfg, { ...flags, recipe: args[0] || flags.recipe, confirm: true });
+    usage();
+    process.exitCode = 2;
+  } catch (e) {
+    log.error(e.message);
+    process.exitCode = e.code === 'WORKFLOW_POLICY' ? 1 : 2;
+  }
+}
+
+async function suggest(root, slug, st, flags) {
+  const intent = flags.intent || flags.i || flags.text || '';
+  if (intent === true) throw new Error('usage: devflow flow suggest --intent="..." --slug=<slug>');
+  const suggestions = workflowSuggest.suggestWorkflowOverrides(intent, st.workflow, {
+    level: st.level,
+    riskSignals: st.riskSignals,
+  });
+  const applyDraft = flags['apply-draft'] === true || flags.applyDraft === true;
+  const shouldConfirm = flags.confirm === true;
+  log.raw('suggested overrides');
+  if (!suggestions.length) {
+    log.raw('  - no workflow override suggested');
+    log.dim('state unchanged.');
+    return;
+  }
+  let overrideCount = 0;
+  for (const item of suggestions) {
+    if (item.type === 'add-step') {
+      overrideCount += 1;
+      log.raw(`  - add-step ${item.step}: ${item.reason}`);
+      log.raw(`    command: devflow flow add-step ${item.skill} --slug=${slug}${item.after ? ` --after=${item.after}` : ''}`);
+    } else if (item.type === 'set-verify') {
+      overrideCount += 1;
+      log.raw(`  - set-verify: ${item.reason}`);
+      log.raw(`    command: devflow flow set-verify --slug=${slug} --reports=${item.reportArgs.join(',')}`);
+    } else if (item.type === 'recipe') {
+      log.raw(`  - recipe ${item.recipe}: ${item.reason}`);
+      log.raw(`    command: devflow flow draft --slug=${slug} --recipe=${item.recipe}`);
+    }
+  }
+  if (applyDraft) {
+    const recipeCount = suggestions.filter((item) => item.type === 'recipe').length;
+    if (shouldConfirm && recipeCount) {
+      log.error('cannot confirm suggested workflow with unapplied recipe suggestions.');
+      process.exitCode = 1;
+      return;
+    }
+    const applied = await applySuggestedDraftOverrides(root, slug, st, suggestions);
+    if (applied.length) {
+      state.logEvent(st, 'workflow.suggest.apply_draft', { applied: applied.map((item) => item.type) });
+      await state.write(root, slug, st);
+      log.ok(`applied safe overrides to workflow draft: ${applied.map((item) => item.label).join(', ')}`);
+    }
+    if (recipeCount) {
+      log.dim('recipe suggestions were not applied; run the draft command explicitly to replace the workflow draft.');
+    }
+    if (!applied.length && !recipeCount) log.dim('no safe draft override to apply.');
+    if (shouldConfirm) {
+      if (!applied.length) {
+        log.error('cannot confirm suggested workflow: no safe draft overrides were applied.');
+        process.exitCode = 1;
+        return;
+      }
+      const confirmed = await confirm(root, slug, st);
+      if (!confirmed) return;
+      st.workflow.audit.push({ ts: new Date().toISOString(), event: 'workflow.suggest.confirm', applied: applied.map((item) => item.type) });
+      state.logEvent(st, 'workflow.suggest.confirm', { applied: applied.map((item) => item.type), currentStep: st.workflow.currentStep });
+      await state.write(root, slug, st);
+      log.ok(`workflow confirmed from suggested draft: currentStep=${st.workflow.currentStep || '-'}`);
+    }
+    return;
+  }
+  if (overrideCount) {
+    log.dim('apply these commands to update the draft; suggest does not mutate state.');
+  } else {
+    log.dim('recipe suggestions replace the draft only if you run the command explicitly.');
+  }
+}
+
+async function applySuggestedDraftOverrides(root, slug, st, suggestions) {
+  const applied = [];
+  for (const item of suggestions) {
+    if (item.type === 'add-step') {
+      if (!workflow.installedSkillExists(root, item.skill)) throw new Error(`skill is not installed in this project: ${item.skill}`);
+      if (await enforcePolicyOrCheckpoint(root, slug, st, workflowPolicy.evaluateWorkflowChange(st, {
+        action: 'add-step',
+        stepId: item.step,
+        skill: item.skill,
+      }))) continue;
+      const step = workflow.addStep(st.workflow, { skill: item.skill, id: item.step, after: item.after });
+      state.logEvent(st, 'workflow.step.add', { step: step.id, skill: item.skill, after: item.after || null, before: null, source: 'suggest' });
+      applied.push({ type: 'add-step', label: step.id });
+    } else if (item.type === 'set-verify') {
+      if (await enforcePolicyOrCheckpoint(root, slug, st, workflowPolicy.evaluateWorkflowChange(st, {
+        action: 'set-verify',
+        requiredReports: item.reports,
+      }))) continue;
+      workflow.setVerifyReports(st.workflow, { requiredReports: item.reports, reason: item.reason });
+      state.logEvent(st, 'workflow.verify.set_reports', { requiredReports: item.reports, reason: item.reason, source: 'suggest' });
+      applied.push({ type: 'set-verify', label: 'verify reports' });
+    }
+  }
+  return applied;
+}
+
+async function recommend(root, slug, st, cfg) {
+  const rec = workflow.recommendRecipe(st, cfg);
+  const recipe = workflow.expandRecipe(rec.id, cfg);
+  log.raw(`推荐流程: ${recipe.label} (${recipe.id})`);
+  log.raw(`原因: ${rec.reason}`);
+  log.raw('步骤:');
+  renderSteps(recipe.steps);
+  log.dim(`next: devflow flow draft --slug=${slug} --recipe=${recipe.id}`);
+}
+
+async function validate(root, cfg) {
+  const ids = new Set(Object.keys(workflow.BUILTIN_RECIPES));
+  for (const id of Object.keys((cfg.workflows && cfg.workflows.recipes) || {})) ids.add(id);
+  for (const id of ids) {
+    const recipe = workflow.expandRecipe(id, cfg);
+    validateInstalledSkills(root, recipe.steps);
+  }
+  log.ok(`workflow recipes valid: ${ids.size}`);
+}
+
+async function preview(root, cfg, id) {
+  if (!id) throw new Error('usage: devflow flow preview <recipe>');
+  const recipe = workflow.expandRecipe(id, cfg);
+  validateInstalledSkills(root, recipe.steps);
+  log.raw(`${recipe.label} (${recipe.id}) source=${recipe.source}`);
+  renderSteps(recipe.steps);
+}
+
+async function draft(root, slug, st, cfg, flags) {
+  const recommendation = flags.recipe
+    ? { id: flags.recipe, reason: flags.reason || 'selected by user' }
+    : workflow.recommendRecipe(st, cfg);
+  const { recipe } = workflowInit.draftRecommendedWorkflow(root, st, cfg, {
+    recipe: recommendation.id,
+    reason: recommendation.reason,
+    force: true,
+  });
+  if (flags.confirm) {
+    workflow.confirmWorkflow(st.workflow);
+    state.logEvent(st, 'workflow.confirm', { recipe: recipe.id, currentStep: st.workflow.currentStep });
+  }
+  await state.write(root, slug, st);
+  log.ok(`${flags.confirm ? 'workflow confirmed' : 'workflow draft'}: ${recipe.label} (${recipe.id})`);
+  renderSteps(st.workflow.steps);
+}
+
+async function addStep(root, slug, st, skill, flags) {
+  if (!skill) throw new Error('usage: devflow flow add-step <skill> --after=<step>');
+  if (!workflow.installedSkillExists(root, skill)) throw new Error(`skill is not installed in this project: ${skill}`);
+  if (await enforcePolicyOrCheckpoint(root, slug, st, workflowPolicy.evaluateWorkflowChange(st, {
+    action: 'add-step',
+    stepId: flags.id || skill,
+    skill,
+  }))) return;
+  const step = workflow.addStep(st.workflow, { skill, id: flags.id, after: flags.after, before: flags.before });
+  state.logEvent(st, 'workflow.step.add', { step: step.id, skill, after: flags.after || null, before: flags.before || null });
+  await state.write(root, slug, st);
+  log.ok(`workflow step added: ${step.id}`);
+}
+
+async function disableStep(root, slug, st, stepId, flags) {
+  if (!stepId) throw new Error('usage: devflow flow disable-step <step> --reason="..."');
+  const policyResult = workflowPolicy.evaluateWorkflowChange(st, { action: 'disable-step', stepId });
+  if (await enforcePolicyOrCheckpoint(root, slug, st, policyResult)) return;
+  const allowRequired = policyResult.decision === 'checkpoint-required'
+    && !!findWorkflowPolicyCheckpoint(st, policyResult.summary, 'resolved', 'accept-risk');
+  try {
+    const step = workflow.disableStep(st.workflow, { stepId, reason: flags.reason, allowRequired });
+    state.logEvent(st, 'workflow.step.disable', { step: step.id, reason: flags.reason });
+    await state.write(root, slug, st);
+    log.ok(`workflow step disabled: ${step.id}`);
+  } catch (e) {
+    if (e.code !== 'WORKFLOW_POLICY') throw e;
+    const cp = checkpoint.addCheckpoint(st, {
+      type: 'workflow_policy',
+      phase: 'workflow',
+      summary: `禁用 required workflow step: ${stepId}`,
+      question: '这个调整会弱化流程质量闸，是否接受风险？',
+      options: [
+        { id: 'keep', label: '保留当前流程', command: `devflow status --slug=${slug}` },
+        { id: 'accept-risk', label: '接受风险', command: `devflow checkpoint resolve --id=<checkpoint-id> --decision=accept-risk` },
+      ],
+      nextAction: `devflow status --slug=${slug}`,
+      risks: ['禁用 required step 可能绕过 review/verify/deliver 或必要前置产物。'],
+      evidence: ['state.json#workflow'],
+    });
+    cp.options = cp.options.map((opt) => opt.id === 'accept-risk'
+      ? { ...opt, command: `devflow checkpoint resolve --id=${cp.id} --decision=accept-risk` }
+      : opt);
+    state.logEvent(st, 'checkpoint.add', { id: cp.id, type: cp.type, phase: cp.phase, step: stepId });
+    await state.write(root, slug, st);
+    log.error(e.message);
+    log.raw('');
+    log.raw(checkpoint.renderNextStepCard(cp));
+    process.exitCode = 1;
+  }
+}
+
+async function moveStep(root, slug, st, stepId, flags) {
+  if (!stepId) throw new Error('usage: devflow flow move-step <step> --after=<step>');
+  const policyResult = workflowPolicy.evaluateWorkflowChange(st, { action: 'move-step', stepId, after: flags.after, before: flags.before });
+  if (policyResult.decision === 'rejected' && ['review', 'verify', 'deliver'].includes(stepId)) {
+    throw Object.assign(new Error(policyResult.message), { code: 'WORKFLOW_POLICY' });
+  }
+  const step = workflow.moveStep(st.workflow, { stepId, after: flags.after, before: flags.before });
+  state.logEvent(st, 'workflow.step.move', { step: step.id, after: flags.after || null, before: flags.before || null });
+  await state.write(root, slug, st);
+  log.ok(`workflow step moved: ${step.id}`);
+}
+
+async function setVerify(root, slug, st, flags) {
+  const raw = flags.reports || flags.report || flags.requiredReports || flags['required-reports'];
+  if (!raw || raw === true) throw new Error('usage: devflow flow set-verify --reports=unit,smoke --slug=<slug>');
+  const requiredReports = workflowVerify.normalizeReportList(raw);
+  const reason = flags.reason && flags.reason !== true ? flags.reason : '';
+  if (await enforcePolicyOrCheckpoint(root, slug, st, workflowPolicy.evaluateWorkflowChange(st, {
+    action: 'set-verify',
+    requiredReports,
+  }))) return;
+  workflow.setVerifyReports(st.workflow, { requiredReports, reason });
+  state.logEvent(st, 'workflow.verify.set_reports', { requiredReports, reason: reason || null });
+  await state.write(root, slug, st);
+  log.ok(`workflow verify reports set: ${requiredReports.join(', ')}`);
+}
+
+async function enforcePolicyOrCheckpoint(root, slug, st, result, options = {}) {
+  if (!result || result.decision === 'safe' || result.decision === 'audit-only') return false;
+  if (result.decision === 'rejected') {
+    const e = new Error(result.message || 'workflow policy rejected this change');
+    e.code = 'WORKFLOW_POLICY';
+    throw e;
+  }
+  if (result.decision !== 'checkpoint-required') return false;
+  const accepted = findWorkflowPolicyCheckpoint(st, result.summary, 'resolved', 'accept-risk');
+  if (accepted) {
+    state.logEvent(st, 'workflow.policy.accept_risk', { checkpoint: accepted.id, summary: result.summary });
+    return false;
+  }
+  const pending = findWorkflowPolicyCheckpoint(st, result.summary, 'pending');
+  if (pending) {
+    renderWorkflowPolicyCheckpoint(slug, pending, result.summary, options);
+    process.exitCode = 1;
+    return true;
+  }
+  const cp = checkpoint.addCheckpoint(st, {
+    type: 'workflow_policy',
+    phase: 'workflow',
+    summary: result.summary,
+    question: result.question || '这个调整会弱化流程质量闸，是否接受风险？',
+    options: [
+      { id: 'keep', label: '保留当前流程', command: `devflow status --slug=${slug}` },
+      { id: 'accept-risk', label: '接受风险', command: `devflow checkpoint resolve --id=<checkpoint-id> --decision=accept-risk` },
+    ],
+    nextAction: `devflow status --slug=${slug}`,
+    risks: result.risks || ['workflow policy requires confirmation.'],
+    evidence: ['state.json#workflow'],
+  });
+  cp.options = cp.options.map((opt) => opt.id === 'accept-risk'
+    ? { ...opt, command: `devflow checkpoint resolve --id=${cp.id} --decision=accept-risk` }
+    : opt);
+  state.logEvent(st, 'checkpoint.add', { id: cp.id, type: cp.type, phase: cp.phase, summary: result.summary });
+  await state.write(root, slug, st);
+  renderWorkflowPolicyCheckpoint(slug, cp, result.summary, options);
+  process.exitCode = 1;
+  return true;
+}
+
+function renderWorkflowPolicyCheckpoint(slug, cp, summary, options = {}) {
+  if (options.json === true) {
+    log.raw(JSON.stringify(buildWorkflowPolicyConfirmationSurface(slug, cp), null, 2));
+    return;
+  }
+  log.error(summary || cp.summary || 'workflow policy checkpoint required');
+  log.raw('');
+  log.raw(checkpoint.renderNextStepCard(cp));
+}
+
+function buildWorkflowPolicyConfirmationSurface(slug, cp) {
+  return {
+    ok: false,
+    type: 'workflow_policy_confirmation_surface',
+    slug,
+    checkpoint: checkpoint.summarizeCheckpoint(cp),
+    confirmationCard: checkpoint.buildConfirmationCard(cp, {
+      type: 'workflow_policy_confirm',
+      title: '确认 workflow 风险',
+      primaryActionId: 'accept-risk',
+    }),
+    actions: {
+      show: `devflow checkpoint show --slug=${slug} --json`,
+      card: `devflow flow card --slug=${slug} --json`,
+      keep: `devflow status --slug=${slug}`,
+      acceptRisk: (cp.options || []).find((opt) => opt.id === 'accept-risk')?.command || `devflow checkpoint resolve --id=${cp.id} --decision=accept-risk`,
+    },
+    nextAction: `devflow checkpoint show --slug=${slug} --json`,
+  };
+}
+
+function findWorkflowPolicyCheckpoint(st, summary, status, decision) {
+  const checkpoints = Array.isArray(st.checkpoints) ? st.checkpoints : [];
+  for (let i = checkpoints.length - 1; i >= 0; i -= 1) {
+    const cp = checkpoints[i];
+    if (cp.type !== 'workflow_policy') continue;
+    if (cp.summary !== summary) continue;
+    if ((cp.status || 'pending') !== status) continue;
+    if (decision && cp.decision !== decision) continue;
+    return cp;
+  }
+  return null;
+}
+
+function diff(st, flags = {}) {
+  const d = workflow.diffWorkflow(st.workflow);
+  if (flags.json === true) {
+    log.raw(JSON.stringify({
+      baseRecipe: st.workflow.baseRecipe || null,
+      status: st.workflow.status || null,
+      ...d,
+    }, null, 2));
+    return;
+  }
+  log.raw('workflow diff');
+  log.raw(`added: ${d.added.length ? d.added.join(', ') : '-'}`);
+  log.raw(`disabled: ${d.disabled.length ? d.disabled.join(', ') : '-'}`);
+  log.raw(`moved: ${d.moved.length ? d.moved.join(', ') : '-'}`);
+  log.raw(`verify reports: ${d.verifyReports.length ? d.verifyReports.join(', ') : '-'}`);
+}
+
+function check(root, slug, st, flags = {}) {
+  const result = workflowCheck.checkWorkflow(root, slug, st);
+  if (flags.json === true) {
+    log.raw(JSON.stringify(result, null, 2));
+  } else {
+    renderCheckResult('workflow check', result);
+  }
+  if (!result.ok) process.exitCode = 1;
+}
+
+function card(root, slug, st, flags = {}) {
+  const result = buildWorkflowConfirmationSurface(root, slug, st);
+  if (flags.json === true) {
+    log.raw(JSON.stringify(result, null, 2));
+  } else {
+    renderCheckResult('workflow card', result);
+  }
+  if (!result.ok) process.exitCode = 1;
+}
+
+function buildWorkflowConfirmationSurface(root, slug, st) {
+  const result = workflowCheck.checkWorkflow(root, slug, st);
+  return {
+    type: 'workflow_confirmation_surface',
+    slug,
+    baseRecipe: st.workflow && st.workflow.baseRecipe ? st.workflow.baseRecipe : null,
+    actions: workflowActions(slug),
+    ...result,
+  };
+}
+
+function workflowActions(slug) {
+  return {
+    picker: `devflow flow picker --slug=${slug} --json`,
+    applySelection: `devflow flow apply-selection --slug=${slug} --selection='<json>' --json`,
+    check: `devflow flow check --slug=${slug} --json`,
+    confirm: `devflow flow confirm --slug=${slug}`,
+  };
+}
+
+function picker(root, slug, st, flags = {}) {
+  const result = workflowPicker.buildPicker(root, slug, st);
+  if (flags.json === true) {
+    log.raw(JSON.stringify(result, null, 2));
+    return;
+  }
+  log.raw(`workflow picker: ${result.baseRecipe ? result.baseRecipe.label : '-'} status=${result.status || '-'}`);
+  for (const group of result.groups) {
+    log.raw(`${group.label}:`);
+    for (const item of group.items) {
+      const box = item.selected ? '[x]' : '[ ]';
+      const tags = [];
+      if (item.locked) tags.push('locked');
+      if (item.recommended && !item.selected) tags.push('recommended');
+      log.raw(`  ${box} ${item.step} -> ${item.skill}${tags.length ? ` (${tags.join(', ')})` : ''}`);
+    }
+  }
+  log.raw(`next: ${result.actions.check}`);
+}
+
+async function applySelection(root, slug, st, flags = {}) {
+  const selection = parseSelection(flags.selection || flags.input || flags.items);
+  const applied = { added: [], disabled: [], skipped: [] };
+
+  for (const item of selection.items) {
+    if (!item || !item.step) {
+      applied.skipped.push({ step: null, reason: 'missing step' });
+      continue;
+    }
+    const existing = (st.workflow.steps || []).find((step) => step.id === item.step);
+    if (item.selected === true && !existing) {
+      const skill = item.skill || item.step;
+      if (!workflow.installedSkillExists(root, skill)) throw new Error(`skill is not installed in this project: ${skill}`);
+      if (await enforcePolicyOrCheckpoint(root, slug, st, workflowPolicy.evaluateWorkflowChange(st, {
+        action: 'add-step',
+        stepId: item.step,
+        skill,
+      }), { json: flags.json === true })) return;
+      const step = workflow.addStep(st.workflow, {
+        skill,
+        id: item.step,
+        after: item.after || null,
+        before: item.before || null,
+      });
+      state.logEvent(st, 'workflow.step.add', { step: step.id, skill, after: item.after || null, before: item.before || null, source: 'selection' });
+      applied.added.push(step.id);
+      continue;
+    }
+
+    if (item.selected === false && existing && existing.status !== 'disabled') {
+      const policyResult = workflowPolicy.evaluateWorkflowChange(st, { action: 'disable-step', stepId: item.step });
+      if (await enforcePolicyOrCheckpoint(root, slug, st, policyResult, { json: flags.json === true })) return;
+      const allowRequired = policyResult.decision === 'checkpoint-required'
+        && !!findWorkflowPolicyCheckpoint(st, policyResult.summary, 'resolved', 'accept-risk');
+      const reason = item.reason || 'disabled from workflow picker';
+      const step = workflow.disableStep(st.workflow, { stepId: item.step, reason, allowRequired });
+      state.logEvent(st, 'workflow.step.disable', { step: step.id, reason, source: 'selection' });
+      applied.disabled.push(step.id);
+      continue;
+    }
+
+    applied.skipped.push({ step: item.step, reason: 'no change' });
+  }
+
+  await state.write(root, slug, st);
+  const result = {
+    ...applied,
+    nextAction: `devflow flow card --slug=${slug} --json`,
+  };
+  if (flags.json === true) {
+    log.raw(JSON.stringify(result, null, 2));
+    return result;
+  }
+  log.ok(`workflow selection applied: added=${applied.added.length} disabled=${applied.disabled.length}`);
+  log.dim(`next: ${result.nextAction}`);
+  return result;
+}
+
+function parseSelection(raw) {
+  if (!raw || raw === true) throw new Error('usage: devflow flow apply-selection --selection=<json> --slug=<slug>');
+  const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
+  const items = Array.isArray(parsed) ? parsed : parsed.items;
+  if (!Array.isArray(items)) throw new Error('workflow selection must contain an items array');
+  return { items };
+}
+
+async function confirm(root, slug, st) {
+  const result = workflowCheck.checkWorkflow(root, slug, st);
+  if (!result.ok) {
+    renderCheckResult('workflow confirm blocked', result);
+    process.exitCode = 1;
+    return false;
+  }
+  workflow.confirmWorkflow(st.workflow);
+  state.logEvent(st, 'workflow.confirm', { recipe: st.workflow.baseRecipe && st.workflow.baseRecipe.id, currentStep: st.workflow.currentStep });
+  await state.write(root, slug, st);
+  log.ok(`workflow confirmed: currentStep=${st.workflow.currentStep || '-'}`);
+  return true;
+}
+
+function renderCheckResult(label, result) {
+  log.raw(`${label}: ${result.ok ? 'ok' : 'blocked'}`);
+  for (const item of result.errors) log.raw(`error: ${item.code} - ${item.message}`);
+  for (const item of result.warnings) log.raw(`warning: ${item.code} - ${item.message}`);
+  if (result.ok && result.confirmationCard) helpers.renderWorkflowConfirmationCard(result.confirmationCard);
+  log.raw(`next: ${result.nextAction || '-'}`);
+}
+
+function current(st) {
+  if (!st.workflow) {
+    log.dim('no workflow draft. run devflow flow draft.');
+    return;
+  }
+  log.raw(`workflow: ${st.workflow.baseRecipe.label} (${st.workflow.baseRecipe.id}) status=${st.workflow.status}`);
+  renderSteps(st.workflow.steps);
+}
+
+function next(st) {
+  if (!st.workflow) {
+    log.dim('no workflow draft. run devflow flow draft.');
+    return;
+  }
+  const step = st.workflow.steps.find((s) => s.id === st.workflow.currentStep)
+    || st.workflow.steps.find((s) => s.status !== 'disabled');
+  log.raw(`next: ${step ? `${step.id} (${step.skill})` : '-'}`);
+}
+
+function explain(st, flags = {}) {
+  if (!st.workflow) {
+    log.dim('no workflow draft. run devflow flow draft.');
+    return;
+  }
+  const info = explainWorkflow(st);
+  if (flags.json === true) {
+    log.raw(JSON.stringify(info, null, 2));
+    return;
+  }
+  log.raw(`base recipe: ${st.workflow.baseRecipe.label} (${st.workflow.baseRecipe.id}) source=${st.workflow.baseRecipe.source}`);
+  if (st.workflow.baseRecipe.reason) log.raw(`reason: ${st.workflow.baseRecipe.reason}`);
+  log.raw('steps:');
+  for (const s of info.steps) {
+    const flags = [];
+    if (s.protected) flags.push('protected');
+    if (s.required) flags.push('required');
+    if (s.optional) flags.push('optional');
+    if (s.status === 'disabled') flags.push(`disabled: ${s.disabledReason || '-'}`);
+    log.raw(`  - ${s.id}: skill=${s.skill} source=${s.source}${flags.length ? ` [${flags.join(', ')}]` : ''}`);
+  }
+  const requiredReports = info.verify && info.verify.requiredReports;
+  if (Array.isArray(requiredReports) && requiredReports.length) {
+    log.raw(`verify required reports: ${requiredReports.join(', ')}`);
+    if (info.verify.reason) log.raw(`verify reason: ${info.verify.reason}`);
+  }
+  const openRisks = info.openRiskSignals;
+  if (openRisks.length) {
+    log.raw('open risk signals:');
+    for (const risk of openRisks) {
+      log.raw(`  - ${risk.type}: ${risk.reason || '-'}`);
+    }
+  }
+  const overrides = info.overrides || [];
+  if (overrides.length) {
+    log.raw('overrides:');
+    for (const item of overrides) {
+      log.raw(`  - ${formatOverride(item)}`);
+    }
+  }
+}
+
+function explainWorkflow(st) {
+  const wf = st.workflow || {};
+  return {
+    baseRecipe: wf.baseRecipe || null,
+    status: wf.status || null,
+    currentStep: wf.currentStep || null,
+    steps: wf.steps || [],
+    verify: wf.verify || null,
+    openRiskSignals: (st.riskSignals || []).filter((risk) => (risk.status || 'open') === 'open'),
+    overrides: wf.overrides || [],
+    audit: wf.audit || [],
+  };
+}
+
+function formatOverride(item) {
+  if (item.type === 'add-step') {
+    const anchor = item.after ? ` after=${item.after}` : item.before ? ` before=${item.before}` : '';
+    return `add-step ${item.step}${anchor}`;
+  }
+  if (item.type === 'disable-step') {
+    return `disable-step ${item.step} reason=${item.reason || '-'}`;
+  }
+  if (item.type === 'move-step') {
+    const anchor = item.after ? ` after=${item.after}` : item.before ? ` before=${item.before}` : '';
+    return `move-step ${item.step}${anchor}`;
+  }
+  if (item.type === 'set-verify') {
+    return `set-verify ${(item.requiredReports || []).join(', ')}`;
+  }
+  return item.type || 'unknown';
+}
+
+function renderSteps(steps) {
+  for (const s of steps) {
+    const tags = [];
+    if (s.required) tags.push('required');
+    if (s.optional) tags.push('optional');
+    if (s.protected) tags.push('protected');
+    if (s.status === 'disabled') tags.push('disabled');
+    log.raw(`  - ${s.id} -> ${s.skill}${tags.length ? ` (${tags.join(', ')})` : ''}`);
+  }
+}
+
+function validateInstalledSkills(root, steps) {
+  for (const s of steps) {
+    if (!workflow.installedSkillExists(root, s.skill)) throw new Error(`skill is not installed in this project: ${s.skill}`);
+  }
+}
+
+function usage() {
+  log.error('usage: devflow flow <recommend|draft|suggest|add-step|disable-step|move-step|set-verify|diff|picker|apply-selection|card|check|confirm|current|next|explain|validate|preview|use>');
+}
+
+module.exports = { run };