@house365/comate 0.10.2 → 1.0.2-next.0

package/skills/{comate-gate/scaffold/docs → comate/scaffold/comate}/knowledge-base/integrations/_TEMPLATE/README.md

@@ -14,8 +14,8 @@
 |------|------|
 | 服务标识 | <目录名,如 oceanengine> |
 | 对接目的 | <为什么对接它,支撑哪个需求> |
-| 关联需求 | docs/knowledge-base/requirements/<YYYYMMDD-功能名>/PRD-001-<功能名>.md |
-| 关联变更 | openspec/changes/<变更名>/ |
+| 关联需求 | comate/knowledge-base/requirements/<YYYYMMDD-功能名>/PRD-001-<功能名>.md |
+| 关联变更 | comate/comate/changes/<变更名>/ |
 | 官方文档 | <URL> |
 | 我方负责人 | <name> |
 | 对方联系人 | <姓名/渠道,非必填> |

package/skills/{comate-gate/scaffold/docs → comate/scaffold/comate}/knowledge-base/integrations/_TEMPLATE/api-snapshot.md

@@ -1,47 +1,47 @@
-# <平台名> 接口摘录 (API Snapshot)
-
-| 作者 | 更新时间 | 原文档地址 |
-|------|---------|-----------|
-| <建档/最近修改人,默认 git 用户名> | <YYYY-MM-DD,改动即更新> | <官方文档主 URL> |
-
-> 只摘录**我方实际用到**的接口与字段,不复制官方全文。
-> 标题正下方的「作者/更新时间/原文档地址」三项**必填**(本档案是我方二开文档,须可追溯回官方原文)。
-> 官方文档: <URL>
-> 抓取日期: <YYYY-MM-DD>  ← 每次对照官方更新时改这里
-
----
-
-## <接口1: 如 获取 access_token>
-
-**请求**
-```
-POST https://<host>/oauth/token
-Content-Type: application/json
-```
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| app_key | string | 是 | 见 README 凭证位置 |
-| grant_type | string | 是 | 固定 client_credentials |
-
-**响应**
-```json
-{
-  "access_token": "<string>",
-  "expires_in": 7200
-}
-```
-
-| 字段 | 说明 | 我方注意点 |
-|------|------|-----------|
-| expires_in | 有效期(秒) | ⚠️ 实测 2h,需提前刷新 |
-
-**错误码/异常**
-
-| code/status | 含义 | 我方处理 |
-|-------------|------|----------|
-| <...> | <...> | <重试/告警/提示用户/忽略> |
-
----
-
-## <接口2: ...>
+# <平台名> 接口摘录 (API Snapshot)
+
+| 作者 | 更新时间 | 原文档地址 |
+|------|---------|-----------|
+| <建档/最近修改人,默认 git 用户名> | <YYYY-MM-DD,改动即更新> | <官方文档主 URL> |
+
+> 只摘录**我方实际用到**的接口与字段,不复制官方全文。
+> 标题正下方的「作者/更新时间/原文档地址」三项**必填**(本档案是我方二开文档,须可追溯回官方原文)。
+> 官方文档: <URL>
+> 抓取日期: <YYYY-MM-DD>  ← 每次对照官方更新时改这里
+
+---
+
+## <接口1: 如 获取 access_token>
+
+**请求**
+```
+POST https://<host>/oauth/token
+Content-Type: application/json
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| app_key | string | 是 | 见 README 凭证位置 |
+| grant_type | string | 是 | 固定 client_credentials |
+
+**响应**
+```json
+{
+  "access_token": "<string>",
+  "expires_in": 7200
+}
+```
+
+| 字段 | 说明 | 我方注意点 |
+|------|------|-----------|
+| expires_in | 有效期(秒) | ⚠️ 实测 2h,需提前刷新 |
+
+**错误码/异常**
+
+| code/status | 含义 | 我方处理 |
+|-------------|------|----------|
+| <...> | <...> | <重试/告警/提示用户/忽略> |
+
+---
+
+## <接口2: ...>

package/skills/{comate-gate/scaffold/docs → comate/scaffold/comate}/knowledge-base/requirements/_templates/PRD.md

@@ -1,7 +1,7 @@
 # PRD-<序号>-<功能名>: <产品标题>
 
-> 复制本文件到需求目录，按项目约定命名，删除本行与所有 `<...>` 占位说明。
-> PRD = 产品需求文档，回答「做成什么样」。本 PRD 由 `/comate-gate` 直接读取：先过质量门禁（审阅、评分、阻断检查），通过后按依赖和独立性拆成 1 或 N 个 comate change。
+> 复制本文件到需求目录，按项目约定命名，删除本行与所有 `<...>` 占位说明。
+> PRD = 产品需求文档，回答「做成什么样」。本 PRD 由 `/comate` 直接读取：澄清未决策项后，按依赖和独立性拆成 1 或 N 个 comate change 并写出规约。
 
 | 字段 | 内容 |
 |------|------|
@@ -39,7 +39,7 @@
 
 ### 功能清单
 
-> `/comate-gate` 据此清单判定拆分粒度:有依赖的功能项归同一 change,独立的可拆开。请标清优先级。
+> `/comate` 据此清单判定拆分粒度:有依赖的功能项归同一 change,独立的可拆开。请标清优先级。
 
 | 功能 | 说明 | 优先级 (P0/P1/P2) |
 |------|------|------------------|
@@ -65,7 +65,7 @@
 |--------|------|------|--------------|--------|
 | <平台名> | <本产品中用它做什么> | <限流/权限/回调/稳定性等> | <超时/未配置/返回错误如何处理> | <name> |
 
-> 对接档案: docs/knowledge-base/integrations/<平台名>/README.md
+> 对接档案: comate/knowledge-base/integrations/<平台名>/README.md
 
 ## 数据与来源
 

package/skills/comate/scripts/comate.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// comate.mjs — the single entry of the comate 1.0 state machine. Zero
+// dependencies, Node >= 20. Flow: open -> build <-> verify -> archive.
+// Every command ends with a next (text, or --json for agents).
+//
+// Exit codes: 0 OK | 1 BLOCK (a guard refused; the next says what to
+// fix) | 2 USAGE | 3 ENV | 4 CORRUPT
+import { fileURLToPath } from 'node:url';
+
+import { cmdArchive } from './lib/cmd-archive.mjs';
+import { cmdDecide } from './lib/cmd-decide.mjs';
+import { cmdInit } from './lib/cmd-init.mjs';
+import { cmdHandoff, cmdProbe, cmdVerify } from './lib/cmd-loop.mjs';
+import { cmdNew, cmdOpen, cmdRename, cmdSpec } from './lib/cmd-open.mjs';
+import { cmdDoctor, cmdImportSpecs, cmdStatus } from './lib/cmd-status.mjs';
+import { load } from './lib/common.mjs';
+import { nextFor, formatText } from './lib/next.mjs';
+import { makeContext } from './lib/paths.mjs';
+import { BLOCK, ComateError, OK, USAGE, die, log } from './lib/util.mjs';
+
+const SCRIPT = fileURLToPath(import.meta.url);
+
+// command -> [handler, allowed options]
+const COMMANDS = {
+  init: [cmdInit, []],
+  status: [cmdStatus, []],
+  new: [cmdNew, ['mode', 'source', 'base']],
+  open: [cmdOpen, ['prepare', 'confirm', 'expect']],
+  rename: [cmdRename, []],
+  spec: [cmdSpec, []],
+  handoff: [cmdHandoff, ['input', 'expect', 'recheck']],
+  verify: [cmdVerify, ['result', 'error', 'unavailable', 'expect']],
+  probe: [cmdProbe, ['remove']],
+  decide: [cmdDecide, ['expect', 'accept', 'finish', 'revise-implementation', 'revise-requirements', 'resolve', 'upgrade', 'note']],
+  archive: [cmdArchive, ['dry-run']],
+  doctor: [cmdDoctor, ['repair']],
+  'import-specs': [cmdImportSpecs, ['dry-run']],
+};
+const VALUED = new Set(['mode', 'source', 'base', 'expect', 'input', 'result', 'error', 'remove', 'finish', 'note']);
+
+export function parseArgs(argv) {
+  const a = { _: [], flags: {}, values: {}, sources: [], used: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (!tok.startsWith('--')) {
+      a._.push(tok);
+      continue;
+    }
+    const eq = tok.indexOf('=');
+    const key = eq === -1 ? tok.slice(2) : tok.slice(2, eq);
+    a.used.push(key);
+    if (!VALUED.has(key)) {
+      if (eq !== -1) die(USAGE, `--${key} 不接受值`);
+      a.flags[key] = true;
+      continue;
+    }
+    const value = eq !== -1 ? tok.slice(eq + 1) : argv[++i];
+    if (value === undefined) die(USAGE, `--${key} 需要一个值`);
+    if (key === 'source') a.sources.push(value);
+    else a.values[key] = value;
+  }
+  return a;
+}
+
+const USAGE_TEXT = `comate 1.0 — open → build ⇄ verify → archive
+
+  init                                             初始化 comate 项目结构
+  status [<name>] [--json]                     当前位置 + 下一步（只读）
+  new <name> [--mode full|fix] [--source <file>]... [--base <branch>]
+  open <name> --prepare                        校验 brief/spec，抽取验收项
+  open <name> --confirm --expect <v>:confirm   用户确认后进入 build
+  rename <name> <new>                          仅 open 阶段
+  spec remove|restore <name> <capability>      登记/取消删除一个主能力
+  handoff <name> --input <json> --expect <v>:<step>   提交候选实现并跑检查
+  verify <name> --result <json> | --error "<原因>" | --unavailable --expect <v>:await-verifier
+  probe <name> [--remove <dir>]                反向验证用的临时 worktree
+  decide <name> --expect <v>:<step> --accept --finish keep|merge|pr|push
+                                  | --revise-implementation --note "<…>"
+                                  | --revise-requirements [--note "<…>"]
+                                  | --resolve --note "<…>" | --upgrade
+  archive <name> [--dry-run]
+  doctor [--repair]
+  import-specs [--dry-run]                     openspec/specs -> comate/comate/specs
+
+退出码：0 成功 | 1 被守卫拦截 | 2 用法错误 | 3 环境缺失 | 4 状态损坏
+所有命令加 --json 输出机器可读结果。`;
+
+export async function main(argv) {
+  const [cmd, ...rest] = argv;
+  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    process.stdout.write(`${USAGE_TEXT}\n`);
+    return cmd ? OK : USAGE;
+  }
+  let json = rest.includes('--json');
+  try {
+    const entry = COMMANDS[cmd];
+    if (!entry) die(USAGE, `未知命令 '${cmd}'。运行 node "$COMATE" help 查看用法。`);
+    const a = parseArgs(rest.filter((t) => t !== '--json'));
+    const bad = a.used.filter((k) => !entry[1].includes(k));
+    if (bad.length) die(USAGE, `${cmd} 不支持选项：${bad.map((k) => `--${k}`).join(' ')}`);
+    let ctx = null;
+    try {
+      ctx = makeContext(process.cwd(), SCRIPT);
+    } catch (err) {
+      if (cmd !== 'doctor' && cmd !== 'init') throw err;
+    }
+    const res = entry[0](ctx, a);
+    return emit(ctx, res, json);
+  } catch (err) {
+    if (!(err instanceof ComateError)) throw err;
+    return fail(err, json);
+  }
+}
+
+function emit(ctx, res, json) {
+  if (res.lines) {
+    process.stdout.write(json ? `${JSON.stringify(res.json ?? {}, null, 2)}\n` : `${res.lines.join('\n')}\n`);
+    return res.exit ?? OK;
+  }
+  const next = nextFor(ctx, res.cp, res.st, { done: res.done });
+  process.stdout.write(json ? `${JSON.stringify(next, null, 2)}\n` : `${formatText(next)}\n`);
+  return OK;
+}
+
+// A refused command still prints the latest next, so the agent knows
+// exactly what to fix and which command to run afterwards.
+function fail(err, json) {
+  let next = null;
+  if (err.code === BLOCK && err.change) {
+    try {
+      const ctx = makeContext(process.cwd(), SCRIPT);
+      const { cp, st } = load(ctx, err.change);
+      next = nextFor(ctx, cp, st);
+    } catch {
+      next = null;
+    }
+  }
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ error: { code: err.code, message: err.message }, next: next }, null, 2)}\n`);
+  } else {
+    log.fail(err.message);
+    if (next) process.stdout.write(`${formatText(next)}\n`);
+  }
+  return err.code;
+}
+
+process.exitCode = await main(process.argv.slice(2));

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

