@house365/comate 0.3.0 → 0.5.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

@@ -2,6 +2,7 @@
 import { spawn } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
 
 import { findBash } from './doctor.mjs';
 import {
@@ -11,6 +12,7 @@ import {
   npmInvocation,
   openSpecState,
   run,
+  scaffoldDocs,
   skillsInvocation,
   superpowersInstalled,
 } from './init.mjs';
@@ -49,12 +51,19 @@ export async function init(pkgRoot) {
 
   const target = inspectTarget(cwd, home);
   if (target.kind !== 'project') {
-    console.error(
-      target.kind === 'home'
-        ? '\n这是主目录，请在项目目录下运行 comate init。'
-        : '\n当前目录不像项目（无 .git / package.json 等），请在项目目录下运行 comate init。',
-    );
-    return 1;
+    // Home directory is always refused
+    if (target.kind === 'home') {
+      console.error('\n这是主目录，请在项目目录下运行 comate init。');
+      return 1;
+    }
+
+    // Bare directory: ask user if they want to create a project here
+    console.log('\n当前目录不像项目（无 .git / package.json 等）。');
+    const confirmed = await askConfirm('要在这里初始化新项目吗？');
+    if (!confirmed) {
+      console.log('已取消。');
+      return 1;
+    }
   }
 
   // comate's skills are bash scripts needing associative arrays (bash 4+), and
@@ -147,10 +156,40 @@ 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);
 }
 
+// A yes/no prompt. Defaults to "no" so a piped/non-interactive run (CI, an
+// unattended npx) never silently scaffolds a project into whatever directory it
+// happened to land in — those callers should point at a real project instead.
+// [y/N]: empty input, EOF (Ctrl-D / closed stdin), or anything but y/yes = no.
+export function askConfirm(question, { input = process.stdin, output = process.stdout } = {}) {
+  if (!input.isTTY) return Promise.resolve(false);
+  const rl = createInterface({ input, output });
+  return new Promise((done) => {
+    rl.question(`${question} [y/N] `, (answer) => {
+      rl.close();
+      done(/^\s*y(es)?\s*$/i.test(answer));
+    });
+  });
+}
+
 // The spinner runs in its own process because every step above is a synchronous
 // spawnSync — an interval on this thread would never fire. In a pipe \r does not
 // overwrite, so animating there would leave every frame on screen; print one

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/bin/postinstall.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// Postinstall hook: show the wordmark and next steps after npm install finishes.
+// Skipped in CI (where the logo wouldn't render anyway) and local dev installs
+// (where the developer already knows what they installed).
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+// Skip in CI, or when installing the package's own dependencies during dev.
+if (isCI() || isDevInstall()) {
+  process.exit(0);
+}
+
+const { banner, pkgVersion } = await import('./init-run.mjs');
+
+console.log(banner(pkgVersion(pkgRoot)));
+console.log(`  🎉 Congratulations! comate 已成功安装。\n`);
+console.log('  下一步：');
+console.log('    在你的项目目录下运行  comate init  开始使用');
+console.log('    或运行                comate doctor  健康检查');
+console.log('    更多帮助              comate --help\n');
+
+function isCI() {
+  return Boolean(process.env.CI || process.env.GITHUB_ACTIONS);
+}
+
+// When npm installs a package's own dependencies (npm i in the repo itself),
+// INIT_CWD points to the package root. A user installing comate globally or as
+// a dependency has INIT_CWD pointing elsewhere.
+function isDevInstall() {
+  const initCwd = process.env.INIT_CWD;
+  if (!initCwd) return false;
+  const normalise = (p) => resolve(p).replace(/[\\/]+$/, '').toLowerCase();
+  return normalise(initCwd) === normalise(pkgRoot);
+}

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.5.0",
   "description": "comate —— OpenSpec + Superpowers 规约驱动的 AI 开发编排器（Agent Skills）",
   "type": "module",
   "license": "MIT",
@@ -44,6 +44,7 @@
     "skills": "^1.5.21"
   },
   "scripts": {
+    "postinstall": "node bin/postinstall.mjs",
     "test": "node bin/init.test.mjs && bash skills/comate/tests/run.sh",
     "doctor": "cd skills && bash comate/scripts/comate.sh doctor",
     "prepublish-check": "node scripts/prepublish-check.mjs",

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
+}