@house365/comate 0.10.0 → 0.10.1

package/skills/comate-verify/SKILL.md

@@ -1,141 +1,141 @@
----
-name: comate-verify
-description: "comate 阶段 4：验证与收尾。用 /comate-verify 调用。验证实现符合设计，处理开发分支。"
----
-
-# comate 阶段 4：验证与收尾（Verify）
-
-## 前置条件
-
-- 代码已提交（阶段 3 完成）
-- tasks.md 全部任务已完成
-
-## 步骤
-
-### 0. 入口状态验证
-
-```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 失败项、判定依据、将如何修复。
-
+---
+name: comate-verify
+description: "comate 阶段 4：验证与收尾。用 /comate-verify 调用。验证实现符合设计，处理开发分支。"
+---
+
+# comate 阶段 4：验证与收尾（Verify）
+
+## 前置条件
+
+- 代码已提交（阶段 3 完成）
+- tasks.md 全部任务已完成
+
+## 步骤
+
+### 0. 入口状态验证
+
+```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`
-   - **逐项处理**：勾选要修的项，其余接受偏差
+   - **全部修复**：`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。
-
-### 2b. 完整验证（大改动）
-
-规模为「大」时**立即使用 Skill 工具加载 `openspec-verify-change`**。检查项：tasks 全勾、实现符合 design.md 高层决策、符合 Design Doc、能力规格场景全通过、proposal 目标满足、delta spec 与 design doc 无矛盾、关联设计文档可定位。
-
+
+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。
+
+### 2b. 完整验证（大改动）
+
+规模为「大」时**立即使用 Skill 工具加载 `openspec-verify-change`**。检查项：tasks 全勾、实现符合 design.md 高层决策、符合 Design Doc、能力规格场景全通过、proposal 目标满足、delta spec 与 design doc 无矛盾、关联设计文档可定位。
+
 **Spec 漂移处理**（决策阻塞点 4 的一部分）：若发现 delta spec 与 design doc 矛盾，**必须以单选题 AskUserQuestion 暂停**：
-- A：在 design doc 追加 "Implementation Divergence" 节记录偏差（属 verify 阶段允许产物，写入后不再触发 Step 1b dirty 决策）
-- B：`state transition verify-fail` 然后调 `/comate-build` 由 Spec 增量更新规则更新
+- 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 自动流转。
-
-若本 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`。不可用时停止并提示安装。
-
+
+### 3. 记录验证证据
+
+验证报告必须落盘并记录。不要手动设 `verify_result: pass`，通过 guard 自动流转。
+
+若本 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
 bash "$COMATE" state <name> set branch_status handled
 bash "$COMATE" state <name> set phase_step verify.branch-handled
 ```
@@ -150,24 +150,24 @@ 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 进入归档。
+
+## 退出条件
+
+- 验证报告通过，分支已处理
+- `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 进入归档。