@house365/comate 0.10.2 → 1.0.2-next.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Jian Liang
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Jian Liang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,53 +4,72 @@
 
 # comate
 
-**SDD (规约驱动开发)** 的 AI 开发编排器。
+**SDD（规约驱动开发）** 的 AI 开发编排器：每个变更先写规约、确认后再实现，实现由独立 verifier 逐项验收，通过后归档进主规格。
 
-comate 践行 **Specification-Driven Development (SDD)** 理念，通过五阶段工作流（gate → open → design → build → verify → archive）确保每个变更都有完整的规约与设计（fix 预设除外）。底层集成 **OpenSpec**（提案、规约生命周期、归档）和 **Superpowers**（技术设计、规划、执行、收尾），并提供 PRD 门禁、决策澄清、知识库对接等编排能力。
+1.0 只有一个 `/comate` skill 和一个零依赖的 Node 状态机，流程由脚本输出的 next（下一步指令）驱动。
 
-## 五阶段
+## 流程
 
 ```
-[原始 PRD] ─→ /comate-gate ─┐  (阶段 0:门禁+拆分)
-                              ▼
-/comate  ──自动探测阶段──────→ open → design → build → verify → archive
+/comate ── status ──┬─ 无 change ── new <name> [--mode full|fix] [--source <PRD>]
+                    └─ 有 change ── 按 next 继续
+
+open      澄清需求 → brief.md + specs/<能力>/spec.md → 脚本抽取验收项 A1…An → 【停①】用户确认
+build     按 brief/spec 实现并提交 → handoff（冻结候选 commit，脚本跑检查命令）
+verify    独立只读 verifier 逐项判定 passed / failed / blocked；失败自动回 build 修复
+          全部通过 →【停②】一次问完「接受结果 + 收尾方式」
+archive   完整目标 spec 写入主规格 → change 移入 archive/ → 提交 → keep / merge / push / pr
 ```
 
-| 阶段 | skill | 职责 |
-|------|-------|------|
-| gate | `/comate-gate` | (阶段 0,可选)对原始 PRD 做质量门禁 + 拆分成 N 个 change |
-| open | `/comate-open` | 探索想法,创建 change 结构并初始化 `.comate.yaml` |
-| design | `/comate-design` | 技术设计与方案 brainstorming |
-| build | `/comate-build` | 按任务实现并提交 |
-| verify | `/comate-verify` | 验证、出报告、处理分支 |
-| archive | `/comate-archive` | 同步增量规约并归档 |
-
-预设路径:`/comate-fix`(快速小改动,覆盖 bug 修复与文案/配置小调整两种模式)。
-
-工具 skill:
-- `/comate-grill`(决策点穷追式澄清)——对计划/设计/PRD 的模糊点逐个深挖,每问附推荐答案、一次一问,直到歧义清零。comate-gate 在阻断问题多、有依赖链时会自动提供「深度澄清」选项调用它;也可单独 `/comate-grill <话题>` 挑战自己的计划草稿。
-- `/comate-kb-integration`(第三方对接档案生成)——从官方文档 URL 抓取并按 `docs/knowledge-base/integrations/_TEMPLATE/` 规范产出对接档案(`<service-id>/README.md` + `api-snapshot.md`),自动追加根索引一行。是知识库 integrations scaffold 的配套建档工具;遇 JS 动态渲染文档站自动降级 Playwright 无头抓取。
-
-**阶段 0(PRD 门禁与拆分)**:需求若来自一份**原始 PRD**,先过 `/comate-gate`——它审阅 PRD 质量、百分制评分、建阻断台账,门禁通过前禁止建任何 change;通过后按依赖/独立性判定把 PRD 拆成 1 或 N 个 change(粒度由用户定),逐个交给 `/comate-open`。门禁状态钉在 PRD 同级 `<PRD>.gate.yaml`,PRD 通过后被改会自动失效需重跑。需求来自对话时无需此阶段,直接从 open 起步。
+**核心机制**
+- **脚本持有状态机**：每条命令返回 next（下一步做什么、执行哪条命令），agent 照做，不自己判断阶段；上下文压缩或新会话后跑 `status` 即可恢复
+- **原则驱动澄清**（本分支优化重点）：代码是唯一真相，文档服务于代码；不走机械清单，按实际需求深挖风险视角；full 模式三分类（仓库事实/产品决策/实现选择），fix 模式三个核心问题
+- **两套文档变一套**：需求只有 `brief.md`（为什么、做什么、关键决定、验收示例）和完整目标 `spec.md`；build 通过 handoff 的 `addressed` 交接实现进度
+- **验收是结构化数据**：验收项存在 `state.json`（ID 格式 A1、A2…），verifier 结果必须带回 token、覆盖全部 ID、每项恰好一次；过期结果、漏报、HEAD 变化都会被拒
+- **build ⇄ verify 是循环**：脚本记轮次、失败次数和无进展次数，到上限（最多 10 轮迭代，或连续 3 次失败且零进展）才停下问你
+- **只有两次固定停顿**：① open 确认（目标、范围、非目标、关键决定、全部验收项、change 名称）；② 验收全部通过后一次问完「接受结果 + 收尾方式」。merge / push / PR 只在你选择时执行
+- **fix 模式**：`new <name> --mode fix`，边界清楚的小修（bug 修复、小调整），走原则驱动三问（是什么、为什么、怎么验收），免确认直接进 build；边界不清时默认用 full
+- **需求来自 PRD**：`new <name> --source <PRD>` 钉住文件哈希，brief 的「来源覆盖」表逐段登记；PRD 之后被改，后续阶段都会拦截
+- **独立验收**：verifier 是未参与 build 的只读子 agent，可选用 `probe`（临时 worktree 反向验证：故意改错，看测试会不会失败）
 
 ## 安装
 
 ```bash
 npm install -g @house365/comate
+cd your-project
+comate init
 ```
 
