@house365/comate 0.9.5 → 0.9.7

package/skills/comate-design/SKILL.md

@@ -25,7 +25,39 @@ fi
 bash "$COMATE" state <name> check design
 ```
 
-**幂等性**：design 阶段操作可安全重试。若 `handoff_context` 和 `handoff_hash` 已存在，先确认与当前产物一致再决定是否重新生成。
+**幂等性检查**：
+
+1. 读取 `.comate.yaml` 的 `design_doc`、`handoff_context`、`handoff_hash`、`phase_step`
+
+2. **已完成 Step 1c（方案已确认）** 的判定条件（按优先级，首个命中即算）：
+   
+   a. **phase_step 明确标记已确认**（最高优先级）：
+      - `phase_step` 值为 `design.approval-confirmed` 或 `design.complete`（旧版 `1c-confirmed` / `2` 兼容一次）
+      - → **立即判定为已完成 Step 1c**，跳过 Step 1a-1c
+   
+   b. **Design Doc 文件存在且格式正确**（次优先级）：
+      - `design_doc` 已设置且文件存在
+      - frontmatter 含 `comate_change: <name>`
+      - frontmatter 含 `role: technical-design`
+      - frontmatter 含 `canonical_spec: openspec`
+      - 文件内容非空（除了 frontmatter 外有实质设计内容）
+      - → **判定为已完成 Step 1c**，跳过 Step 1a-1c
+   
+   **说明**：之所以 `phase_step` 优先级更高，是因为它是原子操作记录的决策状态，即使 Design Doc 文件创建失败或被误删，也能防止重复进入决策流程。
+
+3. **幂等分支**：
+   - **已完成 Step 1c 且 Design Doc 存在** → 跳过 Step 1a-1c，检查交接包：
+     - 若 `handoff_context` 和 `handoff_hash` 已设置且验证通过 → 直接进入 Step 2 的 guard 检查
+     - 若交接包缺失或 hash 不匹配 → 重新生成交接包（`bash "$COMATE" handoff <name> design --write`），**但不重新 brainstorming，不重新确认方案**，然后进入 Step 2
+   - **已确认但 Design Doc 缺失** → 从 `.comate/design-candidate.md` 恢复已确认方案并创建 Design Doc；候选文件也缺失时停止并报告状态损坏，不得假称 Design Doc 已存在，也不得重新向用户询问同一决策
+   - **未完成 Step 1c** → 继续 Step 1a
+
+4. **断点恢复**（根据 `phase_step` 值）：
+   - `phase_step` 为 `design.handoff-written`（或旧版 `1a`）→ 从 Step 1b 开始并改写新格式
+   - `phase_step` 为 `design.brainstorm-complete` / `design.approval-awaiting`（或旧版 `1b`）→ 从候选文件恢复 Step 1c 并改写新格式
+   - `phase_step` 为 `design.approval-confirmed` 或 `design.complete` → 见第 3 点幂等分支
+
+5. **特别注意**：即使上下文压缩或会话中断，只要 `phase_step` 已标记 `design.approval-confirmed` 或 Design Doc 文件存在且格式正确，**就不得重新执行 brainstorming 或重新要求用户确认方案**。
 
 ### 1a. 生成 OpenSpec → Superpowers 交接包
 
@@ -33,6 +65,8 @@ bash "$COMATE" state <name> check design
 
 ```bash
 bash "$COMATE" handoff <name> design --write
