@house365/comate 0.2.10 → 0.4.0

package/skills/comate-intake/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: comate-intake
+description: "comate 阶段 0：PRD 门禁与拆分。用 /comate-intake 调用。对原始 PRD 做质量审阅+评分+阻断闸门，通过后按依赖/独立性判定拆成 1 或 N 个 change，逐个交给 comate-open。门禁状态钉在 PRD 同级 <PRD>.gate.yaml，门禁未通过禁止建 change。"
+---
+
+# comate 阶段 0：PRD 门禁与拆分（Intake）
+
+**定位**：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>.gate.yaml`。评审报告 `PRD-REVIEW-<PRD名>.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 . ./.claude/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/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`/`需求` 的），用 **AskUserQuestion** 让用户选一个。
+- 读取后重点提取：**功能清单**（各功能项 + 优先级 P0/P1/P2）、**范围（In/Out）**、**第三方依赖**、**验收标准**、文档状态。
+- 若 PRD 明显未定稿（状态字段非「已定稿」等），用 **AskUserQuestion** 提示可能未冻结并暂停确认；确认前只审阅，不建 gate。
+
+### 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-REVIEW-<PRD名>.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。
+
+#### 复杂场景模式（阻断数 > 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. 完成后更新评审报告台账、重算 `blocking_open`。若依然未清零，回到本步骤 3 再次判定（通常经过深度澄清后会清零）。
+
+**只有 `blocking_open` 清零、或用户选 2 授权，才进入步骤 4。**
+
+### 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。** 确认后用 **TodoWrite** 把每个待建 change 建成任务项。
+
+### 5. 通过门禁
+
+映射与 `blocking_open` 都就绪后，置门禁通过：
+
+```bash
+bash "$COMATE" gate <prd> pass          # 阻断已清零
+# 或用户授权带 TBD：
+bash "$COMATE" gate <prd> pass --tbd
+```
+
+`pass` 会硬校验 `blocking_open=0` 且报告非空，并重钉 PRD 哈希——之后 PRD 再被改，哈希漂移会使门禁 `stale`，须重跑 `/comate-intake`。
+
+### 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 受影响处标 **「⚠ 待确认」** 并引用评审报告。
+
+多 change 时，在 PRD 同目录建 `CHANGES-MAP.md` 记录「功能项 → change」映射，便于回溯。
+
+### 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-intake/scaffold/docs/README.md

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

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

@@ -0,0 +1,31 @@
+# architecture (架构规范占位目录)
+
+> ⚠️ **本目录由 `comate init` 创建为占位,内容需根据项目实际情况建立。**
+
+本目录是工程约束的**唯一来源**,也是 `/comate-intake` PRD 门禁审阅中「契约对齐架构文档」的事实源。
+
+## 为什么需要架构文档
+
+PRD 门禁审阅时,会检查数据来源、接口契约、命名规范、错误码、边界处理等是否明确。这些约束的**唯一事实源**应该是架构文档,而不是散落在 PRD/代码里的重复规则。
+
+`/comate-intake` 要求 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 对齐。

package/skills/comate-intake/scaffold/docs/knowledge-base/README.md

@@ -0,0 +1,48 @@
+# 知识库 (Knowledge Base)
+
+本目录承载**需求(PRD)与第三方对接**的长期文档,与代码同仓库、同 PR 评审、同版本。
+
+## 文档体系与交接
+
+```
+docs/knowledge-base/requirements/
+  ├─ _templates/              PRD 模板
+  └─ <YYYYMMDD-功能名>/        一个功能一个目录,日期=该功能起始日   ──┐
+       ├─ PRD-001-<功能名>.md           产品需求文档                  │
+       ├─ PRD-001-<功能名>.gate.yaml    门禁状态(机器真相源)          │
+       ├─ PRD-REVIEW-PRD-001-<功能名>.md 门禁评审报告(人类可读)       │
+       └─ CHANGES-MAP.md               (多 change 时)功能项→change 映射 │
+                                                                    ├─→ /comate-intake (门禁+拆分)
+docs/knowledge-base/integrations/                                   │         ↓
+  第三方对接档案/索引 (跨需求长期存在)                              ──┘   comate changes
+```
+
+## PRD → comate 流程
+
+comate 采用**简化需求流**:只保留 **PRD**(产品需求文档),通过 `/comate-intake` 做两件事:
+
+1. **门禁**:审阅 PRD 质量、百分制评分、建阻断台账。阻断问题未清零,禁止建任何 change。
+2. **拆分**:按依赖/整体性/独立性/规模判定该 PRD 变成 1 或 N 个 comate change(粒度由用户定),逐个交给 `/comate-open`。
+
+PRD 门禁状态钉在同级 `<PRD名>.gate.yaml`(机器真相源,含 `gate_status` / `score` / `blocking_open` / `prd_hash` / `spawned_changes`)。评审报告为 `PRD-REVIEW-<PRD名>.md`(人类可读,含问题台账)。PRD 通过门禁后被改会因哈希漂移自动失效(`stale`),需重跑 intake。
+
+扇出的 comate change 内部用 proposal / design / tasks 承接 PRD 的功能项内容——**不再产独立 FRD 文档**,PRD 直接作为 change 的源文档被 `sources track` 钉住。
+
+## 命名约定
+
+- 功能目录: `<YYYYMMDD-功能名>/`,日期为该功能需求起始日,功能名用中文短名,如 `20260805-积分商城/`
+- PRD: 目录内 `PRD-<三位序号>-<功能名>.md`,功能名用目录功能名,如 `PRD-001-积分商城.md`
+- gate: 自动生成,`PRD-<三位序号>-<功能名>.gate.yaml`,与 PRD 同级
+- 评审报告: 自动生成,`PRD-REVIEW-PRD-<三位序号>-<功能名>.md`,与 PRD 同级
+
+## 横向 (integrations/)
+
+- `integrations/` —— 第三方业务/接口对接档案与总索引,**跨多个需求长期存在**。
+- 单个 PRD 生命周期随功能上线收敛;本目录的内容长期维护,故独立放置。
+- PRD 的「第三方依赖」表应链接到 `integrations/<平台名>/README.md`。
+
+## 溯源与可追溯
+
+- PRD 顶部溯源块可选(若有更上游背景文档);没有上游时 PRD 是起点。
+- PRD 经门禁后扇出的 change 名记录在 `<PRD>.gate.yaml` 的 `spawned_changes` 字段,形成 PRD → change 的正向链。
+- 每个 change 的 `sources.manifest` 记录 PRD 路径与 sha256,形成 change → PRD 的反向链。

package/skills/comate-intake/scaffold/docs/knowledge-base/integrations/_TEMPLATE/README.md

@@ -0,0 +1,49 @@
+# 第三方对接档案: <平台名>
+
+| 作者 | 更新时间 | 原文档地址 |
+|------|---------|-----------|
+| <建档/最近修改人,默认 git 用户名> | <YYYY-MM-DD,改动即更新> | <官方文档主 URL> |
+
+> 复制本目录,重命名为平台名,删除本行与所有 `<...>` 占位说明。
+> 本文件是「对接档案」——长期维护,不是官方文档副本。
+> 标题正下方的「作者/更新时间/原文档地址」三项**必填**:本档案是我方二开文档,须随时可追溯回官方原文。
+
+## 基本信息
+
+| 字段 | 内容 |
+|------|------|
+| 服务标识 | <目录名,如 oceanengine> |
+| 对接目的 | <为什么对接它,支撑哪个需求> |
+| 关联需求 | docs/knowledge-base/requirements/<YYYYMMDD-功能名>/PRD-001-<功能名>.md |
+| 关联变更 | openspec/changes/<变更名>/ |
+| 官方文档 | <URL> |
+| 我方负责人 | <name> |
+| 对方联系人 | <姓名/渠道,非必填> |
+| 接入状态 | 调研中 / 联调中 / 使用中 / 暂停使用 / 待下线 / 已下线 |
+| 最近校验 | <YYYY-MM-DD> |
+
+## 凭证与密钥位置(只写在哪,不写值)
+
+> ⚠️ 严禁把 token / secret / 私钥 写进本文件或任何 git 文件。
+
+| 凭证 | 存放位置 | 环境 |
+|------|---------|------|
+| AppKey/AppSecret | <如:K8s Secret xxx / 密钥系统路径> | 开发/生产 |
+
+## 接口清单(我方实际用到的)
+
+| 用途 | 方法/路径 | 限流/配额 | 备注 |
+|------|----------|----------|------|
+| <如 OAuth 换 token> | POST /xxx | <QPS/日配额> | <...> |
+
+详细字段摘录见 `api-snapshot.md`。
+
+## 失败与降级
+
+> PRD 门禁要求:凡有外部依赖必单列降级/失败场景。
+
+| 场景 | 表现 | 处理策略 |
+|------|------|----------|
+| 超时 | <...> | <重试/降级/告警> |
+| 未配置 | <...> | <...> |
+| 返回错误 | <...> | <...> |

package/skills/comate-intake/scaffold/docs/knowledge-base/integrations/_TEMPLATE/api-snapshot.md

@@ -0,0 +1,47 @@
+# <平台名> 接口摘录 (API Snapshot)
+
+| 作者 | 更新时间 | 原文档地址 |
+|------|---------|-----------|
+| <建档/最近修改人,默认 git 用户名> | <YYYY-MM-DD,改动即更新> | <官方文档主 URL> |
+
+> 只摘录**我方实际用到**的接口与字段,不复制官方全文。
+> 标题正下方的「作者/更新时间/原文档地址」三项**必填**(本档案是我方二开文档,须可追溯回官方原文)。
+> 官方文档: <URL>
+> 抓取日期: <YYYY-MM-DD>  ← 每次对照官方更新时改这里
+
+---
+
+## <接口1: 如 获取 access_token>
+
+**请求**
+```
+POST https://<host>/oauth/token
+Content-Type: application/json
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| app_key | string | 是 | 见 README 凭证位置 |
+| grant_type | string | 是 | 固定 client_credentials |
+
+**响应**
+```json
+{
+  "access_token": "<string>",
+  "expires_in": 7200
+}
+```
+
+| 字段 | 说明 | 我方注意点 |
+|------|------|-----------|
+| expires_in | 有效期(秒) | ⚠️ 实测 2h,需提前刷新 |
+
+**错误码/异常**
+
+| code/status | 含义 | 我方处理 |
+|-------------|------|----------|
+| <...> | <...> | <重试/告警/提示用户/忽略> |
+
+---
+
+## <接口2: ...>

