@house365/comate 0.9.10 → 0.9.12

package/README.md

@@ -93,13 +93,17 @@ skills/
   comate-fix/                                     预设路径 skill(bug + 小调整)
   comate-grill/                                   决策点穷追式澄清工具
   comate-kb-integration/                          第三方对接档案生成工具(知识库配套)
-docs/
-  COMATE_MANUAL.md   完整操作手册
-```
+docs/
+  COMATE_BEGINNER_GUIDE.md  面向新手的安装与使用手册
+  COMATE_MANUAL.md   完整操作手册
+```
 
 ## 文档
 
-完整说明见 [docs/COMATE_MANUAL.md](docs/COMATE_MANUAL.md):安装前置、命令参考、阶段详解、状态文件字段、决策阻塞点、故障排除。
+文档：
+
+- [入门操作手册](docs/COMATE_BEGINNER_GUIDE.md)：面向第一次使用 comate 的同学，覆盖安装、`init`、目录、PRD、Skill 流程和常见问题。
+- [完整技术手册](docs/COMATE_MANUAL.md)：安装前置、命令参考、阶段详解、状态文件字段、决策阻塞点、故障排除。
 
 ## License
 

package/bin/init-run.mjs

@@ -68,15 +68,13 @@ export async function init(pkgRoot) {
     }
   }
 
-  // comate's skills are bash scripts needing associative arrays (bash 4+), and
-  // macOS ships 3.2. Fail here rather than installing everything and letting the
-  // first /comate call die inside a sourced library.
+  // comate's scripts intentionally support macOS's system Bash 3.2. Fail only
+  // when Bash is older than the syntax the state machine supports.
   const bash = bashVersion();
