@house365/comate 0.9.17 → 0.9.19

package/docs/COMATE_INIT_DIRECTORY_GUIDE.md

@@ -0,0 +1,201 @@
+# comate init 目录说明
+
+`comate init` 会同时准备两类内容：用户级 skills，以及当前项目的 OpenSpec 和知识库目录。
+
+## 1. 初始化时会发生什么
+
+在项目根目录运行：
+
+```bash
+comate init
+```
+
+它会：
+
+- 将 comate、OpenSpec 和 Superpowers 相关 skills 安装到用户级 skills 目录。
+- 在当前项目创建 `openspec/`。
+- 在当前项目补齐 `docs/` 知识库骨架。
+- 保留已经存在的文件，不覆盖项目已有内容。
+
+项目目录通常会得到以下结构：
+
+```text
+your-project/
+├── openspec/
+│   ├── config.yaml
+│   ├── changes/
+│   │   └── archive/
+│   └── specs/
+└── docs/
+    ├── README.md
+    ├── architecture/
+    │   └── README.md
+    └── knowledge-base/
+        ├── README.md
+        ├── requirements/
+        │   └── _templates/
+        │       └── PRD.md
+        └── integrations/
+            ├── README.md
+            └── _TEMPLATE/
+                ├── README.md
+                └── api-snapshot.md
+```
+
+## 2. 用户级 skills
+
+默认目录：
+
+```text
+macOS/Linux: ~/.agents/skills/
+Windows:     %USERPROFILE%\.agents\skills\
+```
+
+这里保存可被多个项目共用的 skills。常见目录包括：
+
+| 目录 | 用途 |
+| --- | --- |
+| `comate/` | comate 总入口、状态脚本和共享规则 |
+| `comate-open/` | 创建 change，生成初始产物 |
+| `comate-design/` | 技术设计和方案确认 |
+| `comate-build/` | 计划和代码实现 |
+| `comate-verify/` | 测试、验证和分支收尾 |
+| `comate-archive/` | 归档 change 并同步规格 |
+| `comate-fix/` | Bug 或小调整的快速流程 |
+| `comate-gate/` | PRD 门禁和拆分 |
+| `comate-grill/` | 澄清关键决策 |
+| `comate-kb-integration/` | 生成第三方对接档案 |
+| `openspec-*/` | OpenSpec 提供的配套 skills |
+
+通常不需要手动修改这些目录。升级 comate 后，在项目根目录重新运行 `comate init`，即可同步新版 comate skills。
+
+## 3. 项目级 `openspec/`
+
+`openspec/` 保存当前项目的变更规格，是项目自己的文件，应纳入版本控制。
+
+### `openspec/config.yaml`
+
+OpenSpec 的项目配置文件，记录当前项目使用的规格 schema。通常由初始化命令创建；已有配置会保留，不要随意删除。
+
+### `openspec/changes/`
+
+每个进行中的需求或修复对应一个 change：
+
+```text
+openspec/changes/<change-name>/
+├── .comate.yaml
+├── proposal.md
+├── design.md
+├── tasks.md
+├── specs/<capability>/spec.md
+└── .comate/
+    ├── handoff/
+    └── sources.manifest
+```
+
+这些文件由 `/comate`、`/comate-fix` 及各阶段 skill 逐步生成：
+
+- `.comate.yaml`：comate 当前阶段和验证状态的事实来源。
+- `proposal.md`：为什么做、做什么、范围和非目标。
+- `design.md`：高层设计、方案选择和数据流。
+- `tasks.md`：实施任务清单，完成一项勾选一项。
+- `specs/<capability>/spec.md`：本次变更的增量能力规格。
+- `.comate/handoff/`：阶段之间自动生成的交接上下文。
+- `.comate/sources.manifest`：需求源文件的追踪清单，仅在需求来自文件时出现。
+
+`openspec/changes/archive/` 在初始化时就会创建。`<change-name>` 完成并归档后，会移动到：
+
+```text
+openspec/changes/archive/YYYY-MM-DD-<change-name>/
+```
+
+### `openspec/specs/`
+
+这里保存已经沉淀的长期能力规格：
+
+```text
+openspec/specs/<capability>/spec.md
+```
+
+归档 change 时，增量规格会合并到对应的主规格中。
+
+## 4. 项目级 `docs/`
+
+`docs/` 保存跨多个 change 长期有效的项目文档。初始化只创建骨架，具体内容需要项目团队补充。
+
+### `docs/README.md`
+
+说明 `docs/` 的整体边界，以及架构文档、知识库和 `openspec/` 的分工。一般不需要频繁修改。
+
+### `docs/architecture/`
+
+保存项目架构约束，例如：
+
+- 前后端分层和模块依赖；
+- API、DTO、数据库和错误码约定；
+- 命名、日志、测试和部署规范。
+
+初始化时只有占位说明。项目应根据实际技术栈补充正式规则。涉及架构约束的 PRD，门禁会以这里的内容作为对齐依据。
+
+### `docs/knowledge-base/`
+
+保存需求和第三方服务资料。
+
+#### `requirements/`
+
+存放原始 PRD。推荐按功能和日期组织：
+
+```text
+docs/knowledge-base/requirements/<YYYYMMDD-功能名>/
+├── PRD-001-功能名.md
+├── PRD-001.gate.yaml
+└── PRD-001-REVIEW.md
+```
+
+`_templates/PRD.md` 是新建 PRD 的模板。`.gate.yaml` 和 `-REVIEW.md` 由 `/comate-gate` 生成，不需要手动创建。
+
+#### `integrations/`
+
+保存第三方服务的长期对接档案：
+
+```text
+docs/knowledge-base/integrations/<service-id>/
+├── README.md
+└── api-snapshot.md
+```
+
+`_TEMPLATE/` 只存模板，不代表真实服务。接入新服务时，复制模板或使用 `/comate-kb-integration` 生成档案，并维护 `integrations/README.md` 中的服务索引。
+
+## 5. 后续流程会新增的目录
+
+以下目录不是 `comate init` 必然立即创建的，而是在对应阶段产生：
+
+```text
+docs/superpowers/
+├── specs/   # design 阶段的设计文档
+├── plans/   # build 阶段的实施计划
+└── reports/ # verify 阶段的验证报告
+```
+
+如果项目暂时没有进行中的 change，这些目录不存在是正常的。
+
+## 6. 哪些内容应提交到 Git
+
+建议提交项目级内容：
+
+- `openspec/`
+- `docs/architecture/`
+- `docs/knowledge-base/`
+- 已生成的 `docs/superpowers/`
+
+用户级 `~/.agents/skills/` 或 `%USERPROFILE%\.agents\skills\` 属于本机环境，不放进项目仓库。
+
+## 7. 重跑 init
+
+`comate init` 是幂等的：
+
+- 已安装的依赖和 skills 会跳过或复用；
+- 已存在的 `openspec/` 和 `docs/` 文件会保留；
+- 缺少的目录或模板文件会补齐。
+
+因此升级 comate 后，可以安全地在每个项目根目录重新运行一次 `comate init`。

package/docs/COMATE_MANUAL.md

@@ -595,7 +595,8 @@ bash "$COMATE" doctor
 | `gate <prd> review` | 建/刷新 gate.yaml，钉当前 PRD sha256，回显评审报告路径。PRD 变了则状态重置为 `reviewing` |
 | `gate <prd> set <field> <value>` | 写字段：`score` / `blocking_open` / `gate_status` 等 |
 | `gate <prd> pass [--tbd]` | 校验评分、拆分映射和报告。普通 pass 要求 `blocking_open=0`；`--tbd` 要求至少一个经用户接受的未解决阻断项 |
-| `gate <prd> spawned <change>` | 记录据此 PRD 扇出的 change（逗号拼接） |
+| `gate <prd> spawned <change>` | 校验 change 属于确认映射、gate 未 stale、open 骨架与 PRD 源追踪完整后，记录据此 PRD 扇出的 change（逗号拼接，幂等） |
+| `gate <prd> fanout-status [--json]` | 对比 `changes_map` 与 `spawned_changes`，输出 expected/spawned/complete/missing/invalid，用于多 change 中断恢复与完整性校验 |
 | `gate <prd> status [--json]` | 查状态；哈希漂移时自动判 `stale`（不改文件） |
 | `gate <prd> check` | comate-open 建 change 前的前置守卫。PASS 要求 gate 存在、状态 ∈ {passed, passed-with-tbd}、哈希未漂移；否则退出码 1 阻塞 |
 

package/package.json

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

package/skills/comate/scripts/comate.sh

@@ -21,6 +21,7 @@
 #   gate    <prd> set <field> <value>        — write score | blocking_open | gate_status | …
 #   gate    <prd> pass [--tbd]               — pass clean gate or explicitly accepted TBD blockers
 #   gate    <prd> spawned <change>           — record a change fanned out from this PRD
+#   gate    <prd> fanout-status [--json]     — report mapped/spawned fanout progress
 #   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
@@ -62,6 +63,7 @@ Usage: comate.sh <command> ...
   gate    <prd> set <field> <value>         score | blocking_open | gate_status | …
   gate    <prd> pass [--tbd]                pass: zero blockers; --tbd: accepted blockers
   gate    <prd> spawned <change>            record a change fanned out from this PRD
+  gate    <prd> fanout-status [--json]      report mapped/spawned fanout progress
   gate    <prd> status [--json]
   gate    <prd> check                       precondition guard before spawning a change
   archive <name> [--dry-run]
@@ -1471,10 +1473,52 @@ gate_set() {
   [ -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"
+  if [ "$field" = "changes_map" ]; then
+    gate_validate_changes_map "$value"
+    local current_map current_status
+    current_map=$(yaml_get "$gate" changes_map)
+    current_status=$(yaml_get "$gate" gate_status)
+    case "$current_status" in
+      passed|passed-with-tbd)
+        [ "$value" = "$current_map" ] || \
+          die "$COMATE_BLOCK" "BLOCK: changes_map is immutable after gate pass; re-run gate review before remapping"
+        ;;
+    esac
+  fi
   gate_yaml_set "$gate" "$field" "$value"
   log_pass "[GATE] set $field=$value"
 }
 
+# gate_validate_changes_map <changes_map> — reject malformed entries and
+# duplicate names when the user-confirmed mapping is first persisted.
+gate_validate_changes_map() {
+  local map="$1" rest entry name items seen=""
+  [ -n "$map" ] && [ "$map" != "null" ] || \
+    die "$COMATE_USAGE" "ERROR: changes_map cannot be empty"
+  case "$map" in
+    \;*|*\;\;*|*\;) die "$COMATE_USAGE" "ERROR: changes_map contains an empty entry" ;;
+  esac
+  rest="$map"
+  while [ -n "$rest" ]; do
+    case "$rest" in
+      *\;*) entry="${rest%%;*}"; rest="${rest#*;}" ;;
+      *) entry="$rest"; rest="" ;;
+    esac
+    name="${entry%%:*}"
+    items="${entry#*:}"
+    [ -n "$name" ] && [ "$name" != "$entry" ] || \
+      die "$COMATE_USAGE" "ERROR: malformed changes_map entry '$entry'"
+    [ -n "$(printf '%s' "$items" | tr -d '[:space:]')" ] || \
+      die "$COMATE_USAGE" "ERROR: empty function mapping for change '$name'"
+    validate_change_name "$name"
+    case ",$seen," in
+      *",$name,"*) die "$COMATE_USAGE" "ERROR: duplicate change '$name' in changes_map" ;;
+    esac
+    [ -n "$seen" ] && seen="$seen,"
+    seen="$seen$name"
+  done
+}
+
 # gate <prd> pass [--tbd] — flip to passed/passed-with-tbd. Normal pass requires
 # zero blockers; --tbd requires at least one explicitly accepted blocker.
 gate_pass() {
@@ -1501,6 +1545,7 @@ gate_pass() {
   if [ -z "$changes_map" ] || [ "$changes_map" = "null" ]; then
     die "$COMATE_BLOCK" "BLOCK: changes_map is required before passing the gate"
   fi
+  gate_validate_changes_map "$changes_map"
   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"
@@ -1524,10 +1569,15 @@ gate_spawned() {
   validate_change_name "$change"
   local gate; gate=$(gate_path_for "$prd")
   [ -f "$gate" ] || die "$COMATE_CORRUPT" "ERROR: gate not found: $gate"
+  local changes_map; changes_map=$(yaml_get "$gate" changes_map)
+  gate_change_is_mapped "$changes_map" "$change" || \
+    die "$COMATE_BLOCK" "BLOCK: change '$change' is not present in changes_map"
   local cur; cur=$(yaml_get "$gate" spawned_changes)
   case ",$cur," in
     *",$change,"*) log_info "[GATE] $change already recorded" ; return 0 ;;
   esac
+  gate_check "$prd" >/dev/null
+  gate_require_skeleton "$prd" "$change"
   if [ -z "$cur" ] || [ "$cur" = "null" ]; then
     gate_yaml_set "$gate" spawned_changes "$change"
   else
@@ -1536,6 +1586,118 @@ gate_spawned() {
   log_pass "[GATE] recorded spawned change: $change"
 }
 
+# gate_require_skeleton <prd> <change> — prove that comate-open finished the
+# gate skeleton before it is counted as spawned.
+gate_require_skeleton() {
+  local prd="$1" change="$2" dir yaml manifest tracked_prd f
+  dir=$(comate_change_dir "$change")
+  for f in .openspec.yaml proposal.md design.md tasks.md .comate.yaml; do
+    file_nonempty "$dir/$f" || \
+      die "$COMATE_BLOCK" "BLOCK: change '$change' skeleton incomplete: missing or empty $dir/$f"
+  done
+  yaml="$dir/.comate.yaml"
+  validate_flat_yaml "$yaml"
+  [ "$(yaml_get "$yaml" phase)" = "open" ] || \
+    die "$COMATE_BLOCK" "BLOCK: change '$change' skeleton must remain in phase=open"
+  [ "$(yaml_get "$yaml" source_kind)" = "file" ] || \
+    die "$COMATE_BLOCK" "BLOCK: change '$change' skeleton has not tracked its PRD source"
+  manifest=$(yaml_get "$yaml" source_manifest)
+  [ -n "$manifest" ] && [ "$manifest" != "null" ] && [ -f "$manifest" ] || \
+    die "$COMATE_BLOCK" "BLOCK: change '$change' source manifest is missing"
+  tracked_prd=$(validate_kb_path "$prd") || \
+    die "$COMATE_BLOCK" "BLOCK: PRD source path is outside the knowledge base: $prd"
+  local record_ok=0 line record_path="" record_hash=""
+  while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in
+      path:*) record_path="${line#path:}"; record_hash="" ;;
+      sha256:*)
+        record_hash="${line#sha256:}"
+        if [ "$record_path" = "$tracked_prd" ] && [ -n "$record_hash" ]; then record_ok=1; fi
+        ;;
+      ---|"") record_path=""; record_hash="" ;;
+    esac
+  done < "$manifest"
+  [ "$record_ok" -eq 1 ] || \
+    die "$COMATE_BLOCK" "BLOCK: change '$change' source manifest lacks a complete path/sha256 record for $tracked_prd"
+  local drift rc=0
+  drift=$(sources_drift "$manifest") || rc=$?
+  [ "$rc" -eq 0 ] || die "$COMATE_BLOCK" "BLOCK: change '$change' source evidence is stale: $drift"
+}
+
+# gate_change_names <changes_map> — emit mapped change names, one per line.
+# The persisted format is `name:function item,...;name:function item,...`.
+gate_change_names() {
+  local map="$1" entry name
+  [ -n "$map" ] && [ "$map" != "null" ] || return 0
+  gate_validate_changes_map "$map"
+  while [ -n "$map" ]; do
+    case "$map" in
+      *\;*) entry="${map%%;*}"; map="${map#*;}" ;;
+      *) entry="$map"; map="" ;;
+    esac
+    name="${entry%%:*}"
+    [ -n "$name" ] || die "$COMATE_USAGE" "ERROR: malformed changes_map entry '$entry'"
+    [ "$name" != "$entry" ] || die "$COMATE_USAGE" "ERROR: malformed changes_map entry '$entry'"
+    validate_change_name "$name"
+    printf '%s\n' "$name"
+  done
+}
+
+# gate_change_is_mapped <changes_map> <change> — membership test for a mapped name.
+gate_change_is_mapped() {
+  local map="$1" wanted="$2" name
+  gate_validate_changes_map "$map"
+  while IFS= read -r name; do
+    [ "$name" = "$wanted" ] && return 0
+  done <<EOF
+$(gate_change_names "$map")
+EOF
+  return 1
+}
+
+# gate_fanout_status <prd> [--json] — calculate persisted fanout progress.
+# This is deliberately derived from changes_map and spawned_changes so an
+# interrupted run can resume from the missing names instead of relying on
+# conversation/task state.
+gate_fanout_status() {
+  local prd; prd=$(require_prd "$1")
+  local json="${2:-}" gate; gate=$(gate_path_for "$prd")
+  [ -f "$gate" ] || die "$COMATE_CORRUPT" "ERROR: gate not found: $gate"
+  local map spawned name expected=0 count=0 missing="" invalid=""
+  map=$(yaml_get "$gate" changes_map); spawned=$(yaml_get "$gate" spawned_changes)
+  gate_validate_changes_map "$map"
+  while IFS= read -r name; do
+    [ -n "$name" ] || continue
+    expected=$((expected + 1))
+    case ",$spawned," in
+      *",$name,"*) count=$((count + 1)) ;;
+      *) [ -n "$missing" ] && missing="$missing,"; missing="$missing$name" ;;
+    esac
+  done <<EOF
+$(gate_change_names "$map")
+EOF
+  if [ -n "$spawned" ] && [ "$spawned" != "null" ]; then
+    local rest="$spawned" item
+    while [ -n "$rest" ]; do
+      case "$rest" in
+        *,*) item="${rest%%,*}"; rest="${rest#*,}" ;;
+        *) item="$rest"; rest="" ;;
+      esac
+      gate_change_is_mapped "$map" "$item" || { [ -n "$invalid" ] && invalid="$invalid,"; invalid="$invalid$item"; }
+    done
+  fi
+  local complete=false
+  [ "$expected" -gt 0 ] && [ "$count" -eq "$expected" ] && [ -z "$invalid" ] && complete=true
+  if [ "$json" = "--json" ]; then
+    printf '{"expected":%s,"spawned":%s,"complete":%s,"missing":"%s","invalid":"%s"}\n' \
+      "$expected" "$count" "$complete" "$(json_escape "$missing")" "$(json_escape "$invalid")"
+  else
+    [ -z "$missing" ] && missing=none
+    [ -z "$invalid" ] && invalid=none
+    echo "fanout: expected=$expected spawned=$count complete=$complete missing=$missing invalid=$invalid"
+  fi
+}
+
 # _gate_is_stale <gate> <prd> — true (0) if the recorded hash no longer matches
 # the PRD on disk.
 _gate_is_stale() {
@@ -1956,6 +2118,7 @@ case "$CMD" in
       set)     gate_set "$PRD" "${1:-}" "${2:-}" ;;
       pass)    gate_pass "$PRD" "${1:-}" ;;
       spawned) gate_spawned "$PRD" "${1:-}" ;;
+      fanout-status) gate_fanout_status "$PRD" "${1:-}" ;;
       status)  gate_status "$PRD" "${1:-}" ;;
       check)   gate_check "$PRD" ;;
       *) die "$COMATE_USAGE" "Unknown gate subcommand: $SUB" ;;

package/skills/comate/tests/comate.bats

@@ -565,6 +565,17 @@ seed_prd() {
   echo "docs/knowledge-base/requirements/test/PRD-001-demo.md"
 }
 
+seed_gate_skeleton() {
+  local prd="$1" change="$2" d="openspec/changes/$2"
+  mkdir -p "$d"
+  printf 'schema: specs-driven\n' > "$d/.openspec.yaml"
+  printf '# proposal\n' > "$d/proposal.md"
+  printf '# design\n' > "$d/design.md"
+  printf -- '- [ ] task\n' > "$d/tasks.md"
+  comate state "$change" init full >/dev/null
+  comate sources "$change" track "$prd" >/dev/null
+}
+
 @test "gate review creates gate.yaml next to PRD" {
   local prd; prd=$(seed_prd)
   run comate gate "$prd" review
@@ -643,6 +654,71 @@ seed_prd() {
   [[ "$output" == *"changes_map"* ]]
 }
 
+@test "gate rejects changes_map entries without a function mapping" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  run comate gate "$prd" set changes_map "login-flow"
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"malformed changes_map"* ]]
+}
+
+@test "gate rejects duplicate change names in changes_map" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  run comate gate "$prd" set changes_map "login-flow:功能项1;login-flow:功能项2"
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"duplicate change"* ]]
+}
+
+@test "gate rejects an empty middle entry in changes_map" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  run comate gate "$prd" set changes_map "login-flow:功能项1;;logout-flow:功能项2"
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"empty entry"* ]]
+}
+
+@test "gate rejects a trailing empty entry in changes_map" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  run comate gate "$prd" set changes_map "login-flow:功能项1;"
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"empty entry"* ]]
+}
+
+@test "gate rejects an empty function mapping" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  run comate gate "$prd" set changes_map "login-flow:"
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"empty function mapping"* ]]
+}
+
+@test "gate rejects an all-whitespace function mapping" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  run comate gate "$prd" set changes_map "login-flow:   "
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"empty function mapping"* ]]
+}
+
+@test "gate keeps a passed changes_map immutable except for idempotent writes" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  comate gate "$prd" set changes_map "a:功能项1;b:功能项2;c:功能项3;d:功能项4" >/dev/null
+  printf '# 报告\n' > "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
+  comate gate "$prd" pass >/dev/null
+  run comate gate "$prd" set changes_map "a:功能项1;b:功能项2;c:功能项3;d:功能项4"
+  [ "$status" -eq 0 ]
+  run comate gate "$prd" set changes_map "a:功能项1"
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"immutable after gate pass"* ]]
+  run comate gate "$prd" fanout-status --json
+  [[ "$output" == *'"expected":4'* ]]
+}
+
 @test "gate pass --tbd requires unresolved blockers" {
   local prd; prd=$(seed_prd)
   comate gate "$prd" review >/dev/null
@@ -727,6 +803,7 @@ seed_prd() {
   printf '# 报告\n' > \
     "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
   comate gate "$prd" pass >/dev/null
+  seed_gate_skeleton "$prd" login-flow
   run comate gate "$prd" spawned login-flow
   [ "$status" -eq 0 ]
   local gate="docs/knowledge-base/requirements/test/PRD-001.gate.yaml"
@@ -743,6 +820,8 @@ seed_prd() {
   printf '# 报告\n' > \
     "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
   comate gate "$prd" pass >/dev/null
+  seed_gate_skeleton "$prd" login-flow
+  seed_gate_skeleton "$prd" logout-flow
   comate gate "$prd" spawned login-flow >/dev/null
   comate gate "$prd" spawned logout-flow >/dev/null
   local gate="docs/knowledge-base/requirements/test/PRD-001.gate.yaml"
@@ -751,6 +830,131 @@ seed_prd() {
   [[ "$sc" == *"logout-flow"* ]]
 }
 
+@test "gate spawned remains idempotent after an already recorded change leaves the active directory" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  comate gate "$prd" set changes_map "login-flow:功能项1" >/dev/null
+  printf '# 报告\n' > "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
+  comate gate "$prd" pass >/dev/null
+  seed_gate_skeleton "$prd" login-flow
+  comate gate "$prd" spawned login-flow >/dev/null
+  mkdir -p openspec/changes/archive
+  mv openspec/changes/login-flow openspec/changes/archive/2026-08-28-login-flow
+  run comate gate "$prd" spawned login-flow
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"already recorded"* ]]
+}
+
+@test "gate fanout status reports missing changes instead of treating one of four as complete" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  comate gate "$prd" set changes_map "login-flow:功能项1;logout-flow:功能项2;ops:功能项3;report:功能项4" >/dev/null
+  printf '# 报告\n' > "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
+  comate gate "$prd" pass >/dev/null
+  seed_gate_skeleton "$prd" login-flow
+  comate gate "$prd" spawned login-flow >/dev/null
+  run comate gate "$prd" fanout-status --json
+  [ "$status" -eq 0 ]
+  [[ "$output" == *'"expected":4'* ]]
+  [[ "$output" == *'"spawned":1'* ]]
+  [[ "$output" == *'"complete":false'* ]]
+  [[ "$output" == *'logout-flow'* ]]
+}
+
+@test "gate spawned rejects a change outside the confirmed map" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  comate gate "$prd" set changes_map "login-flow:功能项1" >/dev/null
+  printf '# 报告\n' > "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
+  comate gate "$prd" pass >/dev/null
+  seed_gate_skeleton "$prd" other-flow
+  run comate gate "$prd" spawned other-flow
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"not present in changes_map"* ]]
+}
+
+@test "gate fanout status becomes complete only after every mapped change is spawned" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  comate gate "$prd" set changes_map "login-flow:功能项1;logout-flow:功能项2" >/dev/null
+  printf '# 报告\n' > "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
+  comate gate "$prd" pass >/dev/null
+  seed_gate_skeleton "$prd" login-flow
+  seed_gate_skeleton "$prd" logout-flow
+  comate gate "$prd" spawned login-flow >/dev/null
+  comate gate "$prd" spawned logout-flow >/dev/null
+  run comate gate "$prd" fanout-status
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"complete=true"* ]]
+  [[ "$output" == *"missing=none"* ]]
+}
+
+@test "gate spawned rejects an incomplete change skeleton" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  comate gate "$prd" set changes_map "login-flow:功能项1" >/dev/null
+  printf '# 报告\n' > "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
+  comate gate "$prd" pass >/dev/null
+  mkdir -p openspec/changes/login-flow
+  run comate gate "$prd" spawned login-flow
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"skeleton incomplete"* ]]
+}
+
+@test "gate spawned blocks a new registration after the PRD becomes stale" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  comate gate "$prd" set changes_map "login-flow:功能项1" >/dev/null
+  printf '# 报告\n' > "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
+  comate gate "$prd" pass >/dev/null
+  seed_gate_skeleton "$prd" login-flow
+  printf '\nchanged\n' >> "$prd"
+  run comate gate "$prd" spawned login-flow
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"hash mismatch"* ]]
+}
+
+@test "gate spawned accepts a normalized PRD path recorded in the source manifest" {
+  local prd; prd=$(seed_prd)
+  prd="./$prd"
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  comate gate "$prd" set changes_map "login-flow:功能项1" >/dev/null
+  printf '# 报告\n' > "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
+  comate gate "$prd" pass >/dev/null
+  seed_gate_skeleton "$prd" login-flow
+  run comate gate "$prd" spawned login-flow
+  [ "$status" -eq 0 ]
+}
+
+@test "gate spawned rejects a truncated PRD source record without sha256" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  comate gate "$prd" set changes_map "login-flow:功能项1" >/dev/null
+  printf '# 报告\n' > "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
+  comate gate "$prd" pass >/dev/null
+  seed_gate_skeleton "$prd" login-flow
+  printf 'path:%s\n' "$prd" > openspec/changes/login-flow/.comate/sources.manifest
+  run comate gate "$prd" spawned login-flow
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"complete path/sha256 record"* ]]
+}
+
 @test "gate status returns none when gate does not exist" {
   mkdir -p docs/knowledge-base/requirements/test
   run comate gate "docs/knowledge-base/requirements/test/PRD-001-demo.md" status