@house365/comate 0.10.3 → 1.0.2-next.0

package/docs/COMATE_MANUAL.md

@@ -1,713 +1,287 @@
-# comate - 操作手册
+# comate 1.0 操作手册
 
-> SDD (规约驱动开发) 的 AI 开发编排器
-> 版本：schema_version 1，五阶段工作流
-> 最后更新：2026-08-17
+comate 是规约驱动开发（SDD）编排器：每个变更先写规约、确认后实现，实现由独立 verifier 逐项验收，通过后归档进主规格。
 
----
+**核心流程**：open（澄清需求、写 brief + spec）→ build ⇄ verify（失败自动回修）→ archive（写入主 spec、归档、收尾）
 
-## 目录
+**技术栈**：一个 `/comate` skill + 一个 Node.js 状态机（`skills/comate/scripts/comate.mjs`，Node ≥ 20，零依赖）。
 
-- 1. 概述与核心概念
-- 2. 安装与前置条件
-- 3. 快速开始
-- 4. 命令参考：/comate 主命令
-- 5. 阶段详解：open / design / build / verify / archive
-- 6. 预设路径：fix（bug + 调整两种模式）
-- 7. 状态文件：.comate.yaml
-- 8. 决策阻塞点
-- 9. 关键协议
-- 10. CLI 命令参考（comate.sh）
-- 11. 故障排除
-- 12. 文件结构
+## 1. 命令
 
----
-
-## 1. 概述与核心概念
-
-comate 是一个 **Specification-Driven Development (SDD，规约驱动开发)** 的 AI 开发编排器，通过五阶段工作流确保每个变更都有完整的规约与设计。底层集成 **OpenSpec**（提案、规约生命周期、归档）和 **Superpowers**（技术设计、规划、执行、收尾），并提供 PRD 门禁、决策澄清、知识库对接等编排能力。
-### 1.1 核心原则
-
-**头脑风暴是强制性的。每个变更都必须经过深度设计（fix 预设除外）。**
-
-### 1.2 五阶段流程
-
-```
-[原始 PRD] -> /comate-gate -┐  (阶段 0：门禁 + 拆分)
-                              v
-/comate
-  auto-detect
-/comate-open -> /comate-design -> /comate-build -> /comate-verify -> /comate-archive
-  (OpenSpec)      (Superpowers)      (Superpowers)      (两者)            (OpenSpec)
-```
-
-流程链：(gate ->) open -> design -> build -> verify -> archive
-
-**阶段 0（可选，PRD 门禁与拆分）**：需求来自一份**原始 PRD**时，先过 `/comate-gate`：审阅 PRD 质量、百分制评分、建阻断台账，门禁通过前禁止建任何 change；通过后按依赖/整体性/独立性/规模把 PRD 拆成 1 或 N 个 change（粒度由用户定），逐个交给 `/comate-open`。门禁状态钉在 PRD 同级 `PRD-<NNN>.gate.yaml`（如 `PRD-001.gate.yaml`，机器真相源），评审报告为 `PRD-<NNN>-REVIEW.md`（如 `PRD-001-REVIEW.md`，人类可读）。PRD 通过门禁后被改会因哈希漂移自动失效（stale），需重跑 gate。需求来自对话时无需此阶段。
-
-单次 `/comate` 调用从检测到的阶段开始，当退出条件满足时推进到下一阶段。智能体会自动推进后续阶段，但必须在决策阻塞点暂停，直到收到用户确认。
-
-### 1.3 预设快捷方式
-
-- **fix**：快速小改动 —— 跳过头脑风暴（及完整计划），走 open -> build -> verify -> archive。覆盖两种模式，调用时判定：
-  - **bug 模式**：修复已有功能的错误行为。含根因消除检查，commit 前缀 `fix:`，升级阈值 3 文件
-  - **调整模式**：非 Bug 的局部优化（文本、配置、文档、提示词）。跳过根因检查，commit 前缀 `chore:`，升级阈值 5 文件
-
-### 1.3.1 工具 skill
-
-- **grill**（`/comate-grill`）：决策点穷追式澄清。对计划/设计/PRD 的模糊点做深度优先遍历，逐个决策点给推荐答案并等用户确认，直到歧义清零。不是阶段，是跨阶段可复用的工具。comate-gate 在阻断问题 > 3 或有依赖链时会提供「深度澄清」选项自动调用它；用户也可 `/comate-grill <话题>` 直接挑战自己的计划草稿。算法内化自社区 grill-me pattern，避免外部依赖漂移。
-- **kb-integration**（`/comate-kb-integration`）：第三方对接档案生成。从官方文档 URL 抓取，按 `docs/knowledge-base/integrations/_TEMPLATE/` 规范产出 `<service-id>/README.md`（长期维护的对接档案）+ `api-snapshot.md`（我方用到的接口字段摘录），并在根索引 README.md 追加一行。是知识库 integrations scaffold（comate init 铺入）的配套建档工具，只摘我方用得到的接口/字段、密钥只记位置不写值。遇 JS 动态渲染的 SPA 文档站（WebFetch 抓到空壳）自动降级 `scripts/fetch_rendered_doc.py`（Playwright 无头渲染，需 `pip install playwright && playwright install chromium`）。
-
-### 1.4 命令快速参考
-
-| 命令 | 阶段 | 归属 | 产出物 |
-|---------|-------|-------|-----------|
-| `/comate-gate` | 0. PRD 门禁与拆分 | Claude | `<PRD>.gate.yaml`, 评审报告, N 个 change |
-| `/comate-open` | 1. 启动 | OpenSpec | proposal.md, design.md, tasks.md |
-| `/comate-design` | 2. 深度设计 | Superpowers | 设计文档, delta spec |
-| `/comate-build` | 3. 规划与构建 | Superpowers | 实现计划, 代码提交 |
-| `/comate-verify` | 4. 验证与收尾 | 两者 | 验证报告, 分支处理 |
-| `/comate-archive` | 5. 归档 | OpenSpec | delta->main spec 同步, 设计文档标注, 归档 |
-| `/comate-fix` | 预设 | 两者 | 快速小改动：bug 修复 + 非 bug 调整（跳过头脑风暴） |
-| `/comate-grill` | 工具 | Claude | 决策台账（逐决策点澄清，附推荐 + 用户答案） |
-| `/comate-kb-integration` | 工具 | Claude | 第三方对接档案（从官方文档 URL 生成 integrations 目录档案 + 索引行） |
-
-此外，终端命令 `comate usage` 查看当前项目的 token 用量与估算成本（见 §2.7）。
-
----
-
-## 2. 安装与前置条件
-
-```bash
-npm install -g @house365/comate
-cd your-project && comate init
-```
-
-`init` 会装好下面 2.2–2.4 的全部内容，并铺出 `docs/` 知识库骨架（2.5）。本节余下部分用于排查：init 报某项失败时，对照确认要装什么、怎么自查。
-
-### 2.1 运行环境
-
-| 依赖 | 要求 | 检查方式 |
-|------------|-------------|-------|
-| bash | >= 3.2 | `bash --version` |
-| git | 任意现代版本 | `git --version` |
-| sha256 | `sha256sum` 或 `shasum`（至少一个） | `command -v sha256sum shasum` |
-| LF 换行符 | 所有 `.sh` 文件必须使用 LF | `bash comate/scripts/comate.sh doctor` |
-
-### 2.2 OpenSpec（WHAT 侧）
-
-处理提案/规约生命周期/归档。comate 的 open 和 archive 阶段依赖它。
+agent 通过 `node "$COMATE" <command> --json` 调用；人可以用全局的 `comate status` / `comate doctor`（转发到同一个脚本）。
 
 ```bash
-npm install -g @fission-ai/openspec@latest
-# --tools 必填：openspec 靠探测已有 agent 配置目录决定写哪些 tool 文件，
-# 干净项目里探测不到会直接报 No tools detected 退出
-cd <project-root> && openspec init . --tools none
-openspec list --json  # 验证安装
+status [<name>]                                 当前位置 + 下一步（只读）
+new <name> [--mode full|fix] [--source <file>]... [--base <branch>]
+open <name> --prepare                           校验 brief/spec，抽取验收项，生成确认摘要
+open <name> --confirm --expect <v>:confirm      用户确认后进入 build
+rename <name> <new>                             仅 open 阶段
+spec remove|restore <name> <capability>         登记 / 取消删除一个主能力
+handoff <name> --input <json> --expect <v>:<step>   提交候选实现，脚本跑检查命令
+handoff <name> --recheck --expect <v>:checking  检查被中断时重跑
+verify <name> --result <json> | --error "<原因>" | --unavailable --expect <v>:await-verifier
+probe <name> [--remove <dir>]                   反向验证用的临时 worktree（系统临时目录）
+decide <name> --expect <v>:<step>
+    --accept --finish keep|merge|pr|push
+  | --revise-implementation --note "<要改什么>"
+  | --revise-requirements [--note "<原因>"]
+  | --resolve --note "<补充信息>"
+  | --upgrade                                   fix 转 full
+archive <name> [--dry-run]
+doctor [--repair]                               健康检查；--repair 清理临时文件与残留 worktree
+import-specs [--dry-run]                        openspec/specs → comate/comate/specs
 ```
 
