@house365/comate 0.9.10 → 0.9.11

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` |
@@ -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.11",
   "description": "comate —— SDD (规约驱动开发) 的 AI 开发编排器（Agent Skills）",
   "type": "module",
   "license": "MIT",

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
@@ -1825,11 +1810,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.