@house365/comate 0.9.18 → 0.9.19

package/docs/COMATE_BEGINNER_GUIDE.md

@@ -1,45 +1,33 @@
-# comate 入门操作手册
+# comate 入门指南
 
-这是一份给第一次使用 comate 的同学看的操作手册。按“安装 → 初始化 → 输入 /comate”的顺序，就可以开始使用。
+这份指南覆盖 comate 的安装、初始化和日常使用。
 
 ## 1. comate 是什么
 
-comate 是一个 AI 编程流程编排器。它把一次需求变更拆成几个可以检查的阶段，让 AI 先理解需求和设计，再写代码，最后验证并归档。
-
-完整流程：
+comate 是一个面向 AI 编程工具的 SDD（规约驱动开发）编排器。它把一次需求变更按阶段推进：
 
 ```text
 原始 PRD（可选）
-    ↓
-/comate-gate   PRD 门禁和拆分
-    ↓
-/comate-open   开题，创建 change
-    ↓
-/comate-design 深度设计
-    ↓
-/comate-build  计划和编码
-    ↓
-/comate-verify 验证和收尾
-    ↓
-/comate-archive 归档规格
+    -> gate -> open -> design -> build -> verify -> archive
 ```
 
-- **OpenSpec** 负责“要做什么”：proposal、spec、tasks 和归档。
-- **Superpowers** 负责“怎么做好”：头脑风暴、技术设计、计划、执行和验证。
-- **comate** 负责识别当前阶段，并把这些能力串起来。
+通常只需要使用 `/comate`，它会根据当前项目状态自动进入下一阶段。
 
-## 2. 安装前准备
+- `/comate-gate`：审阅 PRD，并在需要时拆分变更。
+- `/comate-fix`：处理 Bug 或很小的文案、配置调整。
+- `/comate-grill`：逐个澄清 PRD、设计或计划中的关键决策。
+- `/comate-kb-integration`：根据第三方官方文档生成对接档案。
 
-### 2.1 必需软件
+## 2. 安装前准备
 
-| 软件 | 建议版本 | 用途 |
-| --- | --- | --- |
-| Node.js | 20 或更高 | 运行 comate 和 npm |
-| npm | 随 Node.js 安装 | 安装 comate、OpenSpec |
-| Git | 任意现代版本 | 管理代码和分支 |
-| Bash | 3.2 或更高 | 执行 comate 的状态机脚本 |
+需要以下环境：
 
