@house365/comate 0.3.0 → 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.3.0",
+  "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 <描述>` | → **询问**：继续已有还是新建；继续则列出供选择 |
@@ -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/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
+}

package/skills/comate/scripts/comate.sh

@@ -17,6 +17,12 @@
 #   sources <name> check                     — drift check tracked source files
 #   sources <name> list                      — print the source manifest
 #   sources find <file>                      — reverse lookup: changes citing a file
+#   gate    <prd> review                     — create/refresh gate.yaml next to the PRD, pin hash
+#   gate    <prd> set <field> <value>        — write score | blocking_open | gate_status | …
+#   gate    <prd> pass [--tbd]               — mark passed (needs blocking_open=0 + report)
+#   gate    <prd> spawned <change>           — record a change fanned out from this PRD
+#   gate    <prd> status [--json]            — print gate status (computes stale on hash drift)
+#   gate    <prd> check                      — precondition guard before spawning a change
 #   archive <name> [--dry-run]               — sync delta specs + annotate + move + mark archived
 #   status  [path]                           — list active changes + next command
 #   doctor                                   — prerequisite self-check
@@ -66,6 +72,12 @@ Usage: comate.sh <command> ...
   sources <name> check
   sources <name> list
   sources find <file>
+  gate    <prd> review                      create/refresh gate.yaml next to PRD, pin hash
+  gate    <prd> set <field> <value>         score | blocking_open | gate_status | …
+  gate    <prd> pass [--tbd]                mark passed (needs blocking_open=0 + report)
+  gate    <prd> spawned <change>            record a change fanned out from this PRD
+  gate    <prd> status [--json]
+  gate    <prd> check                       precondition guard before spawning a change
   archive <name> [--dry-run]
   status  [path]
   doctor
@@ -1332,6 +1344,184 @@ sources_find() {
   return 0
 }
 
