@house365/comate 0.10.2 → 1.0.2-next.0

package/skills/comate/reference/archive.md

@@ -0,0 +1,50 @@
+# archive：接受、归档与收尾
+
+## 1. 接受（停②）
+
+next `action: accept` 时，一次 AskUserQuestion 问完「接受结果 + 收尾方式」。`message` 里有 verifier 的 risks，要列给用户。选项就是 `alternatives`：
+
+- 接受并本地合并到 base 分支（`--finish merge`）
+- 接受并推送、创建 PR（`--finish pr`，需要 origin 和 gh）
+- 接受并保留分支（`--finish keep`）
+- 回去修改实现（`--revise-implementation --note "<要改什么>"`）
+- 需求确实要变（`--revise-requirements`）
+
+`push` 也可用（只推送不建 PR），用户明确要求时再用。merge / push / PR 是对外或不可逆动作，**只执行用户这次选的那一个**，不自行追加。
+
+配置了 `"finish": "auto"` 且没有 risks 时，脚本跳过停②直接进入归档，收尾方式取 `auto_finish_action`（未配置就是 keep，只本地归档）。
+
+## 2. 归档
+
+脚本在 accept 阶段已做预检（文档、源文件、候选 commit、主 spec 基线），用户确认收尾方式后直接执行：
+
+```bash
+node "$COMATE" archive <name> --dry-run --json   # 可选：只做预检，列出将执行的步骤
+node "$COMATE" archive <name> --json
+```
+
+脚本按固定顺序执行：记录计划 → 写入 `comate/comate/specs/` → change 目录移到 `comate/comate/archive/YYYY-MM-DD-<name>/` → 提交 `chore(comate): archive <name>` → 执行收尾。
+
+**如果 accept 后、archive 前有冲突**（主 spec 被改、验收后又提交代码）：
+- 主 spec 冲突：重读新的主 spec，改写本 change 的 spec，`decide --revise-requirements` 重新确认
+- 代码冲突：`decide --revise-implementation` 重新验收
+
+## 3. 收尾方式
+
+| 方式 | 脚本做什么 |
+|---|---|
+| `keep` | 不动，报告分支名 |
+| `merge` | base 分支签出在别的 worktree（orca 常见）时在那个 worktree 里 `merge --no-ff`，那边有未提交改动就停；否则切到 base 合并。冲突时中止合并并停下，不自动解决。是否推送由用户决定 |
+| `push` | `git push -u origin <分支>` |
+| `pr` | 推送后 `gh pr create --base <base 分支>`，已存在 PR 就复用 |
+
+## 4. 中断与恢复
+
+任何一步中断后，直接重跑 `archive <name>`：脚本按证据判断（主 spec 是写入前还是写入后的内容、目录在 changes 还是 archive、归档提交是否存在、分支是否已合并 / 已推送）从断点继续，不重复覆盖，不重做已成功的远程动作。
+
+- 收尾失败（没有远端、gh 未登录、目标 worktree 不干净、合并冲突）：next 为 `retry-finish`，按提示处理后重跑 `archive <name>`。用户决定放弃这个收尾时，执行 alternatives 里的「改为保留分支」。
+- 出现计划解释不了的状态（主 spec 既不是写入前也不是写入后的内容）：脚本停下。运行 `doctor`，向用户说明，人工核对后再处理。
+
+## 5. 结束
+
+`disposition: done` 后向用户报告：归档路径、写入的主 spec（能力与操作）、收尾结果（分支名 / 合并目标 / PR 链接）。

package/skills/comate/reference/build.md

