@house365/comate 0.10.3 → 1.0.2-next.0

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

@@ -0,0 +1,85 @@
+// Minimal markdown structure: headings (outside code fences), list items, tables.
+
+const FENCE = /^\s*(```|~~~)/;
+
+// Sections at one heading level: [{ title, body, line }]. Deeper headings stay in the body.
+export function sections(text, level = 1) {
+  const head = new RegExp(`^${'#'.repeat(level)}\\s+(.+?)\\s*#*\\s*$`);
+  const out = [];
+  let cur = null;
+  let fenced = false;
+  text.split(/\r?\n/).forEach((line, i) => {
+    if (FENCE.test(line)) fenced = !fenced;
+    const m = fenced ? null : head.exec(line);
+    if (m) {
+      cur = { title: m[1].trim(), body: '', line: i + 1 };
+      out.push(cur);
+    } else if (cur) {
+      cur.body += `${line}\n`;
+    }
+  });
+  return out;
+}
+
+export const section = (text, title, level = 1) => sections(text, level).find((s) => s.title === title) ?? null;
+
+export const stripComments = (body) => body.replace(/<!--[\s\S]*?-->/g, '');
+export const isBlank = (body) => stripComments(body ?? '').trim() === '';
+
+const PLACEHOLDER = /\b(TODO|TBD|FIXME)\b|待填写|待补充/i;
+export const hasPlaceholder = (body) => PLACEHOLDER.test(stripComments(body ?? ''));
+
+// Top-level list items; indented lines that follow belong to the item above.
+export function listItems(body) {
+  const items = [];
+  let cur = null;
+  let fenced = false;
+  for (const line of stripComments(body).split(/\r?\n/)) {
+    if (FENCE.test(line)) fenced = !fenced;
+    const m = !fenced && /^(?:[-*+]|\d+[.)])\s+(.*\S)\s*$/.exec(line);
+    if (m) {
+      cur = { text: m[1] };
+      items.push(cur);
+    } else if (cur && /^\s+\S/.test(line)) {
+      cur.text += `\n${line.trim()}`;
+    } else if (line.trim() !== '') {
+      cur = null;
+    }
+  }
+  return items.map((i) => i.text);
+}
+
+const cellsOf = (line) =>
+  line
+    .trim()
+    .replace(/^\|/, '')
+    .replace(/\|$/, '')
+    .split(/(?<!\\)\|/)
+    .map((c) => c.replace(/\\\|/g, '|').trim().replace(/^`(.*)`$/, '$1'));
+
+// First table in body: { headers, rows: [{ header: cell }] } or null.
+export function table(body) {
+  const lines = stripComments(body).split(/\r?\n/);
+  const start = lines.findIndex((l) => l.trim().startsWith('|'));
+  if (start === -1) return null;
+  const block = [];
+  for (let i = start; i < lines.length && lines[i].trim().startsWith('|'); i++) block.push(lines[i]);
+  if (block.length < 2) return null;
+  const headers = cellsOf(block[0]).map((h) => h.toLowerCase());
+  const rows = block
+    .slice(1)
+    .filter((l) => !/^\|?\s*:?-{2,}/.test(l.trim()))
+    .map((l) => {
+      const cells = cellsOf(l);
+      return Object.fromEntries(headers.map((h, i) => [h, cells[i] ?? '']));
+    });
+  return { headers, rows };
+}
+
+// Body text normalised for comparison: trimmed lines, no blanks, no comments.
+export const normalizeBody = (body) =>
+  stripComments(body)
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .join('\n');

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

