@house365/comate 0.10.2 → 1.0.2-next.0

package/skills/comate-grill/SKILL.md

@@ -1,185 +0,0 @@
----
-name: comate-grill
-description: "决策点穷追式澄清工具。对计划/设计/PRD 问题进行深度优先遍历，逐个决策点给推荐答案并等用户确认，直到所有歧义清零。可由 comate-gate 内部调用，或用户直接 /comate-grill 使用。"
----
-
-# comate-grill —— 决策点穷追式澄清
-
-**定位**：一个通用的决策澄清引擎，用于在计划/设计/需求阶段对模糊点、依赖链、歧义进行**逐个深挖**，直到所有分支清晰。
-
-**算法来源**：改编自社区 [grill-me pattern](https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/)（Timothy Vang、Matt Pocock 等贡献的最佳实践），内化到 comate 家族以避免外部依赖漂移。
-
----
-
-## 核心算法（四条铁律）
-
-1. **决策树深度优先遍历**  
-   串行解决决策点，不批量轰炸。后续分支常依赖前面的答案，所以必须一个接一个。
-
-2. **每个问题附推荐答案**  
-   不是裸问题（"你觉得 X 怎么设计？"），而是"我建议用 Y 方案，因为 Z 理由。你同意吗？如果不同意，你倾向什么？"
-
-3. **优先探索代码库/文档，不问能查到的事实**  
-   - 已有架构约定、字段定义、接口规范、对接档案 → 用 Read/Grep/Glob/LSP 核实，引用来源，不丢给用户。
-   - 产品决策（范围、优先级、用户行为、状态流转、数据口径、失败处理、验收规则）→ 必须问用户。
-
-4. **一次一问，等回答再进下一个**  
-   并行提多个问题会让用户不知从哪答起，且前面的答案可能让后面的问题失效。
-
----
-
-## 调用场景
-
-### 由其他 skill 内部调用（主场景）
-
-- **comate-gate 步骤 3（阻断闸门）**：当 PRD 阻断问题 > 3 个或有决策依赖链时，用户可选「深度澄清模式」，此时 gate 调用本 skill，传入阻断问题清单，逐个深挖。
-- **未来扩展**：comate-design 的方案澄清、comate-verify 的验收标准澄清等，都可复用本 skill。
-
-**调用方式**（从其他 skill 内）：
-
-```markdown
-用 Skill 工具加载 `comate-grill`，传入：
-
-话题：<要澄清的主题，如「PRD 阻断问题清单」>
-问题列表：
-1. [ID] 问题描述 | 原文依据 | 影响范围 | 当前歧义
-2. ...
-```
-
-### 用户直接调用
-
-用户可以在任何阶段直接 `/comate-grill <话题>` 对计划、设计、决策进行穷追式澄清。适用于：
-
-- 自己的计划草稿想被挑战一遍
-- 技术方案有多个路径，想逐条过一遍利弊
-- PRD/需求文档的边界不清楚，想被问到无死角
-
----
-
-## 工作流
-
-### 输入
-
-- **话题**：澄清的主题（如「PRD 阻断问题」「技术选型」「API 设计」）
-- **问题列表**（可选，无则从话题自由展开）：带 ID、描述、依据、影响的问题清单
-
-### 过程
-
-1. **建决策树骨架**  
-   根据问题列表（或从话题展开）识别所有决策点，按依赖关系排序（前面的决策会影响后面的选项）。
-
-2. **逐点深挖**  
-   从第一个决策点开始：
-   - 先查代码库/文档/架构约定能否直接回答（能则引用来源，告知用户，进入下一个）
-   - 不能则构造推荐答案：2–3 个互斥选项 + 推荐项 + 理由 + 各选项的后果
-   - 用 **AskUserQuestion** 提问，等用户回答
-   - 记录答案，更新后续决策点的前置条件
-
-3. **递归展开新分支**  
-   用户的回答可能引出新的子问题（如选了"分布式事务"就要问"补偿机制怎么设计"）。把新问题插入决策树对应位置，继续深挖。
-
-4. **终止条件**  
-   所有决策点都有明确答案（非"待定""看情况"），或用户主动喊停。
-
-### 输出
-
-- **决策台账**（markdown 表格）：每个问题的 ID、问题、推荐、用户答案、依据/来源
-- **待办事项**（若有）：哪些答案需要后续在代码/文档中落地
-
----
-
-## Guardrails
-
-- **AskUserQuestion 是真阻塞点**：推荐答案、默认值、"通常做法"、历史偏好都不能替代用户明确回答。只有用户选了选项或输入自定义答案，才能进入下一个决策点。
-- **不替用户拍板**：可以给建议、列利弊、引用案例，但最终选择必须等用户确认。
-- **不问能查到的事实**：已有的架构文档、代码约定、接口规范先用工具核实，只问"怎么做"的决策，不问"是什么"的事实。
-- **分支依赖显式标注**：后续问题若依赖前面的答案，在提问时点明"因为你选了 X，所以这里..."，让用户理解为什么要问这个。
-- **深度有限，避免无底洞**：单个决策点最多展开 2 层子问题。若发现需要第 3 层，说明原问题拆得不够，停下来重新拆解问题本身。
-
----
-
-## 示例
-
-**输入**（由 comate-gate 调用）：
-
-```
-话题：PRD 门禁阻断问题清单
-问题列表：
-1. [B-03] 用户登录失败后的重试机制未明确 | 原文"支持登录" | 影响：异常路径、用户体验
-2. [B-07] 数据同步到第三方失败时的降级策略缺失 | 原文"对接外部 API" | 影响：可用性、数据一致性
-3. [B-11] 管理员权限范围模糊（能否删除其他管理员的数据？）| 原文"管理员可管理所有数据" | 影响：权限设计、安全
-```
-
-**执行**：
-
-1. **问题 1（登录重试）**  
-   - 先查现有登录模块代码：发现有 `max_retries` 配置但未用
-   - 给推荐："我建议限制 5 次/15 分钟，超过后锁定账户 30 分钟并发邮件通知，理由是防暴力破解。你同意吗？"
-   - 用户答："改成 3 次/10 分钟，锁定 1 小时"
-   - 记录，进入下一个
-
-2. **问题 2（第三方失败降级）**  
-   - 查架构文档：无降级策略先例
-   - 给推荐："我建议失败后写本地队列，定时重试 3 次，3 次后人工介入。你倾向什么？"
-   - 用户答："可以，但重试间隔用指数退避"
-   - 追问："指数退避的初始间隔和最大间隔？"（新分支）
-   - 用户答："初始 30s，最大 10min"
-   - 记录，进入下一个
-
-3. **问题 3（管理员权限）**  
-   - 查权限表和现有角色定义：只有 `admin` 和 `user` 两角色
-   - 给推荐："建议引入超级管理员（super_admin）和普通管理员（admin），普通管理员不能删除其他管理员的数据。你同意吗？"
-   - 用户答："不需要超级管理员，所有管理员平级，但删除操作需二次确认"
-   - 记录
-
-**输出**：
-
-```markdown
-## 决策台账
-
-| ID    | 问题 | 推荐 | 用户答案 | 依据/来源 |
-|-------|------|------|----------|-----------|
-| B-03  | 登录重试机制 | 5次/15分钟，锁定30分钟 | 3次/10分钟，锁定1小时 | 用户确认 |
-| B-07  | 第三方失败降级 | 本地队列+定时重试3次 | 同意，重试用指数退避（30s→10min） | 用户确认 |
-| B-11  | 管理员权限范围 | 引入super_admin和admin两级 | 不分级，删除操作二次确认 | 用户确认 |
-
-所有阻断问题已澄清，可更新 PRD 评审报告并置 `blocking_open=0`。
-```
-
----
-
-## 与 comate 其他 skill 的区别
-
-| skill | 定位 | 提问方式 |
-|-------|------|----------|
-| **comate-grill** | 决策点穷追引擎，逐个深挖直到无歧义 | 深度优先、一次一问、附推荐 |
-| comate-gate | PRD 门禁+拆分，暴露问题但不深挖每个 | 批量扫描+分轮处理 |
-| openspec-explore | 探索问题空间，发散式头脑风暴 | 开放式、多角度、不强制收敛 |
-| comate-design | 技术设计+方案 brainstorming | 方案对比、架构决策、不逐点穷举 |
-
-**简单说**：explore 是发散、grill 是收敛、gate 是门禁、design 是方案对比。grill 的独特价值是"不放过任何一个模糊点"。
-
----
-
-## 何时用 comate-grill
-
-**推荐用**：
-- 阻断问题 > 3 个且有依赖链（gate 自动提供选项）
-- 技术方案有多条路径，想逐条过利弊（design 阶段手动调用）
-- 自己的计划草稿想被挑战到无死角（用户直接 `/comate-grill <话题>`）
-
-**不推荐用**：
-- 简单问题（≤ 2 个独立决策点）→ 直接 AskUserQuestion 即可
-- 纯事实查询（"这个字段在哪张表"）→ 用 Read/Grep/LSP
-- 开放式头脑风暴（"有哪些可能的方案"）→ 用 openspec-explore
-
----
-
-## 维护说明
-
-本 skill 是社区最佳实践的内化版本，避免外部依赖漂移。若社区 grill-me 有新算法改进，可在此同步更新，但保持 comate 命名空间和中文文档风格。
-
-**来源致谢**：
-- [mattpocock/skills - grill-me](https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md)
-- [gsarig/skills - grill-me](https://github.com/gsarig/skills/blob/main/skills/grill-me/README.md)
-- [RobMitt/grill-me-skill](https://github.com/RobMitt/grill-me-skill)

package/skills/comate-open/SKILL.md

@@ -1,230 +0,0 @@
----
-name: comate-open
-description: "comate 阶段 1：开题。用 /comate-open 调用。通过 OpenSpec 探索想法、创建 change 结构（proposal + design + tasks）并初始化 .comate.yaml。"
----
-
-# comate 阶段 1：开题（Open）
-
-## 前置条件
-
-- 无活跃 change，或用户希望创建新 change
-
-## 步骤
-
-### 1. 探索想法
-
-**立即执行：** 使用 Skill 工具加载 `openspec-explore` 技能。禁止跳过。加载后按其指引自由探索问题空间。
-
-### 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 结构 + 初始化状态
-
-#### Gate 扇出骨架模式
-
-当调用方明确说明本次来自 `comate-gate` 的批量扇出时，使用独立的骨架模式：
-
-1. 运行 gate check；
-2. 创建或补齐 `.openspec.yaml`、proposal.md、design.md、tasks.md；
-3. `.comate.yaml` 不存在时才执行 `state init full`，已存在时读取并复用，不能重复 init；
-4. 追踪源 PRD；
-5. 运行 `state check open` 并检查所有骨架文件非空、proposal 范围忠实承接映射；
-6. 最后执行 `gate spawned`。脚本会再次校验 gate 未 stale、骨架完整且源 manifest 确实追踪该 PRD；
-7. 登记成功后保持 `phase: open`，立即返回 comate-gate 的扇出循环。
-
-骨架模式不执行 Step 4 后的 `phase_step` 记录、Step 5 产物确认、open guard 或本文“自动流转”；**不得**在同一次 gate 调用中加载 `comate-design`。下一项由 gate 根据 `fanout-status` 的 `missing` 列表继续处理。
-
-若不是 gate 扇出调用，保持普通 open 流程并按本文退出条件进入 design。
-
-**立即执行：** 使用 Skill 工具加载 `openspec-new-change` 技能。若用户意图未明确、需先形成建议，改为加载 `openspec-propose`。禁止跳过。
-
-**命名与范围守卫**：change name 必须用用户指定或经 AskUserQuestion 确认的名称，不得自动生成或推断。变更范围必须与用户描述一致，不得自行扩大或缩小。
-
-确认产物已创建：
-
-```
-openspec/changes/<name>/
-├── .openspec.yaml
-├── proposal.md       # Why + What：问题、目标、范围、非目标
-├── design.md         # How（高层）：架构决策、方案选型、数据流
-└── tasks.md          # 任务清单（勾选框）
-```
-
-定位 comate 脚本并初始化 `.comate.yaml`：
-
-```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" state <name> init full
-```
-
-这会创建 `openspec/changes/<name>/.comate.yaml`，初始状态：`workflow: full`, `phase: open`, `phase_step: null`。
-
-**恢复规则**：若 change 目录或 `.comate.yaml` 已存在，逐项检查并补齐缺失产物；`.comate.yaml` 存在时跳过 `state init`。这覆盖“骨架已创建但尚未 gate spawned”中断点，完成校验后直接补登记。
-
-### 3b. 判定需求来源(源文件追踪)
-
-`state init` 默认写入 `source_kind: conversation`、`source_manifest: null`(需求由对话产生)。
-
-若本次需求来自 `docs/knowledge-base/` 下的一份或多份知识库文档,追踪它们以支持后续双向排查:
-
-```bash
-bash "$COMATE" sources <name> track docs/knowledge-base/<path>.md --note "<可选说明>"
-```
-
-- 追踪成功后 `source_kind` 自动改为 `file`,并在 `openspec/changes/<name>/.comate/sources.manifest` 钉住每个文件当时的 sha256 与 commit ref。
-- 仅 `docs/knowledge-base/` 范围内的文件可追踪;范围外文件会被跳过并提示,`source_kind` 保持 `conversation`,不影响流程。
-- 边追踪边产生:若开题时为对话来源、设计中途才拿到知识库文档,后续任意阶段补 `sources <name> track` 即可,无需回到 open。
-
-### 3c. PRD 扇出记录（从 PRD 建 change 时必须登记）
-
-若本 change 来自 PRD，在创建、源追踪和完整性校验全部完成后，把该 change 记回门禁：
-
-```bash
-bash "$COMATE" gate <prd路径> spawned <name>
-```
-
-此步将 change 名称追加到 `<PRD>.gate.yaml` 的 `spawned_changes` 列表，用于追溯 PRD → change 的完整扇出关系。不得在文件不完整或源追踪前提前登记。
-
-需求**来自对话**时跳过本步。
-
-### 3. 入口状态验证与幂等性检查
-
-```bash
-bash "$COMATE" state <name> check open
-```
-
-验证通过后继续 Step 4。失败时脚本输出具体原因。
-
-**幂等性检查**：
-
-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 或执行守卫，必须回创建步骤补充。
-
-完整性检查通过后记录：
-
-```bash
-bash "$COMATE" state <name> set phase_step open.artifacts-created
-```
-
-### 5. 产物审视（决策阻塞点 1，按来源分类）
-
-三件套完成且 Step 4 完整性检查通过后，**先按来源分类，再决定是否需要用户输入**。规则见 `comate/reference/decision-points.md` 第 1 条。
-
-#### 5a. 判定是否属"PRD 扇出且范围一致"（可自动流转）
-
-同时满足以下**全部**条件时，本决策点降级为自动流转，**不 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 3c 的上下文取得；
-3. change 名已记入该 PRD 的 `spawned_changes`（Step 3c 的 `gate spawned` 已执行，通常由 `/comate-gate` 备妥）；
-4. **范围一致性自检**：proposal 的目标/范围/非目标忠实承接 gate 映射里本 change 认领的功能项——没有擅自扩大或缩小、没有认领未分配的功能项、没有漏掉已分配项。
-
-四条全成立时：范围/映射/命名已在决策点 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 偏差场景额外列出偏差点）和选项：
-- 「确认，继续下一阶段」— 记录确认状态后执行守卫流转
-- 「需要调整」— 附调整说明（PRD 偏差场景默认建议按映射修正），修改后重新请求确认
-
-**提问前先持久化等待状态**：
-
-```bash
-bash "$COMATE" state <name> set phase_step open.review-awaiting
-```
-
-**用户确认后立即记录**：
-
-```bash
-bash "$COMATE" state <name> set phase_step open.review-confirmed
-```
-
-然后继续执行退出条件（guard）。
-
-## 退出条件
-
-以下退出条件仅适用于普通 open；gate 扇出骨架模式使用 Step 3 的专用返回条件。
-
-- 三件套已创建且内容完整
-- **用户已确认**
-- **阶段守卫**：运行 `bash "$COMATE" guard <name> open --apply`，全 PASS 后自动流转
-
-退出前必须 `--apply`，否则 `.comate.yaml` 停留在 `phase: open`，下阶段入口检查会失败。
-
-```bash
-bash "$COMATE" guard <name> open --apply
-```
-
-full 流程自动更新为 `phase: design`；fix 预设自动更新为 `phase: build`。
-
-## 自动流转
-
-仅普通 open 在用户确认后自动流转：
-
-> **REQUIRED NEXT SKILL（完整流程）：** 调用 `comate-design` skill 进入深度设计。
->
-> fix 预设由 `/comate-fix` skill 控制后续流转（phase 直接进 build），不经过本节。

package/skills/comate-verify/SKILL.md

@@ -1,212 +0,0 @@
----
-name: comate-verify
-description: "comate 阶段 4：验证与收尾。用 /comate-verify 调用。验证实现符合设计，处理开发分支。"
----
-
-# comate 阶段 4：验证与收尾（Verify）
-
-## 前置条件
-
-- 代码已提交（阶段 3 完成）
-- tasks.md 全部任务已完成
-
-## 步骤
-
-### 0a. 输出语言约束
-
-**在开始任何检查前先确立**：本阶段所有产物——落盘的验证报告、失败项报告、给用户的结论——正文一律简体中文。标题、结论、问题描述、修复建议、表格表头都用中文。
-
-以下保留英文原文：严重程度枚举（CRITICAL / WARNING / SUGGESTION）、代码标识符与路径、命令与日志原始输出、`file.ts:123` 形式的引用、技术术语和库名。
-
-判断标准：句子主体是中文即合格。不要把英文模板逐句直译成生硬中文，按中文表达重写。
-
-### 0b. 入口状态验证
-
-```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" state <name> check verify
-```
-
-**幂等性**：verify 阶段检查可安全重复。若 `verify_result` 已为 `pass` 且 `branch_status` 为 `handled`，直接执行 guard 流转；若为 `pending`，从头验证。
-
-### 1. 改动规模评估
-
-```bash
-bash "$COMATE" state <name> scale
-```
-
-脚本统计任务数、增量规格数、变更文件数，判断 light/full 验证模式并设 `verify_mode`。输出会标注用了哪个基线（plan base-ref / state base_ref / 工作树 diff）。
-
-验证开始前，按 `comate/reference/dirty-worktree.md` 处理未提交改动。verify 阶段特例：
-1. dirty diff 属于当前 change 且涉及实现/测试/tasks/spec/design doc → 不在 verify 直接修复，报告失败项进入 Step 1b
-2. dirty diff 只是 verify 本阶段产物（验证报告草稿、分支处理记录）→ 可继续
-3. dirty diff 已实现但 tasks.md 未勾选 → 视为 build 滞后，报告失败项进入 Step 1b
-
-注意：build 阶段每任务都提交时，工作区 diff 可能低估规模。读 plan 文件头 `base-ref` 用提交区间复核：
-
-```bash
-PLAN=$(bash "$COMATE" state <name> get plan)
-BASE_REF=$(grep '^base-ref:' "$PLAN" 2>/dev/null | head -1 | sed 's/^base-ref:[[:space:]]*//')
-git diff --stat "$BASE_REF"...HEAD
-```
-
-超轻量阈值（> 4 文件 / 跨模块 / delta spec > 1 capability）则手动设 `bash "$COMATE" state <name> set verify_mode full`。
-
-### 1b. 验证失败决策（决策阻塞点 4）
-
-验证不通过时**先按严重程度分类，再判定是否需要用户输入**。规则与"三类行动"判定见 `comate/reference/decision-points.md` 第 4 条。
-
-分类（**不确定性原则**：无法确定严重程度时降级 SUGGESTION > WARNING > CRITICAL）：
-- **CRITICAL**：构建失败 / 测试失败 / 安全问题 / 核心验收场景失败
-- **WARNING / SUGGESTION**：非阻断性问题（覆盖率不足、风格、优化建议等）
-- **Spec 漂移**：delta spec 与 design doc 矛盾（见 Step 2b 单独处理）
-
-按类别分流：
-
-1. **有任何 CRITICAL（且非 Spec 漂移）** —— 属"自动处理"，唯一安全动作就是修复。**不询问**，直接：
-   ```bash
-   bash "$COMATE" state <name> transition verify-fail
-   ```
-   然后调 `/comate-build`。回到 build 前如实报告：哪些是 CRITICAL 失败项、判定依据、将如何修复。
-
-2. **无 CRITICAL，仅 WARNING / SUGGESTION** —— 属"用户决策"（接受偏差是合法选择）。**一次性 AskUserQuestion 批量展示**全部失败项与推荐处理，提供：
-   - **全部修复**：`bash "$COMATE" state <name> transition verify-fail` 然后调 `/comate-build`
-   - **逐项处理**：勾选要修的项，其余接受偏差
-   - **接受偏差**：全部接受，须在报告记录每项原因和影响
-
-   提问前先写 `phase_step: verify.failure-awaiting`；作出决定后清除或写入对应处理结果。
-
-3. **Spec 漂移** —— 按 Step 2b 的单选题处理（属"用户决策"，必须暂停）。
-
-> CRITICAL 自动回 build 不代表跳过用户知情：回退前必须输出清晰的失败报告作为证据。若一次验证同时含 CRITICAL 与非 CRITICAL，以 CRITICAL 优先自动回 build，非 CRITICAL 项留待修复轮次一并处理。
-
-### 2a. 轻量验证（小改动）
-
-规模为「小」时跳过 `openspec-verify-change`，直接执行 5 项检查：
-1. tasks.md 全部 `[x]`
-2. 改动文件与 tasks.md 描述一致（`git diff --stat` 对照）
-3. 编译通过（项目构建命令）
-4. 相关测试通过
-5. 无明显安全问题（无硬编码密钥、无新增 unsafe）
-
-**通过标准**：5 项全 OK，无 CRITICAL。不通过 → 进入 Step 1b。报告语言按 Step 0a，骨架可只保留「结论 / 检查项 / 验证证据」三节。
-
-### 2b. 完整验证（大改动）
-
-规模为「大」时**立即使用 Skill 工具加载 `openspec-verify-change`**。检查项：tasks 全勾、实现符合 design.md 高层决策、符合 Design Doc、能力规格场景全通过、proposal 目标满足、delta spec 与 design doc 无矛盾、关联设计文档可定位。
-
-<!-- external-openspec-skill-override -->
-> **外部 skill 覆写**：加载后**只采用其验证语义**（检查维度、严重程度分级、判定启发式）。其输出形式一律不采用——报告模板、英文标题与结论话术、表格表头都按 Step 0a 的语言约束和 Step 3 的骨架重写，不得照抄。
-
-**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`）
-
-提问前先写 `phase_step: verify.spec-drift-awaiting`。
-
-### 3. 记录验证证据
-
-验证报告必须落盘并记录。不要手动设 `verify_result: pass`，通过 guard 自动流转。
-
-语言按 Step 0a。参考骨架：
-
-```markdown
-# 验证报告：<change-name>
-
-## 结论
-<通过 / 存在 N 个 CRITICAL，需修复后归档>
-
-## 摘要
-| 维度 | 结果 |
-|------|------|
-| 完整性 | X/Y 任务完成，N 条需求 |
-| 正确性 | N 条需求中 M 条有实现覆盖 |
-| 一致性 | 符合设计 / 发现 N 处偏差 |
-
-## 问题清单
-### CRITICAL
-- <问题描述>（`path/to/file.ts:123`）→ 建议：<具体动作>
-
-### WARNING / SUGGESTION
-- <同上>
-
-## 验证证据
-- 构建：<命令与结果>
-- 测试：<命令与结果>
-- 源文件对照：<sources check 结果，无则写"不适用">
-```
-
-若本 change 有源文件追踪（`source_kind: file`），报告须声明本实现对照的知识库文档及其版本，并复核未漂移：
-
-```bash
-bash "$COMATE" sources <name> check          # 0=未漂移 / 1=漂移 / 4=manifest 损坏
-bash "$COMATE" sources <name> list           # 列出对照的文档路径/sha256/ref，贴入报告
-```
-
-`source_kind: conversation` 时跳过（check 为无操作通过）。
-
-```bash
-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 phase_step verify.branch-awaiting
-```
-
-选择本地合并 / 推送建 PR / 保持分支且操作完成后写入状态：
-
-```bash
-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。
-
-## 退出条件
-
-- 验证报告通过，分支已处理
-- `verification_report` 指向真实文件，`branch_status: handled`
-- `impl_hash` 与当前 plan+tasks 一致（guard 强制）
-- **阶段守卫**：`bash "$COMATE" guard <name> verify --apply` 全 PASS 后经 `verify-pass` 自动流转到 `phase: archive`
-
-```bash
-bash "$COMATE" guard <name> verify --apply
-```
-
-## 上下文压缩恢复
-
-```bash
-bash "$COMATE" state <name> recover verify
-```
-
-## 自动流转
-
-> **REQUIRED NEXT SKILL：** 调用 `comate-archive` skill 进入归档。