+# 记录步骤完成
+bash "$COMATE" state <name> set phase_step design.handoff-written
 ```
 
 脚本生成 `openspec/changes/<name>/.comate/handoff/design-context.{json,md}` 并在 `.comate.yaml` 写入 `handoff_context` / `handoff_hash`。默认是 **compact 可追溯摘录**（含脚本标记 `Generated-by: comate`、source path、line range、sha256），不是 agent summary。需全文时加 `--full`。
@@ -62,13 +96,48 @@ canonical_spec: openspec
 
 禁止跳过；该技能不可用时停止流程并提示安装 Superpowers，不要用普通对话替代。
 
-brainstorming 阶段不写 Design Doc 文件，仅产出方案供 Step 1c 确认。
+brainstorming 阶段不写最终 Design Doc；但必须把完整候选方案写入 `openspec/changes/<name>/.comate/design-candidate.md`，供确认与上下文恢复使用。
+
+**步骤完成后记录**：
+
+```bash
+bash "$COMATE" state <name> set phase_step design.brainstorm-complete
+```
 
 ### 1c. 用户确认设计方案（决策阻塞点 2）
 
 **必须使用 AskUserQuestion 工具暂停等待用户明确确认设计方案**。规则见 `comate/reference/decision-points.md` 第 2 条。确认前不得创建最终 Design Doc、写 `design_doc`、跑 design guard 或进入 build。
 
-展示摘要：采用的技术方案、关键取舍与风险、测试策略、Spec Patch（如有）。用户确认后才继续 Step 2；要求调整则继续迭代。
+展示摘要：采用的技术方案、关键取舍与风险、测试策略、Spec Patch（如有）。用户确认后才继续 Step 2；要求调整则继续迭代。
+
+提问前先确认候选文件非空，并持久化等待状态：
+
+```bash
+bash "$COMATE" state <name> set phase_step design.approval-awaiting
+```
+
+**确认后的处理顺序（不可颠倒）**：
+
+1. **立即记录决策状态**：
+   ```bash
+   bash "$COMATE" state <name> set phase_step design.approval-confirmed
+   ```
+
+2. **然后创建 Design Doc 文件**（保存到 `docs/superpowers/specs/YYYY-MM-DD-topic-design.md`），frontmatter 必须包含：
+   ```yaml
+   ---
+   comate_change: <name>
+   role: technical-design
+   canonical_spec: openspec
+   ---
+   ```
+
+3. **记录 design_doc 路径**：
+   ```bash
+   bash "$COMATE" state <name> set design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+   ```
+
+**说明**：候选方案先落盘，确认后再记录 `design.approval-confirmed` 并创建最终文件。这样中断恢复既不会重复提问，也不会丢失创建 Design Doc 所需内容。
 
 ### 2. 更新 comate 状态
 
@@ -79,6 +148,9 @@ bash "$COMATE" state <name> set design_doc docs/superpowers/specs/YYYY-MM-DD-top
 # 如有 delta spec 变更，重新生成 handoff 以更新 hash
 bash "$COMATE" handoff <name> design --write
 
+# 记录步骤完成
+bash "$COMATE" state <name> set phase_step design.complete
+
 # 自动流转
 bash "$COMATE" guard <name> design --apply
 ```

package/skills/comate-fix/SKILL.md

@@ -138,15 +138,19 @@ Fix 为**一次性连续执行**。调用后在自有步骤间自动推进，但
 | 需新增 capability | 超出局部优化 |
 | 需 delta spec | 影响已有规格 |
 
-**必须使用 AskUserQuestion 工具暂停确认升级**。用户确认后**先回退到 open 阶段并更新 workflow**，再走完整流程：
+**必须使用 AskUserQuestion 工具暂停确认升级**。提问前记录：
 
 ```bash
-bash "$COMATE" state <name> set phase open
-bash "$COMATE" state <name> set workflow full
-bash "$COMATE" state <name> transition open-complete
+bash "$COMATE" state <name> set phase_step fix.upgrade-awaiting
 ```
 
-此时 phase 已转换到 `design`（因为 workflow 是 full），然后**立即加载 `comate-design` skill** 补 Design Doc。用户不确认则停止 fix 并报告超出适用范围。
+用户确认后使用原子状态转换进入完整流程：
+
+```bash
+bash "$COMATE" state <name> transition fix-upgrade
+```
+
+该转换会原子设置 `workflow: full`、进入 `phase: design`，并清空 fix 预置的 `build_mode` / `tdd_mode` / `isolation` / `verify_mode` 及阶段进度，避免 full build 误沿用 `direct`。然后**立即加载 `comate-design` skill** 补 Design Doc。用户不确认则停止 fix 并报告超出适用范围。
 
 ## 退出条件
 

package/skills/comate-gate/SKILL.md

@@ -42,7 +42,7 @@ gate 命令族（退出码：`0` 通过 / `1` 阻塞 / `2` 用法 / `3` 环境 /
 ```bash
 bash "$COMATE" gate <prd> review              # 建/刷新 gate.yaml，钉 PRD 哈希，回报告路径
 bash "$COMATE" gate <prd> set <field> <value> # 写 score | blocking_open | gate_status
-bash "$COMATE" gate <prd> pass [--tbd]         # 置 passed（要求 blocking_open=0 且报告非空）
+bash "$COMATE" gate <prd> pass [--tbd]         # 普通通过要求 0 阻断；--tbd 要求有已授权的未解决阻断
 bash "$COMATE" gate <prd> spawned <change>     # 记录据此 PRD 扇出的 change
 bash "$COMATE" gate <prd> status [--json]      # 查状态（哈希漂移自动判 stale）
 bash "$COMATE" gate <prd> check                # comate-open 建 change 前的前置守卫
@@ -209,12 +209,12 @@ bash "$COMATE" gate <prd> set changes_map "changeA:功能项1,2,3;changeB:功能
 映射与 `blocking_open` 都就绪后，置门禁通过：
 
 ```bash