-  if (bash !== null && bash < 4) {
+  if (bash !== null && bash < 3) {
     console.error(
-      `\ncomate 的脚本需要 bash >= 4，当前 ${bash === 0 ? '未知版本' : `bash ${bash}.x`}。\n` +
-        'macOS 自带 bash 3.2（授权原因），装一个新的：\n\n  brew install bash\n\n' +
-        '装好后重跑 comate init。',
+      `\ncomate 的脚本需要 bash >= 3.2，当前 ${bash === 0 ? '未知版本' : `bash ${bash}.x`}。\n` +
+        '请安装 Bash 3.2 或更高版本后重跑 comate init。',
     );
     return 3;
   }

package/docs/COMATE_BEGINNER_GUIDE.md

@@ -0,0 +1,429 @@
+# comate 入门操作手册
+
+这是一份给第一次使用 comate 的同学看的操作手册。按“安装 → 初始化 → 输入 /comate”的顺序，就可以开始使用。
+
+## 1. comate 是什么
+
+comate 是一个 AI 编程流程编排器。它把一次需求变更拆成几个可以检查的阶段，让 AI 先理解需求和设计，再写代码，最后验证并归档。
+
+完整流程：
+
+```text
+原始 PRD（可选）
+    ↓
+/comate-gate   PRD 门禁和拆分
+    ↓
+/comate-open   开题，创建 change
+    ↓
+/comate-design 深度设计
+    ↓
+/comate-build  计划和编码
+    ↓
+/comate-verify 验证和收尾
+    ↓
+/comate-archive 归档规格
+```
+
+- **OpenSpec** 负责“要做什么”：proposal、spec、tasks 和归档。
+- **Superpowers** 负责“怎么做好”：头脑风暴、技术设计、计划、执行和验证。
+- **comate** 负责识别当前阶段，并把这些能力串起来。
+
+## 2. 安装前准备
+
+### 2.1 必需软件
+
+| 软件 | 建议版本 | 用途 |
+| --- | --- | --- |
+| Node.js | 20 或更高 | 运行 comate 和 npm |
+| npm | 随 Node.js 安装 | 安装 comate、OpenSpec |
+| Git | 任意现代版本 | 管理代码和分支 |
+| Bash | 3.2 或更高 | 执行 comate 的状态机脚本 |
+
+Windows 用户建议安装 [Git for Windows](https://git-scm.com/download/win)，它会提供 Git Bash。PowerShell 可以运行 `comate`，但流程脚本仍需要 Bash。
+
+检查环境：
+
+```bash
+node --version
+npm --version
+git --version
+bash --version
+```
+
+### 2.2 哪些步骤需要网络
+
+首次初始化时，`comate init` 可能需要访问 npm registry 安装 OpenSpec CLI，并访问 GitHub 安装 Superpowers。
+
+comate 自己的 npm 包会随包携带 comate skill。npm 安装钩子只会尽力同步 comate 自身 skill，不会安装 Superpowers，也不会创建项目的 `openspec/` 和 `docs/`；这些由项目目录中的 `comate init` 完成。
+
+## 3. 安装 comate
+
+全局安装：
+
+```bash
+npm install -g @house365/comate
+```
+
+确认命令可用：
+
+```bash
+comate --version
+comate --help
+```
+
+安装后，skill 通常会同步到用户级目录：
+
+- macOS/Linux：`~/.agents/skills/`
+- Windows：`%USERPROFILE%\.agents\skills\`
+
+用户级 skill 可以被多个项目共用。项目自己的规格文件放在项目目录下的 `openspec/`。
+
+## 4. 初始化项目：`comate init`
+
+进入项目根目录再运行：
+
+```bash
+cd path/to/your-project
+comate init
+```
+
+Windows PowerShell 示例：
+
+```powershell
+Set-Location D:\work\my-project
+comate init
+```
+
+请不要在用户主目录直接运行。comate 会检查当前目录是否有 `.git`、`package.json`、`pyproject.toml`、`Cargo.toml` 等项目标记；空目录会先询问是否确认初始化。
+
+### 4.1 `init` 会做什么
+
+1. 检查 Bash 版本。
+2. 检查 OpenSpec，不存在或版本过旧时执行 `npm install -g @fission-ai/openspec@latest`。
+3. 检查 Superpowers，不存在时执行 `skills add obra/superpowers -g -y`。
+4. 把 comate 自身 skill 同步到用户级 skill 目录。
+5. 创建项目级 `openspec/`（已经存在则保留）。
+6. 创建 `docs/` 知识库骨架（只补缺少的文件，不覆盖已有文件）。
+
+某一步失败时，修好网络或环境后重新运行 `comate init` 即可。它是幂等的，已完成的步骤会跳过。
+
+## 5. 初始化后的目录结构
+
+```text
+your-project/
+├─ openspec/
+│  ├─ changes/              # 每次需求变更的工作区
+│  └─ specs/                # 已沉淀的主规格
+├─ docs/
+│  ├─ README.md
+│  ├─ architecture/
+│  │  └─ README.md
+│  └─ knowledge-base/
+│     ├─ README.md
+│     ├─ requirements/
+│     │  └─ _templates/PRD.md
+│     └─ integrations/
+│        ├─ README.md
+│        └─ _TEMPLATE/
+└─ 你的业务代码...
+```
+
+### 5.1 `openspec/`：项目规格
+
+- `changes/<change-name>/`：正在进行的变更，包含 `proposal.md`、`design.md`、`tasks.md`、delta spec 和 `.comate.yaml`。
+- `specs/<capability>/spec.md`：归档后长期维护的能力规格。
+- `changes/archive/`：已经完成并归档的 change。
+
+`.comate.yaml` 是 comate 的状态真相源，记录当前阶段、构建模式、验证结果等。
+
+### 5.2 `docs/`：长期知识库
+
+- `docs/`：项目背景、架构约束、原始 PRD、第三方对接资料。
+- `openspec/`：某次变更的提案、设计、任务、能力规格和归档记录。
+
+### 5.3 用户级 skill 目录
+
+```text
+~/.agents/skills/                  # macOS/Linux
+%USERPROFILE%\.agents\skills\     # Windows
+```
+
+已有的 Superpowers 或其他 skill 不会因为 `comate init` 被覆盖。
+
+## 6. `docs/` 目录详解
+
+### 6.1 `docs/README.md`
+
+说明知识库整体规则、`architecture/` 与 `knowledge-base/` 的边界，以及它们和 `openspec/` 的关系。
+
+### 6.2 `docs/architecture/`
+
+放项目架构约束，例如前后端分层、API/数据库/错误码约定、命名规范和部署约束。`comate init` 只创建占位 README，真正的规则需要项目自己补充。这里是 `/comate-gate` 检查契约时的事实来源。
+
+### 6.3 `docs/knowledge-base/`
+
+放长期维护的需求和外部服务资料：
+
+- `requirements/`：原始 PRD；
+- `integrations/`：第三方服务对接档案；
+- `README.md`：命名、溯源和 PRD 到 change 的流程说明。
+
+### 6.4 `docs/knowledge-base/requirements/`
+
+这里是 PRD 的固定位置。模板位于：
+
+```text
+docs/knowledge-base/requirements/_templates/PRD.md
+```
+
+复制模板到功能目录，填写后运行 `/comate-gate`。
+
+### 6.5 `docs/knowledge-base/integrations/`
+
+每个第三方平台建立一个子目录，例如：
+
+```text
+docs/knowledge-base/integrations/alipay/README.md
+docs/knowledge-base/integrations/alipay/api-snapshot.md
+```
+
+需要从官方文档生成对接档案时，使用 `/comate-kb-integration`。
+
+## 7. PRD 存放位置和命名规范
+
+推荐格式：
+
+```text
+docs/knowledge-base/requirements/<YYYYMMDD-功能名>/PRD-<三位序号>-<功能名>.md
+```
+
+示例：
+
+```text
+docs/knowledge-base/requirements/20260820-用户登录/PRD-001-用户登录.md
+```
+
+规则：
+
+1. 功能目录使用“日期 + 功能名”，日期格式为 `YYYYMMDD`。
+2. PRD 文件以 `PRD-001`、`PRD-002` 这样的三位序号开头。
+3. 文件名中的功能名应和目录功能名保持一致。
+4. 同一个功能目录中的序号不要重复。
+5. 不建议使用 `PRD-1.md` 或把 PRD 放到 `openspec/changes/`。
+
+`/comate-gate` 会在 PRD 同级自动生成：
+
+```text
+PRD-001.gate.yaml       # 机器读取的门禁状态
+PRD-001-REVIEW.md       # 人类可读的评审报告
+```
+
+PRD 通过门禁后如果又被修改，哈希会变化，门禁会变成过期状态，需要重新运行 `/comate-gate`。
+
+## 8. 从需求到代码的 Skill 流程
+
+### 8.1 需求来自一份 PRD
+
+先把 PRD 放到 `docs/knowledge-base/requirements/`，然后直接指定 PRD 路径：
+
+```text
+/comate docs/knowledge-base/requirements/20260820-用户登录/PRD-001-用户登录.md
+```
+
+`/comate` 会识别这是原始 PRD，自动进入 PRD 门禁和拆分流程；不需要先手动调用 `/comate-gate`。门禁通过后，它会继续处理拆分出来的 change。
+
+如果只想单独审阅或重新运行门禁，也可以直接输入：
+
+```text
+/comate-gate docs/knowledge-base/requirements/20260820-用户登录/PRD-001-用户登录.md
+```
+
+对已有 change 继续工作时，输入：
+
+```text
+/comate
+```
+
+comate 会自动从当前阶段继续：`open → design → build → verify → archive`。
+
+### 8.2 需求来自普通对话
+
+不需要先写 PRD，直接输入：
+
+```text
+/comate 我想增加用户登录功能，支持邮箱和密码登录
+```
+
+复杂需求仍建议先整理成 PRD，便于评审和追踪。
+
+### 8.3 Bug 或很小的调整
+
+```text
+/comate-fix 修复登录失败时页面没有提示的问题
+```
+
+它走简化流程：`open → build → verify → archive`，跳过完整 brainstorming。涉及新能力、架构变化、数据库 schema 或多个模块时，应升级回完整 `/comate` 流程。
+
+## 9. Skill 介绍
+
+| Skill | 作用 |
+| --- | --- |
+| `/comate` | 总入口，自动检测当前 change 阶段并分派 |
+| `/comate-gate` | 审阅 PRD、评分、记录阻断问题并拆分 change |
+| `/comate-open` | 探索需求，创建 change 和 proposal/design/tasks 骨架 |
+| `/comate-design` | 技术设计和方案头脑风暴，形成 Design Doc 和 delta spec |
+| `/comate-build` | 制定实施计划、按任务编码并更新 tasks |
+| `/comate-verify` | 运行测试和检查，生成验证报告并处理分支收尾 |
+| `/comate-archive` | 同步 delta spec、标记设计文档并归档 change |
+| `/comate-fix` | Bug 或小调整的快速路径 |
+| `/comate-grill` | 对 PRD、计划或设计中的模糊决策逐个追问 |
+| `/comate-kb-integration` | 根据第三方官方文档生成 integrations 对接档案 |
+
+### 9.1 底层依赖分工
+
+- **OpenSpec**：负责 `openspec/`、change 规格和归档。
+- **Superpowers**：由 `comate init` 通过 `skills` CLI 从 `obra/superpowers` 安装，负责设计、规划、执行和收尾。
+- **comate skill**：本项目提供的编排规则和状态机。
+
+首次使用时，如果 Superpowers 安装失败，design/build/verify 相关流程不能完整运行。先修复网络或手工安装，再重跑 `comate init`。
+
+## 10. 常用命令
+
+### 10.1 安装和检查
+
+```bash
+comate --help
+comate --version
+comate init
+comate doctor
+```
+
+### 10.2 查看 token 用量
+
+```bash
+comate usage
+comate usage daily
+comate usage --global
+comate usage --json
+```
+
+## 11. 配套 UI 查看器
+
+`comate-ui` 是 comate 的本地只读浏览器工作区，用来可视化查看项目中的变更状态、OpenSpec 规格、PRD、Superpowers 设计文档、计划和验证报告。它不会修改项目文件，也不需要数据库。
+
+全局安装：
+
+```bash
+npm install -g @house365/comate-ui@latest
+```
+
+安装后，在包含 `openspec/` 的项目根目录运行：
+
+```bash
+comate-ui
+```
+
+也可以指定项目路径、端口或禁止自动打开浏览器：
+
+```bash
+comate-ui D:\work\my-project
+comate-ui D:\work\my-project --port 4300
+comate-ui --no-open
+```
+
+查看内置示例：
+
+```bash
+comate-ui --demo
+```
+
+查看器只绑定本机 `127.0.0.1`。默认会自动打开浏览器；端口被占用时会自动选择下一个可用端口，按 `Ctrl+C` 停止。
+
+## 12. 更新 comate
+
+```bash
+npm install -g @house365/comate@latest
+cd path/to/your-project
+comate init
+```
+
+npm 更新 CLI 和包内文件；`comate init` 负责把新版 comate skill 同步到用户级目录，并补齐当前项目缺少的 `openspec/`、`docs/` 文件。
+
+更新是幂等的：已有 Superpowers 不覆盖，已有项目规格和 docs 文件不覆盖。若使用 `npm install --ignore-scripts`，请手动执行 `comate init`。
+
+## 13. 网络问题和手工补装
+
+### OpenSpec 安装失败
+
+```bash
+npm install -g @fission-ai/openspec@latest
+openspec --version
+```
+
+### Superpowers 安装失败
+
+```bash
+skills add obra/superpowers -g -y
+```
+
+GitHub 无法访问时，可以配置 npm/Git 代理、使用公司网络或 Git Bash/WSL，安装成功后再运行：
+
+```bash
+comate init
+comate doctor
+```
+
+当前 npm 包没有内置 Superpowers 离线快照；不要把“npm 安装成功”理解成 Superpowers 已安装完成。
+
+## 14. 常见问题
+
+### `comate init` 应该在哪运行？
+
+在业务项目根目录运行，也就是能看到 `.git` 或 `package.json` 的目录。不要在 `C:\Users\你的用户名` 或 `~` 直接运行。
+
+### npm 安装后为什么还要 `comate init`？
+
+npm 只安装 CLI 和包本身。`init` 才会准备 OpenSpec、Superpowers 与 comate skill，并创建当前项目的 `openspec/`、`docs/`。
+
+### 重跑 init 会不会覆盖我的文件？
+
+不会。已有 skill、`openspec/`、docs 文件会保留，只补缺少的内容。
+
+### 找不到 `openspec` 怎么办？
+
+重开终端让全局 npm PATH 生效，然后运行 `openspec --version`。仍找不到就执行 `npm install -g @fission-ai/openspec@latest`，再运行 `comate init`。
+
+### 找不到 Bash 怎么办？
+
+Windows 安装 Git for Windows；macOS 自带的 Bash 3.2 可以直接使用，不需要另外安装 Bash 4+。
+
+### 流程中断了怎么办？
+
+回到同一个项目目录，再输入 `/comate`。comate 会读取 `openspec/changes/<name>/.comate.yaml` 和已有产物，从当前阶段继续。先运行 `comate doctor` 可以排除环境问题。
+
+### 有多个 change 怎么办？
+
+在对话中明确 change 名称。不要同时修改多个 change 的 `tasks.md`。
+
+## 15. 新手最短上手路径
+
+```bash
+npm install -g @house365/comate
+cd your-project
+comate init
+comate doctor
+```
+
+然后在 Claude Code、Codex、Cursor 等支持 Agent Skills 的工具中输入：
+
+```text
+/comate 我想实现一个用户登录功能
+```
+
+等待 AI 在需要你决定的地方提问，确认设计和构建选项后，让流程走到验证和归档。
+
+## 16. 进一步阅读
+
+- [完整技术手册](COMATE_MANUAL.md)：状态字段、门禁规则、脚本接口和故障排查。
+- [项目 README](../README.md)：项目概览和快速安装。
+- 初始化后生成的 `docs/knowledge-base/README.md`：PRD 溯源和命名规则。

package/docs/COMATE_MANUAL.md

@@ -89,7 +89,7 @@ cd your-project && comate init
 
 | 依赖 | 要求 | 检查方式 |
 |------------|-------------|-------|
-| bash | >= 4（需要关联数组） | `bash --version` |
+| bash | >= 3.2 | `bash --version` |
 | git | 任意现代版本 | `git --version` |
 | sha256 | `sha256sum` 或 `shasum`（至少一个） | `command -v sha256sum shasum` |
 | LF 换行符 | 所有 `.sh` 文件必须使用 LF | `bash comate/scripts/comate.sh doctor` |
@@ -137,14 +137,14 @@ docs/
 ├── architecture/README.md                      # 架构规范占位（契约事实源，需项目自建）
 └── knowledge-base/
     ├── README.md                               # PRD → comate 流程说明 + 命名约定
-    ├── requirements/_templates/PRD.md          # PRD 模板（comate 版，无 MRD/FRD 层）
+    ├── requirements/_templates/PRD.md          # PRD 模板
     └── 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。
+- PRD 是需求入口，具体实现约束由 change 的 proposal/design/tasks 承接。
 
 ### 2.6 comate 本身的技能布局
 
@@ -235,7 +235,7 @@ comate usage --json -s 2026-08-01   # 其余参数原样透传给 ccusage
 1. `archived: true` 或变更已在归档中 -> 流程完成
 2. `verify_result: pass` 且 `archived` 不为 `true` -> 调用 `/comate-archive`
 3. `verify_result: fail` -> 验证失败决策阻塞点（决策点 4）
-4. `phase: verify` 或 tasks.md 全部勾选 -> 调用 `/comate-verify`
+4. `phase: verify` -> 调用 `/comate-verify`。`tasks.md` 全部勾选不能单独触发 verify；从 verify-fail 回到 build 后必须按 build 路由继续修复。
 5. `phase: build` 或有设计文档但计划/执行不完整 -> 按工作流路由
 6. `phase: design` 或有变更但无设计文档 -> 调用 `/comate-design`
 7. `phase: open` 或有活动变更但 `.comate.yaml` 缺失 -> 调用 `/comate-open`
@@ -645,7 +645,7 @@ bash comate/scripts/comate.sh status       # 所有活动变更状态
 | 变更目录结构不完整 | 流程中断 | 按 comate-open 产出物要求补全 |
 | `openspec list --json` 失败 | openspec 未安装或未初始化 | 运行 `comate init`，或 `openspec init . --tools none` |
 | 子技能不可用 | Superpowers 未安装 | 运行 `comate init` 补装 |
-| bash 版本过低 | bash < 4（无关联数组） | Windows：Git Bash/WSL；macOS：`brew install bash` |
+| bash 版本过低 | bash < 3.2 | Windows：Git Bash/WSL；macOS 自带 Bash 3.2 可直接使用 |
 | .sh 文件包含 CRLF | git 配置问题 | 仓库有 `.gitattributes` 强制 `eol=lf`；如已损坏，使用 `dos2unix` |
 | 脏工作树无法推进 | 未遵循 dirty-worktree 协议 | 按协议归属，暂停并询问用户 |
 

package/package.json

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

package/skills/comate/SKILL.md

@@ -185,8 +185,8 @@ agent 做决策只需读本节，其余参见末尾「参考附录」。决策
 1. `archived: true` 或 change 已移入 archive → 流程完成
 2. `verify_result: pass` 且 `archived` 非 `true` → 调用 `/comate-archive`
 3. `verify_result: fail` → 验证失败决策阻塞点（决策点 4）
-4. `phase: verify` 或 tasks.md 全勾 → 调用 `/comate-verify`
-5. `phase: build` 或有 Design Doc 但 plan/执行未完成 → 按 workflow 路由：`fix`→`/comate-fix`，`full`→`/comate-build`
+4. `phase: verify` → 调用 `/comate-verify`。`tasks.md` 全勾不能单独触发 verify；验证失败回退到 build 后，必须继续按 build 路由修复。
+5. `phase: build` 或有 Design Doc 但 plan/执行未完成 → 按 workflow 路由：`fix`→`/comate-fix`，`full`→`/comate-build`
 6. `phase: design` 或有 change 但无 Design Doc → 调用 `/comate-design`
 7. `phase: open` 或有活跃 change 但 `.comate.yaml` 缺失 → 调用 `/comate-open`
 8. 无活跃 change → 调用 `/comate-open`

package/skills/comate/reference/prerequisites.md

@@ -10,7 +10,7 @@
 
 | 依赖 | 要求 | 检查 | 缺失处理 |
 |------|------|------|----------|
-| bash | ≥ 4（需要关联数组） | `bash --version` | Windows 用 Git Bash / WSL；macOS 自带 3.2，需 `brew install bash` |
+| bash | ≥ 3.2 | `bash --version` | Windows 用 Git Bash / WSL；macOS 自带 3.2 可直接使用 |
 | git | 任意近代版本 | `git --version` | 安装 git |
 | sha256 工具 | `sha256sum` 或 `shasum` 至少其一 | `command -v sha256sum shasum` | Linux 装 coreutils；macOS 自带 `shasum`（perl） |
 | LF 换行 | 所有 `.sh` 必须是 LF | `doctor` 会检测 CRLF | 仓库已带 `.gitattributes` 强制 `eol=lf`；若被改坏，用 `dos2unix` 或重新 checkout |

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

@@ -80,42 +80,44 @@ FIELD_ORDER=(
 # Current schema version written by `state init`.
 readonly COMATE_SCHEMA_VERSION=1
 
-# --- Enum table: key -> space-separated legal values ---
-declare -A ENUMS=(
-  [schema_version]="1"
-  [workflow]="full fix"
-  [phase]="open design build verify archive"
-  [build_mode]="subagent-driven-development executing-plans direct"
-  [tdd_mode]="tdd direct"
-  [isolation]="branch worktree"
-  [verify_mode]="light full"
-  [verify_result]="pending pass fail"
-  [branch_status]="pending handled discarded"
-  [direct_override]="true false"
-  [archived]="true false"
-  [source_kind]="conversation file"
-)
+# --- Enum tables ---
+# Keep these as case-based lookups instead of associative arrays. macOS ships
+# Bash 3.2, which has normal arrays but not `declare -A`.
+enum_keys() {
+  printf '%s\n' \
+    schema_version workflow phase build_mode tdd_mode isolation verify_mode \
+    verify_result branch_status direct_override archived source_kind
+}
+
+enum_values() {
+  case "$1" in
+    schema_version)  printf '%s\n' '1' ;;
+    workflow)        printf '%s\n' 'full fix' ;;
+    phase)           printf '%s\n' 'open design build verify archive' ;;
+    build_mode)      printf '%s\n' 'subagent-driven-development executing-plans direct' ;;
+    tdd_mode)        printf '%s\n' 'tdd direct' ;;
+    isolation)       printf '%s\n' 'branch worktree' ;;
+    verify_mode)     printf '%s\n' 'light full' ;;
+    verify_result)   printf '%s\n' 'pending pass fail' ;;
+    branch_status)   printf '%s\n' 'pending handled discarded' ;;
+    direct_override) printf '%s\n' 'true false' ;;
+    archived)        printf '%s\n' 'true false' ;;
+    source_kind)     printf '%s\n' 'conversation file' ;;
+    *) return 1 ;;
+  esac
+}
 
 # Keys whose values are free-form (paths, dates, commands, hashes, refs).
-# Listed so validate_change/validate can flag genuinely unknown keys.
-declare -A FREEFORM_KEYS=(
-  [design_doc]=1
-  [plan]=1
-  [verification_report]=1
-  [handoff_context]=1
-  [handoff_hash]=1
-  [impl_context]=1
-  [impl_hash]=1
-  [base_ref]=1
-  [base_branch]=1
-  [source_manifest]=1
-  [build_command]=1
-  [verify_command]=1
-  [created_at]=1
-  [verified_at]=1
-  [phase_step]=1
-  [phase_step_data]=1
-)
+# Listed as a case lookup so unknown fields can still be rejected on Bash 3.2.
+is_freeform_key() {
+  case "$1" in
+    design_doc|plan|verification_report|handoff_context|handoff_hash|\
+    impl_context|impl_hash|base_ref|base_branch|source_manifest|\
+    build_command|verify_command|created_at|verified_at|phase_step|phase_step_data)
+      return 0 ;;
+    *) return 1 ;;
+  esac
+}
 
 # --- Path location ---
 
@@ -157,7 +159,8 @@ validate_change_name() {
 # Free-form keys and unlisted keys pass through. null/empty always allowed.
 validate_enum() {
   local key="$1" value="$2"
-  local legal="${ENUMS[$key]:-}"
+  local legal
+  legal=$(enum_values "$key" 2>/dev/null) || legal=""
   [ -z "$legal" ] && return 0
   [ -z "$value" ] && return 0
   [ "$value" = "null" ] && return 0
@@ -216,18 +219,6 @@ yaml_keys() {
   grep -E '^[A-Za-z0-9_-]+:' "$file" 2>/dev/null | sed 's/:.*//' || true
 }
 
-# _yaml_read_all <file> <assoc-array-name> — load every known field into the
-# named associative array, defaulting missing fields to "null".
-_yaml_read_all() {
-  local file="$1" arrname="$2" k
-  for k in "${FIELD_ORDER[@]}"; do
-    local v
-    v=$(yaml_get "$file" "$k")
-    [ -z "$v" ] && v="null"
-    printf -v "${arrname}[$k]" '%s' "$v"
-  done
-}
-
 # validate_flat_yaml <file> — enforce that .comate.yaml is the
 # declared subset: top-level `key: value` scalars plus `#` comments only.
 # Reject indented lines, list items, block/flow collections. die(CORRUPT) on violation.
@@ -278,22 +269,25 @@ yaml_set() {
   [ -f "$file" ] || die "$COMATE_CORRUPT" "ERROR: state file not found: $file"
 
   # Reject keys we do not know about (prevents silent typo fields).
-  if [ -z "${ENUMS[$key]:-}" ] && [ -z "${FREEFORM_KEYS[$key]:-}" ] && [ "$key" != "schema_version" ]; then
+  if ! enum_values "$key" >/dev/null 2>&1 && ! is_freeform_key "$key" && [ "$key" != "schema_version" ]; then
     die "$COMATE_USAGE" "ERROR: unknown field '$key'"
   fi
   validate_enum "$key" "$value"
 
-  declare -A _cur
-  _yaml_read_all "$file" _cur
-  _cur[$key]="$value"
-
   local tmp
   tmp=$(mktemp "${TMPDIR:-/tmp}/comate.XXXXXX") || die "$COMATE_ENV" "ERROR: mktemp failed"
   {
     printf '# comate state — flat key:value only, no nesting\n'
     local k
     for k in "${FIELD_ORDER[@]}"; do
-      printf '%s: %s\n' "$k" "${_cur[$k]:-null}"
+      local current
+      if [ "$k" = "$key" ]; then
+        current="$value"
+      else
+        current=$(yaml_get "$file" "$k")
+      fi
+      [ -z "$current" ] && current="null"
+      printf '%s: %s\n' "$k" "$current"
     done
   } > "$tmp"
 
@@ -460,10 +454,13 @@ GATE_FIELD_ORDER=(
 
 # 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_enum_values() {
+  case "$1" in
+    schema_version) printf '%s\n' '1' ;;
+    gate_status)    printf '%s\n' 'reviewing blocked passed passed-with-tbd stale' ;;
+    *) return 1 ;;
+  esac
+}
 
 # gate_stem_for <prd> — derive the short stem used to name a PRD's gate.yaml
 # and review report. A conforming PRD file is `PRD-<NNN>-<title>.md`, whose
