@house365/comate 0.10.0 → 0.10.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Jian Liang
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Jian Liang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/docs/CLEANUP_SUPERPOWERS.md

@@ -0,0 +1,128 @@
+# Superpowers 重复安装清理指南
+
+## 背景
+
+如果你在 Claude Code 中通过 plugin 安装了 superpowers，然后又运行了 `comate init`（在检测功能添加之前），可能会导致系统中同时存在两份 superpowers：
+
+1. **Claude Code plugin 版本**：`~/.claude/plugins/cache/.../superpowers/`
+2. **Skills CLI 版本**：`~/.agents/skills/using-superpowers/` 和 `~/.agents/skills/brainstorming/`
+
+这会导致：
+- 占用额外的磁盘空间
+- 可能的版本冲突
+- 用户困惑（不清楚在用哪个版本）
+
+## 解决方案
+
+### 自动清理（推荐）
+
+运行清理命令：
+
+```bash
+comate cleanup
+```
+
+该命令会：
+1. 检查是否存在 Claude Code plugin 版本的 superpowers
+2. 如果存在，扫描并删除 skills CLI 安装的版本
+3. 保留 plugin 版本（更新更方便）
+
+### 输出示例
+
+**有重复安装时：**
+```
+=== Superpowers 重复安装清理工具 ===
+
+1. 检查 Claude Code plugin 安装...
+   ✓ 检测到 Claude Code plugin 版本
+
+2. 扫描 skills CLI 安装...
+   发现: C:\Users\xxx\.agents\skills\using-superpowers
+   发现: C:\Users\xxx\.agents\skills\brainstorming
+
+   共找到 2 个目录需要清理
+
+3. 执行清理...
+   ✓ 已删除 2 个目录:
+     - C:\Users\xxx\.agents\skills\using-superpowers
+     - C:\Users\xxx\.agents\skills\brainstorming
+
+=== 清理完成 ===
+现在只使用 Claude Code plugin 版本的 superpowers
+相关 skill 在 Claude 中仍然可用
+```
+
+**无需清理时：**
+```
+=== Superpowers 重复安装清理工具 ===
+
+1. 检查 Claude Code plugin 安装...
+   ✓ 检测到 Claude Code plugin 版本
+
+2. 扫描 skills CLI 安装...
+   ✓ 未发现 skills CLI 版本的 superpowers
+
+无需清理，已经是最优状态！
+```
+
+### 手动清理
+
+如果你更喜欢手动操作：
+
+```bash
+# 删除 skills CLI 安装的 superpowers
+rm -rf ~/.agents/skills/using-superpowers
+rm -rf ~/.agents/skills/brainstorming
+rm -rf ~/.claude/skills/using-superpowers
+rm -rf ~/.claude/skills/brainstorming
+```
+
+## 预防措施
+
+从 comate v0.9.24 开始，`comate init` 会自动检测 Claude Code plugin 安装的 superpowers，并跳过重复安装。
+
+如果你使用的是旧版本，建议升级：
+
+```bash
+npm install -g @house365/comate@latest
+```
+
+## 常见问题
+
+### Q: 清理后 superpowers 还能用吗？
+
+A: 能！只要你有 Claude Code plugin 版本，所有 superpowers 的功能都正常可用。
+
+### Q: 如果我没有 plugin 版本会怎样？
+
+A: `comate cleanup` 会检测并拒绝清理，提示你需要先安装 plugin 版本。
+
+### Q: 我应该用哪个版本？
+
+A: 推荐使用 **Claude Code plugin 版本**，因为：
+- 通过 Claude 内置的 plugin 管理器自动更新
+- 与 Claude Code 集成更好
+- 不需要手动运行 `skills add` 更新
+
+### Q: 清理是否安全？
+
+A: 是的，清理脚本：
+- 仅在检测到 plugin 版本时才执行
+- 只删除明确的 superpowers 目录
+- 不会影响其他 skills
+- 不会删除 plugin 版本
+
+## 技术细节
+
+清理脚本检查以下位置：
+- `~/.agents/skills/`
+- `~/.claude/skills/`
+- `~/.config/skills/`
+- `~/.cursor/skills/`
+
+删除的目录：
+- `using-superpowers/`
+- `brainstorming/`
+
+保留的位置：
+- `~/.claude/plugins/cache/.../superpowers/`（plugin 版本）