@@ -0,0 +1,67 @@
+# build：实现
+
+## 1. 开始前读什么
+
+next 的 `dispatch` 里有文档路径和全部验收项（`status <name> --json` 随时可取）。
+
+- 首轮：brief.md、全部 spec 全文，以及 `dispatch.acceptance` 的每一项。
+- 修复轮（`action: repair`）：看 `dispatch.acceptance` 里 `failed` / `blocked` 项的 `reason`、`dispatch.verifier_summary`、`dispatch.failed_checks[].tail`，以及 `dispatch.repairs` 里的回修项。这些是修复重点，下一轮仍验收全部项。
+- 连续两轮没有进展时 next 会提示：换一种修复思路，不要重复上一轮的改法。
+
+## 2. 实现
+
+- 实现方式自己定，不强制 TDD。但覆盖验收项的测试与实现同批提交，断言 THEN 描述的结果，不断言实现细节。
+- bug 修复必须带能复现原问题的回归测试。
+- 无法自动化的验收项，在 handoff 的 `manual_checks` 写可复现的手工步骤。
+- 可并行时，把互不依赖的任务派给子 agent；子 agent 只报告完成，由你提交。
+- 开发期只跑定向测试；全量检查由脚本在 handoff 后执行（`comate/comate/config.json` 的 `build_command` / `verify_command`，未配置时自动探测）。
+
+## 3. 需求变化
+
+**以下情况必须 `--revise-requirements`**（停下问用户，回 open 重新确认）：
+- spec 里没有的 Scenario 需要实现
+- 已有 Scenario 的 THEN 需要改（行为变化）
+- 新增 capability
+- 公共 API 签名变化（参数、返回值、端点路径）
+- 数据 schema 变化（表结构、字段类型、约束）
+
+**以下不算需求变化**（直接补，不回 open）：
+- brief 里已列明但实现时遗漏的功能点
+- 测试覆盖不足（补测试）
+- 代码重构（不改外部可见行为）
+- 实现细节调整（算法、性能优化、内部接口）
+
+**与本 change 无关的需求**：交给另一个 change。
+
+## 4. 工作区有来历不明的改动
+
+恢复会话时先 `git status --short` 和 `git diff --stat` 归因：
+
+- 属于当前 change：纳入当前任务继续，不重复改同一处。
+- 不属于当前 change 或来源不确定：停下，向用户列出文件，问是并入、拆成新 change、保留不动，还是明确授权丢弃。
+- 没理解来源前，不覆盖、不回滚、不格式化重写用户的改动。
+
+## 5. handoff
+
+实现和测试完成并提交后，工作区除 change 目录外必须干净。把 handoff 写到 `.comate/handoff.json`（脚本读完会删）：
+
+```json
+{
+  "summary": "本轮改了什么",
+  "addressed": ["A1", "A2"],
+  "manual_checks": [{ "id": "A3", "steps": "打开登录页，输入…，应看到…" }],
+  "known_limits": []
+}
+```
+
+- `addressed`：本轮**有代码改动**的验收项 ID 数组
+  - 首轮：必须覆盖全部验收项
+  - 修复轮：至少包含上轮 failed/blocked 的项；未改动的项可不列（verifier 仍会验收全部项）
+- `manual_checks`：无法自动化的验收项的手工验证步骤。
+- `known_limits`：已知的非阻塞性限制或技术债（可选）。
+
+然后执行 next 的 `command`：`node "$COMATE" handoff <name> --input .comate/handoff.json --expect <v>:<step> --json`。
+
+脚本会：冻结 HEAD 为候选、运行检查命令。检查失败直接回修（state.json 记录回修项）；通过则签发 verifier token，next 变为 `dispatch-verifier`，接着读 `reference/verify.md`。
+
+被拦截常见原因：实现未提交、addressed 未覆盖必需的验收项、没配置测试命令（在 config.json 写 `"verify_command": "<命令>"`，确实没有写 `"none"`）。

package/skills/comate/reference/fix.md

