@house365/comate 0.9.23 → 0.9.25

package/skills/comate-gate/SKILL.md

@@ -1,63 +1,63 @@
----
-name: comate-gate
+---
+name: comate-gate
 description: "comate 阶段 0：PRD 门禁与拆分。用 /comate-gate 调用。对原始 PRD 做质量审阅+评分+阻断闸门，通过后按依赖/独立性判定拆成 1 或 N 个 change，逐个交给 comate-open。门禁状态钉在 PRD 同级 gate 文件，门禁未通过禁止建 change。"
----
-
-# comate 阶段 0：PRD 门禁与拆分（Gate）
-
-**定位**：comate 五阶段（open→design→build→verify→archive）之前的上游入口。输入一份**原始 PRD**，产出「已过门禁、已拆分」的 N 个 change，各自进入 open 阶段。
-
-**两件事，缺一不可**：
-1. **门禁**：审阅 PRD 质量、百分制评分、建阻断台账。阻断问题未清零，**禁止建任何 change**。
-2. **拆分**：按依赖/整体性/独立性/规模判定该 PRD 变成几个 change，粒度由用户拍板（AI 只给建议）。
-
 ---
-
-## 核心铁律
-
+
+# comate 阶段 0：PRD 门禁与拆分（Gate）
+
+**定位**：comate 五阶段（open→design→build→verify→archive）之前的上游入口。输入一份**原始 PRD**，产出「已过门禁、已拆分」的 N 个 change，各自进入 open 阶段。
+
+**两件事，缺一不可**：
+1. **门禁**：审阅 PRD 质量、百分制评分、建阻断台账。阻断问题未清零，**禁止建任何 change**。
+2. **拆分**：按依赖/整体性/独立性/规模判定该 PRD 变成几个 change，粒度由用户拍板（AI 只给建议）。
+
+---
+
+## 核心铁律
+
 - **门禁状态是可验证的文件真相源**：钉在 PRD 同级的 gate 文件。评审报告是给人看的派生物，**不是**状态源。PRD 命名按本 skill 的前置规范执行，派生文件名由脚本确定性生成。
-- **AskUserQuestion 是真阻塞点**：文字提示、推荐方案、默认值、历史偏好、用户未反对，都**不能**替代明确回答。
-- **只审不改**：门禁只暴露 PRD 问题，不替 PRD 补内容、不替产品拍板。
-- **门禁未通过禁止建 change**：`gate_status ∈ {passed, passed-with-tbd}` 且 PRD 哈希未漂移，才允许 comate-open 建 change（由 `gate check` 硬强制）。
-- **拆分粒度由人定**：AI 给「功能项→change」映射建议，用户确认或改，AI 不拍板。
-
----
-
-## 脚本定位（单一入口）
-
-```bash
-COMATE="${COMATE:-$(for r in . ./.agents/skills ./.claude/skills ./.cursor/skills ./.codex/skills "$HOME"/.agents/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills "$HOME"/.codex/skills "$HOME"/.gemini/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
-```
-
-gate 命令族（退出码：`0` 通过 / `1` 阻塞 / `2` 用法 / `3` 环境 / `4` 状态损坏）：
-
-```bash
-bash "$COMATE" gate <prd> review              # 建/刷新 gate.yaml，钉 PRD 哈希，回报告路径
-bash "$COMATE" gate <prd> set <field> <value> # 写 score | blocking_open | gate_status
+- **AskUserQuestion 是真阻塞点**：文字提示、推荐方案、默认值、历史偏好、用户未反对，都**不能**替代明确回答。
+- **只审不改**：门禁只暴露 PRD 问题，不替 PRD 补内容、不替产品拍板。
+- **门禁未通过禁止建 change**：`gate_status ∈ {passed, passed-with-tbd}` 且 PRD 哈希未漂移，才允许 comate-open 建 change（由 `gate check` 硬强制）。
+- **拆分粒度由人定**：AI 给「功能项→change」映射建议，用户确认或改，AI 不拍板。
+
+---
+
+## 脚本定位（单一入口）
+
+```bash
+COMATE="${COMATE:-$(for r in . ./.agents/skills ./.claude/skills ./.cursor/skills ./.codex/skills "$HOME"/.agents/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills "$HOME"/.codex/skills "$HOME"/.gemini/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
+```
+
+gate 命令族（退出码：`0` 通过 / `1` 阻塞 / `2` 用法 / `3` 环境 / `4` 状态损坏）：
+
+```bash
+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> fanout-status [--json] # 查看映射/已创建/待创建进度
 bash "$COMATE" gate <prd> status [--json]      # 查状态（哈希漂移自动判 stale）
