@house365/comate 0.10.2 → 1.0.2-next.0

package/skills/comate/scripts/lib/cmd-archive.mjs

@@ -0,0 +1,152 @@
+// archive: preflight -> record plan -> write main specs -> move dir -> commit -> finish.
+// Every step checks the real files first, so a rerun after any interruption
+// continues from where the evidence says it stopped, never re-overwriting.
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+import { load, save } from './common.mjs';
+import { docDrift } from './docs.mjs';
+import { archivePaths, finishEvidence, runFinish } from './finish.mjs';
+import { changedFiles, commitPaths, dirtyOutside, head, isAncestor, knownPath } from './git.mjs';
+import { section } from './md.mjs';
+import { changePaths } from './paths.mjs';
+import { requireNode, setNode } from './state.mjs';
+import { writeVerification } from './render.mjs';
+import { BLOCK, CORRUPT, die, git, hashFile, readText, today } from './util.mjs';
+
+export function cmdArchive(ctx, a) {
+  let { cp, st } = load(ctx, a._[0]);
+  if (st.step === 'done') {
+    if (a.flags['dry-run']) return { cp, st, done: `已归档。收尾：${finishEvidence(ctx, st).message}` };
+    return finish(ctx, cp, st);
+  }
+  requireNode(st, ['ArchiveReady'], 'archive');
+  const moved = cp.archived;
+  if (!moved) {
+    const problems = preflight(ctx, cp, st);
+    if (problems.length) die(BLOCK, `归档预检未通过：\n  - ${problems.join('\n  - ')}`, { change: st.name });
+    if (a.flags['dry-run']) return { cp, st, done: `预检通过（dry-run）。将执行：${planText(ctx, cp, st).join('；')}` };
+  } else if (a.flags['dry-run']) {
+    return { cp, st, done: '目录已移入 archive，下一步只剩提交与收尾' };
+  }
+
+  if (!st.archive) {
+    const dest = `${ctx.archiveRel}/${today()}-${st.name}`;
+    st.archive = { step: 'planned', dest, from: cp.rel, targets: targetsPlan(ctx, cp, st) };
+    save(cp, st, 'archive-plan', dest);
+  }
+  if (!moved) {
+    writeMainSpecs(ctx, cp, st);
+    st.archive.step = 'moving';
+    save(cp, st, 'archive-specs', '主 spec 已写入');
+    const destAbs = ctx.abs(st.archive.dest);
+    if (existsSync(destAbs)) die(CORRUPT, `归档目录已存在：${st.archive.dest}。运行 doctor 核对后手动处理。`, { change: st.name });
+    for (const f of readdirSync(cp.dir)) if (f.endsWith('.tmp') || f === 'verify-result.json') rmSync(`${cp.dir}/${f}`, { force: true });
+    mkdirSync(dirname(destAbs), { recursive: true });
+    try {
+      renameSync(cp.dir, destAbs);
+    } catch (err) {
+      die(BLOCK, `移动目录失败（${err.code}）：关掉占用 ${cp.rel} 的程序后重跑 archive`, { change: st.name });
+    }
+    cp = { ...changePaths(ctx, st.name, st.archive.dest), archived: true };
+  }
+  st.archive.step = 'moved';
+  setNode(st, 'Done');
+  writeVerification(cp, st);
+  save(cp, st, 'archived', st.archive.dest);
+  commitArchive(ctx, cp, st);
+  return finish(ctx, cp, st);
+}
+
+function preflight(ctx, cp, st) {
+  const p = [...docDrift(ctx, cp, st)];
+  // After specs are written, an interrupted rename may legitimately leave the
+  // planned main spec files dirty. Their before/after hashes are checked below;
+  // all other files must still be clean before retrying archive.
+  const archiveWrites = st.archive
+    ? st.archive.targets.map((t) => `${ctx.specsRel}/${t.capability}/spec.md`)
+    : [];
+  const dirty = dirtyOutside(ctx, [cp.rel, ...archiveWrites]);
+  if (dirty.length) p.push(`工作区有未提交改动：${dirty.slice(0, 10).join(', ')}${dirty.length > 10 ? ' …' : ''}，需要清理后再归档`);
+  const h = head(ctx);
+  const c = st.candidate?.commit;
+  if (!c) p.push('没有候选实现记录');
+  else if (h !== c) {
+    if (!isAncestor(ctx, c, h)) p.push(`HEAD ${h?.slice(0, 7)} 不包含已验收的候选 ${c.slice(0, 7)}`);
+    else {
+      const extra = changedFiles(ctx, c, h).filter((f) => !f.startsWith(`${cp.rel}/`));
+      if (extra.length) p.push(`验收后又提交了 change 目录外的改动（${extra.slice(0, 5).join(', ')}），需要重新验收：decide --revise-implementation`);
+    }
+  }
+  if (st.verifier?.independent !== false && st.acceptance.some((x) => x.result !== 'passed')) p.push('存在未通过的验收项');
+  const dest = st.archive?.dest ?? `${ctx.archiveRel}/${today()}-${st.name}`;
+  if (st.archive?.step !== 'moved' && existsSync(ctx.abs(dest))) p.push(`归档目录已存在：${dest}（同名 change 今天已归档过，手动处理后重试）`);
+  for (const t of st.spec_targets) {
+    const now = hashFile(ctx.abs(`${ctx.specsRel}/${t.capability}/spec.md`));
+    const after = t.op === 'remove' ? null : hashFile(`${cp.specs}/${t.capability}/spec.md`);
+    if (now === after && st.archive) continue;
+    if (now !== t.base_hash) {
+      p.push(t.op === 'create'
+        ? `主 spec ${t.capability} 已被其他 change 创建：重读新主 spec，改写本 change 的 spec，再 --revise-requirements 重新确认`
+        : `主 spec ${t.capability} 在确认后被改动（基线不符）：重读新主 spec 并 rebase 本 change 的 spec，再 --revise-requirements 重新确认`);
+    }
+  }
+  return p;
+}
+
+function targetsPlan(ctx, cp, st) {
+  return st.spec_targets.map((t) => ({
+    capability: t.capability, op: t.op,
+    before: t.base_hash,
+    after: t.op === 'remove' ? null : hashFile(`${cp.specs}/${t.capability}/spec.md`),
+  }));
+}
+
+const planText = (ctx, cp, st) => [
+  ...st.spec_targets.map((t) => `${t.op} ${ctx.specsRel}/${t.capability}/spec.md`),
+  `移动 ${cp.rel} -> ${ctx.archiveRel}/${today()}-${st.name}`,
+  `提交 chore(comate): archive ${st.name}`,
+  `收尾 ${st.finish?.action ?? 'keep'}`,
+];
+
+function writeMainSpecs(ctx, cp, st) {
+  for (const t of st.archive.targets) {
+    const mainRel = `${ctx.specsRel}/${t.capability}/spec.md`;
+    const now = hashFile(ctx.abs(mainRel));
+    if (now === t.after) continue;
+    if (now !== t.before) die(CORRUPT, `主 spec ${mainRel} 的内容既不是写入前也不是写入后，无法确认来源。运行 doctor，人工核对后处理。`, { change: st.name });
+    if (t.op === 'remove') {
+      const keep = `${cp.dir}/removed-specs/${t.capability}/spec.md`;
+      mkdirSync(dirname(keep), { recursive: true });
+      copyFileSync(ctx.abs(mainRel), keep);
+      rmSync(ctx.abs(`${ctx.specsRel}/${t.capability}`), { recursive: true, force: true });
+    } else {
+      mkdirSync(dirname(ctx.abs(mainRel)), { recursive: true });
+      writeFileSync(ctx.abs(mainRel), readFileSync(`${cp.specs}/${t.capability}/spec.md`));
+    }
+  }
+}
+
+function commitArchive(ctx, cp, st) {
+  const paths = archivePaths(ctx, st);
+  const live = paths.filter((p) => knownPath(ctx, p));
+  if (!live.length || !git(ctx.root, 'status', '--porcelain', '--', ...live)) return;
+  try {
+    commitPaths(ctx, paths, `chore(comate): archive ${st.name}`);
+  } catch (err) {
+    die(BLOCK, `目录已归档，但提交失败：${err.message}\n修好后重跑 node "$COMATE" archive ${st.name}`, { change: st.name });
+  }
+}
+
+function finish(ctx, cp, st) {
+  commitArchive(ctx, cp, st);
+  const brief = readText(cp.brief) ?? '';
+  const goal = section(brief, '目标')?.body.replace(/<!--[\s\S]*?-->/g, '').trim() ?? '';
+  const body = [
+    `## 目标\n\n${goal}`,
+    `## 验收\n\n${st.acceptance.map((x) => `- ${x.id} ${x.title}：${x.result}`).join('\n')}`,
+    `详见 \`${st.archive.dest}/verification.md\`。`,
+  ].join('\n\n');
+  const message = runFinish(ctx, st, body);
+  return { cp, st, done: `已归档到 ${st.archive.dest}。${message}` };
+}