@@ -0,0 +1,150 @@
+# fix 模式
+
+同一个状态机的 `mode: fix`，不是另一套流程。用于边界清楚的小修：bug 修复、小调整、配置改动。
+
+```bash
+node "$COMATE" new <name> --mode fix --json
+```
+
+## 核心原则
+
+fix 模式信任你能快速判断清楚的小修范围，**不走九大视角清单**，只需回答三个核心问题：
+
+1. **修什么**（目标） — 现象、影响范围、复现方式
+2. **怎么验收**（验收示例） — 至少一条「修复后原问题不再出现」
+3. **为什么这样修**（决定） — 根因分析与修复方式
+
+### 何时需要查证
+
+虽然不走清单，但以下情况必须主动查证或问用户：
+
+| 情况 | 处理方式 |
+|---|---|
+| **根因不明** | 先复现问题、定位根因，再写 brief |
+| **影响范围不确定** | 检查调用链、依赖关系，明确波及范围 |
+| **修复方案有多种** | 评估可逆性和副作用，选最小改动；不确定时问用户 |
+| **可能破坏已有行为** | 列出可能受影响的场景，验收示例必须包含回归检查 |
+
+**判断标准**：如果你写完 brief 后发现"其实不太确定影响范围"或"可能有副作用但说不清"，那就是该查证的信号。
+
+## 与 full 的区别
+
+| 方面 | fix | full |
+|---|---|---|
+| brief.md | 三章：目标、验收示例、决定 | 七章：目标、范围、非目标、验收示例、约束与不变量、决定、待决问题 |
+| 澄清方式 | 原则驱动：按需查证 | 清单驱动：九大视角逐项检查 |
+| spec | 可省；有行为变化时照常写 | 必须（除非明确「无行为变更」） |
+| 停① | 免确认：prepare 通过后直接进 build | 必须用户确认 |
+| handoff | `addressed` 至少覆盖一项验收 | 必须覆盖全部验收项 |
+| verify | 独立 verifier 验收，**bug 修复必须带回归测试** | 独立 verifier 验收 |
+| 停② | 照常（接受 + 收尾） | 照常 |
+
+## 升级为 full
+
+**判断标准**：如果继续用 fix 模式，会不会因为澄清不足导致返工？
+- **会** → 停下告诉用户，执行 `decide <name> --upgrade --expect <v>:<step>`
+- **不会** → 继续 fix
+
+**常见升级信号**（出现任一即升级）：
+- **根因复杂**：一次修复解决不了，需要分阶段处理；涉及多个子系统协调
+- **影响范围扩大**：需要新的用户可见行为；发现多个模块的耦合问题；需要配套的迁移或灰度方案
+- **需要产品决策**：如何权衡副作用；多种方案各有利弊
+- **架构级改动**：需要改 schema、新增 API、调整模块边界
+
+升级后回到 open：补全 brief 七章（走原则驱动澄清），重新 prepare，并请用户确认一次。
+
+## 实践要点
+
+### brief 写作
+
+**目标章节** — 问题导向
+```markdown
+# 目标
+
+用户在订单列表页滚动到底部时，点击「加载更多」无反应。
+影响范围：所有用户，订单超过 20 条时必现。
+复现：登录 → 订单列表 → 滚动到底部 → 点击「加载更多」→ 无反应。
+```
+
+**验收示例** — 端到端可测试的结果
+
+写成用户视角的完整操作链，覆盖修复后的主流程和关键边界：
+
+```markdown
+# 验收示例
+
+- 修复后，点击「加载更多」能正常加载下一页订单
+- 已加载全部订单时，「加载更多」按钮变灰且显示「已加载全部」
+- 回归：其他分页场景（商品列表、搜索结果）不受影响
+```
+
+**注意**：
+- 粒度：端到端操作（用户做什么 → 看到什么结果），不是单个交互细节
+- 数量：通常 2–5 条（修复验证 + 关键回归）
+- 回归检查：必须列出可能受影响的相关场景
+
+**决定章节** — 根因与方案
+```markdown
+# 决定
+
+根因：分页请求的 offset 计算错误，`offset = page * pageSize` 应为 `offset = (page - 1) * pageSize`。
+修复方式：修正 `api/orders.js:45` 的 offset 计算公式。
+不改其他分页实现（已单独封装且行为正确）。
+```
+
+### 何时需要 spec
+
+- **有新的产品行为** — 例如「按钮变灰 + 文案提示」是新行为，写 spec
+- **只修 bug，行为恢复原设计** — 无需 spec，在 brief 说明即可
+- **改了配置或文案** — 无需 spec（除非配置本身有复杂规则）
+
+### 验收要点
+
+Bug 修复的验收**必须包含**：
+1. **正向验证** — 修复后原问题消失
+2. **回归验证** — 相关场景不受影响（列出具体场景）
+3. **边界验证** — 极值、空值、并发（按实际风险选择）
+
+verifier 会独立判定每一项，不能只验正向。
+
+## 常见误用
+
+❌ **把不确定的大改当 fix**
+```
+目标：优化订单查询性能
+决定：加缓存（Redis？本地？过期策略？）
+
+→ 这不是 fix，用 full 模式走完整澄清
+```
+
+❌ **根因不明就开始改**
+```
+目标：偶现的订单创建失败
+决定：加重试逻辑
+
+→ 先定位根因（并发？超时？数据校验？），再决定方案
+```
+
+❌ **遗漏回归验证**
+```
+验收示例：
+- 修复后，订单列表加载正常
+
+→ 缺少：商品列表、搜索结果等其他分页场景的回归
+```
+
+## 何时选 fix
+
+**适合 fix**：
+- 明确的 bug，能快速复现和定位
+- 影响范围清楚（单一模块或功能）
+- 修复方案直接（不涉及架构调整）
+- 改动文件少（bug 修复 ≤3 个文件，调整 ≤5 个文件）
+
+**不适合 fix**：
+- 需求不清楚，要探索解决方案
+- 涉及多个子系统的协调
+- 需要产品决策（权衡、取舍）
+- 改动规模不确定
+
+**边界不清时，默认用 full**。升级成本低（补章节 + 重确认），降级没有（full 不能转 fix）。

package/skills/comate/reference/open.md

