@house365/comate 0.9.11 → 0.9.12

package/docs/COMATE_MANUAL.md

@@ -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`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@house365/comate",
-  "version": "0.9.11",
+  "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/scripts/comate.sh

@@ -1398,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"
 }
 

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。
 
 | 字段 | 内容 |
 |------|------|