-bash "$COMATE" gate <prd> check                # comate-open 建 change 前的前置守卫
-```
-
----
-
-## 步骤
-
-### 1. 定位 PRD
-
-- 用户给了路径/编号 → 直接读该文件。
+bash "$COMATE" gate <prd> check                # comate-open 建 change 前的前置守卫
+```
+
+---
+
+## 步骤
+
+### 1. 定位 PRD
+
+- 用户给了路径/编号 → 直接读该文件。
 - 未给 → 用 Glob 列出候选（默认搜索 `docs/knowledge-base/requirements/**/*.md`，若项目无此结构再探测 `docs/**/*.md`），按命中数分类（对齐 `comate/reference/decision-points.md` 首节三类框架）：
-  - **恰好 1 个候选** → 无 ≥2 有效选项，属"自动处理"：直接选中该 PRD 并**报告选了哪份**，不 AskUserQuestion。
-  - **多个候选** → 属"用户决策"：用 **AskUserQuestion** 让用户选一个。
-  - **0 个候选** → 属"停止条件"：报告在约定路径下未找到 PRD，请用户提供路径或确认 PRD 位置，不发明选项。
+  - **恰好 1 个候选** → 无 ≥2 有效选项，属"自动处理"：直接选中该 PRD 并**报告选了哪份**，不 AskUserQuestion。
+  - **多个候选** → 属"用户决策"：用 **AskUserQuestion** 让用户选一个。
+  - **0 个候选** → 属"停止条件"：报告在约定路径下未找到 PRD，请用户提供路径或确认 PRD 位置，不发明选项。
 - 读取后重点提取：**功能清单**（各功能项 + 优先级 P0/P1/P2）、**范围（In/Out）**、**第三方依赖**、**验收标准**、文档状态。检查内容是否可审阅即可，不要求 Markdown 标题、表格或模板字段完全一致。
 - 若 PRD 明显未定稿（状态字段非「已定稿」等），用 **AskUserQuestion** 提示可能未冻结并暂停确认；确认前只审阅，不建 gate。
 
@@ -73,139 +73,139 @@ PRD 的路径和文件名需要稳定、可追踪，以便 gate 状态和评审
 发现不规范时，先列出旧名和建议新名，等待用户确认后再用 `git mv` 改名，并同步修正引用。命名规范是流程前置条件；PRD 的正文格式不要求完全套用模板，只需能被审阅并包含可判断的需求内容。
 
 ### 2. 门禁：质量审阅 + 评分（不可跳过）
