@house365/comate 0.9.24 → 0.9.26

package/docs/COMATE_MANUAL.md

@@ -1,713 +1,713 @@
-# comate - 操作手册
-
-> SDD (规约驱动开发) 的 AI 开发编排器
-> 版本：schema_version 1，五阶段工作流
-> 最后更新：2026-08-17
-
----
-
-## 目录
-
-- 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. 概述与核心概念
-
-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 运行环境
-
-| 依赖 | 要求 | 检查方式 |
-|------------|-------------|-------|
+# comate - 操作手册
+
+> SDD (规约驱动开发) 的 AI 开发编排器
+> 版本：schema_version 1，五阶段工作流
+> 最后更新：2026-08-17
+
+---
+
+## 目录
+
+- 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. 概述与核心概念
+
+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 阶段依赖它。
-
-```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  # 验证安装
-```
-
-comate 使用以下 OpenSpec 能力（以技能形式调用）：`openspec-explore`、`openspec-new-change`、`openspec-propose`、`openspec-verify-change`。请确认这些技能在你的平台技能目录中可用。
-
-### 2.3 Superpowers（HOW 侧）
-
-处理技术设计/规划/执行/收尾。comate 的 design、build 和 verify 阶段依赖它。
-
-`comate init` 已用 `skills add obra/superpowers -g` 装到用户级。手动补装同理。确认以下技能可加载：
-
-- `superpowers:brainstorming`
-- `superpowers:writing-plans`
-- `superpowers:subagent-driven-development`
-- `superpowers:executing-plans`
-- `superpowers:using-git-worktrees`
-- `superpowers:finishing-a-development-branch`
-
-**如果任何 Superpowers 步骤不可用，对应阶段必须停止并提示安装。不得用普通对话替代。**
-
-### 2.4 comate 本身
-
-comate 以 npm 包分发（`npm install -g @house365/comate`），`comate init` 通过 skills CLI 装到用户级 `~/.agents/skills`，一次装完所有项目共用，支持 Claude Code、Codex、Cursor 等 70+ agent。
-
-### 2.5 docs/ 知识库骨架（阶段 0 用）
-
-`comate init` 会在项目里铺出 `docs/` 骨架，供 `/comate-gate` 读写 PRD：
-
-```
-docs/
-├── README.md                                   # docs 目录说明
-├── architecture/README.md                      # 架构规范占位（契约事实源，需项目自建）
-└── knowledge-base/
-    ├── README.md                               # PRD → comate 流程说明 + 命名约定
+| 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 阶段依赖它。
+
+```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  # 验证安装
+```
+
+comate 使用以下 OpenSpec 能力（以技能形式调用）：`openspec-explore`、`openspec-new-change`、`openspec-propose`、`openspec-verify-change`。请确认这些技能在你的平台技能目录中可用。
+
+### 2.3 Superpowers（HOW 侧）
+
+处理技术设计/规划/执行/收尾。comate 的 design、build 和 verify 阶段依赖它。
+
+`comate init` 已用 `skills add obra/superpowers -g` 装到用户级。手动补装同理。确认以下技能可加载：
+
+- `superpowers:brainstorming`
+- `superpowers:writing-plans`
+- `superpowers:subagent-driven-development`
+- `superpowers:executing-plans`
+- `superpowers:using-git-worktrees`
+- `superpowers:finishing-a-development-branch`
+
+**如果任何 Superpowers 步骤不可用，对应阶段必须停止并提示安装。不得用普通对话替代。**
+
+### 2.4 comate 本身
+
+comate 以 npm 包分发（`npm install -g @house365/comate`），`comate init` 通过 skills CLI 装到用户级 `~/.agents/skills`，一次装完所有项目共用，支持 Claude Code、Codex、Cursor 等 70+ agent。
+
+### 2.5 docs/ 知识库骨架（阶段 0 用）
+
+`comate init` 会在项目里铺出 `docs/` 骨架，供 `/comate-gate` 读写 PRD：
+
+```
+docs/
+├── README.md                                   # docs 目录说明
+├── architecture/README.md                      # 架构规范占位（契约事实源，需项目自建）
+└── knowledge-base/
+    ├── README.md                               # PRD → comate 流程说明 + 命名约定
     ├── requirements/_templates/PRD.md          # PRD 模板
