@house365/comate 0.9.3 → 0.9.4

package/skills/comate-gate/SKILL.md

@@ -1,262 +1,262 @@
----
-name: comate-gate
-description: "comate 阶段 0：PRD 门禁与拆分。用 /comate-gate 调用。对原始 PRD 做质量审阅+评分+阻断闸门，通过后按依赖/独立性判定拆成 1 或 N 个 change，逐个交给 comate-open。门禁状态钉在 PRD 同级 <PRD>.gate.yaml，门禁未通过禁止建 change。"
----
-
-# comate 阶段 0：PRD 门禁与拆分（Gate）
-
-**定位**：comate 五阶段（open→design→build→verify→archive）之前的上游入口。输入一份**原始 PRD**，产出「已过门禁、已拆分」的 N 个 change，各自进入 open 阶段。
-
-**两件事，缺一不可**：
-1. **门禁**：审阅 PRD 质量、百分制评分、建阻断台账。阻断问题未清零，**禁止建任何 change**。
-2. **拆分**：按依赖/整体性/独立性/规模判定该 PRD 变成几个 change，粒度由用户拍板（AI 只给建议）。
-
-**FRD 层已消解**：不再产独立 FRD 文档。PRD 直接作为 change 的源文档被 `sources track` 钉住，其内容顺着 open→design 流进 comate 原生产物（proposal / design / tasks）。
-
----
-
-## 核心铁律
-
-- **门禁状态是可验证的文件真相源**：钉在 PRD 同级 `<PRD-NNN>.gate.yaml`（如 `PRD-001.gate.yaml`）。评审报告 `<PRD-NNN>-REVIEW.md`（如 `PRD-001-REVIEW.md`）是给人看的派生物，**不是**状态源。
-- **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]         # 置 passed（要求 blocking_open=0 且报告非空）
-bash "$COMATE" gate <prd> spawned <change>     # 记录据此 PRD 扇出的 change
-bash "$COMATE" gate <prd> status [--json]      # 查状态（哈希漂移自动判 stale）
-bash "$COMATE" gate <prd> check                # comate-open 建 change 前的前置守卫
-```
-
----
-
-## 步骤
-
-### 1. 定位 PRD
-
-- 用户给了路径/编号 → 直接读该文件。
-- 未给 → 用 Glob 列出候选（默认约定 `docs/knowledge-base/requirements/**/PRD-*.md`，若项目无此结构，探测 `docs/**/*.md` 中文件名含 `PRD`/`需求` 的），按命中数分类（对齐 `comate/reference/decision-points.md` 首节三类框架）：
-  - **恰好 1 个候选** → 无 ≥2 有效选项，属"自动处理"：直接选中该 PRD 并**报告选了哪份**，不 AskUserQuestion。
-  - **多个候选** → 属"用户决策"：用 **AskUserQuestion** 让用户选一个。
-  - **0 个候选** → 属"停止条件"：报告在约定路径下未找到 PRD，请用户提供路径或确认 PRD 位置，不发明选项。
-- 读取后重点提取：**功能清单**（各功能项 + 优先级 P0/P1/P2）、**范围（In/Out）**、**第三方依赖**、**验收标准**、文档状态。
-- 若 PRD 明显未定稿（状态字段非「已定稿」等），用 **AskUserQuestion** 提示可能未冻结并暂停确认；确认前只审阅，不建 gate。
-
-### 1.5 命名规范化（前置，定位到 PRD 即检测）
-
-用户一旦指到 `docs/knowledge-base/requirements/` 下的文件，**先检测命名是否规范，再进门禁**——因为 gate.yaml 与评审报告的名字都从 PRD 的 `PRD-<NNN>` 前缀派生，名字不规范会连带派生错。comate 只有 PRD 一层（无 MRD/FRD、无固定负责人），只查这三样：
-
-| 对象 | 规范 | 反例 → 规范名 |
-|------|------|--------------|
-| 功能目录 | `<YYYYMMDD-功能名>/` | `图片素材管理/` → `20260614-图片素材管理/` |
-| PRD 文件 | 目录内 `PRD-<三位序号>-<功能名>.md`（序号紧跟类型在前） | `图片素材管理_PRD_V1.md` → `PRD-001-图片素材管理.md`；`PRD-1.md` → `PRD-001-图片素材管理.md` |
-| 派生文件 | `PRD-<NNN>.gate.yaml`、`PRD-<NNN>-REVIEW.md`（脚本自动按 PRD-NNN 前缀生成，无需手动命名） | 旧式 `PRD-001-图片素材管理.gate.yaml`、`PRD-REVIEW-PRD-001-图片素材管理.md` → 迁移到新名 |
-
-**检测到不规范时**（顺序很重要，避免断链）：
-
-1. 先 **Grep** 全仓搜旧文件名/旧路径的所有引用（正文、其它文档、`.comate.yaml` 的 `source_manifest`、gate.yaml 的 `prd_path`/`review_report`）。
-2. 用 **AskUserQuestion** 给出「旧名 → 建议新名」让用户确认（改名影响引用，不自作主张；功能名/日期推断不出时一并问）。
-3. 确认后 **`git mv`** 改名（目录、PRD 文件；已存在的旧 gate.yaml/报告一并 `git mv` 到新名），保留 git 历史，**不要** Write 新文件+删旧。
-4. **Edit** 把第 1 步搜到的引用全部改成新名/新路径。
-5. 再 **Grep** 一次旧名确认零残留。
-
-已规范或用户确认改名后，才进第 2 步门禁——此时 `gate review` 生成的 gate.yaml/报告自然是新名。若 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 review` 回显的 `review_report` 路径（PRD 同级 `<PRD-NNN>-REVIEW.md`，如 `PRD-001-REVIEW.md`）。内容含：评分 + 评级 + 一句话总评、问题台账表（`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
-bash "$COMATE" gate <prd> pass          # 阻断已清零
-# 或用户授权带 TBD：
-bash "$COMATE" gate <prd> pass --tbd
-```
-
-`pass` 会硬校验 `blocking_open=0` 且报告非空，并重钉 PRD 哈希——之后 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 内部会：
-- 先跑 `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>
-```
-
-若门禁是 `passed-with-tbd`，在该 change 的 proposal/design 受影响处标 **「⚠ 待确认」** 并引用评审报告。
-
-### 7. 收尾
-
-展示：
-- PRD 审阅评分 + 评级、阻断问题关闭情况；
-- 评审报告路径、gate.yaml 路径与最终 `gate_status`；
-- 拆分映射（功能项 → N 个 change）；
-- 已建的 change 列表（名称 + 承接功能项 + 是否带 ⚠ TBD）；
-- 待用户补的字段（如技术负责人）。
-
-提示：「已过门禁并创建 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 显式互引边界职责归属。
-- 门禁通过后 PRD 若被改（哈希漂移），gate 转 stale，禁止再扇出 change，须重跑本 skill。
-- 契约以项目架构文档（如 `docs/architecture/`，若存在）为事实源，change 里点名遵循了哪条，不硬编码具体值、不自造。
-- 不写应用代码——本 skill 止于「过门禁 + 拆分 + 建 change 骨架」，实现由后续 comate 阶段驱动。
+---
+name: comate-gate
+description: "comate 阶段 0：PRD 门禁与拆分。用 /comate-gate 调用。对原始 PRD 做质量审阅+评分+阻断闸门，通过后按依赖/独立性判定拆成 1 或 N 个 change，逐个交给 comate-open。门禁状态钉在 PRD 同级 <PRD>.gate.yaml，门禁未通过禁止建 change。"
+---
+
+# comate 阶段 0：PRD 门禁与拆分（Gate）
+
+**定位**：comate 五阶段（open→design→build→verify→archive）之前的上游入口。输入一份**原始 PRD**，产出「已过门禁、已拆分」的 N 个 change，各自进入 open 阶段。
+
+**两件事，缺一不可**：
+1. **门禁**：审阅 PRD 质量、百分制评分、建阻断台账。阻断问题未清零，**禁止建任何 change**。
+2. **拆分**：按依赖/整体性/独立性/规模判定该 PRD 变成几个 change，粒度由用户拍板（AI 只给建议）。
+
+**FRD 层已消解**：不再产独立 FRD 文档。PRD 直接作为 change 的源文档被 `sources track` 钉住，其内容顺着 open→design 流进 comate 原生产物（proposal / design / tasks）。
+
+---
+
+## 核心铁律
+
+- **门禁状态是可验证的文件真相源**：钉在 PRD 同级 `<PRD-NNN>.gate.yaml`（如 `PRD-001.gate.yaml`）。评审报告 `<PRD-NNN>-REVIEW.md`（如 `PRD-001-REVIEW.md`）是给人看的派生物，**不是**状态源。
+- **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]         # 置 passed（要求 blocking_open=0 且报告非空）
+bash "$COMATE" gate <prd> spawned <change>     # 记录据此 PRD 扇出的 change
+bash "$COMATE" gate <prd> status [--json]      # 查状态（哈希漂移自动判 stale）
+bash "$COMATE" gate <prd> check                # comate-open 建 change 前的前置守卫
+```
+
+---
+
+## 步骤
+
+### 1. 定位 PRD
+
+- 用户给了路径/编号 → 直接读该文件。
+- 未给 → 用 Glob 列出候选（默认约定 `docs/knowledge-base/requirements/**/PRD-*.md`，若项目无此结构，探测 `docs/**/*.md` 中文件名含 `PRD`/`需求` 的），按命中数分类（对齐 `comate/reference/decision-points.md` 首节三类框架）：
+  - **恰好 1 个候选** → 无 ≥2 有效选项，属"自动处理"：直接选中该 PRD 并**报告选了哪份**，不 AskUserQuestion。
+  - **多个候选** → 属"用户决策"：用 **AskUserQuestion** 让用户选一个。
+  - **0 个候选** → 属"停止条件"：报告在约定路径下未找到 PRD，请用户提供路径或确认 PRD 位置，不发明选项。
+- 读取后重点提取：**功能清单**（各功能项 + 优先级 P0/P1/P2）、**范围（In/Out）**、**第三方依赖**、**验收标准**、文档状态。
+- 若 PRD 明显未定稿（状态字段非「已定稿」等），用 **AskUserQuestion** 提示可能未冻结并暂停确认；确认前只审阅，不建 gate。
+
+### 1.5 命名规范化（前置，定位到 PRD 即检测）
+
+用户一旦指到 `docs/knowledge-base/requirements/` 下的文件，**先检测命名是否规范，再进门禁**——因为 gate.yaml 与评审报告的名字都从 PRD 的 `PRD-<NNN>` 前缀派生，名字不规范会连带派生错。comate 只有 PRD 一层（无 MRD/FRD、无固定负责人），只查这三样：
+
+| 对象 | 规范 | 反例 → 规范名 |
+|------|------|--------------|
+| 功能目录 | `<YYYYMMDD-功能名>/` | `图片素材管理/` → `20260614-图片素材管理/` |
+| PRD 文件 | 目录内 `PRD-<三位序号>-<功能名>.md`（序号紧跟类型在前） | `图片素材管理_PRD_V1.md` → `PRD-001-图片素材管理.md`；`PRD-1.md` → `PRD-001-图片素材管理.md` |
+| 派生文件 | `PRD-<NNN>.gate.yaml`、`PRD-<NNN>-REVIEW.md`（脚本自动按 PRD-NNN 前缀生成，无需手动命名） | 旧式 `PRD-001-图片素材管理.gate.yaml`、`PRD-REVIEW-PRD-001-图片素材管理.md` → 迁移到新名 |
+
+**检测到不规范时**（顺序很重要，避免断链）：
+
+1. 先 **Grep** 全仓搜旧文件名/旧路径的所有引用（正文、其它文档、`.comate.yaml` 的 `source_manifest`、gate.yaml 的 `prd_path`/`review_report`）。
+2. 用 **AskUserQuestion** 给出「旧名 → 建议新名」让用户确认（改名影响引用，不自作主张；功能名/日期推断不出时一并问）。
+3. 确认后 **`git mv`** 改名（目录、PRD 文件；已存在的旧 gate.yaml/报告一并 `git mv` 到新名），保留 git 历史，**不要** Write 新文件+删旧。
+4. **Edit** 把第 1 步搜到的引用全部改成新名/新路径。
+5. 再 **Grep** 一次旧名确认零残留。
+
+已规范或用户确认改名后，才进第 2 步门禁——此时 `gate review` 生成的 gate.yaml/报告自然是新名。若 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 review` 回显的 `review_report` 路径（PRD 同级 `<PRD-NNN>-REVIEW.md`，如 `PRD-001-REVIEW.md`）。内容含：评分 + 评级 + 一句话总评、问题台账表（`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
+bash "$COMATE" gate <prd> pass          # 阻断已清零
+# 或用户授权带 TBD：
+bash "$COMATE" gate <prd> pass --tbd
+```
+
+`pass` 会硬校验 `blocking_open=0` 且报告非空，并重钉 PRD 哈希——之后 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 内部会：
+- 先跑 `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>
+```
+
+若门禁是 `passed-with-tbd`，在该 change 的 proposal/design 受影响处标 **「⚠ 待确认」** 并引用评审报告。
+
+### 7. 收尾
+
+展示：
+- PRD 审阅评分 + 评级、阻断问题关闭情况；
+- 评审报告路径、gate.yaml 路径与最终 `gate_status`；
+- 拆分映射（功能项 → N 个 change）；
+- 已建的 change 列表（名称 + 承接功能项 + 是否带 ⚠ TBD）；
+- 待用户补的字段（如技术负责人）。
+
+提示：「已过门禁并创建 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 显式互引边界职责归属。
+- 门禁通过后 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` 打通。