package/docs/SUPERPOWERS_FIX_SUMMARY.md

@@ -0,0 +1,114 @@
+# Superpowers 重复安装问题修复总结
+
+## 问题描述
+
+在 v0.9.24 之前，`comate init` 无法检测 Claude Code plugin 安装的 superpowers，导致：
+- 即使 plugin 已安装，仍会通过 skills CLI 再次安装
+- 用户目录下出现重复的 superpowers 副本
+- 浪费磁盘空间和安装时间
+
+## 解决方案
+
+### 1. 预防重复安装（v0.9.24+）
+
+**修改文件：** `bin/init.mjs`
+
+扩展 `superpowersInstalled()` 函数，增加 plugin 检测：
+
+```javascript
+// 检查 skills CLI 安装（原有逻辑）
+if (roots.some((root) => SUPERPOWERS_MARKERS.some((m) => existsSync(join(root, ...m))))) {
+  return true;
+}
+
+// 检查 Claude Code plugin 安装（新增逻辑）
+if (scope === 'global') {
+  const pluginRegistry = join(home, '.claude', 'plugins', 'installed_plugins.json');
+  try {
+    const registry = JSON.parse(readFileSync(pluginRegistry, 'utf8'));
+    return Object.keys(registry.plugins || {}).some((key) =>
+      key.startsWith('superpowers@') && 
+      Array.isArray(registry.plugins[key]) && 
+      registry.plugins[key].length > 0
+    );
+  } catch {
+    return false;
+  }
+}
+```
+
+**效果：**
+- `comate init` 检测到 plugin 版本后会显示"已安装"并跳过
+- 避免未来的重复安装
+
+### 2. 清理已有重复（cleanup 命令）
+
+**新增文件：** `bin/cleanup-duplicate-superpowers.mjs`
+
+**新增命令：** `comate cleanup`
+
+**工作流程：**
+1. 检查是否有 Claude Code plugin 版本
+2. 扫描 skills CLI 安装的 superpowers
+3. 安全删除重复的目录
+4. 保留 plugin 版本
+
+**安全机制：**
+- 只在检测到 plugin 版本时才执行清理
+- 只删除明确的 superpowers 目录
+- 不影响其他 skills
+
+## 测试覆盖
+
+### init.test.mjs
+- ✅ 检测空注册表
+- ✅ 检测有效的 plugin 安装
+- ✅ 检测其他 plugin 不误判
+- ✅ project scope 不检查 plugin（仅 global）
+
+### cli.test.mjs
+- ✅ cleanup 命令在帮助中列出
+- ✅ cleanup 命令可执行
+
+## 使用指南
+
+### 新用户（v0.9.24+）
+直接运行 `comate init`，系统会自动检测并跳过重复安装。
+
+### 已有重复安装的用户
+运行 `comate cleanup` 清理。
+
+### 验证状态
+```bash
+# 检查是否有重复
+ls ~/.agents/skills | grep -E "(using-super|brainstorm)"
+
+# 检查 plugin 版本
+cat ~/.claude/plugins/installed_plugins.json | grep superpowers
+```
+
+## 提交记录
+
+1. **7cee6e6** - fix: detect Claude Code plugin install to avoid duplicate superpowers
+   - 扩展检测逻辑
+   - 添加测试用例
+
+2. **82dd387** - feat: add cleanup command to remove duplicate superpowers install
+   - 新增清理命令
+   - 添加文档
+
+## 影响范围
+
+- **向后兼容：** 完全兼容，不影响现有功能
+- **新功能：** `comate cleanup` 命令
+- **行为变化：** `comate init` 会跳过 plugin 已安装的 superpowers
+- **磁盘空间：** 清理后可节省约 10-20MB
+
+## 相关文件
+
+- `bin/init.mjs` - 检测逻辑
+- `bin/init.test.mjs` - 检测测试
+- `bin/cleanup-duplicate-superpowers.mjs` - 清理脚本
+- `bin/cli.mjs` - CLI 入口
+- `bin/cli.test.mjs` - CLI 测试
+- `docs/CLEANUP_SUPERPOWERS.md` - 用户文档

package/package.json

