@house365/comate 0.9.25 → 0.9.26

package/package.json

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

package/skills/comate-gate/SKILL.md

@@ -20,6 +20,7 @@ description: "comate 阶段 0：PRD 门禁与拆分。用 /comate-gate 调用。
 - **只审不改**：门禁只暴露 PRD 问题，不替 PRD 补内容、不替产品拍板。
 - **门禁未通过禁止建 change**：`gate_status ∈ {passed, passed-with-tbd}` 且 PRD 哈希未漂移，才允许 comate-open 建 change（由 `gate check` 硬强制）。
 - **拆分粒度由人定**：AI 给「功能项→change」映射建议，用户确认或改，AI 不拍板。
+- **先发散、后收敛**：门禁不只检查已写出的句子，还要主动扫描 PRD 的隐含假设、替代方向与未覆盖场景；只有涉及产品取舍的项才进入 AskUserQuestion，仓库事实优先查证。
 
 ---
 
@@ -72,38 +73,84 @@ PRD 的路径和文件名需要稳定、可追踪，以便 gate 状态和评审
 
 发现不规范时，先列出旧名和建议新名，等待用户确认后再用 `git mv` 改名，并同步修正引用。命名规范是流程前置条件；PRD 的正文格式不要求完全套用模板，只需能被审阅并包含可判断的需求内容。
 
-### 2. 门禁：质量审阅 + 评分（不可跳过）
+### 1.8 需求澄清扫描（内建 brainstorming，不另建 skill）
 
-先初始化 gate（钉当前 PRD 哈希、拿到报告路径）：
+命名检查通过后，先初始化 gate 并取得报告路径，再做一次**发散→收敛**扫描：
 
 ```bash
 bash "$COMATE" gate <prd> review
 ```
 
