@house365/comate 0.9.2 → 0.9.4

package/README.md

@@ -1,3 +1,7 @@
+<div align="center">
+  <img src="comate.png" alt="comate" width="600">
+</div>
+
 # comate
 
 **SDD (规约驱动开发)** 的 AI 开发编排器。

package/bin/init.mjs

@@ -149,26 +149,21 @@ function openSpecState() {
   return { status: atLeast(version, MIN_OPENSPEC) ? 'ready' : 'outdated', version };
 }
 
-// Two install shapes to detect:
-//   skills CLI  — flattens obra/superpowers into one dir per skill, so nothing
-//                 is literally named "superpowers"; using-superpowers is the
-//                 entry skill and the stable marker.
-//   Claude Code — installs it as a plugin under plugins/{cache,data}/.
+// Only detect skills CLI installation (flattens obra/superpowers into one dir
+// per skill). Claude Code plugin cache (plugins/{cache,data}/) is not a real
+// user-level install and should not count.
 const SUPERPOWERS_MARKERS = [
   ['using-superpowers'],
   ['brainstorming'],
-  ['superpowers'],
-  ['superpowers-claude-plugins-official'],
-  ['cache', 'claude-plugins-official', 'superpowers'],
 ];
 
 function superpowersInstalled(scope) {
   const home = process.env.HOME ?? process.env.USERPROFILE ?? '';
   const roots =
     scope === 'global'
-      ? ['.agents/skills', '.claude/skills', '.claude/plugins', '.config/skills', '.cursor/skills']
+      ? ['.agents/skills', '.claude/skills', '.config/skills', '.cursor/skills']
           .map((r) => join(home, r))
-      : ['.agents/skills', '.claude/skills', '.claude/plugins', '.cursor/skills', '.codex/skills'];
+      : ['.agents/skills', '.claude/skills', '.cursor/skills', '.codex/skills'];
   return roots.some((root) => SUPERPOWERS_MARKERS.some((m) => existsSync(join(root, ...m))));
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@house365/comate",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "comate —— SDD (规约驱动开发) 的 AI 开发编排器（Agent Skills）",
   "type": "module",
   "license": "MIT",

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

@@ -29,7 +29,13 @@
 - 推荐规则只能用于在问题里说明建议，不能代替用户拍板。
 - 其他无歧义的阶段流转、以及经判定属"自动处理"的节点，必须自动进行，不得中途退出，也不得为其伪造一次用户确认。
 
-## 七个决策点
+## 决策阻塞点清单
+
+以下是 comate 全流程中**核心决策点**的规范定义。各阶段 SKILL 用一行引用本文件的某一条，而不重复叙述规则，避免措辞漂移。
+
+**本清单不穷举所有决策场景**——仅列出跨阶段、高频、影响流转的关键决策点。各 skill 内还有局部决策（如命名确认、dirty worktree 归因、PRD 选择等），由该 skill 自行定义并遵循本文首节的三类框架。
+
+## 核心决策点（跨阶段 / 流转关键）
 
 1. **开题产物审视确认**（open）
    proposal/design/tasks 三件套完成且内容完整后，**先按来源分类，再决定是否阻塞**（对齐本文件首节三类框架）：
@@ -66,6 +72,26 @@
    实施中发现需要重新设计或拆分新 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 的念头 | 实际风险 |

package/skills/comate/scripts/comate-lib.sh

@@ -449,6 +449,7 @@ GATE_FIELD_ORDER=(
   blocking_open
   review_report
   spawned_changes
+  changes_map
   gated_at
   created_at
 )

package/skills/comate/scripts/comate.sh

@@ -978,7 +978,8 @@ guard() {
         _guard_check "Design Doc declares technical-design role" _g_design_doc_role
         _guard_check "Design Doc declares canonical_spec: openspec" _g_design_doc_canonical
       else
-        [ "$GUARD_JSON" -eq 0 ] && log_warn "  [WARN] no design_doc recorded"
+        # Design Doc is required for full workflow moving to build
+        _guard_check "Design Doc recorded (design_doc field)" false
       fi
       ;;
     build)
@@ -1381,6 +1382,7 @@ score: null
 blocking_open: null
 review_report: $report
 spawned_changes: null
+changes_map: null
 gated_at: null
 created_at: $(today)
 EOF

package/skills/comate-fix/SKILL.md

@@ -138,13 +138,15 @@ Fix 为**一次性连续执行**。调用后在自有步骤间自动推进，但
 | 需新增 capability | 超出局部优化 |
 | 需 delta spec | 影响已有规格 |
 
-**必须使用 AskUserQuestion 工具暂停确认升级**。用户确认后**先更新 workflow** 再走完整流程：
+**必须使用 AskUserQuestion 工具暂停确认升级**。用户确认后**先回退到 open 阶段并更新 workflow**，再走完整流程：
 
 ```bash
+bash "$COMATE" state <name> set phase open
 bash "$COMATE" state <name> set workflow full
+bash "$COMATE" state <name> transition open-complete
 ```
 
-然后**立即加载 `comate-design` skill** 补 Design Doc。用户不确认则停止 fix 并报告超出适用范围。
+此时 phase 已转换到 `design`（因为 workflow 是 full），然后**立即加载 `comate-design` skill** 补 Design Doc。用户不确认则停止 fix 并报告超出适用范围。
 
 ## 退出条件
 

package/skills/comate-gate/SKILL.md

@@ -191,7 +191,18 @@ bash "$COMATE" gate <prd> set blocking_open <未关闭阻断数>
 - 是一功能项一 change 还是合并；
 - 各 change 命名（默认取主功能项名，用户可改）。
 
-**映射确认前不得建任何 change。** 确认后用 **TodoWrite** 把每个待建 change 建成任务项。
+**映射确认前不得建任何 change。** 确认后：
+
+1. **立即持久化映射到 gate.yaml**，使其成为机器可验证事实：
+
+```bash
+# changes_map 格式：changeA:功能项1,2,3;changeB:功能项4,5
+bash "$COMATE" gate <prd> set changes_map "changeA:功能项1,2,3;changeB:功能项4,5"
+```
+
+2. 用 **TaskCreate** 把每个待建 change 建成任务项。
+
+3. 多 change 时，在 PRD 同目录建 `CHANGES-MAP.md` 作为人类可读备份，内容与 `changes_map` 字段一致。
 
 ### 5. 通过门禁
 
@@ -223,8 +234,6 @@ bash "$COMATE" gate <prd> spawned <change-name>
 
 若门禁是 `passed-with-tbd`，在该 change 的 proposal/design 受影响处标 **「⚠ 待确认」** 并引用评审报告。
 
-多 change 时，在 PRD 同目录建 `CHANGES-MAP.md` 记录「功能项 → change」映射，便于回溯。
-
 ### 7. 收尾
 
 展示：

package/skills/comate-open/SKILL.md

@@ -15,7 +15,28 @@ description: "comate 阶段 1：开题。用 /comate-open 调用。通过 OpenSp
 
 **立即执行：** 使用 Skill 工具加载 `openspec-explore` 技能。禁止跳过。加载后按其指引自由探索问题空间。
 
-### 2. 创建 Change 结构 + 初始化状态
+### 2. PRD 门禁前置守卫（从 PRD 建 change 时必须先通过）
+
+若本 change **来自一份原始 PRD**（用户经 `/comate-gate` 拆分而来，或直接指定了来源 PRD），**在创建 change 结构之前**必须先过门禁守卫：
+
+```bash
+COMATE="${COMATE:-$(for r in . ./.agents/skills ./.claude/skills ./.cursor/skills ./.codex/skills "$HOME"/.agents/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills "$HOME"/.codex/skills "$HOME"/.gemini/skills; do
+  [ -d "$r" ] && find "$r" -maxdepth 6 -path '*/comate/scripts/comate.sh' -type f -print -quit 2>/dev/null
+done | head -1)}"
+if [ -z "$COMATE" ]; then
+  echo "ERROR: comate.sh 未找到，请确认 comate skill 已安装。" >&2
+  return 1 2>/dev/null || exit 1
+fi
+
+bash "$COMATE" gate <prd路径> check
+```
+
+- **PASS（exit 0）**：`<PRD>.gate.yaml` 存在、`gate_status ∈ {passed, passed-with-tbd}`、且 PRD 哈希未漂移。继续下一步创建 change。
+- **BLOCK（exit 1）**：门禁不存在 / 未通过 / PRD 通过后被改（stale）。**不得创建 change**，停止并提示用户先跑 `/comate-gate` 对该 PRD 过门禁。
+
+需求**来自对话**（非 PRD）时跳过本步——门禁只约束「PRD → change」这条路径。
+
+### 3. 创建 Change 结构 + 初始化状态
 
 **立即执行：** 使用 Skill 工具加载 `openspec-new-change` 技能。若用户意图未明确、需先形成建议，改为加载 `openspec-propose`。禁止跳过。
 
@@ -42,10 +63,9 @@ if [ -z "$COMATE" ]; then
   return 1 2>/dev/null || exit 1
 fi
 
-bash "$COMATE" state <name> init full
 ```
 
-### 2b. 判定需求来源(源文件追踪)
+### 3b. 判定需求来源(源文件追踪)
 
 `state init` 默认写入 `source_kind: conversation`、`source_manifest: null`(需求由对话产生)。
 
@@ -59,24 +79,17 @@ bash "$COMATE" sources <name> track docs/knowledge-base/<path>.md --note "<可
 - 仅 `docs/knowledge-base/` 范围内的文件可追踪;范围外文件会被跳过并提示,`source_kind` 保持 `conversation`,不影响流程。
 - 边追踪边产生:若开题时为对话来源、设计中途才拿到知识库文档,后续任意阶段补 `sources <name> track` 即可,无需回到 open。
 
-### 2c. PRD 门禁前置守卫（从 PRD 建 change 时必须通过）
-
-若本 change **来自一份原始 PRD**（用户经 `/comate-gate` 拆分而来，或直接指定了来源 PRD），在创建 change 结构**之前**必须先过门禁守卫：
-
-```bash
-bash "$COMATE" gate <prd路径> check
-```
+### 3c. PRD 扇出记录（从 PRD 建 change 时必须登记）
 
-- **PASS（exit 0）**：`<PRD>.gate.yaml` 存在、`gate_status ∈ {passed, passed-with-tbd}`、且 PRD 哈希未漂移。继续建 change。
-- **BLOCK（exit 1）**：门禁不存在 / 未通过 / PRD 通过后被改（stale）。**不得创建 change**，停止并提示用户先跑 `/comate-gate` 对该 PRD 过门禁。
-
-建成后把该 change 记回门禁：
+若本 change 来自 PRD，在创建完成后把该 change 记回门禁：
 
 ```bash
 bash "$COMATE" gate <prd路径> spawned <name>
 ```
 
-需求**来自对话**（非 PRD）时跳过本步——门禁只约束「PRD → change」这条路径。通常本 skill 由 `/comate-gate` 调用并已备妥门禁；用户绕过 gate 直接建 change 时，本守卫是最后一道硬闸门。
+此步将 change 名称追加到 `<PRD>.gate.yaml` 的 `spawned_changes` 列表，用于追溯 PRD → change 的完整扇出关系。
+
+需求**来自对话**时跳过本步。
 
 ### 3. 入口状态验证
 

package/skills/comate-verify/SKILL.md

@@ -96,15 +96,7 @@ git diff --stat "$BASE_REF"...HEAD
 - B：`state transition verify-fail` 然后调 `/comate-build` 由 Spec 增量更新规则更新
 - C：确认偏差可接受继续（归档时 design doc 标记 `superseded-by-main-spec`）
 
-### 3. 收尾（决策阻塞点 5）
-
-**立即执行：** 使用 Skill 工具加载 `superpowers:finishing-a-development-branch`。不可用时停止并提示安装。
-
-分支处理选项：本地合并 / 推送建 PR / 保持分支 / 丢弃。**必须使用 AskUserQuestion 工具暂停等待用户选择**。规则见 `comate/reference/decision-points.md` 第 5 条。仅在用户选择且操作完成后才写 `branch_status: handled`。
-
-确认项：全部测试通过、无硬编码密钥或安全问题。
-
-### 4. 记录验证证据
+### 3. 记录验证证据
 
 验证报告必须落盘并记录。不要手动设 `verify_result: pass`，通过 guard 自动流转。
 
@@ -121,9 +113,26 @@ bash "$COMATE" sources <name> list           # 列出对照的文档路径/sha25
 mkdir -p docs/superpowers/reports
 # 写报告到 docs/superpowers/reports/YYYY-MM-DD-<name>-verify.md
 bash "$COMATE" state <name> set verification_report docs/superpowers/reports/YYYY-MM-DD-<name>-verify.md
+```
+
+确认项：全部测试通过、无硬编码密钥或安全问题。
+
+### 4. 分支收尾（决策阻塞点 5）
+
+**在记录验证证据后**执行分支处理，确保即使丢弃工作也不影响状态持久化。
+
+**立即执行：** 使用 Skill 工具加载 `superpowers:finishing-a-development-branch`。不可用时停止并提示安装。
+
+分支处理选项：本地合并 / 推送建 PR / 保持分支 / 丢弃工作。**必须使用 AskUserQuestion 工具暂停等待用户选择**。规则见 `comate/reference/decision-points.md` 第 5 条。
+
+操作完成后写入状态：
+
+```bash
 bash "$COMATE" state <name> set branch_status handled
 ```
 
+**重要**：无论选择哪种收尾方式（包括"丢弃工作"），都必须在分支操作完成后才设置 `branch_status: handled`。这确保 guard 检查时状态已完整记录。
+
 ## 退出条件
 
 - 验证报告通过，分支已处理