@@ -0,0 +1,162 @@
+# open：澄清与规约
+
+产出两份需求文档（都在 `comate/comate/changes/<name>/`），用户确认一次后进入 build：
+
+| 文件 | 回答 |
+|---|---|
+| `brief.md` | 为什么做、做什么、不做什么、关键决定、验收示例 |
+| `specs/<capability>/spec.md` | 该能力**归档后的完整行为**（不是 delta） |
+
+不写 design / plan / tasks。实现细节由 build 自己定；只有会影响验收的取舍才写进 brief「决定」「约束与不变量」。
+
+## 1. 原则驱动澄清（仅 full 模式）
+
+**fix 模式走简化流程，见 `reference/fix.md`。以下适用于 full 模式。**
+
+### 核心原则（三分类）
+
+- **仓库事实**：自己查（代码、`comate/architecture/`、`comate/comate/specs/`）。如果代码逻辑与文档/注释冲突，以当前真实代码逻辑为准（代码注释不能作为可信源）。不问人。
+- **产品决策**：会改变用户可见结果或验收标准的决定，问用户。
+- **实现选择**：不影响验收结果的技术细节，自己定。
+
+**收敛原则**：仓库能回答的先查证，不问用户；仓库没有唯一答案、涉及产品取舍的才问用户。
+
+### 必答问题
+
+所有 full 模式 change 都要回答：
+
+1. **为谁解决什么问题**（问题与价值）
+   - 解决谁的什么问题、背景假设
+   - 区分「交付功能」与「期望结果」
+   - 成功/失败的业务结果
+
+2. **核心取舍是什么**（方案与取舍）
+   - 实质互斥的方向（同步/异步、客户端/服务端等架构级选择）
+   - 可逆/不可逆决策
+   - 明确不做的替代方案及选择理由
+
+3. **怎么验收**（验收示例）
+   - 至少一条可测试的结果
+   - 关键场景的预期行为
+
+### 视角框架（按需深挖）
+
+以下7个视角作为**风险检查框架**，不是逐项填表。根据 change 特征，主动深挖可能导致返工或生产问题的视角：
+
+| 视角 | 何时必须深挖 | 可以跳过的情况 |
+|---|---|---|
+| **用户与场景** | 多角色、跨角色冲突、公开产品、涉及权限或匿名用户 | 纯内部工具、单一角色、开发者工具 |
+| **架构与边界** | 新模块、模块间交互变化、跨服务调用 | 单一模块内的局部改动 |
+| **旅程与状态** | 有状态变更、跨端行为、跨会话、需支持撤销/回退 | 无状态变更（纯查询、纯展示） |
+| **数据与规则** | 涉及数据存储/传输/隐私、数据生命周期、一致性要求 | 纯前端交互、不涉及持久化 |
+| **非功能约束** | 生产发布、用户实时交互、处理敏感数据/资金、依赖外部系统 | 内部原型、实验功能（需在「决定」中明确延后） |
+| **依赖与交付** | 新依赖、公共 API 变更、数据迁移、需灰度/回滚 | 无新依赖、无迁移、内部接口 |
+| **风险与反例** | 外部输入、并发场景、网络/依赖失败、需要灾备 | 仅管理员可见、无外部输入、单机运行 |
+
+**判断标准**：遗漏这个视角会不会导致返工或生产问题？
+- **会** → 查证仓库事实，或识别出需要问用户的决策点
+- **不会** → 跳过（不需要在 brief 里解释为什么跳过）
+
+**何时需要查证或问用户**：
+
+| 情况 | 处理方式 |
+|---|---|
+| 仓库已有答案（架构文档、现有代码、spec） | 查证并引用来源，不问用户 |
+| 影响范围不确定 | 检查调用链、依赖关系，明确波及范围 |
+| 多种方案都可行，涉及产品权衡 | 评估各方案的可逆性和副作用，写入「待决问题」问用户 |
+| 可能破坏已有行为 | 列出可能受影响的场景，验收示例必须包含回归检查 |
+| 非功能约束的阈值未定（如延迟要求、容量上限） | 问用户具体指标 |
+
+**NFR 检查时机**：生产发布默认检查安全/隐私、可用性/恢复、可观测性、灰度/回滚；用户实时交互检查延迟；批处理/增长场景检查吞吐与容量；处理身份/敏感数据/资金时检查安全隐私合规；对外或多地区产品检查无障碍/国际化；依赖外部系统时检查超时/重试/降级。能力适用但阈值未定，仍需澄清。
+
+## 2. 提问
+
+- 先把问题写进 brief「待决问题」：`- [blocking] Q1: …`，再问。
+- AskUserQuestion 每轮 1–3 题，每题 2–3 个互斥选项并标推荐项与理由；前一答案会改变后续选项时分轮问。
+- 答完立刻把结论写进「决定」和 spec，删掉对应的 `[blocking]` 行。全部清空（或写「无」）才能 prepare。
+
+## 3. 写 brief.md
+
+七个一级章节都要有真实内容（模板里的 `<!-- -->` 注释不算）：目标、范围、非目标、验收示例、约束与不变量、决定、待决问题。
+
+### 验收示例指导
+
+「验收示例」写**端到端的关键路径验证**，每条一个 `- ` 列表项，脚本按顺序编号为 A1、A2…
+
+**职责定位**：
+- **brief 验收示例**：业务价值验证，从用户视角的完整操作链（"能完成任务 X"）
+- **spec Scenario**：行为规格细节，具体输入输出（"输入 Y 时显示 Z"）
+- 关系：一条 brief 验收可能对应多个 spec Scenario
+
+**粒度与数量**：
+- 粒度：端到端操作（登录 → 操作 → 看到结果），不是单个交互
+- 数量：3–7 条，覆盖主流程 + 关键边界（成功路径、主要失败场景、安全约束）
+- 避免：过细（"点击按钮后按钮变灰"应在 spec）、过多（>10 条说明该拆分 change）
+
+**示例对比**：
+```markdown
+# 验收示例（brief）
+- 用户使用邮箱密码登录成功，进入首页，能看到个人信息
+- 密码错误时登录失败，显示错误提示，不泄露用户是否存在
+- 连续 5 次密码错误后账号锁定 30 分钟
+
+对应的 spec Scenario（更细的行为）：
+- Scenario: 密码错误 → 显示「邮箱或密码错误」
+- Scenario: 账号不存在 → 显示相同错误（不泄露）
+- Scenario: 第 5 次密码错误 → 锁定账号
+- Scenario: 锁定期间登录 → 显示剩余锁定时间
+```
+
+**其他要求**：
+- 不留 TODO / TBD / 待填写 / 待补充
+- 确实没有产品行为变化（纯文案、配置）时，不写 spec，在「范围」写一行 `无行为变更：<具体理由>`
+
+## 4. 写 spec.md
+
+```markdown
+# auth
+
+## Requirement: 邮箱登录
+用户可以用邮箱和密码登录。
+
+### Scenario: 密码错误
+- WHEN 用户输入已注册邮箱和错误密码
+- THEN 显示「邮箱或密码错误」，不提示具体哪项错
+```
+
+- 每个 Scenario 必须有 THEN，标题在同一 spec 内唯一。**每个保留或删除的 Scenario 都会成为一项验收。**
+- 修改已有能力：先把 `comate/comate/specs/<capability>/spec.md` 复制过来再改。Scenario 和所属 Requirement 的标题、正文都没变时标为 `regression`；任一变化都标为 `changed`（逐项细验）。验收文本包含 Requirement 上下文，主 spec 有而这里删掉的会列在确认摘要里。
+- 删除整个能力：`node "$COMATE" spec remove <name> <capability>`（撤销用 `spec restore`）。
+
+## 5. 需求来自文件（PRD、附件）
+
+`new <name> --source <file>` 钉住文件哈希，brief 模板会带「## 来源覆盖」表。把源文件逐段拆成 S1、S2… 登记：
+
+| 列 | 取值 |
+|---|---|
+| `source_item` | S1、S2… |
+| `location` | 源文件内位置（章节 / 段落 / 表格） |
+| `read_status` | 必须是 `complete`（`partial` / `unavailable` 会被拒） |
+| `spec_location` | `specs/<cap>/spec.md#<Scenario 标题>` 或 `brief.md#验收示例/<序号>`，多个用逗号分隔；背景类可空 |
+| `coverage` | `covered` / `background` / `non-goal` / `superseded`（`needs-clarification` 会被拒） |
+| `note` | 分类理由；`superseded` 必须写被什么替代 |
+
+不要在表里填验收 ID，脚本会按 `spec_location` 算出映射。源文件之后被改，后续阶段都会拦截。
+
+范围过大（多个可独立交付的功能簇）时，建议用户拆成多个 change 分别 new。
+
+## 6. 确认（停①）
+
+```bash
+node "$COMATE" open <name> --prepare --json
+```
+
+被拦截就按列出的问题修改后重跑。通过后 next 为 `await-user`，`dispatch.summary` 里有确认摘要：用中文向用户完整列出目标、范围、非目标、关键决定、**全部验收项**（ID、类型、来源）、删除的 Scenario、change 名称，AskUserQuestion 给出 alternatives：
+
+- 「确认，开始实现」→ 执行对应命令（`open --confirm --expect …`）
+- 「需要调整」→ 按用户意见改文档，重跑 `--prepare` 再问
+- 用户只想改名：`node "$COMATE" rename <name> <new>`，然后重跑 `--prepare`
+
+确认后验收项冻结：之后改 brief / spec 都会被发现，只能 `decide --revise-requirements` 回来重新确认。
+
+`resolve-drift`：已确认的文档或源文件被改了。误改就 `git checkout -- <文件>` 还原；需求确实要变，向用户说明后执行 next 里的 `--revise-requirements`。