+# =====================================================================
+# gate — phase 0: PRD quality gate + split precondition
+# =====================================================================
+
+# require_prd <prd> — ensure the PRD path is a real, non-empty file; echo it.
+require_prd() {
+  local prd="$1"
+  [ -n "$prd" ] || die "$COMATE_USAGE" "ERROR: PRD path required"
+  case "$prd" in *..*) die "$COMATE_USAGE" "ERROR: PRD path cannot contain '..': $prd" ;; esac
+  [ -f "$prd" ] || die "$COMATE_CORRUPT" "ERROR: PRD not found: $prd"
+  file_nonempty "$prd" || die "$COMATE_CORRUPT" "ERROR: PRD is empty: $prd"
+  echo "$prd"
+}
+
+# gate <prd> review — create or refresh gate.yaml next to the PRD and pin the
+# current PRD hash. Existing passed gates are re-opened to `reviewing` only when
+# the PRD changed (hash drift); otherwise the review report path is (re)emitted
+# so the skill knows where to write its human-readable audit. The skill does the
+# semantic scoring and writes score/blocking_open/gate_status via `gate set`.
+gate_review() {
+  local prd; prd=$(require_prd "$1")
+  local gate report cur_hash
+  gate=$(gate_path_for "$prd")
+  report=$(gate_report_for "$prd")
+  cur_hash=$(hash_file "$prd")
+
+  if [ ! -f "$gate" ]; then
+    cat > "$gate" <<EOF
+# comate PRD gate — flat key:value only, no nesting
+schema_version: $GATE_SCHEMA_VERSION
+prd_path: $prd
+prd_hash: $cur_hash
+gate_status: reviewing
+score: null
+blocking_open: null
+review_report: $report
+spawned_changes: null
+gated_at: null
+created_at: $(today)
+EOF
+    log_pass "[GATE] created $gate (status=reviewing)"
+  else
+    local old_hash old_status
+    old_hash=$(yaml_get "$gate" prd_hash)
+    old_status=$(yaml_get "$gate" gate_status)
+    gate_yaml_set "$gate" prd_path "$prd"
+    gate_yaml_set "$gate" review_report "$report"
+    if [ "$old_hash" != "$cur_hash" ]; then
+      gate_yaml_set "$gate" prd_hash "$cur_hash"
+      gate_yaml_set "$gate" gate_status reviewing
+      log_warn "[GATE] PRD changed since last review — status reset to reviewing (was $old_status)"
+    else
+      log_info "[GATE] $gate (status=$old_status, unchanged PRD)"
+    fi
+  fi
+  echo "review_report: $report"
+}
+
+# gate <prd> set <field> <value> — write a gate field (score/blocking_open/
+# gate_status/…) with the same validation as gate_yaml_set.
+gate_set() {
+  local prd; prd=$(require_prd "$1")
+  local field="${2:-}" value="${3:-}"
+  [ -n "$field" ] || die "$COMATE_USAGE" "Usage: comate.sh gate <prd> set <field> <value>"
+  local gate; gate=$(gate_path_for "$prd")
+  [ -f "$gate" ] || die "$COMATE_CORRUPT" "ERROR: gate not found (run 'gate review' first): $gate"
+  gate_yaml_set "$gate" "$field" "$value"
+  log_pass "[GATE] set $field=$value"
+}
+
+# gate <prd> pass [--tbd] — flip to passed/passed-with-tbd. Hard precondition:
+# blocking_open must be 0 (no open blocking issues). Re-pins prd_hash so a later
+# edit invalidates the pass. --tbd records that the user authorised proceeding
+# with unresolved TBDs (spawned changes must carry ⚠ markers).
+gate_pass() {
+  local prd; prd=$(require_prd "$1")
+  local tbd=0
+  [ "${2:-}" = "--tbd" ] && tbd=1
+  local gate; gate=$(gate_path_for "$prd")
+  [ -f "$gate" ] || die "$COMATE_CORRUPT" "ERROR: gate not found (run 'gate review' first): $gate"
+
+  local blocking; blocking=$(yaml_get "$gate" blocking_open)
+  if [ "$blocking" != "0" ]; then
+    die "$COMATE_BLOCK" "BLOCK: blocking_open='$blocking' — resolve all blocking issues (set blocking_open 0) before passing the gate"
+  fi
+  local report; report=$(yaml_get "$gate" review_report)
+  if [ -z "$report" ] || [ "$report" = "null" ] || ! file_nonempty "$report"; then
+    die "$COMATE_BLOCK" "BLOCK: review report missing or empty ($report) — the gate report is mandatory"
+  fi
+
+  gate_yaml_set "$gate" prd_hash "$(hash_file "$prd")"
+  if [ "$tbd" -eq 1 ]; then
+    gate_yaml_set "$gate" gate_status passed-with-tbd
+  else
+    gate_yaml_set "$gate" gate_status passed
+  fi
+  gate_yaml_set "$gate" gated_at "$(today)"
+  log_pass "[GATE] $(yaml_get "$gate" gate_status) — changes may now be spawned from $prd"
+}
+
+# gate <prd> spawned <change> — append a change name to spawned_changes
+# (comma-joined), recording which changes this PRD fanned out into.
+gate_spawned() {
+  local prd; prd=$(require_prd "$1")
+  local change="${2:-}"
+  validate_change_name "$change"
+  local gate; gate=$(gate_path_for "$prd")
+  [ -f "$gate" ] || die "$COMATE_CORRUPT" "ERROR: gate not found: $gate"
+  local cur; cur=$(yaml_get "$gate" spawned_changes)
+  case ",$cur," in
+    *",$change,"*) log_info "[GATE] $change already recorded" ; return 0 ;;
+  esac
+  if [ -z "$cur" ] || [ "$cur" = "null" ]; then
+    gate_yaml_set "$gate" spawned_changes "$change"
+  else
+    gate_yaml_set "$gate" spawned_changes "$cur,$change"
+  fi
+  log_pass "[GATE] recorded spawned change: $change"
+}
+
+# _gate_is_stale <gate> <prd> — true (0) if the recorded hash no longer matches
+# the PRD on disk.
+_gate_is_stale() {
+  local gate="$1" prd="$2" recorded actual
+  recorded=$(yaml_get "$gate" prd_hash)
+  [ -f "$prd" ] || return 0
+  actual=$(hash_file "$prd")
+  [ "$recorded" != "$actual" ]
+}
+
+# gate <prd> status [--json] — print current gate status, computing stale on the
+# fly (hash drift). Does not mutate the file.
+gate_status() {
+  local prd="$1" json="${2:-}"
+  [ -n "$prd" ] || die "$COMATE_USAGE" "Usage: comate.sh gate <prd> status [--json]"
+  local gate; gate=$(gate_path_for "$prd")
+  if [ ! -f "$gate" ]; then
+    if [ "$json" = "--json" ]; then
+      printf '{"gate":"none","prd":"%s"}\n' "$(json_escape "$prd")"
+    else
+      echo "gate: none ($prd) — run 'gate review' to start"
+    fi
+    return "$COMATE_OK"
+  fi
+  local st score blocking; st=$(yaml_get "$gate" gate_status)
+  score=$(yaml_get "$gate" score); blocking=$(yaml_get "$gate" blocking_open)
+  if [ -f "$prd" ] && _gate_is_stale "$gate" "$prd"; then st="stale"; fi
+  if [ "$json" = "--json" ]; then
+    printf '{"gate":"%s","status":"%s","score":"%s","blocking_open":"%s","report":"%s"}\n' \
+      "$(json_escape "$gate")" "$(json_escape "$st")" "$(json_escape "$score")" \
+      "$(json_escape "$blocking")" "$(json_escape "$(yaml_get "$gate" review_report)")"
+  else
+    echo "gate: $st  score=$score  blocking_open=$blocking  ($gate)"
+  fi
+  return "$COMATE_OK"
+}
+
+# gate <prd> check — the precondition guard comate-open runs before spawning a
+# change. PASS (exit 0) requires: gate.yaml exists, status ∈ {passed,
+# passed-with-tbd}, and prd_hash matches the current PRD. Anything else BLOCKs.
+gate_check() {
+  local prd; prd=$(require_prd "$1")
+  local gate; gate=$(gate_path_for "$prd")
+  if [ ! -f "$gate" ]; then
+    die "$COMATE_BLOCK" "BLOCK: no gate for $prd — run /comate-intake to review the PRD before creating a change"
+  fi
+  local st; st=$(yaml_get "$gate" gate_status)
+  case "$st" in
+    passed|passed-with-tbd) ;;
+    *) die "$COMATE_BLOCK" "BLOCK: gate_status='$st' (not passed) — a change cannot be spawned until the PRD gate passes" ;;
+  esac
+  if _gate_is_stale "$gate" "$prd"; then
+    die "$COMATE_BLOCK" "BLOCK: PRD changed since it passed the gate (hash mismatch) — re-run /comate-intake to re-gate before spawning a change"
+  fi
+  log_pass "[GATE] check PASS ($st) — $prd"
+  return "$COMATE_OK"
+}
+
 # =====================================================================
 # archive
 # =====================================================================
@@ -1678,6 +1868,20 @@ case "$CMD" in
       esac
     fi
     ;;
+  gate)
+    PRD="${1:-}"; SUB="${2:-}"
+    [ -n "$PRD" ] && [ -n "$SUB" ] || { usage_top; exit "$COMATE_USAGE"; }
+    shift 2 || true
+    case "$SUB" in
+      review)  gate_review "$PRD" ;;
+      set)     gate_set "$PRD" "${1:-}" "${2:-}" ;;
+      pass)    gate_pass "$PRD" "${1:-}" ;;
+      spawned) gate_spawned "$PRD" "${1:-}" ;;
+      status)  gate_status "$PRD" "${1:-}" ;;
+      check)   gate_check "$PRD" ;;
+      *) die "$COMATE_USAGE" "Unknown gate subcommand: $SUB" ;;
+    esac
+    ;;
   archive)
     [ -n "${1:-}" ] || { usage_top; exit "$COMATE_USAGE"; }
     archive "$1" "${2:-}"