-bash "$COMATE" gate <prd> pass          # 阻断已清零
-# 或用户授权带 TBD：
-bash "$COMATE" gate <prd> pass --tbd
-```
-
-`pass` 会硬校验 `blocking_open=0` 且报告非空，并重钉 PRD 哈希——之后 PRD 再被改，哈希漂移会使门禁 `stale`，须重跑 `/comate-gate`。
+bash "$COMATE" gate <prd> pass          # 阻断已清零
+# 或用户授权带 TBD：
+bash "$COMATE" gate <prd> pass --tbd
+```
+
+`pass` 会硬校验评分为 0–100、`changes_map` 非空、报告非空；普通 pass 要求 `blocking_open=0`，`--tbd` 则要求存在至少 1 个已记录且经用户明确接受的未解决阻断项。之后 PRD 再被改，哈希漂移会使门禁 `stale`，须重跑 `/comate-gate`。
 
 ### 6. 逐 Change 初始化（调 comate-open）
 

package/skills/comate-open/SKILL.md

@@ -63,8 +63,11 @@ if [ -z "$COMATE" ]; then
   return 1 2>/dev/null || exit 1
 fi
 
+bash "$COMATE" state <name> init full
 ```
 
+这会创建 `openspec/changes/<name>/.comate.yaml`，初始状态：`workflow: full`, `phase: open`, `phase_step: null`。
+
 ### 3b. 判定需求来源(源文件追踪)
 
 `state init` 默认写入 `source_kind: conversation`、`source_manifest: null`(需求由对话产生)。
@@ -91,7 +94,7 @@ bash "$COMATE" gate <prd路径> spawned <name>
 
 需求**来自对话**时跳过本步。
 
-### 3. 入口状态验证
+### 3. 入口状态验证与幂等性检查
 
 ```bash
 bash "$COMATE" state <name> check open
@@ -99,16 +102,41 @@ bash "$COMATE" state <name> check open
 
 验证通过后继续 Step 4。失败时脚本输出具体原因。
 
-**幂等性**：open 阶段所有操作可安全重复。若 `.comate.yaml` 已是 `phase: open` 且三件套已存在，跳过已完成步骤，从第一个缺失步骤继续。
+**幂等性检查**：
+
+1. 读取 `.comate.yaml` 的 `phase`、`phase_step`、workflow、以及三件套文件路径
+
+2. **已完成 Step 5（产物已审视确认）** 的判定条件：
+   - `phase_step` 值为 `open.review-confirmed`（旧版 `5-confirmed` 兼容一次）
+   - 或 `phase` 已经不是 `open`（说明已流转到下一阶段）
+
+3. **幂等分支**：
+   - **已完成 Step 5** → 跳过所有步骤，说明「开题已完成，三件套已确认」，直接检查退出条件（guard）
+   - **未完成 Step 5** → 检查三件套是否存在：
+     - 三件套全部存在且非空 → 跳到 Step 4（内容完整性检查）
+     - 任一文件缺失或为空 → 从 Step 1 开始（如果是首次）或 Step 3b/3c（如果是 PRD 来源）
+
+4. **断点恢复**（根据 `phase_step` 值）：
+   - `phase_step` 为 `open.artifacts-created` → 从 Step 4 开始
+   - `phase_step` 为 `open.review-awaiting`（或旧版 `4`）→ 恢复 Step 5 的用户确认，并改写为新格式
+   - `phase_step` 为 `open.review-confirmed`（或旧版 `5-confirmed`）→ 见第 3 点幂等分支
+
+5. **open 阶段特点**：open 阶段的所有操作（explore、创建三件套、状态初始化）可安全重复执行。但**产物审视（Step 5）的用户确认不可重复**，一旦 `phase_step: open.review-confirmed` 被记录，即使上下文压缩也不得重新要求用户确认。
 
 ### 4. 内容完整性检查
 
