@house365/comate 0.9.4 → 0.9.6

package/skills/comate/scripts/comate.sh

@@ -19,7 +19,7 @@
 #   sources find <file>                      — reverse lookup: changes citing a file
 #   gate    <prd> review                     — create/refresh gate.yaml next to the PRD, pin hash
 #   gate    <prd> set <field> <value>        — write score | blocking_open | gate_status | …
-#   gate    <prd> pass [--tbd]               — mark passed (needs blocking_open=0 + report)
+#   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> status [--json]            — print gate status (computes stale on hash drift)
 #   gate    <prd> check                      — precondition guard before spawning a change
@@ -60,7 +60,7 @@ Usage: comate.sh <command> ...
   state   <name> init <workflow>            full | fix
   state   <name> get <field>
   state   <name> set <field> <value>
-  state   <name> transition <event>         open-complete|design-complete|build-complete|verify-pass|verify-fail|archived
+  state   <name> transition <event>         open-complete|design-complete|build-complete|verify-pass|verify-fail|fix-upgrade|archived
   state   <name> check <phase> [--json]
   state   <name> recover <phase>
   state   <name> scale
@@ -72,9 +72,10 @@ Usage: comate.sh <command> ...
   sources <name> check
   sources <name> list
   sources find <file>
+  dependency <name> archived              verify an exact archived change exists
   gate    <prd> review                      create/refresh gate.yaml next to PRD, pin hash
   gate    <prd> set <field> <value>         score | blocking_open | gate_status | …
-  gate    <prd> pass [--tbd]                mark passed (needs blocking_open=0 + report)
+  gate    <prd> pass [--tbd]                pass: zero blockers; --tbd: accepted blockers
   gate    <prd> spawned <change>            record a change fanned out from this PRD
   gate    <prd> status [--json]
   gate    <prd> check                       precondition guard before spawning a change
@@ -138,6 +139,8 @@ state_init() {
 schema_version: $COMATE_SCHEMA_VERSION
 workflow: $workflow
 phase: open
+phase_step: null
+phase_step_data: null
 build_mode: $build_mode
 tdd_mode: $tdd_mode
 isolation: $isolation
@@ -237,7 +240,7 @@ state_transition() {
   validate_change_name "$name"
   validate_enum_event() {
     case "$1" in
-      open-complete|design-complete|build-complete|verify-pass|verify-fail|archived) return 0 ;;
+      open-complete|design-complete|build-complete|verify-pass|verify-fail|fix-upgrade|archived) return 0 ;;
       *) die "$COMATE_USAGE" "ERROR: unknown event '$1'" ;;
     esac
   }
@@ -246,6 +249,13 @@ state_transition() {
   local yaml; yaml=$(require_yaml "$name")
   validate_flat_yaml "$yaml"
 
+  # phase_step is local to the current phase. Carrying it into the next phase
+  # makes identical step numbers ambiguous and can skip mandatory work.
+  _clear_phase_progress() {
+    yaml_set "$yaml" phase_step null
+    yaml_set "$yaml" phase_step_data null
+  }
+
   case "$event" in
     open-complete)
       _require_phase "$yaml" open
@@ -255,10 +265,12 @@ state_transition() {
       else
         yaml_set "$yaml" phase build
       fi
+      _clear_phase_progress
       ;;
     design-complete)
       _require_phase "$yaml" design
       yaml_set "$yaml" phase build
+      _clear_phase_progress
       ;;
     build-complete)
       _require_phase "$yaml" build
@@ -267,6 +279,7 @@ state_transition() {
       yaml_set "$yaml" verify_result pending
       yaml_set "$yaml" verification_report null
       yaml_set "$yaml" branch_status pending
+      _clear_phase_progress
       ;;
     verify-pass)
       _require_phase "$yaml" verify
@@ -274,12 +287,36 @@ state_transition() {
       yaml_set "$yaml" verify_result pass
       yaml_set "$yaml" phase archive
       yaml_set "$yaml" verified_at "$(today)"
+      _clear_phase_progress
       ;;
     verify-fail)
       _require_phase "$yaml" verify