-    └── integrations/_TEMPLATE/                  # 第三方对接档案模板（README + api-snapshot）
-```
-
-- 路径与 `comate-lib.sh` 硬编码的 `comate_kb_root=docs/knowledge-base` 对齐，PRD 放 `requirements/<YYYYMMDD-功能名>/` 下。
-- **幂等且不覆盖**：逐文件跳过已存在的，重跑 `comate init` 不动你已改过的 docs。
-- `architecture/` 只给占位 README（架构内容项目专属），是 PRD 门禁「契约对齐」的事实源，需按项目实际补齐。
+    └── integrations/_TEMPLATE/                  # 第三方对接档案模板（README + api-snapshot）
+```
+
+- 路径与 `comate-lib.sh` 硬编码的 `comate_kb_root=docs/knowledge-base` 对齐，PRD 放 `requirements/<YYYYMMDD-功能名>/` 下。
+- **幂等且不覆盖**：逐文件跳过已存在的，重跑 `comate init` 不动你已改过的 docs。
+- `architecture/` 只给占位 README（架构内容项目专属），是 PRD 门禁「契约对齐」的事实源，需按项目实际补齐。
 - PRD 是需求入口，具体实现约束由 change 的 proposal/design/tasks 承接。
-
-### 2.6 comate 本身的技能布局
-
-采用扁平布局——每个 phase 是顶层技能目录，而非 `comate/<phase>/` 嵌套。部分 agent（含 Claude Code）只发现顶层目录，扁平是共同可用的最小公倍数：
-
-```
-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`
-
----
-
-### 2.7 Token 用量：`comate usage`
-
-终端命令，查看**当前项目**的 token 消耗与估算成本。封装 [ccusage](https://github.com/ryoppippi/ccusage)——它作为 comate 的依赖随包安装，`comate doctor` 会检测其可用性（缺失时回退 `npx ccusage@latest`）。
-
-```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 阶段级归因（需在状态机流转处打时间戳，属后续增强）。
-
----
-
-## 3. 快速开始
-
-### 3.1 基本用法
-
-```
-/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'
-```
-
-### 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）
+
+### 2.6 comate 本身的技能布局
+
+采用扁平布局——每个 phase 是顶层技能目录，而非 `comate/<phase>/` 嵌套。部分 agent（含 Claude Code）只发现顶层目录，扁平是共同可用的最小公倍数：
+
+```
+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`
+
+---
+
+### 2.7 Token 用量：`comate usage`
+
+终端命令，查看**当前项目**的 token 消耗与估算成本。封装 [ccusage](https://github.com/ryoppippi/ccusage)——它作为 comate 的依赖随包安装，`comate doctor` 会检测其可用性（缺失时回退 `npx ccusage@latest`）。
+
+```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 阶段级归因（需在状态机流转处打时间戳，属后续增强）。
+
+---
+
+## 3. 快速开始
+
+### 3.1 基本用法
+
+```
+/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'
+```
+
+### 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
-```
-
-然后全程复用 `$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`。
+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
+```
+
+然后全程复用 `$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。
-
-### 5.5 阶段 5：归档（/comate-archive）
-
-**归属**：OpenSpec
-**触发条件**：验证已通过，分支已处理
-**产出物**：delta->main spec 同步、设计文档标注、变更移至归档
-
-**路径迁移**：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/`，该目录不移动，保持不变。
-
-**步骤**：
-
-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 目录。
-
----
-## 6. 预设路径：fix
-
-### 6.1 概述
-
-**适用场景**：快速小改动，跳过头脑风暴（及完整计划）。覆盖两种模式，调用时判定「是不是 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 | 影响已有规格 |
-
+5. **退出**：运行 `bash $COMATE guard <name> verify --apply`，通过后自动推进到 archive。
+
+### 5.5 阶段 5：归档（/comate-archive）
+
+**归属**：OpenSpec
+**触发条件**：验证已通过，分支已处理
+**产出物**：delta->main spec 同步、设计文档标注、变更移至归档
+
+**路径迁移**：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/`，该目录不移动，保持不变。
+
+**步骤**：
+
+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 目录。
+
+---
+## 6. 预设路径：fix
+
+### 6.1 概述
+
+**适用场景**：快速小改动，跳过头脑风暴（及完整计划）。覆盖两种模式，调用时判定「是不是 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） |
+
+---
+
+## 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 前必须指向真实文件 |
+| `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。
-
+| `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>` | 读取单个状态字段 |
+
+**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` 等 |
+| `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` 补装 |
+| `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/                           # 验证报告
-```
-
----
-
-> 本手册汇编自所有 comate SKILL.md 源文件和 reference/ 文档，供日常参考。
-> 规范权威仍以源文件为准：每个阶段的 SKILL.md 是执行规约，reference/ 定义协议，comate.sh 是代码实现。
-> 若本手册与源文件冲突，以源文件为准。
+| .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/                           # 验证报告
+```
+
+---
+
+> 本手册汇编自所有 comate SKILL.md 源文件和 reference/ 文档，供日常参考。
+> 规范权威仍以源文件为准：每个阶段的 SKILL.md 是执行规约，reference/ 定义协议，comate.sh 是代码实现。
+> 若本手册与源文件冲突，以源文件为准。