-**逐维度排查**（每条既看「有没有」，也看「清不清楚、能不能落地」）：
+该命令只初始化状态、钉 PRD 哈希并返回 `review_report`，不代替语义审阅。扫描目标是发现“PRD 没写但会改变实现或验收”的决策，而不是替用户写 PRD。
+
+若 `review_report` 指向的文件尚不存在，立即按该路径创建 Markdown 文件并写入标题、PRD 路径/哈希和本节扫描表；后续步骤持续追加到同一文件。不得假定 `gate review` 会替 agent 创建报告。
+
+**发散清单（逐项给结论）**：
+
+| 视角 | 至少检查 |
+|------|----------|
+| 问题与价值 | 要解决的用户问题、背景假设、成功/失败的业务结果；区分「交付功能」与「期望结果」 |
+| 用户与场景 | 角色/画像、主次优先级、触发场景、频率、跨角色冲突；匿名/未登录及无权限用户 |
+| 方案与取舍 | 枚举 PRD 中所有实质互斥方向（如同步/异步、客户端/服务端、SQL/NoSQL 等架构级选择）；检查可逆/不可逆决策、明确不做的替代方案及选择理由；若 PRD 未列举至少 2 种候选方案，AI 应主动识别技术路径并要求补充决策依据 |
+| 架构与边界 | 功能模块是否职责单一；模块间接口/契约是否明确；各模块能否不读内部实现就理解用途；是否可独立测试、部署或替换 |
+| 旅程与状态 | 主流程、分支、状态机、重复提交/回退/撤销、跨端或跨会话行为 |
+| 数据与规则 | 输入输出、来源、口径、生命周期、幂等/一致性、隐私分级、保留与删除 |
+| 非功能约束 | 性能（延迟/吞吐）、容量、可用性/SLA、可靠性、扩展性、成本、可观测性、无障碍/国际化（按场景适用） |
+| 依赖与交付 | 第三方/内部依赖、版本兼容、迁移、灰度/回滚、运营与支持责任 |
+| 风险与反例 | 误用、滥用、对抗输入、极值、空值、并发、网络/依赖失败、灾备与合规 |
+
+对每个视角标记 `已证实`、`需查证`、`需产品决策` 或 `不适用（说明理由）`，并记录原文/仓库证据。**不适用也要有理由**，不能用空白跳过。
+
+**收敛规则**：
+
+1. `需查证` 先用 Read/Glob/rg/LSP 核实；找到事实就引用来源，不向用户提问事实。判定门槛是：问题答案若可由仓库/架构/接口等既有事实唯一确定，才属”需查证”。
+2. `需产品决策` 转为阻断问题，必须包含：`ID`、触发假设、至少一个反例/替代方向、影响（范围/行为/数据/验收）及 2–3 个互斥选项。若 PRD 已列 A/B/C 等方向，必须逐一枚举并纳入取舍，不能只挑其中两项。
+   若答案涉及期望行为、阈值、范围、优先级或取舍，或仓库没有唯一事实而存在多个合理答案，一律属”需产品决策”；反例/替代方向须来自 PRD、仓库证据，或明确标注为假设，不得伪造事实。
+3. 每轮最多问 1–3 个高影响决策；**优先设计为多选题**；问题按依赖顺序排列，前一答案会改变后续选项时不得并行提问。**每个问题必须包含 AI 的推荐选项及理由**，便于用户快速决策。
+4. NFR 不按术语逐条机械提问，而按决策包合并：服务目标（性能/容量/SLA/可靠性）、数据保护（安全/隐私/合规）、可运营性（可观测性/成本/灰度/回滚）；仅询问会改变实现或验收的阈值与取舍。
+5. 若发现 4 个以上相互依赖的决策，进入步骤 3 的复杂场景分流，可由用户选择调用 `comate-grill`；否则在本 skill 内用 AskUserQuestion 收敛。步骤 1.8 负责发散发现和生成决策清单，**不会自动调用** `comate-grill`；后者只负责用户选择后的逐项深挖收敛。
+
+**NFR 适用性判定**：生产发布默认检查安全/隐私、可用性/恢复、可观测性和灰度/回滚；用户实时交互检查延迟，批处理/增长场景检查吞吐与容量，处理身份/敏感数据/资金时检查安全隐私合规，对外或多地区产品检查无障碍/国际化及地域合规，依赖外部系统时检查超时/重试/降级。只有存在明确证据表明该能力不进入本次范围或不会改变实现、发布、运营、验收时，才可标 `不适用`，并引用证据；不能用“PRD 未提及”作为不适用理由。**能力适用后，目标/阈值缺失仍是阻断**；不能把“适用但尚未定阈值”标为 N/A。阈值可以在用户明确授权后作为有限 TBD，但必须记录影响与补齐时点。
+
+将扫描结论写入评审报告的“澄清扫描”小节（视角 / 结论 / 证据或假设 / 是否阻断 / 用户决策 ID），并与问题台账保持同一 ID。扫描不会修改 PRD；用户确认的答案只更新报告和 gate 字段，除非用户另行要求补写 PRD。
+
+### 2. 门禁：质量审阅 + 评分（不可跳过）
+
+使用步骤 1.8 已初始化的 gate 和 `review_report`；不要在 PRD 未变化时重复执行 `gate review`。若 PRD 在澄清期间被修改，重新运行该命令以重钉哈希并从本步骤重新审阅。
+
+**逐维度排查**（先完成步骤 1.8 的澄清扫描，再对下表逐条审阅；每条既看「有没有」，也看「清不清楚、能不能落地」）：
 
 | 维度 | 查什么 |
 |------|--------|
 | 逻辑自洽 | 需求前后是否矛盾；流程有无断链；条件/分支是否闭合；功能项间是否冲突或重复 |
+| 架构与边界 | 功能模块是否职责单一；模块间接口是否明确；各模块能否不读内部实现就理解用途；是否可独立测试和部署 |
 | 数据与来源 | 用到的数据是否交代来源（哪张表/哪个接口/哪方提供）；口径/单位/时间范围是否明确 |
 | 边界与范围 | In/Out 是否清晰；极值、空值、并发、权限、异常路径是否覆盖；第三方失败/降级是否提及 |
 | 表述清晰 | 术语是否一致且有定义；有无「尽快/大量/若干」等模糊量词；验收是否可度量 |