-逐个确认三个文件路径存在且非空：
+逐个确认三个文件路径存在且非空：
 - **proposal.md**：问题背景、目标、范围、非目标
 - **design.md**：高层架构决策、方案选型、数据流
 - **tasks.md**：任务列表，每个任务有明确描述
 
-任一文件缺失或为空时，不得进入 Step 5 或执行守卫，必须回创建步骤补充。
+任一文件缺失或为空时，不得进入 Step 5 或执行守卫，必须回创建步骤补充。
+
+完整性检查通过后记录：
+
+```bash
+bash "$COMATE" state <name> set phase_step open.artifacts-created
+```
 
 ### 5. 产物审视（决策阻塞点 1，按来源分类）
 
@@ -119,21 +147,46 @@ bash "$COMATE" state <name> check open
 同时满足以下**全部**条件时，本决策点降级为自动流转，**不 AskUserQuestion**：
 
 1. `source_kind: file`（本 change 追踪了源文件）；
-2. 追踪的源是一份 PRD，且 `bash "$COMATE" gate <prd路径> check` 返回 PASS（exit 0）——即门禁 `passed`/`passed-with-tbd` 且 PRD 哈希未漂移。PRD 路径从 `sources <name> list` 或 Step 2c 的上下文取得；
-3. change 名已记入该 PRD 的 `spawned_changes`（Step 6 的 `gate spawned` 已执行，通常由 `/comate-gate` 备妥）；
+2. 追踪的源是一份 PRD，且 `bash "$COMATE" gate <prd路径> check` 返回 PASS（exit 0）——即门禁 `passed`/`passed-with-tbd` 且 PRD 哈希未漂移。PRD 路径从 `sources <name> list` 或 Step 3c 的上下文取得；
+3. change 名已记入该 PRD 的 `spawned_changes`（Step 3c 的 `gate spawned` 已执行，通常由 `/comate-gate` 备妥）；
 4. **范围一致性自检**：proposal 的目标/范围/非目标忠实承接 gate 映射里本 change 认领的功能项——没有擅自扩大或缩小、没有认领未分配的功能项、没有漏掉已分配项。
 
-四条全成立时：范围/映射/命名已在决策点 6 由用户拍板，三件套只是承接，无新的有效选项。直接进入退出条件执行守卫流转，并**如实报告**：本 change 承接自哪份 PRD、认领哪些功能项、已核对范围与映射一致。
+四条全成立时：范围/映射/命名已在决策点 6 由用户拍板，三件套只是承接，无新的有效选项。
+
+**自动流转处理**：
+
+1. **记录自动确认状态**：
+   ```bash
+   bash "$COMATE" state <name> set phase_step open.review-confirmed
+   ```
+
+2. **如实报告**：「本 change 承接自 PRD <prd-name>，认领功能项：<列出项>。已核对范围与映射一致，自动进入下一阶段。」
+
+3. 直接进入退出条件执行守卫流转
 
 #### 5b. 需要用户输入的两种情形（AskUserQuestion 阻塞）
 
 - **对话来源**（`source_kind: conversation`）：范围此前未经用户拍板，三件套第一次成形。
 - **PRD 扇出但 5a 第 4 条不成立**（范围与映射有偏差）：分歧重新出现。
 
-以上任一情形，**必须使用 AskUserQuestion 工具暂停等待用户确认**。以单选题呈现摘要（proposal 问题/目标/范围、design 架构决策/选型、tasks 数量与关键任务；PRD 偏差场景额外列出偏差点）和选项：
-- 「确认，继续下一阶段」— 执行守卫流转
+以上任一情形，**必须使用 AskUserQuestion 工具暂停等待用户确认**。以单选题呈现摘要（proposal 问题/目标/范围、design 架构决策/选型、tasks 数量与关键任务；PRD 偏差场景额外列出偏差点）和选项：
+- 「确认，继续下一阶段」— 记录确认状态后执行守卫流转
 - 「需要调整」— 附调整说明（PRD 偏差场景默认建议按映射修正），修改后重新请求确认
 
+**提问前先持久化等待状态**：
+
+```bash
+bash "$COMATE" state <name> set phase_step open.review-awaiting
+```
+
+**用户确认后立即记录**：
+
+```bash
+bash "$COMATE" state <name> set phase_step open.review-confirmed
+```
+
+然后继续执行退出条件（guard）。
+
 ## 退出条件
 
 - 三件套已创建且内容完整

