@house365/comate 0.2.10 → 0.4.0

package/README.md

@@ -7,13 +7,14 @@ comate 把 **OpenSpec**(WHAT:提案、规约生命周期、归档)和 **Superpow
 ## 五阶段
 
 ```
-/comate  ──自动探测阶段──┐
-                         ▼
-open → design → build → verify → archive
+[原始 PRD] ─→ /comate-intake ─┐  (阶段 0:门禁+拆分)
+                              ▼
+/comate  ──自动探测阶段──────→ open → design → build → verify → archive
 ```
 
 | 阶段 | skill | 职责 |
 |------|-------|------|
+| intake | `/comate-intake` | (阶段 0,可选)对原始 PRD 做质量门禁 + 拆分成 N 个 change |
 | open | `/comate-open` | 探索想法,创建 change 结构并初始化 `.comate.yaml` |
 | design | `/comate-design` | 技术设计与方案 brainstorming |
 | build | `/comate-build` | 按任务实现并提交 |
@@ -22,6 +23,10 @@ open → design → build → verify → archive
 
 预设路径:`/comate-hotfix`(热修)、`/comate-tweak`(文案/配置小调整)。
 
+工具 skill:`/comate-grill`(决策点穷追式澄清)——对计划/设计/PRD 的模糊点逐个深挖,每问附推荐答案、一次一问,直到歧义清零。comate-intake 在阻断问题多、有依赖链时会自动提供「深度澄清」选项调用它;也可单独 `/comate-grill <话题>` 挑战自己的计划草稿。
+
+**阶段 0(PRD 门禁与拆分)**:需求若来自一份**原始 PRD**,先过 `/comate-intake`——它审阅 PRD 质量、百分制评分、建阻断台账,门禁通过前禁止建任何 change;通过后按依赖/独立性判定把 PRD 拆成 1 或 N 个 change(粒度由用户定),逐个交给 `/comate-open`。门禁状态钉在 PRD 同级 `<PRD>.gate.yaml`,PRD 通过后被改会自动失效需重跑。需求来自对话时无需此阶段,直接从 open 起步。
+
 ## 安装
 
 ```bash
@@ -35,7 +40,7 @@ cd your-project
 comate init
 ```
 
-`init` 会装好 comate 及其依赖（OpenSpec CLI、Superpowers），并创建 `openspec/` 项目结构。支持 Claude Code、Codex、Cursor 等 70+ agent。可重复执行，已装的自动跳过。
+`init` 会装好 comate 及其依赖（OpenSpec CLI、Superpowers），创建 `openspec/` 项目结构，并铺出 `docs/` 知识库骨架（`docs/knowledge-base/requirements/` 放 PRD + PRD 模板、`docs/architecture/` 架构规范占位、integrations 对接模板）——`/comate-intake` 从这里读 PRD。支持 Claude Code、Codex、Cursor 等 70+ agent。可重复执行，已装的自动跳过，已有的 docs 文件不覆盖。
 
 skills 装到用户级（`~/.agents/skills`），装一次所有项目共用；`openspec/` 是项目自己的规约，建在当前目录，所以 `init` 需要在项目目录下运行。
 
@@ -63,7 +68,9 @@ skills/
     reference/       决策点、脏工作树协议、前置条件
     tests/           bats 测试
   comate-open/ design/ build/ verify/ archive/   各阶段 skill
+  comate-intake/                                  阶段 0:PRD 门禁与拆分
   comate-hotfix/ tweak/                           预设路径 skill