package/skills/comate/reference/verify.md

@@ -0,0 +1,123 @@
+# verify：独立验收
+
+## 1. 主控：派发 verifier
+
+next `action: dispatch-verifier` 时：
+
+1. 启动一个**未参与 build 的只读子 agent**。把本文件第 2 节以后的内容、next 的 `dispatch` 和 `template` 原样交给它，不给 build 过程的对话。
+2. 等它把结果写进 `dispatch.result_file`（即 `.comate/verify-result.json`），执行 `command`：`node "$COMATE" verify <name> --result .comate/verify-result.json --json`。
+3. 结果被拒（漏报、重复、缺理由、缺反向验证）：把错误原文交回同一个 verifier 修正，用同一 token 重交。
+4. 子 agent 崩溃、超时或没有结果：`verify <name> --error "<原因>"`，脚本重签 token 后再派一个新的；连续 3 次转为阻塞。
+5. 平台没有子 agent 能力：执行 next 里的 `verify <name> --unavailable --expect …`。降级必须有成功执行的 `test` 类型检查，并由用户明确接受「只有自动检查」。`none`、编译/语法检查和未知命令不能支持降级；自定义测试配置为 `{ "cmd": "<命令>", "kind": "test" }`。确认后的命令类型、命令或引用的 npm 脚本定义变化，需要恢复计划并重新 handoff，或 `decide --revise-requirements` 重新确认。旧状态缺少完整计划时也须重新确认，或使用独立 verifier。
+
+命令分类只判断已知测试入口及显式声明，不能证明任意脚本的测试质量；逐项行为证据仍由 verifier 核验。
+
+## 2. verifier：规则
+
+### 独立性保证
+
+**上下文隔离**：
+- 主控必须在**新的子 agent 会话**中派发 verifier，不得在同一会话中串行执行
+- verifier 不能访问 build 阶段的对话历史、builder 的思考过程、失败重试的中间状态
+
+**允许访问的信息**（仅这些）：
+- `dispatch.docs`：brief.md 和 spec 文件（需求）
+- `dispatch.diff`：代码变更（`git diff <base_ref>...<candidate>`）
+- `dispatch.checks`：脚本已跑过的检查结果（命令、退出码、输出尾部）
+- `dispatch.handoff`：builder 的摘要（addressed、manual_checks、known_limits）
+- 当前工作区文件：只读访问，用于查看实现和测试
+
+**工作方式**：
+- 对主工作区只读。唯一允许写的是 `dispatch.result_file`（即 `.comate/verify-result.json`）。
+- 先读 `dispatch.docs` 里的 brief 和 spec，再看 `dispatch.diff`，最后才看 `dispatch.handoff`（builder 摘要只是线索）。
+- `dispatch.checks` 是脚本已跑过的检查（命令、退出码、输出尾部）。要看完整输出就自己重跑。
+
+**独立性检查**：verifier 的第一段输出必须包含"我是独立 verifier，未参与 build 过程"的声明。
+
+## 3. 逐项判定
+
+对 `dispatch.acceptance` 的**每一项**给出 `passed` / `failed` / `blocked` 和理由。`kind: removed` 的项目必须确认旧行为确实不可用，或已按 brief 中的迁移规则处理。
+
+### 各类验收项的检查标准
+
+**changed 类**：找到实现位置和覆盖它的测试，读测试确认它断言的是 THEN（不是实现细节、不是恒真）。
+
+**regression 类**：虽然 Scenario 本身没改，但需要确认本 change 是否影响它：
+
+1. **直接依赖检查**：该 Scenario 涉及的函数/接口是否被本 change 修改
+   - 未修改 → 确认已有测试通过即可
+   - 已修改 → 按 changed 标准验证（读测试、确认断言正确）
+
+2. **间接影响检查**：本 change 是否改了 Scenario 依赖的底层逻辑
+   - 示例：改了数据库查询逻辑 → 所有涉及该表的 Scenario 都要检查影响范围
+   - 判定：查看 diff 中的函数是否被该 Scenario 的代码路径调用（通过调用链分析）
+
+3. **集成影响检查**：本 change 是否改了状态管理、配置、中间件、全局拦截器
+   - 这类改动可能影响所有 Scenario → 至少抽查 2–3 个核心流程深度验证
+
+**判定原则**：
+- 低风险 regression（无依赖变化，测试通过）→ `passed`
+- 高风险 regression（有直接或间接依赖变化）→ 深度验证，标准同 changed
+- 没有测试覆盖的 regression → 给出简要手工核对步骤和结果
+
+**无法自动化的验收项**：按 handoff 的 `manual_checks` 或自己设计可复现步骤，写明步骤与结果。
+
+### 判定结果
+
+判 `failed`：构建或测试失败；验收项未实现或行为不符；既无测试也无可复现的手工证据；反向验证时测试仍然通过；bug 修复没有回归测试；安全问题（硬编码密钥、新增注入面、敏感信息写日志）。
+
+判 `blocked`：缺用户或外部信息才能判断（第三方账号、未决的产品口径），理由里写清缺什么、找谁。
+
+不影响验收的问题（风格、可读性、非核心的测试偏向实现细节）写进 `risks`，不判 failed。拿不准时往低定。
+
+## 4. 反向验证（必做）
+
+证明测试真能抓住错误。**不要在主工作区改代码**，用脚本建的临时 worktree：
+
+```bash
+node "$COMATE" probe <name> --json          # 返回 dir：基于候选 commit 的临时 worktree
+# 在 dir 里：
+#   核心项：把决定 THEN 的关键逻辑改错（反转条件、返回空值），跑覆盖它的测试 → 必须失败
+#   bug 修复：git checkout <base_ref> -- <修复涉及的源文件>（保留测试），跑回归测试 → 必须失败
+node "$COMATE" probe <name> --remove <dir>  # 用完删除
+```
+
+### 覆盖要求
+
+根据 change 规模决定反向验证的数量：
+
+| change 规模 | changed 项数量 | 最少验证数量 | 选择标准 |
+|---|---|---|---|
+| **bug 修复** | 任意 | 必须验证修复项 | 回归测试能抓住原问题 |
+| **小型** | ≤3 个 | 至少 1 个核心项 | 最核心的业务流程 |
+| **中型** | 4–6 个 | 至少 2 个核心项 | 覆盖不同功能模块 |
+| **大型** | ≥7 个 | 至少 3 个核心项 | 覆盖不同模块 + 不同复杂度 |
+
+### 选择优先级
+
+选择反向验证目标时，按以下优先级排序：
+
+1. **核心业务流程**：用户直接感知、高频使用的功能
+2. **复杂逻辑**：多分支、状态变化、边界条件处理
+3. **安全相关**：认证、授权、数据校验、敏感信息处理
+4. **集成点**：跨模块调用、外部依赖交互、数据一致性
+
+### 输出格式
+
+每次反向验证写进 `reverse_checks`：`{ target, mutation, test, failed_as_expected }`。测试没有变红（`failed_as_expected: false`）说明测试证明不了行为，对应项判 `failed`。
+
+## 5. 结果 JSON
+
+按 `template` 写：`token`、`candidate` 原样带回；`acceptance` 覆盖全部 ID、每项恰好一次、每项都有 `reason`（写证据：`path:line`、测试名、命令与输出摘要）；`reverse_checks`；`risks`；`summary`（一两句结论）。
+
+## 6. 主控：处理结果
+
+脚本应用结果并生成 `verification.md`，next 告诉你下一步：
+
+- 全部通过 → `accept`（读 `reference/archive.md`）。
+- 有 failed 且没有 blocked → 自动回 build，state.json 已记录回修项。先向用户简要报告失败项和修复思路，然后直接修，不提问。
+- 同时有 failed 和 blocked → 先解除外部阻塞；失败次数和修复证据已经登记。`decide --resolve` 保留结论及补充信息，转回 build 修 failed；若失败预算已耗尽则进入 Stuck。
+- 只有 blocked → `resolve-blocker`：向用户说明缺什么，拿到信息后 `decide --resolve --note "<补充>"`，脚本重新检查并签发新 token。
+- `resolve-stuck`（失败达上限或连续 3 轮无进展）→ 向用户列出仍未通过的项、已尝试的修复和失败原因。用户给方向就 `--revise-implementation --note "<方向>"`；验收本身不合理就 `--revise-requirements`。
+- `accept-degraded` → 向用户说明「没有独立逐项验收，只有自动检查通过」，由用户选择是否接受。
+- 验收期间 HEAD 变了 → 结果作废并计一次失败，回 build 重新 handoff。工作区有未提交改动时结果被拒：verifier 必须只读。

