@chenguangyao/devflow-kit 0.1.43

package/src/cli/commands/report.js

@@ -0,0 +1,143 @@
+'use strict';
+const fs = require('fs/promises');
+const fsSync = require('fs');
+const path = require('path');
+const log = require('../../utils/log.js');
+const change = require('../../core/change.js');
+const templates = require('../../templates/index.js');
+const helpers = require('./_helpers.js');
+const aggregate = require('../../reports/aggregate.js');
+
+async function run({ sub, flags = {}, positional = [], cwd }) {
+  const root = cwd || process.cwd();
+  const kind = sub || positional[0];
+  if (kind !== 'self-test' && kind !== 'compact' && kind !== 'test-report') {
+    log.error('usage: devflow report self-test | compact');
+    log.dim('(other report kinds are produced via devflow test <kind>)');
+    process.exitCode = 2;
+    return;
+  }
+  const slug = await helpers.resolveSlug(root, flags, []);
+  if (!slug) { process.exitCode = 1; return; }
+  const st = await helpers.loadStateOrFail(root, slug);
+  if (!st) { process.exitCode = 1; return; }
+
+  if (kind === 'compact' || kind === 'test-report') {
+    return compactReports({ root, slug, st, flags });
+  }
+
+  const reportsDir = await change.ensureSubdir(root, slug, 'reports');
+  const tpl = await templates.load('reports/self-test.md');
+  const body = templates.render(tpl, {
+    slug,
+    title: st.title || slug,
+    status: 'draft',
+    acceptancePass: '-',
+    acceptanceTotal: '-',
+    unitPassRate: extractRate(root, slug, 'unit-test.md'),
+    integrationPassRate: extractRate(root, slug, 'integration-test.md'),
+    e2ePassRate: extractRate(root, slug, 'e2e-test.md'),
+    jointPassRate: extractRate(root, slug, 'joint-test.md'),
+    remotePassRate: extractRate(root, slug, 'remote-test.md'),
+    smokePassRate: extractRate(root, slug, 'smoke-test.md'),
+    date: new Date().toISOString(),
+  });
+  const file = path.join(reportsDir, 'self-test.md');
+  await aggregate.upsertReport({
+    reportsDir,
+    slug,
+    title: st.title || slug,
+    kind: 'self-test',
+    body,
+    meta: { status: 'draft' },
+  });
+  if (flags.splitReport === true || flags['split-report'] === true) {
+    await fs.writeFile(file, body, 'utf8');
+  }
+  log.ok(`reports/test-report.md#self-test`);
+  log.dim('edit the self-test section if needed, then devflow verify finalize');
+}
+
+async function compactReports({ root, slug, st, flags = {} }) {
+  const reportsDir = await change.ensureSubdir(root, slug, 'reports');
+  let entries = [];
+  try { entries = await fs.readdir(reportsDir); } catch (_) { entries = []; }
+  const files = entries
+    .filter((name) => name.endsWith('.md'))
+    .filter((name) => !['submit.md', 'test-report.md'].includes(name))
+    .sort();
+
+  let count = 0;
+  for (const name of files) {
+    const file = path.join(reportsDir, name);
+    const body = await fs.readFile(file, 'utf8');
+    const fm = readFrontmatter(body);
+    const kind = (fm.kind || kindFromReportFile(name)).trim();
+    await aggregate.upsertReport({
+      reportsDir,
+      slug,
+      title: st.title || slug,
+      kind,
+      body,
+      meta: {
+        status: fm.status || 'pending',
+        total: numericOrNull(fm.total),
+        passed: numericOrNull(fm.passed),
+        failed: numericOrNull(fm.failed),
+        coverage: fm.coverage || null,
+        failureType: fm.failureType || fm.failure_type || null,
+      },
+    });
+    count += 1;
+    if (flags.removeSplit === true || flags['remove-split'] === true) {
+      await fs.rm(file);
+    }
+  }
+
+  log.ok(`reports/test-report.md (${count} section${count === 1 ? '' : 's'} compacted)`);
+  if (flags.removeSplit === true || flags['remove-split'] === true) {
+    log.dim('legacy split report files removed after compaction.');
+  } else {
+    log.dim('legacy split files kept; pass --remove-split to remove them after compaction.');
+  }
+}
+
+function extractRate(root, slug, name) {
+  const f = path.join(change.resolveChangeDir(root, slug), 'reports', name);
+  if (!fsSync.existsSync(f)) {
+    const agg = aggregate.readAggregate(path.join(change.resolveChangeDir(root, slug), 'reports'));
+    const kind = name.replace(/-test\.md$/, '');
+    const found = agg.reports.find((r) => r.kind === kind);
+    return found ? found.status : '-';
+  }
+  const c = require('fs').readFileSync(f, 'utf8');
+  const m = c.match(/^status:\s*(\w+)/m);
+  return m ? m[1] : '-';
+}
+
+function readFrontmatter(text) {
+  const s = String(text || '');
+  if (!s.startsWith('---')) return {};
+  const end = s.indexOf('\n---', 3);
+  if (end < 0) return {};
+  const yaml = s.slice(3, end).trim();
+  const out = {};
+  for (const line of yaml.split('\n')) {
+    const m = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(line.trim());
+    if (m) out[m[1]] = m[2].trim();
+  }
+  return out;
+}
+
+function kindFromReportFile(name) {
+  if (name === 'self-test.md') return 'self-test';
+  return name.replace(/-test\.md$/, '').replace(/\.md$/, '');
+}
+
+function numericOrNull(value) {
+  if (value == null || value === '' || value === '-') return null;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+module.exports = { run, _internals: { compactReports, kindFromReportFile } };

package/src/cli/commands/requirement.js

@@ -0,0 +1,227 @@
+'use strict';
+const path = require('path');
+const log = require('../../utils/log.js');
+const state = require('../../core/state.js');
+const change = require('../../core/change.js');
+const routing = require('../../core/project-routing.js');
+const checkpoint = require('../../core/checkpoint.js');
+const helpers = require('./_helpers.js');
+
+async function run({ flags = {}, positional = [], cwd }) {
+  const root = cwd || process.cwd();
+  const slug = await helpers.resolveSlug(root, flags, positional);
+  if (!slug) { process.exitCode = 1; return; }
+  const st = await helpers.loadStateOrFail(root, slug);
+  if (!st) { process.exitCode = 1; return; }
+
+  if (st.mode === 'micro' || st.level === 'L0') {
+    log.error('requirement skipped: this change is L0 micro mode. Upgrade to L1 before running requirement-analysis.');
+    log.dim(`run: devflow status set-level L1 --slug=${slug} --reason="micro scope expanded"`);
+    process.exitCode = 1;
+    return;
+  }
+  if (helpers.blockWorkflowStep(root, st, slug, 'requirement', 'requirement')) return;
+
+  if (await blockPendingCheckpoint(root, slug, st, flags, ['problem_card'], 'requirement')) return;
+
+  await helpers.writePhaseArtifact(root, slug, st, 'requirement.md', 'requirement.md', {});
+  const projectRouting = await runProjectRouting(root, slug, flags, st);
+  if (projectRouting) {
+    st.projectRouting = projectRouting;
+    st.projects = projectRouting.recommended;
+    await writeRoutingSummary(root, slug, projectRouting);
+    await routing.writeProjectRootsArtifact(root, slug, projectRouting, { source: 'requirement' });
+    ensureProjectConfirmationCheckpoint(st, projectRouting);
+  }
+  state.setPhase(st, 'requirement', 'in_progress');
+  helpers.completeWorkflowStep(st, 'requirement');
+  state.logEvent(st, 'requirement scaffold', projectRouting ? { projectRouting: projectRouting.recommended.length } : undefined);
+  await state.write(root, slug, st);
+
+  if (projectRouting && projectRouting.candidates.length) {
+    log.raw('');
+    log.info('project routing recommendations:');
+    for (const [i, p] of projectRouting.candidates.slice(0, 5).entries()) {
+      const mark = projectRouting.recommended.some((r) => r.root === p.root) ? '*' : ' ';
+      log.raw(`  ${mark} ${i + 1}. ${p.name}  confidence=${p.confidence}  ${p.root}`);
+      for (const e of (p.evidence || []).slice(0, 3)) log.dim(`       - ${e}`);
+    }
+    log.dim('confirm selected projects in requirement.md / state.json before Round 2 code reconnaissance.');
+  }
+
+  const pendingProject = checkpoint.latestPendingByType(st, 'project_confirmation');
+  if (pendingProject) {
+    log.raw('');
+    log.raw(checkpoint.renderNextStepCard(pendingProject));
+  } else {
+    log.dim('next: drive double-round clarification in your IDE (use the devflow-requirement-analysis SKILL)');
+    log.dim('then run: devflow design');
+  }
+}
+
+async function blockPendingCheckpoint(root, slug, st, flags, types, commandName) {
+  const pending = checkpoint.latestPendingByTypes(st, types);
+  if (!pending) return false;
+  if (!flags.force) {
+    log.error(`${commandName} blocked: pending ${pending.type} checkpoint.`);
+    log.raw('');
+    log.raw(checkpoint.renderNextStepCard(pending));
+    log.dim(`override: devflow ${commandName} --force --reason="..."`);
+    process.exitCode = 1;
+    return true;
+  }
+  if (!flags.reason) {
+    log.error(`${commandName} --force requires --reason`);
+    process.exitCode = 2;
+    return true;
+  }
+  state.logEvent(st, `${commandName}.force_bypass_checkpoint`, {
+    checkpoint: pending.id,
+    type: pending.type,
+    reason: flags.reason,
+  });
+  await state.write(root, slug, st);
+  log.warn(`${commandName}: force-bypassed pending ${pending.type} checkpoint`);
+  return false;
+}
+
+function ensureProjectConfirmationCheckpoint(st, projectRouting) {
+  if (!projectRouting || !projectRouting.candidates || !projectRouting.candidates.length) return null;
+  if (projectRouting.status === 'explicit' || projectRouting.status === 'selected') return null;
+  if (checkpoint.latestPendingByType(st, 'project_confirmation')) return null;
+  if (checkpoint.hasResolvedDecision(st, 'project_confirmation', 'accept')) return null;
+
+  const recommended = projectRouting.recommended || [];
+  const candidateSummary = recommended.length
+    ? recommended.map((p) => `${p.name}:${p.role || 'candidate'}`).join(', ')
+    : '无推荐项目';
+  const cp = checkpoint.addCheckpoint(st, {
+    type: 'project_confirmation',
+    phase: 'requirement',
+    summary: `推荐项目：${candidateSummary}`,
+    question: '是否接受当前涉及项目范围，并允许进入 design？',
+    options: [
+      { id: 'accept', label: '接受项目范围', command: 'devflow checkpoint resolve --id=<checkpoint-id> --decision=accept' },
+      { id: 'revise', label: '改选项目', command: 'devflow requirement --project-root=<primary>[,<dependency>]' },
+    ],
+    nextAction: 'devflow checkpoint resolve --id=<checkpoint-id> --decision=accept',
+    evidence: ['requirement.md', 'state.json#projectRouting'],
+    risks: ['项目范围未确认时进入 design，容易侦察或修改错误仓库。'],
+  });
+  cp.options = cp.options.map((opt) => opt.id === 'accept'
+    ? { ...opt, command: `devflow checkpoint resolve --id=${cp.id} --decision=accept` }
+    : opt);
+  cp.nextAction = `devflow checkpoint resolve --id=${cp.id} --decision=accept`;
+  state.logEvent(st, 'checkpoint.add', { id: cp.id, type: cp.type, phase: cp.phase });
+  return cp;
+}
+
+async function runProjectRouting(root, slug, flags, st) {
+  if (flags['no-project-routing'] || flags.noProjectRouting) return null;
+  if (!hasRoutingFlags(flags) && st && Array.isArray(st.projects) && st.projects.length) {
+    return st.projectRouting || {
+      status: 'preselected',
+      searchRoots: st.projects.map((p) => p.root),
+      queryTerms: [],
+      candidates: st.projects,
+      recommended: st.projects,
+    };
+  }
+  const explicitRoots = parseSearchRoots(flags.projectRoot || flags['project-root']);
+  if (explicitRoots.length) {
+    return routing.explicitProjectRouting(explicitRoots, { source: 'requirement' });
+  }
+  const searchRoots = parseSearchRoots(flags.searchRoot || flags['search-root'] || flags.projectsRoot || root);
+  const query = await collectRoutingQuery(root, slug);
+  const result = await routing.routeProjects({
+    searchRoots,
+    query,
+    maxDepth: parseInt(flags.projectDepth || flags['project-depth'] || '3', 10),
+    topK: parseInt(flags.projectTopK || flags['project-top-k'] || '5', 10),
+  });
+  return {
+    status: result.recommended.length ? 'recommended' : 'none',
+    searchRoots: result.searchRoots,
+    queryTerms: routing.extractTerms(query).slice(0, 20),
+    candidates: result.candidates,
+    recommended: result.recommended,
+  };
+}
+
+function hasRoutingFlags(flags) {
+  return Boolean(
+    flags.projectRoot || flags['project-root'] ||
+    flags.searchRoot || flags['search-root'] ||
+    flags.projectsRoot || flags.projectDepth || flags['project-depth'] ||
+    flags.projectTopK || flags['project-top-k']
+  );
+}
+
+async function collectRoutingQuery(root, slug) {
+  const parts = [];
+  for (const name of ['proposal.md', 'requirement.md', 'knowledge.md']) {
+    try { parts.push(await change.readArtifact(root, slug, name)); } catch { /* optional */ }
+  }
+  const cdir = change.resolveChangeDir(root, slug);
+  await collectRefs(path.join(cdir, 'refs'), parts);
+  return parts.join('\n');
+}
+
+async function collectRefs(dir, parts) {
+  const fs = require('fs/promises');
+  const fsSync = require('fs');
+  if (!fsSync.existsSync(dir)) return;
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      await collectRefs(full, parts);
+    } else if (e.isFile() && e.name.endsWith('.md')) {
+      try { parts.push(await fs.readFile(full, 'utf8')); } catch { /* ignore unreadable refs */ }
+    }
+  }
+}
+
+function parseSearchRoots(value) {
+  return String(value || '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+async function writeRoutingSummary(root, slug, projectRouting) {
+  if (!projectRouting || !projectRouting.candidates.length) return;
+  let md;
+  try { md = await change.readArtifact(root, slug, 'requirement.md'); } catch { return; }
+  if (md.includes('## 7. 项目路由确认')) return;
+
+  const lines = [
+    '',
+    '## 7. 项目路由确认',
+    '',
+    '> Round 2 代码侦察前必须确认本次涉及哪些项目；后续 design/apply/review/verify 只围绕已确认项目展开。',
+    '',
+    '| 选择 | 项目 | 角色 | 置信度 | 路径 |',
+    '|------|------|------|--------|------|',
+  ];
+  if (projectRouting.status === 'explicit') {
+    lines.push('状态：用户已指定项目，本节不再执行自动发现评分。', '');
+  }
+  const selected = new Set(projectRouting.recommended.map((p) => p.root));
+  for (const p of projectRouting.candidates.slice(0, 8)) {
+    const picked = selected.has(p.root) ? '✓' : '';
+    const role = projectRouting.recommended.find((r) => r.root === p.root)?.role || '';
+    lines.push(`| ${picked} | ${p.name} | ${role} | ${p.confidence} | \`${p.root}\` |`);
+  }
+  lines.push('', '证据：');
+  for (const p of projectRouting.candidates.slice(0, 5)) {
+    lines.push(`- ${p.name}: ${(p.evidence || []).slice(0, 3).join('; ') || '无明显命中'}`);
+  }
+  lines.push('', '> 如推荐不准确，请手动修改本节和 `state.json#projects` 后再进入 Round 2。', '');
+
+  const updated = md.replace(/## 7\. 第二轮澄清\(实现\)/, `${lines.join('\n')}## 8. 第二轮澄清(实现)`)
+    .replace(/## 8\. 风险与待决项/, '## 9. 风险与待决项');
+  await change.writeArtifact(root, slug, 'requirement.md', updated);
+}
+
+module.exports = { run };

package/src/cli/commands/review.js

@@ -0,0 +1,301 @@
+'use strict';
+const fs = require('fs/promises');
+const fsSync = require('fs');
+const log = require('../../utils/log.js');
+const state = require('../../core/state.js');
+const change = require('../../core/change.js');
+const checkpoint = require('../../core/checkpoint.js');
+const helpers = require('./_helpers.js');
+
+const MAX_ROUNDS = 3;
+
+/**
+ * devflow review [--round] [--must=N --should=M --nit=K] [--reviewer=...]
+ *           [--status]
+ *           [--force-pass --reason="..."]
+ *           [--continue-rounds]   # only after MAX_ROUNDS, with audit
+ *
+ * Default invocation == --status (just show current).
+ *
+ * --round           record a new review round; will read review.md to count
+ *                   MUST/SHOULD/NIT mentions if not given via flags
+ * --must / --should / --nit
+ *                   explicit counts (override review.md scan)
+ * --reviewer        annotation only
+ *
+ * Outcomes per round:
+ *   must > 0  → outcome=back_to_apply, phase stays in 'review' but apply is reopened
+ *   must == 0 → outcome=pass, phase 'review' marked completed
+ *
+ * Hard rules:
+ *   - At round = MAX_ROUNDS with must>0: outcome=blocked, exit 1
+ *     (--force-pass --reason="..." can override; logged in audit)
+ *   - At round > MAX_ROUNDS: refuse unless --continue-rounds (logged)
+ */
+
+async function run({ flags = {}, positional = [], cwd }) {
+  const root = cwd || process.cwd();
+  const slug = await helpers.resolveSlug(root, flags, positional);
+  if (!slug) { process.exitCode = 1; return; }
+  const st = await helpers.loadStateOrFail(root, slug);
+  if (!st) { process.exitCode = 1; return; }
+
+  ensureReviewBucket(st);
+
+  if (flags.status === true || (!flags.round && !flags['force-pass'])) {
+    return showStatus(st, slug);
+  }
+  if (helpers.blockWorkflowStep(root, st, slug, 'review', 'review')) return;
+
+  // Force pass path
+  if (flags['force-pass'] === true || flags.forcePass === true) {
+    return forcePass(root, slug, st, flags);
+  }
+
+  // New round path
+  await helpers.writePhaseArtifact(root, slug, st, 'review.md', 'review.md', {});
+  return appendRound(root, slug, st, flags);
+}
+
+function ensureReviewBucket(st) {
+  st.phases.review = st.phases.review || { status: 'pending' };
+  st.phases.review.rounds = st.phases.review.rounds || [];
+  st.phases.review.max_rounds = st.phases.review.max_rounds || MAX_ROUNDS;
+  st.iterations = st.iterations || {};
+  st.iterations.review = st.iterations.review || st.phases.review.rounds.length;
+}
+
+function showStatus(st, slug) {
+  const r = st.phases.review;
+  log.raw(`review phase: ${r.status}  (iterations=${st.iterations.review || 0} / max=${r.max_rounds})`);
+  if (!r.rounds || !r.rounds.length) { log.dim(`no rounds recorded yet. run "devflow review --slug=${slug} --round"`); return; }
+  for (const round of r.rounds) {
+    const outcome = (round.outcome || '?').padEnd(14);
+    log.raw(`  round ${round.round}  ${outcome} must=${round.must||0}  should=${round.should||0}  nit=${round.nit||0}  ${round.reviewer ? '@'+round.reviewer : ''}  ${round.ts.slice(0,19)}`);
+  }
+  if (r.status === 'completed') {
+    const verifyStart = checkpoint.latestPendingByType(st, 'verify_start');
+    if (verifyStart) log.ok(`review passed → confirm before verify: ${verifyStart.nextAction || `devflow checkpoint resolve --id=${verifyStart.id} --decision=start-verify`}`);
+    else log.ok(`review passed → safe to devflow verify --slug=${slug}`);
+  } else if (r.status === 'blocked') {
+    log.error(`review BLOCKED at round ${r.rounds.length} — must>0 after MAX_ROUNDS. either fix and "devflow review --slug=${slug} --round --continue-rounds" or "devflow review --slug=${slug} --force-pass --reason=..."`);
+  }
+}
+
+async function appendRound(root, slug, st, flags) {
+  const r = st.phases.review;
+  const nextRound = (r.rounds.length || 0) + 1;
+
+  // Check round caps
+  if (nextRound > r.max_rounds) {
+    if (!(flags['continue-rounds'] === true || flags.continueRounds === true)) {
+      log.error(`review at round ${r.rounds.length}, max=${r.max_rounds} already. add --continue-rounds (audited) to continue.`);
+      process.exitCode = 1;
+      return;
+    }
+    state.logEvent(st, 'review.continue_beyond_max', { round: nextRound });
+  }
+
+  // Compute counts
+  let counts;
+  if (flags.must !== undefined || flags.should !== undefined || flags.nit !== undefined) {
+    counts = {
+      must:   toInt(flags.must, 0),
+      should: toInt(flags.should, 0),
+      nit:    toInt(flags.nit, 0),
+      source: 'flags',
+    };
+  } else {
+    counts = await scanReviewMd(root, slug);
+  }
+
+  const outcome = counts.must > 0
+    ? (nextRound >= r.max_rounds ? 'blocked' : 'back_to_apply')
+    : 'pass';
+
+  const round = {
+    round: nextRound,
+    ts: new Date().toISOString(),
+    must: counts.must, should: counts.should, nit: counts.nit,
+    source: counts.source,
+    reviewer: flags.reviewer || null,
+    outcome,
+  };
+  r.rounds.push(round);
+  st.iterations.review = nextRound;
+
+  switch (outcome) {
+    case 'pass':
+      state.setPhase(st, 'apply', 'completed');
+      state.setPhase(st, 'review', 'completed');
+      r.status = 'completed';
+      helpers.completeWorkflowStep(st, 'review');
+      cancelPendingReviewCheckpoints(st, 'review passed');
+      ensureVerifyStartCheckpoint(st, slug, round);
+      log.ok(`round ${nextRound}: PASS  (must=0)  → verify requires confirmation`);
+      break;
+    case 'back_to_apply':
+      state.setPhase(st, 'review', 'in_progress');
+      state.setPhase(st, 'apply', 'in_progress');
+      r.status = 'in_progress';
+      ensureReviewFixCheckpoint(st, slug, round);
+      log.warn(`round ${nextRound}: must=${counts.must} → back to apply (round ${nextRound+1}/${r.max_rounds} remaining)`);
+      log.dim(`fix MUSTs, then run "devflow apply --slug=${slug} --task=<id> --note=..." and "devflow review --slug=${slug} --round"`);
+      break;
+    case 'blocked':
+      state.setPhase(st, 'review', 'in_progress');
+      r.status = 'blocked';
+      ensureReviewBlockedCheckpoint(st, slug, round);
+      log.error(`round ${nextRound}: BLOCKED — must=${counts.must} after MAX_ROUNDS=${r.max_rounds}`);
+      log.dim(`options: fix and "devflow review --slug=${slug} --round --continue-rounds"  OR  "devflow review --slug=${slug} --force-pass --reason=..."`);
+      process.exitCode = 1;
+      break;
+  }
+
+  state.logEvent(st, 'review.round', round);
+  await state.write(root, slug, st);
+  const pending = outcome === 'back_to_apply'
+    ? checkpoint.latestPendingByType(st, 'review_fix')
+    : outcome === 'blocked'
+      ? checkpoint.latestPendingByType(st, 'review_blocked')
+      : null;
+  if (pending) {
+    log.raw('');
+    log.raw(checkpoint.renderNextStepCard(pending));
+  } else if (outcome === 'pass') {
+    const verifyStart = checkpoint.latestPendingByType(st, 'verify_start');
+    if (verifyStart) {
+      log.raw('');
+      log.raw(checkpoint.renderNextStepCard(verifyStart));
+    }
+  }
+}
+
+async function forcePass(root, slug, st, flags) {
+  const reason = flags.reason || flags['reason'];
+  if (!reason || reason === true) {
+    log.error('--force-pass requires --reason="..." (audited)');
+    process.exitCode = 2;
+    return;
+  }
+  const r = st.phases.review;
+  const last = r.rounds[r.rounds.length - 1] || {};
+  const round = {
+    round: (last.round || 0) + 1,
+    ts: new Date().toISOString(),
+    must: 0, should: last.should || 0, nit: last.nit || 0,
+    source: 'force-pass',
+    reviewer: flags.reviewer || null,
+    outcome: 'pass',
+    reason,
+  };
+  r.rounds.push(round);
+  state.setPhase(st, 'apply', 'completed');
+  state.setPhase(st, 'review', 'completed');
+  r.status = 'completed';
+  helpers.completeWorkflowStep(st, 'review');
+  st.iterations.review = round.round;
+  state.logEvent(st, 'review.force_pass', round);
+  cancelPendingReviewCheckpoints(st, reason);
+  ensureVerifyStartCheckpoint(st, slug, round);
+  await state.write(root, slug, st);
+  log.warn(`force-pass recorded at round ${round.round} — reason: "${reason}"`);
+  log.ok(`review marked completed. confirm before devflow verify --slug=${slug}.`);
+}
+
+function ensureReviewFixCheckpoint(st, slug, round) {
+  if (checkpoint.latestPendingByType(st, 'review_fix')) return null;
+  const cp = checkpoint.addCheckpoint(st, {
+    type: 'review_fix',
+    phase: 'review',
+    summary: `Round ${round.round} 发现 MUST=${round.must}，需要回到 apply 修复。`,
+    question: '是否进入 apply 修复本轮 MUST 问题？',
+    options: [
+      { id: 'fix', label: '进入修复', command: `devflow apply --slug=${slug} --note="fix review MUSTs"` },
+      { id: 're-review', label: '重新审查', command: `devflow review --slug=${slug} --round` },
+    ],
+    nextAction: `devflow apply --slug=${slug} --note="fix review MUSTs"`,
+    evidence: ['review.md', `state.json#phases.review.rounds[${round.round - 1}]`],
+    risks: ['未修复 MUST 就进入 verify，会把明确缺陷带到交付前。'],
+  });
+  state.logEvent(st, 'checkpoint.add', { id: cp.id, type: cp.type, phase: cp.phase });
+  return cp;
+}
+
+function ensureReviewBlockedCheckpoint(st, slug, round) {
+  if (checkpoint.latestPendingByType(st, 'review_blocked')) return null;
+  const cp = checkpoint.addCheckpoint(st, {
+    type: 'review_blocked',
+    phase: 'review',
+    summary: `Round ${round.round} 后仍有 MUST=${round.must}，review 已达到最大轮次。`,
+    question: '继续返工审查，还是带原因强制通过？',
+    options: [
+      { id: 'continue', label: '继续返工审查', command: `devflow review --slug=${slug} --round --continue-rounds` },
+      { id: 'force-pass', label: '强制通过', command: `devflow review --slug=${slug} --force-pass --reason="..."` },
+    ],
+    nextAction: `devflow review --slug=${slug} --round --continue-rounds`,
+    evidence: ['review.md', `state.json#phases.review.rounds[${round.round - 1}]`],
+    risks: ['review 达到最大轮次仍有 MUST，必须明确选择继续修复或审计接受风险。'],
+  });
+  state.logEvent(st, 'checkpoint.add', { id: cp.id, type: cp.type, phase: cp.phase });
+  return cp;
+}
+
+function ensureVerifyStartCheckpoint(st, slug, round) {
+  if (checkpoint.latestPendingByType(st, 'verify_start')) return null;
+  const cp = checkpoint.addCheckpoint(st, {
+    type: 'verify_start',
+    phase: 'review',
+    summary: `Review round ${round.round} 已通过，verify 需要显式确认后开始。`,
+    question: '是否允许进入 verify 阶段？确认后再单独运行 devflow verify。',
+    options: [
+      { id: 'start-verify', label: '允许进入 verify', command: 'devflow checkpoint resolve --id=<checkpoint-id> --decision=start-verify' },
+      { id: 'hold', label: '暂不验证', command: `devflow status --slug=${slug}` },
+    ],
+    nextAction: 'devflow checkpoint resolve --id=<checkpoint-id> --decision=start-verify',
+    evidence: ['review.md', `state.json#phases.review.rounds[${round.round - 1}]`],
+    risks: ['跳过显式确认直接 verify，容易在多 change 工作区里跑错对象或缺少验证范围确认。'],
+  });
+  const startCommand = `devflow checkpoint resolve --id=${cp.id} --decision=start-verify`;
+  cp.options[0].command = startCommand;
+  cp.nextAction = startCommand;
+  state.logEvent(st, 'checkpoint.add', { id: cp.id, type: cp.type, phase: cp.phase });
+  return cp;
+}
+
+function cancelPendingReviewCheckpoints(st, reason) {
+  const checkpoints = Array.isArray(st.checkpoints) ? st.checkpoints : [];
+  for (const cp of checkpoints) {
+    if ((cp.type === 'review_fix' || cp.type === 'review_blocked') && cp.status === 'pending') {
+      cp.status = 'resolved';
+      cp.decision = 'force-pass';
+      cp.note = reason;
+      cp.resolvedAt = new Date().toISOString();
+      state.logEvent(st, 'checkpoint.resolve', { id: cp.id, decision: cp.decision });
+    }
+  }
+}
+
+async function scanReviewMd(root, slug) {
+  const file = require('path').join(change.resolveChangeDir(root, slug), 'review.md');
+  if (!fsSync.existsSync(file)) {
+    return { must: 0, should: 0, nit: 0, source: 'no-file' };
+  }
+  const text = await fs.readFile(file, 'utf8');
+  // Count occurrences of MUST / SHOULD / NIT, case-sensitive in plain words and table cells
+  const c = (re) => (text.match(re) || []).length;
+  return {
+    must:   c(/\bMUST\b/g),
+    should: c(/\bSHOULD\b/g),
+    nit:    c(/\bNIT\b/g),
+    source: 'review.md',
+  };
+}
+
+function toInt(v, d) {
+  if (v === undefined || v === null) return d;
+  const n = parseInt(String(v), 10);
+  return Number.isFinite(n) ? n : d;
+}
+
+module.exports = { run, MAX_ROUNDS };