-| 完整性 | 目标/背景、功能清单、优先级、验收标准、第三方依赖是否齐全；有无 TBD/待定 |
+| 完整性 | 目标/背景、功能清单、优先级、验收标准、第三方依赖是否齐全；**有无 TBD/TODO/待定/占位符；是否存在「后续补充」「详见 XX」等延迟决策** |
+| 价值与指标 | 是否定义目标结果、基线、目标值、观测窗口、护栏指标、指标 owner；功能验收通过不等于业务成功 |
+| 用户与场景 | 角色是否完整且有主次；关键场景、未登录/无权限、跨角色协作是否覆盖 |
+| 方案取舍 | 并列方案是否已选定；至少 2 种候选技术路径是否已枚举；选择理由、非目标方案、不可逆决策和回滚边界是否明确 |
+| 非功能与运营 | 性能/容量/SLA/可靠性/安全隐私/合规/可观测性/成本/无障碍国际化及上线回滚责任是否按场景覆盖 |
 
 **每个问题标严重程度三档：**
 - **严重**（扣 15 分）：阻断开发或导致做错方向（逻辑矛盾、关键数据无来源、核心边界缺失、需求自相冲突）。
 - **中**（扣 7 分）：影响实现质量或需返工（口径不清、部分异常路径未覆盖、验收不可度量）。
 - **低**（扣 2 分）：表述瑕疵、术语不统一、可读性问题，不影响方向。
 
+新增澄清项沿用同一扣分规则：未选目标方向、核心角色/优先级或成功判据通常为严重；缺少会改变发布架构或验收的 NFR 为严重，缺少局部阈值/运营细节为中；纯改进建议为低且非阻断。评分与阻断分别表达文档质量和能否安全推进，允许出现“分数较高但仍有阻断”，不得用分数覆盖阻断状态。
+
 **评分**（百分制，从 100 扣，扣到 0 为止）：≥85 优（可拆）、70–84 良（可拆，受影响处标待确认）、<70 待补（建议先补 PRD）。
 
 **先分流再提问**：
 - **仓库事实**（已有架构约定、字段、接口、对接档案）：先用 Read/Glob/rg 核实并引用来源，不丢给用户决定。
-- **产品决策**（范围、优先级、用户可见行为、状态流转、权限、数据口径、失败处理、验收规则）：必须用 **AskUserQuestion** 问用户，不得用推荐方案/历史偏好/「待确认」代替确认。
+- **产品决策**（目标方向、范围、角色及优先级、成功指标、用户可见行为、状态流转、权限、数据口径、失败处理、NFR 目标、验收规则）：必须用 **AskUserQuestion** 问用户，不得用推荐方案/历史偏好/「待确认」代替确认。
+
+步骤 1.8 发现的 `需产品决策` 与本节审阅发现的问题合并去重；即使 PRD 没有显式错误，只要存在未选定的产品方向、关键角色优先级、成功指标或适用的非功能目标，也要登记为阻断并提问。
 
 **写评审报告（必生成）** 到 `gate review` 回显的 `review_report` 路径（与 PRD 同级，由脚本确定性命名）。内容含：评分 + 评级 + 一句话总评、问题台账表（`ID` / 维度 / 严重程度 / 原文依据 / 影响章节 / 是否阻断 / 建议 / 产品回填列）、逐条问题。若无问题，明确写「审阅通过，未发现阻断项」。
 