package/skills/comate/scaffold/comate/README.md

@@ -0,0 +1,18 @@
+# comate 目录说明
+
+comate 管理的全部内容都在项目根的 `comate/` 下,与代码同仓库、同评审、同版本管理。
+
+| 路径 | 定位 | 谁来写 |
+|------|------|--------|
+| `comate/config.json` | 项目配置:检查命令、失败上限、收尾方式、受保护分支 | 人 |
+| `comate/specs/<capability>/spec.md` | 主规格:已归档能力的完整行为 | 归档时由脚本写入 |
+| `comate/changes/<name>/` | 进行中的变更:`brief.md`、`specs/` 由 agent 写,`state.json`、`verification.md` 由脚本写 | agent + 脚本 |
+| `comate/archive/YYYY-MM-DD-<name>/` | 已归档的变更,只读 | 脚本 |
+| `architecture/` | 架构规范:分层、依赖、命名、错误码等工程铁律,以仓库当前实现为准 | 人 |
+| `knowledge-base/` | 知识库:原始 PRD(`requirements/`)与第三方对接档案(`integrations/`) | 人 / kb-integration |
+
+## 规则
+
+- `state.json` 是变更的唯一真相源,只由 `node "$COMATE" <command>` 写入;手改会被下一条命令的校验发现。
+- 架构文档是规则,不是 capability spec,不放进 `comate/specs/`。改对应层代码时同步更新。
+- 需求来自 PRD 时,用 `new <name> --source <PRD 路径>` 钉住文件哈希,并在 brief 的「来源覆盖」表逐段登记。