@@ -1,55 +1,55 @@
-{
-  "name": "@house365/comate",
-  "version": "0.10.0",
-  "description": "comate —— SDD (规约驱动开发) 的 AI 开发编排器（Agent Skills）",
-  "type": "module",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org"
-  },
-  "bin": {
-    "comate": "bin/cli.mjs",
-    "comate-skills": "bin/cli.mjs"
-  },
-  "files": [
-    "skills",
-    "bin",
-    "!bin/*.test.mjs",
-    "docs",
-    "README.md",
-    "LICENSE"
-  ],
-  "keywords": [
-    "agent-skills",
-    "skills",
-    "claude-code",
-    "openspec",
-    "superpowers",
-    "spec-driven-development",
-    "ai-agents"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/liangjiankk/comate.git"
-  },
-  "homepage": "https://github.com/liangjiankk/comate#readme",
-  "bugs": {
-    "url": "https://github.com/liangjiankk/comate/issues"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "dependencies": {
-    "ccusage": "^20.0.19",
-    "skills": "^1.5.21"
-  },
-  "scripts": {
-    "postinstall": "node bin/postinstall.mjs",
-    "test": "node bin/cli.test.mjs && node bin/init.test.mjs && node bin/usage.test.mjs && node bin/update.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",
-    "prepublishOnly": "npm run prepublish-check && npm run pack-check && npm run doctor && npm test"
-  }
-}
+{
+  "name": "@house365/comate",
+  "version": "0.10.1",
+  "description": "comate —— SDD (规约驱动开发) 的 AI 开发编排器（Agent Skills）",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "bin": {
+    "comate": "bin/cli.mjs",
+    "comate-skills": "bin/cli.mjs"
+  },
+  "files": [
+    "skills",
+    "bin",
+    "!bin/*.test.mjs",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "agent-skills",
+    "skills",
+    "claude-code",
+    "openspec",
+    "superpowers",
+    "spec-driven-development",
+    "ai-agents"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/liangjiankk/comate.git"
+  },
+  "homepage": "https://github.com/liangjiankk/comate#readme",
+  "bugs": {
+    "url": "https://github.com/liangjiankk/comate/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "ccusage": "^20.0.19",
+    "skills": "^1.5.21"
+  },
+  "scripts": {
+    "postinstall": "node bin/postinstall.mjs",
+    "test": "node bin/cli.test.mjs && node bin/init.test.mjs && node bin/usage.test.mjs && node bin/update.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",
+    "prepublishOnly": "npm run prepublish-check && npm run pack-check && npm run doctor && npm test"
+  }
+}

package/skills/comate/reference/decision-points.md