@@ -0,0 +1,217 @@
+// The next protocol: every command ends by telling the agent exactly
+// what to do next. `continue` = run `command`; `await-user` = relay `message`
+// and `alternatives` to the user and run the chosen one; `blocked` = fix what is
+// listed; `done` = report and stop. The agent never infers the phase itself.
+import { existsSync } from 'node:fs';
+
+import { briefSummary } from './brief.mjs';
+import { docDrift } from './docs.mjs';
+import { finishEvidence } from './finish.mjs';
+import { changedFiles, hasRemote } from './git.mjs';
+import { nodeOf } from './state.mjs';
+import { readText } from './util.mjs';
+
+const C = (...args) => ['$COMATE', ...args];
+const ex = (st) => `${st.version}:${st.step}`;
+
+export function nextFor(ctx, cp, st, extra = {}) {
+  const node = nodeOf(st);
+  const base = {
+    disposition: 'continue', change: st.name, node, phase: st.phase, step: st.step, status: st.status,
+    version: st.version, iteration: st.loop.iteration, mode: st.mode,
+    action: '', reference: null, message: '', command: null, alternatives: [], template: null, dispatch: null,
+    warnings: [], done: extra.done ?? null, comate: ctx.script,
+  };
+  const n = st.name;
+  const drift = cp.archived || st.phase === 'open' ? [] : docDrift(ctx, cp, st);
+  const reviseReq = { label: '需求确实要变：回 open 修改并重新确认', command: C('decide', n, '--revise-requirements', '--expect', ex(st)) };
+  if (drift.length && node !== 'Done') {
+    return {
+      ...base, disposition: 'blocked', action: 'resolve-drift', reference: 'reference/open.md',
+      warnings: drift,
+      message: '已确认的需求文档或源文件被改动。改动是误操作就还原文件（git checkout -- <文件>）后重跑 status；需求确实要变就回 open 重新确认。',
+      alternatives: [reviseReq],
+    };
+  }
+
+  switch (node) {
+    case 'Drafting':
+      return {
+        ...base, action: 'write-brief', reference: 'reference/open.md',
+        message: `澄清需求，写 ${cp.briefRel} 和 ${cp.specsRel}/<capability>/spec.md，然后校验并抽取验收项。`,
+        command: C('open', n, '--prepare'),
+      };
+    case 'AwaitConfirm':
+      return {
+        ...base, disposition: 'await-user', action: 'confirm', reference: 'reference/open.md',
+        message: '向用户完整转述确认摘要（目标、范围、非目标、关键决定、全部验收项、删除的 Scenario、change 名称），用 AskUserQuestion 请用户确认。',
+        dispatch: { summary: confirmSummary(cp, st) },
+        alternatives: [
+          { label: '确认，开始实现', command: C('open', n, '--confirm', '--expect', ex(st)) },
+          { label: '需要调整：改 brief/spec（或 rename 改名）后重跑 open --prepare', command: C('open', n, '--prepare') },
+        ],
+      };
+    case 'Building':
+    case 'Repairing': {
+      const repairing = node === 'Repairing';
+      const progress = repairing
+        ? `修复重点：${st.loop.previous_unresolved.join(', ')}`
+        : `全部验收项（${st.acceptance.length} 项）：${st.acceptance.map((a) => a.id).join(', ')}`;
+      const hint = st.loop.no_progress_count >= 2 ? '连续两轮没有进展：换一种修复思路，不要重复上一轮的改法。' : '';
+      return {
+        ...base, action: repairing ? 'repair' : 'build', reference: 'reference/build.md',
+        message: [
+          repairing
+            ? `修复轮 iteration ${st.loop.iteration}：${progress}，实现并提交候选。`
+            : `按 brief 和 spec 实现${st.loop.iteration === 1 ? '全部' : '本轮'}验收项。`,
+          progress, hint, `实现完成后在 .comate/handoff.json 的 addressed 字段列出本轮已实现的验收项 ID，执行 command。`,
+        ].filter(Boolean).join('\n'),
+        command: C('handoff', n, '--input', '.comate/handoff.json', '--expect', ex(st)),
+        template: { summary: '本轮改了什么', addressed: repairing ? st.loop.previous_unresolved : st.acceptance.map((a) => a.id), manual_checks: [{ id: 'A?', steps: '无法自动化的验收项的手工验证步骤' }], known_limits: [] },
+        dispatch: {
+          docs: { brief: cp.briefRel, specs: st.spec_targets.filter((t) => t.op !== 'remove').map((t) => `${cp.specsRel}/${t.capability}/spec.md`) },
+          acceptance: st.acceptance.map((a) => ({ id: a.id, kind: a.kind, source: a.source, text: a.text, result: a.result, reason: a.reason })),
+          failed_checks: repairing ? (st.candidate?.checks ?? []).filter((c) => !c.ok) : [],
+          verifier_summary: repairing ? st.verifier?.summary ?? null : null,
+          repairs: repairing ? st.loop.repairs?.entries ?? [] : [],
+        },
+        alternatives: [reviseReq],
+      };
+    }
+    case 'Checking':
+      return { ...base, action: 'resume-checks', message: '检查命令执行被中断。重新执行检查：', command: C('handoff', n, '--recheck', '--expect', ex(st)) };
+    case 'AwaitVerifier':
+      return verifierNext(ctx, cp, st, base);
+    case 'AwaitAccept': {
+      const risks = st.verifier?.risks ?? [];
+      const alts = [
+        { label: `接受并本地合并到 ${st.workspace.base_branch}`, command: C('decide', n, '--accept', '--finish', 'merge', '--expect', ex(st)) },
+        { label: '接受并推送、创建 PR', command: C('decide', n, '--accept', '--finish', 'pr', '--expect', ex(st)) },
+        { label: '接受并保留分支（稍后自己处理）', command: C('decide', n, '--accept', '--finish', 'keep', '--expect', ex(st)) },
+        { label: '回去修改实现（需求不变）', command: C('decide', n, '--revise-implementation', '--note', '<要改什么>', '--expect', ex(st)) },
+        reviseReq,
+      ];
+      if (!hasRemote(ctx)) alts.splice(1, 1);
+      if (st.workspace.branch === st.workspace.base_branch) alts.splice(0, 1);
+      return {
+        ...base, disposition: 'await-user', action: 'accept', reference: 'reference/archive.md',
+        message: `${st.acceptance.length} 项验收全部通过。${risks.length ? `verifier 提出的风险：\n- ${risks.map((r) => (typeof r === 'string' ? r : r.text)).join('\n- ')}\n` : ''}一次问完：是否接受结果，以及收尾方式。`,
+        alternatives: alts,
+      };
+    }
+    case 'Stuck':
+      return {
+        ...base, disposition: 'await-user', action: 'resolve-stuck', reference: 'reference/verify.md',
+        message: `自动回修已停下：${st.loop.stop_reason}。仍未解决：${st.loop.previous_unresolved.join(', ') || '（检查命令失败）'}。向用户说明已尝试的修复与失败原因，请用户决定。`,
+        alternatives: [
+          { label: '换思路再修（用户给方向）', command: C('decide', n, '--revise-implementation', '--note', '<新的修复方向>', '--expect', ex(st)) },
+          reviseReq,
+        ],
+      };
+    case 'Blocked':
+      return {
+        ...base, disposition: 'await-user', action: 'resolve-blocker', reference: 'reference/verify.md',
+        message: `验收被阻塞，需要用户或外部信息：\n- ${st.blockers.map((b) => `${b.id ? `${b.id}：` : ''}${b.reason}`).join('\n- ')}`,
+        alternatives: [
+          { label: '已补充信息，重新验收', command: C('decide', n, '--resolve', '--note', '<补充的信息>', '--expect', ex(st)) },
+          reviseReq,
+        ],
+      };
+    case 'Degraded':
+      return {
+        ...base, disposition: 'await-user', action: 'accept-degraded', reference: 'reference/verify.md',
+        message: '没有可用的独立 verifier，只有自动检查通过。这不等于逐项验收，必须由用户明确接受。',
+        alternatives: [
+          { label: '接受「仅自动检查」的结果并保留分支', command: C('decide', n, '--accept', '--finish', 'keep', '--expect', ex(st)) },
+          ...(st.workspace.branch === st.workspace.base_branch ? [] : [{ label: '接受并本地合并', command: C('decide', n, '--accept', '--finish', 'merge', '--expect', ex(st)) }]),
+          { label: '不接受：回去补充实现或测试', command: C('decide', n, '--revise-implementation', '--note', '<要补什么>', '--expect', ex(st)) },
+        ],
+      };
+    case 'ArchiveReady':
+      return { ...base, action: 'archive', reference: 'reference/archive.md', message: `归档并执行收尾（${st.finish?.action ?? 'keep'}）。`, command: C('archive', n) };
+    case 'Done': {
+      const ev = finishEvidence(ctx, st);
+      if (!ev.done) {
+        return {
+          ...base, disposition: 'blocked', action: 'retry-finish', reference: 'reference/archive.md',
+          message: `归档${st.finish ? `已完成，收尾「${st.finish.action}」` : ''}未完成：${ev.message}处理后重试：`,
+          command: C('archive', n),
+          alternatives: st.finish && st.finish.action !== 'keep'
+            ? [{ label: '改为保留分支（用户同意放弃这个收尾时）', command: C('decide', n, '--accept', '--finish', 'keep', '--expect', ex(st)) }]
+            : [],
+        };
+      }
+      return { ...base, disposition: 'done', action: 'report', message: `已归档到 ${st.archive?.dest ?? cp.rel}。${ev.message}` };
+    }
+    default:
+      return { ...base, disposition: 'blocked', action: 'doctor', message: '状态无法识别，运行 doctor。', command: C('doctor', n) };
+  }
+}
+
+export function confirmSummary(cp, st) {
+  return {
+    name: st.name,
+    ...briefSummary(readText(cp.brief) ?? ''),
+    acceptance: st.acceptance.map((a) => ({ id: a.id, kind: a.kind, source: a.source, text: a.text })),
+    removed_scenarios: st.removed_scenarios,
+    spec_targets: st.spec_targets.map((t) => `${t.capability}: ${t.op}`),
+    source_map: st.source_map,
+  };
+}
+
+function verifierNext(ctx, cp, st, base) {
+  const n = st.name;
+  const resultRel = `.comate/verify-result.json`;
+  const specs = st.spec_targets.filter((t) => t.op !== 'remove').map((t) => `${cp.specsRel}/${t.capability}/spec.md`);
+  const dispatch = {
+    role: '独立只读 verifier：未参与本次 build 的子 agent，不修改主工作区任何文件',
+    instructions: 'reference/verify.md',
+    token: st.verifier.token,
+    candidate: st.candidate.commit,
+    base_ref: st.workspace.base_ref,
+    docs: { brief: cp.briefRel, specs },
+    acceptance: st.acceptance.map((a) => ({ id: a.id, kind: a.kind, source: a.source, text: a.text })),
+    diff: { command: `git diff ${st.workspace.base_ref}...${st.candidate.commit}`, files: changedFiles(ctx, st.workspace.base_ref, st.candidate.commit) },
+    checks: st.candidate.checks,
+    handoff: st.candidate.handoff,
+    probe: { create: `node "${ctx.script}" probe ${n}`, remove: `node "${ctx.script}" probe ${n} --remove <dir>` },
+    result_file: resultRel,
+  };
+  return {
+    ...base, action: 'dispatch-verifier', reference: 'reference/verify.md',
+    message: `派发一个未参与 build 的只读 verifier 子 agent，把 dispatch 原样交给它；它把结果写进 ${resultRel} 后执行 command。`,
+    command: C('verify', n, '--result', resultRel),
+    template: {
+      token: st.verifier.token, candidate: st.candidate.commit,
+      acceptance: st.acceptance.map((a) => ({ id: a.id, result: 'passed | failed | blocked', reason: '证据：实现位置、测试名与断言、或手工步骤与结果' })),
+      reverse_checks: [{ target: 'A?', mutation: '临时改错了什么', test: '跑的测试', failed_as_expected: true }],
+      risks: [], summary: '',
+    },
+    dispatch,
+    alternatives: [
+      { label: 'verifier 执行出错（崩溃、超时、无结果）', command: C('verify', n, '--error', '<原因>') },
+      { label: '平台没有子 agent 能力（降级，须用户明确接受）', command: C('verify', n, '--unavailable', '--expect', ex(st)) },
+    ],
+  };
+}
+
+const quote = (a) => (/^[A-Za-z0-9_./:@=$<>-]+$/.test(a) ? a : `"${a.replace(/"/g, '\\"')}"`);
+export const commandText = (cmd) => cmd.map((a, i) => (i === 0 && a === '$COMATE' ? 'node "$COMATE"' : quote(a))).join(' ');
+
+export function formatText(next) {
+  const out = [`STATE  ${next.change}  ${next.phase}/${next.step}  v${next.version}  iteration ${next.iteration}${next.mode === 'fix' ? '  [fix]' : ''}`];
+  if (next.done) out.push(`DONE   ${next.done}`);
+  for (const w of next.warnings) out.push(`WARN   ${w}`);
+  if (next.message) out.push(...next.message.split('\n').map((l, i) => `${i ? '       ' : 'NEXT   '}${l}`));
+  if (next.command) out.push(`       ${commandText(next.command)}`);
+  next.alternatives.forEach((a, i) => out.push(`  ${i + 1}) ${a.label}`, `     ${commandText(a.command)}`));
+  if (next.dispatch?.summary) {
+    const s = next.dispatch.summary;
+    out.push('', `目标：${s.goal}`, `范围：${s.scope}`, `非目标：${s.non_goals}`, `决定：${s.decisions}`, '验收项：');
+    for (const a of s.acceptance) out.push(`  ${a.id} [${a.kind}] ${a.text.split('\n')[0]}  (${a.source})`);
+    if (s.removed_scenarios.length) out.push(`删除的 Scenario：${s.removed_scenarios.map((r) => `${r.capability}#${r.title}`).join('、')}`);
+  }
+  if (next.dispatch && !next.dispatch.summary) out.push('       （详细信息用 --json 读取 dispatch 与 template）');
+  if (next.reference) out.push(`READ   ${next.reference}`);
+  return out.join('\n');
+}

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

@@ -0,0 +1,96 @@
+// Project layout. Everything comate manages lives under <repo>/comate/comate/;
+// paths kept in state are repo-relative with forward slashes, so a state file is
+// byte-identical whichever OS wrote it.
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { ENV, USAGE, die, git, toPosix } from './util.mjs';
+
+export const BASE = 'comate/comate';
+export const TEMP_DIR = '.comate';
+
+export function makeContext(cwd, script) {
+  const top = git(cwd, 'rev-parse', '--show-toplevel');
+  if (!top) die(ENV, '当前目录不在 git 仓库里。comate 1.0 需要 git：先 git init，再运行 comate init。');
+  const root = toPosix(top);
+  return {
+    root,
+    script: toPosix(script),
+    base: BASE,
+    tempDir: TEMP_DIR,
+    configRel: `${BASE}/config.json`,
+    specsRel: `${BASE}/specs`,
+    changesRel: `${BASE}/changes`,
+    archiveRel: `${BASE}/archive`,
+    abs: (rel) => join(root, rel),
+  };
+}
+
+export function requireInitialized(ctx) {
+  if (!existsSync(ctx.abs(ctx.configRel))) {
+    die(ENV, `未初始化：找不到 ${ctx.configRel}。在项目根运行 comate init。`);
+  }
+}
+
+export function changePaths(ctx, name, dirRel = `${ctx.changesRel}/${name}`) {
+  return {
+    name,
+    rel: dirRel,
+    dir: ctx.abs(dirRel),
+    stateRel: `${dirRel}/state.json`,
+    state: ctx.abs(`${dirRel}/state.json`),
+    briefRel: `${dirRel}/brief.md`,
+    brief: ctx.abs(`${dirRel}/brief.md`),
+    tasksRel: `${dirRel}/tasks.md`,
+    tasks: ctx.abs(`${dirRel}/tasks.md`),
+    specsRel: `${dirRel}/specs`,
+    specs: ctx.abs(`${dirRel}/specs`),
+    verificationRel: `${dirRel}/verification.md`,
+    verification: ctx.abs(`${dirRel}/verification.md`),
+  };
+}
+
+export function validateName(name) {
+  if (!name) die(USAGE, 'change 名称不能为空');
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
+    die(USAGE, `change 名称 '${name}' 不合法：只允许小写字母、数字和连字符（kebab-case），如 add-email-login`);
+  }
+}
+
+export function activeChanges(ctx) {
+  const dir = ctx.abs(ctx.changesRel);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && existsSync(join(dir, e.name, 'state.json')))
+    .map((e) => e.name)
+    .sort();
+}
+
+// Newest archive/YYYY-MM-DD-<name> for an archived change, or null.
+export function archivedDir(ctx, name) {
+  const dir = ctx.abs(ctx.archiveRel);
+  if (!existsSync(dir)) return null;
+  const hits = readdirSync(dir)
+    .filter((d) => /^\d{4}-\d{2}-\d{2}-/.test(d) && d.slice(11) === name)
+    .sort();
+  return hits.length ? `${ctx.archiveRel}/${hits.at(-1)}` : null;
+}
+
+// Active first, then archive (archive/finish recovery runs against the moved dir).
+export function locateChange(ctx, name) {
+  validateName(name);
+  const active = changePaths(ctx, name);
+  if (existsSync(active.state)) return { ...active, archived: false };
+  const moved = archivedDir(ctx, name);
+  if (moved && existsSync(ctx.abs(`${moved}/state.json`))) return { ...changePaths(ctx, name, moved), archived: true };
+  return die(USAGE, `找不到 change '${name}'。运行 node "$COMATE" status 查看现有 change。`);
+}
+
+// Capability directories under a specs dir (each holding spec.md).
+export function capabilities(specsAbs) {
+  if (!existsSync(specsAbs)) return [];
+  return readdirSync(specsAbs, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && existsSync(join(specsAbs, e.name, 'spec.md')))
+    .map((e) => e.name)
+    .sort();
+}

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