-
-先初始化 gate（钉当前 PRD 哈希、拿到报告路径）：
-
-```bash
-bash "$COMATE" gate <prd> review
-```
-
-**逐维度排查**（每条既看「有没有」，也看「清不清楚、能不能落地」）：
-
-| 维度 | 查什么 |
-|------|--------|
-| 逻辑自洽 | 需求前后是否矛盾；流程有无断链；条件/分支是否闭合；功能项间是否冲突或重复 |
-| 数据与来源 | 用到的数据是否交代来源（哪张表/哪个接口/哪方提供）；口径/单位/时间范围是否明确 |
-| 边界与范围 | In/Out 是否清晰；极值、空值、并发、权限、异常路径是否覆盖；第三方失败/降级是否提及 |
-| 表述清晰 | 术语是否一致且有定义；有无「尽快/大量/若干」等模糊量词；验收是否可度量 |
-| 完整性 | 目标/背景、功能清单、优先级、验收标准、第三方依赖是否齐全；有无 TBD/待定 |
-
-**每个问题标严重程度三档：**
-- **严重**（扣 15 分）：阻断开发或导致做错方向（逻辑矛盾、关键数据无来源、核心边界缺失、需求自相冲突）。
-- **中**（扣 7 分）：影响实现质量或需返工（口径不清、部分异常路径未覆盖、验收不可度量）。
-- **低**（扣 2 分）：表述瑕疵、术语不统一、可读性问题，不影响方向。
-
-**评分**（百分制，从 100 扣，扣到 0 为止）：≥85 优（可拆）、70–84 良（可拆，受影响处标待确认）、<70 待补（建议先补 PRD）。
-
-**先分流再提问**：
-- **仓库事实**（已有架构约定、字段、接口、对接档案）：先用 Read/Glob/rg 核实并引用来源，不丢给用户决定。
-- **产品决策**（范围、优先级、用户可见行为、状态流转、权限、数据口径、失败处理、验收规则）：必须用 **AskUserQuestion** 问用户，不得用推荐方案/历史偏好/「待确认」代替确认。
-
+
+先初始化 gate（钉当前 PRD 哈希、拿到报告路径）：
+
+```bash
+bash "$COMATE" gate <prd> review
+```
+
+**逐维度排查**（每条既看「有没有」，也看「清不清楚、能不能落地」）：
+
+| 维度 | 查什么 |
+|------|--------|
+| 逻辑自洽 | 需求前后是否矛盾；流程有无断链；条件/分支是否闭合；功能项间是否冲突或重复 |
+| 数据与来源 | 用到的数据是否交代来源（哪张表/哪个接口/哪方提供）；口径/单位/时间范围是否明确 |
+| 边界与范围 | In/Out 是否清晰；极值、空值、并发、权限、异常路径是否覆盖；第三方失败/降级是否提及 |
+| 表述清晰 | 术语是否一致且有定义；有无「尽快/大量/若干」等模糊量词；验收是否可度量 |
+| 完整性 | 目标/背景、功能清单、优先级、验收标准、第三方依赖是否齐全；有无 TBD/待定 |
+
+**每个问题标严重程度三档：**
+- **严重**（扣 15 分）：阻断开发或导致做错方向（逻辑矛盾、关键数据无来源、核心边界缺失、需求自相冲突）。
+- **中**（扣 7 分）：影响实现质量或需返工（口径不清、部分异常路径未覆盖、验收不可度量）。
+- **低**（扣 2 分）：表述瑕疵、术语不统一、可读性问题，不影响方向。
+
+**评分**（百分制，从 100 扣，扣到 0 为止）：≥85 优（可拆）、70–84 良（可拆，受影响处标待确认）、<70 待补（建议先补 PRD）。
+
+**先分流再提问**：
+- **仓库事实**（已有架构约定、字段、接口、对接档案）：先用 Read/Glob/rg 核实并引用来源，不丢给用户决定。
+- **产品决策**（范围、优先级、用户可见行为、状态流转、权限、数据口径、失败处理、验收规则）：必须用 **AskUserQuestion** 问用户，不得用推荐方案/历史偏好/「待确认」代替确认。
+
 **写评审报告（必生成）** 到 `gate review` 回显的 `review_report` 路径（与 PRD 同级，由脚本确定性命名）。内容含：评分 + 评级 + 一句话总评、问题台账表（`ID` / 维度 / 严重程度 / 原文依据 / 影响章节 / 是否阻断 / 建议 / 产品回填列）、逐条问题。若无问题，明确写「审阅通过，未发现阻断项」。