-      yaml_set "$yaml" verify_result fail
+      # The failure is captured in the report; once routed back to build the
+      # active verification state must be pending or the orchestrator loops.
+      yaml_set "$yaml" verify_result pending
       yaml_set "$yaml" phase build
+      yaml_set "$yaml" verification_report null
+      yaml_set "$yaml" branch_status pending
+      _clear_phase_progress
+      ;;
+    fix-upgrade)
+      [ "$(yaml_get "$yaml" workflow)" = "fix" ] || \
+        die "$COMATE_BLOCK" "ERROR: fix-upgrade requires workflow=fix"
+      case "$(yaml_get "$yaml" phase)" in
+        open|build) ;;
+        *) die "$COMATE_BLOCK" "ERROR: fix-upgrade is only valid from open or build" ;;
+      esac
+      yaml_set "$yaml" workflow full
+      yaml_set "$yaml" phase design
+      yaml_set "$yaml" build_mode null
+      yaml_set "$yaml" tdd_mode null
+      yaml_set "$yaml" isolation null
+      yaml_set "$yaml" verify_mode null
+      yaml_set "$yaml" direct_override false
+      yaml_set "$yaml" verify_result pending
+      yaml_set "$yaml" verification_report null
       yaml_set "$yaml" branch_status pending
+      _clear_phase_progress
       ;;
     archived)
       _require_phase "$yaml" archive