-Windows 用户建议安装 [Git for Windows](https://git-scm.com/download/win)，它会提供 Git Bash。PowerShell 可以运行 `comate`，但流程脚本仍需要 Bash。
+| 软件 | 要求 |
+| --- | --- |
+| Node.js | 20 或更高版本 |
+| npm | 随 Node.js 安装 |
+| Git | 任意现代版本 |
+| Bash | 3.2 或更高版本 |
 
 检查环境：
 
@@ -50,380 +38,151 @@ git --version
 bash --version
 ```
 
-### 2.2 哪些步骤需要网络
+Windows 用户请安装 [Git for Windows](https://git-scm.com/download/win)，以提供 Git Bash。PowerShell 可以运行 `comate`，但 comate 的流程脚本仍需要 Bash。
 
-首次初始化时，`comate init` 可能需要访问 npm registry 安装 OpenSpec CLI，并访问 GitHub 安装 Superpowers。
+首次初始化会访问 npm registry 和 GitHub，用于安装 OpenSpec CLI 与 Superpowers。
 
-comate 自己的 npm 包会随包携带 comate skill。npm 安装钩子只会尽力同步 comate 自身 skill，不会安装 Superpowers，也不会创建项目的 `openspec/` 和 `docs/`；这些由项目目录中的 `comate init` 完成。
+## 3. 安装并初始化项目
 
-## 3. 安装 comate
-
-全局安装：
+先安装 comate：
 
 ```bash
 npm install -g @house365/comate
 ```
 
-确认命令可用：
-
-```bash
-comate --version
-comate --help
-```
-
-安装后，skill 通常会同步到用户级目录：
-
-- macOS/Linux：`~/.agents/skills/`
-- Windows：`%USERPROFILE%\.agents\skills\`
-
-用户级 skill 可以被多个项目共用。项目自己的规格文件放在项目目录下的 `openspec/`。
-
-## 4. 初始化项目：`comate init`
-
-进入项目根目录再运行：
+然后进入业务项目根目录初始化：
 
 ```bash
 cd path/to/your-project
 comate init
+comate doctor
 ```
 
-Windows PowerShell 示例：
-
-```powershell
-Set-Location D:\work\my-project
-comate init
-```
-
-请不要在用户主目录直接运行。comate 会检查当前目录是否有 `.git`、`package.json`、`pyproject.toml`、`Cargo.toml` 等项目标记；空目录会先询问是否确认初始化。
-
-### 4.1 `init` 会做什么
-
-1. 检查 Bash 版本。
-2. 检查 OpenSpec，不存在或版本过旧时执行 `npm install -g @fission-ai/openspec@latest`。
-3. 检查 Superpowers，不存在时执行 `skills add obra/superpowers -g -y`。
-4. 把 comate 自身 skill 同步到用户级 skill 目录。
-5. 创建项目级 `openspec/`（已经存在则保留）。
-6. 创建 `docs/` 知识库骨架（只补缺少的文件，不覆盖已有文件）。
-
-某一步失败时，修好网络或环境后重新运行 `comate init` 即可。它是幂等的，已完成的步骤会跳过。
-
-## 5. 初始化后的目录结构
-
-```text
-your-project/
-├─ openspec/
-│  ├─ changes/              # 每次需求变更的工作区
-│  └─ specs/                # 已沉淀的主规格
-├─ docs/
-│  ├─ README.md
-│  ├─ architecture/
-│  │  └─ README.md
-│  └─ knowledge-base/
-│     ├─ README.md
-│     ├─ requirements/
-│     │  └─ _templates/PRD.md
-│     └─ integrations/
-│        ├─ README.md
-│        └─ _TEMPLATE/
-└─ 你的业务代码...
-```
-
-### 5.1 `openspec/`：项目规格
-
-- `changes/<change-name>/`：正在进行的变更，包含 `proposal.md`、`design.md`、`tasks.md`、delta spec 和 `.comate.yaml`。
-- `specs/<capability>/spec.md`：归档后长期维护的能力规格。
-- `changes/archive/`：已经完成并归档的 change。
-
-`.comate.yaml` 是 comate 的状态真相源，记录当前阶段、构建模式、验证结果等。
-
-### 5.2 `docs/`：长期知识库
-
-- `docs/`：项目背景、架构约束、原始 PRD、第三方对接资料。
-- `openspec/`：某次变更的提案、设计、任务、能力规格和归档记录。
-
-### 5.3 用户级 skill 目录
-
-```text
-~/.agents/skills/                  # macOS/Linux
-%USERPROFILE%\.agents\skills\     # Windows
-```
-
-已有的 Superpowers 或其他 skill 不会因为 `comate init` 被覆盖。
-
-## 6. `docs/` 目录详解
-
-### 6.1 `docs/README.md`
-
-说明知识库整体规则、`architecture/` 与 `knowledge-base/` 的边界，以及它们和 `openspec/` 的关系。
-
-### 6.2 `docs/architecture/`
-
-放项目架构约束，例如前后端分层、API/数据库/错误码约定、命名规范和部署约束。`comate init` 只创建占位 README，真正的规则需要项目自己补充。这里是 `/comate-gate` 检查契约时的事实来源。
-
-### 6.3 `docs/knowledge-base/`
-
-放长期维护的需求和外部服务资料：
-
-- `requirements/`：原始 PRD；
-- `integrations/`：第三方服务对接档案；
-- `README.md`：命名、溯源和 PRD 到 change 的流程说明。
-
-### 6.4 `docs/knowledge-base/requirements/`
-
-这里是 PRD 的固定位置。模板位于：
-
-```text
-docs/knowledge-base/requirements/_templates/PRD.md
-```
-
-复制模板到功能目录，填写后运行 `/comate-gate`。
-
-### 6.5 `docs/knowledge-base/integrations/`
-
-每个第三方平台建立一个子目录，例如：
-
-```text
-docs/knowledge-base/integrations/alipay/README.md
-docs/knowledge-base/integrations/alipay/api-snapshot.md
-```
+`comate init` 会：
 
-需要从官方文档生成对接档案时，使用 `/comate-kb-integration`。
+1. 安装或检查 OpenSpec CLI、Superpowers 和 comate skills。
+2. 在用户级目录安装 skills（通常是 `~/.agents/skills/`；Windows 为 `%USERPROFILE%\.agents\skills\`）。
+3. 在当前项目创建 `openspec/` 和 `docs/` 知识库骨架。
 
-## 7. PRD 存放位置和命名规范
+已有文件不会被覆盖，初始化可以重复执行。请在项目目录运行，不要直接在用户主目录运行。
 
-推荐格式：
+初始化后，项目通常会多出：
 
 ```text
-docs/knowledge-base/requirements/<YYYYMMDD-功能名>/PRD-<三位序号>-<功能名>.md
+openspec/                          # 变更和长期规格
+docs/knowledge-base/requirements/ # PRD
+docs/architecture/                # 架构约束
 ```
 
-示例：
+## 4. 第一次使用
 
-```text
-docs/knowledge-base/requirements/20260820-用户登录/PRD-001-用户登录.md
-```
-
-规则：
-
-1. 功能目录使用“日期 + 功能名”，日期格式为 `YYYYMMDD`。
-2. PRD 文件以 `PRD-001`、`PRD-002` 这样的三位序号开头。
-3. 文件名中的功能名应和目录功能名保持一致。
-4. 同一个功能目录中的序号不要重复。
-5. 不建议使用 `PRD-1.md` 或把 PRD 放到 `openspec/changes/`。
-
-`/comate-gate` 会在 PRD 同级自动生成：
+在 Claude Code、Codex、Cursor 等支持 Agent Skills 的工具中输入：
 
 ```text
-PRD-001.gate.yaml       # 机器读取的门禁状态
-PRD-001-REVIEW.md       # 人类可读的评审报告
+/comate 我想增加用户登录功能，支持邮箱和密码登录
 ```
 
-PRD 通过门禁后如果又被修改，哈希会变化，门禁会变成过期状态，需要重新运行 `/comate-gate`。
+comate 会创建并推进一个 change。过程中只在需要你决定时提问；确认设计、实现和验证结果后，流程会完成归档。
 
-## 8. 从需求到代码的 Skill 流程
+### 需求来自 PRD
 
-### 8.1 需求来自一份 PRD
-
-先把 PRD 放到 `docs/knowledge-base/requirements/`，然后直接指定 PRD 路径：
+复杂需求可以先把 PRD 放在 `docs/knowledge-base/requirements/`，然后直接指定文件：
 
 ```text
 /comate docs/knowledge-base/requirements/20260820-用户登录/PRD-001-用户登录.md
 ```
 
-`/comate` 会识别这是原始 PRD，自动进入 PRD 门禁和拆分流程；不需要先手动调用 `/comate-gate`。门禁通过后，它会继续处理拆分出来的 change。
-
-如果只想单独审阅或重新运行门禁，也可以直接输入：
+这会自动进入 PRD 门禁和拆分流程。只想单独审阅 PRD 时使用：
 
 ```text
-/comate-gate docs/knowledge-base/requirements/20260820-用户登录/PRD-001-用户登录.md
+/comate-gate path/to/PRD.md
 ```
 
-对已有 change 继续工作时，输入：
-
-```text
-/comate
-```
-
-comate 会自动从当前阶段继续：`open → design → build → verify → archive`。
-
-### 8.2 需求来自普通对话
-
-不需要先写 PRD，直接输入：
-
-```text
-/comate 我想增加用户登录功能，支持邮箱和密码登录
-```
-
-复杂需求仍建议先整理成 PRD，便于评审和追踪。
-
-### 8.3 Bug 或很小的调整
+### Bug 或小调整
 
 ```text
 /comate-fix 修复登录失败时页面没有提示的问题
 ```
 
-它走简化流程：`open → build → verify → archive`，跳过完整 brainstorming。涉及新能力、架构变化、数据库 schema 或多个模块时，应升级回完整 `/comate` 流程。
-
-## 9. Skill 介绍
-
-| Skill | 作用 |
-| --- | --- |
-| `/comate` | 总入口，自动检测当前 change 阶段并分派 |
-| `/comate-gate` | 审阅 PRD、评分、记录阻断问题并拆分 change |
-| `/comate-open` | 探索需求，创建 change 和 proposal/design/tasks 骨架 |
-| `/comate-design` | 技术设计和方案头脑风暴，形成 Design Doc 和 delta spec |
-| `/comate-build` | 制定实施计划、按任务编码并更新 tasks |
-| `/comate-verify` | 运行测试和检查，生成验证报告并处理分支收尾 |
-| `/comate-archive` | 同步 delta spec、标记设计文档并归档 change |
-| `/comate-fix` | Bug 或小调整的快速路径 |
-| `/comate-grill` | 对 PRD、计划或设计中的模糊决策逐个追问 |
-| `/comate-kb-integration` | 根据第三方官方文档生成 integrations 对接档案 |
-
-### 9.1 底层依赖分工
+如果改动涉及新能力、架构、数据库结构或多个模块，请改用完整的 `/comate` 流程。
 
-- **OpenSpec**：负责 `openspec/`、change 规格和归档。
-- **Superpowers**：由 `comate init` 通过 `skills` CLI 从 `obra/superpowers` 安装，负责设计、规划、执行和收尾。
-- **comate skill**：本项目提供的编排规则和状态机。
+### 中断后继续
 
-首次使用时，如果 Superpowers 安装失败，design/build/verify 相关流程不能完整运行。先修复网络或手工安装，再重跑 `comate init`。
+回到同一个项目目录，再输入：
 
-## 10. 常用命令
-
-### 10.1 安装和检查
-
-```bash
-comate --help
-comate --version
-comate init
-comate doctor
+```text
+/comate
 ```
 
-### 10.2 查看 token 用量
+comate 会读取 `openspec/changes/<change-name>/.comate.yaml`，从当前阶段继续。
 
-```bash
-comate usage
-comate usage daily
-comate usage --global
-comate usage --json
-```
-
-## 11. 配套 UI 查看器
+## 5. 配套 UI（可选）
 
-`comate-ui` 是 comate 的本地只读浏览器工作区，用来可视化查看项目中的变更状态、OpenSpec 规格、PRD、Superpowers 设计文档、计划和验证报告。它不会修改项目文件，也不需要数据库。
+Comate UI 是本地只读的可视化工作台，用于查看 change 状态、规格、PRD、实施计划和验证结果，不会修改项目文件。
 
-全局安装：
+安装：
 
 ```bash
 npm install -g @house365/comate-ui@latest
 ```
 
-安装后，在包含 `openspec/` 的项目根目录运行：
+在已经执行过 `comate init` 的项目根目录启动：
 
 ```bash
 comate-ui
 ```
 
-也可以指定项目路径、端口或禁止自动打开浏览器：
+启动后会自动打开浏览器。服务只监听本机 `127.0.0.1`，按 `Ctrl+C` 停止。也可以不安装直接运行，或指定项目和端口：
 
 ```bash
-comate-ui D:\work\my-project
-comate-ui D:\work\my-project --port 4300
-comate-ui --no-open
+npx @house365/comate-ui@latest
+comate-ui path/to/your-project --port 4300
+comate-ui --no-open # 不自动打开浏览器
+comate-ui --demo    # 查看内置示例
 ```
 
-查看内置示例：
+## 6. 常用命令
 
 ```bash
-comate-ui --demo
+comate --help         # 查看命令帮助
+comate --version      # 查看版本
+comate doctor         # 检查 Bash、OpenSpec 和 skills
+comate update         # 更新到 npm 最新版本
+comate usage          # 查看当前项目 token 用量
+comate usage daily    # 按天查看
+comate usage --global # 查看全部项目
 ```
 
-查看器只绑定本机 `127.0.0.1`。默认会自动打开浏览器；端口被占用时会自动选择下一个可用端口，按 `Ctrl+C` 停止。
-
-## 12. 更新 comate
+更新后建议在各项目根目录重新执行一次 `comate init`，把新版 skills 同步到用户级目录：
 
 ```bash
-npm install -g @house365/comate@latest
+comate update
 cd path/to/your-project
 comate init
 ```
 
-npm 更新 CLI 和包内文件；`comate init` 负责把新版 comate skill 同步到用户级目录，并补齐当前项目缺少的 `openspec/`、`docs/` 文件。
-
-更新是幂等的：已有 Superpowers 不覆盖，已有项目规格和 docs 文件不覆盖。若使用 `npm install --ignore-scripts`，请手动执行 `comate init`。
-
-## 13. 网络问题和手工补装
-
-### OpenSpec 安装失败
-
-```bash
-npm install -g @fission-ai/openspec@latest
-openspec --version
-```
-
-### Superpowers 安装失败
+## 7. 常见问题
 
-```bash
-skills add obra/superpowers -g -y
-```
+### `comate init` 失败
 
-GitHub 无法访问时，可以配置 npm/Git 代理、使用公司网络或 Git Bash/WSL，安装成功后再运行：
+先运行：
 
 ```bash
-comate init
 comate doctor
 ```
 
-当前 npm 包没有内置 Superpowers 离线快照；不要把“npm 安装成功”理解成 Superpowers 已安装完成。
-
-## 14. 常见问题
-
-### `comate init` 应该在哪运行？
-
-在业务项目根目录运行，也就是能看到 `.git` 或 `package.json` 的目录。不要在 `C:\Users\你的用户名` 或 `~` 直接运行。
-
-### npm 安装后为什么还要 `comate init`？
-
-npm 只安装 CLI 和包本身。`init` 才会准备 OpenSpec、Superpowers 与 comate skill，并创建当前项目的 `openspec/`、`docs/`。
-
-### 重跑 init 会不会覆盖我的文件？
-
-不会。已有 skill、`openspec/`、docs 文件会保留，只补缺少的内容。
-
-### 找不到 `openspec` 怎么办？
-
-重开终端让全局 npm PATH 生效，然后运行 `openspec --version`。仍找不到就执行 `npm install -g @fission-ai/openspec@latest`，再运行 `comate init`。
-
-### 找不到 Bash 怎么办？
-
-Windows 安装 Git for Windows；macOS 自带的 Bash 3.2 可以直接使用，不需要另外安装 Bash 4+。
-
-### 流程中断了怎么办？
-
-回到同一个项目目录，再输入 `/comate`。comate 会读取 `openspec/changes/<name>/.comate.yaml` 和已有产物，从当前阶段继续。先运行 `comate doctor` 可以排除环境问题。
-
-### 有多个 change 怎么办？
-
-在对话中明确 change 名称。不要同时修改多个 change 的 `tasks.md`。
-
-## 15. 新手最短上手路径
+如果是网络问题，确认 npm registry 和 GitHub 可访问，修复代理或网络后重新运行 `comate init`。也可以手动补装：
 
 ```bash
-npm install -g @house365/comate
-cd your-project
+npm install -g @fission-ai/openspec@latest
+skills add obra/superpowers -g -y
 comate init
-comate doctor
 ```
 
-然后在 Claude Code、Codex、Cursor 等支持 Agent Skills 的工具中输入：
-
-```text
-/comate 我想实现一个用户登录功能
-```
+### 找不到 `openspec` 或 Bash
 
-等待 AI 在需要你决定的地方提问，确认设计和构建选项后，让流程走到验证和归档。
+重开终端让全局 npm PATH 生效。Windows 请安装 Git for Windows，并确认 `bash --version` 不低于 3.2。
 
-## 16. 进一步阅读
+### 重跑 `init` 会覆盖项目文件吗？
 
-- [完整技术手册](COMATE_MANUAL.md)：状态字段、门禁规则、脚本接口和故障排查。
-- [项目 README](../README.md)：项目概览和快速安装。
-- 初始化后生成的 `docs/knowledge-base/README.md`：PRD 溯源和命名规则。
+不会。`init` 只补充缺少的 skills、`openspec/` 和 `docs/` 文件，已有内容会保留。

package/docs/COMATE_INIT_DIRECTORY_GUIDE.md

@@ -0,0 +1,201 @@
+# comate init 目录说明
+
+`comate init` 会同时准备两类内容：用户级 skills，以及当前项目的 OpenSpec 和知识库目录。
+
+## 1. 初始化时会发生什么
+
+在项目根目录运行：
+
+```bash
+comate init
+```
+
+它会：
+
+- 将 comate、OpenSpec 和 Superpowers 相关 skills 安装到用户级 skills 目录。
+- 在当前项目创建 `openspec/`。
+- 在当前项目补齐 `docs/` 知识库骨架。
+- 保留已经存在的文件，不覆盖项目已有内容。
+
+项目目录通常会得到以下结构：
+
+```text
+your-project/
+├── openspec/
+│   ├── config.yaml
+│   ├── changes/
+│   │   └── archive/
+│   └── specs/
+└── docs/
+    ├── README.md
+    ├── architecture/
+    │   └── README.md
+    └── knowledge-base/
+        ├── README.md
+        ├── requirements/
+        │   └── _templates/
+        │       └── PRD.md
+        └── integrations/
+            ├── README.md
+            └── _TEMPLATE/
+                ├── README.md
+                └── api-snapshot.md
+```
+
+## 2. 用户级 skills
+
+默认目录：
+
+```text
+macOS/Linux: ~/.agents/skills/
+Windows:     %USERPROFILE%\.agents\skills\
+```
+
+这里保存可被多个项目共用的 skills。常见目录包括：
+
+| 目录 | 用途 |
+| --- | --- |
+| `comate/` | comate 总入口、状态脚本和共享规则 |
+| `comate-open/` | 创建 change，生成初始产物 |
+| `comate-design/` | 技术设计和方案确认 |
+| `comate-build/` | 计划和代码实现 |
+| `comate-verify/` | 测试、验证和分支收尾 |
+| `comate-archive/` | 归档 change 并同步规格 |
+| `comate-fix/` | Bug 或小调整的快速流程 |
+| `comate-gate/` | PRD 门禁和拆分 |
+| `comate-grill/` | 澄清关键决策 |
+| `comate-kb-integration/` | 生成第三方对接档案 |
+| `openspec-*/` | OpenSpec 提供的配套 skills |
+
+通常不需要手动修改这些目录。升级 comate 后，在项目根目录重新运行 `comate init`，即可同步新版 comate skills。
+
+## 3. 项目级 `openspec/`
+
+`openspec/` 保存当前项目的变更规格，是项目自己的文件，应纳入版本控制。
+
+### `openspec/config.yaml`
+
+OpenSpec 的项目配置文件，记录当前项目使用的规格 schema。通常由初始化命令创建；已有配置会保留，不要随意删除。
+
+### `openspec/changes/`
+
+每个进行中的需求或修复对应一个 change：
+
+```text
+openspec/changes/<change-name>/
+├── .comate.yaml
+├── proposal.md
+├── design.md
+├── tasks.md
+├── specs/<capability>/spec.md
+└── .comate/
+    ├── handoff/
+    └── sources.manifest
+```
+
+这些文件由 `/comate`、`/comate-fix` 及各阶段 skill 逐步生成：
+
+- `.comate.yaml`：comate 当前阶段和验证状态的事实来源。
+- `proposal.md`：为什么做、做什么、范围和非目标。
+- `design.md`：高层设计、方案选择和数据流。
+- `tasks.md`：实施任务清单，完成一项勾选一项。
+- `specs/<capability>/spec.md`：本次变更的增量能力规格。
+- `.comate/handoff/`：阶段之间自动生成的交接上下文。
+- `.comate/sources.manifest`：需求源文件的追踪清单，仅在需求来自文件时出现。
+
+`openspec/changes/archive/` 在初始化时就会创建。`<change-name>` 完成并归档后，会移动到：
+
+```text
+openspec/changes/archive/YYYY-MM-DD-<change-name>/
+```
+
+### `openspec/specs/`
+
+这里保存已经沉淀的长期能力规格：
+
+```text
+openspec/specs/<capability>/spec.md
+```
+
+归档 change 时，增量规格会合并到对应的主规格中。
+
+## 4. 项目级 `docs/`
+
+`docs/` 保存跨多个 change 长期有效的项目文档。初始化只创建骨架，具体内容需要项目团队补充。
+
+### `docs/README.md`
+
+说明 `docs/` 的整体边界，以及架构文档、知识库和 `openspec/` 的分工。一般不需要频繁修改。
+
+### `docs/architecture/`
+
+保存项目架构约束，例如：
+
+- 前后端分层和模块依赖；
+- API、DTO、数据库和错误码约定；
+- 命名、日志、测试和部署规范。
+
+初始化时只有占位说明。项目应根据实际技术栈补充正式规则。涉及架构约束的 PRD，门禁会以这里的内容作为对齐依据。
+
+### `docs/knowledge-base/`
+
+保存需求和第三方服务资料。
+
+#### `requirements/`
+
+存放原始 PRD。推荐按功能和日期组织：
+
+```text
+docs/knowledge-base/requirements/<YYYYMMDD-功能名>/
+├── PRD-001-功能名.md
+├── PRD-001.gate.yaml
+└── PRD-001-REVIEW.md
+```
+
+`_templates/PRD.md` 是新建 PRD 的模板。`.gate.yaml` 和 `-REVIEW.md` 由 `/comate-gate` 生成，不需要手动创建。
+
+#### `integrations/`
+
+保存第三方服务的长期对接档案：
+
+```text
+docs/knowledge-base/integrations/<service-id>/
+├── README.md
+└── api-snapshot.md
+```
+
+`_TEMPLATE/` 只存模板，不代表真实服务。接入新服务时，复制模板或使用 `/comate-kb-integration` 生成档案，并维护 `integrations/README.md` 中的服务索引。
+
+## 5. 后续流程会新增的目录
+
+以下目录不是 `comate init` 必然立即创建的，而是在对应阶段产生：
+
+```text
+docs/superpowers/
+├── specs/   # design 阶段的设计文档
+├── plans/   # build 阶段的实施计划
+└── reports/ # verify 阶段的验证报告
+```
+
+如果项目暂时没有进行中的 change，这些目录不存在是正常的。
+
+## 6. 哪些内容应提交到 Git
+
+建议提交项目级内容：
+
+- `openspec/`
+- `docs/architecture/`
+- `docs/knowledge-base/`
+- 已生成的 `docs/superpowers/`
+
+用户级 `~/.agents/skills/` 或 `%USERPROFILE%\.agents\skills\` 属于本机环境，不放进项目仓库。
+
+## 7. 重跑 init
+
+`comate init` 是幂等的：
+
+- 已安装的依赖和 skills 会跳过或复用；
+- 已存在的 `openspec/` 和 `docs/` 文件会保留；
+- 缺少的目录或模板文件会补齐。
+
+因此升级 comate 后，可以安全地在每个项目根目录重新运行一次 `comate init`。

package/docs/COMATE_MANUAL.md

@@ -595,7 +595,8 @@ bash "$COMATE" doctor
 | `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>` | 记录据此 PRD 扇出的 change（逗号拼接） |
+| `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 阻塞 |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@house365/comate",
-  "version": "0.9.18",
+  "version": "0.9.19",
   "description": "comate —— SDD (规约驱动开发) 的 AI 开发编排器（Agent Skills）",
   "type": "module",
   "license": "MIT",

package/skills/comate/scripts/comate.sh

@@ -21,6 +21,7 @@
 #   gate    <prd> set <field> <value>        — write score | blocking_open | gate_status | …
 #   gate    <prd> pass [--tbd]               — pass clean gate or explicitly accepted TBD blockers
 #   gate    <prd> spawned <change>           — record a change fanned out from this PRD
+#   gate    <prd> fanout-status [--json]     — report mapped/spawned fanout progress
 #   gate    <prd> status [--json]            — print gate status (computes stale on hash drift)
 #   gate    <prd> check                      — precondition guard before spawning a change
 #   archive <name> [--dry-run]               — sync delta specs + annotate + move + mark archived
@@ -62,6 +63,7 @@ Usage: comate.sh <command> ...
   gate    <prd> set <field> <value>         score | blocking_open | gate_status | …
   gate    <prd> pass [--tbd]                pass: zero blockers; --tbd: accepted blockers
   gate    <prd> spawned <change>            record a change fanned out from this PRD
+  gate    <prd> fanout-status [--json]      report mapped/spawned fanout progress
   gate    <prd> status [--json]
   gate    <prd> check                       precondition guard before spawning a change
   archive <name> [--dry-run]
@@ -1471,10 +1473,52 @@ gate_set() {
   [ -n "$field" ] || die "$COMATE_USAGE" "Usage: comate.sh gate <prd> set <field> <value>"
   local gate; gate=$(gate_path_for "$prd")
   [ -f "$gate" ] || die "$COMATE_CORRUPT" "ERROR: gate not found (run 'gate review' first): $gate"
+  if [ "$field" = "changes_map" ]; then
+    gate_validate_changes_map "$value"
+    local current_map current_status
+    current_map=$(yaml_get "$gate" changes_map)
+    current_status=$(yaml_get "$gate" gate_status)
+    case "$current_status" in
+      passed|passed-with-tbd)
+        [ "$value" = "$current_map" ] || \
+          die "$COMATE_BLOCK" "BLOCK: changes_map is immutable after gate pass; re-run gate review before remapping"
+        ;;
+    esac
+  fi
   gate_yaml_set "$gate" "$field" "$value"
   log_pass "[GATE] set $field=$value"
 }
 
