@house365/comate 0.9.5 → 0.9.7

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-build/SKILL.md

@@ -25,7 +25,43 @@ fi
 bash "$COMATE" state <name> check build
 ```
 
-**幂等性**：build 阶段操作可安全重复。读 `phase` 确认仍在 build，读 plan 文件头的 `base-ref`，再读 tasks.md 找第一个未勾选任务继续。已提交的任务不得重复提交。
+**幂等性检查**：
+
+1. 读取 `.comate.yaml` 的 `plan`、`isolation`、`build_mode`、`tdd_mode`、`phase_step`、`phase_step_data`
+
+2. **检查是否被依赖阻塞**（最高优先级检查）：
+   - 若 `phase_step` 为 `build.blocked-by-<dependency>`：
+     - 从 `phase_step` 或 `phase_step_data` 中提取依赖的 change 名称
+     - 运行 `bash "$COMATE" dependency <dependency> archived` 检查归档目录中是否存在该 change 且其 `.comate.yaml` 明确记录 `archived: true`；不得用“不在活跃列表”推断归档完成
+     - **若依赖已归档**：
+       ```bash
+       bash "$COMATE" state <name> set phase_step build.options-confirmed
+       bash "$COMATE" state <name> set phase_step_data null
+       ```
+       清除阻塞标记，说明「依赖 change <dependency> 已完成，继续当前 change 的 build」，继续第 3 步检查
+     - **若依赖未归档**：提示「当前 change 正在等待 <dependency> 完成。请先完成 <dependency> 的全流程后再继续。」，**立即退出**
+
+3. **已完成 Step 3（工作方式已选定）** 的判定条件：
+   - `isolation`、`build_mode`、`tdd_mode` **三个字段全部已设置且非 null**
+   - 或 `phase_step` 值为 `build.options-confirmed`
+
+4. **幂等分支**：
+   - **三个决策字段全部已设置** → 跳过 Step 3a-3c，说明「工作方式已选定：isolation={value}, build_mode={value}, tdd_mode={value}」，直接进入执行（加载对应技能）
+   - **任一字段未设置或为 null**：
+     - 若 `phase_step` 为 `build.plan-created` 或 `build.plan-recorded` → 继续对应步骤（见下方第 5 点）
+     - 若 `plan` 未设置 → 从 Step 1 开始
+     - 若 `plan` 已设置但决策未完成 → 从 Step 3 开始
+
+5. **断点恢复**（根据 `phase_step` 值）：
+   - `phase_step` 为 `build.plan-created`（或旧版 `1`）→ 从 Step 2 开始并改写新格式
+   - `phase_step` 为 `build.plan-recorded` / `build.options-awaiting`（或旧版 `2`）→ 从 Step 3 恢复并改写新格式
+   - `phase_step` 为 `build.options-confirmed`（或旧版 `3-confirmed`）→ 直接加载执行技能并改写新格式
+   - `phase_step` 为 `build.blocked-by-*` → 见第 2 点的依赖阻塞检查
+
+6. **已进入执行阶段**（plan 已设置、决策已完成）：
+   - 读 tasks.md 找第一个未勾选任务继续
+   - 已提交的任务不得重复提交
+   - 上下文压缩恢复时，重新加载对应的执行技能，然后继续未完成的任务
 
 ### 1. 制定计划
 
@@ -44,10 +80,17 @@ base-ref: <实施前的 git rev-parse HEAD>
 
 `base-ref` 用于验证阶段跨提交统计改动规模。创建计划时先 `git rev-parse HEAD` 记录。
 
+**步骤完成后记录**：
+
+```bash
+bash "$COMATE" state <name> set phase_step build.plan-created
+```
+
 ### 2. 记录计划路径
 
 ```bash
 bash "$COMATE" state <name> set plan docs/superpowers/plans/YYYY-MM-DD-feature.md