-到项目目录初始化：
+`init` 检查 git，把 comate skill 装到用户级（`~/.agents/skills`，所有项目共用），并在项目根铺出 `comate/`：
 
-```bash
-cd your-project
-comate init
 ```
+comate/
+├─ comate/
+│  ├─ config.json        检查命令、失败上限、收尾方式、受保护分支
+│  ├─ specs/             主规格：已归档能力的完整行为
+│  ├─ changes/<name>/    进行中的变更（state.json、brief.md、specs/、verification.md）
+│  └─ archive/           已归档的变更
+├─ knowledge-base/       PRD（requirements/）与第三方对接档案（integrations/）
+└─ architecture/         架构约定
+```
+
+可重复执行，已有文件不覆盖。在 `comate/comate/config.json` 配置 `build_command` / `verify_command`；不配置时自动探测 npm / Maven / Cargo / Go，确实没有测试写 `"none"`。
 
-`init` 会装好 comate 及其依赖（OpenSpec CLI、Superpowers），创建 `openspec/` 项目结构，并铺出 `docs/` 知识库骨架（`docs/knowledge-base/requirements/` 放 PRD + PRD 模板、`docs/architecture/` 架构规范占位、integrations 对接模板）——`/comate-gate` 从这里读 PRD。支持 Claude Code、Codex、Cursor 等 70+ agent。可重复执行，已装的自动跳过，已有的 docs 文件不覆盖。
+装完在 agent 中输入 `/comate` 开始，`comate doctor` 自检，`comate status` 查看当前项目的 change。
 
-skills 装到用户级（`~/.agents/skills`），装一次所有项目共用；`openspec/` 是项目自己的规约，建在当前目录，所以 `init` 需要在项目目录下运行。
+**退出码**：
+- `0` 成功
+- `1` BLOCK（守卫拒绝，但仍输出 `next` 告知如何修复）
+- `2` USAGE（用法错误）
+- `3` ENV（环境缺失）
+- `4` CORRUPT（状态损坏，运行 `doctor`）
 
-装完输入 `/comate` 开始使用，`comate doctor` 可自检。
+## 从 0.x 升级
+
+- **进行中的旧 change**：1.0 不自动转换。先用 0.10.x 把手上的 change 做完，再升级。
+- **目录**：`comate init --migrate --dry-run` 列出 `docs/knowledge-base`、`docs/architecture` → `comate/` 的迁移（`git mv` 保留历史），确认后去掉 `--dry-run` 执行。`docs/` 其他内容不动。
+- **主规格**：`comate import-specs --dry-run` 列出 `openspec/specs/<能力>/spec.md` → `comate/comate/specs/` 的复制清单，确认后去掉 `--dry-run` 执行。`openspec/changes/archive/` 历史原样保留、只读。
+- `init` 会清理旧版 skill 目录（comate-gate / spec / build / verify / fix 等，只删 comate 自己的历史名单）。
 
 ## 更新
 
@@ -59,52 +78,73 @@ npm install -g @house365/comate@latest
 cd your-project && comate init
 ```
 