+# gate_validate_changes_map <changes_map> — reject malformed entries and
+# duplicate names when the user-confirmed mapping is first persisted.
+gate_validate_changes_map() {
+  local map="$1" rest entry name items seen=""
+  [ -n "$map" ] && [ "$map" != "null" ] || \
+    die "$COMATE_USAGE" "ERROR: changes_map cannot be empty"
+  case "$map" in
+    \;*|*\;\;*|*\;) die "$COMATE_USAGE" "ERROR: changes_map contains an empty entry" ;;
+  esac
+  rest="$map"
+  while [ -n "$rest" ]; do
+    case "$rest" in
+      *\;*) entry="${rest%%;*}"; rest="${rest#*;}" ;;
+      *) entry="$rest"; rest="" ;;
+    esac
+    name="${entry%%:*}"
+    items="${entry#*:}"
+    [ -n "$name" ] && [ "$name" != "$entry" ] || \
+      die "$COMATE_USAGE" "ERROR: malformed changes_map entry '$entry'"
+    [ -n "$(printf '%s' "$items" | tr -d '[:space:]')" ] || \
+      die "$COMATE_USAGE" "ERROR: empty function mapping for change '$name'"
+    validate_change_name "$name"
+    case ",$seen," in
+      *",$name,"*) die "$COMATE_USAGE" "ERROR: duplicate change '$name' in changes_map" ;;
+    esac
+    [ -n "$seen" ] && seen="$seen,"
+    seen="$seen$name"
+  done
+}
+
 # gate <prd> pass [--tbd] — flip to passed/passed-with-tbd. Normal pass requires
 # zero blockers; --tbd requires at least one explicitly accepted blocker.
 gate_pass() {
@@ -1501,6 +1545,7 @@ gate_pass() {
   if [ -z "$changes_map" ] || [ "$changes_map" = "null" ]; then
     die "$COMATE_BLOCK" "BLOCK: changes_map is required before passing the gate"
   fi
+  gate_validate_changes_map "$changes_map"
   local report; report=$(yaml_get "$gate" review_report)
   if [ -z "$report" ] || [ "$report" = "null" ] || ! file_nonempty "$report"; then
     die "$COMATE_BLOCK" "BLOCK: review report missing or empty ($report) — the gate report is mandatory"
@@ -1524,10 +1569,15 @@ gate_spawned() {
   validate_change_name "$change"
   local gate; gate=$(gate_path_for "$prd")
   [ -f "$gate" ] || die "$COMATE_CORRUPT" "ERROR: gate not found: $gate"
+  local changes_map; changes_map=$(yaml_get "$gate" changes_map)
+  gate_change_is_mapped "$changes_map" "$change" || \
+    die "$COMATE_BLOCK" "BLOCK: change '$change' is not present in changes_map"
   local cur; cur=$(yaml_get "$gate" spawned_changes)
   case ",$cur," in
     *",$change,"*) log_info "[GATE] $change already recorded" ; return 0 ;;
   esac
+  gate_check "$prd" >/dev/null
+  gate_require_skeleton "$prd" "$change"
   if [ -z "$cur" ] || [ "$cur" = "null" ]; then
     gate_yaml_set "$gate" spawned_changes "$change"
   else
@@ -1536,6 +1586,118 @@ gate_spawned() {
   log_pass "[GATE] recorded spawned change: $change"
 }
 
+# gate_require_skeleton <prd> <change> — prove that comate-open finished the
+# gate skeleton before it is counted as spawned.
+gate_require_skeleton() {
+  local prd="$1" change="$2" dir yaml manifest tracked_prd f
+  dir=$(comate_change_dir "$change")
+  for f in .openspec.yaml proposal.md design.md tasks.md .comate.yaml; do
+    file_nonempty "$dir/$f" || \
+      die "$COMATE_BLOCK" "BLOCK: change '$change' skeleton incomplete: missing or empty $dir/$f"
+  done
+  yaml="$dir/.comate.yaml"
+  validate_flat_yaml "$yaml"
+  [ "$(yaml_get "$yaml" phase)" = "open" ] || \
+    die "$COMATE_BLOCK" "BLOCK: change '$change' skeleton must remain in phase=open"
+  [ "$(yaml_get "$yaml" source_kind)" = "file" ] || \
+    die "$COMATE_BLOCK" "BLOCK: change '$change' skeleton has not tracked its PRD source"
+  manifest=$(yaml_get "$yaml" source_manifest)
+  [ -n "$manifest" ] && [ "$manifest" != "null" ] && [ -f "$manifest" ] || \
+    die "$COMATE_BLOCK" "BLOCK: change '$change' source manifest is missing"
+  tracked_prd=$(validate_kb_path "$prd") || \
+    die "$COMATE_BLOCK" "BLOCK: PRD source path is outside the knowledge base: $prd"
+  local record_ok=0 line record_path="" record_hash=""
+  while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in
+      path:*) record_path="${line#path:}"; record_hash="" ;;
+      sha256:*)
+        record_hash="${line#sha256:}"
+        if [ "$record_path" = "$tracked_prd" ] && [ -n "$record_hash" ]; then record_ok=1; fi
+        ;;
+      ---|"") record_path=""; record_hash="" ;;
+    esac
+  done < "$manifest"
+  [ "$record_ok" -eq 1 ] || \
+    die "$COMATE_BLOCK" "BLOCK: change '$change' source manifest lacks a complete path/sha256 record for $tracked_prd"
+  local drift rc=0
+  drift=$(sources_drift "$manifest") || rc=$?
+  [ "$rc" -eq 0 ] || die "$COMATE_BLOCK" "BLOCK: change '$change' source evidence is stale: $drift"
+}
+
+# gate_change_names <changes_map> — emit mapped change names, one per line.
+# The persisted format is `name:function item,...;name:function item,...`.
+gate_change_names() {
+  local map="$1" entry name
+  [ -n "$map" ] && [ "$map" != "null" ] || return 0
+  gate_validate_changes_map "$map"
+  while [ -n "$map" ]; do
+    case "$map" in
+      *\;*) entry="${map%%;*}"; map="${map#*;}" ;;
+      *) entry="$map"; map="" ;;
+    esac
+    name="${entry%%:*}"
+    [ -n "$name" ] || die "$COMATE_USAGE" "ERROR: malformed changes_map entry '$entry'"
+    [ "$name" != "$entry" ] || die "$COMATE_USAGE" "ERROR: malformed changes_map entry '$entry'"
+    validate_change_name "$name"
+    printf '%s\n' "$name"
+  done
+}
+
+# gate_change_is_mapped <changes_map> <change> — membership test for a mapped name.
+gate_change_is_mapped() {
+  local map="$1" wanted="$2" name
+  gate_validate_changes_map "$map"
+  while IFS= read -r name; do
+    [ "$name" = "$wanted" ] && return 0
+  done <<EOF
+$(gate_change_names "$map")
+EOF
+  return 1
+}
+
+# gate_fanout_status <prd> [--json] — calculate persisted fanout progress.
+# This is deliberately derived from changes_map and spawned_changes so an
+# interrupted run can resume from the missing names instead of relying on
+# conversation/task state.
+gate_fanout_status() {
+  local prd; prd=$(require_prd "$1")
+  local json="${2:-}" gate; gate=$(gate_path_for "$prd")
+  [ -f "$gate" ] || die "$COMATE_CORRUPT" "ERROR: gate not found: $gate"
+  local map spawned name expected=0 count=0 missing="" invalid=""
+  map=$(yaml_get "$gate" changes_map); spawned=$(yaml_get "$gate" spawned_changes)
+  gate_validate_changes_map "$map"
+  while IFS= read -r name; do
+    [ -n "$name" ] || continue
+    expected=$((expected + 1))
+    case ",$spawned," in
+      *",$name,"*) count=$((count + 1)) ;;
+      *) [ -n "$missing" ] && missing="$missing,"; missing="$missing$name" ;;
+    esac
+  done <<EOF
+$(gate_change_names "$map")
+EOF
+  if [ -n "$spawned" ] && [ "$spawned" != "null" ]; then
+    local rest="$spawned" item
+    while [ -n "$rest" ]; do
+      case "$rest" in
+        *,*) item="${rest%%,*}"; rest="${rest#*,}" ;;
+        *) item="$rest"; rest="" ;;
+      esac
+      gate_change_is_mapped "$map" "$item" || { [ -n "$invalid" ] && invalid="$invalid,"; invalid="$invalid$item"; }
+    done
+  fi
+  local complete=false
+  [ "$expected" -gt 0 ] && [ "$count" -eq "$expected" ] && [ -z "$invalid" ] && complete=true
+  if [ "$json" = "--json" ]; then
+    printf '{"expected":%s,"spawned":%s,"complete":%s,"missing":"%s","invalid":"%s"}\n' \
+      "$expected" "$count" "$complete" "$(json_escape "$missing")" "$(json_escape "$invalid")"
+  else
+    [ -z "$missing" ] && missing=none
+    [ -z "$invalid" ] && invalid=none
+    echo "fanout: expected=$expected spawned=$count complete=$complete missing=$missing invalid=$invalid"
+  fi
+}
+
 # _gate_is_stale <gate> <prd> — true (0) if the recorded hash no longer matches
 # the PRD on disk.
 _gate_is_stale() {
@@ -1956,6 +2118,7 @@ case "$CMD" in
       set)     gate_set "$PRD" "${1:-}" "${2:-}" ;;
       pass)    gate_pass "$PRD" "${1:-}" ;;
       spawned) gate_spawned "$PRD" "${1:-}" ;;