+  comate-grill/                                   决策点穷追式澄清工具
 docs/
   COMATE_MANUAL.md   完整操作手册
 ```

package/bin/init-run.mjs

@@ -11,6 +11,7 @@ import {
   npmInvocation,
   openSpecState,
   run,
+  scaffoldDocs,
   skillsInvocation,
   superpowersInstalled,
 } from './init.mjs';
@@ -147,6 +148,21 @@ export async function init(pkgRoot) {
     results.push(['openspec/', r2.ok ? 'installed' : 'failed', r2.ok ? '' : r2.reason, r2.output]);
   }
 
+  // 5. docs/ knowledge-base scaffold. /comate-intake reads PRDs from
+  // docs/knowledge-base/requirements/ (comate_kb_root is hardcoded there), so a
+  // fresh project has nowhere to put a PRD. Idempotent — existing files are left
+  // alone, only missing pieces are filled in, so re-running never clobbers a
+  // project's real docs. A failure here is non-fatal to the rest of the install.
+  const sc = scaffoldDocs(pkgRoot);
+  if (!sc.ok) {
+    results.push(['docs/', 'failed', sc.reason]);
+  } else if (sc.created === 0) {
+    results.push(['docs/', 'skipped', '已存在']);
+  } else {
+    const note = sc.skipped > 0 ? `新建 ${sc.created} 个文件,保留 ${sc.skipped} 个已有` : '';
+    results.push(['docs/', 'installed', note]);
+  }
+
   stopSpinner();
   return report(results);
 }

package/bin/init.mjs

@@ -9,7 +9,7 @@
 // ponytail: no SKILLS_AGENT_MAP here. The skills CLI detects the running agent
 // on its own, so translating platform ids to agent names would be dead code.
 import { spawnSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, copyFileSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 
@@ -172,6 +172,45 @@ function superpowersInstalled(scope) {
   return roots.some((root) => SUPERPOWERS_MARKERS.some((m) => existsSync(join(root, ...m))));
 }
 
+// The docs scaffold ships inside the comate skill, so it is present both in dev
+// (repo checkout) and after `skills add` copies the skill to ~/.agents/skills.
+// Locating it relative to pkgRoot means init reads the same tree it packed.
+function scaffoldSourceDir(pkgRoot) {
+  return join(pkgRoot, 'skills', 'comate-intake', 'scaffold', 'docs');
+}
+
+// copyTreeSkipExisting — recursively copy src→dst, never overwriting a file that
+// already exists. Returns { created, skipped } counts so init can report whether
+// it actually laid anything down (matching the openspec/ step's idempotence:
+// an existing docs/ is left alone, only missing pieces are filled in).
+function copyTreeSkipExisting(src, dst, acc = { created: 0, skipped: 0 }) {
+  mkdirSync(dst, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    const s = join(src, entry);
+    const d = join(dst, entry);
+    if (statSync(s).isDirectory()) {
+      copyTreeSkipExisting(s, d, acc);
+    } else if (existsSync(d)) {
+      acc.skipped++;
+    } else {
+      copyFileSync(s, d);
+      acc.created++;
+    }
+  }
+  return acc;
+}
+
+// scaffoldDocs — lay down docs/ (knowledge-base + architecture placeholder + PRD
+// template) so /comate-intake has somewhere to read PRDs from. comate_kb_root in
+// comate-lib.sh is hardcoded to docs/knowledge-base, so this path is not
+// configurable — it must match. Idempotent: existing files are never clobbered.
+function scaffoldDocs(pkgRoot, cwd = process.cwd()) {
+  const src = scaffoldSourceDir(pkgRoot);
+  if (!existsSync(src)) return { ok: false, reason: `scaffold source missing: ${src}` };
+  const { created, skipped } = copyTreeSkipExisting(src, join(cwd, 'docs'));
+  return { ok: true, created, skipped };
+}
+
 export {
   MIN_OPENSPEC,
   NPM_TIMEOUT_MS,
@@ -186,4 +225,7 @@ export {
   atLeast,
   openSpecState,
   superpowersInstalled,
+  scaffoldSourceDir,
+  copyTreeSkipExisting,
+  scaffoldDocs,
 };

package/docs/COMATE_MANUAL.md

@@ -33,13 +33,17 @@ comate 是一个规约驱动、AI 辅助的开发编排器。它将 **OpenSpec**
 ### 1.2 五阶段流程
 
 ```