@@ -0,0 +1,46 @@
+// verification.md is generated from state.json after every verify result. Hand
+// edits are pointless: the next render overwrites them.
+import { writeAtomic } from './util.mjs';
+
+const esc = (s) => String(s ?? '').replace(/\|/g, '\\|').replace(/\r?\n/g, '<br>');
+const RESULT = { passed: '✅ 通过', failed: '❌ 未通过', blocked: '⛔ 无法验证', pending: '… 待验收' };
+
+export function renderVerification(st) {
+  const lines = [`# 验证报告：${st.name}`, '', '> 本文件由 comate 脚本根据 state.json 生成，手改无效。', ''];
+  const v = st.verifier;
+  const c = st.candidate;
+  const passed = st.acceptance.filter((a) => a.result === 'passed').length;
+  lines.push('## 结论', '');
+  if (st.step === 'degraded' || (st.phase === 'archive' && v && v.independent === false)) {
+    lines.push('降级：没有独立 verifier，只有自动检查，由用户明确接受。');
+  } else {
+    lines.push(`${passed}/${st.acceptance.length} 项验收通过（iteration ${st.loop.iteration}）。`);
+  }
+  if (v?.summary) lines.push('', v.summary);
+  lines.push('', '## 候选', '');
+  lines.push(`- commit：\`${c?.commit ?? '-'}\``);
+  lines.push(`- 基线：\`${st.workspace.base_ref ?? '-'}\`（${st.workspace.base_branch ?? '-'}）`);
+  if (c?.handoff?.summary) lines.push(`- builder 摘要：${esc(c.handoff.summary)}`);
+  lines.push('', '## 验收项', '', '| ID | 类型 | 来源 | 结果 | 理由 |', '|---|---|---|---|---|');
+  for (const a of st.acceptance) {
+    lines.push(`| ${a.id} | ${a.kind} | ${esc(a.source)} | ${RESULT[a.result] ?? a.result} | ${esc(a.reason)} |`);
+  }
+  lines.push('', '## 自动检查', '');
+  if (!c?.checks?.length) lines.push('无（项目配置为 none）。');
+  for (const k of c?.checks ?? []) {
+    lines.push(`- ${k.ok ? '✅' : '❌'} \`${k.cmd}\` — ${k.timed_out ? '超时' : `exit ${k.exit}`}，${(k.ms / 1000).toFixed(1)}s`);
+  }
+  const reverse = v?.reverse_checks ?? [];
+  if (reverse.length) {
+    lines.push('', '## 反向验证', '', '| 对象 | 破坏方式 | 运行的测试 | 测试变红 |', '|---|---|---|---|');
+    for (const r of reverse) lines.push(`| ${esc(r.target)} | ${esc(r.mutation)} | ${esc(r.test)} | ${r.failed_as_expected ? '是' : '否'} |`);
+  }
+  if (v?.risks?.length) {
+    lines.push('', '## 风险与建议', '');
+    for (const r of v.risks) lines.push(`- ${typeof r === 'string' ? r : `${r.severity ?? 'note'}：${r.text ?? JSON.stringify(r)}`}`);
+  }
+  lines.push('', '## 核验方式', '', v?.independent === false ? '仅自动检查（verifier 不可用）' : '独立只读 verifier');
+  return `${lines.join('\n')}\n`;
+}
+
+export const writeVerification = (cp, st) => writeAtomic(cp.verification, renderVerification(st));

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