+      fanout-status) gate_fanout_status "$PRD" "${1:-}" ;;
       status)  gate_status "$PRD" "${1:-}" ;;
       check)   gate_check "$PRD" ;;
       *) die "$COMATE_USAGE" "Unknown gate subcommand: $SUB" ;;

package/skills/comate/tests/comate.bats

@@ -565,6 +565,17 @@ seed_prd() {
   echo "docs/knowledge-base/requirements/test/PRD-001-demo.md"
 }
 
+seed_gate_skeleton() {
+  local prd="$1" change="$2" d="openspec/changes/$2"
+  mkdir -p "$d"
+  printf 'schema: specs-driven\n' > "$d/.openspec.yaml"
+  printf '# proposal\n' > "$d/proposal.md"
+  printf '# design\n' > "$d/design.md"
+  printf -- '- [ ] task\n' > "$d/tasks.md"
+  comate state "$change" init full >/dev/null
+  comate sources "$change" track "$prd" >/dev/null
+}
+
 @test "gate review creates gate.yaml next to PRD" {
   local prd; prd=$(seed_prd)
   run comate gate "$prd" review
@@ -643,6 +654,71 @@ seed_prd() {
   [[ "$output" == *"changes_map"* ]]
 }
 
+@test "gate rejects changes_map entries without a function mapping" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  run comate gate "$prd" set changes_map "login-flow"
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"malformed changes_map"* ]]
+}
+
+@test "gate rejects duplicate change names in changes_map" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  run comate gate "$prd" set changes_map "login-flow:功能项1;login-flow:功能项2"
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"duplicate change"* ]]
+}
+
+@test "gate rejects an empty middle entry in changes_map" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  run comate gate "$prd" set changes_map "login-flow:功能项1;;logout-flow:功能项2"
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"empty entry"* ]]
+}
+
+@test "gate rejects a trailing empty entry in changes_map" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  run comate gate "$prd" set changes_map "login-flow:功能项1;"
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"empty entry"* ]]
+}
+
+@test "gate rejects an empty function mapping" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  run comate gate "$prd" set changes_map "login-flow:"
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"empty function mapping"* ]]
+}
+
+@test "gate rejects an all-whitespace function mapping" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  run comate gate "$prd" set changes_map "login-flow:   "
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"empty function mapping"* ]]
+}
+
+@test "gate keeps a passed changes_map immutable except for idempotent writes" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  comate gate "$prd" set changes_map "a:功能项1;b:功能项2;c:功能项3;d:功能项4" >/dev/null
+  printf '# 报告\n' > "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
+  comate gate "$prd" pass >/dev/null
+  run comate gate "$prd" set changes_map "a:功能项1;b:功能项2;c:功能项3;d:功能项4"
+  [ "$status" -eq 0 ]
+  run comate gate "$prd" set changes_map "a:功能项1"
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"immutable after gate pass"* ]]
+  run comate gate "$prd" fanout-status --json
+  [[ "$output" == *'"expected":4'* ]]
+}
+
 @test "gate pass --tbd requires unresolved blockers" {
   local prd; prd=$(seed_prd)
   comate gate "$prd" review >/dev/null
@@ -727,6 +803,7 @@ seed_prd() {
   printf '# 报告\n' > \
     "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
   comate gate "$prd" pass >/dev/null
+  seed_gate_skeleton "$prd" login-flow
   run comate gate "$prd" spawned login-flow
   [ "$status" -eq 0 ]
   local gate="docs/knowledge-base/requirements/test/PRD-001.gate.yaml"
@@ -743,6 +820,8 @@ seed_prd() {
   printf '# 报告\n' > \
     "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
   comate gate "$prd" pass >/dev/null
+  seed_gate_skeleton "$prd" login-flow
+  seed_gate_skeleton "$prd" logout-flow
   comate gate "$prd" spawned login-flow >/dev/null
   comate gate "$prd" spawned logout-flow >/dev/null
   local gate="docs/knowledge-base/requirements/test/PRD-001.gate.yaml"
@@ -751,6 +830,131 @@ seed_prd() {
   [[ "$sc" == *"logout-flow"* ]]
 }
 
+@test "gate spawned remains idempotent after an already recorded change leaves the active directory" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  comate gate "$prd" set changes_map "login-flow:功能项1" >/dev/null
+  printf '# 报告\n' > "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
+  comate gate "$prd" pass >/dev/null
+  seed_gate_skeleton "$prd" login-flow
+  comate gate "$prd" spawned login-flow >/dev/null
+  mkdir -p openspec/changes/archive
+  mv openspec/changes/login-flow openspec/changes/archive/2026-08-28-login-flow
+  run comate gate "$prd" spawned login-flow
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"already recorded"* ]]
+}
+
+@test "gate fanout status reports missing changes instead of treating one of four as complete" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  comate gate "$prd" set changes_map "login-flow:功能项1;logout-flow:功能项2;ops:功能项3;report:功能项4" >/dev/null
+  printf '# 报告\n' > "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
+  comate gate "$prd" pass >/dev/null
+  seed_gate_skeleton "$prd" login-flow
+  comate gate "$prd" spawned login-flow >/dev/null
+  run comate gate "$prd" fanout-status --json
+  [ "$status" -eq 0 ]
+  [[ "$output" == *'"expected":4'* ]]
+  [[ "$output" == *'"spawned":1'* ]]
+  [[ "$output" == *'"complete":false'* ]]
+  [[ "$output" == *'logout-flow'* ]]
+}
+
+@test "gate spawned rejects a change outside the confirmed map" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  comate gate "$prd" set changes_map "login-flow:功能项1" >/dev/null
+  printf '# 报告\n' > "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
+  comate gate "$prd" pass >/dev/null
+  seed_gate_skeleton "$prd" other-flow
+  run comate gate "$prd" spawned other-flow
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"not present in changes_map"* ]]
+}
+
+@test "gate fanout status becomes complete only after every mapped change is spawned" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  comate gate "$prd" set changes_map "login-flow:功能项1;logout-flow:功能项2" >/dev/null
+  printf '# 报告\n' > "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
+  comate gate "$prd" pass >/dev/null
+  seed_gate_skeleton "$prd" login-flow
+  seed_gate_skeleton "$prd" logout-flow
+  comate gate "$prd" spawned login-flow >/dev/null
+  comate gate "$prd" spawned logout-flow >/dev/null
+  run comate gate "$prd" fanout-status
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"complete=true"* ]]
+  [[ "$output" == *"missing=none"* ]]
+}
+
+@test "gate spawned rejects an incomplete change skeleton" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  comate gate "$prd" set changes_map "login-flow:功能项1" >/dev/null
+  printf '# 报告\n' > "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
+  comate gate "$prd" pass >/dev/null
+  mkdir -p openspec/changes/login-flow
+  run comate gate "$prd" spawned login-flow
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"skeleton incomplete"* ]]
+}
+
+@test "gate spawned blocks a new registration after the PRD becomes stale" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  comate gate "$prd" set changes_map "login-flow:功能项1" >/dev/null
+  printf '# 报告\n' > "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
+  comate gate "$prd" pass >/dev/null
+  seed_gate_skeleton "$prd" login-flow
+  printf '\nchanged\n' >> "$prd"
+  run comate gate "$prd" spawned login-flow
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"hash mismatch"* ]]
+}
+
+@test "gate spawned accepts a normalized PRD path recorded in the source manifest" {
+  local prd; prd=$(seed_prd)
+  prd="./$prd"
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  comate gate "$prd" set changes_map "login-flow:功能项1" >/dev/null
+  printf '# 报告\n' > "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
+  comate gate "$prd" pass >/dev/null
+  seed_gate_skeleton "$prd" login-flow
+  run comate gate "$prd" spawned login-flow
+  [ "$status" -eq 0 ]
+}
+
+@test "gate spawned rejects a truncated PRD source record without sha256" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  comate gate "$prd" set changes_map "login-flow:功能项1" >/dev/null
+  printf '# 报告\n' > "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
+  comate gate "$prd" pass >/dev/null
+  seed_gate_skeleton "$prd" login-flow
+  printf 'path:%s\n' "$prd" > openspec/changes/login-flow/.comate/sources.manifest
+  run comate gate "$prd" spawned login-flow
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"complete path/sha256 record"* ]]
+}
+
 @test "gate status returns none when gate does not exist" {
   mkdir -p docs/knowledge-base/requirements/test
   run comate gate "docs/knowledge-base/requirements/test/PRD-001-demo.md" status

package/skills/comate-gate/SKILL.md

@@ -41,8 +41,9 @@ gate 命令族（退出码：`0` 通过 / `1` 阻塞 / `2` 用法 / `3` 环境 /
 bash "$COMATE" gate <prd> review              # 建/刷新 gate.yaml，钉 PRD 哈希，回报告路径
 bash "$COMATE" gate <prd> set <field> <value> # 写 score | blocking_open | gate_status
 bash "$COMATE" gate <prd> pass [--tbd]         # 普通通过要求 0 阻断；--tbd 要求有已授权的未解决阻断
-bash "$COMATE" gate <prd> spawned <change>     # 记录据此 PRD 扇出的 change
-bash "$COMATE" gate <prd> status [--json]      # 查状态（哈希漂移自动判 stale）
+bash "$COMATE" gate <prd> spawned <change>     # 记录据此 PRD 扇出的 change
+bash "$COMATE" gate <prd> fanout-status [--json] # 查看映射/已创建/待创建进度
+bash "$COMATE" gate <prd> status [--json]      # 查状态（哈希漂移自动判 stale）
 bash "$COMATE" gate <prd> check                # comate-open 建 change 前的前置守卫
 ```
 
@@ -205,21 +206,33 @@ bash "$COMATE" gate <prd> pass --tbd
 
 `pass` 会硬校验评分为 0–100、`changes_map` 非空、报告非空；普通 pass 要求 `blocking_open=0`，`--tbd` 则要求存在至少 1 个已记录且经用户明确接受的未解决阻断项。之后 PRD 再被改，哈希漂移会使门禁 `stale`，须重跑 `/comate-gate`。
 
-### 6. 逐 Change 初始化（调 comate-open）
-
-对映射里每个 change，逐个调用 comate-open。**每次都在 change 描述里点明**：本 change 承接 PRD 的哪些功能项、范围边界、以及（多 change 时）相邻职责归哪个 change（In/Out 显式互引，防重复防遗漏）。
-
-**立即执行**：用 Skill 工具加载 `comate-open`，传入 change 名与来源 PRD。comate-open 内部会：
+### 6. 逐 Change 初始化（调 comate-open）
+
+这是一个可恢复的扇出循环，不是一次性只执行首项的提示。每次进入本步骤先运行：
+
+```bash
+bash "$COMATE" gate <prd路径> fanout-status --json
+```
+
+只处理返回 JSON 中 `missing` 列出的 change；不要重新处理 `spawned` 中已有的 change。每创建一个 change 后立即运行 `gate spawned`，再重新运行 `fanout-status`，直到 `complete: true`。如果本轮因上下文、用户决策或子 skill 中断，下一轮必须从 `fanout-status` 恢复，不能根据对话记忆猜测剩余项。
+
+对 `missing` 里的每个 change，逐个调用 comate-open。**每次都在 change 描述里点明**：本 change 承接 PRD 的哪些功能项、范围边界、以及（多 change 时）相邻职责归哪个 change（In/Out 显式互引，防重复防遗漏）。若同名目录或 `.comate.yaml` 已存在，视为中断恢复：让 comate-open 复用现有状态、补齐缺失产物和源追踪后登记，不得重复执行 `state init`。
+
+**立即执行**：用 Skill 工具加载 `comate-open`，传入 change 名与来源 PRD，并明确使用“gate 扇出骨架模式”。该模式创建/补齐并校验当前 change 的 `.openspec.yaml`、open 三件套、`.comate.yaml` 和 PRD 源追踪，最后登记 `gate spawned` 并保持 `phase: open` 返回本 gate 循环；不得在同一次 gate 调用中自动进入该 change 的 design/build。
+
+comate-open 内部会：
 - 先跑 `gate check <prd>` 前置守卫（未通过则阻断）；
 - 生成 proposal.md（范围/目标/非目标承接该 change 的功能项，不脱离 PRD 另起炉灶）；
 - `sources track <prd>` 钉住 PRD 为源（`source_kind=file`）；
 - design.md / tasks.md 由后续 comate-design 细化。
 
-每建成一个，记录到门禁：
+每建成一个，记录到门禁（目录已存在后才能登记）：
 
 ```bash
-bash "$COMATE" gate <prd> spawned <change-name>
-```
+bash "$COMATE" gate <prd> spawned <change-name>
+```
+
+登记后继续处理 `fanout-status` 的 `missing` 列表。只有 `complete: true` 才能进入步骤 7，并且收尾报告中的“已创建 N 个 change”必须等于映射项数量；部分完成必须明确报告剩余项，不能宣称扇出完成。
 
 若门禁是 `passed-with-tbd`，在该 change 的 proposal/design 受影响处标 **「⚠ 待确认」** 并引用评审报告。
 
@@ -229,7 +242,8 @@ bash "$COMATE" gate <prd> spawned <change-name>
 - PRD 审阅评分 + 评级、阻断问题关闭情况；
 - 评审报告路径、gate.yaml 路径与最终 `gate_status`；
 - 拆分映射（功能项 → N 个 change）；
-- 已建的 change 列表（名称 + 承接功能项 + 是否带 ⚠ TBD）；
+- 已建的 change 列表（名称 + 承接功能项 + 是否带 ⚠ TBD）；
+- 扇出完整性（`fanout-status` 的 expected/spawned/missing/invalid）；
 - 待用户补的字段（如技术负责人）。
 
 提示：「已过门禁并创建 N 个 change。对每个 change 调用 `/comate` 继续 design→build→verify→archive。」
@@ -245,7 +259,8 @@ bash "$COMATE" gate <prd> spawned <change-name>
 - AskUserQuestion 是真实阻塞点：文字输出/推荐/默认值/历史选择/用户未反对都不能替代明确回答。
 - 拆分粒度（1 PRD → 几个 change）由用户定，AI 只给建议不拍板。
 - 每个 change 承接 PRD 对应功能项，不另起炉灶；范围/依赖/验收与 PRD 对齐。
-- 多 change 时在各 change 的 In/Out Scope 显式互引边界职责归属。
+- 多 change 时在各 change 的 In/Out Scope 显式互引边界职责归属。
+- 扇出必须以 `gate fanout-status` 为持久化进度真相；`TaskCreate` 仅作展示，不得替代 gate.yaml 状态。
 - 门禁通过后 PRD 若被改（哈希漂移），gate 转 stale，禁止再扇出 change，须重跑本 skill。
 - 契约以项目架构文档（如 `docs/architecture/`，若存在）为事实源，change 里点名遵循了哪条，不硬编码具体值、不自造。
 - 不写应用代码——本 skill 止于「过门禁 + 拆分 + 建 change 骨架」，实现由后续 comate 阶段驱动。

package/skills/comate-open/SKILL.md

@@ -36,7 +36,23 @@ bash "$COMATE" gate <prd路径> check
 
 需求**来自对话**（非 PRD）时跳过本步——门禁只约束「PRD → change」这条路径。
 
-### 3. 创建 Change 结构 + 初始化状态
+### 3. 创建 Change 结构 + 初始化状态
+
+#### Gate 扇出骨架模式
+
+当调用方明确说明本次来自 `comate-gate` 的批量扇出时，使用独立的骨架模式：
+
+1. 运行 gate check；
+2. 创建或补齐 `.openspec.yaml`、proposal.md、design.md、tasks.md；
+3. `.comate.yaml` 不存在时才执行 `state init full`，已存在时读取并复用，不能重复 init；
+4. 追踪源 PRD；
+5. 运行 `state check open` 并检查所有骨架文件非空、proposal 范围忠实承接映射；
+6. 最后执行 `gate spawned`。脚本会再次校验 gate 未 stale、骨架完整且源 manifest 确实追踪该 PRD；
+7. 登记成功后保持 `phase: open`，立即返回 comate-gate 的扇出循环。
+
+骨架模式不执行 Step 4 后的 `phase_step` 记录、Step 5 产物确认、open guard 或本文“自动流转”；**不得**在同一次 gate 调用中加载 `comate-design`。下一项由 gate 根据 `fanout-status` 的 `missing` 列表继续处理。
+
+若不是 gate 扇出调用，保持普通 open 流程并按本文退出条件进入 design。
 
 **立即执行：** 使用 Skill 工具加载 `openspec-new-change` 技能。若用户意图未明确、需先形成建议，改为加载 `openspec-propose`。禁止跳过。
 
@@ -63,10 +79,12 @@ if [ -z "$COMATE" ]; then
   return 1 2>/dev/null || exit 1
 fi
 
-bash "$COMATE" state <name> init full
-```
-
-这会创建 `openspec/changes/<name>/.comate.yaml`，初始状态：`workflow: full`, `phase: open`, `phase_step: null`。
+bash "$COMATE" state <name> init full
+```
+
+这会创建 `openspec/changes/<name>/.comate.yaml`，初始状态：`workflow: full`, `phase: open`, `phase_step: null`。
+
+**恢复规则**：若 change 目录或 `.comate.yaml` 已存在，逐项检查并补齐缺失产物；`.comate.yaml` 存在时跳过 `state init`。这覆盖“骨架已创建但尚未 gate spawned”中断点，完成校验后直接补登记。
 
 ### 3b. 判定需求来源(源文件追踪)
 
@@ -84,13 +102,13 @@ bash "$COMATE" sources <name> track docs/knowledge-base/<path>.md --note "<可
 
 ### 3c. PRD 扇出记录（从 PRD 建 change 时必须登记）
 
-若本 change 来自 PRD，在创建完成后把该 change 记回门禁：
+若本 change 来自 PRD，在创建、源追踪和完整性校验全部完成后，把该 change 记回门禁：
 
 ```bash
 bash "$COMATE" gate <prd路径> spawned <name>
 ```
 
-此步将 change 名称追加到 `<PRD>.gate.yaml` 的 `spawned_changes` 列表，用于追溯 PRD → change 的完整扇出关系。
+此步将 change 名称追加到 `<PRD>.gate.yaml` 的 `spawned_changes` 列表，用于追溯 PRD → change 的完整扇出关系。不得在文件不完整或源追踪前提前登记。
 
 需求**来自对话**时跳过本步。
 
@@ -187,7 +205,9 @@ bash "$COMATE" state <name> set phase_step open.review-confirmed
 
 然后继续执行退出条件（guard）。
 
-## 退出条件
+## 退出条件
+
+以下退出条件仅适用于普通 open；gate 扇出骨架模式使用 Step 3 的专用返回条件。
 
 - 三件套已创建且内容完整
 - **用户已确认**
@@ -201,9 +221,9 @@ bash "$COMATE" guard <name> open --apply
 
 full 流程自动更新为 `phase: design`；fix 预设自动更新为 `phase: build`。
 
-## 自动流转
-
-用户确认后退出条件满足，自动流转：
+## 自动流转
+
+仅普通 open 在用户确认后自动流转：
 
 > **REQUIRED NEXT SKILL（完整流程）：** 调用 `comate-design` skill 进入深度设计。
 >