+[原始 PRD] -> /comate-intake -┐  (阶段 0：门禁 + 拆分)
+                              v
 /comate
   auto-detect
 /comate-open -> /comate-design -> /comate-build -> /comate-verify -> /comate-archive
   (OpenSpec)      (Superpowers)      (Superpowers)      (两者)            (OpenSpec)
 ```
 
-流程链：open -> design -> build -> verify -> archive
+流程链：(intake ->) open -> design -> build -> verify -> archive
+
+**阶段 0（可选，PRD 门禁与拆分）**：需求来自一份**原始 PRD**时，先过 `/comate-intake`：审阅 PRD 质量、百分制评分、建阻断台账，门禁通过前禁止建任何 change；通过后按依赖/整体性/独立性/规模把 PRD 拆成 1 或 N 个 change（粒度由用户定），逐个交给 `/comate-open`。门禁状态钉在 PRD 同级 `<PRD>.gate.yaml`（机器真相源），评审报告为 `PRD-REVIEW-<PRD名>.md`（人类可读）。PRD 通过门禁后被改会因哈希漂移自动失效（stale），需重跑 intake。需求来自对话时无需此阶段。
 
 单次 `/comate` 调用从检测到的阶段开始，当退出条件满足时推进到下一阶段。智能体会自动推进后续阶段，但必须在决策阻塞点暂停，直到收到用户确认。
 
@@ -48,10 +52,15 @@ comate 是一个规约驱动、AI 辅助的开发编排器。它将 **OpenSpec**
 - **hotfix**：Bug 修复 / 热修复 —— 跳过头脑风暴，直接走 open -> build -> verify -> archive
 - **tweak**：非 Bug 的微调（文本、配置、文档、提示词）—— 跳过头脑风暴和完整计划，走 open -> 轻量 build -> 轻量 verify -> archive
 
+### 1.3.1 工具 skill
+
+- **grill**（`/comate-grill`）：决策点穷追式澄清。对计划/设计/PRD 的模糊点做深度优先遍历，逐个决策点给推荐答案并等用户确认，直到歧义清零。不是阶段，是跨阶段可复用的工具。comate-intake 在阻断问题 > 3 或有依赖链时会提供「深度澄清」选项自动调用它；用户也可 `/comate-grill <话题>` 直接挑战自己的计划草稿。算法内化自社区 grill-me pattern，避免外部依赖漂移。
+
 ### 1.4 命令快速参考
 
 | 命令 | 阶段 | 归属 | 产出物 |
 |---------|-------|-------|-----------|
+| `/comate-intake` | 0. PRD 门禁与拆分 | Claude | `<PRD>.gate.yaml`, 评审报告, N 个 change |
 | `/comate-open` | 1. 启动 | OpenSpec | proposal.md, design.md, tasks.md |
 | `/comate-design` | 2. 深度设计 | Superpowers | 设计文档, delta spec |
 | `/comate-build` | 3. 规划与构建 | Superpowers | 实现计划, 代码提交 |
@@ -59,6 +68,7 @@ comate 是一个规约驱动、AI 辅助的开发编排器。它将 **OpenSpec**
 | `/comate-archive` | 5. 归档 | OpenSpec | delta->main spec 同步, 设计文档标注, 归档 |
 | `/comate-hotfix` | 预设 | 两者 | 快速修复（跳过头脑风暴） |
 | `/comate-tweak` | 预设 | 两者 | 微调（跳过头脑风暴 + 完整计划） |
+| `/comate-grill` | 工具 | Claude | 决策台账（逐决策点澄清，附推荐 + 用户答案） |
 
 ---
 
@@ -69,7 +79,7 @@ npm install -g @house365/comate
 cd your-project && comate init
 ```
 
-`init` 会装好下面 2.2–2.4 的全部内容。本节余下部分用于排查：init 报某项失败时，对照确认要装什么、怎么自查。
+`init` 会装好下面 2.2–2.4 的全部内容，并铺出 `docs/` 知识库骨架（2.5）。本节余下部分用于排查：init 报某项失败时，对照确认要装什么、怎么自查。
 
 ### 2.1 运行环境
 