@@ -1,103 +1,103 @@
-# 决策阻塞点清单（decision-points）
-
-规范路径：`comate/reference/decision-points.md`（单一真相源）
-
-本文件集中定义 comate 全流程中**必须暂停等待用户**的决策点。各阶段 SKILL 用一行引用本文件的某一条，而不重复叙述规则，避免措辞漂移。
-
-## 先判定：这里真的需要用户输入吗？
-
-到达一个候选决策点时，**先分类，再决定是否阻塞**。不要把"需要做出选择"等同于"需要问用户"。
-
-| 类别 | 判据 | 处理 |
-|------|------|------|
-| **用户决策** | 存在 ≥2 个有效选项，且不同选项会改变范围、行为、可接受的风险或产生不可逆结果 | 阻塞，按下方通用规则用 AskUserQuestion 等待用户 |
-| **自动处理** | 在用户请求范围内只剩一个安全动作：修复客观失败、调和可验证的状态、重试幂等检查、或遵循已持久化的配置 | 直接执行并如实报告，**不制造确认点** |
-| **停止条件** | 缺依赖、状态损坏、路径逃逸、外部命令不可用，无有效下一步 | 报告阻塞与恢复条件，**不发明选项** |
-
-三条落地准则：
-
-1. **能合并的选择合并问**：相邻、可一次答完的选择放进同一次 AskUserQuestion，不拆成多次暂停。
-2. **不重复问已持久化且仍有效的选择**：配置文件或状态已记录且未失效时，直接沿用并说明。
-3. **先做能力预检再展示选项**：只呈现当前平台/仓库真正可执行的选项；某字段只剩一个有效值时，解释原因并直接应用，不为它单独制造一次暂停。
-
-## 通用规则
-
-经上一节判定确属**用户决策**后，该节点即为**阻塞点**：当前 `/comate` 调用必须停止，**使用 AskUserQuestion 工具等待用户选择**。只有在用户明确选择后，才能写入对应状态字段并继续执行，然后恢复自动推进。
-
-- 文字输出**不能**替代工具等待。必须通过 AskUserQuestion 显式获得用户选择。
-- 不得用推荐规则、默认值或历史偏好替代**用户决策类**节点的确认。
-- 推荐规则只能用于在问题里说明建议，不能代替用户拍板。
-- 其他无歧义的阶段流转、以及经判定属"自动处理"的节点，必须自动进行，不得中途退出，也不得为其伪造一次用户确认。
-
-## 决策阻塞点清单
-
-以下是 comate 全流程中**核心决策点**的规范定义。各阶段 SKILL 用一行引用本文件的某一条，而不重复叙述规则，避免措辞漂移。
-
-**本清单不穷举所有决策场景**——仅列出跨阶段、高频、影响流转的关键决策点。各 skill 内还有局部决策（如命名确认、dirty worktree 归因、PRD 选择等），由该 skill 自行定义并遵循本文首节的三类框架。
-
-## 核心决策点（跨阶段 / 流转关键）
-
-1. **开题产物审视确认**（open）
-   proposal/design/tasks 三件套完成且内容完整后，**先按来源分类，再决定是否阻塞**（对齐本文件首节三类框架）：
-   - **对话来源**（`source_kind: conversation`）——范围此前未经任何用户拍板，三件套是第一次成形，属"用户决策"。暂停请用户确认或要求调整。
-   - **PRD 扇出且范围一致**——本 change 来自一份**已过门禁的 PRD**（可验证信号全部成立：`source_kind: file`、追踪的源是 PRD、`gate <prd> check` 返回 PASS、change 名已记入该 PRD `spawned_changes`），**且** proposal 的范围/目标/非目标忠实承接 gate 映射里本 change 认领的功能项、无擅自扩缩。此时范围/映射/命名已在决策点 6 由用户拍板，三件套只是承接，不产生新的 ≥2 有效选项 —— 只剩"继续"一个安全动作，属"自动处理"。**不 AskUserQuestion**，完整性检查通过即自动流转，并如实报告：承接自哪份 PRD、认领哪些功能项、已核对范围与映射一致。
-   - **PRD 扇出但范围有偏差**——proposal 与 gate 映射不一致（擅自扩大/缩小范围、认领了未分配的功能项、漏掉已分配项）时，分歧重新出现，属"用户决策"。**必须 AskUserQuestion 暂停**，展示偏差点，请用户裁定按映射修正还是接受新范围。
-   引用：`comate-open` Step 5。
-
-2. **设计方案确认**（design / brainstorming）
-   brainstorming 产出技术方案后，暂停请用户确认采用的方案、关键取舍、测试策略、Spec Patch。确认前不得创建最终 Design Doc、写 `design_doc`、跑 design guard 或进入 build。
-   引用：`comate-design` Step 1c。
-
-3. **构建工作方式选择**（build）
-   开始执行前，先做能力预检，再**一次性**就工作区隔离方式（current / branch / worktree）、执行方式（subagent-driven-development / executing-plans）、TDD 模式（tdd / direct）做一个**联合决策**；选 branch 时分支名也在同一次问清，不得二次暂停。
-   预检后某维度只剩一个可执行选项时，属"自动处理"：说明原因并直接写入对应字段，不为它单独制造暂停。仍有 ≥2 个有效选项的维度才进入 AskUserQuestion。三个维度全部只剩单值时，全部自动写入，本决策点跳过。
-   引用：`comate-build` Step 3。
-
-4. **验证失败决策**（verify）
-   验证不通过时先按严重程度分类，**只有真正的用户决策才阻塞**：
-   - **CRITICAL（构建失败 / 测试失败 / 安全问题 / 核心验收场景失败）** —— 属"自动处理"，唯一安全动作就是修复。直接执行 `state transition <name> verify-fail` 回到 build，如实报告失败项，**不询问**。
-   - **Spec 漂移**（design doc 与 delta spec 矛盾）—— 属"用户决策"，必须 AskUserQuestion 暂停（见 Step 2b 三选项）。
-   - **仅 WARNING / SUGGESTION，无任何 CRITICAL** —— 属"用户决策"（可接受偏差是合法选择），一次性批量展示并提供「全部修复 / 逐项处理 / 接受偏差（记录原因）」。
-   引用：`comate-verify` Step 1b、Step 2b 的 Spec 漂移处理。
-
-5. **分支收尾方式选择**（verify / finishing-a-development-branch）
+# 决策阻塞点清单（decision-points）
+
+规范路径：`comate/reference/decision-points.md`（单一真相源）
+
+本文件集中定义 comate 全流程中**必须暂停等待用户**的决策点。各阶段 SKILL 用一行引用本文件的某一条，而不重复叙述规则，避免措辞漂移。
+
+## 先判定：这里真的需要用户输入吗？
+
+到达一个候选决策点时，**先分类，再决定是否阻塞**。不要把"需要做出选择"等同于"需要问用户"。
+
+| 类别 | 判据 | 处理 |
+|------|------|------|
+| **用户决策** | 存在 ≥2 个有效选项，且不同选项会改变范围、行为、可接受的风险或产生不可逆结果 | 阻塞，按下方通用规则用 AskUserQuestion 等待用户 |
+| **自动处理** | 在用户请求范围内只剩一个安全动作：修复客观失败、调和可验证的状态、重试幂等检查、或遵循已持久化的配置 | 直接执行并如实报告，**不制造确认点** |
+| **停止条件** | 缺依赖、状态损坏、路径逃逸、外部命令不可用，无有效下一步 | 报告阻塞与恢复条件，**不发明选项** |
+
+三条落地准则：
+
+1. **能合并的选择合并问**：相邻、可一次答完的选择放进同一次 AskUserQuestion，不拆成多次暂停。
+2. **不重复问已持久化且仍有效的选择**：配置文件或状态已记录且未失效时，直接沿用并说明。
+3. **先做能力预检再展示选项**：只呈现当前平台/仓库真正可执行的选项；某字段只剩一个有效值时，解释原因并直接应用，不为它单独制造一次暂停。
+
+## 通用规则
+
+经上一节判定确属**用户决策**后，该节点即为**阻塞点**：当前 `/comate` 调用必须停止，**使用 AskUserQuestion 工具等待用户选择**。只有在用户明确选择后，才能写入对应状态字段并继续执行，然后恢复自动推进。
+
+- 文字输出**不能**替代工具等待。必须通过 AskUserQuestion 显式获得用户选择。
+- 不得用推荐规则、默认值或历史偏好替代**用户决策类**节点的确认。
+- 推荐规则只能用于在问题里说明建议，不能代替用户拍板。
+- 其他无歧义的阶段流转、以及经判定属"自动处理"的节点，必须自动进行，不得中途退出，也不得为其伪造一次用户确认。
+
+## 决策阻塞点清单
+
+以下是 comate 全流程中**核心决策点**的规范定义。各阶段 SKILL 用一行引用本文件的某一条，而不重复叙述规则，避免措辞漂移。
+
+**本清单不穷举所有决策场景**——仅列出跨阶段、高频、影响流转的关键决策点。各 skill 内还有局部决策（如命名确认、dirty worktree 归因、PRD 选择等），由该 skill 自行定义并遵循本文首节的三类框架。
+
+## 核心决策点（跨阶段 / 流转关键）
+
+1. **开题产物审视确认**（open）
+   proposal/design/tasks 三件套完成且内容完整后，**先按来源分类，再决定是否阻塞**（对齐本文件首节三类框架）：
+   - **对话来源**（`source_kind: conversation`）——范围此前未经任何用户拍板，三件套是第一次成形，属"用户决策"。暂停请用户确认或要求调整。
+   - **PRD 扇出且范围一致**——本 change 来自一份**已过门禁的 PRD**（可验证信号全部成立：`source_kind: file`、追踪的源是 PRD、`gate <prd> check` 返回 PASS、change 名已记入该 PRD `spawned_changes`），**且** proposal 的范围/目标/非目标忠实承接 gate 映射里本 change 认领的功能项、无擅自扩缩。此时范围/映射/命名已在决策点 6 由用户拍板，三件套只是承接，不产生新的 ≥2 有效选项 —— 只剩"继续"一个安全动作，属"自动处理"。**不 AskUserQuestion**，完整性检查通过即自动流转，并如实报告：承接自哪份 PRD、认领哪些功能项、已核对范围与映射一致。
+   - **PRD 扇出但范围有偏差**——proposal 与 gate 映射不一致（擅自扩大/缩小范围、认领了未分配的功能项、漏掉已分配项）时，分歧重新出现，属"用户决策"。**必须 AskUserQuestion 暂停**，展示偏差点，请用户裁定按映射修正还是接受新范围。
+   引用：`comate-open` Step 5。
+
+2. **设计方案确认**（design / brainstorming）
+   brainstorming 产出技术方案后，暂停请用户确认采用的方案、关键取舍、测试策略、Spec Patch。确认前不得创建最终 Design Doc、写 `design_doc`、跑 design guard 或进入 build。
+   引用：`comate-design` Step 1c。
+
+3. **构建工作方式选择**（build）
+   开始执行前，先做能力预检，再**一次性**就工作区隔离方式（current / branch / worktree）、执行方式（subagent-driven-development / executing-plans）、TDD 模式（tdd / direct）做一个**联合决策**；选 branch 时分支名也在同一次问清，不得二次暂停。
+   预检后某维度只剩一个可执行选项时，属"自动处理"：说明原因并直接写入对应字段，不为它单独制造暂停。仍有 ≥2 个有效选项的维度才进入 AskUserQuestion。三个维度全部只剩单值时，全部自动写入，本决策点跳过。
+   引用：`comate-build` Step 3。
+
+4. **验证失败决策**（verify）
+   验证不通过时先按严重程度分类，**只有真正的用户决策才阻塞**：
+   - **CRITICAL（构建失败 / 测试失败 / 安全问题 / 核心验收场景失败）** —— 属"自动处理"，唯一安全动作就是修复。直接执行 `state transition <name> verify-fail` 回到 build，如实报告失败项，**不询问**。
+   - **Spec 漂移**（design doc 与 delta spec 矛盾）—— 属"用户决策"，必须 AskUserQuestion 暂停（见 Step 2b 三选项）。
+   - **仅 WARNING / SUGGESTION，无任何 CRITICAL** —— 属"用户决策"（可接受偏差是合法选择），一次性批量展示并提供「全部修复 / 逐项处理 / 接受偏差（记录原因）」。
+   引用：`comate-verify` Step 1b、Step 2b 的 Spec 漂移处理。
+
+5. **分支收尾方式选择**（verify / finishing-a-development-branch）
    暂停请用户选择：本地合并 / 推送建 PR / 保持分支 / 丢弃工作。前三项操作成功后写 `branch_status: handled`；丢弃工作写 `branch_status: discarded` 并停止流程，禁止执行 verify guard 或归档。