package/skills/{comate-gate/scaffold/docs → comate/scaffold/comate}/architecture/README.md

@@ -2,13 +2,13 @@
 
 > ⚠️ **本目录由 `comate init` 创建为占位,内容需根据项目实际情况建立。**
 
-本目录是工程约束的**唯一来源**,也是 `/comate-gate` PRD 门禁审阅中「契约对齐架构文档」的事实源。
+本目录是工程约束的**唯一来源**,也是 `/comate` 在 open 阶段写 brief「约束与不变量」「决定」时对齐的事实源。
 
 ## 为什么需要架构文档
 
-PRD 门禁审阅时,会检查数据来源、接口契约、命名规范、错误码、边界处理等是否明确。这些约束的**唯一事实源**应该是架构文档,而不是散落在 PRD/代码里的重复规则。
+`/comate` 澄清需求、写设计时,会检查数据来源、接口契约、命名规范、错误码、边界处理等是否明确。这些约束的**唯一事实源**应该是架构文档,而不是散落在 PRD/代码里的重复规则。
 
-`/comate-gate` 要求 PRD 里的契约「对齐并点名遵循了架构文档的哪条」,不硬编码具体值、不自造规则。
+`/comate` 要求 brief 的「决定」「约束与不变量」点名遵循了架构文档的哪条,不硬编码具体值、不自造规则。
 
 ## 建议包含的架构文档
 