@@ -113,6 +123,27 @@ comate 使用以下 OpenSpec 能力（以技能形式调用）：`openspec-explo
 
 comate 以 npm 包分发（`npm install -g @house365/comate`），`comate init` 通过 skills CLI 装到用户级 `~/.agents/skills`，一次装完所有项目共用，支持 Claude Code、Codex、Cursor 等 70+ agent。
 
+### 2.5 docs/ 知识库骨架（阶段 0 用）
+
+`comate init` 会在项目里铺出 `docs/` 骨架，供 `/comate-intake` 读写 PRD：
+
+```
+docs/
+├── README.md                                   # docs 目录说明
+├── architecture/README.md                      # 架构规范占位（契约事实源，需项目自建）
+└── knowledge-base/
+    ├── README.md                               # PRD → comate 流程说明 + 命名约定
+    ├── requirements/_templates/PRD.md          # PRD 模板（comate 版，无 MRD/FRD 层）
+    └── integrations/_TEMPLATE/                  # 第三方对接档案模板（README + api-snapshot）
+```
+
+- 路径与 `comate-lib.sh` 硬编码的 `comate_kb_root=docs/knowledge-base` 对齐，PRD 放 `requirements/<YYYYMMDD-功能名>/` 下。
+- **幂等且不覆盖**：逐文件跳过已存在的，重跑 `comate init` 不动你已改过的 docs。
+- `architecture/` 只给占位 README（架构内容项目专属），是 PRD 门禁「契约对齐」的事实源，需按项目实际补齐。
+- 不含 MRD/FRD 模板——comate 只保留 PRD 层，FRD 内容消解进 change 的 proposal/design/tasks。
+
+### 2.6 comate 本身的技能布局
+
 采用扁平布局——每个 phase 是顶层技能目录，而非 `comate/<phase>/` 嵌套。部分 agent（含 Claude Code）只发现顶层目录，扁平是共同可用的最小公倍数：
 
 ```
@@ -511,6 +542,21 @@ bash `""` doctor
 
 清单文件位于 `openspec/changes/<name>/.comate/sources.manifest`，随 change 进版本库、随归档保留。design 与 build 阶段 guard 会复算知识库文件哈希、与清单比对，漂移则阻塞。
 
+### gate - PRD 门禁（阶段 0）
+
+对**原始 PRD** 做质量门禁，通过前禁止从该 PRD 建 change。状态钉在 PRD 同级 `<PRD>.gate.yaml`（独立于 change 的 `.comate.yaml`），评审报告为 `PRD-REVIEW-<PRD名>.md`。由 `/comate-intake` 驱动。
+
+| 命令 | 描述 |
+|---------|-------------|
+| `gate <prd> review` | 建/刷新 gate.yaml，钉当前 PRD sha256，回显评审报告路径。PRD 变了则状态重置为 `reviewing` |
+| `gate <prd> set <field> <value>` | 写字段：`score` / `blocking_open` / `gate_status` 等 |
+| `gate <prd> pass [--tbd]` | 置 `passed`（`--tbd` 置 `passed-with-tbd`）。硬校验 `blocking_open=0` 且评审报告非空，并重钉哈希 |
+| `gate <prd> spawned <change>` | 记录据此 PRD 扇出的 change（逗号拼接） |
+| `gate <prd> status [--json]` | 查状态；哈希漂移时自动判 `stale`（不改文件） |
+| `gate <prd> check` | comate-open 建 change 前的前置守卫。PASS 要求 gate 存在、状态 ∈ {passed, passed-with-tbd}、哈希未漂移；否则退出码 1 阻塞 |
+
+`gate_status` 取值：`reviewing`（审阅中）/ `blocked`（有未关闭阻断项）/ `passed`（阻断清零，可扇出）/ `passed-with-tbd`（用户授权带 TBD，change 需标 ⚠）/ `stale`（PRD 通过后被改，须重过门禁）。退出码契约同 guard：0 通过 / 1 阻塞 / 2 用法 / 3 环境 / 4 状态损坏。
+
 ### archive - 归档
 
 | 命令 | 描述 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@house365/comate",
-  "version": "0.2.10",
+  "version": "0.4.0",
   "description": "comate —— OpenSpec + Superpowers 规约驱动的 AI 开发编排器（Agent Skills）",
   "type": "module",
   "license": "MIT",

package/skills/comate/SKILL.md

@@ -24,10 +24,12 @@ agent 做决策只需读本节，其余参见末尾「参考附录」。决策
 **预设探测优先级最高**：
 - 用户明确描述 bug 修复/热修 + 满足 hotfix 条件 → 直接调用 `/comate-hotfix`
 - 用户明确描述文案/配置/文档/prompt 小调整 + 满足 tweak 条件 → 直接调用 `/comate-tweak`
+- **用户输入指向一份原始 PRD**（给了 PRD 路径/编号，或明确说「这是 PRD / 从这份需求文档开始」，典型路径 `docs/knowledge-base/**/PRD-*.md`）**且无对应活跃 change** → 直接调用 `/comate-intake`（阶段 0：先过门禁，再拆分建 change）。不要直接调 `/comate-open`——PRD 必须先过质量门禁。
 - 无预设命中 → 按下表处理
 
 | 活跃 change | 用户输入 | 行为 |
 |-------------|----------|------|