-两步都要跑：`npm` 只换 CLI 本身，skills 是 `comate init` 铺到 `~/.agents/skills` 的，npm 不管。这里的 `@latest` 不能省——本地已装时，不带 tag 的 `npm install -g` 可能认为已满足而不去 registry 取新版。
-
-## 用法
+两步都要跑：npm 只换 CLI，skills 由 `comate init` 铺到 `~/.agents/skills`。
+
+## 命令速查
+
+所有命令加 `--json` 输出机器可读结果。
+
+| 命令 | 说明 | 常用选项 |
+|------|------|----------|
+| `status [<name>]` | 当前位置 + 下一步（只读） | `--json` |
+| `new <name>` | 创建新 change | `--mode full\|fix` `--source <file>` `--base <branch>` |
+| `open <name>` | 校验 brief/spec 并抽取验收项 | `--prepare` `--confirm --expect <v>:<step>` |
+| `rename <old> <new>` | 重命名（仅 open 阶段） | - |
+| `spec <remove\|restore> <name> <capability>` | 登记/取消删除一个主能力 | - |
+| `handoff <name>` | 提交候选实现并跑检查 | `--input <handoff.json> --expect <v>:<step>` `--recheck` |
+| `verify <name>` | 提交验收结果 | `--result <json>` `--error "<原因>"` `--unavailable` |
+| `probe <name>` | 反向验证临时 worktree（改错看测试失败） | `--remove <dir>` |
+| `decide <name>` | 用户决策 | `--accept --finish keep\|merge\|pr\|push` `--revise-implementation` `--revise-requirements` `--resolve` `--upgrade` |
+| `archive <name>` | 归档并执行收尾 | `--dry-run` |
+| `doctor` | 诊断 + 修复状态 | `--repair` |
+| `import-specs` | 从 openspec/specs 导入 | `--dry-run` |
+
+**handoff.json 结构**：
+```json
+{
+  "summary": "本轮改了什么",
+  "addressed": ["A1", "A2"],       // 已实现的验收项 ID（必须精确匹配 state.json）
+  "manual_checks": [],              // 无法自动化的验收步骤
+  "known_limits": []                // 已知局限
+}
+```
 
-输入 `/comate` 自动探测当前阶段并分派,或直接调用某个阶段 skill。状态记录在每个 change 的 `openspec/changes/<name>/.comate.yaml` 中,支持上下文压缩后断点恢复。
+**verify-result.json 结构**：
+```json
+{
+  "token": "<verifier.token>",
+  "candidate": "<commit-sha>",
+  "acceptance": [
+    {"id": "A1", "result": "passed|failed|blocked", "reason": "证据：实现位置/测试名/手工步骤"}
+  ],
+  "reverse_checks": [],             // 反向验证结果（可选）
+  "risks": [],
+  "summary": ""
+}
+```
 
-## Token 用量:`comate usage`
+## Token 用量：`comate usage`
 
-查看**当前项目**的 token 消耗与估算成本(封装 [ccusage](https://github.com/ryoppippi/ccusage),随 comate 一起装):
+查看当前项目的 token 消耗与估算成本（封装 [ccusage](https://github.com/ryoppippi/ccusage)）：
 
 ```bash
-comate usage            # 本项目按会话(session)统计
+comate usage            # 本项目按会话统计
 comate usage daily      # 本项目按天
-comate usage --global   # 全部项目(不做项目隔离)
-comate usage --json -s 2026-08-01   # 其余参数原样透传给 ccusage
+comate usage --global   # 全部项目
 ```
 
-默认只统计当前工作目录这一个项目:Claude Code 数据按 `~/.claude/projects/<项目>/` 隔离,Codex 数据按会话记录里的 `cwd` 过滤,两者都不会混入其它项目的用量。加 `--global` 看全量,或用 `comate usage codex ...` 单看某个 agent。
-
-> 粒度到项目/会话级;不做 open/design/build 阶段级归因(那需要在状态机打时间戳,属后续增强)。
-
 ## 目录结构
 
 ```
 skills/
-  comate/            主编排器:SKILL.md + 脚本 + 参考文档 + 测试
-    scripts/         comate.sh(CLI)、comate-lib.sh(共享库)
-    reference/       决策点、脏工作树协议、前置条件
-    tests/           bats 测试
-  comate-open/ design/ build/ verify/ archive/   各阶段 skill
-  comate-gate/                                    阶段 0:PRD 门禁与拆分
-  comate-fix/                                     预设路径 skill(bug + 小调整)
-  comate-grill/                                   决策点穷追式澄清工具
-  comate-kb-integration/                          第三方对接档案生成工具(知识库配套)
-docs/
-  COMATE_BEGINNER_GUIDE.md  面向新手的安装与使用手册
-  COMATE_MANUAL.md   完整操作手册
+  comate/
+    SKILL.md             规则 + next 处理 + 按阶段读取索引
+    reference/           open / build / verify / archive / fix
+    scripts/comate.mjs   状态机入口（lib/ 下按职责拆分，零依赖）
+    scaffold/comate/     comate init 铺到项目的 comate/ 骨架
+  comate-kb-integration/ 第三方对接档案生成工具
+bin/                     CLI：init / doctor / status / import-specs / update / usage
+test/                    node:test 端到端用例
 ```
 
-## 文档
-
-文档：
-
-- [入门操作手册](docs/COMATE_BEGINNER_GUIDE.md)：面向第一次使用 comate 的同学，覆盖安装、`init`、目录、PRD、Skill 流程和常见问题。
-- [完整技术手册](docs/COMATE_MANUAL.md)：安装前置、命令参考、阶段详解、状态文件字段、决策阻塞点、故障排除。
-
-## License
-
-[MIT](LICENSE)
+完整说明见 [docs/COMATE_MANUAL.md](docs/COMATE_MANUAL.md)。