-
-**阻断规则**：影响范围、用户行为、状态流转、数据契约、权限、异常处理或验收标准的问题标「阻断」。把当前未关闭的阻断问题数写入 gate：
-
-```bash
-bash "$COMATE" gate <prd> set score <分数>
-bash "$COMATE" gate <prd> set blocking_open <未关闭阻断数>
-```
-
-### 3. 阻断闸门（AskUserQuestion）
-
-**若 `blocking_open > 0`**，先判定复杂度：
-
-- **阻断数 ≤ 3 且无明显依赖链** → 默认模式（批量+分轮处理）
-- **阻断数 > 3 或存在决策依赖链** → 提供深度澄清选项
-
-#### 默认模式（阻断数 ≤ 3）
-
-用 **AskUserQuestion** 暂停，给三选项（文字提示不能替代工具等待）：
-1. **先补 PRD** — 让用户/产品补齐，补后回步骤 2 重新审阅（`gate review` 会因 PRD 改动重钉哈希、状态回 reviewing）。
-2. **授权带 TBD 继续** — 用户显式授权。此时后续 change 的 proposal/design 受影响处必须标 **「⚠ 待确认」** 并引用评审报告。
-3. **暂停** — 停在此，不建 change。
-
-对每轮最多 1–3 个高影响决策提问；每个问题给 `ID`、原文依据、影响、2–3 个互斥选项、推荐项及后果，允许自定义答案。用户回答后更新报告台账、重算 `blocking_open`，直到清零或用户选 2。**清零或授权后，立即继续执行步骤 4（拆分判定）。**
-
-#### 复杂场景模式（阻断数 > 3 或有依赖链）
-
-用 **AskUserQuestion** 暂停，给四选项：
-1. **先补 PRD** — 同上。
-2. **授权带 TBD 继续** — 同上。
-3. **深度澄清模式** — 调用 `comate-grill` skill 逐决策点穷追式澄清。适合复杂 PRD，更彻底但耗时更长。
-4. **暂停** — 停在此，不建 change。
-
-**若用户选 3（深度澄清）**：
-
-1. **立即执行**：使用 Skill 工具加载 `comate-grill`，传入话题和阻断问题清单：
-
-   ```markdown
-   话题：PRD 门禁阻断问题清单
-   问题列表：
-   [逐条列出所有 blocking_open > 0 的问题，每条含：ID、问题描述、原文依据、影响范围、当前歧义]
-   ```
-
-2. `comate-grill` 会逐个决策点深挖，每个问题附推荐答案，等用户确认后进入下一个，直到所有分支清晰。
-
-3. `comate-grill` 完成后，**立即**更新评审报告台账、重算 `blocking_open`。若依然未清零，回到本步骤 3 再次判定（通常经过深度澄清后会清零）。
-
-4. **`blocking_open` 清零后，立即继续执行步骤 4（拆分判定）。**
-
-#### 步骤 3 出口条件（自动流转到步骤 4）
-
-**只有满足以下条件之一，才自动进入步骤 4**：
-- `blocking_open` 已清零（默认模式或深度澄清模式完成后）
-- 用户选择"授权带 TBD 继续"（选项 2）
-
-**满足条件后，必须立即继续执行步骤 4-7，不得停在步骤 3。** 用户选"先补 PRD"（选项 1）时回步骤 2；选"暂停"（选项 3/4）时停止整个 skill。
-
-### 4. 拆分判定（必须 AskUserQuestion 问人）
-
-列出 PRD 功能清单各功能项及优先级，AI 按下列维度**给拆分建议**（不拍板）：
-
-- **依赖关系**：前后依赖的功能项归**同一** change。
-- **整体性**：共同构成一个完整用户价值的功能簇归**同一** change。
-- **独立性**：互不依赖、可并行实现的功能项拆成**独立** change。
-- **规模**：功能点少（≤3）且简单 → **1 个** change 即可；复杂多点（>5）且可切分 → **多个** change。
-
-产出「功能项 → change」映射建议，例如：
-
-```
-建议拆分：
-- Change A「核心登录流」：功能项 1、2、3（有依赖链，整体交付）
-- Change B「运营配置」：功能项 4、5（独立，可与 A 并行）
-- Change C「数据报表」：功能项 6（独立后置）
-```
-
-用 **AskUserQuestion**（可多选/自定义）让用户确认：
-- 哪些功能项归哪个 change（显示建议映射）；
-- 是一功能项一 change 还是合并；
-- 各 change 命名（默认取主功能项名，用户可改）。
-
-**映射确认前不得建任何 change。** 确认后：
-
-1. **立即持久化映射到 gate.yaml**，使其成为机器可验证事实：
-
-```bash
-# changes_map 格式：changeA:功能项1,2,3;changeB:功能项4,5
-bash "$COMATE" gate <prd> set changes_map "changeA:功能项1,2,3;changeB:功能项4,5"
-```
-
-2. 用 **TaskCreate** 把每个待建 change 建成任务项。
-
-3. 多 change 时，在 PRD 同目录建 `CHANGES-MAP.md` 作为人类可读备份，内容与 `changes_map` 字段一致。
-
-### 5. 通过门禁
-
-映射与 `blocking_open` 都就绪后，置门禁通过：
-
-```bash
+
+**阻断规则**：影响范围、用户行为、状态流转、数据契约、权限、异常处理或验收标准的问题标「阻断」。把当前未关闭的阻断问题数写入 gate：
+
+```bash
+bash "$COMATE" gate <prd> set score <分数>
+bash "$COMATE" gate <prd> set blocking_open <未关闭阻断数>
+```
+
+### 3. 阻断闸门（AskUserQuestion）
+
+**若 `blocking_open > 0`**，先判定复杂度：
+
+- **阻断数 ≤ 3 且无明显依赖链** → 默认模式（批量+分轮处理）
+- **阻断数 > 3 或存在决策依赖链** → 提供深度澄清选项
+
+#### 默认模式（阻断数 ≤ 3）
+
+用 **AskUserQuestion** 暂停，给三选项（文字提示不能替代工具等待）：
+1. **先补 PRD** — 让用户/产品补齐，补后回步骤 2 重新审阅（`gate review` 会因 PRD 改动重钉哈希、状态回 reviewing）。
+2. **授权带 TBD 继续** — 用户显式授权。此时后续 change 的 proposal/design 受影响处必须标 **「⚠ 待确认」** 并引用评审报告。
+3. **暂停** — 停在此，不建 change。
+
+对每轮最多 1–3 个高影响决策提问；每个问题给 `ID`、原文依据、影响、2–3 个互斥选项、推荐项及后果，允许自定义答案。用户回答后更新报告台账、重算 `blocking_open`，直到清零或用户选 2。**清零或授权后，立即继续执行步骤 4（拆分判定）。**
+
+#### 复杂场景模式（阻断数 > 3 或有依赖链）
+
+用 **AskUserQuestion** 暂停，给四选项：
+1. **先补 PRD** — 同上。
+2. **授权带 TBD 继续** — 同上。
+3. **深度澄清模式** — 调用 `comate-grill` skill 逐决策点穷追式澄清。适合复杂 PRD，更彻底但耗时更长。
+4. **暂停** — 停在此，不建 change。
+
+**若用户选 3（深度澄清）**：
+
+1. **立即执行**：使用 Skill 工具加载 `comate-grill`，传入话题和阻断问题清单：
+
+   ```markdown
+   话题：PRD 门禁阻断问题清单
+   问题列表：
+   [逐条列出所有 blocking_open > 0 的问题，每条含：ID、问题描述、原文依据、影响范围、当前歧义]
+   ```
+
+2. `comate-grill` 会逐个决策点深挖，每个问题附推荐答案，等用户确认后进入下一个，直到所有分支清晰。
+
+3. `comate-grill` 完成后，**立即**更新评审报告台账、重算 `blocking_open`。若依然未清零，回到本步骤 3 再次判定（通常经过深度澄清后会清零）。
+
+4. **`blocking_open` 清零后，立即继续执行步骤 4（拆分判定）。**
+
+#### 步骤 3 出口条件（自动流转到步骤 4）
+
+**只有满足以下条件之一，才自动进入步骤 4**：
+- `blocking_open` 已清零（默认模式或深度澄清模式完成后）
+- 用户选择"授权带 TBD 继续"（选项 2）
+
+**满足条件后，必须立即继续执行步骤 4-7，不得停在步骤 3。** 用户选"先补 PRD"（选项 1）时回步骤 2；选"暂停"（选项 3/4）时停止整个 skill。
+
+### 4. 拆分判定（必须 AskUserQuestion 问人）
+
+列出 PRD 功能清单各功能项及优先级，AI 按下列维度**给拆分建议**（不拍板）：
+
+- **依赖关系**：前后依赖的功能项归**同一** change。
+- **整体性**：共同构成一个完整用户价值的功能簇归**同一** change。
+- **独立性**：互不依赖、可并行实现的功能项拆成**独立** change。
+- **规模**：功能点少（≤3）且简单 → **1 个** change 即可；复杂多点（>5）且可切分 → **多个** change。
+
+产出「功能项 → change」映射建议，例如：
+
+```
+建议拆分：
+- Change A「核心登录流」：功能项 1、2、3（有依赖链，整体交付）
+- Change B「运营配置」：功能项 4、5（独立，可与 A 并行）
+- Change C「数据报表」：功能项 6（独立后置）
+```
+
+用 **AskUserQuestion**（可多选/自定义）让用户确认：
+- 哪些功能项归哪个 change（显示建议映射）；
+- 是一功能项一 change 还是合并；
+- 各 change 命名（默认取主功能项名，用户可改）。
+
+**映射确认前不得建任何 change。** 确认后：
+
+1. **立即持久化映射到 gate.yaml**，使其成为机器可验证事实：
+
+```bash
+# changes_map 格式：changeA:功能项1,2,3;changeB:功能项4,5
+bash "$COMATE" gate <prd> set changes_map "changeA:功能项1,2,3;changeB:功能项4,5"
+```
+
+2. 用 **TaskCreate** 把每个待建 change 建成任务项。
+
+3. 多 change 时，在 PRD 同目录建 `CHANGES-MAP.md` 作为人类可读备份，内容与 `changes_map` 字段一致。
+
+### 5. 通过门禁
+
+映射与 `blocking_open` 都就绪后，置门禁通过：
+
+```bash
 bash "$COMATE" gate <prd> pass          # 阻断已清零
 # 或用户授权带 TBD：
 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）
 
 这是一个可恢复的扇出循环，不是一次性只执行首项的提示。每次进入本步骤先运行：