+| 无 | 指向原始 PRD | → 调用 `/comate-intake` |
 | 无 | 非预设输入 | → 调用 `/comate-open` |
 | 恰好 1 个 | `/comate <描述>` | → **询问**：继续该 change 还是新建 |
 | 多个 | `/comate <描述>` | → **询问**：继续已有还是新建；继续则列出供选择 |
@@ -48,7 +50,7 @@ agent 做决策只需读本节，其余参见末尾「参考附录」。决策
 - 每次上下文恢复都重跑 Step 0、Step 1；不要信任对话历史做阶段探测。
 - 有活跃 change 且工作树有未提交改动时，按 `comate/reference/dirty-worktree.md` 协议处理。
 - 若 `phase: build`，先检查 `build_mode`、`isolation`、`tdd_mode` 是否已设；任一未设则回 `/comate-build` 对应步骤补充；都已设则读 tasks.md 下一个未勾选任务继续。
-- 若 `phase: verify` 且 `verify_result: fail`，进入验证失败决策阻塞点（决策点 4）：暂停询问修复或接受偏差；仅在用户选修复后运行 `state transition <name> verify-fail` 并调用 `/comate-build`。
+- 若 `phase: verify` 且 `verify_result: fail`，按决策点 4 分级处理：CRITICAL 失败直接 `state transition <name> verify-fail` 回 `/comate-build`（不询问，回退前报告失败项）；仅 WARNING/SUGGESTION 或 Spec 漂移时才 AskUserQuestion 暂停。
 - 若 `phase: open` 但 proposal/design/tasks 已完成，先 `bash "$COMATE" guard <name> open --apply` 修复状态，再继续探测。
 - 若 `phase: archive`，只调用 `/comate-archive`；归档成功后 change 移入 archive 目录，不要再对旧活跃目录跑 guard。
 
@@ -99,6 +101,7 @@ agent 做决策只需读本节，其余参见末尾「参考附录」。决策
 
 | 命令 | 阶段 | Owner | 产物 |
 |------|------|-------|------|
+| `/comate-intake` | 0. PRD 门禁与拆分 | Claude | `<PRD>.gate.yaml`, 评审报告, N 个 change |
 | `/comate-open` | 1. 开题 | OpenSpec | proposal.md, design.md, tasks.md |
 | `/comate-design` | 2. 深度设计 | Superpowers | Design Doc, delta spec |
 | `/comate-build` | 3. 计划与构建 | Superpowers | 实施计划, 代码提交 |
@@ -108,12 +111,16 @@ agent 做决策只需读本节，其余参见末尾「参考附录」。决策
 | `/comate-tweak` | 预设 | 双方 | 小调整（跳过 brainstorming + 完整 plan） |
 
 ```
-/comate
+[原始 PRD] ──→ /comate-intake ──┐  (门禁+拆分，扇出 N 个 change)
+                  (Claude)        │
+/comate                           ▼
   ↓ 自动探测
 /comate-open ──→ /comate-design ──→ /comate-build ──→ /comate-verify ──→ /comate-archive
   (OpenSpec)      (Superpowers)      (Superpowers)      (双方)            (OpenSpec)
 ```
 
+需求来自对话时从 `/comate-open` 起步；来自原始 PRD 时先过 `/comate-intake` 门禁再拆分。
+
 ---
 
 ## 参考附录

package/skills/comate/reference/decision-points.md

@@ -4,14 +4,30 @@
 
 本文件集中定义 comate 全流程中**必须暂停等待用户**的决策点。各阶段 SKILL 用一行引用本文件的某一条，而不重复叙述规则，避免措辞漂移。
 