@@ -0,0 +1,106 @@
+// specs/<capability>/spec.md: the complete target behaviour of a capability
+// (not a delta). Scenarios are `### Scenario: <title>`; OpenSpec's `####` level
+// is also read so imported main specs parse the same way.
+import { hasPlaceholder, normalizeBody, stripComments } from './md.mjs';
+
+const SCENARIO = /^(#{3,4})\s+Scenario\s*[:：]\s*(.+?)\s*#*\s*$/i;
+const REQUIREMENT = /^(#{2,3})\s+Requirement\s*[:：]\s*(.*?)\s*#*\s*$/i;
+const ANY_HEADING = /^(#{1,6})\s/;
+const FENCE = /^\s*(```|~~~)/;
+
+export function parseSpec(text) {
+  const scenarios = [];
+  const requirements = [];
+  const requirementFor = new Map();
+  let curReq = null;
+  let curScenario = null;
+  let fenced = false;
+
+  stripComments(text)
+    .split(/\r?\n/)
+    .forEach((line, i) => {
+      if (FENCE.test(line)) fenced = !fenced;
+
+      const req = !fenced && REQUIREMENT.exec(line);
+      if (req) {
+        curReq = { title: req[2], level: req[1].length, body: '', line: i + 1 };
+        requirements.push(curReq);
+        curScenario = null;
+      } else if (!fenced) {
+        const m = SCENARIO.exec(line);
+        if (m) {
+          curScenario = { title: m[2].trim(), body: '', line: i + 1, requirement: null };
+          scenarios.push(curScenario);
+          requirementFor.set(curScenario, curReq);
+        } else if (ANY_HEADING.test(line)) {
+          const level = ANY_HEADING.exec(line)[1].length;
+          if (curReq && level > curReq.level) curReq.body += `${line}\n`;
+          else curReq = null;
+          curScenario = null;
+        } else if (curScenario) {
+          curScenario.body += `${line}\n`;
+        } else if (curReq) {
+          curReq.body += `${line}\n`;
+        }
+      } else {
+        if (curScenario) curScenario.body += `${line}\n`;
+        else if (curReq) curReq.body += `${line}\n`;
+      }
+    });
+
+  for (const s of scenarios) {
+    s.body = normalizeBody(s.body);
+    const req = requirementFor.get(s);
+    s.requirement = req ? normalizeBody(`Requirement: ${req.title}\n${req.body}`) : null;
+  }
+  const reqBodies = requirements.map((r) => normalizeBody(r.body));
+  return { requirements: reqBodies.length, requirementBodies: reqBodies, scenarios };
+}
+
+// 统一步骤解析：提取 WHEN/THEN/那么 等步骤，忽略代码块
+function parseSteps(body) {
+  const steps = [];
+  const lines = body.split('\n');
+  let inFence = false;
+
+  for (const line of lines) {
+    if (/^\s*(```|~~~)/.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+
+    const step = line.replace(/^\s*(?:[-*+]|\d+[.)])\s+/, '').trim();
+    const match = step.match(/^(?:\*\*(WHEN|THEN|GIVEN|那么|当|假设)\*\*|(WHEN|THEN|GIVEN|那么|当|假设))(?=\s|[:：]|$)\s*[:：]?\s*(.*)$/i);
+    if (match) {
+      steps.push({ keyword: (match[1] ?? match[2]).toUpperCase(), content: match[3].trim() });
+    }
+  }
+
+  return steps;
+}
+
+// Problems that make a change spec unusable as an acceptance source.
+export function checkChangeSpec(cap, text) {
+  const { scenarios } = parseSpec(text);
+  const problems = [];
+  if (scenarios.length === 0) {
+    problems.push(`specs/${cap}/spec.md 没有任何「### Scenario:」`);
+  }
+  const seen = new Set();
+  for (const s of scenarios) {
+    if (seen.has(s.title)) problems.push(`specs/${cap}/spec.md 的 Scenario「${s.title}」重复`);
+    seen.add(s.title);
+    if (!s.body) problems.push(`specs/${cap}/spec.md 的 Scenario「${s.title}」没有正文`);
+    else {
+      const steps = parseSteps(s.body);
+      const thenSteps = steps.filter((st) => st.keyword === 'THEN' || st.keyword === '那么');
+      const hasThen = thenSteps.some((st) => st.content && !hasPlaceholder(st.content));
+
+      if (!hasThen) {
+        problems.push(`specs/${cap}/spec.md 的 Scenario「${s.title}」缺少 THEN（可检验的结果）`);
+      }
+    }
+  }
+  return problems;
+}