-**阻断规则**：影响范围、用户行为、状态流转、数据契约、权限、异常处理或验收标准的问题标「阻断」。把当前未关闭的阻断问题数写入 gate：
+**阻断规则**：影响目标方向、目标用户/角色优先级、成功判据、范围、用户行为、状态流转、数据契约、权限、异常处理、适用的非功能目标或验收标准的问题标「阻断」。泛化改进建议只有在“不确认也不会改变实现、发布或验收”时才可记为非阻断。把当前未关闭的阻断问题数写入 gate：
 
 ```bash
 bash "$COMATE" gate <prd> set score <分数>
@@ -112,7 +159,7 @@ bash "$COMATE" gate <prd> set blocking_open <未关闭阻断数>
 
 ### 3. 阻断闸门（AskUserQuestion）
 
-**若 `blocking_open > 0`**，先判定复杂度：
+**若 `blocking_open > 0`**，先判定复杂度（阻断既包括传统审阅问题，也包括步骤 1.8 发现的未决策项）：
 
 - **阻断数 ≤ 3 且无明显依赖链** → 默认模式（批量+分轮处理）
 - **阻断数 > 3 或存在决策依赖链** → 提供深度澄清选项
@@ -126,6 +173,8 @@ bash "$COMATE" gate <prd> set blocking_open <未关闭阻断数>
 
 对每轮最多 1–3 个高影响决策提问；每个问题给 `ID`、原文依据、影响、2–3 个互斥选项、推荐项及后果，允许自定义答案。用户回答后更新报告台账、重算 `blocking_open`，直到清零或用户选 2。**清零或授权后，立即继续执行步骤 4（拆分判定）。**
 
+`passed-with-tbd` 不是默认的“先做再说”：目标方向、核心角色/优先级、业务成功判据等不可逆或会导致做错方向的阻断，默认应先补齐或深度澄清；只有用户针对这些 ID 明确接受风险、指定补齐责任人与时点，才可授权带 TBD。性能等可后置阈值也必须标注影响、验证方式和截止时点。
+
 #### 复杂场景模式（阻断数 > 3 或有依赖链）
 
 用 **AskUserQuestion** 暂停，给四选项：
@@ -146,7 +195,7 @@ bash "$COMATE" gate <prd> set blocking_open <未关闭阻断数>
 
 2. `comate-grill` 会逐个决策点深挖，每个问题附推荐答案，等用户确认后进入下一个，直到所有分支清晰。
 
-3. `comate-grill` 完成后，**立即**更新评审报告台账、重算 `blocking_open`。若依然未清零，回到本步骤 3 再次判定（通常经过深度澄清后会清零）。
+3. `comate-grill` 完成后，**立即**更新评审报告中的“澄清扫描”和问题台账，重算 `blocking_open`。若依然未清零，回到本步骤 3 再次判定（通常经过深度澄清后会清零）。
 
 4. **`blocking_open` 清零后，立即继续执行步骤 4（拆分判定）。**
 
@@ -255,7 +304,8 @@ bash "$COMATE" gate <prd> spawned <change-name>
 - 生成 change 前必先过门禁并评分（步骤 2），不可跳过；审阅只暴露问题、不替 PRD 补内容。
 - 评审报告**必生成**，不再询问是否生成。
 - 门禁状态以 `<PRD>.gate.yaml` 为唯一真相源；报告是人类可读派生物，二者冲突以 gate.yaml 为准。
-- 影响范围、用户行为、状态流转、数据契约、权限、异常处理或验收标准的歧义必须逐项确认；未清零只能停在 reviewing/blocked，或经用户授权走 passed-with-tbd（带 ⚠ 标记）。
+- 影响目标方向、目标用户/角色优先级、成功判据、范围、用户行为、状态流转、数据契约、权限、异常处理、适用的非功能目标或验收标准的歧义必须逐项确认；未清零只能停在 reviewing/blocked，或经用户授权走 passed-with-tbd（带 ⚠ 标记）。
+- 必须完成步骤 1.8 的全部视角并在报告中留下结论；不能因为 PRD 文字自洽就跳过隐含假设、替代方向、角色、成功指标或适用的非功能约束。
 - AskUserQuestion 是真实阻塞点：文字输出/推荐/默认值/历史选择/用户未反对都不能替代明确回答。
 - 拆分粒度（1 PRD → 几个 change）由用户定，AI 只给建议不拍板。
 - 每个 change 承接 PRD 对应功能项，不另起炉灶；范围/依赖/验收与 PRD 对齐。