@@ -0,0 +1,112 @@
+// Acceptance items A1…An come from brief examples, target spec Scenarios, and
+// Scenarios removed from the main spec. Unchanged Scenarios are regressions.
+import { acceptanceExamples } from './brief.mjs';
+import { section, sections, table } from './md.mjs';
+import { parseSpec } from './spec.mjs';
+
+const firstLine = (s, n = 80) => {
+  const line = s.split('\n')[0].trim();
+  return line.length > n ? `${line.slice(0, n)}…` : line;
+};
+
+// changeSpecs: [{ cap, text }] sorted; mainSpecs: { cap: text|null }; removals: [cap]
+export function collectAcceptance({ briefText, changeSpecs, mainSpecs, removals }) {
+  const acceptance = [];
+  const push = (item) => acceptance.push({ id: `A${acceptance.length + 1}`, ...item, result: 'pending', reason: null });
+  const pushRemoved = (cap, s) => push({
+    kind: 'removed',
+    source: `specs/${cap}/spec.md#${s.title}`,
+    title: `移除：${s.title}`,
+    text: [`旧 Scenario：${s.title}`, s.requirement, s.body, '期望：该行为已移除或按 brief 中的迁移规则处理'].filter(Boolean).join('\n'),
+  });
+
+  acceptanceExamples(briefText).forEach((text, i) => {
+    push({ kind: 'changed', source: `brief.md#验收示例/${i + 1}`, title: firstLine(text), text });
+  });
+
+  const removed = [];
+  for (const { cap, text } of changeSpecs) {
+    const mainParsed = mainSpecs[cap] ? parseSpec(mainSpecs[cap]) : { requirementBodies: [], scenarios: [] };
+    const ownParsed = parseSpec(text);
+    const byTitle = new Map(mainParsed.scenarios.map((s) => [s.title, { body: s.body, requirement: s.requirement }]));
+    for (const s of ownParsed.scenarios) {
+      const main = byTitle.get(s.title);
+      const unchanged = main && main.body === s.body && main.requirement === s.requirement;
+      const kind = unchanged ? 'regression' : 'changed';
+      push({ kind, source: `specs/${cap}/spec.md#${s.title}`, title: s.title, text: [s.title, s.requirement, s.body].filter(Boolean).join('\n') });
+    }
+    const kept = new Set(ownParsed.scenarios.map((s) => s.title));
+    for (const s of mainParsed.scenarios) if (!kept.has(s.title)) {
+      removed.push({ capability: cap, title: s.title });
+      pushRemoved(cap, s);
+    }
+  }
+  for (const cap of removals) {
+    for (const s of mainSpecs[cap] ? parseSpec(mainSpecs[cap]).scenarios : []) {
+      removed.push({ capability: cap, title: s.title });
+      pushRemoved(cap, s);
+    }
+  }
+  return { acceptance, removed };
+}
+
+const COLUMNS = ['source_item', 'location', 'read_status', 'spec_location', 'coverage', 'note'];
+const READ = ['complete', 'partial', 'unavailable'];
+const COVERAGE = ['covered', 'needs-clarification', 'background', 'non-goal', 'superseded'];
+
+export function coverageTable(briefText) {
+  const scope = section(briefText, '范围');
+  const sub = scope && sections(scope.body, 2).find((s) => s.title === '来源覆盖');
+  return sub ? table(sub.body) : null;
+}
+
+// "specs/auth/spec.md#Scenario: 密码错误" / "`comate/.../specs/auth/spec.md#x`" -> canonical source.
+function canonical(loc) {
+  let s = loc.trim().replace(/^`|`$/g, '');
+  const at = Math.max(s.lastIndexOf('specs/'), s.lastIndexOf('brief.md'));
+  if (at > 0) s = s.slice(at);
+  return s.replace(/#\s*Scenario\s*[:：]\s*/i, '#').replace(/\s+$/, '');
+}
+
+// Validates the「来源覆盖」table and derives source_item -> acceptance IDs.
+export function checkCoverage(briefText, acceptance, hasSources) {
+  const t = coverageTable(briefText);
+  if (!t) {
+    return hasSources
+      ? { problems: ['需求来自文件（new --source）时，「# 范围」下必须有「## 来源覆盖」表，逐段登记源文件内容'], sourceMap: {} }
+      : { problems: [], sourceMap: {} };
+  }
+  const problems = [];
+  const missing = COLUMNS.filter((c) => !t.headers.includes(c));
+  if (missing.length) return { problems: [`来源覆盖表缺少列：${missing.join('、')}`], sourceMap: {} };
+  if (t.rows.length === 0) problems.push('来源覆盖表没有任何行');
+
+  const bySource = new Map(acceptance.map((a) => [a.source, a.id]));
+  const sourceMap = {};
+  const seen = new Set();
+  for (const row of t.rows) {
+    const item = row.source_item;
+    const at = `来源覆盖 ${item || '(空 source_item)'}`;
+    if (!/^S\d+$/.test(item)) problems.push(`${at}：source_item 应为 S1、S2…`);
+    if (seen.has(item)) problems.push(`${at}：source_item 重复`);
+    seen.add(item);
+    if (!row.location) problems.push(`${at}：location 为空`);
+    if (!READ.includes(row.read_status)) problems.push(`${at}：read_status 应为 ${READ.join(' / ')}`);
+    else if (row.read_status !== 'complete') problems.push(`${at}：read_status=${row.read_status}，源内容必须完整读完`);
+    if (!COVERAGE.includes(row.coverage)) problems.push(`${at}：coverage 应为 ${COVERAGE.join(' / ')}`);
+    if (row.coverage === 'needs-clarification') problems.push(`${at}：仍需澄清，确认前必须解决`);
+    if (row.coverage === 'superseded' && !row.note) problems.push(`${at}：superseded 必须在 note 写明被什么替代`);
+    if (row.coverage !== 'covered') continue;
+
+    const locs = row.spec_location.split(/[,，;；、]|<br\s*\/?>/i).map((l) => l.trim()).filter(Boolean);
+    if (!locs.length) problems.push(`${at}：covered 必须填 spec_location`);
+    const ids = [];
+    for (const loc of locs) {
+      const id = bySource.get(canonical(loc));
+      if (id) ids.push(id);
+      else problems.push(`${at}：spec_location「${loc}」没有对应任何验收项（应形如 specs/<cap>/spec.md#<Scenario 标题> 或 brief.md#验收示例/<序号>）`);
+    }
+    if (ids.length) sourceMap[item] = [...new Set(ids)];
+  }
+  return { problems, sourceMap };
+}

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

@@ -0,0 +1,50 @@
+// brief.md: why, what, key decisions and acceptance examples. Seven chapters in
+// full mode, three in fix mode; every required chapter must carry real content.
+import { hasPlaceholder, isBlank, listItems, section, sections, stripComments } from './md.mjs';
+
+export const FULL_CHAPTERS = ['目标', '范围', '非目标', '验收示例', '约束与不变量', '决定', '待决问题'];
+export const FIX_CHAPTERS = ['目标', '验收示例', '决定'];
+
+export const requiredChapters = (mode) => (mode === 'fix' ? FIX_CHAPTERS : FULL_CHAPTERS);
+
+export function checkBrief(text, mode) {
+  const problems = [];
+  const all = sections(text, 1);
+  for (const title of requiredChapters(mode)) {
+    const hits = all.filter((s) => s.title === title);
+    if (hits.length === 0) problems.push(`缺少一级章节「# ${title}」`);
+    else if (hits.length > 1) problems.push(`章节「# ${title}」出现了 ${hits.length} 次`);
+    else if (isBlank(hits[0].body)) problems.push(`章节「${title}」为空（模板注释不算内容）`);
+  }
+  for (const s of all) {
+    if (hasPlaceholder(s.body)) problems.push(`章节「${s.title}」含占位符（TODO / TBD / FIXME / 待填写 / 待补充）`);
+  }
+  const examples = section(text, '验收示例');
+  if (examples && !isBlank(examples.body) && acceptanceExamples(text).length === 0) {
+    problems.push('「验收示例」里没有列表项：每条验收写成一个 `- ` 开头的列表项');
+  }
+  const blocking = stripComments(text).match(/\[blocking\][^\n]*/gi) ?? [];
+  for (const b of blocking) problems.push(`仍有阻断问题未决：${b.trim()}`);
+  return problems;
+}
+
+export const acceptanceExamples = (text) => listItems(section(text, '验收示例')?.body ?? '');
+
+// "无行为变更：<理由>" in 范围 (fix mode: anywhere), for a change that ships no spec.
+export function noBehaviorReason(text, mode) {
+  const scope = mode === 'fix' ? stripComments(text) : stripComments(section(text, '范围')?.body ?? '');
+  const m = /无行为变更\s*[:：]\s*(.+)/.exec(scope);
+  if (!m) return null;
+  const reason = m[1].trim();
+  return reason.length >= 6 && !hasPlaceholder(reason) ? reason : null;
+}
+
+const clip = (s, n = 800) => {
+  const t = stripComments(s ?? '').trim();
+  return t.length > n ? `${t.slice(0, n)}…` : t;
+};
+
+export function briefSummary(text) {
+  const get = (t) => clip(section(text, t)?.body);
+  return { goal: get('目标'), scope: get('范围'), non_goals: get('非目标'), decisions: get('决定') };
+}

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

@@ -0,0 +1,178 @@
+// Project config and the check plan (build_command / verify_command) that the
+// script runs itself after every handoff. Results are summarised into
+// state.json; no log files are kept.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { ENV, die, readText } from './util.mjs';
+
+export const DEFAULT_CONFIG = {
+  language: 'zh-CN',
+  build_command: null,
+  verify_command: null,
+  check_timeout_seconds: 900,
+  max_verify_failures: 5,
+  finish: 'ask',
+  auto_finish_action: null,
+  protected_branches: ['main', 'master'],
+};
+
+export function loadConfig(ctx) {
+  const text = readText(ctx.abs(ctx.configRel));
+  if (text === null) return { ...DEFAULT_CONFIG };
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (err) {
+    return die(ENV, `${ctx.configRel} 不是合法 JSON：${err.message}`);
+  }
+  const cfg = { ...DEFAULT_CONFIG, ...raw };
+  const bad = [];
+  if (!['ask', 'auto'].includes(cfg.finish)) bad.push(`finish 应为 ask / auto`);
+  if (cfg.auto_finish_action !== null && !['keep', 'merge', 'push', 'pr'].includes(cfg.auto_finish_action)) {
+    bad.push('auto_finish_action 应为 null / keep / merge / push / pr');
+  }
+  if (!Number.isInteger(cfg.max_verify_failures) || cfg.max_verify_failures < 1) bad.push('max_verify_failures 应为正整数');
+  if (!Array.isArray(cfg.protected_branches)) bad.push('protected_branches 应为数组');
+  if (bad.length) die(ENV, `${ctx.configRel} 配置错误：\n  - ${bad.join('\n  - ')}`);
+  return cfg;
+}
+
+const NPM_PLACEHOLDER = /no test specified/;
+
+function packageScripts(root) {
+  try {
+    return JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).scripts ?? {};
+  } catch {
+    return {};
+  }
+}
+
+// Include referenced npm scripts and lifecycle hooks, so a stable wrapper
+// command cannot hide a changed test entry point. Test source files may evolve.
+function commandProfile(cmd, scripts) {
+  const definitions = new Map();
+  const commands = [cmd];
+  let complete = true;
+  for (let i = 0; i < commands.length; i++) {
+    const refs = [...commands[i].matchAll(/(?:^|&&|;|\|)\s*npm(?:\.cmd)?\s+([^;&|\n]+)/g)];
+    const invocations = [...commands[i].matchAll(/\bnpm(?:\.cmd)?(?=\s|$)/g)];
+    if (invocations.length !== refs.length) complete = false;
+    for (const ref of refs) {
+      const args = ref[1].match(/"[^"]*"|'[^']*'|[^\s]+/g) ?? [];
+      while (/^(?:--silent|-s|--quiet|-q|--no-audit|--no-fund|--loglevel=\w+)$/.test(args[0] ?? '')) args.shift();
+      const action = args.shift();
+      const raw = action === 'run' || action === 'run-script' ? args.shift() : ['test', 't'].includes(action) ? 'test' : null;
+      const name = raw?.replace(/^(["'])(.*)\1$/, '$2');
+      if (!name || /[\s$%`\\"']/.test(name) || /--(?:prefix|workspace|workspaces)\b|(?:^|\s)-w/.test(ref[1])) {
+        complete = false;
+        continue;
+      }
+      for (const key of [name, `pre${name}`, `post${name}`]) {
+        if (definitions.has(key)) continue;
+        const body = typeof scripts[key] === 'string' ? scripts[key] : null;
+        definitions.set(key, body);
+        if (body !== null) commands.push(body);
+      }
+    }
+  }
+  return { commands, complete, scripts: [...definitions].sort(([a], [b]) => a.localeCompare(b)).map(([name, cmd]) => ({ name, cmd })) };
+}
+
+const NON_TEST = /\bnode\s+(?:--check|-c)\b|\btsc\b|\b(?:vite|webpack|next)\s+build\b|\b(?:eslint|prettier)\b|\b(?:cargo|go)\s+build\b|\b(?:mvn|mvnw)(?:\.cmd)?\b[^\n]*\b(?:compile|package)\b/i;
+const SKIP_OR_MASK = /no test specified|--(?:passWithNoTests|skipTests|listTests|showConfig|collect-only|test-skip-pattern|help|version)\b|(?:^|\s)-h(?=\s|$)|\b(?:node|jest|vitest)\s+[^;&|\n]*-v(?=\s|$)|-DskipTests\b|\bvitest\s+list\b|process\.exit\(\s*0\s*\)/i;
+const TEST_RUNNER = /^(?:npx\s+(?:--no-install\s+)?)?(?:node\s+[^\n]*--test(?=\s|$)|(?:vitest|jest|mocha|ava|pytest)(?=\s|$)|(?:cargo|go)\s+test(?=\s|$)|(?:mvn|mvnw)(?:\.cmd)?\s+[^\n]*\btest(?=\s|$))/i;
+
+function checkKind(stage, declared, profile) {
+  const commands = profile.commands;
+  const executable = commands.map((cmd) => cmd.replace(/"[^"\n]*"|'[^'\n]*'/g, 'quoted'));
+  if (stage !== 'verify' || declared === 'check' || commands.some((cmd) => SKIP_OR_MASK.test(cmd)) || executable.some((cmd) => /[;|]|(?<!&)&(?!&)/.test(cmd))) return 'check';
+  // Unsupported npm forms may address another package; they need independent verification.
+  if (!profile.complete) return 'unknown';
+  const segments = executable.flatMap((cmd) => cmd.split(/&&|\n/).map((part) => part.trim()));
+  if (segments.some((cmd) => TEST_RUNNER.test(cmd) && !NON_TEST.test(cmd))) return 'test';
+  if (commands.some((cmd) => NON_TEST.test(cmd))) return 'check';
+  if (declared === 'test') return 'test';
+  return 'unknown';
+}
+
+function detect(root, stage) {
+  const cmds = [];
+  const pkg = join(root, 'package.json');
+  if (existsSync(pkg)) {
+    const scripts = packageScripts(root);
+    if (stage === 'build' && scripts.build) cmds.push('npm run build');
+    if (stage === 'verify' && scripts.test && !NPM_PLACEHOLDER.test(scripts.test)) cmds.push('npm test');
+  }
+  const mvnw = process.platform === 'win32' ? 'mvnw.cmd' : './mvnw';
+  const mvn = existsSync(join(root, mvnw)) ? mvnw : 'mvn';
+  if (existsSync(join(root, 'pom.xml'))) cmds.push(stage === 'build' ? `${mvn} -q compile` : `${mvn} -q test`);
+  if (existsSync(join(root, 'Cargo.toml'))) cmds.push(stage === 'build' ? 'cargo build' : 'cargo test');
+  if (existsSync(join(root, 'go.mod'))) cmds.push(stage === 'build' ? 'go build ./...' : 'go test ./...');
+  return cmds;
+}
+
+// -> { plan: [{ stage, cmd, kind, scripts }], problems: [] }. `none` = the project truly has
+// nothing to run for that stage; null = detect (npm / Maven / Cargo / Go).
+export function resolveChecks(ctx, cfg) {
+  const plan = [];
+  const problems = [];
+  const scripts = packageScripts(ctx.root);
+  for (const stage of ['build', 'verify']) {
+    const v = cfg[`${stage}_command`];
+    if (v === 'none') continue;
+    const cmds = v === null || v === undefined ? detect(ctx.root, stage) : Array.isArray(v) ? v : [v];
+    if (cmds.length === 0 && stage === 'verify') {
+      problems.push(
+        `没有配置 verify_command，也没探测到测试命令。在 ${ctx.configRel} 写上 "verify_command": "<命令>"，项目确实没有测试时写 "none"`,
+      );
+    }
+    for (const entry of cmds) {
+      const object = entry !== null && typeof entry === 'object' && !Array.isArray(entry);
+      const cmd = object ? entry.cmd : entry;
+      const declared = object ? entry.kind : undefined;
+      if (typeof cmd !== 'string' || !cmd.trim() || (declared !== undefined && !['test', 'check'].includes(declared))) {
+        problems.push(`${stage}_command 每项必须是非空命令字符串或 { cmd, kind: "test" | "check" }`);
+        continue;
+      }
+      const profile = commandProfile(cmd, scripts);
+      plan.push({ stage, cmd, kind: checkKind(stage, declared, profile), scripts: profile.scripts });
+    }
+  }
+  return { plan, problems };
+}
+
+export const verifyPlan = (plan) => plan.filter((c) => c.stage === 'verify').map(({ cmd, kind, scripts }) => ({ cmd, kind, scripts }));
+
+const SECRET = [
+  /((?:api[_-]?key|secret|token|password|passwd|authorization)\s*[:=]\s*)\S+/gi,
+  /\b(gh[pousr]_|sk-|xox[baprs]-|npm_)[A-Za-z0-9_-]{10,}/g,
+  /\bAKIA[0-9A-Z]{16}\b/g,
+];
+const redact = (s) => SECRET.reduce((acc, re) => acc.replace(re, (m, p1) => (p1 && /[:=]\s*$/.test(p1) ? `${p1}***` : '***')), s);
+
+function tail(out, lines) {
+  const all = out.replace(/\x1b\[[0-9;]*m/g, '').split(/\r?\n/).filter((l) => l.trim() !== '');
+  return redact(all.slice(-lines).join('\n'));
+}
+
+export function runChecks(ctx, cfg, plan) {
+  const timeout = (cfg.check_timeout_seconds ?? 900) * 1000;
+  return plan.map(({ stage, cmd, kind }) => {
+    const started = Date.now();
+    const r = spawnSync(cmd, {
+      cwd: ctx.root,
+      shell: true,
+      encoding: 'utf8',
+      timeout,
+      maxBuffer: 256 * 1024 * 1024,
+      env: { ...process.env, CI: process.env.CI ?? '1' },
+    });
+    const timedOut = r.error?.code === 'ETIMEDOUT' || (r.signal !== null && Date.now() - started >= timeout);
+    const exit = r.error && !timedOut ? -1 : r.status ?? -1;
+    const ok = exit === 0 && !timedOut;
+    const out = `${r.stdout ?? ''}${r.stderr ?? ''}${r.error && !timedOut ? `\n${r.error.message}` : ''}`;
+    return { stage, cmd, kind, exit, timed_out: timedOut, ok, ms: Date.now() - started, tail: tail(out, ok ? 5 : 50) };
+  });
+}