+## 先判定：这里真的需要用户输入吗？
+
+到达一个候选决策点时，**先分类，再决定是否阻塞**。不要把"需要做出选择"等同于"需要问用户"。
+
+| 类别 | 判据 | 处理 |
+|------|------|------|
+| **用户决策** | 存在 ≥2 个有效选项，且不同选项会改变范围、行为、可接受的风险或产生不可逆结果 | 阻塞，按下方通用规则用 AskUserQuestion 等待用户 |
+| **自动处理** | 在用户请求范围内只剩一个安全动作：修复客观失败、调和可验证的状态、重试幂等检查、或遵循已持久化的配置 | 直接执行并如实报告，**不制造确认点** |
+| **停止条件** | 缺依赖、状态损坏、路径逃逸、外部命令不可用，无有效下一步 | 报告阻塞与恢复条件，**不发明选项** |
+
+三条落地准则：
+
+1. **能合并的选择合并问**：相邻、可一次答完的选择放进同一次 AskUserQuestion，不拆成多次暂停。
+2. **不重复问已持久化且仍有效的选择**：配置文件或状态已记录且未失效时，直接沿用并说明。
+3. **先做能力预检再展示选项**：只呈现当前平台/仓库真正可执行的选项；某字段只剩一个有效值时，解释原因并直接应用，不为它单独制造一次暂停。
+
 ## 通用规则
 
-**决策点是阻塞点**。到达下列任一节点时，当前 `/comate` 调用必须停止，**使用 AskUserQuestion 工具等待用户选择**。只有在用户明确选择后，才能写入对应状态字段并继续执行，然后恢复自动推进。
+经上一节判定确属**用户决策**后，该节点即为**阻塞点**：当前 `/comate` 调用必须停止，**使用 AskUserQuestion 工具等待用户选择**。只有在用户明确选择后，才能写入对应状态字段并继续执行，然后恢复自动推进。
 
 - 文字输出**不能**替代工具等待。必须通过 AskUserQuestion 显式获得用户选择。
-- 不得用推荐规则、默认值或历史偏好替代用户确认。
+- 不得用推荐规则、默认值或历史偏好替代**用户决策类**节点的确认。
 - 推荐规则只能用于在问题里说明建议，不能代替用户拍板。
-- 其他无歧义的阶段流转必须自动进行，不得中途退出。
+- 其他无歧义的阶段流转、以及经判定属"自动处理"的节点，必须自动进行，不得中途退出，也不得为其伪造一次用户确认。
 
 ## 七个决策点
 
@@ -24,11 +40,15 @@
    引用：`comate-design` Step 1c。
 
 3. **构建工作方式选择**（build）
-   开始执行前，**一次性**询问工作区隔离方式（branch / worktree）、执行方式（subagent-driven-development / executing-plans）和 TDD 模式（tdd / direct）。一次交互内取得三项选择，并分别写入 `isolation`、`build_mode`、`tdd_mode`。
+   开始执行前，先做能力预检，再**一次性**就工作区隔离方式（current / branch / worktree）、执行方式（subagent-driven-development / executing-plans）、TDD 模式（tdd / direct）做一个**联合决策**；选 branch 时分支名也在同一次问清，不得二次暂停。
+   预检后某维度只剩一个可执行选项时，属"自动处理"：说明原因并直接写入对应字段，不为它单独制造暂停。仍有 ≥2 个有效选项的维度才进入 AskUserQuestion。三个维度全部只剩单值时，全部自动写入，本决策点跳过。
    引用：`comate-build` Step 3。
 
 4. **验证失败决策**（verify）
-   验证不通过时，暂停请用户决定全部修复 / 逐项处理 / 接受偏差。含 Spec 漂移处理（design doc 与 delta spec 矛盾）。CRITICAL 失败项必须修复。用户选择修复后才执行 `state transition <name> verify-fail` 并回到 build。
+   验证不通过时先按严重程度分类，**只有真正的用户决策才阻塞**：
+   - **CRITICAL（构建失败 / 测试失败 / 安全问题 / 核心验收场景失败）** —— 属"自动处理"，唯一安全动作就是修复。直接执行 `state transition <name> verify-fail` 回到 build，如实报告失败项，**不询问**。
+   - **Spec 漂移**（design doc 与 delta spec 矛盾）—— 属"用户决策"，必须 AskUserQuestion 暂停（见 Step 2b 三选项）。
+   - **仅 WARNING / SUGGESTION，无任何 CRITICAL** —— 属"用户决策"（可接受偏差是合法选择），一次性批量展示并提供「全部修复 / 逐项处理 / 接受偏差（记录原因）」。
    引用：`comate-verify` Step 1b、Step 2b 的 Spec 漂移处理。
 
 5. **分支收尾方式选择**（verify / finishing-a-development-branch）

package/skills/comate/scripts/comate-lib.sh