@@ -472,12 +469,15 @@ declare -A GATE_ENUMS=(
 # names (no PRD-NNN prefix) fall back to the full basename so callers still get
 # a stable, collision-free stem instead of an error.
 gate_stem_for() {
-  local base
+  local base stem
   base=$(basename "$1")
   base="${base%.markdown}"
   base="${base%.md}"
-  if [[ "$base" =~ ^([Pp][Rr][Dd]-[0-9]+) ]]; then
-    echo "${BASH_REMATCH[1]}"
+  # Avoid a capture group in `[[ =~ ]]`: the old parser in macOS Bash 3.2
+  # treats an unquoted `(` as syntax before the conditional can run.
+  stem=$(printf '%s\n' "$base" | sed -n 's/^\([Pp][Rr][Dd]-[0-9][0-9]*\).*/\1/p')
+  if [ -n "$stem" ]; then
+    echo "$stem"
   else
     echo "$base"
   fi
@@ -514,27 +514,27 @@ gate_yaml_set() {
   done
   [ "$known" -eq 1 ] || die "$COMATE_USAGE" "ERROR: unknown gate field '$key'"
 
-  local legal="${GATE_ENUMS[$key]:-}"
+  local legal
+  legal=$(gate_enum_values "$key" 2>/dev/null) || legal=""
   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}"
+      local current
+      if [ "$k" = "$key" ]; then
+        current="$value"
+      else
+        current=$(yaml_get "$file" "$k")
+      fi
+      [ -z "$current" ] && current="null"
+      printf '%s: %s\n' "$k" "$current"
     done
   } > "$tmp"
   mv "$tmp" "$file" || { rm -f "$tmp"; die "$COMATE_ENV" "ERROR: failed to replace $file"; }

package/skills/comate/scripts/comate.sh

@@ -31,23 +31,8 @@
 
 set -euo pipefail
 
-# Must come before sourcing the lib. comate-lib.sh declares associative arrays
-# at load time, which bash 3.2 (what macOS ships as /bin/bash) parses as an
-# ordinary array assignment — the subscript is then evaluated as arithmetic and
-# `set -u` aborts with "schema_version: unbound variable". doctor has its own
-# bash>=4 check, but it never got to run: the source above it already died.
-if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
-  cat >&2 <<EOF
-comate needs bash >= 4 (associative arrays), found ${BASH_VERSION:-unknown}.
-
-macOS ships bash 3.2 for licensing reasons. Install a current one:
-  brew install bash
-
-Then re-run through it, e.g.:
-  $(command -v brew >/dev/null 2>&1 && echo "\$(brew --prefix)/bin/bash" || echo /opt/homebrew/bin/bash) $0 $*
-EOF
-  exit 3
-fi
+# The scripts intentionally stay compatible with macOS's system Bash 3.2.
+# Do not add Bash 4-only features (notably associative arrays) here.
 
 SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")")" && pwd)"
 # shellcheck source=comate-lib.sh