-comate 使用以下 OpenSpec 能力（以技能形式调用）：`openspec-explore`、`openspec-new-change`、`openspec-propose`、`openspec-verify-change`。请确认这些技能在你的平台技能目录中可用。
+退出码：`0` 成功 · `1` 被守卫拦截（输出里带最新 next 和修复方法）· `2` 用法错误 · `3` 环境缺失（非 git 仓库、未 init）· `4` 状态损坏。
 
-### 2.3 Superpowers（HOW 侧）
+## 命令说明
 
-处理技术设计/规划/执行/收尾。comate 的 design、build 和 verify 阶段依赖它。
+### 只读命令
 
-`comate init` 已用 `skills add obra/superpowers -g` 装到用户级。手动补装同理。确认以下技能可加载：
+- **status [name]**：查看当前状态和下一步。无参数时列出所有进行中的 change；有多个时提示选择。
+- **doctor [--repair]**：健康检查。`--repair` 清理临时文件与残留 worktree。
 
-- `superpowers:brainstorming`
-- `superpowers:writing-plans`
-- `superpowers:subagent-driven-development`
-- `superpowers:executing-plans`
-- `superpowers:using-git-worktrees`
-- `superpowers:finishing-a-development-branch`
+### 初始化
 
-**如果任何 Superpowers 步骤不可用，对应阶段必须停止并提示安装。不得用普通对话替代。**
+- **new <name> [--mode full|fix] [--source <file>]... [--base <branch>]**
+  - 创建新 change，默认 full 模式
+  - `--mode fix`：小修模式（bug 修复、小调整），brief 三章、免确认
+  - `--source <file>`：需求来自文件时钉住哈希，brief 会带「来源覆盖」表
+  - `--base <branch>`：指定基础分支（默认当前分支）
+  - 在 protected_branches 上会自动切到 `comate/<name>` 分支
 
-### 2.4 comate 本身
+### open 阶段
 
-comate 以 npm 包分发（`npm install -g @house365/comate`），`comate init` 通过 skills CLI 装到用户级 `~/.agents/skills`，一次装完所有项目共用，支持 Claude Code、Codex、Cursor 等 70+ agent。
+- **open <name> --prepare**：校验 brief/spec，抽取验收项 A1…An，生成确认摘要
+- **open <name> --confirm --expect <v>:confirm**：用户确认后进入 build
+- **rename <name> <new>**：重命名 change（仅 open 阶段）
+- **spec remove|restore <name> <capability>**：登记/取消删除一个主能力
 
-### 2.5 docs/ 知识库骨架（阶段 0 用）
+### build 阶段
 
-`comate init` 会在项目里铺出 `docs/` 骨架，供 `/comate-gate` 读写 PRD：
+- **handoff <name> --input <json> --expect <v>:<step>**
+  - 提交候选实现，脚本跑检查命令
+  - `<json>` 包含：summary、addressed（验收 ID 列表）、manual_checks、known_limits
+- **handoff <name> --recheck --expect <v>:checking**：检查被中断时重跑
 
-```
-docs/
-├── README.md                                   # docs 目录说明
-├── architecture/README.md                      # 架构规范占位（契约事实源，需项目自建）
-└── knowledge-base/
-    ├── README.md                               # PRD → comate 流程说明 + 命名约定
-    ├── requirements/_templates/PRD.md          # PRD 模板
-    └── integrations/_TEMPLATE/                  # 第三方对接档案模板（README + api-snapshot）
-```
+### verify 阶段
 
-- 路径与 `comate-lib.sh` 硬编码的 `comate_kb_root=docs/knowledge-base` 对齐，PRD 放 `requirements/<YYYYMMDD-功能名>/` 下。
-- **幂等且不覆盖**：逐文件跳过已存在的，重跑 `comate init` 不动你已改过的 docs。
-- `architecture/` 只给占位 README（架构内容项目专属），是 PRD 门禁「契约对齐」的事实源，需按项目实际补齐。
-- PRD 是需求入口，具体实现约束由 change 的 proposal/design/tasks 承接。
+- **verify <name> --result <json> --expect <v>:await-verifier**
+  - verifier 提交验收结果
+  - `<json>` 必须包含：token、candidate、acceptance（逐项结论）、reverse_checks、risks、summary
+- **verify <name> --error "<原因>" --expect <v>:await-verifier**
+  - verifier 崩溃/超时时报告，脚本重签 token 再派新的（≤2 次）
+- **verify <name> --unavailable --expect <v>:await-verifier**
+  - 平台无子 agent 时降级（必须有自动测试）
+- **probe <name>**：创建反向验证用的临时 worktree，返回路径
+- **probe <name> --remove <dir>**：删除临时 worktree
 
-### 2.6 comate 本身的技能布局
+### 决策点
 
-采用扁平布局——每个 phase 是顶层技能目录，而非 `comate/<phase>/` 嵌套。部分 agent（含 Claude Code）只发现顶层目录，扁平是共同可用的最小公倍数：
+- **decide <name> --expect <v>:<step> <action>**
+  - `--accept --finish keep|merge|pr|push`：接受结果并选择收尾方式
+  - `--revise-implementation --note "<要改什么>"`：回 build 修改实现
+  - `--revise-requirements [--note "<原因>"]`：需求要变，回 open 重新确认
+  - `--resolve --note "<补充信息>"`：补充信息解除 blocked 状态
+  - `--upgrade`：fix 升级为 full
 
-```
-skills/
-|-- comate/                 # 主入口 + 共享资源
-|   |-- SKILL.md
-|   |-- reference/
-|   |   |-- dirty-worktree.md
-|   |   |-- decision-points.md
-|   |   |-- prerequisites.md
-|   |-- scripts/
-|   |   |-- comate-lib.sh     # 库函数
-|   |   |-- comate.sh         # 调度器 + 状态机（单一入口）
-|   |-- tests/
-|-- comate-open/SKILL.md       # 阶段 1：启动
-|-- comate-design/SKILL.md     # 阶段 2：深度设计
-|-- comate-build/SKILL.md      # 阶段 3：规划与构建
-|-- comate-verify/SKILL.md     # 阶段 4：验证与收尾
-|-- comate-archive/SKILL.md    # 阶段 5：归档
-|-- comate-fix/SKILL.md        # 预设：快速小改动（bug + 调整）
-```
+### 归档
 
-一键健康检查：`bash comate/scripts/comate.sh doctor`
+- **archive <name> [--dry-run]**
+  - 写入主 spec、移目录、提交、执行收尾
+  - `--dry-run`：只做预检，列出将执行的步骤
+  - 中断后重跑会按证据从断点继续
 
----
+### 迁移
 