@@ -498,15 +535,19 @@ state_recover() {
   yaml="$dir/.comate.yaml"
   [ -f "$yaml" ] || die "$COMATE_CORRUPT" "ERROR: .comate.yaml not found at $yaml"
 
-  local phase workflow
+  local phase workflow phase_step phase_step_data
   phase=$(yaml_get "$yaml" phase)
   workflow=$(yaml_get "$yaml" workflow)
+  phase_step=$(yaml_get "$yaml" phase_step)
+  phase_step_data=$(yaml_get "$yaml" phase_step_data)
   # If a phase arg was passed, honor it for reporting; else use stored phase.
   [ -n "$phase_arg" ] && phase="$phase_arg"
 
   echo "=== Recovery Context: $name ==="
   echo "Phase: $phase"
   echo "Workflow: $workflow"
+  echo "Phase step: ${phase_step:-null}"
+  echo "Phase step data: ${phase_step_data:-null}"
   echo ""
 
   local design_doc plan verify_result verify_mode verification_report
@@ -578,7 +619,11 @@ state_recover() {
         echo "Tasks: tasks.md MISSING"
       fi
       echo ""
-      if [ "$isolation" = "null" ] || [ -z "$isolation" ]; then
+      if [[ "$phase_step" == build.blocked-by-* ]]; then
+        local dep="$phase_step_data"
+        if [ -z "$dep" ] || [ "$dep" = "null" ]; then dep="${phase_step#build.blocked-by-}"; fi
+        echo "Recovery action: Blocked by $dep. Run: comate.sh dependency $dep archived"
+      elif [ "$isolation" = "null" ] || [ -z "$isolation" ]; then
         echo "Recovery action: Isolation not selected. AskUserQuestion for branch/worktree."
       elif [ "$build_mode" = "null" ] || [ -z "$build_mode" ]; then
         echo "Recovery action: Build mode not selected. AskUserQuestion for execution method."
@@ -600,7 +645,9 @@ state_recover() {
       _field_status "branch_status" "$branch_status"
       _field_status "impl_hash" "$impl_hash"
       echo ""
-      if [ "$verify_result" = "pass" ] && [ "$branch_status" = "handled" ]; then
+      if [ "$branch_status" = "discarded" ]; then
+        echo "Recovery action: Work was discarded. Run verify-fail to return to build before reimplementing, or explicitly abandon the change."
+      elif [ "$verify_result" = "pass" ] && [ "$branch_status" = "handled" ]; then
         echo "Recovery action: Verification complete. Run guard to transition to archive."
       elif [ "$verify_result" = "pass" ]; then
         echo "Recovery action: Verified but branch not handled. Complete branch handling, set branch_status=handled."
@@ -1345,6 +1392,23 @@ sources_find() {
   return 0
 }
 
+# dependency <name> archived — prove completion from archived state, rather
+# than inferring it from absence in `openspec list`.
+dependency_archived() {
+  local name="$1"
+  validate_change_name "$name"
+  [ ! -d "openspec/changes/$name" ] || \
+    die "$COMATE_BLOCK" "BLOCK: dependency '$name' is still active"
+  local found="" yaml
+  while IFS= read -r yaml; do
+    [ "$(yaml_get "$yaml" archived)" = "true" ] && found="$yaml"
+  done < <(find openspec/changes/archive -mindepth 2 -maxdepth 2 \
+    -path "*/????-??-??-${name}/.comate.yaml" -type f 2>/dev/null | sort)
+  [ -n "$found" ] || \
+    die "$COMATE_BLOCK" "BLOCK: no archived=true record found for dependency '$name'"
+  log_pass "[DEPENDENCY] archived: $name ($found)"
+}
+
 # =====================================================================
 # gate — phase 0: PRD quality gate + split precondition
 # =====================================================================
@@ -1416,10 +1480,8 @@ gate_set() {
   log_pass "[GATE] set $field=$value"
 }
 
-# gate <prd> pass [--tbd] — flip to passed/passed-with-tbd. Hard precondition:
-# blocking_open must be 0 (no open blocking issues). Re-pins prd_hash so a later
-# edit invalidates the pass. --tbd records that the user authorised proceeding
-# with unresolved TBDs (spawned changes must carry ⚠ markers).
+# 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() {
   local prd; prd=$(require_prd "$1")
   local tbd=0
@@ -1427,9 +1489,22 @@ gate_pass() {
   local gate; gate=$(gate_path_for "$prd")
   [ -f "$gate" ] || die "$COMATE_CORRUPT" "ERROR: gate not found (run 'gate review' first): $gate"
 
-  local blocking; blocking=$(yaml_get "$gate" blocking_open)
-  if [ "$blocking" != "0" ]; then
-    die "$COMATE_BLOCK" "BLOCK: blocking_open='$blocking' — resolve all blocking issues (set blocking_open 0) before passing the gate"
+  local score blocking changes_map
+  score=$(yaml_get "$gate" score)
+  blocking=$(yaml_get "$gate" blocking_open)
+  changes_map=$(yaml_get "$gate" changes_map)
+  [[ "$score" =~ ^[0-9]+$ ]] && [ "$score" -ge 0 ] && [ "$score" -le 100 ] || \
+    die "$COMATE_BLOCK" "BLOCK: score must be an integer from 0 to 100 (got '$score')"
+  [[ "$blocking" =~ ^[0-9]+$ ]] || \
+    die "$COMATE_BLOCK" "BLOCK: blocking_open must be a non-negative integer (got '$blocking')"
+  if [ "$tbd" -eq 1 ]; then
+    [ "$blocking" -gt 0 ] || \
+      die "$COMATE_BLOCK" "BLOCK: --tbd requires at least one recorded unresolved blocker"
+  elif [ "$blocking" -ne 0 ]; then
+    die "$COMATE_BLOCK" "BLOCK: blocking_open='$blocking' — resolve all blocking issues or use --tbd after explicit user authorization"
+  fi
+  if [ -z "$changes_map" ] || [ "$changes_map" = "null" ]; then
+    die "$COMATE_BLOCK" "BLOCK: changes_map is required before passing the gate"
   fi
   local report; report=$(yaml_get "$gate" review_report)
   if [ -z "$report" ] || [ "$report" = "null" ] || ! file_nonempty "$report"; then
@@ -1703,7 +1778,7 @@ status() {
     echo "No active changes."
     return 0
   fi
-  local any=0 d name yaml phase workflow build_mode vr dd plan total done tasks_file
+  local any=0 d name yaml phase phase_step workflow build_mode vr dd plan total done tasks_file
   for d in "$changes_dir"/*/; do
     [ -d "$d" ] || continue
     name=$(basename "$d")
@@ -1713,6 +1788,7 @@ status() {
     [ "$(yaml_get "$yaml" archived)" = "true" ] && continue
     any=1
     phase=$(yaml_get "$yaml" phase)
+    phase_step=$(yaml_get "$yaml" phase_step)
     workflow=$(yaml_get "$yaml" workflow)
     build_mode=$(yaml_get "$yaml" build_mode)
     vr=$(yaml_get "$yaml" verify_result)
@@ -1726,6 +1802,7 @@ status() {
     fi
     echo "• $name [phase: $phase, $done/$total tasks]"
     echo "    workflow: $workflow | build_mode: $build_mode"
+    [ -n "$phase_step" ] && [ "$phase_step" != "null" ] && echo "    step: $phase_step"
     [ -n "$dd" ] && [ "$dd" != "null" ] && echo "    design: $dd"
     [ -n "$plan" ] && [ "$plan" != "null" ] && echo "    plan:   $plan"
     [ "$phase" = "verify" ] && echo "    verify_result: $vr"
@@ -1870,6 +1947,11 @@ case "$CMD" in
       esac
     fi
     ;;
+  dependency)
+    NAME="${1:-}"; SUB="${2:-}"
+    [ -n "$NAME" ] && [ "$SUB" = "archived" ] || { usage_top; exit "$COMATE_USAGE"; }
+    dependency_archived "$NAME"
+    ;;
   gate)
     PRD="${1:-}"; SUB="${2:-}"
     [ -n "$PRD" ] && [ -n "$SUB" ] || { usage_top; exit "$COMATE_USAGE"; }

package/skills/comate/tests/comate.bats

@@ -144,8 +144,10 @@ seed_open() {
 
 @test "open-complete routes full to design" {
   seed_open
+  comate state demo set phase_step open.review-confirmed >/dev/null
   comate state demo transition open-complete
   [ "$(comate state demo get phase)" = "design" ]
+  [ "$(comate state demo get phase_step)" = "null" ]
 }
 
 @test "open-complete routes fix to build" {
@@ -201,6 +203,56 @@ seed_open() {
   [ "$status" -eq 1 ]
 }
 
+@test "fix-upgrade resets preset decisions and enters design" {
+  comate state demo init fix
+  comate state demo transition open-complete
+  comate state demo set phase_step build.options-confirmed >/dev/null
+  comate state demo transition fix-upgrade
+  [ "$(comate state demo get workflow)" = "full" ]
+  [ "$(comate state demo get phase)" = "design" ]
+  [ "$(comate state demo get build_mode)" = "null" ]
+  [ "$(comate state demo get tdd_mode)" = "null" ]
+  [ "$(comate state demo get isolation)" = "null" ]
+  [ "$(comate state demo get phase_step)" = "null" ]
+}
+
+@test "discarded branch cannot pass verification" {
+  comate state demo init full
+  comate state demo set phase verify >/dev/null
+  printf '# pass\n' > report.md
+  comate state demo set verification_report report.md >/dev/null
+  comate state demo set branch_status discarded >/dev/null
+  run comate state demo transition verify-pass
+  [ "$status" -eq 1 ]
+  [ "$(comate state demo get phase)" = "verify" ]
+}
+
+@test "verify-fail returns to build without a failure routing loop" {
+  comate state demo init full
+  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" ]
+  [ "$(comate state demo get verification_report)" = "null" ]
+}
+
+@test "recover reports phase-local progress" {
+  comate state demo init full
+  comate state demo set phase_step open.review-awaiting >/dev/null
+  run comate state demo recover open
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"Phase step: open.review-awaiting"* ]]
+}
+
+@test "status exposes awaiting decisions" {
+  comate state demo init full
+  comate state demo set phase_step open.review-awaiting >/dev/null
+  run comate status
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"step: open.review-awaiting"* ]]
+}
+
 # --- guard open ---
 
 @test "guard open passes with full artifacts and applies" {
@@ -436,6 +488,18 @@ SH
   [ "$status" -eq 0 ]
 }
 
+@test "dependency archived requires an archived=true record" {
+  comate state dep init full
+  run comate dependency dep archived
+  [ "$status" -eq 1 ]
+  comate state dep set phase archive >/dev/null
+  comate state dep transition archived >/dev/null
+  mkdir -p openspec/changes/archive
+  mv openspec/changes/dep openspec/changes/archive/2026-08-20-dep
+  run comate dependency dep archived
+  [ "$status" -eq 0 ]
+}
+
 @test "top-level usage error returns code 2" {
   run comate frobnicate
   [ "$status" -eq 2 ]
@@ -503,16 +567,41 @@ 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 "demo:功能项1" >/dev/null
   run comate gate "$prd" pass
   [ "$status" -eq 1 ]
   [[ "$output" == *"report"* ]]
 }
 
+@test "gate pass blocks without a confirmed changes 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
+  printf '# report\n' > "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
+  run comate gate "$prd" pass
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"changes_map"* ]]
+}
+
+@test "gate pass --tbd requires unresolved blockers" {
+  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 "demo:功能项1" >/dev/null
+  printf '# report\n' > "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
+  run comate gate "$prd" pass --tbd
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"requires at least one"* ]]
+}
+
 @test "gate pass succeeds and check passes after report written" {
   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 "demo:功能项1" >/dev/null
   printf '# 评审报告\n' > \
     "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
   run comate gate "$prd" pass
@@ -525,7 +614,8 @@ seed_prd() {
   local prd; prd=$(seed_prd)
   comate gate "$prd" review >/dev/null
   comate gate "$prd" set score 65 >/dev/null
-  comate gate "$prd" set blocking_open 0 >/dev/null
+  comate gate "$prd" set blocking_open 2 >/dev/null
+  comate gate "$prd" set changes_map "demo:功能项1" >/dev/null
   printf '# 评审报告\n' > \
     "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
   run comate gate "$prd" pass --tbd
@@ -539,6 +629,7 @@ 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 "demo:功能项1" >/dev/null
   printf '# 评审报告\n' > \
     "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
   comate gate "$prd" pass >/dev/null
@@ -554,6 +645,7 @@ 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 "demo:功能项1" >/dev/null
   printf '# 评审报告\n' > \
     "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
   comate gate "$prd" pass >/dev/null
@@ -572,6 +664,7 @@ 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
@@ -587,6 +680,7 @@ 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
@@ -616,6 +710,7 @@ 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 "demo:功能项1" >/dev/null
   printf '# 报告\n' > \
     "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
   comate gate "$prd" pass >/dev/null

package/skills/comate-archive/SKILL.md

@@ -1,63 +1,63 @@
----
-name: comate-archive
-description: "comate 阶段 5：归档。用 /comate-archive 调用。委托 OpenSpec 合并 delta spec 并归档 change。"
----
-
-# comate 阶段 5：归档（Archive）
-
-## 前置条件
-
-- 验证已通过（阶段 4 完成），分支已处理
-- `openspec/changes/<name>/.comate.yaml` 中 `verify_result: pass`
-
-## 步骤
-
-### 0. 入口状态验证
-
-```bash
-COMATE="${COMATE:-$(for r in . ./.agents/skills ./.claude/skills ./.cursor/skills ./.codex/skills "$HOME"/.agents/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills "$HOME"/.codex/skills "$HOME"/.gemini/skills; do
-  [ -d "$r" ] && find "$r" -maxdepth 6 -path '*/comate/scripts/comate.sh' -type f -print -quit 2>/dev/null
-done | head -1)}"
-if [ -z "$COMATE" ]; then
-  echo "ERROR: comate.sh 未找到，请确认 comate skill 已安装。" >&2
-  return 1 2>/dev/null || exit 1
-fi
-bash "$COMATE" state <name> check archive
-```
-
-### 1. 执行归档
-
-```bash
-bash "$COMATE" archive "<name>"
-```
-
-脚本自动完成：
-1. 入口状态验证（phase=archive, verify_result=pass, archived=false）
-2. 委托 `openspec archive <name> -y` 合并 delta spec 到主 spec；无 delta spec 时使用 `--skip-specs`
-3. Design doc 前置元数据标注（archived-with, status: final），并把正文中指向 `openspec/changes/<name>/` 的引用重写为归档路径
-4. Plan 前置元数据标注（archived-with），同样重写正文 OpenSpec 路径引用
-5. 由 OpenSpec 移动 change 到 `openspec/changes/archive/YYYY-MM-DD-<name>/`
-6. 通过 `state transition <archive-name> archived` 设 `archived: true`
-7. 重写归档后 `.comate.yaml` 中随 change 移动的自指字段（`source_manifest` / `handoff_context` / `impl_context`）指向新归档路径，使 `sources <name> check/list` 等命令对归档 change 仍可用
-
-非零退出码 → 报告错误并停止。零退出码 → 归档完成。摘要 `X/Y steps succeeded` 以真实执行步骤计数。
-
-需预览不实际执行：加 `--dry-run`。
-
-### 2. 生命周期闭环
-
-```
-brainstorming → delta spec → 实施 → 验证 → OpenSpec 合并主 spec → design doc 标注 → 归档
-```
-
-## 退出条件
-
-- 归档脚本退出码 0
-- 归档目录 `openspec/changes/archive/YYYY-MM-DD-<name>/` 存在
-- 归档后 `.comate.yaml` 中 `archived: true`
-
-归档成功后**不要再对原 change 名跑 guard**，原活跃目录已不存在。
-
-## 完成
-
-comate 流程全部完成。如需开始新工作，调用 `/comate` 或 `/comate-open`。
+---
+name: comate-archive
+description: "comate 阶段 5：归档。用 /comate-archive 调用。委托 OpenSpec 合并 delta spec 并归档 change。"
+---
+
+# comate 阶段 5：归档（Archive）
+
+## 前置条件
+
+- 验证已通过（阶段 4 完成），分支已处理
+- `openspec/changes/<name>/.comate.yaml` 中 `verify_result: pass`
+
+## 步骤
+
+### 0. 入口状态验证
+
+```bash
+COMATE="${COMATE:-$(for r in . ./.agents/skills ./.claude/skills ./.cursor/skills ./.codex/skills "$HOME"/.agents/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills "$HOME"/.codex/skills "$HOME"/.gemini/skills; do
+  [ -d "$r" ] && find "$r" -maxdepth 6 -path '*/comate/scripts/comate.sh' -type f -print -quit 2>/dev/null
+done | head -1)}"
+if [ -z "$COMATE" ]; then
+  echo "ERROR: comate.sh 未找到，请确认 comate skill 已安装。" >&2
+  return 1 2>/dev/null || exit 1
+fi
+bash "$COMATE" state <name> check archive
+```
+
+### 1. 执行归档
+
+```bash
+bash "$COMATE" archive "<name>"
+```
+
+脚本自动完成：
+1. 入口状态验证（phase=archive, verify_result=pass, archived=false）
+2. 委托 `openspec archive <name> -y` 合并 delta spec 到主 spec；无 delta spec 时使用 `--skip-specs`
+3. Design doc 前置元数据标注（archived-with, status: final），并把正文中指向 `openspec/changes/<name>/` 的引用重写为归档路径
+4. Plan 前置元数据标注（archived-with），同样重写正文 OpenSpec 路径引用
+5. 由 OpenSpec 移动 change 到 `openspec/changes/archive/YYYY-MM-DD-<name>/`
+6. 通过 `state transition <archive-name> archived` 设 `archived: true`
+7. 重写归档后 `.comate.yaml` 中随 change 移动的自指字段（`source_manifest` / `handoff_context` / `impl_context`）指向新归档路径，使 `sources <name> check/list` 等命令对归档 change 仍可用
+
+非零退出码 → 报告错误并停止。零退出码 → 归档完成。摘要 `X/Y steps succeeded` 以真实执行步骤计数。
+
+需预览不实际执行：加 `--dry-run`。
+
+### 2. 生命周期闭环
+
+```
+brainstorming → delta spec → 实施 → 验证 → OpenSpec 合并主 spec → design doc 标注 → 归档
+```
+
+## 退出条件
+
+- 归档脚本退出码 0
+- 归档目录 `openspec/changes/archive/YYYY-MM-DD-<name>/` 存在
+- 归档后 `.comate.yaml` 中 `archived: true`
+
+归档成功后**不要再对原 change 名跑 guard**，原活跃目录已不存在。
+
+## 完成
+
+comate 流程全部完成。如需开始新工作，调用 `/comate` 或 `/comate-open`。