package/skills/comate-intake/scaffold/docs/knowledge-base/requirements/_templates/PRD.md

@@ -0,0 +1,97 @@
+# PRD-<序号>-<功能名>: <产品标题>
+
+> 复制本文件到对应功能目录 `requirements/<YYYYMMDD-功能名>/`,按命名约定重命名(如 `PRD-001-积分商城.md`,功能名用目录功能名),删除本行与所有 `<...>` 占位说明。
+> PRD = 产品需求文档,回答「做成什么样」。**本 PRD 由 `/comate-intake` 直接读取**:先过质量门禁(审阅+评分+阻断),通过后按依赖/独立性拆成 1 或 N 个 comate change,由 comate 实现——无需再写 FRD。
+
+| 字段 | 内容 |
+|------|------|
+| 产品编号 | PRD-001-<功能名> |
+| 产品负责人 | <PM name> |
+| 技术负责人 | <未知则留待补,不杜撰> |
+| 创建日期 | <YYYY-MM-DD> |
+| 优先级 | 高 / 中 / 低 |
+| 状态 | 设计中 / 评审中 / 已定稿 |
+| 关联迭代 | <如 2026-08 迭代,没有可删> |
+
+## 需求概述
+
+<一句话讲清这个产品/功能解决什么问题、给谁用。>
+
+## 用户与场景
+
+| 角色 | 场景 | 想要达成 |
+|------|------|----------|
+| <运营> | <每天看投放数据> | <无需手工导出即可日级复盘> |
+
+## 用户故事
+
+- 作为 <角色>,我希望 <能力>,以便 <价值>。
+
+## 产品方案 (What — 产品视角)
+
+<整体方案描述。可配流程图/示意。说明产品形态:是页面、后台任务、API、还是看板等。>
+
+### 核心流程
+
+1. <用户/系统从哪开始>
+2. <经过哪些关键步骤>
+3. <到哪结束,产出什么>
+
+### 功能清单
+
+> `/comate-intake` 据此清单判定拆分粒度:有依赖的功能项归同一 change,独立的可拆开。请标清优先级。
+
+| 功能 | 说明 | 优先级 (P0/P1/P2) |
+|------|------|------------------|
+| <功能A> | <做什么> | P0 |
+
+## 范围
+
+**做什么 (In Scope)**
+- <...>
+
+**不做什么 (Out of Scope)**
+- <明确边界,避免范围蔓延>
+
+## 交互 / 界面要点
+
+<关键页面、状态、空态/异常态。可链接设计稿。非视觉类(如纯后台任务)说明触发与产出形态。>
+
+## 第三方依赖
+
+<是否依赖外部平台/接口。若有,链接到对接档案,并说明失败/降级处理:>
+
+| 第三方 | 用途 | 风险 | 失败/降级处理 | 负责人 |
+|--------|------|------|--------------|--------|
+| <平台名> | <本产品中用它做什么> | <限流/权限/回调/稳定性等> | <超时/未配置/返回错误如何处理> | <name> |
+
+> 对接档案: docs/knowledge-base/integrations/<平台名>/README.md
+
+## 数据与来源
+
+> 门禁重点审查项:用到的数据必须交代来源(哪张表/哪个接口/哪方提供)、口径、单位、时间范围。
+
+- **数据来源**: <积分从哪来?余额存哪张表?哪个接口读?>
+- **成功指标**: <上线后用什么衡量产品是否成功,尽量可度量>
+
+## 边界与异常
+
+> 门禁重点审查项:极值、空值、并发、权限、异常路径、第三方失败是否覆盖。
+
+- <库存不足 / 并发冲突 / 重复提交 / 无权限 等如何处理>
+
+## 验收标准 (产品视角)
+
+> 门禁重点审查项:必须**可度量**,避免「体验流畅」这类不可验证的表述。
+
+- [ ] <可验证的产品行为,如「兑换成功率 ≥ 99.9%」「P99 响应 ≤ 500ms」>
+
+## 决策记录
+
+<为什么这样设计、放弃了哪些方案、权衡点。哪些能力不做、为什么不做。>
+
+## 变更历史
+
+| 日期 | 改动 | 人 |
+|------|------|----|
+| <YYYY-MM-DD> | 创建 | <name> |