package/skills/comate/scripts/lib/cmd-decide.mjs

@@ -0,0 +1,116 @@
+// decide: every user decision after open. All forms carry --expect.
+import { candidateMoved, startChecking } from './cmd-loop.mjs';
+import { load, queueRepairs, recordFailure, requireCleanTree, save } from './common.mjs';
+import { loadConfig } from './checks.mjs';
+import { finishEvidence, finishProblem } from './finish.mjs';
+import { commitPaths, head } from './git.mjs';
+import { freshLoop, requireExpect, requireNode, setNode } from './state.mjs';
+import { repairEntryForItem } from './tasks.mjs';
+import { BLOCK, USAGE, die, hashFile } from './util.mjs';
+
+const CHOICES = ['accept', 'revise-implementation', 'revise-requirements', 'resolve', 'upgrade'];
+const AFTER_OPEN = ['Building', 'Repairing', 'Checking', 'AwaitVerifier', 'AwaitAccept', 'Stuck', 'Blocked', 'Degraded', 'ArchiveReady'];
+
+export function cmdDecide(ctx, a) {
+  const { cp, st } = load(ctx, a._[0]);
+  const picked = CHOICES.filter((c) => a.flags[c]);
+  if (picked.length !== 1) die(USAGE, `decide 需要且只能有一个选择：${CHOICES.map((c) => `--${c}`).join(' / ')}`);
+  const note = a.values.note?.trim();
+  const choice = picked[0];
+
+  if (choice === 'accept') {
+    const node = requireNode(st, ['AwaitAccept', 'Degraded', 'Done'], 'decide --accept');
+    requireExpect(st, a.values.expect);
+    const f = a.values.finish;
+    if (!f) die(USAGE, '--accept 需要 --finish keep|merge|pr|push');
+    const problem = finishProblem(ctx, st, f);
+    if (problem) die(BLOCK, problem, { change: st.name });
+    if (node === 'Done') {
+      // Archived, but the chosen finish could not complete: switch it.
+      if (finishEvidence(ctx, st).done) die(BLOCK, '收尾已完成，无需更改', { change: st.name });
+      st.finish = { action: f, by: 'user', at: new Date().toISOString() };
+      save(cp, st, 'refinish', f);
+      commitPaths(ctx, [cp.rel], `chore(comate): ${st.name} finish ${f}`);
+      return { cp, st, done: `收尾方式改为 ${f}，重跑 archive 执行` };
+    }
+    st.finish = { action: f, by: 'user', at: new Date().toISOString() };
+    setNode(st, 'ArchiveReady');
+    save(cp, st, 'accept', `${st.verifier?.independent === false ? '接受降级结果，' : ''}收尾 ${f}`);
+    return { cp, st, done: `用户接受结果，收尾方式：${f}` };
+  }
+
+  if (choice === 'revise-implementation') {
+    const node = requireNode(st, ['AwaitAccept', 'Stuck', 'Degraded'], 'decide --revise-implementation');
+    requireExpect(st, a.values.expect);
+    if (!note) die(USAGE, '--revise-implementation 需要 --note "<要改什么 / 新的修复方向>"');
+    const entries = [`用户要求：${note}`];
+    if (node === 'Stuck') {
+      for (const id of st.loop.previous_unresolved) {
+        const x = st.acceptance.find((y) => y.id === id);
+        if (x && x.result !== 'pending') entries.push(repairEntryForItem(x));
+      }
+      Object.assign(st.loop, { fail_count: 0, no_progress_count: 0, previous_unresolved: [], stop_reason: null });
+    }
+    st.loop.iteration += 1;
+    st.verifier = null;
+    for (const x of st.acceptance) Object.assign(x, { result: 'pending', reason: null });
+    queueRepairs(st, entries);
+    setNode(st, 'Repairing');
+    save(cp, st, 'revise-implementation', note);
+    return { cp, st, done: '需求不变，回 build 修改实现' };
+  }
+
+  if (choice === 'revise-requirements') {
+    requireNode(st, AFTER_OPEN, 'decide --revise-requirements');
+    requireExpect(st, a.values.expect);
+    if (st.archive) die(BLOCK, '归档已经开始写主 spec，不能再改需求。先 archive 收尾，再开新 change。', { change: st.name });
+    resetToOpen(ctx, st);
+    save(cp, st, 'revise-requirements', note ?? '');
+    return { cp, st, done: `回到 open（goal_cycle ${st.loop.goal_cycle}）：修改 brief/spec 后重新 prepare 并确认` };
+  }
+
+  if (choice === 'resolve') {
+    requireNode(st, ['Blocked'], 'decide --resolve');
+    requireExpect(st, a.values.expect);
+    if (!note) die(USAGE, '--resolve 需要 --note "<补充的信息>"');
+    st.candidate.handoff.notes.push({ at: new Date().toISOString(), note });
+    st.loop.error_count = 0;
+    if (head(ctx) !== st.candidate.commit) return candidateMoved(ctx, cp, st);
+    requireCleanTree(ctx, cp, st);
+    const failed = st.acceptance.filter((x) => x.result === 'failed');
+    if (failed.length) {
+      // Older mixed-result states did not register their failed round.
+      if (!st.loop.repairs) {
+        recordFailure(st, failed.map((x) => x.id), loadConfig(ctx));
+        st.loop.iteration += 1;
+      }
+      queueRepairs(st, [...failed.map(repairEntryForItem), `解除阻塞补充：${note}`]);
+      st.blockers = [];
+      setNode(st, st.loop.stop_reason ? 'Stuck' : 'Repairing');
+      save(cp, st, 'resolve', note);
+      return { cp, st, done: st.loop.stop_reason ? `阻塞已解除，${st.loop.stop_reason}` : '阻塞已解除，保留验收证据并回 build 修复未通过项' };
+    }
+    return startChecking(ctx, cp, st, 'resolve');
+  }
+
+  if (st.mode !== 'fix') die(BLOCK, '已经是 full 模式', { change: st.name });
+  requireNode(st, ['Drafting', ...AFTER_OPEN.filter((n) => n !== 'ArchiveReady')], 'decide --upgrade');
+  requireExpect(st, a.values.expect);
+  st.mode = 'full';
+  resetToOpen(ctx, st);
+  save(cp, st, 'upgrade', note ?? '范围超出小修');
+  return { cp, st, done: '已转为 full 模式：补全 brief 七章，重新 prepare 并请用户确认' };
+}
+
+// Back to Drafting for a new goal cycle. Registered removals survive (their
+// baseline is re-checked at prepare); source pins move to the current content.
+function resetToOpen(ctx, st) {
+  st.loop = freshLoop(st.loop.goal_cycle + 1);
+  Object.assign(st, {
+    acceptance: [], removed_scenarios: [], source_map: {}, candidate: null, verifier: null, blockers: [], finish: null,
+    confirm: { doc_hash: null, at: null, skip_reason: null },
+    spec_targets: st.spec_targets.filter((t) => t.op === 'remove'),
+    sources: st.sources.map((s) => ({ ...s, sha256: hashFile(ctx.abs(s.path)) ?? s.sha256 })),
+  });
+  setNode(st, 'Drafting');
+}