package/skills/comate-verify/SKILL.md

@@ -67,10 +67,12 @@ git diff --stat "$BASE_REF"...HEAD
    ```
    然后调 `/comate-build`。回到 build 前如实报告：哪些是 CRITICAL 失败项、判定依据、将如何修复。
 
-2. **无 CRITICAL，仅 WARNING / SUGGESTION** —— 属"用户决策"（接受偏差是合法选择）。**一次性 AskUserQuestion 批量展示**全部失败项与推荐处理，提供：
+2. **无 CRITICAL，仅 WARNING / SUGGESTION** —— 属"用户决策"（接受偏差是合法选择）。**一次性 AskUserQuestion 批量展示**全部失败项与推荐处理，提供：
    - **全部修复**：`bash "$COMATE" state <name> transition verify-fail` 然后调 `/comate-build`
    - **逐项处理**：勾选要修的项，其余接受偏差
-   - **接受偏差**：全部接受，须在报告记录每项原因和影响
+   - **接受偏差**：全部接受，须在报告记录每项原因和影响
+
+   提问前先写 `phase_step: verify.failure-awaiting`；作出决定后清除或写入对应处理结果。
 
 3. **Spec 漂移** —— 按 Step 2b 的单选题处理（属"用户决策"，必须暂停）。
 
@@ -91,10 +93,12 @@ git diff --stat "$BASE_REF"...HEAD
 
 规模为「大」时**立即使用 Skill 工具加载 `openspec-verify-change`**。检查项：tasks 全勾、实现符合 design.md 高层决策、符合 Design Doc、能力规格场景全通过、proposal 目标满足、delta spec 与 design doc 无矛盾、关联设计文档可定位。
 
-**Spec 漂移处理**（决策阻塞点 4 的一部分）：若发现 delta spec 与 design doc 矛盾，**必须以单选题 AskUserQuestion 暂停**：
+**Spec 漂移处理**（决策阻塞点 4 的一部分）：若发现 delta spec 与 design doc 矛盾，**必须以单选题 AskUserQuestion 暂停**：
 - A：在 design doc 追加 "Implementation Divergence" 节记录偏差（属 verify 阶段允许产物，写入后不再触发 Step 1b dirty 决策）
 - B：`state transition verify-fail` 然后调 `/comate-build` 由 Spec 增量更新规则更新
-- C：确认偏差可接受继续（归档时 design doc 标记 `superseded-by-main-spec`）
+- C：确认偏差可接受继续（归档时 design doc 标记 `superseded-by-main-spec`）
+
+提问前先写 `phase_step: verify.spec-drift-awaiting`。
 
 ### 3. 记录验证证据
 
@@ -123,15 +127,20 @@ bash "$COMATE" state <name> set verification_report docs/superpowers/reports/YYY
 
 **立即执行：** 使用 Skill 工具加载 `superpowers:finishing-a-development-branch`。不可用时停止并提示安装。
 
-分支处理选项：本地合并 / 推送建 PR / 保持分支 / 丢弃工作。**必须使用 AskUserQuestion 工具暂停等待用户选择**。规则见 `comate/reference/decision-points.md` 第 5 条。
+分支处理选项：本地合并 / 推送建 PR / 保持分支 / 丢弃工作。**必须使用 AskUserQuestion 工具暂停等待用户选择**。规则见 `comate/reference/decision-points.md` 第 5 条。提问前先写：
+
+```bash
+bash "$COMATE" state <name> set phase_step verify.branch-awaiting
+```
 
-操作完成后写入状态：
+选择本地合并 / 推送建 PR / 保持分支且操作完成后写入状态：
 
 ```bash
-bash "$COMATE" state <name> set branch_status handled
-```
-
-**重要**：无论选择哪种收尾方式（包括"丢弃工作"），都必须在分支操作完成后才设置 `branch_status: handled`。这确保 guard 检查时状态已完整记录。
+bash "$COMATE" state <name> set branch_status handled
+bash "$COMATE" state <name> set phase_step verify.branch-handled
+```
+
+选择**丢弃工作**时必须写 `branch_status: discarded` 和 `phase_step: verify.discarded`，随后立即停止；不得运行 verify guard、不得设置 `verify_result: pass`、不得归档。若之后要继续该 change，先执行 `state transition <name> verify-fail` 回到 build，再重新实现并生成新的 build handoff。
 
 ## 退出条件