@house365/comate 0.9.12 → 0.9.14

package/bin/cli.mjs

@@ -5,11 +5,18 @@
 //           handles agent detection, symlinking, update/remove for 70+ agents.
 import { fileURLToPath } from 'node:url';
 import { dirname } from 'node:path';
+import { readFileSync } from 'node:fs';
 
 import { run, skillsInvocation, SKILLS_TIMEOUT_MS } from './init.mjs';
 
 const pkgRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 const args = process.argv.slice(2);
+const packageVersion = JSON.parse(readFileSync(`${pkgRoot}/package.json`, 'utf8')).version;
+
+if (args[0] === '--version' || args[0] === '-v') {
+  console.log(packageVersion);
+  process.exit(0);
+}
 
 if (args[0] === 'init') {
   const { init } = await import('./init-run.mjs');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@house365/comate",
-  "version": "0.9.12",
+  "version": "0.9.14",
   "description": "comate —— SDD (规约驱动开发) 的 AI 开发编排器（Agent Skills）",
   "type": "module",
   "license": "MIT",
@@ -46,7 +46,7 @@
   },
   "scripts": {
     "postinstall": "node bin/postinstall.mjs",
-    "test": "node bin/init.test.mjs && node bin/usage.test.mjs && bash skills/comate/tests/run.sh",
+    "test": "node bin/cli.test.mjs && node bin/init.test.mjs && node bin/usage.test.mjs && bash skills/comate/tests/run.sh",
     "doctor": "cd skills && bash comate/scripts/comate.sh doctor",
     "prepublish-check": "node scripts/prepublish-check.mjs",
     "pack-check": "node scripts/pack-check.mjs",

package/skills/comate/SKILL.md

@@ -53,8 +53,9 @@ agent 做决策只需读本节，其余参见末尾「参考附录」。决策
 
       普通进度（如 `design.brainstorm-complete`）、已确认状态和依赖阻塞状态都**不是**待决策，不得抢占用户的新请求。用户明确说“新建 change”时也优先按新建意图处理。
       
-      **立即路由到对应子 skill**（根据 `phase` 字段）：
-      - `phase: open` → 调用 `/comate-open`
+      **立即路由到对应子 skill**（根据 `phase` 字段）：
+      - `phase_step: fix.upgrade-awaiting` → 无论当前是 `phase: open` 还是 `phase: build`，调用 `/comate-fix`
+      - `phase: open` → 调用 `/comate-open`
       - `phase: design` → 调用 `/comate-design`
       - `phase: build` → 调用 `/comate-build`
       - `phase: verify` → 调用 `/comate-verify`
@@ -173,7 +174,7 @@ agent 做决策只需读本节，其余参见末尾「参考附录」。决策
 - 有活跃 change 且工作树有未提交改动时，按 `comate/reference/dirty-worktree.md` 协议处理。
 - 若 `phase: build`，先检查 `build_mode`、`isolation`、`tdd_mode` 是否已设；任一未设则回 `/comate-build` 对应步骤补充；都已设则读 tasks.md 下一个未勾选任务继续。
 - 若 `phase: verify` 且 `verify_result: fail`，按决策点 4 分级处理：CRITICAL 失败直接 `state transition <name> verify-fail` 回 `/comate-build`（不询问，回退前报告失败项）；仅 WARNING/SUGGESTION 或 Spec 漂移时才 AskUserQuestion 暂停。
-- 若 `phase: open` 但 proposal/design/tasks 已完成，先 `bash "$COMATE" guard <name> open --apply` 修复状态，再继续探测。
+- 若 `phase: open` 但 proposal/design/tasks 已完成，按 `workflow` 恢复：`fix` 调 `/comate-fix`，`full` 调 `/comate-open`；对应 skill 立即运行 `bash "$COMATE" guard <name> open --apply` 修复状态，并在 guard 成功后同轮继续下一阶段。
 - 若 `phase: archive`，只调用 `/comate-archive`；归档成功后 change 移入 archive 目录，不要再对旧活跃目录跑 guard。
 
 **phase_step 生命周期**：
@@ -188,7 +189,7 @@ agent 做决策只需读本节，其余参见末尾「参考附录」。决策
 4. `phase: verify` → 调用 `/comate-verify`。`tasks.md` 全勾不能单独触发 verify；验证失败回退到 build 后，必须继续按 build 路由修复。
 5. `phase: build` 或有 Design Doc 但 plan/执行未完成 → 按 workflow 路由：`fix`→`/comate-fix`，`full`→`/comate-build`
 6. `phase: design` 或有 change 但无 Design Doc → 调用 `/comate-design`
-7. `phase: open` 或有活跃 change 但 `.comate.yaml` 缺失 → 调用 `/comate-open`
+7. `phase: open` → 按 workflow 路由：`fix`→`/comate-fix`，`full`→`/comate-open`；有活跃 change 但 `.comate.yaml` 缺失 → 调用 `/comate-open`
 8. 无活跃 change → 调用 `/comate-open`
 
 元数据与文件状态冲突时，以可验证的文件状态为准，先用 `state set` 修正 `.comate.yaml` 再继续。
@@ -214,7 +215,9 @@ agent 做决策只需读本节，其余参见末尾「参考附录」。决策
 
 流转链：open → design → build → verify → archive
 
-**连续执行要求**：从探测到的阶段开始，agent 自动连续走完后续阶段。但**自动推进仅适用于无用户决策的流转点**。遇到决策阻塞点时，**必须用 AskUserQuestion 工具暂停等待用户明确回应**，不得用推荐规则、默认值或历史偏好替代用户确认，也不得只输出文字提示后继续执行。
+**连续执行要求**：从探测到的阶段开始，agent 自动连续走完后续阶段。但**自动推进仅适用于无用户决策的流转点**。遇到决策阻塞点时，**必须用 AskUserQuestion 工具暂停等待用户明确回应**，不得用推荐规则、默认值或历史偏好替代用户确认，也不得只输出文字提示后继续执行。
+
+guard 成功、代码提交成功以及用户已经完成某个决策后的操作都不是新的暂停点。状态已满足下一阶段入口时，必须在当前调用内重新探测并继续；尤其是 fix 流程不得停在 `phase: open` 实现代码，也不得停在 build 提交之后等待用户发送“继续”。
 
 7 个决策点（部分含自动处理分支）+ Red Flags 表见 `comate/reference/decision-points.md`。**每个决策点先按三类行动分类**（用户决策 / 自动处理 / 停止条件）：判定属用户决策才用 AskUserQuestion 阻塞等待用户选择；属自动处理则直接执行并如实报告；其他无歧义流转自动进行，不得中途退出。
 </IMPORTANT>

package/skills/comate/tests/comate.bats

@@ -275,6 +275,21 @@ seed_open() {
   [ "$(comate state demo get phase)" = "design" ]
 }
 
+@test "fix guards continuously advance open to build to verify" {
+  comate state demo init fix
+  local d="openspec/changes/demo"
+  printf '# p\n' > "$d/proposal.md"
+  printf '# d\n' > "$d/design.md"
+  printf -- '- [x] t1\n' > "$d/tasks.md"
+
+  comate guard demo open --apply >/dev/null 2>&1
+  [ "$(comate state demo get phase)" = "build" ]
+
+  comate handoff demo build --write >/dev/null 2>&1
+  comate guard demo build --apply >/dev/null 2>&1
+  [ "$(comate state demo get phase)" = "verify" ]
+}
+
 @test "guard open json emits block false" {
   seed_open
   run comate guard demo open --json

package/skills/comate-fix/SKILL.md

@@ -39,6 +39,25 @@ if [ -z "$COMATE" ]; then
 fi
 ```
 
+### 0. 入口状态与断点恢复
+
+`comate-fix` 必须以 `.comate.yaml` 为进度真相源，并且可以从任一已完成步骤继续。已有 fix change 时，**禁止重新创建 change**；先读取：
+
+```bash
+bash "$COMATE" state <name> get workflow
+bash "$COMATE" state <name> get phase
+bash "$COMATE" state <name> get phase_step
+```
+
+- `workflow` 不是 `fix` → 退出本预设，交回 `/comate` 按完整流程路由
+- `phase: open` → 恢复 Step 1；产物齐全时立即执行 open guard，不重新创建产物
+- `phase: build` → 恢复 Step 2，从 tasks.md 第一个未完成任务继续；全部完成时直接执行 build 交接与 guard
+- `phase: verify` → 立即加载 `comate-verify`，不得回跑 open/build
+- `phase: archive` → 立即加载 `comate-archive`
+- `phase_step: fix.upgrade-awaiting` → 恢复升级决策，不执行普通 open/build
+
+每次 guard 使用 `--apply` 成功后，**在同一次调用内**重新读取 `phase`，并立即执行新阶段；除明确的用户决策、guard 失败或停止条件外，不得把“请用户再说继续”作为阶段边界。
+
 ### 1. 快速开启（preset open）
 
 复用 open 能力但用 fix 默认值：不执行 `openspec-explore` 长探索，直接精简创建。
@@ -55,6 +74,14 @@ bash "$COMATE" state <name> check open
 bash "$COMATE" guard <name> open --apply
 ```
 
+**Step 1 硬出口**：open guard 成功后必须立即确认状态已经进入 build：
+
+```bash
+test "$(bash "$COMATE" state <name> get phase)" = "build"
+```
+
+只有该检查通过才能开始 Step 2 的源码修改。不得在 `phase: open` 时实现或提交代码；guard 失败则修复 open 产物并重跑，不能绕过状态流转。
+
 ### 2. 直接构建（preset build）
 
 用 fix 默认值 `build_mode: direct`。跳过 `superpowers:brainstorming` 和 `superpowers:writing-plans`（除非任务 > 3，则转入 `/comate-build` 的计划与执行方式选择）。
@@ -63,6 +90,8 @@ bash "$COMATE" guard <name> open --apply
 
 **立即执行：** 按 tasks.md 逐个执行：读未完成任务 → 改代码 → 运行格式化命令 → 运行测试 → 勾选 `- [x]` → 提交。全部完成后显式运行测试和构建命令。
 
+提交代码不是 Step 2 的结束点。最后一次提交完成后，当前调用必须继续生成 build 交接包、运行 build guard，并确认进入 verify；不得在提交成功处停下或只向用户报告“代码已提交”。
+
 **commit 前缀**：
 - **bug 模式** — `fix: <简述>`
 - **调整模式** — `chore: <简述>`
@@ -82,9 +111,12 @@ bash "$COMATE" guard <name> open --apply
 ```bash
 bash "$COMATE" handoff <name> build --write
 bash "$COMATE" guard <name> build --apply
+test "$(bash "$COMATE" state <name> get phase)" = "verify"
 ```
 
-**调整模式跳过此步**，tasks 完成后直接运行上述命令流转。
+**调整模式跳过根因检查，但不跳过交接与流转**；tasks 完成后同样连续运行上述三个命令。
+
+build guard 成功后，必须在**同一次 `/comate-fix` 调用**中立即进入 Step 4。只有 guard 返回非 0 时才停留在 build，并报告具体失败检查。
 
 ### 4. 验证（preset verify）
 
@@ -94,6 +126,8 @@ bash "$COMATE" guard <name> build --apply
 
 验证通过后按其规则记录 `verify_result: pass`。
 
+`comate-verify` 的分支处理属于合法用户决策点；等待用户选择是暂停。用户完成分支处理后，必须立即继续 verify guard，并在 guard 流转到 archive 后同轮加载 `comate-archive`，不得再要求用户发送“继续”。
+
 ### 5. 归档（preset archive）
 
 **立即执行：** 使用 Skill 工具加载 `comate-archive`。归档前必须 `verify_result: pass`。有 delta spec（仅 bug 模式可能）则同步到 main spec。
@@ -109,6 +143,8 @@ Fix 为**一次性连续执行**。调用后在自有步骤间自动推进，但
 3. comate-verify 的验证失败决策（决策点 4）和分支处理决策（决策点 5）
 
 执行顺序：快速开启 → 直接构建 → [bug 模式：根因消除检查] → 验证 → 归档 → 完成。
+
+其中“提交代码”“guard 成功”“用户已完成分支处理”都不是可停点；它们分别触发交接、下一阶段和 verify 收尾。每次恢复也必须按 Step 0 从持久化状态继续，而不是依赖对话中的上一条说明。
 </IMPORTANT>
 
 ---

package/skills/comate-verify/SKILL.md

@@ -140,6 +140,15 @@ bash "$COMATE" state <name> set branch_status handled
 bash "$COMATE" state <name> set phase_step verify.branch-handled
 ```
 
+写入 `branch_status: handled` 后不是退出点。当前 `/comate-verify` 调用必须立即运行：
+
+```bash
+bash "$COMATE" guard <name> verify --apply
+test "$(bash "$COMATE" state <name> get phase)" = "archive"
+```
+
+guard 成功流转到 `archive` 后，立即加载 `comate-archive` skill；只有 guard 失败或新的用户决策才允许暂停。
+
 选择**丢弃工作**时必须写 `branch_status: discarded` 和 `phase_step: verify.discarded`，随后立即停止；不得运行 verify guard、不得设置 `verify_result: pass`、不得归档。若之后要继续该 change，先执行 `state transition <name> verify-fail` 回到 build，再重新实现并生成新的 build handoff。
 
 ## 退出条件