+bash "$COMATE" state <name> set phase_step build.plan-recorded
 ```
 
 无需手动改 phase，guard 会在退出条件满足后自动流转。
@@ -79,11 +122,17 @@ bash "$COMATE" state <name> set plan docs/superpowers/plans/YYYY-MM-DD-feature.m
 
 #### 3c. 联合决策（仍有 ≥2 有效选项的维度才问）
 
-对仍有多个有效选项的维度，**一次 AskUserQuestion 问清全部**，选 `branch` 时**分支名也在同一次确认**，不得先问是否继续再二次追问配置或命名。已在 3b 自动写入的维度不再列入问题。每个选项附推荐理由（推荐只说明倾向，不代替用户拍板）：
+对仍有多个有效选项的维度，**一次 AskUserQuestion 问清全部**，选 `branch` 时**分支名也在同一次确认**，不得先问是否继续再二次追问配置或命名。已在 3b 自动写入的维度不再列入问题。每个选项附推荐理由（推荐只说明倾向，不代替用户拍板）：
 
 - **工作区隔离**：`branch` 新建分支（简单快速，≤3 文件推荐）/ `worktree` 独立工作区（需并行或当前分支有未提交工作时推荐）。
 - **执行方式**：`subagent-driven-development`（任务 ≥3、独立、需双阶段审查）/ `executing-plans`（任务 ≤2 且无跨模块依赖，或来自 fix 预设）。
-- **TDD 模式**：`tdd`（涉及业务逻辑/新功能/API，推荐）/ `direct`（无需测试覆盖或用户明确跳过）。
+- **TDD 模式**：`tdd`（涉及业务逻辑/新功能/API，推荐）/ `direct`（无需测试覆盖或用户明确跳过）。
+
+提问前先持久化：
+
+```bash
+bash "$COMATE" state <name> set phase_step build.options-awaiting
+```
 
 用户选择后（连同 3b 已自动应用的维度）写入：
 
@@ -91,6 +140,7 @@ bash "$COMATE" state <name> set plan docs/superpowers/plans/YYYY-MM-DD-feature.m
 bash "$COMATE" state <name> set isolation <branch|worktree>
 bash "$COMATE" state <name> set build_mode <subagent-driven-development|executing-plans|direct>
 bash "$COMATE" state <name> set tdd_mode <tdd|direct>
+bash "$COMATE" state <name> set phase_step build.options-confirmed
 ```
 
 `isolation` 是脚本级硬约束，保持 `null` 时 `build → verify` 的 guard 和 `state transition build-complete` 都会失败。
@@ -136,9 +186,36 @@ bash "$COMATE" state <name> set build_mode direct
 |------|------|------|
 | 小 | 遗漏验收场景、边界条件 | 直接编辑 delta spec + design.md，追加 tasks.md |
 | 中 | 接口变更、新增组件、数据流变化 | **AskUserQuestion 确认后**加载 `superpowers:brainstorming` 更新 Design Doc + delta spec |
-| 大 | 全新 capability | **AskUserQuestion 确认拆分后**用 `/comate-open` 创建独立 change |
-
-**50% 阈值**：以 tasks.md 初始任务总数为基准，新增任务超过总数一半即视为超范围，**必须 AskUserQuestion 暂停**决定是否拆分。创建独立 change 必须调 `/comate-open`，不得直接调 `/opsx:new`。
+| 大 | 全新 capability | **AskUserQuestion 确认拆分后**用 `/comate-open` 创建独立 change，**当前 change 的 build 流程立即终止** |
+
+**50% 阈值**：以 tasks.md 初始任务总数为基准，新增任务超过总数一半即视为超范围，**必须 AskUserQuestion 暂停**决定是否拆分。创建独立 change 必须调 `/comate-open`，不得直接调 `/opsx:new`。
+
+凡需 AskUserQuestion 决定范围扩张时，提问前先写 `phase_step: build.scope-awaiting`；用户决定继续当前 change 后恢复为 `build.options-confirmed`。
+
+**大规模扩张（全新 capability）确认拆分后的流程终止规则**：
+
+1. 用 `/comate-open` 创建独立 change `<new-change-name>`
+2. **当前 change `<current>` 的 build 流程立即暂停**，记录依赖关系：
+   ```bash
+   bash "$COMATE" state <current> set phase_step "build.blocked-by-<new-change-name>"
+   bash "$COMATE" state <current> set phase_step_data "<new-change-name>"
+   ```
+3. 提示用户：
+   ```
+   已创建独立 change <new-change-name>。
+   当前 change <current> 的 build 流程已暂停，等待 <new-change-name> 完成。
+   
+   请先完成 <new-change-name> 的全流程（design → build → verify → archive），
+   然后再继续 <current> 的 build。
+   ```
+4. **立即退出当前 /comate 调用**，不继续执行当前 change 的后续任务，不进入 Step 5
+
+**恢复被阻塞的 change**：
+
+当用户稍后运行 `/comate <current>` 时，Step 0 幂等性检查会发现 `phase_step` 包含 `blocked-by` 标记：
+- 检查依赖的 change 是否已归档
+- 若 `dependency <name> archived` 通过 → 清除阻塞标记，恢复 `phase_step` 为 `build.options-confirmed`，继续执行 tasks.md 中未完成的任务
+- 若未归档 → 提示用户先完成依赖 change，退出
 
 ### 5. 上下文管理与 build 交接包