@@ -428,3 +428,97 @@ sources_drift() {
 
 # json_escape <string> — escape backslash and double-quote for JSON values.
 json_escape() { printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'; }
+
+# --- PRD gate (phase 0: quality gate + split) ---
+#
+# gate.yaml lives NEXT TO the PRD (<prd>.gate.yaml), not under openspec/changes,
+# so it has its own flat schema kept separate from the change .comate.yaml
+# FIELD_ORDER (mixing them would pollute every change state file with gate keys).
+# It is the machine truth for "may a change be spawned from this PRD"; the
+# markdown review report is the human-readable derivative.
+
+readonly GATE_SCHEMA_VERSION=1
+
+# Canonical field order for gate.yaml (same full-rewrite discipline as yaml_set).
+GATE_FIELD_ORDER=(
+  schema_version
+  prd_path
+  prd_hash
+  gate_status
+  score
+  blocking_open
+  review_report
+  spawned_changes
+  gated_at
+  created_at
+)
+
+# gate_status is the only enum. `stale` is computed (hash mismatch) but also
+# storable so a detected-stale gate persists across runs.
+declare -A GATE_ENUMS=(
+  [schema_version]="1"
+  [gate_status]="reviewing blocked passed passed-with-tbd stale"
+)
+
+# gate_path_for <prd> — echo the gate.yaml path adjacent to the PRD.
+# Strips a trailing .md/.markdown and appends .gate.yaml.
+gate_path_for() {
+  local prd="$1" base
+  base="${prd%.markdown}"
+  base="${base%.md}"
+  echo "${base}.gate.yaml"
+}
+
+# gate_report_for <prd> — echo the review report path (PRD same dir).
+gate_report_for() {
+  local prd="$1" dir base
+  dir=$(dirname "$prd")
+  base=$(basename "$prd")
+  base="${base%.markdown}"
+  base="${base%.md}"
+  echo "${dir}/PRD-REVIEW-${base}.md"
+}
+
+# gate_yaml_set <file> <key> <value> — gate-file analogue of yaml_set: validate
+# enum, read the whole file, set one key, rewrite every GATE_FIELD_ORDER field,
+# atomic mv, write-back verify.
+gate_yaml_set() {
+  local file="$1" key="$2" value="$3"
+  [ -f "$file" ] || die "$COMATE_CORRUPT" "ERROR: gate file not found: $file"
+
+  local known=0 k
+  for k in "${GATE_FIELD_ORDER[@]}"; do
+    [ "$k" = "$key" ] && { known=1; break; }
+  done
+  [ "$known" -eq 1 ] || die "$COMATE_USAGE" "ERROR: unknown gate field '$key'"
+
+  local legal="${GATE_ENUMS[$key]:-}"
+  if [ -n "$legal" ] && [ -n "$value" ] && [ "$value" != "null" ]; then
+    local ok=0 v
+    for v in $legal; do [ "$value" = "$v" ] && { ok=1; break; }; done
+    [ "$ok" -eq 1 ] || die "$COMATE_USAGE" "ERROR: invalid value '$value' for '$key' (expected: $legal)"
+  fi
+
+  declare -A _g
+  for k in "${GATE_FIELD_ORDER[@]}"; do
+    local cv; cv=$(yaml_get "$file" "$k")
+    [ -z "$cv" ] && cv="null"
+    _g[$k]="$cv"
+  done
+  _g[$key]="$value"
+
+  local tmp
+  tmp=$(mktemp "${TMPDIR:-/tmp}/comate-gate.XXXXXX") || die "$COMATE_ENV" "ERROR: mktemp failed"
+  {
+    printf '# comate PRD gate — flat key:value only, no nesting\n'
+    for k in "${GATE_FIELD_ORDER[@]}"; do
+      printf '%s: %s\n' "$k" "${_g[$k]:-null}"
+    done
+  } > "$tmp"
+  mv "$tmp" "$file" || { rm -f "$tmp"; die "$COMATE_ENV" "ERROR: failed to replace $file"; }
+
+  local readback; readback=$(yaml_get "$file" "$key")
+  if [ "$readback" != "$value" ]; then
+    die "$COMATE_CORRUPT" "ERROR: gate write-back mismatch for '$key': wrote '$value', read '$readback'"
+  fi
+}