@@ -356,11 +341,11 @@ state_validate() {
 
   # Enum validity (null/empty allowed by validate_enum, but it dies on bad — so check inline).
   local key legal v ok w
-  for key in "${!ENUMS[@]}"; do
+  for key in $(enum_keys); do
     v=$(yaml_get "$yaml" "$key")
     [ -z "$v" ] && continue
     [ "$v" = "null" ] && continue
-    legal="${ENUMS[$key]}"
+    legal=$(enum_values "$key")
     ok=0
     for w in $legal; do
       if [ "$v" = "$w" ]; then ok=1; break; fi
@@ -1413,13 +1398,23 @@ dependency_archived() {
 # 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 <prd> — ensure the PRD path is real, non-empty, and conventionally named.
+validate_prd_filename() {
+  local prd="$1" base
+  base=$(basename "$prd")
+  case "$base" in
+    PRD-[0-9][0-9][0-9]-?*.md) return 0 ;;
+    *) die "$COMATE_USAGE" "ERROR: PRD filename must match PRD-NNN-title.md: $base" ;;
+  esac
+}
+
 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"
+  validate_prd_filename "$prd"
   echo "$prd"
 }
 
@@ -1825,11 +1820,11 @@ doctor() {
 
   log_info "comate doctor"
 
-  # bash version >= 4 (need associative arrays).
-  if [ "${BASH_VERSINFO[0]:-0}" -ge 4 ]; then
-    _d_pass "bash ${BASH_VERSION} (>= 4)"
+  # The state machine is written for Bash 3.2-compatible syntax.
+  if [ "${BASH_VERSINFO[0]:-0}" -ge 3 ]; then
+    _d_pass "bash ${BASH_VERSION} (>= 3)"
   else
-    _d_fail "bash ${BASH_VERSION:-unknown} — comate needs bash >= 4 (associative arrays)"
+    _d_fail "bash ${BASH_VERSION:-unknown} — comate needs bash >= 3"
   fi
 
   # git.

package/skills/comate/tests/comate.bats

@@ -237,6 +237,18 @@ seed_open() {
   [ "$(comate state demo get verification_report)" = "null" ]
 }
 
+@test "verify-fail keeps build authoritative when tasks remain checked" {
+  comate state demo init full
+  printf '%s\n' '# Tasks' '- [x] already implemented' > openspec/changes/demo/tasks.md
+  comate state demo set phase verify >/dev/null
+  comate state demo set verify_result fail >/dev/null
+  comate state demo transition verify-fail
+  [ "$(comate state demo get phase)" = "build" ]
+  [ "$(comate state demo get verify_result)" = "pending" ]
+  # The router must use the persisted phase; task completion is not a phase.
+  [ "$(comate state demo get phase)" != "verify" ]
+}
+
 @test "recover reports phase-local progress" {
   comate state demo init full
   comate state demo set phase_step open.review-awaiting >/dev/null
@@ -346,8 +358,8 @@ SH
   local d="openspec/changes/demo"
   printf '# p\n' > "$d/proposal.md"; printf '# d\n' > "$d/design.md"; printf -- '- [x] t1\n' > "$d/tasks.md"
   mkdir -p docs/knowledge-base/cb bin
-  printf '# frd\n' > docs/knowledge-base/cb/frd.md
-  comate sources demo track docs/knowledge-base/cb/frd.md >/dev/null 2>&1
+  printf '# source\n' > docs/knowledge-base/cb/source.md
+  comate sources demo track docs/knowledge-base/cb/source.md >/dev/null 2>&1
   cat > bin/openspec <<'SH'
 #!/bin/bash
 set -e
@@ -427,13 +439,13 @@ SH
 @test "sources track records kb file and flips source_kind to file" {
   comate state demo init full
   mkdir -p docs/knowledge-base/cb
-  printf '# frd\n' > docs/knowledge-base/cb/frd.md
-  run comate sources demo track docs/knowledge-base/cb/frd.md --note "main entry"
+  printf '# source\n' > docs/knowledge-base/cb/source.md
+  run comate sources demo track docs/knowledge-base/cb/source.md --note "main entry"
   [ "$status" -eq 0 ]
   [ "$(comate state demo get source_kind)" = "file" ]
   [ "$(comate state demo get source_manifest)" = "openspec/changes/demo/.comate/sources.manifest" ]
   run comate sources demo list
-  [[ "$output" == *"path:docs/knowledge-base/cb/frd.md"* ]]
+  [[ "$output" == *"path:docs/knowledge-base/cb/source.md"* ]]
   [[ "$output" == *"note:main entry"* ]]
 }
 
@@ -448,9 +460,9 @@ SH
 @test "sources check detects drift after file edited" {
   comate state demo init full
   mkdir -p docs/knowledge-base/cb
-  printf '# frd\n' > docs/knowledge-base/cb/frd.md
-  comate sources demo track docs/knowledge-base/cb/frd.md >/dev/null 2>&1
-  printf 'edited\n' >> docs/knowledge-base/cb/frd.md
+  printf '# source\n' > docs/knowledge-base/cb/source.md
+  comate sources demo track docs/knowledge-base/cb/source.md >/dev/null 2>&1
+  printf 'edited\n' >> docs/knowledge-base/cb/source.md
   run comate sources demo check
   [ "$status" -eq 1 ]
   [[ "$output" == *"drifted"* ]]
@@ -459,9 +471,9 @@ SH
 @test "sources find reverse-looks-up a tracked file" {
   comate state demo init full
   mkdir -p docs/knowledge-base/cb
-  printf '# frd\n' > docs/knowledge-base/cb/frd.md
-  comate sources demo track docs/knowledge-base/cb/frd.md >/dev/null 2>&1
-  run comate sources find docs/knowledge-base/cb/frd.md
+  printf '# source\n' > docs/knowledge-base/cb/source.md
+  comate sources demo track docs/knowledge-base/cb/source.md >/dev/null 2>&1
+  run comate sources find docs/knowledge-base/cb/source.md
   [ "$status" -eq 0 ]
   [[ "$output" == *"demo"* ]]
 }
@@ -471,11 +483,11 @@ SH
   local d="openspec/changes/demo"
   printf '# p\n' > "$d/proposal.md"; printf '# d\n' > "$d/design.md"; printf -- '- [x] t1\n' > "$d/tasks.md"
   mkdir -p docs/knowledge-base/cb
-  printf '# frd\n' > docs/knowledge-base/cb/frd.md
-  comate sources demo track docs/knowledge-base/cb/frd.md >/dev/null 2>&1
+  printf '# source\n' > docs/knowledge-base/cb/source.md
+  comate sources demo track docs/knowledge-base/cb/source.md >/dev/null 2>&1
   comate guard demo open --apply >/dev/null 2>&1
   comate handoff demo build --write >/dev/null 2>&1
-  printf 'edited\n' >> docs/knowledge-base/cb/frd.md
+  printf 'edited\n' >> docs/knowledge-base/cb/source.md
   run comate guard demo build --json
   [ "$status" -eq 1 ]
   [[ "$output" == *'"block":true'* ]]
@@ -521,6 +533,14 @@ seed_prd() {
   [ -f "docs/knowledge-base/requirements/test/PRD-001.gate.yaml" ]
 }
 
+@test "gate rejects PRD filenames outside the naming convention" {
+  mkdir -p docs/knowledge-base/requirements/test
+  printf '# PRD\n' > docs/knowledge-base/requirements/test/PRD-1.md
+  run comate gate docs/knowledge-base/requirements/test/PRD-1.md review
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"PRD-NNN-title.md"* ]]
+}
+
 @test "gate names key off PRD-NNN stem, dropping title" {
   local prd; prd=$(seed_prd)
   run comate gate "$prd" review

package/skills/comate-gate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: comate-gate
-description: "comate 阶段 0：PRD 门禁与拆分。用 /comate-gate 调用。对原始 PRD 做质量审阅+评分+阻断闸门，通过后按依赖/独立性判定拆成 1 或 N 个 change，逐个交给 comate-open。门禁状态钉在 PRD 同级 <PRD>.gate.yaml，门禁未通过禁止建 change。"
+description: "comate 阶段 0：PRD 门禁与拆分。用 /comate-gate 调用。对原始 PRD 做质量审阅+评分+阻断闸门，通过后按依赖/独立性判定拆成 1 或 N 个 change，逐个交给 comate-open。门禁状态钉在 PRD 同级 gate 文件，门禁未通过禁止建 change。"
 ---
 
 # comate 阶段 0：PRD 门禁与拆分（Gate）
@@ -11,13 +11,11 @@ description: "comate 阶段 0：PRD 门禁与拆分。用 /comate-gate 调用。
 1. **门禁**：审阅 PRD 质量、百分制评分、建阻断台账。阻断问题未清零，**禁止建任何 change**。
 2. **拆分**：按依赖/整体性/独立性/规模判定该 PRD 变成几个 change，粒度由用户拍板（AI 只给建议）。
 
-**FRD 层已消解**：不再产独立 FRD 文档。PRD 直接作为 change 的源文档被 `sources track` 钉住，其内容顺着 open→design 流进 comate 原生产物（proposal / design / tasks）。
-
----
+---
 
 ## 核心铁律
 
-- **门禁状态是可验证的文件真相源**：钉在 PRD 同级 `<PRD-NNN>.gate.yaml`（如 `PRD-001.gate.yaml`）。评审报告 `<PRD-NNN>-REVIEW.md`（如 `PRD-001-REVIEW.md`）是给人看的派生物，**不是**状态源。
+- **门禁状态是可验证的文件真相源**：钉在 PRD 同级的 gate 文件。评审报告是给人看的派生物，**不是**状态源。PRD 命名按本 skill 的前置规范执行，派生文件名由脚本确定性生成。
 - **AskUserQuestion 是真阻塞点**：文字提示、推荐方案、默认值、历史偏好、用户未反对，都**不能**替代明确回答。
 - **只审不改**：门禁只暴露 PRD 问题，不替 PRD 补内容、不替产品拍板。
 - **门禁未通过禁止建 change**：`gate_status ∈ {passed, passed-with-tbd}` 且 PRD 哈希未漂移，才允许 comate-open 建 change（由 `gate check` 硬强制）。
@@ -55,34 +53,25 @@ bash "$COMATE" gate <prd> check                # comate-open 建 change 前的
 ### 1. 定位 PRD
 
 - 用户给了路径/编号 → 直接读该文件。
-- 未给 → 用 Glob 列出候选（默认约定 `docs/knowledge-base/requirements/**/PRD-*.md`，若项目无此结构，探测 `docs/**/*.md` 中文件名含 `PRD`/`需求` 的），按命中数分类（对齐 `comate/reference/decision-points.md` 首节三类框架）：
+- 未给 → 用 Glob 列出候选（默认搜索 `docs/knowledge-base/requirements/**/*.md`，若项目无此结构再探测 `docs/**/*.md`），按命中数分类（对齐 `comate/reference/decision-points.md` 首节三类框架）：
   - **恰好 1 个候选** → 无 ≥2 有效选项，属"自动处理"：直接选中该 PRD 并**报告选了哪份**，不 AskUserQuestion。
   - **多个候选** → 属"用户决策"：用 **AskUserQuestion** 让用户选一个。
   - **0 个候选** → 属"停止条件"：报告在约定路径下未找到 PRD，请用户提供路径或确认 PRD 位置，不发明选项。
-- 读取后重点提取：**功能清单**（各功能项 + 优先级 P0/P1/P2）、**范围（In/Out）**、**第三方依赖**、**验收标准**、文档状态。
-- 若 PRD 明显未定稿（状态字段非「已定稿」等），用 **AskUserQuestion** 提示可能未冻结并暂停确认；确认前只审阅，不建 gate。
-
-### 1.5 命名规范化（前置，定位到 PRD 即检测）
-
-用户一旦指到 `docs/knowledge-base/requirements/` 下的文件，**先检测命名是否规范，再进门禁**——因为 gate.yaml 与评审报告的名字都从 PRD 的 `PRD-<NNN>` 前缀派生，名字不规范会连带派生错。comate 只有 PRD 一层（无 MRD/FRD、无固定负责人），只查这三样：
-
-| 对象 | 规范 | 反例 → 规范名 |
-|------|------|--------------|
-| 功能目录 | `<YYYYMMDD-功能名>/` | `图片素材管理/` → `20260614-图片素材管理/` |
-| PRD 文件 | 目录内 `PRD-<三位序号>-<功能名>.md`（序号紧跟类型在前） | `图片素材管理_PRD_V1.md` → `PRD-001-图片素材管理.md`；`PRD-1.md` → `PRD-001-图片素材管理.md` |
-| 派生文件 | `PRD-<NNN>.gate.yaml`、`PRD-<NNN>-REVIEW.md`（脚本自动按 PRD-NNN 前缀生成，无需手动命名） | 旧式 `PRD-001-图片素材管理.gate.yaml`、`PRD-REVIEW-PRD-001-图片素材管理.md` → 迁移到新名 |
-
-**检测到不规范时**（顺序很重要，避免断链）：
-
-1. 先 **Grep** 全仓搜旧文件名/旧路径的所有引用（正文、其它文档、`.comate.yaml` 的 `source_manifest`、gate.yaml 的 `prd_path`/`review_report`）。
-2. 用 **AskUserQuestion** 给出「旧名 → 建议新名」让用户确认（改名影响引用，不自作主张；功能名/日期推断不出时一并问）。
-3. 确认后 **`git mv`** 改名（目录、PRD 文件；已存在的旧 gate.yaml/报告一并 `git mv` 到新名），保留 git 历史，**不要** Write 新文件+删旧。
-4. **Edit** 把第 1 步搜到的引用全部改成新名/新路径。
-5. 再 **Grep** 一次旧名确认零残留。
-
-已规范或用户确认改名后，才进第 2 步门禁——此时 `gate review` 生成的 gate.yaml/报告自然是新名。若 PRD 名已规范，本步无操作，直接进门禁。
-
-### 2. 门禁：质量审阅 + 评分（不可跳过）
+- 读取后重点提取：**功能清单**（各功能项 + 优先级 P0/P1/P2）、**范围（In/Out）**、**第三方依赖**、**验收标准**、文档状态。检查内容是否可审阅即可，不要求 Markdown 标题、表格或模板字段完全一致。
+- 若 PRD 明显未定稿（状态字段非「已定稿」等），用 **AskUserQuestion** 提示可能未冻结并暂停确认；确认前只审阅，不建 gate。
+
+### 1.5 命名规范化（必要前置检查）
+
+PRD 的路径和文件名需要稳定、可追踪，以便 gate 状态和评审报告确定性派生。进入门禁前检查：
+
+| 对象 | 规范 |
+|------|------|
+| 功能目录 | `<YYYYMMDD-功能名>/` |
+| PRD 文件 | 目录内 `PRD-<三位序号>-<功能名>.md` |
+
+发现不规范时，先列出旧名和建议新名，等待用户确认后再用 `git mv` 改名，并同步修正引用。命名规范是流程前置条件；PRD 的正文格式不要求完全套用模板，只需能被审阅并包含可判断的需求内容。
+
+### 2. 门禁：质量审阅 + 评分（不可跳过）
 
 先初始化 gate（钉当前 PRD 哈希、拿到报告路径）：
 
@@ -111,7 +100,7 @@ bash "$COMATE" gate <prd> review
 - **仓库事实**（已有架构约定、字段、接口、对接档案）：先用 Read/Glob/rg 核实并引用来源，不丢给用户决定。
 - **产品决策**（范围、优先级、用户可见行为、状态流转、权限、数据口径、失败处理、验收规则）：必须用 **AskUserQuestion** 问用户，不得用推荐方案/历史偏好/「待确认」代替确认。
 
-**写评审报告（必生成）** 到 `gate review` 回显的 `review_report` 路径（PRD 同级 `<PRD-NNN>-REVIEW.md`，如 `PRD-001-REVIEW.md`）。内容含：评分 + 评级 + 一句话总评、问题台账表（`ID` / 维度 / 严重程度 / 原文依据 / 影响章节 / 是否阻断 / 建议 / 产品回填列）、逐条问题。若无问题，明确写「审阅通过，未发现阻断项」。
+**写评审报告（必生成）** 到 `gate review` 回显的 `review_report` 路径（与 PRD 同级，由脚本确定性命名）。内容含：评分 + 评级 + 一句话总评、问题台账表（`ID` / 维度 / 严重程度 / 原文依据 / 影响章节 / 是否阻断 / 建议 / 产品回填列）、逐条问题。若无问题，明确写「审阅通过，未发现阻断项」。
 
 **阻断规则**：影响范围、用户行为、状态流转、数据契约、权限、异常处理或验收标准的问题标「阻断」。把当前未关闭的阻断问题数写入 gate：
 

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

@@ -26,14 +26,13 @@ comate 采用**简化需求流**:只保留 **PRD**(产品需求文档),通过 `/
 
 PRD 门禁状态钉在同级 `PRD-<三位序号>.gate.yaml`(机器真相源,含 `gate_status` / `score` / `blocking_open` / `prd_hash` / `spawned_changes`)。评审报告为 `PRD-<三位序号>-REVIEW.md`(人类可读,含问题台账)。PRD 通过门禁后被改会因哈希漂移自动失效(`stale`),需重跑 gate。
 
-扇出的 comate change 内部用 proposal / design / tasks 承接 PRD 的功能项内容——**不再产独立 FRD 文档**,PRD 直接作为 change 的源文档被 `sources track` 钉住。
+扇出的 comate change 内部用 proposal / design / tasks 承接 PRD 的功能项内容，PRD 直接作为 change 的源文档被 `sources track` 钉住。
 
-## 命名约定
-
-- 功能目录: `<YYYYMMDD-功能名>/`,日期为该功能需求起始日,功能名用中文短名,如 `20260805-积分商城/`
-- PRD: 目录内 `PRD-<三位序号>-<功能名>.md`,功能名用目录功能名,如 `PRD-001-积分商城.md`
-- gate: 自动生成,`PRD-<三位序号>.gate.yaml`(去 title,只用 PRD-NNN),与 PRD 同级,如 `PRD-001.gate.yaml`
-- 评审报告: 自动生成,`PRD-<三位序号>-REVIEW.md`,与 PRD 同级,如 `PRD-001-REVIEW.md`
+## 命名约定
+
+- 功能目录：`<YYYYMMDD-功能名>/`
+- PRD：目录内 `PRD-<三位序号>-<功能名>.md`
+- gate 和评审报告：由脚本根据 PRD 路径自动生成，不手工命名。
 
 ## 横向 (integrations/)
 

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

@@ -1,7 +1,7 @@
 # PRD-<序号>-<功能名>: <产品标题>
 
-> 复制本文件到对应功能目录 `requirements/<YYYYMMDD-功能名>/`,按命名约定重命名(如 `PRD-001-积分商城.md`,功能名用目录功能名),删除本行与所有 `<...>` 占位说明。
-> PRD = 产品需求文档,回答「做成什么样」。**本 PRD 由 `/comate-gate` 直接读取**:先过质量门禁(审阅+评分+阻断),通过后按依赖/独立性拆成 1 或 N 个 comate change,由 comate 实现——无需再写 FRD。
+> 复制本文件到需求目录，按项目约定命名，删除本行与所有 `<...>` 占位说明。
+> PRD = 产品需求文档，回答「做成什么样」。本 PRD 由 `/comate-gate` 直接读取：先过质量门禁（审阅、评分、阻断检查），通过后按依赖和独立性拆成 1 或 N 个 comate change。
 
 | 字段 | 内容 |
 |------|------|