@@ -221,46 +221,46 @@ bash "$COMATE" gate <prd路径> fanout-status --json
 **立即执行**：用 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 细化。
-
+- 先跑 `gate check <prd>` 前置守卫（未通过则阻断）；
+- 生成 proposal.md（范围/目标/非目标承接该 change 的功能项，不脱离 PRD 另起炉灶）；
+- `sources track <prd>` 钉住 PRD 为源（`source_kind=file`）；
+- design.md / tasks.md 由后续 comate-design 细化。
+
 每建成一个，记录到门禁（目录已存在后才能登记）：
-
-```bash
+
+```bash
 bash "$COMATE" gate <prd> spawned <change-name>
 ```
 
 登记后继续处理 `fanout-status` 的 `missing` 列表。只有 `complete: true` 才能进入步骤 7，并且收尾报告中的“已创建 N 个 change”必须等于映射项数量；部分完成必须明确报告剩余项，不能宣称扇出完成。
-
-若门禁是 `passed-with-tbd`，在该 change 的 proposal/design 受影响处标 **「⚠ 待确认」** 并引用评审报告。
-
-### 7. 收尾
-
-展示：
-- PRD 审阅评分 + 评级、阻断问题关闭情况；
-- 评审报告路径、gate.yaml 路径与最终 `gate_status`；
-- 拆分映射（功能项 → N 个 change）；
+
+若门禁是 `passed-with-tbd`，在该 change 的 proposal/design 受影响处标 **「⚠ 待确认」** 并引用评审报告。
+
+### 7. 收尾
+
+展示：
+- PRD 审阅评分 + 评级、阻断问题关闭情况；
+- 评审报告路径、gate.yaml 路径与最终 `gate_status`；
+- 拆分映射（功能项 → N 个 change）；
 - 已建的 change 列表（名称 + 承接功能项 + 是否带 ⚠ TBD）；
 - 扇出完整性（`fanout-status` 的 expected/spawned/missing/invalid）；
-- 待用户补的字段（如技术负责人）。
-
-提示：「已过门禁并创建 N 个 change。对每个 change 调用 `/comate` 继续 design→build→verify→archive。」
-
----
-
-## Guardrails
-
-- 生成 change 前必先过门禁并评分（步骤 2），不可跳过；审阅只暴露问题、不替 PRD 补内容。
-- 评审报告**必生成**，不再询问是否生成。
-- 门禁状态以 `<PRD>.gate.yaml` 为唯一真相源；报告是人类可读派生物，二者冲突以 gate.yaml 为准。
-- 影响范围、用户行为、状态流转、数据契约、权限、异常处理或验收标准的歧义必须逐项确认；未清零只能停在 reviewing/blocked，或经用户授权走 passed-with-tbd（带 ⚠ 标记）。
-- AskUserQuestion 是真实阻塞点：文字输出/推荐/默认值/历史选择/用户未反对都不能替代明确回答。
-- 拆分粒度（1 PRD → 几个 change）由用户定，AI 只给建议不拍板。
-- 每个 change 承接 PRD 对应功能项，不另起炉灶；范围/依赖/验收与 PRD 对齐。
+- 待用户补的字段（如技术负责人）。
+
+提示：「已过门禁并创建 N 个 change。对每个 change 调用 `/comate` 继续 design→build→verify→archive。」
+
+---
+
+## Guardrails
+
+- 生成 change 前必先过门禁并评分（步骤 2），不可跳过；审阅只暴露问题、不替 PRD 补内容。
+- 评审报告**必生成**，不再询问是否生成。
+- 门禁状态以 `<PRD>.gate.yaml` 为唯一真相源；报告是人类可读派生物，二者冲突以 gate.yaml 为准。
+- 影响范围、用户行为、状态流转、数据契约、权限、异常处理或验收标准的歧义必须逐项确认；未清零只能停在 reviewing/blocked，或经用户授权走 passed-with-tbd（带 ⚠ 标记）。
+- AskUserQuestion 是真实阻塞点：文字输出/推荐/默认值/历史选择/用户未反对都不能替代明确回答。
+- 拆分粒度（1 PRD → 几个 change）由用户定，AI 只给建议不拍板。
+- 每个 change 承接 PRD 对应功能项，不另起炉灶；范围/依赖/验收与 PRD 对齐。
 - 多 change 时在各 change 的 In/Out Scope 显式互引边界职责归属。
 - 扇出必须以 `gate fanout-status` 为持久化进度真相；`TaskCreate` 仅作展示，不得替代 gate.yaml 状态。
-- 门禁通过后 PRD 若被改（哈希漂移），gate 转 stale，禁止再扇出 change，须重跑本 skill。
-- 契约以项目架构文档（如 `docs/architecture/`，若存在）为事实源，change 里点名遵循了哪条，不硬编码具体值、不自造。
-- 不写应用代码——本 skill 止于「过门禁 + 拆分 + 建 change 骨架」，实现由后续 comate 阶段驱动。
+- 门禁通过后 PRD 若被改（哈希漂移），gate 转 stale，禁止再扇出 change，须重跑本 skill。
+- 契约以项目架构文档（如 `docs/architecture/`，若存在）为事实源，change 里点名遵循了哪条，不硬编码具体值、不自造。
+- 不写应用代码——本 skill 止于「过门禁 + 拆分 + 建 change 骨架」，实现由后续 comate 阶段驱动。

package/skills/comate-gate/scaffold/docs/README.md

@@ -1,36 +1,36 @@
-# docs 文档目录说明
-
-本目录承载项目的长期文档,与代码同仓库、同评审、同版本管理。按用途分为以下几类:
-
-| 子目录 | 定位 | 说明 |
-|--------|------|------|
-| `architecture/` | 架构规范 | 前后端分层、依赖规则、命名、错误码等工程铁律,以仓库**当前实现**为准 |
-| `knowledge-base/` | 知识库 | 上游需求(PRD)与横向(第三方对接)的长期文档,详见其内 `README.md` |
-
-## architecture/
-
-工程约束的唯一来源,是 `/comate-gate` PRD 门禁审阅中「契约对齐」的事实源。改对应层代码前必须先读。
-
-**占位目录,需根据项目实际情况建立规范文档**。常见架构文档包含:
-
-- 后端分层 / 依赖 / DTO / 错误码 / 命名。
-- 前端分层 / API / store / 路由 / 命名。
-- 工程原则与铁律。
-
-> 这些是**架构规则文档,不是 capability spec**,不放在 `openspec/specs/` 下,也不参与 `openspec validate --strict`。
-> 调整架构相关代码时,必须同步更新对应文档。
-
-## knowledge-base/
-
-需求与第三方对接的长期文档,是 comate 变更流程的上游:
-
-- `requirements/` —— 原始 PRD(产品需求文档)。PRD 经 `/comate-gate` 门禁与拆分后,扇出为 N 个 comate change。
-- `integrations/` —— 第三方业务/接口对接档案与索引,跨多个变更长期维护。
-
-完整的命名规则、溯源约定与铁律见 `knowledge-base/README.md`。
-
-## 与 openspec/ 的边界
-
-- `docs/` 放**长期文档**(架构规范、需求、对接档案)。
-- `openspec/` 放**变更驱动的规格**:`changes/`(一次性变更)与 `specs/`(能力沉淀)。
-- 两者通过 PRD 门禁状态(`<PRD>.gate.yaml`)与 change 的 `sources.manifest` 打通。
+# docs 文档目录说明
+
+本目录承载项目的长期文档,与代码同仓库、同评审、同版本管理。按用途分为以下几类:
+
+| 子目录 | 定位 | 说明 |
+|--------|------|------|
+| `architecture/` | 架构规范 | 前后端分层、依赖规则、命名、错误码等工程铁律,以仓库**当前实现**为准 |
+| `knowledge-base/` | 知识库 | 上游需求(PRD)与横向(第三方对接)的长期文档,详见其内 `README.md` |
+
+## architecture/
+
+工程约束的唯一来源,是 `/comate-gate` PRD 门禁审阅中「契约对齐」的事实源。改对应层代码前必须先读。
+
+**占位目录,需根据项目实际情况建立规范文档**。常见架构文档包含:
+
+- 后端分层 / 依赖 / DTO / 错误码 / 命名。
+- 前端分层 / API / store / 路由 / 命名。
+- 工程原则与铁律。
+
+> 这些是**架构规则文档,不是 capability spec**,不放在 `openspec/specs/` 下,也不参与 `openspec validate --strict`。
+> 调整架构相关代码时,必须同步更新对应文档。
+
+## knowledge-base/
+
+需求与第三方对接的长期文档,是 comate 变更流程的上游:
+
+- `requirements/` —— 原始 PRD(产品需求文档)。PRD 经 `/comate-gate` 门禁与拆分后,扇出为 N 个 comate change。
+- `integrations/` —— 第三方业务/接口对接档案与索引,跨多个变更长期维护。
+
+完整的命名规则、溯源约定与铁律见 `knowledge-base/README.md`。
+
+## 与 openspec/ 的边界
+
+- `docs/` 放**长期文档**(架构规范、需求、对接档案)。
+- `openspec/` 放**变更驱动的规格**:`changes/`(一次性变更)与 `specs/`(能力沉淀)。
+- 两者通过 PRD 门禁状态(`<PRD>.gate.yaml`)与 change 的 `sources.manifest` 打通。

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

@@ -1,31 +1,31 @@
-# architecture (架构规范占位目录)
-
-> ⚠️ **本目录由 `comate init` 创建为占位,内容需根据项目实际情况建立。**
-
-本目录是工程约束的**唯一来源**,也是 `/comate-gate` PRD 门禁审阅中「契约对齐架构文档」的事实源。
-
-## 为什么需要架构文档
-
-PRD 门禁审阅时,会检查数据来源、接口契约、命名规范、错误码、边界处理等是否明确。这些约束的**唯一事实源**应该是架构文档,而不是散落在 PRD/代码里的重复规则。
-
-`/comate-gate` 要求 PRD 里的契约「对齐并点名遵循了架构文档的哪条」,不硬编码具体值、不自造规则。
-
-## 建议包含的架构文档
-
-根据项目技术栈,常见架构文档包括:
-
-- **后端架构** — 分层(如 Controller / Service / Repository)、依赖规则、DTO 规范、错误码体系、命名约定、数据库表与字段命名、缓存 key 规范、权限收口。
-- **前端架构** — 分层(如 views / components / api)、状态管理、路由、API 调用规范、组件命名。
-- **工程原则** — 日志、监控、测试、发布流程等通用铁律。
-
-## 如何使用
-
-1. 根据项目实际情况,在本目录建立 `backend-architecture.md` / `frontend-architecture.md` 等文档。
-2. PRD 里涉及接口、数据库、错误码、命名时,引用并对齐这些文档的既有约定。
-3. 架构变更时,先更新本目录文档,再改代码。
-
-## 注意事项
-
-- 这些是**架构规则文档,不是 capability spec**,不放在 `openspec/specs/` 下。
-- 不参与 `openspec validate --strict`。
-- 由 `docs/knowledge-base/` 里的 PRD 引用,由 comate change 的 proposal/design 对齐。
+# architecture (架构规范占位目录)
+
+> ⚠️ **本目录由 `comate init` 创建为占位,内容需根据项目实际情况建立。**
+
+本目录是工程约束的**唯一来源**,也是 `/comate-gate` PRD 门禁审阅中「契约对齐架构文档」的事实源。
+
+## 为什么需要架构文档
+
+PRD 门禁审阅时,会检查数据来源、接口契约、命名规范、错误码、边界处理等是否明确。这些约束的**唯一事实源**应该是架构文档,而不是散落在 PRD/代码里的重复规则。
+
+`/comate-gate` 要求 PRD 里的契约「对齐并点名遵循了架构文档的哪条」,不硬编码具体值、不自造规则。
+
+## 建议包含的架构文档
+
+根据项目技术栈,常见架构文档包括:
+
+- **后端架构** — 分层(如 Controller / Service / Repository)、依赖规则、DTO 规范、错误码体系、命名约定、数据库表与字段命名、缓存 key 规范、权限收口。
+- **前端架构** — 分层(如 views / components / api)、状态管理、路由、API 调用规范、组件命名。
+- **工程原则** — 日志、监控、测试、发布流程等通用铁律。
+
+## 如何使用
+
+1. 根据项目实际情况,在本目录建立 `backend-architecture.md` / `frontend-architecture.md` 等文档。
+2. PRD 里涉及接口、数据库、错误码、命名时,引用并对齐这些文档的既有约定。
+3. 架构变更时,先更新本目录文档,再改代码。
+
+## 注意事项
+
+- 这些是**架构规则文档,不是 capability spec**,不放在 `openspec/specs/` 下。
+- 不参与 `openspec validate --strict`。
+- 由 `docs/knowledge-base/` 里的 PRD 引用,由 comate change 的 proposal/design 对齐。