@@ -26,6 +26,5 @@ PRD 门禁审阅时,会检查数据来源、接口契约、命名规范、错误
 
 ## 注意事项
 
-- 这些是**架构规则文档,不是 capability spec**,不放在 `openspec/specs/` 下。
-- 不参与 `openspec validate --strict`。
-- 由 `docs/knowledge-base/` 里的 PRD 引用,由 comate change 的 proposal/design 对齐。
+- 这些是**架构规则文档,不是 capability spec**,不放在 `comate/comate/specs/` 下。
+- 由 `comate/knowledge-base/` 里的 PRD 引用,由 comate change 的 brief 对齐。

package/skills/comate/scaffold/comate/comate/config.json

@@ -0,0 +1,10 @@
+{
+  "language": "zh-CN",
+  "build_command": null,
+  "verify_command": null,
+  "check_timeout_seconds": 900,
+  "max_verify_failures": 5,
+  "finish": "ask",
+  "auto_finish_action": null,
+  "protected_branches": ["main", "master"]
+}

package/skills/comate/scaffold/comate/knowledge-base/README.md

@@ -0,0 +1,42 @@
+# 知识库 (Knowledge Base)
+
+本目录承载**需求(PRD)与第三方对接**的长期文档,与代码同仓库、同 PR 评审、同版本。
+
+## 文档体系与交接
+
+```
+comate/knowledge-base/requirements/
+  ├─ _templates/              PRD 模板
+  └─ <YYYYMMDD-功能名>/        一个功能一个目录,日期=该功能起始日   ──┐
+       └─ PRD-001-<功能名>.md          产品需求文档                  │
+                                                                    ├─→ /comate (澄清+拆分+写规约)
+comate/knowledge-base/integrations/                                   │         ↓
+  第三方对接档案/索引 (跨需求长期存在)                              ──┘   comate changes
+```
+
+## PRD → comate 流程
+
+comate 只保留 **PRD**(产品需求文档)一层,由 `/comate` 直接读取:
+
+1. **澄清**:扫描 PRD 的隐含假设、未选定方案、边界与非功能约束;仓库事实先查证,产品决策逐项问用户。结论写进 change 的 `brief.md`「决定」,不改 PRD 本身;PRD 每段内容在 brief 的「来源覆盖」表里逐条登记。
+2. **拆分**:PRD 含多个可独立交付的功能簇时,按依赖/独立性给出「功能项 → change」建议,由用户确认。
+3. **写规约**:每个 change 用 brief.md + specs/<capability>/spec.md(完整目标规格)承接对应功能项;范围过大时拆成多个 change。
+
+PRD 被 `sources track` 钉为 change 的源文档(记录 sha256)。之后 PRD 被改,spec / build 守卫会报漂移,重读确认后重新 track 即可放行。
+
+## 命名约定
+
+- 功能目录：`<YYYYMMDD-功能名>/`
+- PRD：目录内 `PRD-<三位序号>-<功能名>.md`(推荐,便于检索;不强制)
+
+## 横向 (integrations/)
+
+- `integrations/` —— 第三方业务/接口对接档案与总索引,**跨多个需求长期存在**。
+- 单个 PRD 生命周期随功能上线收敛;本目录的内容长期维护,故独立放置。
+- PRD 的「第三方依赖」表应链接到 `integrations/<平台名>/README.md`。
+
+## 溯源与可追溯
+
+- PRD 顶部溯源块可选(若有更上游背景文档);没有上游时 PRD 是起点。
+- 每个 change 的 `state.json` 在 `sources` 里记录 PRD 路径与 sha256(`new --source` 钉住),形成 change → PRD 的链;PRD 之后被改,build / verify / archive 都会拦截。
+- 反查某份 PRD 派生了哪些 change:`comate.mjs sources find <PRD 路径>`。