@house365/comate 0.9.17 → 0.9.19

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 进入深度设计。
 >