@house365/comate 0.10.2 → 1.0.2-next.0

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

@@ -0,0 +1,161 @@
+// new / open --prepare / open --confirm / rename / spec remove|restore
+import { existsSync, mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { relative, resolve } from 'node:path';
+
+import { collectAcceptance, checkCoverage } from './acceptance.mjs';
+import { checkBrief, noBehaviorReason } from './brief.mjs';
+import { loadConfig } from './checks.mjs';
+import { enterBuild, load, save } from './common.mjs';
+import { changeSpecList, computeDocHash, mainSpecText, sourceDrift } from './docs.mjs';
+import { branchExists, currentBranch, defaultBranch, dirtyOutside, head } from './git.mjs';
+import { archivedDir, changePaths, requireInitialized, validateName } from './paths.mjs';
+import { freshLoop, newState, requireExpect, requireNode, saveState, setNode } from './state.mjs';
+import { checkChangeSpec } from './spec.mjs';
+import { BLOCK, USAGE, die, gitOk, hashFile, readText, toPosix } from './util.mjs';
+import { briefTemplate } from './templates.mjs';
+
+export function cmdNew(ctx, a) {
+  requireInitialized(ctx);
+  const name = a._[0];
+  validateName(name);
+  const mode = a.values.mode ?? 'full';
+  if (!['full', 'fix'].includes(mode)) die(USAGE, `--mode 只能是 full 或 fix，收到 '${mode}'`);
+  const cp = changePaths(ctx, name);
+  if (existsSync(cp.dir)) die(BLOCK, `change '${name}' 已存在：${cp.rel}`);
+  if (archivedDir(ctx, name)) die(BLOCK, `已有同名的归档 change（${archivedDir(ctx, name)}），换一个名称`);
+  if (!head(ctx)) die(BLOCK, '仓库还没有任何提交。先做一次初始提交再新建 change。');
+
+  const sources = a.sources.map((raw) => {
+    const abs = resolve(process.cwd(), raw);
+    const rel = toPosix(relative(ctx.root, abs));
+    if (rel.startsWith('..') || !existsSync(abs)) die(USAGE, `--source 必须是仓库内存在的文件：${raw}`);
+    return { path: rel, sha256: hashFile(abs) };
+  });
+
+  const cfg = loadConfig(ctx);
+  let branch = currentBranch(ctx);
+  if (!branch) die(BLOCK, '当前处于 detached HEAD，先切到一个分支。');
+  const baseBranch = a.values.base ?? (cfg.protected_branches.includes(branch) ? branch : defaultBranch(ctx) ?? branch);
+  if (a.values.base && !branchExists(ctx, a.values.base)) die(USAGE, `--base 分支不存在：${a.values.base}`);
+  if (cfg.protected_branches.includes(branch)) {
+    const dirty = dirtyOutside(ctx, []);
+    if (dirty.length) die(BLOCK, `当前在受保护分支 ${branch}，需要新建 comate/${name}，但工作区有未提交改动：\n  ${dirty.slice(0, 10).join('\n  ')}`);
+    const target = `comate/${name}`;
+    if (branchExists(ctx, target)) die(BLOCK, `分支 ${target} 已存在`);
+    gitOk(ctx.root, 'checkout', '-q', '-b', target, baseBranch);
+    branch = target;
+  }
+  const baseRef = gitOk(ctx.root, 'rev-parse', baseBranch === branch ? 'HEAD' : baseBranch);
+
+  mkdirSync(cp.specs, { recursive: true });
+  writeFileSync(cp.brief, briefTemplate(mode, sources.length > 0));
+  const st = newState({ name, mode, workspace: { branch, base_branch: baseBranch, base_ref: baseRef }, sources });
+  saveState(cp.state, st, 'new', `${mode} 模式，分支 ${branch}`);
+  return { cp, st, done: `已创建 ${cp.rel}（${mode}，分支 ${branch}，基线 ${baseBranch}）` };
+}
+
+export function cmdOpen(ctx, a) {
+  const { cp, st } = load(ctx, a._[0]);
+  if (a.flags.prepare) return prepare(ctx, cp, st);
+  if (a.flags.confirm) return confirm(ctx, cp, st, a);
+  return die(USAGE, 'open 需要 --prepare 或 --confirm --expect <v>:confirm');
+}
+
+function prepare(ctx, cp, st) {
+  requireNode(st, ['Drafting', 'AwaitConfirm'], 'open --prepare');
+  const briefText = readText(cp.brief);
+  if (briefText === null) die(BLOCK, `找不到 ${cp.briefRel}`, { change: st.name });
+  const problems = checkBrief(briefText, st.mode);
+  const specs = changeSpecList(cp);
+  for (const { cap, text } of specs) problems.push(...checkChangeSpec(cap, text));
+
+  const removals = st.spec_targets.filter((t) => t.op === 'remove');
+  for (const r of removals) {
+    if (specs.some((s) => s.cap === r.capability)) problems.push(`${r.capability} 同时登记了删除又写了 change spec，二选一（spec restore 取消删除）`);
+    if (hashFile(ctx.abs(`${ctx.specsRel}/${r.capability}/spec.md`)) !== r.base_hash) problems.push(`主 spec ${r.capability} 在登记删除后被改动，重新 spec remove`);
+  }
+  if (specs.length === 0 && removals.length === 0 && !noBehaviorReason(briefText, st.mode) && st.mode === 'full') {
+    problems.push('没有任何 specs/<capability>/spec.md。有产品行为变化就写完整目标 spec；确实没有，在「# 范围」写一行「无行为变更：<具体理由>」');
+  }
+  problems.push(...sourceDrift(ctx, st).map((d) => `${d}（new 时钉住的版本已变，需求来源要重新确认）`));
+  if (problems.length) die(BLOCK, `open --prepare 未通过：\n  - ${problems.join('\n  - ')}`, { change: st.name });
+
+  const mainSpecs = {};
+  for (const cap of [...specs.map((s) => s.cap), ...removals.map((r) => r.capability)]) mainSpecs[cap] = mainSpecText(ctx, cap);
+  const { acceptance, removed } = collectAcceptance({ briefText, changeSpecs: specs, mainSpecs, removals: removals.map((r) => r.capability) });
+  if (acceptance.length === 0) die(BLOCK, '没有抽到任何验收项：「验收示例」写列表项，或在 spec 里写 Scenario', { change: st.name });
+  const cov = checkCoverage(briefText, acceptance, st.sources.length > 0);
+  if (cov.problems.length) die(BLOCK, `来源覆盖未通过：\n  - ${cov.problems.join('\n  - ')}`, { change: st.name });
+
+  st.spec_targets = [
+    ...specs.map(({ cap }) => {
+      const main = hashFile(ctx.abs(`${ctx.specsRel}/${cap}/spec.md`));
+      return { capability: cap, op: main ? 'replace' : 'create', base_hash: main };
+    }),
+    ...removals,
+  ];
+  Object.assign(st, { acceptance, removed_scenarios: removed, source_map: cov.sourceMap });
+  st.confirm = { doc_hash: computeDocHash(cp, st), at: null, skip_reason: null };
+
+  if (st.mode === 'fix') {
+    st.confirm.at = new Date().toISOString();
+    st.confirm.skip_reason = 'fix 模式：open --prepare 通过后免确认直接进入 build（范围超出小修时用 decide --upgrade 转 full）';
+    enterBuild(ctx, cp, st, 'prepare', `fix 直通 build，${acceptance.length} 项验收`);
+    return { cp, st, done: `fix 模式：${acceptance.length} 项验收已冻结，直接进入 build` };
+  }
+  setNode(st, 'AwaitConfirm');
+  save(cp, st, 'prepare', `${acceptance.length} 项验收待确认`);
+  return { cp, st, done: `校验通过，抽出 ${acceptance.length} 项验收（${acceptance.filter((x) => x.kind === 'regression').length} 项回归）` };
+}
+
+function confirm(ctx, cp, st, a) {
+  requireNode(st, ['AwaitConfirm'], 'open --confirm');
+  requireExpect(st, a.values.expect);
+  if (computeDocHash(cp, st) !== st.confirm.doc_hash) {
+    die(BLOCK, 'brief/spec 在 prepare 之后又改过，用户看到的摘要已过期。重跑 open --prepare 再请用户确认。', { change: st.name });
+  }
+  const drift = sourceDrift(ctx, st);
+  if (drift.length) die(BLOCK, `源文件变化：${drift.join('；')}`, { change: st.name });
+  st.confirm.at = new Date().toISOString();
+  enterBuild(ctx, cp, st, 'confirm', '用户确认需求与验收项');
+  return { cp, st, done: `需求已确认，${st.acceptance.length} 项验收冻结，进入 build` };
+}
+
+export function cmdRename(ctx, a) {
+  const [name, next] = a._;
+  const { cp, st } = load(ctx, name);
+  requireNode(st, ['Drafting', 'AwaitConfirm'], 'rename');
+  validateName(next);
+  const to = changePaths(ctx, next);
+  if (existsSync(to.dir) || archivedDir(ctx, next)) die(BLOCK, `change '${next}' 已存在`);
+  renameSync(cp.dir, to.dir);
+  st.name = next;
+  if (st.workspace.branch === `comate/${name}` && currentBranch(ctx) === `comate/${name}` && !branchExists(ctx, `comate/${next}`)) {
+    gitOk(ctx.root, 'branch', '-m', `comate/${name}`, `comate/${next}`);
+    st.workspace.branch = `comate/${next}`;
+  }
+  if (st.phase === 'open' && st.step === 'confirm') st.confirm.doc_hash = computeDocHash(to, st);
+  saveState(to.state, st, 'rename', `${name} -> ${next}`);
+  return { cp: to, st, done: `已改名 ${name} -> ${next}` };
+}
+
+export function cmdSpec(ctx, a) {
+  const [sub, name, cap] = a._;
+  if (!['remove', 'restore'].includes(sub) || !cap) die(USAGE, '用法：spec remove|restore <name> <capability>');
+  const { cp, st } = load(ctx, name);
+  requireNode(st, ['Drafting', 'AwaitConfirm'], `spec ${sub}`);
+  const has = st.spec_targets.some((t) => t.op === 'remove' && t.capability === cap);
+  if (sub === 'remove') {
+    const h = hashFile(ctx.abs(`${ctx.specsRel}/${cap}/spec.md`));
+    if (!h) die(BLOCK, `主 spec 不存在：${ctx.specsRel}/${cap}/spec.md`);
+    if (has) die(BLOCK, `${cap} 已登记删除`);
+    st.spec_targets.push({ capability: cap, op: 'remove', base_hash: h });
+  } else {
+    if (!has) die(BLOCK, `${cap} 没有登记删除`);
+    st.spec_targets = st.spec_targets.filter((t) => !(t.op === 'remove' && t.capability === cap));
+  }
+  setNode(st, 'Drafting');
+  st.loop = freshLoop(st.loop.goal_cycle);
+  save(cp, st, `spec-${sub}`, cap);
+  return { cp, st, done: `${sub === 'remove' ? '已登记删除' : '已取消删除'} ${cap}，重跑 open --prepare` };
+}

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

@@ -0,0 +1,121 @@
+// status (read-only routing), doctor (health + safe repairs), import-specs.
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { loadConfig, resolveChecks } from './checks.mjs';
+import { load } from './common.mjs';
+import { docDrift } from './docs.mjs';
+import { probeList, probeRemove } from './git.mjs';
+import { activeChanges, capabilities, changePaths, requireInitialized } from './paths.mjs';
+import { loadState, nodeOf } from './state.mjs';
+import { git, hashFile } from './util.mjs';
+
+export function cmdStatus(ctx, a) {
+  requireInitialized(ctx);
+  if (a._[0]) return load(ctx, a._[0]);
+  const names = activeChanges(ctx);
+  if (names.length === 1) return load(ctx, names[0]);
+  const list = names.map((n) => {
+    try {
+      const st = loadState(changePaths(ctx, n).state);
+      return { name: n, node: nodeOf(st), phase: st.phase, step: st.step, iteration: st.loop.iteration, mode: st.mode };
+    } catch (err) {
+      return { name: n, error: err.message.split('\n')[0] };
+    }
+  });
+  const next = names.length === 0
+    ? { disposition: 'continue', action: 'new', message: '没有进行中的 change。按需求拟一个 kebab-case 名称后新建：', command: ['$COMATE', 'new', '<name>', '--mode', 'full'], changes: [] }
+    : { disposition: 'await-user', action: 'select-change', message: `有 ${names.length} 个进行中的 change。用户描述能对应其中一个就直接选，否则请用户选择：`, changes: list, command: null };
+  const lines = [`CHANGES ${names.length}`, ...list.map((c) => `  ${c.name}  ${c.error ? `损坏：${c.error}` : `${c.phase}/${c.step}  iteration ${c.iteration}${c.mode === 'fix' ? '  [fix]' : ''}`}`), `NEXT   ${next.message}`];
+  if (next.command) lines.push(`       node "$COMATE" new <name> [--mode full|fix] [--source <file>]`);
+  else lines.push('       node "$COMATE" status <name>');
+  return { lines, json: { ...next, comate: ctx.script } };
+}
+
+export function cmdDoctor(ctx, a) {
+  const out = [];
+  const add = (level, msg) => out.push({ level, msg });
+  const major = Number(process.versions.node.split('.')[0]);
+  add(major >= 20 ? 'ok' : 'fail', `Node ${process.versions.node}${major >= 20 ? '' : '（需要 >= 20）'}`);
+  const g = spawnSync('git', ['--version'], { encoding: 'utf8' });
+  add(g.status === 0 ? 'ok' : 'fail', g.status === 0 ? g.stdout.trim() : '找不到 git');
+  const gh = spawnSync('gh', ['--version'], { encoding: 'utf8' });
+  add(gh.status === 0 ? 'ok' : 'warn', gh.status === 0 ? 'gh 可用（支持 PR 收尾）' : '没有 gh CLI：收尾方式 pr 不可用');
+  if (!ctx) return report(out, a, '不在 git 仓库里');
+
+  if (!existsSync(ctx.abs(ctx.configRel))) {
+    add('warn', `未初始化：没有 ${ctx.configRel}（运行 comate init）`);
+  } else {
+    try {
+      const cfg = loadConfig(ctx);
+      add('ok', `${ctx.configRel} 合法`);
+      for (const p of resolveChecks(ctx, cfg).problems) add('warn', p);
+    } catch (err) {
+      add('fail', err.message);
+    }
+  }
+  if (existsSync(ctx.abs('openspec/changes'))) {
+    const legacy = readdirSync(ctx.abs('openspec/changes')).filter((d) => existsSync(ctx.abs(`openspec/changes/${d}/.comate.yaml`)));
+    if (legacy.length) add('warn', `发现 0.x 进行中的 change（${legacy.join(', ')}）：1.0 不自动转换，请用 comate 0.10.x 完成后再升级`);
+    if (existsSync(ctx.abs('openspec/specs'))) add('warn', 'openspec/specs 下有旧主规格：comate import-specs --dry-run 查看迁移清单');
+  }
+
+  for (const name of activeChanges(ctx)) {
+    const cp = changePaths(ctx, name);
+    let st;
+    try {
+      st = loadState(cp.state);
+    } catch (err) {
+      add('fail', `${name}：${err.message.split('\n')[0]}（手动核对 ${cp.stateRel}，或从 git 历史恢复：git checkout -- ${cp.stateRel}）`);
+      continue;
+    }
+    if (st.name !== name) add('fail', `${name}：state.json 里的 name 是 '${st.name}'，与目录名不符`);
+    const drift = st.phase === 'open' ? [] : docDrift(ctx, cp, st);
+    for (const d of drift) add('warn', `${name}：${d}`);
+    if (st.archive) add('warn', `${name}：归档中断（${st.archive.step}），重跑 node "$COMATE" archive ${name} 按证据继续`);
+    const tmps = readdirSync(cp.dir).filter((f) => f.endsWith('.tmp'));
+    if (tmps.length) {
+      if (a.flags.repair) for (const f of tmps) rmSync(join(cp.dir, f), { force: true });
+      add(a.flags.repair ? 'ok' : 'warn', `${name}：${a.flags.repair ? '已清理' : '残留'}临时文件 ${tmps.join(', ')}${a.flags.repair ? '' : '（doctor --repair 清理）'}`);
+    }
+    if (!drift.length && !st.archive && !tmps.length) add('ok', `${name}：${st.phase}/${st.step}，v${st.version}`);
+  }
+  const probes = probeList(ctx);
+  if (probes.length) {
+    if (a.flags.repair) for (const d of probes) probeRemove(ctx, d);
+    add(a.flags.repair ? 'ok' : 'warn', `${a.flags.repair ? '已清理' : '残留'} ${probes.length} 个反向验证 worktree${a.flags.repair ? '' : '（doctor --repair 清理）'}`);
+  }
+  if (a.flags.repair) git(ctx.root, 'worktree', 'prune');
+  return report(out, a);
+}
+
+function report(out, a, extra) {
+  const mark = { ok: '✓', warn: '⚠', fail: '✗' };
+  const lines = out.map((c) => `  ${mark[c.level]} ${c.msg}`);
+  if (extra) lines.push(`  · ${extra}`);
+  const failed = out.some((c) => c.level === 'fail');
+  return { lines, json: { ok: !failed, checks: out }, exit: failed ? 1 : 0 };
+}
+
+export function cmdImportSpecs(ctx, a) {
+  requireInitialized(ctx);
+  const src = ctx.abs('openspec/specs');
+  const plan = capabilities(src).map((cap) => {
+    const from = `openspec/specs/${cap}/spec.md`;
+    const to = `${ctx.specsRel}/${cap}/spec.md`;
+    const d = hashFile(ctx.abs(to));
+    const action = d === null ? 'copy' : d === hashFile(ctx.abs(from)) ? 'same' : 'conflict';
+    return { capability: cap, from, to, action };
+  });
+  if (!a.flags['dry-run']) {
+    for (const p of plan.filter((x) => x.action === 'copy')) {
+      mkdirSync(dirname(ctx.abs(p.to)), { recursive: true });
+      copyFileSync(ctx.abs(p.from), ctx.abs(p.to));
+    }
+  }
+  const label = { copy: a.flags['dry-run'] ? '将复制' : '已复制', same: '已存在且相同', conflict: '冲突（目标已存在且不同，未覆盖）' };
+  const lines = plan.length ? plan.map((p) => `  ${label[p.action]}  ${p.from} -> ${p.to}`) : ['  openspec/specs 下没有可迁移的主规格'];
+  if (!a.flags['dry-run'] && plan.some((p) => p.action === 'copy')) lines.push(`核对后提交：git add ${ctx.specsRel} && git commit -m "chore(comate): import specs"`);
+  return { lines, json: { dry_run: Boolean(a.flags['dry-run']), plan }, exit: plan.some((p) => p.action === 'conflict') ? 1 : 0 };
+}

package/skills/comate/scripts/lib/common.mjs

@@ -0,0 +1,85 @@
+// Helpers shared by the command modules.
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+
+import { loadConfig, resolveChecks, verifyPlan } from './checks.mjs';
+import { docDrift } from './docs.mjs';
+import { commitPaths, dirtyOutside, forkPoint } from './git.mjs';
+import { locateChange } from './paths.mjs';
+import { loadState, saveState, setNode } from './state.mjs';
+import { BLOCK, USAGE, die, ensureDir, log } from './util.mjs';
+
+export function load(ctx, name) {
+  if (!name) die(USAGE, '缺少 change 名称');
+  const cp = locateChange(ctx, name);
+  return { cp, st: loadState(cp.state) };
+}
+
+export const save = (cp, st, event, message) => saveState(cp.state, st, event, message);
+
+export function requireNoDrift(ctx, cp, st) {
+  const drift = docDrift(ctx, cp, st);
+  if (drift.length) {
+    die(BLOCK, `需求在确认后发生变化：\n  - ${drift.join('\n  - ')}\n误改就还原文件；需求确实要变就 decide --revise-requirements。`, { change: st.name });
+  }
+}
+
+// A path the agent passed on the command line: cwd first, then repo root.
+export function inputPath(ctx, raw, flag) {
+  if (!raw) die(USAGE, `缺少 ${flag} <file.json>`);
+  if (isAbsolute(raw)) return raw;
+  const fromCwd = resolve(process.cwd(), raw);
+  return existsSync(fromCwd) ? fromCwd : resolve(ctx.root, raw);
+}
+
+// open -> build: record the real fork point, freeze iteration 1, commit the
+// confirmed documents. A failed commit (hook) is a warning, not a stop: the
+// archive commit carries the change directory in the end either way.
+export function enterBuild(ctx, cp, st, event, message) {
+  ensureDir(ctx.abs(ctx.tempDir)); // 确保 .comate 目录存在
+  st.workspace.base_ref = forkPoint(ctx, st.workspace.base_ref, st.workspace.base_branch);
+  st.loop.iteration = 1;
+
+  // 保存确认时的测试计划指纹，用于降级判断
+  const cfg = loadConfig(ctx);
+  const { plan } = resolveChecks(ctx, cfg);
+  st.confirm.verify_plan = verifyPlan(plan);
+
+  setNode(st, 'Building');
+  save(cp, st, event, message);
+  try {
+    commitPaths(ctx, [cp.rel], `docs(comate): ${st.name}`);
+  } catch (err) {
+    log.warn(`提示：需求文档未能提交（${err.message.split('\n')[0]}），build 开始前请手动提交 ${cp.rel}`);
+  }
+}
+
+// Unresolved-set bookkeeping. Progress = this round's unresolved set is a
+// strict subset of the last one. Two stalls in a row -> hint; three -> stop.
+// Repair items remain in state and are included in the next build dispatch.
+export function queueRepairs(st, entries) {
+  st.loop.repairs = { iteration: st.loop.iteration, entries };
+}
+
+export function requireCleanTree(ctx, cp, st, extra = []) {
+  const dirty = dirtyOutside(ctx, [cp.rel, ...extra]);
+  if (dirty.length) {
+    die(BLOCK, `工作区有未提交改动：${dirty.slice(0, 10).join(', ')}${dirty.length > 10 ? ' …' : ''}\n验收只针对已提交的候选：属于本 change 就提交后重新 handoff，否则撤回。`, { change: st.name });
+  }
+}
+
+export function recordFailure(st, unresolved, cfg) {
+  const prev = new Set(st.loop.previous_unresolved);
+  const progress = prev.size > 0 && unresolved.length < prev.size && unresolved.every((id) => prev.has(id));
+  st.loop.fail_count += 1;
+  st.loop.no_progress_count = progress || prev.size === 0 ? 0 : st.loop.no_progress_count + 1;
+  st.loop.previous_unresolved = unresolved;
+  if (st.loop.fail_count >= cfg.max_verify_failures) {
+    st.loop.stop_reason = `验收失败已达上限 ${cfg.max_verify_failures} 次`;
+  } else if (st.loop.no_progress_count >= 3) {
+    st.loop.stop_reason = '连续 3 轮未解决集合没有缩小（停滞）';
+  } else {
+    st.loop.stop_reason = null;
+  }
+  return st.loop.stop_reason;
+}

package/skills/comate/scripts/lib/docs.mjs

@@ -0,0 +1,45 @@
+// Requirement documents of a change as one unit: which specs exist, the
+// confirmed doc_hash, and source-file drift. Build, verify and archive all
+// re-check these, so an edit after confirmation is caught wherever it happens.
+import { hashFile, hashText, readText } from './util.mjs';
+import { capabilities } from './paths.mjs';
+
+export function changeSpecList(cp) {
+  return capabilities(cp.specs).map((cap) => ({ cap, text: readText(`${cp.specs}/${cap}/spec.md`) }));
+}
+
+export function mainSpecText(ctx, cap) {
+  return readText(ctx.abs(`${ctx.specsRel}/${cap}/spec.md`));
+}
+
+// brief + every change spec + registered removals. tasks.md is deliberately
+// excluded: it is the build checklist and may change freely.
+export function computeDocHash(cp, st) {
+  const parts = [`brief\n${hashText(readText(cp.brief) ?? '')}`];
+  for (const { cap, text } of changeSpecList(cp)) parts.push(`spec:${cap}\n${hashText(text)}`);
+  const removes = st.spec_targets.filter((t) => t.op === 'remove').map((t) => t.capability).sort();
+  parts.push(`remove\n${removes.join(',')}`);
+  return hashText(parts.join('\n'));
+}
+
+export function sourceDrift(ctx, st) {
+  const out = [];
+  for (const s of st.sources) {
+    const now = hashFile(ctx.abs(s.path));
+    if (now === null) out.push(`源文件已不存在：${s.path}`);
+    else if (now !== s.sha256) out.push(`源文件已修改：${s.path}`);
+  }
+  return out;
+}
+
+// Problems that mean the confirmed requirements no longer match the disk.
+// Once archive has started writing main specs, a source that is itself a main
+// spec legitimately changes, so sources are no longer compared.
+export function docDrift(ctx, cp, st) {
+  if (!st.confirm.doc_hash) return [];
+  const out = st.archive ? [] : sourceDrift(ctx, st);
+  if (computeDocHash(cp, st) !== st.confirm.doc_hash) {
+    out.unshift('brief.md 或 specs/ 在确认后被修改（验收项已冻结）');
+  }
+  return out;
+}

package/skills/comate/scripts/lib/finish.mjs

@@ -0,0 +1,108 @@
+// Finish actions after the archive commit: keep / merge / push / pr. Nothing is
+// written to state afterwards (that would dirty the tree the archive just
+// committed), so whether a finish already happened is read from git itself.
+import { spawnSync } from 'node:child_process';
+import { resolve } from 'node:path';
+
+import { dirtyOutside, hasRemote, isAncestor, knownPath, worktreeFor } from './git.mjs';
+import { BLOCK, die, git, gitOk } from './util.mjs';
+
+const sha = (ctx, ref) => git(ctx.root, 'rev-parse', '--verify', '--quiet', `${ref}^{commit}`);
+const same = (a, b) => resolve(a).toLowerCase() === resolve(b).toLowerCase();
+const run = (cmd, args, cwd) => spawnSync(cmd, args, { cwd, encoding: 'utf8' });
+const why = (r) => (r.error ? r.error.message : `${r.stderr || r.stdout}`.trim() || `exit ${r.status}`);
+
+// Why a finish action cannot run here, or null. Shared by decide --accept and
+// finish: auto so an impossible action is refused before the archive commit.
+export function finishProblem(ctx, st, action) {
+  const { branch, base_branch: base } = st.workspace;
+  if (!['keep', 'merge', 'pr', 'push'].includes(action)) return '收尾方式只能是 keep / merge / pr / push';
+  if ((action === 'pr' || action === 'push') && !hasRemote(ctx)) return '没有 origin 远端，不能 push / pr';
+  if (action === 'merge' && branch === base) return `工作分支就是 ${base}，无需合并，选 keep`;
+  if (action === 'merge' && !sha(ctx, base)) return `目标分支 ${base} 不存在`;
+  return null;
+}
+
+// What the archive commit contains: touched capability dirs, old and new change dir.
+export const archivePaths = (ctx, st) => [
+  ...st.archive.targets.map((t) => `${ctx.specsRel}/${t.capability}`),
+  st.archive.from,
+  st.archive.dest,
+];
+
+// A created PR is remembered in local git config (not in the committed tree).
+const prKey = (st) => `comate.${st.name}.pr`;
+
+// Local evidence only — no network, so `status` stays fast and offline-safe.
+export function finishEvidence(ctx, st) {
+  const f = st.finish;
+  const { branch, base_branch: base } = st.workspace;
+  if (st.archive) {
+    const live = archivePaths(ctx, st).filter((p) => knownPath(ctx, p));
+    if (live.length && git(ctx.root, 'status', '--porcelain', '--', ...live)) return { done: false, message: '归档目录已移动，但归档提交还没完成。' };
+  }
+  if (!f || f.action === 'keep') return { done: true, message: `分支 ${branch} 已保留。` };
+  if (f.action === 'merge') {
+    const b = sha(ctx, branch);
+    const t = sha(ctx, base);
+    const done = branch === base || Boolean(b && t && isAncestor(ctx, b, t));
+    return { done, message: done ? `已合并到 ${base}。` : `尚未合并到 ${base}。` };
+  }
+  const b = sha(ctx, branch);
+  const pushed = Boolean(b && b === sha(ctx, `refs/remotes/origin/${branch}`));
+  if (!pushed) return { done: false, message: `${branch} 尚未推送。` };
+  if (f.action === 'push') return { done: true, message: `已推送 ${branch}。` };
+  const pr = git(ctx.root, 'config', '--get', prKey(st));
+  return pr ? { done: true, message: `PR：${pr}` } : { done: false, message: `${branch} 已推送，但还没有确认 PR 已创建。` };
+}
+
+export function runFinish(ctx, st, prBody) {
+  const f = st.finish;
+  const { branch, base_branch: base } = st.workspace;
+  const fail = (msg) => die(BLOCK, `归档已完成，但收尾「${f.action}」没有完成：${msg}\n处理后重跑 node "$COMATE" archive ${st.name}`, { change: st.name });
+  if (!f || f.action === 'keep') return `分支 ${branch} 已保留，未合并、未推送。`;
+
+  if (f.action === 'merge') {
+    if (finishEvidence(ctx, st).done) return `${branch} 已在 ${base} 中。`;
+    const wt = worktreeFor(ctx, base);
+    if (wt && !same(wt, ctx.root)) {
+      if (git(wt, 'status', '--porcelain')) fail(`${base} 签出在 ${wt}，那里有未提交改动`);
+      const r = run('git', ['-C', wt, 'merge', '--no-ff', '--no-edit', branch]);
+      if (r.status !== 0) {
+        run('git', ['-C', wt, 'merge', '--abort']);
+        fail(`在 ${wt} 合并冲突或失败，已中止合并：${why(r)}`);
+      }
+      return `已在 ${wt} 把 ${branch} 合并到 ${base}（--no-ff）。`;
+    }
+    const dirty = dirtyOutside(ctx, []);
+    if (dirty.length) fail(`当前工作区有未提交改动，无法切到 ${base}：${dirty.slice(0, 5).join(', ')}`);
+    gitOk(ctx.root, 'checkout', '-q', base);
+    const r = run('git', ['merge', '--no-ff', '--no-edit', branch], ctx.root);
+    if (r.status !== 0) {
+      run('git', ['merge', '--abort'], ctx.root);
+      run('git', ['checkout', '-q', branch], ctx.root);
+      fail(`合并冲突或失败，已中止并切回 ${branch}：${why(r)}`);
+    }
+    return `已把 ${branch} 合并到 ${base}（--no-ff），当前在 ${base}。是否推送远端由你决定。`;
+  }
+
+  if (!hasRemote(ctx)) fail('没有 origin 远端');
+  if (!finishEvidence(ctx, { ...st, finish: { action: 'push' } }).done) {
+    const r = run('git', ['push', '-u', 'origin', branch], ctx.root);
+    if (r.status !== 0) fail(`git push 失败：${why(r)}`);
+  }
+  if (f.action === 'push') return `已推送 ${branch} 到 origin。`;
+
+  const gh = run('gh', ['--version']);
+  if (gh.error || gh.status !== 0) fail('找不到 gh CLI（分支已推送，可手动创建 PR）');
+  const view = run('gh', ['pr', 'view', branch, '--json', 'url', '-q', '.url'], ctx.root);
+  if (view.status === 0 && view.stdout.trim()) {
+    git(ctx.root, 'config', prKey(st), view.stdout.trim());
+    return `PR 已存在：${view.stdout.trim()}`;
+  }
+  const r = run('gh', ['pr', 'create', '--base', base, '--head', branch, '--title', `comate: ${st.name}`, '--body', prBody], ctx.root);
+  if (r.status !== 0) fail(`gh pr create 失败：${why(r)}`);
+  const url = r.stdout.trim().split('\n').at(-1);
+  git(ctx.root, 'config', prKey(st), url);
+  return `已创建 PR：${url}`;
+}

package/skills/comate/scripts/lib/git.mjs

@@ -0,0 +1,112 @@
+// Git operations on the project root. Every helper takes ctx so the cwd the
+// script happened to start in never matters.
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { git, gitOk, toPosix } from './util.mjs';
+
+const status = (ctx, ...args) => spawnSync('git', ['-c', 'core.quotepath=false', ...args], { cwd: ctx.root, encoding: 'utf8' }).status;
+
+export const head = (ctx) => git(ctx.root, 'rev-parse', '--verify', 'HEAD');
+export const currentBranch = (ctx) => git(ctx.root, 'symbolic-ref', '--quiet', '--short', 'HEAD');
+export const branchExists = (ctx, b) => status(ctx, 'show-ref', '--verify', '--quiet', `refs/heads/${b}`) === 0;
+export const isAncestor = (ctx, a, b) => status(ctx, 'merge-base', '--is-ancestor', a, b) === 0;
+export const hasRemote = (ctx, r = 'origin') => git(ctx.root, 'remote', 'get-url', r) !== null;
+
+export function defaultBranch(ctx) {
+  const remote = git(ctx.root, 'symbolic-ref', 'refs/remotes/origin/HEAD')?.replace('refs/remotes/origin/', '');
+  if (remote) return remote;
+  for (const b of ['main', 'master']) if (branchExists(ctx, b)) return b;
+  return currentBranch(ctx);
+}
+
+// Newest ancestor of HEAD among the recorded ref and HEAD's merge-base with the
+// base branch (local and remote, either may be stale). Open can take days while
+// the base moves on, so the ref recorded at `new` alone is not enough.
+export function forkPoint(ctx, recorded, baseBranch) {
+  const h = head(ctx);
+  if (!h) return recorded;
+  const refs = [recorded];
+  if (baseBranch) refs.push(git(ctx.root, 'merge-base', 'HEAD', baseBranch), git(ctx.root, 'merge-base', 'HEAD', `origin/${baseBranch}`));
+  const cands = [...new Set(refs.filter(Boolean).map((r) => git(ctx.root, 'rev-parse', '--verify', `${r}^{commit}`)))].filter(
+    (c) => c && isAncestor(ctx, c, h),
+  );
+  if (!cands.length) return h;
+  return cands.find((c) => cands.every((o) => isAncestor(ctx, o, c))) ?? cands[0];
+}
+
+// Paths with uncommitted changes (staged, unstaged, untracked) outside `allowed` prefixes.
+export function dirtyOutside(ctx, allowed = []) {
+  const out = git(ctx.root, 'status', '--porcelain=v1', '-z', '--untracked-files=all') ?? '';
+  const parts = out.split('\0').filter(Boolean);
+  const paths = [];
+  for (let i = 0; i < parts.length; i++) {
+    const code = parts[i].slice(0, 2);
+    paths.push(parts[i].slice(3));
+    if (code.includes('R') || code.includes('C')) i++;
+  }
+  // 自动排除 .comate 临时目录
+  const allowedWithTemp = [...allowed, ctx.tempDir];
+  return paths.filter((p) => !allowedWithTemp.some((a) => p === a || p.startsWith(a.endsWith('/') ? a : `${a}/`)));
+}
+
+export function isClean(ctx, rel) {
+  const tracked = status(ctx, 'ls-files', '--error-unmatch', '--', rel) === 0;
+  return tracked && (git(ctx.root, 'status', '--porcelain', '--', rel) ?? '') === '';
+}
+
+// Commit exactly `paths` (other staged work is left staged, not swept in).
+// Returns the new sha, or null when there was nothing to commit.
+// On disk, in the index, or in HEAD — a staged deletion is only visible in HEAD.
+export const knownPath = (ctx, p) =>
+  existsSync(ctx.abs(p)) || Boolean(git(ctx.root, 'ls-files', '--', p)) || Boolean(git(ctx.root, 'ls-tree', '-r', '--name-only', 'HEAD', '--', p));
+
+export function commitPaths(ctx, paths, message) {
+  const keep = paths.filter((p) => knownPath(ctx, p));
+  if (!keep.length) return null;
+  const addable = keep.filter((p) => existsSync(ctx.abs(p)) || git(ctx.root, 'ls-files', '--', p));
+  if (addable.length) gitOk(ctx.root, 'add', '-A', '--', ...addable);
+  if (status(ctx, 'diff', '--cached', '--quiet', '--', ...keep) === 0) return null;
+  gitOk(ctx.root, 'commit', '-q', '-m', message, '--', ...keep);
+  return head(ctx);
+}
+
+export const changedFiles = (ctx, from, to) =>
+  (git(ctx.root, 'diff', '--name-only', `${from}..${to}`) ?? '').split('\n').filter(Boolean);
+
+export function worktreeFor(ctx, branch) {
+  const out = git(ctx.root, 'worktree', 'list', '--porcelain') ?? '';
+  let path = null;
+  for (const line of out.split('\n')) {
+    if (line.startsWith('worktree ')) path = line.slice(9).trim();
+    else if (line.trim() === `branch refs/heads/${branch}`) return toPosix(path);
+  }
+  return null;
+}
+
+export const remoteSha = (ctx, branch) => git(ctx.root, 'ls-remote', '--heads', 'origin', branch)?.split(/\s+/)[0] || null;
+
+// Throwaway worktree at `commit` in the OS temp dir, for reverse checks that
+// break code on purpose without touching the main working tree.
+export function probeAdd(ctx, name, commit) {
+  const dir = toPosix(mkdtempSync(join(tmpdir(), `comate-probe-${name}-`)));
+  rmSync(dir, { recursive: true, force: true });
+  gitOk(ctx.root, 'worktree', 'add', '--detach', dir, commit);
+  return dir;
+}
+
+export function probeRemove(ctx, dir) {
+  git(ctx.root, 'worktree', 'remove', '--force', dir);
+  rmSync(dir, { recursive: true, force: true });
+  git(ctx.root, 'worktree', 'prune');
+}
+
+export function probeList(ctx) {
+  const out = git(ctx.root, 'worktree', 'list', '--porcelain') ?? '';
+  return out
+    .split('\n')
+    .filter((l) => l.startsWith('worktree ') && /comate-probe-/.test(l))
+    .map((l) => toPosix(l.slice(9).trim()));
+}