-### 2.7 Token 用量：`comate usage`
+- **import-specs [--dry-run]**：将 `openspec/specs/` 的主规格复制到 `comate/comate/specs/`
 
-终端命令，查看**当前项目**的 token 消耗与估算成本。封装 [ccusage](https://github.com/ryoppippi/ccusage)——它作为 comate 的依赖随包安装，`comate doctor` 会检测其可用性（缺失时回退 `npx ccusage@latest`）。
+## 2. next（下一步指令）
 
-```bash
-comate usage            # 本项目按会话(session)统计（默认）
-comate usage daily      # 本项目按天
-comate usage --global   # 全部项目，不做项目隔离
-comate usage codex daily            # 单看某个 agent
-comate usage --json -s 2026-08-01   # 其余参数原样透传给 ccusage
-```
-
-**项目隔离原理**：ccusage 默认全局聚合、无项目过滤。comate 在临时目录里为当前项目重建一个 scoped 配置根，用 `CLAUDE_CONFIG_DIR` + `CODEX_HOME` 指过去，命令结束即清理：
-
-- **Claude Code**：数据本就按 `~/.claude/projects/<编码 cwd>/` 分目录，硬链接本项目那一个目录的 `*.jsonl` 进 scoped 根。
-- **Codex**：数据按日期平铺（`~/.codex/sessions/YYYY/MM/DD/`），项目路径藏在每个文件的 `session_meta.cwd`，故按 `cwd` 过滤后硬链接命中的文件。
-
-用硬链接而非目录 symlink/junction：Windows 下 ccusage 的文件扫描不遍历 symlink/junction 目录，硬链接则表现为真实文件。硬链接跨盘失败时回退复制。两个 agent 的 scoped 根都会设，未命中的 agent 报 0 而非泄漏全局数据。
-
-**边界**：粒度到项目/会话级，不做 open/design/build 阶段级归因（需在状态机流转处打时间戳，属后续增强）。
+每条命令执行完都输出一个 `next` 对象，告诉 agent 当前状态和下一步该做什么。
 
----
+### 核心字段
 
-## 3. 快速开始
-
-### 3.1 基本用法
+| 字段 | 含义 |
+|---|---|
+| `disposition` | 决定 agent 如何响应：<br>• `continue` — 读 reference（首次），完成工作，执行 command<br>• `await-user` — 转述 message，用 alternatives 让用户选<br>• `blocked` — 处理 message 列出的问题，重跑 status<br>• `done` — 流程结束，报告结果 |
+| `action` | 当前动作标识（write-brief / build / dispatch-verifier / accept / archive 等） |
+| `reference` | agent 该读的文档路径（只在首次进入该阶段时读） |
+| `message` | 人话说明当前状态和下一步 |
+| `command` | 要执行的命令数组（`$COMATE` 会替换成脚本绝对路径） |
+| `alternatives` | `await-user` 时的互斥选项列表，每项包含 label 和 command |
+| `version` / `step` | 乐观锁版本号，用于 `--expect <version>:<step>` 防止并发冲突 |
+| `dispatch` | 派发给下游的任务包（确认摘要 / build 上下文 / verifier 派发） |
+| `template` | 要填写的 JSON 结构模板 |
+
+### disposition 决策表
+
+| disposition | agent 动作 |
+|---|---|
+| `continue` | 1. 如果是本阶段第一次，读 `reference` 文档<br>2. 完成 `message` 描述的工作<br>3. 执行 `command`（占位符 `<…>` 换成实际值） |
+| `await-user` | 1. 向用户转述 `message`（accept 时需列出 risks）<br>2. 用 AskUserQuestion 把 `alternatives` 作为选项<br>3. 用户选哪个就执行哪个的 `command` |
+| `blocked` | 1. 处理 `message` 或 `warnings` 列出的问题<br>2. 处理完后重跑 `status` 获取最新 next |
+| `done` | 向用户报告最终结果，流程结束 |
+
+### 版本控制与冲突检测
+
+- **`--expect` 参数**：用户决策类命令（decide）和 handoff 必须带 `--expect <version>:<step>`
+- **版本来源**：只能用最新 next 里的 version 和 step，不要自己拼接
+- **冲突拒绝**：脚本写状态前会校验版本，不匹配就拒绝（退出码 1）并返回最新 next
+- **作用**：防止基于过期状态操作（如用户在另一处改了文档，agent 还在用旧版本 handoff）
+
+## 3. 状态机
+
+comate 状态机管理整个开发流程，状态存储在 `state.json` 中，由脚本原子写入（写前复核 version）。
+
+### 节点与转换
+
+| 节点 | phase / step | 如何离开 | 说明 |
+|---|---|---|---|
+| **Drafting** | open / drafting | `open --prepare` | 起草 brief 和 spec（fix 模式直接进 Building） |
+| **AwaitConfirm** | open / confirm | `open --confirm` | 等待用户确认验收项和范围 |
+| **Building** | build / building | `handoff` | 首轮实现 |
+| **Repairing** | build / repairing | `handoff` | 验收失败后的修复轮 |
+| **Checking** | verify / checking | 自动 | 脚本执行检查命令，通过进 AwaitVerifier，失败回 Repairing/Stuck |
+| **AwaitVerifier** | verify / await-verifier | `verify --result/error/unavailable` | 等待独立 verifier 提交验收结果 |
+| **AwaitAccept** | verify / accept | `decide --accept/revise-*` | 验收全通过，等待用户接受并选收尾方式 |
+| **Stuck** | verify / stuck | `decide --revise-*` | 失败达上限或连续 3 轮无进展 |
+| **Blocked** | verify / blocked | `decide --resolve` | 验收被阻塞（缺外部信息） |
+| **Degraded** | verify / degraded | `decide --accept` | 降级验收（无独立 verifier，只有自动测试） |
+| **ArchiveReady** | archive / ready | `archive` | 准备归档 |
+| **Done** | archive / done | — | 流程完成 |
+
+### 关键机制
+
+**进展判断**
+- 本轮未通过的验收项是上轮的严格子集 = 有进展
+- 连续 2 轮无进展时，next 提示换思路
+- 连续 3 轮无进展或失败达 `max_verify_failures`（默认 5）→ Stuck
+
+**候选锁定**
+- handoff 时实现必须已提交，HEAD 的 commit sha 即候选 ID
+- 验收期间 HEAD 变化 → 结果作废，计一次失败，回 Repairing
+
+**文档冻结**
+- 确认后，brief、spec、登记的删除、源文件都记录哈希
+- 后续阶段发现改动 → 拒绝，必须 `decide --revise-requirements` 回 open 重新确认
+
+**工作区要求**
+- handoff、verify 和 archive 时，change 目录外必须干净（无未提交改动）
+- 保证验收的是实际提交的实现，不含临时改动
+
+## 4. 产物与验收
+
+### change 目录结构
 
 ```
-/comate add pagination to user management page
-/comate fix login page password mask not showing after input
-/comate change button text from 'Submit' to 'Confirm'
+comate/comate/changes/<name>/
+  state.json           唯一真相源，只由脚本写（原子替换，写前复核 version）
+  brief.md             agent 写：目标、范围、非目标、验收示例、约束与不变量、决定、待决问题
+  specs/<cap>/spec.md  agent 写：归档后的完整行为（Requirement + Scenario WHEN/THEN）
+  verification.md      脚本从 state.json 生成，记录每轮验收结果
 ```
 
-### 3.2 自动检测逻辑
-
-当 `/comate` 被调用时，智能体按以下顺序检测当前阶段：
-
-**步骤 0：活动变更发现 + 意图检测**
-
-1. 先检测预设：如果 fix 条件匹配（bug 修复或非 bug 小调整），直接调用 `/comate-fix`。
-2. 无预设匹配：运行 `openspec list --json` 获取所有活动变更。
-
-| 活动变更 | 用户输入 | 行为 |
-|---------------|------------|------|
-| 无 | 非预设输入 | 调用 `/comate-open` |
-| 恰好 1 个 | `/comate <描述>` | 询问：继续此变更还是创建新变更 |
-| 多个 | `/comate <描述>` | 询问：继续现有还是创建新变更；如继续，列出供选择 |
-| 恰好 1 个 | `/comate` 无描述 | 自动选择，进入步骤 1 |
-| 多个 | `/comate` 无描述 | 列出变更供用户选择 |
-
-> 当用户选择"创建新变更"时，必须调用 `/comate-open`。不要直接调用 `/opsx:new`。`/comate-open` 执行双重初始化：OpenSpec 产出物（通过内部 `/opsx:new`）+ `.comate.yaml` 状态文件。
-
-**步骤 1：读取 `.comate.yaml` 状态元数据**
-
-优先读取 `openspec/changes/<name>/.comate.yaml`。当不可用时，回退到 `openspec status --change "<name>" --json`、`tasks.md`、`docs/superpowers/` 文件检查。
-
-**步骤 2：阶段判定**（按顺序检查，首次匹配即生效）
-
-1. `archived: true` 或变更已在归档中 -> 流程完成
-2. `verify_result: pass` 且 `archived` 不为 `true` -> 调用 `/comate-archive`
-3. `verify_result: fail` -> 验证失败决策阻塞点（决策点 4）
-4. `phase: verify` -> 调用 `/comate-verify`。`tasks.md` 全部勾选不能单独触发 verify；从 verify-fail 回到 build 后必须按 build 路由继续修复。
-5. `phase: build` 或有设计文档但计划/执行不完整 -> 按工作流路由
-6. `phase: design` 或有变更但无设计文档 -> 调用 `/comate-design`
-7. `phase: open` 或有活动变更但 `.comate.yaml` 缺失 -> 调用 `/comate-open`
-8. 无活动变更 -> 调用 `/comate-open`
-
-### 3.3 预设升级条件
-
-**fix（bug 模式）-> full**（任意匹配即触发升级）：变更 >= 3 个文件 / 架构变更（新模块、新接口、新依赖）/ 数据库 schema 变更 / 新增公共 API / 范围超出单一功能模块。
-
-**fix（调整模式）-> full**（任意匹配即触发升级）：变更 >= 5 个文件 / 跨模块协调 / 需要 >= 5 个新测试用例 / 配置项新增/删除（非值变更）/ 需新增能力 / 需 delta spec。
-
-### 3.4 错误处理快速参考
-
-| 场景 | 处理方式 |
-|----------|----------|
-| `openspec list --json` 失败 | 检查 openspec 安装，提示 `openspec init . --tools none` |
-| 子技能不可用 | 停止流程，提示运行 `comate init` 补装 |
-| `.comate.yaml` 损坏或缺失 | 以文件状态为真相源，用 `state set` 修复后继续 |
-| 构建/测试失败 | 回到 build 阶段修复，不要进入 verify |
-| 变更目录结构不完整 | 按 comate-open 产出物要求补全缺失文件 |
-
----
-## 4. 命令参考：/comate 主命令
-
-### 4.1 自动检测与连续执行
-
-单次 `/comate` 调用从检测到的阶段开始，当退出条件满足时推进到下一阶段。智能体会自动推进后续阶段，但必须在决策阻塞点暂停，直到收到用户确认。自动推进仅适用于非决策型流程转换。
-
-### 4.2 断点恢复规则
-
-- 每次上下文恢复时，重新运行步骤 0 和步骤 1。不要信任对话历史来进行阶段检测。
-- 当存在活动变更且工作树有未提交更改时，遵循 `comate/reference/dirty-worktree.md` 协议。
-- 如果 `phase: build`，检查 `build_mode` 和 `isolation` 是否已设置；如有任一未设置，返回 `/comate-build` 完成；如两者均已设置，读取 tasks.md 找下一个未完成的任务。
-- 如果 `phase: verify` 且 `verify_result: fail`，进入验证失败决策点（决策点 4）。
-- 如果 `phase: open` 但 proposal/design/tasks 已完成，运行 `bash $COMATE guard <name> open --apply` 修复状态，然后继续检测。
-- 如果 `phase: archive`，只调用 `/comate-archive`。成功归档后，变更移至 archive 目录。不要对旧的活动目录运行 guard。
-
-### 4.3 脚本位置（单一入口）
-
-comate 收敛到一个调度器：`comate/scripts/comate.sh`。技能只需定位此脚本并缓存到 `$COMATE`：
-
-```bash
-COMATE="${COMATE:-$(for r in . ./.claude/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/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
+### 验收项来源
+
+验收项（A1、A2…）从以下来源抽取：
+
+1. **brief.md 的「验收示例」章节**：每个列表项（`- `）算一项
+2. **spec.md 的 Scenario**：每个 `### Scenario:` 算一项
+3. **被删除的 Scenario**：每个从现有主 spec 删除的 Scenario 算一项，verifier 必须确认行为已移除或按迁移规则处理
+
+抽取规则：
+- brief 按出现顺序编号：A1、A2…
+- spec 按文件路径字典序 + 章节顺序编号，接在 brief 之后
+- 修改已有能力时，与主 spec 完全一致的 Scenario 标为 `regression`（已有测试须通过），其余标 `changed`（逐项细验）
+
+### 主规格写入
+
+归档时每个能力按以下三种操作之一写入 `comate/comate/specs/`：
+
+| 操作 | 条件 | 行为 |
+|---|---|---|
+| `create` | 主 spec 不存在 | 直接写入 |
+| `replace` | 主 spec 存在且哈希等于确认时的基线 | 覆盖写入 |
+| `remove` | 显式通过 `spec remove` 登记 | 删除主 spec 文件 |
+
+**不做 delta 合并**：归档的 spec 是完整行为，不是增量。如果基线不符（别的 change 先改了同一能力），拒绝归档，要求：
+1. rebase 当前分支
+2. 重读最新主 spec
+3. 修改本 change 的 spec
+4. `decide --revise-requirements` 重新确认
+
+## 5. 配置 `comate/comate/config.json`
+
+| 字段 | 默认值 | 说明 |
+|---|---|---|
+| `build_command` | `null` | 构建命令。字符串、命令对象或它们组成的数组；`null` 自动探测（npm / Maven / Cargo / Go）；`"none"` 表示确实没有 |
+| `verify_command` | `null` | 验收检查命令。同上。命令对象为 `{ "cmd": "<命令>", "kind": "test" \| "check" }`。handoff 需要配置、探测成功或显式写 `"none"`；降级验收另需成功执行的 test 类型检查 |
+| `check_timeout_seconds` | `900` | 单条检查命令的超时时间（秒） |
+| `max_verify_failures` | `5` | 验收失败次数上限，到达后转 Stuck 状态 |
+| `finish` | `"ask"` | 收尾模式。`"ask"` 每次都停下问用户；`"auto"` 全部通过且无 risks 时自动归档 |
+| `auto_finish_action` | `null` | `finish: auto` 时的收尾方式。`null` 或 `"keep"` 只本地归档；`"merge"` / `"push"` / `"pr"` 需显式配置 |
+| `protected_branches` | `["main","master"]` | 受保护分支列表。`new` 在这些分支上执行时自动切到 `comate/<name>` 分支 |
+
+**配置示例**
+
+```json
+{
+  "build_command": "npm run build",
+  "verify_command": "npm test",
+  "check_timeout_seconds": 600,
+  "max_verify_failures": 3,
+  "finish": "auto",
+  "auto_finish_action": "keep",
+  "protected_branches": ["main", "master", "develop"]
+}
 ```
 
-然后全程复用 `$COMATE`：
-
-```bash
-bash "$COMATE" state   <name> init <full|fix>     # 初始化 .comate.yaml
-bash "$COMATE" state   <name> transition <event>           # 执行状态转换
-bash "$COMATE" state   <name> check <phase> [--json]       # 检查阶段进入条件
-bash "$COMATE" state   <name> recover <phase>              # 从文件状态推断修复 .comate.yaml
-bash "$COMATE" state   <name> scale                        # 评估变更规模
-bash "$COMATE" state   <name> validate                     # 验证 .comate.yaml 完整性
-bash "$COMATE" guard   <name> <phase> [--apply] [--json]   # 阶段门禁
-bash "$COMATE" handoff <name> <design|build> --write [--full]  # 生成交接包
-bash "$COMATE" archive <name> [--dry-run]                  # 执行归档
-bash "$COMATE" status
-bash "$COMATE" doctor
-```
-
-`guard --apply` 在检查通过后委托给 `state transition`。退出码约定：`0` 通过 / `1` 验证阻塞 / `2` 用法错误 / `3` 环境缺失 / `4` 状态文件损坏。
-
----
-
-## 5. 阶段详解
-
-### 5.1 阶段 1：启动（/comate-open）
-
-**归属**：OpenSpec
-**触发条件**：无活动变更，或用户明确要求新变更
-**产出物**：proposal.md, design.md, tasks.md, `.comate.yaml`
-
-**步骤**：
-
-1. **理解意图**：如果提供了用户描述则遵循；否则通过 2-3 轮对话澄清，建立意图、功能边界和验收标准。
-2. **探索现有能力**：调用 `openspec-explore` 探索现有能力和规约状态。
-3. **创建变更目录**：调用 `openspec-new-change`（内部 `/opsx:new`）生成 proposal.md、design.md、tasks.md 骨架，**并立即写入 `.comate.yaml`**。
-4. **提案审核**：调用 `openspec-propose` 充实 proposal、design、tasks。
-5. **产出物审核（决策点 1，按来源分类）**：proposal/design/tasks 完成且内容全面后先按来源分类——**PRD 扇出且范围与 gate 映射一致**时属自动处理，完整性检查通过即自动流转并报告承接情况，不再暂停；**对话来源**或 **PRD 扇出但范围有偏差**时暂停等待用户确认或调整请求。详见 `comate/reference/decision-points.md` 第 1 条。
-6. **退出**：用户确认后，运行 `bash $COMATE guard <name> open --apply` 进行验证并自动推进到 design。
-
-### 5.2 阶段 2：深度设计（/comate-design）
-
-**归属**：Superpowers
-**触发条件**：活动变更已存在（proposal/design/tasks 已完成），但尚无设计文档
-**产出物**：设计文档（`docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`）、delta spec
-
-**步骤**：
-
-1. **加载输入**：读取 proposal.md、design.md、tasks.md、delta spec（如存在）。从 `.comate.yaml` 获取交接上下文（如有）。
-2. **头脑风暴（强制）**：调用 `superpowers:brainstorming` 产出技术方案。在头脑风暴之前不要创建最终设计文档。
-3. **方案确认（决策点 2）**：头脑风暴产出技术方案后，暂停让用户确认方案方法、关键权衡、测试策略、Spec Patch。在确认之前不要创建设计文档、写 `design_doc`、运行设计 guard 或进入 build。
-4. **创建设计文档**：确认后，在 `docs/superpowers/specs/` 下创建设计文档。
-5. **更新 delta spec**：如果头脑风暴产出了 spec 变更，同步到 delta spec。
-6. **写入交接包**：运行 `bash $COMATE handoff <name> design --write`
-7. **退出**：运行 `bash $COMATE guard <name> design --apply`，通过后自动推进到 build。
-
-### 5.3 阶段 3：规划与构建（/comate-build）
-
-**归属**：Superpowers
-**触发条件**：设计文档已创建，但计划/执行不完整
-**产出物**：实现计划（`docs/superpowers/plans/YYYY-MM-DD-<feature>.md`）、代码提交
-
-**步骤**：
-
-1. **加载输入**：读取设计文档、delta spec、tasks.md、交接包（如有）。
-2. **生成实现计划**：调用 `superpowers:writing-plans` 将设计文档转换为可执行的任务和步骤。将修正同步到 tasks.md。
-3. **构建模式选择（决策点 3）**：执行前，一次性询问工作空间隔离方式（branch/worktree）和执行模式（subagent-driven-development/executing-plans）。在一次交互中获取两个选择。
-4. **规模评估**：运行 `bash $COMATE state <name> scale` 评估变更规模并写入 `verify_mode`。
-5. **执行实现**：按选定模式执行。构建过程中，delta spec 可能随任务进展被修改。
-6. **范围扩展（决策点 7）**：如果实现过程揭示需要重新设计或拆分为新变更，暂停。判定标准：基于初始 tasks.md 任务数，新增任务超过总数一半（50% 阈值）视为超出范围。询问用户是否拆分。
-7. **写入交接包**：运行 `bash $COMATE handoff <name> build --write`
-8. **退出**：运行 `bash $COMATE guard <name> build --apply`，通过后自动推进到 verify。
-
-### 5.4 阶段 4：验证与收尾（/comate-verify）
-
-**归属**：两者
-**触发条件**：代码已提交，所有 tasks.md 任务已完成
-**产出物**：验证报告、分支处理
-
-**步骤**：
+**自动探测规则**
 
-1. **进入验证与分类**：检查脏工作树，运行 guard，运行构建/测试命令。将失败分类为 SPEC、REGRESSION、COVERAGE、SECURITY、STYLE、OTHER。
-2. **验证失败决策（决策点 4）**：验证失败时，暂停让用户决定：全部修复 / 逐项处理 / 接受偏差。包括 Spec 漂移处理（设计文档与 delta spec 冲突）。CRITICAL 级别的失败必须修复。仅在用户选择修复后才执行 `state transition <name> verify-fail` 并返回 build。
-3. **验证通过**：全部通过或用户接受偏差后，写入 `verify_result: pass`，将验证报告路径写入 `verification_report`。
-4. **分支收尾（决策点 5）**：调用 `superpowers:finishing-a-development-branch`。暂停让用户选择：本地合并 / 推送为 PR / 保留分支 / 丢弃工作。前三项完成后写 `branch_status: handled`；丢弃写 `branch_status: discarded` 并停止，不得验证通过或归档。
-5. **退出**：运行 `bash $COMATE guard <name> verify --apply`，通过后自动推进到 archive。
+当 `build_command` 或 `verify_command` 为 `null` 时，脚本按以下顺序探测：
 
-### 5.5 阶段 5：归档（/comate-archive）
+1. **npm**：存在 `package.json` 且有 `scripts.build` / `scripts.test`
+2. **Maven**：存在 `pom.xml` → `mvn package` / `mvn test`
+3. **Cargo**：存在 `Cargo.toml` → `cargo build` / `cargo test`
+4. **Go**：存在 `go.mod` → `go build ./...` / `go test ./...`
 
-**归属**：OpenSpec
-**触发条件**：验证已通过，分支已处理
-**产出物**：delta->main spec 同步、设计文档标注、变更移至归档
+确实没有构建或测试命令时，显式配置为 `"none"`，否则 handoff 会被拦截。
 
-**路径迁移**：change 目录从 `openspec/changes/<name>/` 移到 `openspec/changes/archive/YYYY-MM-DD-<name>/`。归档脚本会同步修正失效引用：
-- 归档后 `.comate.yaml` 中随目录移动的自指字段（`source_manifest` / `handoff_context` / `impl_context`）重写为归档路径，确保 `sources <name> check/list` 对归档 change 仍可用；
-- 设计文档 / plan 正文中指向旧 `openspec/changes/<name>/` 的引用重写为归档路径，并在 frontmatter 留 `archived-with` 面包屑；
-- `design_doc` / `plan` 字段本身指向 `docs/superpowers/`，该目录不移动，保持不变。
+降级验收会识别 Node `--test`、Jest、Vitest、Mocha、AVA、pytest、Maven/Cargo/Go 测试入口，并展开引用的 npm 脚本及生命周期钩子。未知自定义测试需显式配置，例如 `"verify_command": { "cmd": "node tools/run-tests.js", "kind": "test" }`。纯编译、语法检查、只列举/跳过测试或掩盖失败的已知命令即使声明为 test，也不能作为降级依据；编译后实际运行测试的命令链仍可识别为测试。
 
-**步骤**：
+npm 支持普通 `test` / `run` / `run-script`、完整脚本名、常见静默参数及嵌套脚本。无法解析的 npm 调用和跨包的 `--prefix` / `--workspace` / `-w` 形式不能支持降级，须使用独立 verifier。降级命令链使用 `&&` 保留失败退出码；独立管道、分号或单个 `&` 分隔的命令链不作为测试依据。命令分类不是通用 shell 解释器，也不证明自定义脚本的断言质量。
 
-1. **加载输入**：读取 delta spec、设计文档、tasks.md、验证报告。
-2. **同步 spec**：对每个 delta spec 能力，调用 `openspec-verify-change`，通过后合并到 main spec。
-3. **更新设计文档**：在设计文档末尾追加实现摘要（实际实现差异、关键决策、验证结果）。
-4. **执行归档**：运行 `bash $COMATE archive <name> --dry-run` 预览，如无问题则运行正式归档。
-5. **退出**：运行 `bash $COMATE guard <name> archive --apply`，通过后变更移至 archive 目录。
+确认时保存命令类型和引用的 npm 脚本定义，降级时与候选执行计划及当前计划比较。空计划也参与比较；计划变化或旧状态缺少完整计划时，需要 `decide --revise-requirements` 重新确认，或使用独立 verifier。允许修改实现和测试源码，但命令声明不能替代逐项行为证据。
 
----
-## 6. 预设路径：fix
+## 6. 故障排除
 
-### 6.1 概述
+| 现象 | 原因 | 处理方法 |
+|---|---|---|
+| `status` 显示 `resolve-drift` | 确认后的文档或源文件被改动 | • 误改：`git checkout -- <文件>` 还原<br>• 需求要变：`decide --revise-requirements` 回 open |
+| handoff 被拦「未提交改动」 | 实现代码或测试未提交 | 提交实现和测试后重新 handoff（change 目录内的 state.json 除外） |
+| handoff 被拦「addressed 未覆盖验收项」 | handoff 没有列出本轮要求覆盖的验收 ID | 在 handoff JSON 的 `addressed` 中补齐 ID；修复轮至少覆盖上一轮未通过项 |
+| handoff 被拦「没有配置 verify_command」 | config.json 缺测试命令配置 | • 有测试：在 config.json 写 `"verify_command": "<命令>"`<br>• 确实没有：写 `"verify_command": "none"` |
+| verify 被拦「token 不匹配」 | 结果来自旧的派发 | 用最新 next 的 dispatch.token 重新派 verifier |
+| verify 被拦「工作区不干净」 | handoff 后有未提交的改动 | 提交或清理未提交的改动（verifier 必须只读主工作区） |
+| verify 被拦「HEAD 变了」 | 验收期间又提交了代码 | 结果作废，重新 handoff。避免在验收期间修改代码 |
+| archive 被拦「基线不符」 | 主 spec 在确认后被别的 change 改过 | 1. rebase 当前分支<br>2. 重读最新主 spec<br>3. 修改本 change 的 spec<br>4. `decide --revise-requirements` 重新确认 |
+| archive 被拦「验收后又提交了」 | 验收通过后改了 change 目录外的代码 | `decide --revise-implementation` 重新验收 |
+| archive 中途失败 | 写主 spec、移目录、提交或收尾某步失败 | 修复失败原因后重跑 `archive <name>`，脚本按证据从断点继续 |
+| 收尾失败（merge/push/pr） | 无 origin、无 gh、目标 worktree 不干净、冲突 | • next 为 `retry-finish`：按提示处理后重跑 `archive`<br>• 放弃该收尾：执行 alternatives 里的「改为保留分支」 |
+| 退出码 4（状态损坏） | state.json 格式错误或字段缺失 | 1. 运行 `comate doctor` 查看详情<br>2. 从 git 历史恢复：`git checkout -- <state.json 路径>`<br>3. 不要手动编辑 state.json 字段 |
+| 发现 0.x 的 `.comate.yaml` | 旧版 change 残留 | 用 comate 0.10.x 完成旧 change；主规格用 `comate import-specs` 迁移 |
 
-**适用场景**：快速小改动，跳过头脑风暴（及完整计划）。覆盖两种模式，调用时判定「是不是 bug」。
-**流程**：open -> build -> verify -> archive
+### 常见陷阱
 
-| 模式 | 触发 | 独有步骤 | commit 前缀 | 升级阈值 |
-|------|------|----------|-------------|----------|
-| **bug 模式** | 修复已有功能的错误行为 | 根因消除检查 | `fix:` | 改动 **3+ 文件** |
-| **调整模式** | 非 bug 的局部优化（文案/配置/文档/prompt） | 无 | `chore:` | 改动 **5+ 文件** |
-
-### 6.2 触发条件（两种模式共通，全部必须满足）
-
-- 不新增 capability
-- 不涉及接口变更或架构调整
-- 改动范围可预估（bug 模式通常 ≤ 2 文件；调整模式通常 ≤ 3 tasks、≤ 4 文件）
-
-### 6.3 升级条件（fix -> full）
-
-**bug 模式**（任意匹配即触发升级）：
-
-| 条件 | 说明 |
-|------|------|
-| 改动 **3+ 文件** | 超出单点修复 |
-| 架构变更 | 新模块、新接口、新依赖 |
-| 数据库 schema 变更 | 结构性调整 |
-| 引入新 public API | 修复产生新对外接口 |
-| 范围超出单一函数/模块 | 需多处协调 |
-
-**调整模式**（任意匹配即触发升级）：
-
-| 条件 | 说明 |
-|------|------|
-| 改动 **5+ 文件** | 超出小改动 |
-| 多模块协调 | 跨组件协调 |
-| 需新增 **5+** 测试用例 | 复杂度上升 |
-| 配置项增删 | 非值修改的配置变更 |
-| 需新增 capability | 超出局部优化 |
-| 需 delta spec | 影响已有规格 |
-
-提问前写 `phase_step: fix.upgrade-awaiting`。用户确认后执行 `state transition <name> fix-upgrade`，原子清理 fix 默认值并进入 design。
-
----
-
-## 7. 状态文件：.comate.yaml
-
-状态文件是扁平的 `key: value` 子集（无嵌套/列表/多行）。完整字段模板见 `comate/scripts/comate-lib.sh` 中的 `FIELD_ORDER`。
-
-**关键字段**：
-
-| 字段 | 含义 |
-|-------|---------|
-| `schema_version` | 状态文件格式版本（当前：1） |
-| `workflow` | `full` / `fix` |
-| `phase` | `open` / `design` / `build` / `verify` / `archive` |
-| `phase_step` / `phase_step_data` | 当前阶段内的恢复标记和附加数据；阶段转换时自动清空 |
-| `build_mode` | `subagent-driven-development` / `executing-plans` / `direct` |
-| `isolation` | `branch` / `worktree`（必须在 build->verify 之前设置） |
-| `verify_mode` | `light` / `full`（由规模评估写入） |
-| `verify_result` | `pending` / `pass` / `fail` |
-| `verification_report` | 验证报告路径，在 verify-pass 前必须指向真实文件 |
-| `branch_status` | `pending` / `handled` / `discarded` |
-| `handoff_context` / `handoff_hash` | 设计交接包路径 + 源文件 sha256 |
-| `impl_context` / `impl_hash` | 构建交接包路径 + plan+tasks sha256 |
-| `direct_override` | 对于使用 `direct` 的 full 流程必须显式为 `true` |
-| `base_ref` / `base_branch` | 初始化时记录的 HEAD + 检测到的默认分支 |
-| `source_kind` / `source_manifest` | 需求来源类型（`conversation` / `file`）+ 知识库源文件清单路径（防漂移） |
-| `build_command` / `verify_command` | 可选，项目构建/验证命令 |
-
-**状态机硬约束（guard + state transition 双重执行）**：
-- `build -> verify`：`isolation` 必须为 `branch` 或 `worktree`
-- `build -> verify`：`build_mode` 必须已设置
-- `build_mode: direct` 默认仅用于 fix；full 流程需要 `direct_override: true`
-- `verify -> archive`：`verification_report` 指向真实文件，`branch_status: handled`，`impl_hash` 与当前 plan+tasks 匹配
-
----
-
-## 8. 决策阻塞点
-
-**通用规则**：决策点是阻塞点。到达时，当前 `/comate` 调用必须停止并使用 AskUserQuestion 工具等待用户选择。只有在用户做出明确选择后，才能写入相应状态字段并继续执行。
-
-- 文本输出不能替代基于工具的等待
-- 不要用推荐规则、默认值或历史偏好替代用户确认
-- 其他无歧义的阶段转换必须自动推进
-
-### 七大决策点
-
-**1. 启动产出物审核**（open）：proposal/design/tasks 完成且内容全面后，暂停等待用户确认或调整请求。
-
-**2. 设计方案确认**（design/头脑风暴）：头脑风暴产出技术方案后，暂停让用户确认方案方法、关键权衡、测试策略、Spec Patch。在确认之前不要创建设计文档、写 design_doc、运行设计 guard 或进入 build。
-
-**3. 构建模式选择**（build）：执行前，一次性询问工作空间隔离方式（branch/worktree）和执行模式（subagent-driven-development/executing-plans）。在一次交互中获取两个选择。
-
-**4. 验证失败决策**（verify）：验证失败时，暂停让用户决定：全部修复 / 逐项处理 / 接受偏差。包括 Spec 漂移处理（设计文档与 delta spec 冲突）。CRITICAL 级别的失败必须修复。仅在用户选择修复后才执行 `state transition <name> verify-fail` 并返回 build。
-
-**5. 分支收尾选择**（verify/收尾开发分支）：暂停让用户选择：本地合并 / 推送为 PR / 保留分支 / 丢弃工作。前三项成功后写 `handled`；丢弃写 `discarded` 并终止当前流程。
-
-**6. 预设升级确认**（fix -> full）：当升级条件满足时，先写 `fix.upgrade-awaiting` 再暂停确认。确认后执行 `state transition <name> fix-upgrade`，由脚本清理 fix 默认构建选项并进入 design。
-
-**7. 构建范围扩展**（build）：如果实现过程揭示需要重新设计或拆分为新变更，暂停。判定标准：基于初始 tasks.md 任务数，新增任务超过总数一半（50% 阈值）视为超出范围。询问用户是否拆分。中等规模（接口变更、新组件）：确认后加载 `superpowers:brainstorming` 更新设计。大规模（新能力）：确认后使用 `/comate-open` 创建独立变更。
-
-### 红线警示
-
-| 智能体想法 | 实际风险 |
-|--------------|---------|
-| "用户大概会同意这个方案" | 绝不替用户决定 - 使用 AskUserQuestion |
-| "这只是个小改动，不需要确认" | 决策点没有规模豁免 - 阻塞点必须等待 |
-| "用户上次选了 A，这次也选 A" | 历史偏好不能替代当前确认 |
-| "我已经解释了计划，用户没反对" | 不反对 != 同意 - 必须通过工具获取明确选择 |
-| "都做到这一步了，应该没问题" | 验证未通过 != 通过 - 检查 verify_result |
-
----
-
-## 9. 关键协议
-
-### 9.1 脏工作树协议
-
-**规范路径**：`comate/reference/dirty-worktree.md`
-
-所有涉及代码变更的 comate 子技能共享此协议。当智能体恢复上下文或继续执行时，必须按此协议处理未提交的工作树变更。
-
-**核心规则**：
-- 用户可能不会说明他们改了什么。只要存在脏工作树（包括 git status 中的 `??` 文件），就假定变更可能来自用户或混合来源。
-- 脏工作树仅代表代码事实；它不会自动推进 `.comate.yaml` 的 `phase` 或勾选 `tasks.md`。
-
-**归属分类**：
-
-1. **属于当前变更**：文件和内容与当前变更目标/tasks.md/plan/delta spec 匹配。纳入当前任务，不要重复做相同的工作。
-2. **不属于当前变更**：文件或内容与当前目标无关。暂停并询问用户：合并到当前变更、拆分为新变更、保持现状，或明确授权丢弃。
-3. **来源不确定**：无法从 diff 和文档确定归属。暂停并向用户报告文件列表和判定依据。不要推进阶段。
-
-**常见处理模式**：
-- 已实现但 tasks.md 未勾选：先验证实现（运行构建和测试），通过后勾选任务。不要仅因为任务未勾选就重做。
-- 隐含的计划或范围已变化：按当前子技能的升级、增量更新或回滚规则处理。
-- open/design 阶段的代码变更：先按协议归属。不要将代码变更视为已完成实现并推进到 verify。
-
-**禁止事项**：
-- 在未理解脏 diff 来源的情况下，不要覆盖、回滚、格式化重写或忽略用户变更
-- 在脏 diff 未得到解释的情况下，不要判定验证通过
-
-### 9.2 最佳实践
-
-1. 头脑风暴是强制性的（fix 除外）
-2. Delta spec 是活文档，构建期间可修改，归档时同步
-3. 交接包由脚本生成（`handoff`），guard 验证来源/hash/mode
-4. tasks.md 实时同步，每完成一个任务就勾选并提交
-5. 仅在验证通过后归档
-6. 预设有其边界；条件满足时及时升级到 full
-
----
-## 10. CLI 命令参考（comate.sh）
-
-`comate.sh` 是 comate 状态机和工具的单一入口。所有子命令：`bash comate/scripts/comate.sh <子命令>`
-
-### state - 状态机操作
-
-| 命令 | 描述 |
-|---------|-------------|
-| `state <name> init <full|fix>` | 初始化 `.comate.yaml` |
-| `state <name> set <key> <value>` | 设置单个状态字段 |
-| `state <name> get <key>` | 读取单个状态字段 |
-| `state <name> transition <event>` | 执行状态转换 |
-| `dependency <name> archived` | 严格检查指定 change 已归档且状态为 `archived: true` |
-| `state <name> check <phase> [--json]` | 检查阶段进入条件 |
-| `state <name> recover <phase>` | 从文件状态推断并修复 `.comate.yaml` |
-| `state <name> scale` | 评估变更规模并写入 `verify_mode` |
-| `state <name> validate` | 验证 `.comate.yaml` 完整性 |
-
-### guard - 阶段门禁
-
-| 命令 | 描述 |
-|---------|-------------|
-| `guard <name> <phase> [--apply] [--json]` | 检查阶段退出条件。`--apply` 在通过时自动执行转换。 |
-
-### handoff - 交接包
-
-| 命令 | 描述 |
-|---------|-------------|
-| `handoff <name> design --write [--full]` | 生成设计交接包 |
-| `handoff <name> build --write [--full]` | 生成构建交接包（包含 plan+tasks sha256） |
-
-### sources - 源文件追踪
-
-仅追踪 `docs/knowledge-base/` 范围内的文件，钉住每个文件当时的 sha256 与 commit ref，支持双向排查。
-
-| 命令 | 描述 |
-|---------|-------------|
-| `sources <name> track <file...> [--note <text>]` | 追踪知识库源文件；成功后 `source_kind` 改为 `file`，越界文件跳过 |
-| `sources <name> check` | 漂移检查（`conversation` 跳过）；退出码 0=未漂移 / 1=漂移 / 4=manifest 损坏 |
-| `sources <name> list` | 打印源文件清单（路径/sha256/ref/note） |
-| `sources find <file>` | 反查：列出引用该文件的全部 change |
-
-清单文件位于 `openspec/changes/<name>/.comate/sources.manifest`，随 change 进版本库、随归档保留。design 与 build 阶段 guard 会复算知识库文件哈希、与清单比对，漂移则阻塞。
-
-### gate - PRD 门禁（阶段 0）
-
-对**原始 PRD** 做质量门禁，通过前禁止从该 PRD 建 change。状态钉在 PRD 同级 `PRD-<NNN>.gate.yaml`（如 `PRD-001.gate.yaml`，独立于 change 的 `.comate.yaml`），评审报告为 `PRD-<NNN>-REVIEW.md`（如 `PRD-001-REVIEW.md`）。由 `/comate-gate` 驱动。
-
-| 命令 | 描述 |
-|---------|-------------|
-| `gate <prd> review` | 建/刷新 gate.yaml，钉当前 PRD sha256，回显评审报告路径。PRD 变了则状态重置为 `reviewing` |
-| `gate <prd> set <field> <value>` | 写字段：`score` / `blocking_open` / `gate_status` 等 |
-| `gate <prd> pass [--tbd]` | 校验评分、拆分映射和报告。普通 pass 要求 `blocking_open=0`；`--tbd` 要求至少一个经用户接受的未解决阻断项 |
-| `gate <prd> spawned <change>` | 校验 change 属于确认映射、gate 未 stale、open 骨架与 PRD 源追踪完整后，记录据此 PRD 扇出的 change（逗号拼接，幂等） |
-| `gate <prd> fanout-status [--json]` | 对比 `changes_map` 与 `spawned_changes`，输出 expected/spawned/complete/missing/invalid，用于多 change 中断恢复与完整性校验 |
-| `gate <prd> status [--json]` | 查状态；哈希漂移时自动判 `stale`（不改文件） |
-| `gate <prd> check` | comate-open 建 change 前的前置守卫。PASS 要求 gate 存在、状态 ∈ {passed, passed-with-tbd}、哈希未漂移；否则退出码 1 阻塞 |
-
-`gate_status` 取值：`reviewing`（审阅中）/ `blocked`（有未关闭阻断项）/ `passed`（阻断清零，可扇出）/ `passed-with-tbd`（用户授权带 TBD，change 需标 ⚠）/ `stale`（PRD 通过后被改，须重过门禁）。退出码契约同 guard：0 通过 / 1 阻塞 / 2 用法 / 3 环境 / 4 状态损坏。
-
-### archive - 归档
-
-| 命令 | 描述 |
-|---------|-------------|
-| `archive <name> [--dry-run]` | 执行归档。`--dry-run` 用于预览。 |
-
-### 诊断
-
-| 命令 | 描述 |
-|---------|-------------|
-| `status` | 列出所有活动变更及其当前阶段 |
-| `doctor` | 环境健康检查（bash/git/sha256/LF/openspec/superpowers 等） |
-
-### 退出码约定
-
-| 码值 | 含义 |
-|------|---------|
-| 0 | 通过 |
-| 1 | 验证阻塞 |
-| 2 | 用法错误 |
-| 3 | 环境缺失 |
-| 4 | 状态文件损坏 |
-
----
-
-## 11. 故障排除
-
-### 11.1 快速诊断
-
-```bash
-bash comate/scripts/comate.sh doctor       # 环境健康检查
-bash comate/scripts/comate.sh status       # 所有活动变更状态
-```
-
-### 11.2 常见问题
-
-| 症状 | 可能原因 | 解决方案 |
-|---------|-------------|----------|
-| `/comate` 无法检测阶段 | `.comate.yaml` 缺失或损坏 | `bash "" state <name> recover <phase>` |
-| Guard 持续报告 isolation/build_mode 未设置 | 断点恢复时未填写 | 返回 build 阶段完成设置 |
-| 验证失败后无法推进 | verify_result: fail | 用户先选择修复方案，智能体执行 `state transition <name> verify-fail` 后返回 build |
-| 变更目录结构不完整 | 流程中断 | 按 comate-open 产出物要求补全 |
-| `openspec list --json` 失败 | openspec 未安装或未初始化 | 运行 `comate init`，或 `openspec init . --tools none` |
-| 子技能不可用 | Superpowers 未安装 | 运行 `comate init` 补装 |
-| bash 版本过低 | bash < 3.2 | Windows：Git Bash/WSL；macOS 自带 Bash 3.2 可直接使用 |
-| .sh 文件包含 CRLF | git 配置问题 | 仓库有 `.gitattributes` 强制 `eol=lf`；如已损坏，使用 `dos2unix` |
-| 脏工作树无法推进 | 未遵循 dirty-worktree 协议 | 按协议归属，暂停并询问用户 |
-
-### 11.3 状态修复流程
-
-1. 以文件状态为真相源：检查 proposal.md / design.md / tasks.md / delta spec / 设计文档 / 代码提交的实际状态。
-2. 运行 `bash "" state <name> recover <phase>` 从文件状态修复 `.comate.yaml`。
-3. 运行 `bash "" guard <name> <phase> --apply` 验证并自动推进。
-
----
-
-## 12. 文件结构
-
-### 12.1 技能布局
-
-```
-skills/
-|-- comate/                    # 主入口 + 共享资源
-|   |-- SKILL.md               # /comate：检测与分发
-|   |-- COMATE_MANUAL.md       # 本手册
-|   |-- reference/
-|   |   |-- decision-points.md # 决策阻塞点（单一真相源）
-|   |   |-- dirty-worktree.md  # 脏工作树协议
-|   |   |-- prerequisites.md   # 前置条件检查清单
-|   |-- scripts/
-|   |   |-- comate.sh          # 调度器 + 状态机（单一入口）
-|   |   |-- comate-lib.sh      # 库函数
-|   |-- tests/
-|       |-- comate.bats
-|       |-- run.sh
-|-- comate-open/SKILL.md       # 阶段 1：启动
-|-- comate-design/SKILL.md     # 阶段 2：深度设计
-|-- comate-build/SKILL.md      # 阶段 3：规划与构建
-|-- comate-verify/SKILL.md     # 阶段 4：验证与收尾
-|-- comate-archive/SKILL.md    # 阶段 5：归档
-|-- comate-fix/SKILL.md        # 预设：快速小改动（bug + 调整）
-```
-
-### 12.2 运行时产出物
-
-```
-openspec/                              # OpenSpec - WHAT
-|-- changes/<name>/
-|   |-- .comate.yaml                   # comate 状态机真相源
-|   |-- proposal.md / design.md / tasks.md
-|   |-- specs/<capability>/spec.md     # Delta 能力规约
-|   |-- .comate/handoff/               # 脚本生成的阶段交接包
-|   |-- .comate/sources.manifest       # 知识库源文件清单（source_kind=file 时）
-|-- specs/<capability>/spec.md         # 主规约（归档时由 delta 覆写）
-
-docs/                                  # 文档与知识库
-|-- knowledge-base/<...>.md            # 可追踪的需求源文档（source_kind=file）
-
-docs/superpowers/                      # Superpowers - HOW
-|-- specs/YYYY-MM-DD-<topic>-design.md # 设计文档
-|-- plans/YYYY-MM-DD-<feature>.md      # 实现计划
-|-- reports/                           # 验证报告
-```
+**不要在验收期间改代码**
+- ❌ 错误：handoff 后发现问题，在主工作区直接改
+- ✅ 正确：等验收结果，失败会自动回 build，在回修轮里改
 
----
+**不要跳过确认**
+- ❌ 错误：open --prepare 后直接改代码
+- ✅ 正确：等用户确认或自己执行 open --confirm，进入 Building 后再写代码
 
-> 本手册汇编自所有 comate SKILL.md 源文件和 reference/ 文档，供日常参考。
-> 规范权威仍以源文件为准：每个阶段的 SKILL.md 是执行规约，reference/ 定义协议，comate.sh 是代码实现。
-> 若本手册与源文件冲突，以源文件为准。
+**不要手动编辑 state.json**
+- ❌ 错误：state.json 里有奇怪的字段，直接删掉
+- ✅ 正确：运行 `doctor` 诊断，或从 git 历史恢复