-   引用：`comate-verify` Step 3。
-
-6. **预设升级确认**（fix → full）
+   引用：`comate-verify` Step 3。
+
+6. **预设升级确认**（fix → full）
    命中升级条件（见 `comate-fix` SKILL 的「升级条件」，bug 模式与调整模式各有阈值）时，先写 `phase_step: fix.upgrade-awaiting`，再暂停请用户确认。用户确认后执行原子转换 `state transition <name> fix-upgrade`，由脚本清除 fix 默认构建选项并进入 design。
-   引用：`comate-fix`「升级条件」。
-
-7. **构建期范围扩张**（build）
-   实施中发现需要重新设计或拆分新 change 时暂停。判定基准：以 tasks.md 初始任务总数为准，新增任务超过总数一半（50% 阈值）即视为超范围，请用户决定是否拆分。中等规模（接口变更、新增组件）确认后加载 `superpowers:brainstorming` 更新设计；大规模（全新 capability）确认后用 `/comate-open` 拆独立 change。
-   引用：`comate-build` Step 4。
-
-## 其他决策场景（局部 / 特定 skill）
-
-以下决策点由特定 skill 自行定义，同样遵循本文首节的三类框架，但不属于跨阶段核心流转：
-
-### Gate 阶段（comate-gate）
-- **PRD 命名规范确认**：PRD 不符合命名规范时，AskUserQuestion 确认改名或拒绝
-- **PRD 未定稿处理**：PRD 标记 draft/WIP 时，确认是否继续评审
-- **阻断问题处理策略**：`blocking_open > 0` 时选择：先补 PRD / 授权带 TBD 继续 / 深度澄清 / 暂停
-- **拆分粒度与映射**（决策点 6 已列入核心）：功能项 → change 的映射由用户确认
-
-### Open 阶段（comate-open）
-- **继续已有 change / 新建**：顶层探测到活跃 change 时，确认继续还是新建
-- **Change 命名确认**：必须用用户指定或经 AskUserQuestion 确认的名称，不得自动生成
-
-### Build 阶段（comate-build）
-- **Dirty worktree 归因**：脏工作树按 `dirty-worktree.md` 协议分类后，不属于当前 change 或来源不确定时需要用户裁定：并入 / 拆分 / 保留 / 丢弃
-
-### Verify 阶段（comate-verify）
-- 已列入核心决策点 4、5
-
-## Red Flags — 出现这些念头就停下来检查
-
-| Agent 的念头 | 实际风险 |
-|--------------|----------|
-| “用户大概会同意这个方案吧” | 不能替用户决定 —— 用 AskUserQuestion |
-| “这是个小改动，不用确认” | 决策点没有大小豁免 —— 阻塞点必须等待 |
-| “上次用户选了 A，这次也 A” | 历史偏好不能替代当前确认 |
-| “我把计划讲了，用户没反对” | 没反对 ≠ 同意 —— 必须用工具拿到明确选择 |
-| “流程都走到这了，应该没问题” | 验证未通过 ≠ 已通过 —— 检查 verify_result |
+   引用：`comate-fix`「升级条件」。
+
+7. **构建期范围扩张**（build）
+   实施中发现需要重新设计或拆分新 change 时暂停。判定基准：以 tasks.md 初始任务总数为准，新增任务超过总数一半（50% 阈值）即视为超范围，请用户决定是否拆分。中等规模（接口变更、新增组件）确认后加载 `superpowers:brainstorming` 更新设计；大规模（全新 capability）确认后用 `/comate-open` 拆独立 change。
+   引用：`comate-build` Step 4。
+
+## 其他决策场景（局部 / 特定 skill）
+
+以下决策点由特定 skill 自行定义，同样遵循本文首节的三类框架，但不属于跨阶段核心流转：
+
+### Gate 阶段（comate-gate）
+- **PRD 命名规范确认**：PRD 不符合命名规范时，AskUserQuestion 确认改名或拒绝
+- **PRD 未定稿处理**：PRD 标记 draft/WIP 时，确认是否继续评审
+- **阻断问题处理策略**：`blocking_open > 0` 时选择：先补 PRD / 授权带 TBD 继续 / 深度澄清 / 暂停
+- **拆分粒度与映射**（决策点 6 已列入核心）：功能项 → change 的映射由用户确认
+
+### Open 阶段（comate-open）
+- **继续已有 change / 新建**：顶层探测到活跃 change 时，确认继续还是新建
+- **Change 命名确认**：必须用用户指定或经 AskUserQuestion 确认的名称，不得自动生成
+
+### Build 阶段（comate-build）
+- **Dirty worktree 归因**：脏工作树按 `dirty-worktree.md` 协议分类后，不属于当前 change 或来源不确定时需要用户裁定：并入 / 拆分 / 保留 / 丢弃
+
+### Verify 阶段（comate-verify）
+- 已列入核心决策点 4、5
+
+## Red Flags — 出现这些念头就停下来检查
+
+| Agent 的念头 | 实际风险 |
+|--------------|----------|
+| “用户大概会同意这个方案吧” | 不能替用户决定 —— 用 AskUserQuestion |
+| “这是个小改动，不用确认” | 决策点没有大小豁免 —— 阻塞点必须等待 |
+| “上次用户选了 A，这次也 A” | 历史偏好不能替代当前确认 |
+| “我把计划讲了，用户没反对” | 没反对 ≠ 同意 —— 必须用工具拿到明确选择 |
+| “流程都走到这了，应该没问题” | 验证未通过 ≠ 已通过 —— 检查 verify_result |