package/skills/comate/scripts/lib/cmd-init.mjs

@@ -0,0 +1,75 @@
+// cmd-init: Initialize comate in a project.
+import { cpSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { BASE, TEMP_DIR, makeContext } from './paths.mjs';
+import { ensureDir, git, log, toPosix } from './util.mjs';
+
+export function cmdInit(ctx) {
+  const changes = [];
+
+  // 如果没有 ctx（还不在 git 仓库或还未初始化），先创建一个临时的
+  if (!ctx) {
+    const cwd = toPosix(process.cwd());
+    const top = git(cwd, 'rev-parse', '--show-toplevel');
+    if (!top) {
+      log.fail('当前目录不在 git 仓库里。请先运行 git init。');
+      return { exit: 1 };
+    }
+    const root = toPosix(top);
+    ctx = {
+      root,
+      base: BASE,
+      tempDir: TEMP_DIR,
+      configRel: `${BASE}/config.json`,
+      abs: (rel) => join(root, rel),
+    };
+  }
+
+  // 1. 确保 .comate 临时目录存在
+  const tempDir = ctx.abs(ctx.tempDir);
+  if (!existsSync(tempDir)) {
+    ensureDir(tempDir);
+    changes.push(`创建临时文件目录 ${ctx.tempDir}/`);
+  }
+
+  // 2. 检查并更新 .gitignore
+  const gitignorePath = ctx.abs('.gitignore');
+  const gitignoreEntry = `\n${ctx.tempDir}\n`;
+
+  if (existsSync(gitignorePath)) {
+    const content = readFileSync(gitignorePath, 'utf8');
+    if (!content.includes(ctx.tempDir)) {
+      writeFileSync(gitignorePath, content.trimEnd() + gitignoreEntry);
+      changes.push(`已在 .gitignore 中添加 ${ctx.tempDir}`);
+    }
+  } else {
+    writeFileSync(gitignorePath, `${ctx.tempDir}\n`);
+    changes.push(`创建 .gitignore 并添加 ${ctx.tempDir}`);
+  }
+
+  // 3. 复制 scaffold 目录（如果尚未初始化）
+  const configPath = ctx.abs(ctx.configRel);
+  if (!existsSync(configPath)) {
+    const scriptDir = dirname(fileURLToPath(import.meta.url));
+    const scaffoldSrc = join(scriptDir, '..', '..', 'scaffold', 'comate');
+
+    if (!existsSync(scaffoldSrc)) {
+      log.fail(`找不到 scaffold 目录：${scaffoldSrc}`);
+      return { lines: changes.map((c) => `  ✓ ${c}`), exit: 1 };
+    }
+
+    const targetDir = ctx.abs('comate');
+    ensureDir(targetDir);
+    cpSync(scaffoldSrc, targetDir, { recursive: true });
+    changes.push(`已从 scaffold 初始化 ${ctx.base}/`);
+  }
+
+  // 输出结果
+  if (changes.length === 0) {
+    return { lines: ['  · 项目已初始化，无需操作'], exit: 0 };
+  } else {
+    return { lines: changes.map((c) => `  ✓ ${c}`), exit: 0 };
+  }
+}

package/skills/comate/scripts/lib/cmd-loop.mjs

@@ -0,0 +1,273 @@
+// build ⇄ verify: handoff (freeze candidate + run checks), verify results, probe.
+import { rmSync } from 'node:fs';
+import { relative, resolve } from 'node:path';
+
+import { finishProblem } from './finish.mjs';
+import { loadConfig, resolveChecks, runChecks, verifyPlan } from './checks.mjs';
+import { inputPath, load, queueRepairs, recordFailure, requireCleanTree, requireNoDrift, save } from './common.mjs';
+import { head, probeAdd, probeList, probeRemove } from './git.mjs';
+import { writeVerification } from './render.mjs';
+import { requireExpect, requireNode, setNode } from './state.mjs';
+import { repairEntryForCheck, repairEntryForItem } from './tasks.mjs';
+import { BLOCK, USAGE, die, randomId, readJson, toPosix } from './util.mjs';
+
+const relIn = (ctx, abs) => toPosix(relative(ctx.root, abs));
+const inChange = (cp, rel) => rel.startsWith(`${cp.rel}/`);
+const dropIfInChange = (ctx, cp, abs) => inChange(cp, relIn(ctx, abs)) && rmSync(abs, { force: true });
+const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+export function cmdHandoff(ctx, a) {
+  const { cp, st } = load(ctx, a._[0]);
+  if (a.flags.recheck) {
+    requireNode(st, ['Checking'], 'handoff --recheck');
+    requireExpect(st, a.values.expect);
+    if (head(ctx) !== st.candidate.commit) return candidateMoved(ctx, cp, st);
+    requireCleanTree(ctx, cp, st);
+    return startChecking(ctx, cp, st, 'recheck');
+  }
+  requireNode(st, ['Building', 'Repairing'], 'handoff');
+  requireExpect(st, a.values.expect);
+  const file = inputPath(ctx, a.values.input, '--input');
+  const input = readJson(file, '--input');
+  if (!isObj(input)) die(USAGE, '--input 必须是 JSON 对象', { change: st.name });
+  const ids = st.acceptance.map((x) => x.id);
+
+  const problems = [];
+  if (typeof input.summary !== 'string' || !input.summary.trim()) problems.push('handoff.summary 必须写本轮改了什么');
+  for (const key of ['addressed', 'manual_checks', 'known_limits']) {
+    if (input[key] !== undefined && !Array.isArray(input[key])) problems.push(`handoff.${key} 必须是数组`);
+  }
+  for (const id of Array.isArray(input.addressed) ? input.addressed : []) if (!ids.includes(id)) problems.push(`handoff.addressed 里有未知验收 ID：${id}`);
+  for (const m of Array.isArray(input.manual_checks) ? input.manual_checks : []) if (!ids.includes(m?.id) || !m?.steps) problems.push(`manual_checks 每项需要合法 id 和 steps：${JSON.stringify(m)}`);
+  requireNoDrift(ctx, cp, st);
+  if (!Array.isArray(input.addressed) || input.addressed.length === 0) {
+    problems.push('handoff.addressed 必须是非空验收项 ID 数组');
+  } else {
+    const unresolved = st.loop.previous_unresolved;
+    const target = unresolved.length > 0 ? unresolved : ids;
+    const uncovered = target.filter((id) => !input.addressed.includes(id));
+    if (uncovered.length > 0) {
+      const hint = unresolved.length > 0 ? `本轮修复重点：${unresolved.join(', ')}` : `第一轮必须覆盖全部验收项`;
+      problems.push(`${hint}；遗漏：${uncovered.join(', ')}`);
+    }
+  }
+  problems.push(...resolveChecks(ctx, loadConfig(ctx)).problems);
+  if (problems.length) die(BLOCK, `handoff 未通过：\n  - ${problems.join('\n  - ')}`, { change: st.name });
+  requireCleanTree(ctx, cp, st, [relIn(ctx, file)]);
+
+  const notes = st.candidate?.handoff?.notes ?? [];
+  st.candidate = {
+    commit: head(ctx),
+    at: new Date().toISOString(),
+    handoff: { summary: input.summary.trim(), addressed: input.addressed ?? [], manual_checks: input.manual_checks ?? [], known_limits: input.known_limits ?? [], notes },
+    checks: [],
+  };
+  st.loop.repairs = null;
+  dropIfInChange(ctx, cp, file);
+  return startChecking(ctx, cp, st, 'handoff');
+}
+
+// Checking: run the plan against the frozen candidate, then route.
+export function startChecking(ctx, cp, st, event) {
+  const cfg = loadConfig(ctx);
+  for (const x of st.acceptance) Object.assign(x, { result: 'pending', reason: null });
+  st.verifier = null;
+  st.blockers = [];
+  setNode(st, 'Checking');
+  save(cp, st, event, `候选 ${st.candidate.commit.slice(0, 7)}，执行检查`);
+
+  const { plan } = resolveChecks(ctx, cfg);
+  st.candidate.verify_plan = verifyPlan(plan);
+  const checks = runChecks(ctx, cfg, plan);
+  st.candidate.checks = checks;
+  const failed = checks.filter((c) => !c.ok);
+  if (failed.length) {
+    const stop = recordFailure(st, st.acceptance.map((x) => x.id), cfg);
+    st.loop.iteration += 1;
+    queueRepairs(st, failed.map(repairEntryForCheck));
+    setNode(st, stop ? 'Stuck' : 'Repairing');
+    save(cp, st, 'checks-failed', failed.map((c) => c.cmd).join(', '));
+    return { cp, st, done: `检查失败：${failed.map((c) => `${c.cmd}（${c.timed_out ? '超时' : `exit ${c.exit}`}）`).join('；')}` };
+  }
+  st.loop.attempt = 1;
+  st.loop.error_count = 0;
+  st.verifier = { token: `v-${st.loop.iteration}-1-${randomId(3)}`, independent: true, risks: [], summary: null, reverse_checks: [] };
+  setNode(st, 'AwaitVerifier');
+  save(cp, st, 'checks-passed', `${checks.length} 条检查通过`);
+  return { cp, st, done: `检查通过（${checks.map((c) => c.cmd).join('、') || '无检查命令'}），签发 verifier token` };
+}
+
+// HEAD moved away from the frozen candidate: every result for it is void, and
+// the round counts as a failure so moving HEAD can never dodge the budget.
+export function candidateMoved(ctx, cp, st) {
+  const cfg = loadConfig(ctx);
+  const unresolved = st.loop.previous_unresolved.length ? st.loop.previous_unresolved : st.acceptance.map((x) => x.id);
+  const stop = recordFailure(st, unresolved, cfg);
+  st.loop.iteration += 1;
+  st.verifier = null;
+  for (const x of st.acceptance) Object.assign(x, { result: 'pending', reason: null });
+  queueRepairs(st, [`验收期间 HEAD 从候选 ${st.candidate.commit.slice(0, 7)} 变成了 ${head(ctx)?.slice(0, 7)}：确认新提交属于本 change 后重新 handoff`]);
+  setNode(st, stop ? 'Stuck' : 'Repairing');
+  save(cp, st, 'candidate-moved', `HEAD ${head(ctx)?.slice(0, 7)} ≠ 候选 ${st.candidate.commit.slice(0, 7)}`);
+  return { cp, st, done: '验收期间 HEAD 变了，本轮结果作废并计一次失败。确认改动后重新 handoff。' };
+}
+
+const RESULTS = { passed: 'passed', pass: 'passed', failed: 'failed', fail: 'failed', blocked: 'blocked' };
+
+export function cmdVerify(ctx, a) {
+  const { cp, st } = load(ctx, a._[0]);
+  requireNode(st, ['AwaitVerifier'], 'verify');
+  requireNoDrift(ctx, cp, st);
+  const cfg = loadConfig(ctx);
+  const reissue = () => `v-${st.loop.iteration}-${st.loop.attempt}-${randomId(3)}`;
+
+  if (a.values.error !== undefined) {
+    st.loop.error_count += 1;
+    if (st.loop.error_count >= 3) {
+      st.blockers = [{ id: null, reason: `verifier 连续 ${st.loop.error_count} 次执行失败：${a.values.error}` }];
+      setNode(st, 'Blocked');
+      save(cp, st, 'verifier-error', a.values.error);
+      return { cp, st, done: 'verifier 连续失败 3 次，转为阻塞' };
+    }
+    st.loop.attempt += 1;
+    st.verifier.token = reissue();
+    save(cp, st, 'verifier-error', a.values.error);
+    return { cp, st, done: `verifier 出错（第 ${st.loop.error_count} 次），已重签 token，重新派发` };
+  }
+  if (a.flags.unavailable) {
+    requireExpect(st, a.values.expect);
+    if (head(ctx) !== st.candidate.commit) return candidateMoved(ctx, cp, st);
+    requireCleanTree(ctx, cp, st);
+
+    const hasTests = (st.candidate.checks ?? []).some((c) => c.stage === 'verify' && c.kind === 'test' && c.ok === true);
+    if (!hasTests) {
+      die(BLOCK, '没有自动测试可依赖，不能降级为「仅自动检查」。编译、语法检查或未知命令不算测试；自定义测试用 { "cmd": "<命令>", "kind": "test" } 声明，然后 decide --revise-requirements 重新确认并 handoff，或使用独立 verifier。', { change: st.name });
+    }
+
+    const currentPlan = verifyPlan(resolveChecks(ctx, cfg).plan);
+    const confirmedPlan = st.confirm?.verify_plan;
+    const candidatePlan = st.candidate.verify_plan;
+    if (!Array.isArray(confirmedPlan) || confirmedPlan.some((c) => typeof c !== 'object' || c === null) || !Array.isArray(candidatePlan)) {
+      die(BLOCK, '旧状态没有完整测试计划，不能降级。decide --revise-requirements 重新确认，或使用独立 verifier。', { change: st.name });
+    }
+    if (JSON.stringify(currentPlan) !== JSON.stringify(confirmedPlan) || JSON.stringify(candidatePlan) !== JSON.stringify(confirmedPlan)) {
+      die(BLOCK, '测试计划在确认后被改动（包括命令类型或 npm 脚本定义）。恢复测试计划后重新 handoff，或 decide --revise-requirements 重新确认。', { change: st.name });
+    }
+
+    Object.assign(st.verifier, { token: null, independent: false, summary: '平台没有子 agent 能力，只有自动检查' });
+    setNode(st, 'Degraded');
+    save(cp, st, 'verifier-unavailable', '');
+    writeVerification(cp, st);
+    return { cp, st, done: '独立 verifier 不可用，等待用户决定是否接受仅自动检查的结果' };
+  }
+
+  const file = inputPath(ctx, a.values.result, '--result');
+  const r = readJson(file, '--result');
+  if (!isObj(r)) die(USAGE, '--result 必须是 JSON 对象', { change: st.name });
+  if (r.token !== st.verifier.token) die(BLOCK, `verifier token 不匹配（结果 ${r.token ?? '无'}，当前 ${st.verifier.token}）：这是过期或串号的结果`, { change: st.name });
+  if (r.candidate !== st.candidate.commit) die(BLOCK, `结果针对的候选 ${r.candidate} 不是当前候选 ${st.candidate.commit}`, { change: st.name });
+  if (head(ctx) !== st.candidate.commit) {
+    dropIfInChange(ctx, cp, file);
+    return candidateMoved(ctx, cp, st);
+  }
+  requireCleanTree(ctx, cp, st, [relIn(ctx, file)]);
+  const problems = validateResult(r, st);
+  if (problems.length) die(BLOCK, `verifier 结果不完整，修正 ${relIn(ctx, file)} 后用同一 token 重交：\n  - ${problems.join('\n  - ')}`, { change: st.name });
+
+  const byId = new Map(r.acceptance.map((x) => [x.id, x]));
+  for (const x of st.acceptance) Object.assign(x, { result: RESULTS[byId.get(x.id).result], reason: byId.get(x.id).reason.trim() });
+  Object.assign(st.verifier, { risks: r.risks ?? [], summary: r.summary ?? null, reverse_checks: r.reverse_checks ?? [] });
+  dropIfInChange(ctx, cp, file);
+
+  const failed = st.acceptance.filter((x) => x.result === 'failed');
+  const blocked = st.acceptance.filter((x) => x.result === 'blocked');
+  let done;
+  if (!failed.length && !blocked.length) {
+    st.loop.previous_unresolved = [];
+    const action = cfg.auto_finish_action ?? 'keep';
+    const auto = cfg.finish === 'auto' && !st.verifier.risks.length && !finishProblem(ctx, st, action);
+    if (auto) st.finish = { action, by: 'config' };
+    setNode(st, auto ? 'ArchiveReady' : 'AwaitAccept');
+    done = `${st.acceptance.length} 项验收全部通过${auto ? `（finish: auto，直接归档，收尾 ${action}）` : ''}`;
+  } else if (blocked.length && failed.length) {
+    // 混合阻塞：先解除 blocked，再修 failed
+    st.blockers = blocked.map((x) => ({ id: x.id, reason: x.reason }));
+    recordFailure(st, failed.map((x) => x.id), cfg);
+    st.loop.iteration += 1;
+    queueRepairs(st, failed.map(repairEntryForItem));
+    setNode(st, 'Blocked');
+    done = `${blocked.length} 项无法验证、${failed.length} 项未通过：${blocked.map((x) => x.id).join(', ')} 外部阻塞 + ${failed.map((x) => x.id).join(', ')} 待修复。补充信息后 decide --resolve 继续修 failed 项`;
+  } else if (failed.length) {
+    const unresolved = failed.map((x) => x.id);
+    const stop = recordFailure(st, unresolved, cfg);
+    st.loop.iteration += 1;
+    queueRepairs(st, failed.map(repairEntryForItem));
+    setNode(st, stop ? 'Stuck' : 'Repairing');
+    done = `${failed.length} 项未通过：${unresolved.join(', ')}${stop ? `；${stop}` : '，自动回 build 修复'}`;
+  } else {
+    st.blockers = blocked.map((x) => ({ id: x.id, reason: x.reason }));
+    setNode(st, 'Blocked');
+    done = `${blocked.length} 项无法验证，需要用户或外部信息`;
+  }
+  save(cp, st, 'verify-result', done);
+  writeVerification(cp, st);
+  return { cp, st, done };
+}
+
+export function validateResult(r, st) {
+  const p = [];
+  if (!Array.isArray(r.acceptance)) return ['acceptance 必须是数组'];
+  const ids = st.acceptance.map((x) => x.id);
+  const seen = new Map();
+  const validItems = []; // 收集有效项，供后续使用
+  for (const x of r.acceptance) {
+    if (!isObj(x)) {
+      p.push(`acceptance 里有非对象项：${JSON.stringify(x)}`);
+      continue;
+    }
+    validItems.push(x);
+    if (!ids.includes(x.id)) p.push(`未知验收 ID：${x.id}`);
+    seen.set(x.id, (seen.get(x.id) ?? 0) + 1);
+    if (!RESULTS[String(x.result).toLowerCase()]) p.push(`${x.id} 的 result 必须是 passed / failed / blocked`);
+    else x.result = String(x.result).toLowerCase();
+    if (typeof x.reason !== 'string' || !x.reason.trim()) p.push(`${x.id} 缺少 reason（写明证据）`);
+  }
+  for (const id of ids) {
+    if (!seen.has(id)) p.push(`漏报 ${id}`);
+    else if (seen.get(id) > 1) p.push(`${id} 报了 ${seen.get(id)} 次，每项恰好一次`);
+  }
+  const allPassed = validItems.every((x) => RESULTS[x.result] === 'passed');
+  const hasTests = (st.candidate.checks ?? []).some((c) => c.stage === 'verify' && c.ok === true);
+  const rev = r.reverse_checks ?? [];
+  if (!Array.isArray(rev)) p.push('reverse_checks 必须是数组');
+  else {
+    for (const c of rev) {
+      if (!isObj(c) || !ids.includes(c.target) || typeof c.mutation !== 'string' || !c.mutation.trim() || typeof c.test !== 'string' || !c.test.trim() || typeof c.failed_as_expected !== 'boolean') {
+        p.push(`反向验证「${c?.target ?? '(空)'}」必须包含合法验收 ID、mutation、test 和 failed_as_expected`);
+      } else if (c.failed_as_expected !== true) {
+        const targetItem = validItems.find((x) => x.id === c.target);
+        if (targetItem && RESULTS[targetItem.result] === 'passed') {
+          p.push(`反向验证「${c.target}」测试没有变红：测试证明不了行为，对应项应判 failed`);
+        }
+      }
+    }
+    if (allPassed && hasTests && rev.length === 0) p.push('全部通过时至少要有 1 条反向验证（reverse_checks），bug 修复必做');
+  }
+  if (r.risks !== undefined && !Array.isArray(r.risks)) p.push('risks 必须是数组');
+  return p;
+}
+
+const norm = (p) => toPosix(resolve(p)).toLowerCase();
+
+export function cmdProbe(ctx, a) {
+  const { cp, st } = load(ctx, a._[0]);
+  if (a.values.remove) {
+    const hit = probeList(ctx).find((d) => norm(d) === norm(a.values.remove));
+    if (!hit) die(USAGE, `${a.values.remove} 不是 comate 建的 probe worktree（git worktree list 里没有），拒绝删除`);
+    probeRemove(ctx, hit);
+    return { lines: [`已删除 ${hit}`], json: { removed: hit } };
+  }
+  if (!st.candidate) die(BLOCK, '还没有候选实现，无法建 probe', { change: st.name });
+  const dir = probeAdd(ctx, st.name, st.candidate.commit);
+  return { lines: [dir], json: { dir, commit: st.candidate.commit, remove: `node "${ctx.script}" probe ${cp.name} --remove ${dir}` } };
+}