package/skills/comate-open/SKILL.md

@@ -59,6 +59,25 @@ bash "$COMATE" sources <name> track docs/knowledge-base/<path>.md --note "<可
 - 仅 `docs/knowledge-base/` 范围内的文件可追踪;范围外文件会被跳过并提示,`source_kind` 保持 `conversation`,不影响流程。
 - 边追踪边产生:若开题时为对话来源、设计中途才拿到知识库文档,后续任意阶段补 `sources <name> track` 即可,无需回到 open。
 
+### 2c. PRD 门禁前置守卫（从 PRD 建 change 时必须通过）
+
+若本 change **来自一份原始 PRD**（用户经 `/comate-intake` 拆分而来，或直接指定了来源 PRD），在创建 change 结构**之前**必须先过门禁守卫：
+
+```bash
+bash "$COMATE" gate <prd路径> check
+```
+
+- **PASS（exit 0）**：`<PRD>.gate.yaml` 存在、`gate_status ∈ {passed, passed-with-tbd}`、且 PRD 哈希未漂移。继续建 change。
+- **BLOCK（exit 1）**：门禁不存在 / 未通过 / PRD 通过后被改（stale）。**不得创建 change**，停止并提示用户先跑 `/comate-intake` 对该 PRD 过门禁。
+
+建成后把该 change 记回门禁：
+
+```bash
+bash "$COMATE" gate <prd路径> spawned <name>
+```
+
+需求**来自对话**（非 PRD）时跳过本步——门禁只约束「PRD → change」这条路径。通常本 skill 由 `/comate-intake` 调用并已备妥门禁；用户绕过 intake 直接建 change 时，本守卫是最后一道硬闸门。
+
 ### 3. 入口状态验证
 
 ```bash

package/skills/comate-verify/SKILL.md

@@ -52,13 +52,29 @@ git diff --stat "$BASE_REF"...HEAD
 
 ### 1b. 验证失败决策（决策阻塞点 4）
 
-验证不通过时**必须使用 AskUserQuestion 工具暂停等待用户决定修复或接受偏差**。规则见 `comate/reference/decision-points.md` 第 4 条。不得自动运行 `state transition verify-fail`，也不得自动调 `/comate-build`。
+验证不通过时**先按严重程度分类，再判定是否需要用户输入**。规则与"三类行动"判定见 `comate/reference/decision-points.md` 第 4 条。
 
-暂停时列出：失败项、是否 CRITICAL（构建失败/测试失败/安全问题/核心验收场景失败）、推荐处理。**不确定性原则**：无法确定严重程度时降级（SUGGESTION > WARNING > CRITICAL）。
+分类（**不确定性原则**：无法确定严重程度时降级 SUGGESTION > WARNING > CRITICAL）：
+- **CRITICAL**：构建失败 / 测试失败 / 安全问题 / 核心验收场景失败
+- **WARNING / SUGGESTION**：非阻断性问题（覆盖率不足、风格、优化建议等）
+- **Spec 漂移**：delta spec 与 design doc 矛盾（见 Step 2b 单独处理）
 
-用户选择后：
-- **全部修复**：`bash "$COMATE" state <name> transition verify-fail` 然后调 `/comate-build`
-- **逐项处理**：CRITICAL 必须修复；非 CRITICAL 可接受偏差但须在报告记录原因和影响。有任何 CRITICAL 时不允许跳过修复全部接受。
+按类别分流：
+
+1. **有任何 CRITICAL（且非 Spec 漂移）** —— 属"自动处理"，唯一安全动作就是修复。**不询问**，直接：
+   ```bash
+   bash "$COMATE" state <name> transition verify-fail
+   ```
+   然后调 `/comate-build`。回到 build 前如实报告：哪些是 CRITICAL 失败项、判定依据、将如何修复。
+
+2. **无 CRITICAL，仅 WARNING / SUGGESTION** —— 属"用户决策"（接受偏差是合法选择）。**一次性 AskUserQuestion 批量展示**全部失败项与推荐处理，提供：
+   - **全部修复**：`bash "$COMATE" state <name> transition verify-fail` 然后调 `/comate-build`
+   - **逐项处理**：勾选要修的项，其余接受偏差
+   - **接受偏差**：全部接受，须在报告记录每项原因和影响
+
+3. **Spec 漂移** —— 按 Step 2b 的单选题处理（属"用户决策"，必须暂停）。
+
+> CRITICAL 自动回 build 不代表跳过用户知情：回退前必须输出清晰的失败报告作为证据。若一次验证同时含 CRITICAL 与非 CRITICAL，以 CRITICAL 优先自动回 build，非 CRITICAL 项留待修复轮次一并处理。
 
 ### 2a. 轻量验证（小改动）