@house365/comate 0.10.2 → 1.0.2-next.0

package/skills/comate/scripts/comate.sh

@@ -1,2147 +0,0 @@
-#!/bin/bash
-# comate.sh — single entry dispatcher for comate.
-#
-# Subcommands:
-#   state   <name> init <workflow>           — create .comate.yaml with workflow defaults
-#   state   <name> get <field>               — read a field
-#   state   <name> set <field> <value>       — write a field (atomic, write-back checked)
-#   state   <name> transition <event>        — guarded state-machine transition
-#   state   <name> check <phase> [--json]    — entry-precondition check for a phase
-#   state   <name> recover <phase>           — structured compaction-resume context
-#   state   <name> scale                     — assess and set verify_mode
-#   state   <name> validate                  — schema + flat-yaml validation
-#   guard   <name> <phase> [--apply] [--json] — exit-evidence check, optionally transition
-#   handoff <name> design --write [--full]   — design->build handoff package
-#   handoff <name> build  --write            — build->verify handoff package
-#   sources <name> track <file...> [--note]  — record knowledge-base source files
-#   sources <name> check                     — drift check tracked source files
-#   sources <name> list                      — print the source manifest
-#   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]               — 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
-#   status  [path]                           — list active changes + next command
-#   doctor                                   — prerequisite self-check
-#
-# Exit codes: 0 OK | 1 BLOCK | 2 USAGE | 3 ENV | 4 CORRUPT
-
-set -euo pipefail
-
-# 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
-. "$SCRIPT_DIR/comate-lib.sh"
-
-usage_top() {
-  cat >&2 <<'EOF'
-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|fix-upgrade|archived
-  state   <name> check <phase> [--json]
-  state   <name> recover <phase>
-  state   <name> scale
-  state   <name> validate
-  guard   <name> <phase> [--apply] [--json]
-  handoff <name> design --write [--full]
-  handoff <name> build  --write
-  sources <name> track <file...> [--note <text>]
-  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]                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]
-  status  [path]
-  doctor
-EOF
-}
-
-require_yaml() {
-  # $1 = change name; ensures .comate.yaml exists, echoes its path.
-  local name="$1" yaml
-  yaml=$(comate_yaml_for "$name")
-  [ -f "$yaml" ] || die "$COMATE_CORRUPT" "ERROR: .comate.yaml not found at $yaml"
-  echo "$yaml"
-}
-
-today() { date +%Y-%m-%d; }
-
-# =====================================================================
-# state
-# =====================================================================
-
-state_init() {
-  local name="$1" workflow="${2:-}"
-  validate_change_name "$name"
-  validate_enum workflow "$workflow"
-  [ -n "$workflow" ] || die "$COMATE_USAGE" "Usage: comate.sh state <name> init <full|fix>"
-
-  local dir yaml
-  dir=$(comate_change_dir "$name")
-  yaml="$dir/.comate.yaml"
-  [ -f "$yaml" ] && die "$COMATE_USAGE" "ERROR: .comate.yaml already exists at $yaml"
-  mkdir -p "$dir"
-
-  # base_ref = current HEAD.
-  local base_ref="null"
-  if git rev-parse --verify HEAD >/dev/null 2>&1; then
-    base_ref=$(git rev-parse HEAD 2>/dev/null || echo "null")
-  fi
-  # base_branch = detected default branch, fallback main/master.
-  local base_branch="null" ref
-  if ref=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null); then
-    base_branch="${ref#refs/remotes/origin/}"
-  elif git show-ref --verify --quiet refs/heads/main 2>/dev/null; then
-    base_branch="main"
-  elif git show-ref --verify --quiet refs/heads/master 2>/dev/null; then
-    base_branch="master"
-  fi
-
-  # Workflow defaults: full leaves decisions null; presets prefill.
-  local build_mode="null" tdd_mode="null" isolation="null" verify_mode="null"
-  case "$workflow" in
-    fix)
-      build_mode="direct"; tdd_mode="direct"; isolation="branch"; verify_mode="light" ;;
-  esac
-
-  # Write full canonical file directly (FIELD_ORDER kept in sync with lib).
-  cat > "$yaml" <<EOF
-# comate state — flat key:value only, no nesting
-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
-verify_mode: $verify_mode
-verify_result: pending
-design_doc: null
-plan: null
-verification_report: null
-branch_status: pending
-handoff_context: null
-handoff_hash: null
-impl_context: null
-impl_hash: null
-direct_override: false
-base_ref: $base_ref
-base_branch: $base_branch
-source_kind: conversation
-source_manifest: null
-build_command: null
-verify_command: null
-created_at: $(today)
-verified_at: null
-archived: false
-EOF
-
-  validate_flat_yaml "$yaml"
-  log_pass "[INIT] $yaml (workflow=$workflow, base_branch=$base_branch)"
-}
-
-state_get() {
-  local name="$1" field="${2:-}"
-  validate_change_name "$name"
-  [ -n "$field" ] || die "$COMATE_USAGE" "Usage: comate.sh state <name> get <field>"
-  local yaml; yaml=$(require_yaml "$name")
-  yaml_get "$yaml" "$field"
-}
-
-state_set() {
-  local name="$1" field="${2:-}" value="${3:-}"
-  validate_change_name "$name"
-  [ -n "$field" ] || die "$COMATE_USAGE" "Usage: comate.sh state <name> set <field> <value>"
-  if [ "$field" = "phase" ]; then
-    log_warn "WARNING: setting 'phase' directly bypasses the state machine; prefer 'state transition'."
-  fi
-  local yaml; yaml=$(require_yaml "$name")
-  yaml_set "$yaml" "$field" "$value"
-  log_pass "[SET] $field=$value"
-}
-
-# --- transition guards (see IMPLEMENTATION.md §3 guard table) ---
-
-_require_phase() {
-  local yaml="$1" expected="$2" actual
-  actual=$(yaml_get "$yaml" phase)
-  [ "$actual" = "$expected" ] || \
-    die "$COMATE_BLOCK" "ERROR: expected phase '$expected', got '${actual:-null}'"
-}
-
-_require_build_decisions() {
-  local yaml="$1"
-  local workflow build_mode tdd_mode isolation direct_override
-  workflow=$(yaml_get "$yaml" workflow)
-  build_mode=$(yaml_get "$yaml" build_mode)
-  tdd_mode=$(yaml_get "$yaml" tdd_mode)
-  isolation=$(yaml_get "$yaml" isolation)
-  direct_override=$(yaml_get "$yaml" direct_override)
-  case "$isolation" in
-    branch|worktree) ;;
-    *) die "$COMATE_BLOCK" "ERROR: isolation must be branch or worktree, got '${isolation:-null}'" ;;
-  esac
-  case "$build_mode" in
-    subagent-driven-development|executing-plans|direct) ;;
-    *) die "$COMATE_BLOCK" "ERROR: build_mode must be selected, got '${build_mode:-null}'" ;;
-  esac
-  if [ "$build_mode" = "direct" ] && [ "$workflow" != "fix" ] && [ "$direct_override" != "true" ]; then
-    die "$COMATE_BLOCK" "ERROR: build_mode=direct is only allowed for fix unless direct_override=true"
-  fi
-  case "$tdd_mode" in
-    tdd|direct) ;;
-    *) die "$COMATE_BLOCK" "ERROR: tdd_mode must be tdd or direct, got '${tdd_mode:-null}'" ;;
-  esac
-}
-
-_require_verify_evidence() {
-  local yaml="$1" report branch_status
-  report=$(yaml_get "$yaml" verification_report)
-  branch_status=$(yaml_get "$yaml" branch_status)
-  if [ -z "$report" ] || [ "$report" = "null" ] || [ ! -f "$report" ]; then
-    die "$COMATE_BLOCK" "ERROR: verification_report must point to an existing file (got '${report:-null}')"
-  fi
-  [ "$branch_status" = "handled" ] || \
-    die "$COMATE_BLOCK" "ERROR: branch_status must be 'handled', got '${branch_status:-null}'"
-}
-
-state_transition() {
-  local name="$1" event="${2:-}"
-  validate_change_name "$name"
-  validate_enum_event() {
-    case "$1" in
-      open-complete|design-complete|build-complete|verify-pass|verify-fail|fix-upgrade|archived) return 0 ;;
-      *) die "$COMATE_USAGE" "ERROR: unknown event '$1'" ;;
-    esac
-  }
-  [ -n "$event" ] || die "$COMATE_USAGE" "Usage: comate.sh state <name> transition <event>"
-  validate_enum_event "$event"
-  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
-      local workflow; workflow=$(yaml_get "$yaml" workflow)
-      if [ "$workflow" = "full" ]; then
-        yaml_set "$yaml" phase design
-      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
-      _require_build_decisions "$yaml"
-      yaml_set "$yaml" phase verify
-      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
-      _require_verify_evidence "$yaml"
-      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
-      # 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
-      yaml_set "$yaml" archived true
-      ;;
-  esac
-  log_pass "[TRANSITION] $event"
-}
-
-# --- validate (schema + flat-yaml) ---
-
-state_validate() {
-  local name="$1"
-  validate_change_name "$name"
-  local yaml; yaml=$(require_yaml "$name")
-  log_info "[VALIDATE] $yaml"
-
-  validate_flat_yaml "$yaml"  # dies code 4 on nesting/lists/block scalars
-
-  local errors=0 warnings=0
-  # schema_version present and known.
-  local sv; sv=$(yaml_get "$yaml" schema_version)
-  if [ -z "$sv" ] || [ "$sv" = "null" ]; then
-    log_warn "  WARN: schema_version missing"; warnings=$((warnings+1))
-  elif [ "$sv" != "$COMATE_SCHEMA_VERSION" ]; then
-    log_warn "  WARN: schema_version=$sv (this tool writes $COMATE_SCHEMA_VERSION)"; warnings=$((warnings+1))
-  fi
-
-  # Required fields present.
-  local required="workflow phase verify_result archived"
-  local f
-  for f in $required; do
-    if ! yaml_keys "$yaml" | grep -qx "$f"; then
-      log_fail "  FAIL: missing required field '$f'"; errors=$((errors+1))
-    fi
-  done
-
-  # 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 $(enum_keys); do
-    v=$(yaml_get "$yaml" "$key")
-    [ -z "$v" ] && continue
-    [ "$v" = "null" ] && continue
-    legal=$(enum_values "$key")
-    ok=0
-    for w in $legal; do
-      if [ "$v" = "$w" ]; then ok=1; break; fi
-    done
-    if [ "$ok" -eq 0 ]; then
-      log_fail "  FAIL: $key='$v' invalid (expected: $legal)"; errors=$((errors+1))
-    fi
-  done
-
-  # Path fields point to existing files when set.
-  for f in design_doc plan verification_report handoff_context impl_context; do
-    v=$(yaml_get "$yaml" "$f")
-    if [ -n "$v" ] && [ "$v" != "null" ] && [ ! -f "$v" ]; then
-      log_fail "  FAIL: $f='$v' does not exist on disk"; errors=$((errors+1))
-    fi
-  done
-
-  # Hash fields are 64 hex when set.
-  for f in handoff_hash impl_hash; do
-    v=$(yaml_get "$yaml" "$f")
-    if [ -n "$v" ] && [ "$v" != "null" ] && [[ ! "$v" =~ ^[a-f0-9]{64}$ ]]; then
-      log_fail "  FAIL: $f='$v' is not a sha256 hex digest"; errors=$((errors+1))
-    fi
-  done
-
-  # Unknown keys -> warning.
-  local known=" ${FIELD_ORDER[*]} "
-  while IFS= read -r key; do
-    [ -z "$key" ] && continue
-    case "$known" in
-      *" $key "*) ;;
-      *) log_warn "  WARN: unknown field '$key'"; warnings=$((warnings+1)) ;;
-    esac
-  done < <(yaml_keys "$yaml")
-
-  if [ "$errors" -gt 0 ]; then
-    die "$COMATE_CORRUPT" "$errors error(s), $warnings warning(s) — validation FAILED"
-  fi
-  log_pass "0 errors, $warnings warning(s) — validation PASSED"
-}
-
-# --- check (entry preconditions for a phase) ---
-
-CHECK_JSON=0
-declare -a CHECK_RESULTS=()  # "name|status"
-CHECK_BLOCK=0
-
-_chk() {
-  # $1 = name, $2 = 0(pass)/1(fail). Always returns 0 (set -e safe).
-  local name="$1" rc="$2"
-  if [ "$rc" -eq 0 ]; then
-    CHECK_RESULTS+=("$name|pass")
-    if [ "$CHECK_JSON" -eq 0 ]; then log_pass "  [PASS] $name"; fi
-  else
-    CHECK_RESULTS+=("$name|fail")
-    CHECK_BLOCK=1
-    if [ "$CHECK_JSON" -eq 0 ]; then log_fail "  [FAIL] $name"; fi
-  fi
-  return 0
-}
-
-_chk_yaml_is() {
-  local yaml="$1" field="$2" expected="$3" actual rc=0
-  actual=$(yaml_get "$yaml" "$field")
-  [ "$actual" = "$expected" ] || rc=1
-  _chk "$field=$expected (got ${actual:-null})" "$rc"
-}
-
-_chk_yaml_empty() {
-  local yaml="$1" field="$2" v rc=0
-  v=$(yaml_get "$yaml" "$field")
-  { [ -z "$v" ] || [ "$v" = "null" ]; } || rc=1
-  _chk "$field empty/null" "$rc"
-}
-
-_chk_nonempty() {
-  local rc=0
-  file_nonempty "$2" || rc=1
-  _chk "$1 non-empty" "$rc"
-}
-
-state_check() {
-  local name="$1" phase="${2:-}"
-  validate_change_name "$name"
-  validate_enum phase "$phase"
-  [ -n "$phase" ] || die "$COMATE_USAGE" "Usage: comate.sh state <name> check <phase> [--json]"
-  local dir yaml
-  dir=$(comate_change_dir "$name")
-  yaml="$dir/.comate.yaml"
-  [ -f "$yaml" ] || die "$COMATE_CORRUPT" "ERROR: .comate.yaml not found at $yaml"
-
-  case "$phase" in
-    open)
-      _chk ".comate.yaml exists" 0
-      _chk_yaml_is "$yaml" phase open
-      ;;
-    design)
-      _chk_yaml_is "$yaml" phase design
-      _chk_yaml_is "$yaml" workflow full
-      _chk_yaml_empty "$yaml" design_doc
-      _chk_nonempty "proposal.md" "$dir/proposal.md"
-      _chk_nonempty "design.md" "$dir/design.md"
-      _chk_nonempty "tasks.md" "$dir/tasks.md"
-      ;;
-    build)
-      _chk_yaml_is "$yaml" phase build
-      local workflow; workflow=$(yaml_get "$yaml" workflow)
-      if [ "$workflow" = "full" ]; then
-        local dd; dd=$(yaml_get "$yaml" design_doc)
-        { [ -n "$dd" ] && [ "$dd" != "null" ] && [ -f "$dd" ]; }
-        _chk "design_doc exists ($dd)" $?
-      fi
-      _chk_nonempty "proposal.md" "$dir/proposal.md"
-      _chk_nonempty "tasks.md" "$dir/tasks.md"
-      ;;
-    verify)
-      _chk_yaml_is "$yaml" phase verify
-      local vr; vr=$(yaml_get "$yaml" verify_result)
-      { [ "$vr" = "pending" ] || [ -z "$vr" ] || [ "$vr" = "null" ]; }
-      _chk "verify_result pending/null (got $vr)" $?
-      ;;
-    archive)
-      _chk_yaml_is "$yaml" phase archive
-      _chk_yaml_is "$yaml" verify_result pass
-      local ar; ar=$(yaml_get "$yaml" archived)
-      [ "$ar" != "true" ]; _chk "archived not yet true (got $ar)" $?
-      ;;
-  esac
-
-  if [ "$CHECK_JSON" -eq 1 ]; then
-    local out='{"phase":"'"$phase"'","checks":['
-    local first=1 r cname cstatus
-    for r in "${CHECK_RESULTS[@]}"; do
-      cname="${r%|*}"; cstatus="${r#*|}"
-      [ "$first" -eq 0 ] && out+=','
-      first=0
-      out+='{"name":"'"$(json_escape "$cname")"'","status":"'"$cstatus"'"}'
-    done
-    out+='],"block":'"$([ "$CHECK_BLOCK" -eq 1 ] && echo true || echo false)"'}'
-    printf '%s\n' "$out"
-  else
-    echo "" >&2
-    if [ "$CHECK_BLOCK" -eq 1 ]; then
-      log_fail "BLOCKED — fix failing checks before proceeding"
-    else
-      log_pass "ALL CHECKS PASSED — ready to proceed"
-    fi
-  fi
-  if [ "$CHECK_BLOCK" -eq 1 ]; then exit "$COMATE_BLOCK"; fi
-  exit "$COMATE_OK"
-}
-
-# --- recover (compaction-resume structured context) ---
-
-_field_status() {
-  # $1 name, $2 value, [$3 path]
-  local field="$1" value="$2" path="${3:-}"
-  if [ -z "$value" ] || [ "$value" = "null" ]; then
-    echo "  - $field: PENDING"
-  elif [ -n "$path" ] && [ ! -f "$path" ]; then
-    echo "  - $field: BROKEN (path $value does not exist)"
-  else
-    echo "  - $field: DONE ($value)"
-  fi
-}
-
-state_recover() {
-  local name="$1" phase_arg="${2:-}"
-  validate_change_name "$name"
-  local dir yaml
-  dir=$(comate_change_dir "$name")
-  yaml="$dir/.comate.yaml"
-  [ -f "$yaml" ] || die "$COMATE_CORRUPT" "ERROR: .comate.yaml not found at $yaml"
-
-  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
-  local branch_status handoff_context handoff_hash impl_context impl_hash
-  local isolation build_mode tdd_mode direct_override
-  design_doc=$(yaml_get "$yaml" design_doc)
-  plan=$(yaml_get "$yaml" plan)
-  verify_result=$(yaml_get "$yaml" verify_result)
-  verify_mode=$(yaml_get "$yaml" verify_mode)
-  verification_report=$(yaml_get "$yaml" verification_report)
-  branch_status=$(yaml_get "$yaml" branch_status)
-  handoff_context=$(yaml_get "$yaml" handoff_context)
-  handoff_hash=$(yaml_get "$yaml" handoff_hash)
-  impl_context=$(yaml_get "$yaml" impl_context)
-  impl_hash=$(yaml_get "$yaml" impl_hash)
-  isolation=$(yaml_get "$yaml" isolation)
-  build_mode=$(yaml_get "$yaml" build_mode)
-  tdd_mode=$(yaml_get "$yaml" tdd_mode)
-  direct_override=$(yaml_get "$yaml" direct_override)
-
-  case "$phase" in
-    open)
-      echo "Artifacts:"
-      local fdone
-      for f in proposal.md design.md tasks.md; do
-        if file_nonempty "$dir/$f"; then echo "  - $f: DONE"; else echo "  - $f: PENDING"; fi
-      done
-      echo ""
-      echo "Recovery action: Create or complete missing artifacts, then use AskUserQuestion for user confirmation."
-      ;;
-    design)
-      echo "Artifacts:"
-      for f in proposal.md design.md tasks.md; do
-        if file_nonempty "$dir/$f"; then echo "  - $f: DONE"; else echo "  - $f: MISSING (unexpected in design)"; fi
-      done
-      echo ""
-      echo "Design progress:"
-      _field_status "handoff_context" "$handoff_context" "$handoff_context"
-      _field_status "handoff_hash" "$handoff_hash"
-      _field_status "design_doc" "$design_doc" "$design_doc"
-      echo ""
-      if [ -n "$design_doc" ] && [ "$design_doc" != "null" ] && [ -f "$design_doc" ]; then
-        echo "Recovery action: Design Doc linked. Run guard to transition to build."
-      elif [ -n "$handoff_context" ] && [ "$handoff_context" != "null" ] && [ -f "$handoff_context" ]; then
-        echo "Recovery action: Handoff generated but Design Doc not created. Resume from brainstorming confirmation (Step 1c)."
-      else
-        echo "Recovery action: No handoff yet. Start from Step 1a (generate handoff package)."
-      fi
-      ;;
-    build)
-      echo "Build decisions:"
-      _field_status "isolation" "$isolation"
-      _field_status "build_mode" "$build_mode"
-      _field_status "tdd_mode" "$tdd_mode"
-      if [ "$build_mode" = "direct" ] && [ "$workflow" != "fix" ]; then
-        _field_status "direct_override" "$direct_override"
-      fi
-      echo ""
-      _field_status "plan" "$plan" "$plan"
-      _field_status "impl_context" "$impl_context" "$impl_context"
-      echo ""
-      local tasks_file="$dir/tasks.md" total=0 done=0 pending=0
-      if [ -f "$tasks_file" ]; then
-        total=$(grep -c '^- \[' "$tasks_file" 2>/dev/null || echo 0)
-        done=$(grep -c '^- \[x\]' "$tasks_file" 2>/dev/null || echo 0)
-        pending=$((total - done))
-        echo "Tasks: $done/$total done, $pending pending"
-      else
-        echo "Tasks: tasks.md MISSING"
-      fi
-      echo ""
-      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."
-      elif [ "$tdd_mode" = "null" ] || [ -z "$tdd_mode" ]; then
-        echo "Recovery action: TDD mode not selected. AskUserQuestion for tdd/direct."
-      elif [ ! -f "$tasks_file" ]; then
-        echo "Recovery action: tasks.md missing. Verify change directory integrity."
-      elif [ "$pending" -gt 0 ]; then
-        echo "Recovery action: Read tasks.md and continue from first unchecked task."
-      else
-        echo "Recovery action: All tasks done. Run guard to transition to verify."
-      fi
-      ;;
-    verify)
-      echo "Verification:"
-      _field_status "verify_result" "$verify_result"
-      _field_status "verify_mode" "$verify_mode"
-      _field_status "verification_report" "$verification_report" "$verification_report"
-      _field_status "branch_status" "$branch_status"
-      _field_status "impl_hash" "$impl_hash"
-      echo ""
-      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."
-      elif [ "$verify_result" = "fail" ]; then
-        echo "Recovery action: Verification failed, rolled back to build. Resume from /comate-build."
-      else
-        echo "Recovery action: Verification not started. Run scale assessment then verify."
-      fi
-      ;;
-    archive)
-      echo "Archive:"
-      _field_status "verify_result" "$verify_result"
-      _field_status "archived" "$(yaml_get "$yaml" archived)"
-      echo ""
-      echo "Recovery action: Run /comate-archive to complete archiving."
-      ;;
-    *)
-      die "$COMATE_USAGE" "ERROR: unknown phase '$phase'"
-      ;;
-  esac
-  echo ""
-  echo "=== End Recovery Context ==="
-}
-
-# --- scale (assess verify_mode, base-ref annotation) ---
-
-state_scale() {
-  local name="$1"
-  validate_change_name "$name"
-  local dir yaml
-  dir=$(comate_change_dir "$name")
-  yaml="$dir/.comate.yaml"
-  [ -f "$yaml" ] || die "$COMATE_CORRUPT" "ERROR: .comate.yaml not found at $yaml"
-
-  local tasks_file="$dir/tasks.md" task_count=0
-  [ -f "$tasks_file" ] && task_count=$(grep -c '^- \[' "$tasks_file" 2>/dev/null || echo 0)
-
-  local delta_spec_count=0
-  if [ -d "$dir/specs" ]; then
-    delta_spec_count=$(find "$dir/specs" -name spec.md -type f 2>/dev/null | wc -l | tr -d ' ')
-  fi
-
-  # Changed files: plan base-ref > yaml base_ref > worktree diff. Annotate source.
-  local changed_files=0 basis="worktree-diff" base_ref=""
-  if git rev-parse --git-dir >/dev/null 2>&1; then
-    local plan_file
-    plan_file=$(yaml_get "$yaml" plan)
-    if [ -n "$plan_file" ] && [ "$plan_file" != "null" ] && [ -f "$plan_file" ]; then
-      base_ref=$(grep '^base-ref:' "$plan_file" 2>/dev/null | head -1 | sed 's/^base-ref:[[:space:]]*//')
-      [ -n "$base_ref" ] && [ "$base_ref" != "null" ] && basis="plan base-ref"
-    fi
-    if [ -z "$base_ref" ] || [ "$base_ref" = "null" ]; then
-      base_ref=$(yaml_get "$yaml" base_ref)
-      [ -n "$base_ref" ] && [ "$base_ref" != "null" ] && basis="state base_ref"
-    fi
-    if [ -n "$base_ref" ] && [ "$base_ref" != "null" ] && git rev-parse --verify "$base_ref" >/dev/null 2>&1; then
-      changed_files=$(git diff --name-only "$base_ref"...HEAD 2>/dev/null | wc -l | tr -d ' ')
-    else
-      changed_files=$(git diff --name-only HEAD 2>/dev/null | wc -l | tr -d ' ')
-      basis="worktree-diff"
-    fi
-  fi
-
-  local result="light"
-  if [ "$task_count" -gt 3 ] || [ "$delta_spec_count" -gt 1 ] || [ "$changed_files" -gt 4 ]; then
-    result="full"
-  fi
-
-  {
-    echo "=== Scale Assessment: $name ==="
-    echo "  Tasks: $task_count (threshold: 3)"
-    echo "  Delta specs: $delta_spec_count capabilities (threshold: 1)"
-    echo "  Changed files: $changed_files (threshold: 4) [basis: $basis]"
-    echo "  -> Result: $result"
-  } >&2
-
-  yaml_set "$yaml" verify_mode "$result"
-  log_pass "[SCALE] verify_mode=$result"
-}
-
-# =====================================================================
-# guard — phase EXIT evidence checks (table in IMPLEMENTATION.md §4.3)
-# =====================================================================
-
-GUARD_BLOCK=0
-declare -a GUARD_RESULTS=()  # "name|status"
-
-# _guard_check <desc> <command...> — run command; capture output; record result.
-# Always returns 0 so a recorded FAIL never trips the caller's set -e.
-_guard_check() {
-  local desc="$1"; shift
-  local output rc
-  if output=$("$@" 2>&1); then rc=0; else rc=1; fi
-  if [ "$rc" -eq 0 ]; then
-    GUARD_RESULTS+=("$desc|pass")
-    if [ "$GUARD_JSON" -eq 0 ]; then log_pass "  [PASS] $desc"; fi
-  else
-    GUARD_RESULTS+=("$desc|fail")
-    GUARD_BLOCK=1
-    if [ "$GUARD_JSON" -eq 0 ]; then
-      log_fail "  [FAIL] $desc"
-      if [ -n "$output" ]; then while IFS= read -r line; do log_fail "    $line"; done <<< "$output"; fi
-    fi
-  fi
-  return 0
-}
-
-# --- evidence predicates (use $G_DIR / $G_YAML / $G_CHANGE set by guard()) ---
-
-_g_tasks_all_done() {
-  local tasks="$G_DIR/tasks.md"
-  [ -f "$tasks" ] || { echo "tasks.md missing at $tasks"; return 1; }
-  grep -q '^- \[x\]' "$tasks" || { echo "tasks.md has no completed tasks"; return 1; }
-  if grep -q '^- \[ \]' "$tasks"; then
-    echo "Unfinished tasks:"; grep -n '^- \[ \]' "$tasks" || true; return 1
-  fi
-  return 0
-}
-_g_tasks_has_any() {
-  local tasks="$G_DIR/tasks.md"
-  [ -f "$tasks" ] && grep -q '^- \[' "$tasks"
-}
-
-# Resolve a project command: change yaml first, then repo-root config files.
-_g_project_command() {
-  local field="$1" value
-  value=$(yaml_get "$G_YAML" "$field")
-  if [ -n "$value" ] && [ "$value" != "null" ]; then echo "$value"; return 0; fi
-  local cfg
-  for cfg in ".comate.yaml" "comate.yaml" ".comate.yml" "comate.yml"; do
-    if [ -f "$cfg" ]; then
-      value=$(yaml_get "$cfg" "$field")
-      if [ -n "$value" ] && [ "$value" != "null" ]; then echo "$value"; return 0; fi
-    fi
-  done
-}
-
-_g_is_windows_bash() {
-  case "$(uname -s 2>/dev/null || true)" in
-    MINGW*|MSYS*|CYGWIN*) return 0 ;;
-    *) return 1 ;;
-  esac
-}
-
-_g_run_cmd() { echo "+ $1" >&2; bash -lc "$1"; }
-
-_g_build_passes() {
-  [ "${COMATE_SKIP_BUILD:-0}" = "1" ] && return 0
-  local cmd; cmd=$(_g_project_command build_command)
-  if [ -n "$cmd" ]; then _g_run_cmd "$cmd"; return $?; fi
-  if [ -f package.json ] && grep -q '"build"' package.json; then npm run build; return $?; fi
-  if [ -f pom.xml ]; then
-    if [ -x ./mvnw ]; then ./mvnw compile -q
-    elif _g_is_windows_bash && command -v mvn.cmd >/dev/null 2>&1; then mvn.cmd compile -q
-    else mvn compile -q; fi
-    return $?
-  fi
-  if [ -f Cargo.toml ]; then cargo build; return $?; fi
-  echo "no build_command configured and no known build tool detected"
-  echo "Next: set build_command in .comate.yaml, or skip with COMATE_SKIP_BUILD=1 (not recommended)."
-  return 1
-}
-
-_g_verify_passes() {
-  [ "${COMATE_SKIP_BUILD:-0}" = "1" ] && return 0
-  local cmd; cmd=$(_g_project_command verify_command)
-  if [ -n "$cmd" ]; then _g_run_cmd "$cmd"; return $?; fi
-  _g_build_passes
-}
-
-_g_isolation_selected() {
-  local v; v=$(yaml_get "$G_YAML" isolation)
-  case "$v" in branch|worktree) return 0 ;; esac
-  echo "isolation must be branch or worktree, got '${v:-null}'"
-  echo "Next: comate.sh state $G_CHANGE set isolation <branch|worktree>"
-  return 1
-}
-_g_build_mode_selected() {
-  local v; v=$(yaml_get "$G_YAML" build_mode)
-  case "$v" in subagent-driven-development|executing-plans|direct) return 0 ;; esac
-  echo "build_mode must be selected, got '${v:-null}'"
-  return 1
-}
-_g_build_mode_allowed() {
-  local workflow build_mode direct_override
-  workflow=$(yaml_get "$G_YAML" workflow)
-  build_mode=$(yaml_get "$G_YAML" build_mode)
-  direct_override=$(yaml_get "$G_YAML" direct_override)
-  [ "$build_mode" != "direct" ] && return 0
-  case "$workflow" in fix) return 0 ;; esac
-  [ "$direct_override" = "true" ] && return 0
-  echo "build_mode=direct only allowed for fix unless direct_override=true"
-  return 1
-}
-_g_tdd_mode_selected() {
-  local v; v=$(yaml_get "$G_YAML" tdd_mode)
-  case "$v" in tdd|direct) return 0 ;; esac
-  echo "tdd_mode must be tdd or direct, got '${v:-null}'"
-  echo "Next: comate.sh state $G_CHANGE set tdd_mode <tdd|direct>"
-  return 1
-}
-_g_verification_report_exists() {
-  local v; v=$(yaml_get "$G_YAML" verification_report)
-  [ -n "$v" ] && [ "$v" != "null" ] && [ -f "$v" ]
-}
-_g_branch_status_handled() {
-  [ "$(yaml_get "$G_YAML" branch_status)" = "handled" ]
-}
-_g_archived_is_true() {
-  [ "$(yaml_get "$G_YAML" archived)" = "true" ]
-}
-
-# source-tracking drift: knowledge-base files unchanged since they were pinned.
-# conversation sources (no manifest) pass trivially.
-_g_sources_not_drifted() {
-  local kind; kind=$(yaml_get "$G_YAML" source_kind)
-  [ "$kind" = "file" ] || return 0
-  local manifest; manifest=$(yaml_get "$G_YAML" source_manifest)
-  if [ -z "$manifest" ] || [ "$manifest" = "null" ]; then
-    echo "source_kind=file but source_manifest is null"; return 1
-  fi
-  local out rc
-  out=$(sources_drift "$manifest"); rc=$?
-  if [ "$rc" -ne 0 ]; then
-    [ -n "$out" ] && echo "$out"
-    echo "Next: review the knowledge-base change; rerun comate.sh sources $G_CHANGE track <file> if intended."
-    return 1
-  fi
-  return 0
-}
-
-# Handoff source set (design phase) — proposal/design/tasks + delta specs.
-_g_handoff_sources() {
-  printf '%s\n' "$G_DIR/proposal.md" "$G_DIR/design.md" "$G_DIR/tasks.md"
-  [ -d "$G_DIR/specs" ] && find "$G_DIR/specs" -path '*/spec.md' -type f 2>/dev/null | sort
-}
-
-_g_design_handoff_valid() {
-  local context recorded actual md
-  context=$(yaml_get "$G_YAML" handoff_context)
-  recorded=$(yaml_get "$G_YAML" handoff_hash)
-  if [ -z "$context" ] || [ "$context" = "null" ]; then
-    echo "handoff_context missing; run: comate.sh handoff $G_CHANGE design --write"; return 1
-  fi
-  [ -s "$context" ] || { echo "handoff_context not a non-empty file: $context"; return 1; }
-  if [[ ! "$recorded" =~ ^[a-f0-9]{64}$ ]]; then
-    echo "handoff_hash missing or invalid: ${recorded:-null}"; return 1
-  fi
-  # Recompute over current sources; flag drift.
-  local files=()
-  while IFS= read -r f; do files+=("$f"); done < <(_g_handoff_sources)
-  actual=$(hash_files_manifest "${files[@]}")
-  if [ "$actual" != "$recorded" ]; then
-    echo "OpenSpec artifacts changed after handoff was generated."
-    echo "  recorded: $recorded"
-    echo "  actual:   $actual"
-    echo "Next: rerun comate.sh handoff $G_CHANGE design --write"
-    return 1
-  fi
-  md="${context%.json}.md"
-  [ -s "$md" ] || { echo "design handoff markdown missing/empty: $md"; return 1; }
-  return 0
-}
-
-_g_design_handoff_traceable() {
-  local context md
-  context=$(yaml_get "$G_YAML" handoff_context)
-  [ -n "$context" ] && [ "$context" != "null" ] || { echo "handoff_context missing"; return 1; }
-  md="${context%.json}.md"
-  [ -s "$md" ] || { echo "handoff markdown missing/empty: $md"; return 1; }
-  grep -q '^Generated-by: comate$' "$md" || { echo "missing Generated-by marker"; return 1; }
-  grep -Eq '^- Mode: (compact|full)$' "$md" || { echo "missing Mode marker"; return 1; }
-  local f rc=0
-  while IFS= read -r f; do
-    [ -f "$f" ] || continue
-    grep -q "^- Source: $f$" "$md" || { echo "missing source reference: $f"; rc=1; }
-    grep -q "^- SHA256: $(hash_file "$f")$" "$md" || { echo "missing current sha256 for: $f"; rc=1; }
-  done < <(_g_handoff_sources)
-  return $rc
-}
-
-# Design Doc frontmatter helper.
-_g_frontmatter_has() {
-  local file="$1" field="$2" expected="$3"
-  awk '
-    { line=$0; sub(/^\357\273\277/, "", line) }
-    !in_fm && line == "---" { in_fm=1; next }
-    in_fm && line == "---" { exit }
-    in_fm { print line }
-  ' "$file" | grep -Eq "^${field}: ['\"]?${expected}['\"]?[[:space:]]*$"
-}
-_g_design_doc_links_change() {
-  local dd; dd=$(yaml_get "$G_YAML" design_doc)
-  [ -n "$dd" ] && [ "$dd" != "null" ] && [ -s "$dd" ] || { echo "design_doc must point to an existing Design Doc"; return 1; }
-  _g_frontmatter_has "$dd" comate_change "$G_CHANGE" || { echo "Design Doc frontmatter missing comate_change: $G_CHANGE"; return 1; }
-}
-_g_design_doc_role() {
-  local dd; dd=$(yaml_get "$G_YAML" design_doc)
-  [ -n "$dd" ] && [ "$dd" != "null" ] && [ -s "$dd" ] && _g_frontmatter_has "$dd" role technical-design
-}
-_g_design_doc_canonical() {
-  local dd; dd=$(yaml_get "$G_YAML" design_doc)
-  [ -n "$dd" ] && [ "$dd" != "null" ] && [ -s "$dd" ] && _g_frontmatter_has "$dd" canonical_spec openspec
-}
-
-# impl-context drift: verify entry plan+tasks match build exit.
-_g_impl_context_written() {
-  local ctx hash
-  ctx=$(yaml_get "$G_YAML" impl_context)
-  hash=$(yaml_get "$G_YAML" impl_hash)
-  if [ -z "$ctx" ] || [ "$ctx" = "null" ] || [ ! -f "$ctx" ]; then
-    echo "impl_context not written; run: comate.sh handoff $G_CHANGE build --write"
-    return 1
-  fi
-  if [[ ! "$hash" =~ ^[a-f0-9]{64}$ ]]; then
-    echo "impl_hash missing or invalid: ${hash:-null}"; return 1
-  fi
-  return 0
-}
-_g_impl_hash_matches() {
-  local recorded plan actual
-  recorded=$(yaml_get "$G_YAML" impl_hash)
-  if [ -z "$recorded" ] || [ "$recorded" = "null" ]; then
-    echo "impl_hash missing; run: comate.sh handoff $G_CHANGE build --write at end of build"; return 1
-  fi
-  plan=$(yaml_get "$G_YAML" plan)
-  local files=("$G_DIR/tasks.md")
-  [ -n "$plan" ] && [ "$plan" != "null" ] && [ -f "$plan" ] && files=("$plan" "$G_DIR/tasks.md")
-  actual=$(hash_files_manifest "${files[@]}")
-  if [ "$actual" != "$recorded" ]; then
-    echo "plan/tasks changed between build exit and verify entry."
-    echo "  recorded: $recorded"
-    echo "  actual:   $actual"
-    echo "Next: investigate the edit; rerun build handoff only if the change is intended."
-    return 1
-  fi
-  return 0
-}
-
-guard() {
-  local name="$1" phase="${2:-}"
-  validate_change_name "$name"
-  validate_enum phase "$phase"
-  [ -n "$phase" ] || die "$COMATE_USAGE" "Usage: comate.sh guard <name> <phase> [--apply] [--json]"
-
-  G_CHANGE="$name"
-  G_DIR=$(comate_change_dir "$name")
-  G_YAML="$G_DIR/.comate.yaml"
-
-  # preflight: directory + state file + flat-yaml schema.
-  [ -d "$G_DIR" ] || die "$COMATE_CORRUPT" "FATAL: change directory not found: $G_DIR"
-  [ -f "$G_YAML" ] || die "$COMATE_CORRUPT" "FATAL: .comate.yaml not found in $G_DIR"
-  validate_flat_yaml "$G_YAML"
-
-  [ "$GUARD_JSON" -eq 0 ] && log_info "=== Guard: $phase ==="
-
-  case "$phase" in
-    open)
-      _guard_check "proposal.md non-empty" file_nonempty "$G_DIR/proposal.md"
-      _guard_check "design.md non-empty" file_nonempty "$G_DIR/design.md"
-      _guard_check "tasks.md non-empty" file_nonempty "$G_DIR/tasks.md"
-      _guard_check "tasks.md has at least one task" _g_tasks_has_any
-      ;;
-    design)
-      _guard_check "proposal.md non-empty" file_nonempty "$G_DIR/proposal.md"
-      _guard_check "design.md non-empty" file_nonempty "$G_DIR/design.md"
-      _guard_check "tasks.md non-empty" file_nonempty "$G_DIR/tasks.md"
-      _guard_check "design handoff context valid (hash not drifted)" _g_design_handoff_valid
-      _guard_check "design handoff markdown traceable" _g_design_handoff_traceable
-      _guard_check "source files not drifted" _g_sources_not_drifted
-      local dd; dd=$(yaml_get "$G_YAML" design_doc)
-      if [ -n "$dd" ] && [ "$dd" != "null" ]; then
-        _guard_check "Design Doc exists ($dd)" file_nonempty "$dd"
-        _guard_check "Design Doc frontmatter links change" _g_design_doc_links_change
-        _guard_check "Design Doc declares technical-design role" _g_design_doc_role
-        _guard_check "Design Doc declares canonical_spec: openspec" _g_design_doc_canonical
-      else
-        # Design Doc is required for full workflow moving to build
-        _guard_check "Design Doc recorded (design_doc field)" false
-      fi
-      ;;
-    build)
-      _guard_check "isolation selected" _g_isolation_selected
-      _guard_check "build_mode selected" _g_build_mode_selected
-      _guard_check "build_mode allowed for workflow" _g_build_mode_allowed
-      _guard_check "tdd_mode selected" _g_tdd_mode_selected
-      _guard_check "tasks.md all tasks checked" _g_tasks_all_done
-      _guard_check "proposal.md non-empty" file_nonempty "$G_DIR/proposal.md"
-      _guard_check "impl-context written" _g_impl_context_written
-      _guard_check "source files not drifted" _g_sources_not_drifted
-      _guard_check "build passes" _g_build_passes
-      ;;
-    verify)
-      _guard_check "tasks.md all tasks checked" _g_tasks_all_done
-      _guard_check "verify command passes" _g_verify_passes
-      _guard_check "verification_report exists" _g_verification_report_exists
-      _guard_check "branch_status=handled" _g_branch_status_handled
-      _guard_check "impl_hash matches current plan+tasks" _g_impl_hash_matches
-      ;;
-    archive)
-      _guard_check "archived is true" _g_archived_is_true
-      _guard_check "proposal.md non-empty" file_nonempty "$G_DIR/proposal.md"
-      _guard_check "tasks.md all tasks checked" _g_tasks_all_done
-      ;;
-  esac
-
-  if [ "$GUARD_JSON" -eq 1 ]; then
-    local out='{"phase":"'"$phase"'","checks":['
-    local first=1 r cname cstatus
-    for r in "${GUARD_RESULTS[@]}"; do
-      cname="${r%|*}"; cstatus="${r#*|}"
-      [ "$first" -eq 0 ] && out+=','
-      first=0
-      out+='{"name":"'"$(json_escape "$cname")"'","status":"'"$cstatus"'"}'
-    done
-    out+='],"block":'"$([ "$GUARD_BLOCK" -eq 1 ] && echo true || echo false)"
-    out+=',"applied":false}'
-    printf '%s\n' "$out"
-    if [ "$GUARD_BLOCK" -eq 1 ]; then exit "$COMATE_BLOCK"; fi
-    # In JSON mode, still apply if requested (silent).
-    if [ "$GUARD_APPLY" -eq 1 ]; then _guard_apply "$phase" >/dev/null 2>&1 || true; fi
-    exit "$COMATE_OK"
-  fi
-
-  echo "" >&2
-  if [ "$GUARD_BLOCK" -eq 1 ]; then
-    log_fail "BLOCKED — fix failing checks before proceeding to next phase"
-    exit "$COMATE_BLOCK"
-  fi
-  log_pass "ALL CHECKS PASSED — ready for next phase"
-  if [ "$GUARD_APPLY" -eq 1 ]; then
-    _guard_apply "$phase"
-  fi
-  exit "$COMATE_OK"
-}
-
-# _guard_apply <phase> — delegate to the matching transition.
-_guard_apply() {
-  case "$1" in
-    open)   state_transition "$G_CHANGE" open-complete ;;
-    design) state_transition "$G_CHANGE" design-complete ;;
-    build)  state_transition "$G_CHANGE" build-complete ;;
-    verify) state_transition "$G_CHANGE" verify-pass ;;
-    archive) : ;;  # archive completion handled by the archive command
-  esac
-  local np; np=$(yaml_get "$G_YAML" phase)
-  log_pass "  [APPLY] .comate.yaml updated: phase=$np"
-}
-
-# =====================================================================
-# handoff — machine-owned context packages between phases
-# =====================================================================
-
-# Shared: emit a traceable markdown excerpt for one file.
-_handoff_excerpt() {
-  local file="$1" max_lines="$2" mode="$3" total
-  total=$(wc -l < "$file" | tr -d ' ')
-  echo "## $file"
-  echo ""
-  echo "- Source: $file"
-  echo "- Lines: 1-$total"
-  echo "- SHA256: $(hash_file "$file")"
-  echo ""
-  if [ "$mode" = "full" ] || [ "$total" -le "$max_lines" ]; then
-    echo '```md'; cat "$file"; echo '```'
-  else
-    echo "[TRUNCATED]"; echo ""
-    echo '```md'; sed -n "1,${max_lines}p" "$file"; echo '```'
-    echo ""; echo "Full source: $file"
-  fi
-  echo ""
-}
-
-handoff() {
-  local name="$1" phase="${2:-}" mode="${3:-}" full="${4:-}"
-  validate_change_name "$name"
-  local dir yaml
-  dir=$(comate_change_dir "$name")
-  yaml="$dir/.comate.yaml"
-  [ -d "$dir" ] || die "$COMATE_CORRUPT" "ERROR: change directory not found: $dir"
-  [ -f "$yaml" ] || die "$COMATE_CORRUPT" "ERROR: .comate.yaml not found at $yaml"
-  [ "$mode" = "--write" ] || die "$COMATE_USAGE" "Usage: comate.sh handoff <name> <design|build> --write [--full]"
-
-  case "$phase" in
-    design) _handoff_design "$name" "$dir" "$yaml" "$full" ;;
-    build)  _handoff_build  "$name" "$dir" "$yaml" ;;
-    *) die "$COMATE_USAGE" "Usage: comate.sh handoff <name> <design|build> --write [--full]" ;;
-  esac
-}
-
-_handoff_design() {
-  local name="$1" dir="$2" yaml="$3" full="$4"
-  local hmode="compact"
-  case "$full" in
-    "") hmode="compact" ;;
-    --full) hmode="full" ;;
-    *) die "$COMATE_USAGE" "Usage: comate.sh handoff <name> design --write [--full]" ;;
-  esac
-  [ "$(yaml_get "$yaml" phase)" = "design" ] || die "$COMATE_BLOCK" "ERROR: design handoff requires phase: design"
-
-  local f
-  for f in proposal.md design.md tasks.md; do
-    [ -s "$dir/$f" ] || die "$COMATE_BLOCK" "ERROR: required artifact missing/empty: $dir/$f"
-  done
-
-  # Source set: proposal/design/tasks + delta specs.
-  local files=("$dir/proposal.md" "$dir/design.md" "$dir/tasks.md")
-  if [ -d "$dir/specs" ]; then
-    while IFS= read -r s; do files+=("$s"); done < <(find "$dir/specs" -path '*/spec.md' -type f 2>/dev/null | sort)
-  fi
-
-  local hdir="$dir/.comate/handoff"
-  mkdir -p "$hdir"
-  local cjson="$hdir/design-context.json" cmd="$hdir/design-context.md"
-  local chash; chash=$(hash_files_manifest "${files[@]}")
-
-  # markdown
-  {
-    echo "# comate Design Handoff"
-    echo ""
-    echo "- Change: $name"
-    echo "- Phase: design"
-    echo "- Mode: $hmode"
-    echo "- Context hash: $chash"
-    echo ""
-    echo "Generated-by: comate"
-    echo ""
-    echo "OpenSpec remains the canonical capability spec. This handoff is a deterministic, source-traceable context pack, not an agent-authored summary."
-    echo ""
-    for f in "${files[@]}"; do
-      [ -f "$f" ] || continue
-      _handoff_excerpt "$f" 80 "$hmode"
-    done
-  } > "$cmd"
-
-  # json
-  {
-    echo "{"
-    echo "  \"change\": \"$(json_escape "$name")\","
-    echo "  \"phase\": \"design\","
-    echo "  \"mode\": \"$hmode\","
-    echo "  \"canonical_spec\": \"openspec\","
-    echo "  \"generated_by\": \"comate\","
-    echo "  \"context_hash\": \"$chash\","
-    echo "  \"files\": ["
-    local first=1
-    for f in "${files[@]}"; do
-      [ -f "$f" ] || continue
-      [ "$first" -eq 0 ] && echo ","
-      first=0
-      printf '    { "path": "%s", "sha256": "%s" }' "$(json_escape "$f")" "$(hash_file "$f")"
-    done
-    echo ""
-    echo "  ]"
-    echo "}"
-  } > "$cjson"
-
-  yaml_set "$yaml" handoff_context "$cjson"
-  yaml_set "$yaml" handoff_hash "$chash"
-  log_pass "[HANDOFF] wrote $cjson"
-  log_pass "[HANDOFF] wrote $cmd"
-  log_pass "[HANDOFF] handoff_hash=$chash"
-}
-
-# build->verify handoff: hash plan + tasks.
-_handoff_build() {
-  local name="$1" dir="$2" yaml="$3"
-  [ "$(yaml_get "$yaml" phase)" = "build" ] || die "$COMATE_BLOCK" "ERROR: build handoff requires phase: build"
-  [ -s "$dir/tasks.md" ] || die "$COMATE_BLOCK" "ERROR: tasks.md missing/empty: $dir/tasks.md"
-
-  local plan; plan=$(yaml_get "$yaml" plan)
-  local files=("$dir/tasks.md")
-  if [ -n "$plan" ] && [ "$plan" != "null" ] && [ -f "$plan" ]; then
-    files=("$plan" "$dir/tasks.md")
-  fi
-
-  local hdir="$dir/.comate/handoff"
-  mkdir -p "$hdir"
-  local cjson="$hdir/impl-context.json"
-  local chash; chash=$(hash_files_manifest "${files[@]}")
-
-  {
-    echo "{"
-    echo "  \"change\": \"$(json_escape "$name")\","
-    echo "  \"phase\": \"build\","
-    echo "  \"generated_by\": \"comate\","
-    echo "  \"impl_hash\": \"$chash\","
-    echo "  \"files\": ["
-    local first=1 f
-    for f in "${files[@]}"; do
-      [ -f "$f" ] || continue
-      [ "$first" -eq 0 ] && echo ","
-      first=0
-      printf '    { "path": "%s", "sha256": "%s" }' "$(json_escape "$f")" "$(hash_file "$f")"
-    done
-    echo ""
-    echo "  ]"
-    echo "}"
-  } > "$cjson"
-
-  yaml_set "$yaml" impl_context "$cjson"
-  yaml_set "$yaml" impl_hash "$chash"
-  log_pass "[HANDOFF] wrote $cjson"
-  log_pass "[HANDOFF] impl_hash=$chash"
-}
-
-# =====================================================================
-# sources — knowledge-base provenance for a change
-# =====================================================================
-
-# _sources_pin_ref <yaml> — echo the commit ref to pin a tracked file to:
-# the change's base_ref, falling back to current HEAD, else "null".
-_sources_pin_ref() {
-  local yaml="$1" ref
-  ref=$(yaml_get "$yaml" base_ref)
-  if [ -z "$ref" ] || [ "$ref" = "null" ]; then
-    ref=$(git rev-parse --short HEAD 2>/dev/null || echo "null")
-  elif git rev-parse --git-dir >/dev/null 2>&1; then
-    ref=$(git rev-parse --short "$ref" 2>/dev/null || echo "$ref")
-  fi
-  echo "$ref"
-}
-
-# sources <name> track <file...> [--note <text>] — record knowledge-base files
-# as the source of this change. Out-of-range files are skipped (caller stays on
-# conversation). Re-tracking a path replaces its prior record.
-sources_track() {
-  local name="$1"; shift
-  validate_change_name "$name"
-  local yaml; yaml=$(require_yaml "$name")
-  local manifest; manifest=$(sources_manifest_for "$name")
-
-  local note="" files=()
-  while [ $# -gt 0 ]; do
-    case "$1" in
-      --note) note="${2:-}"; shift 2 || shift ;;
-      *) files+=("$1"); shift ;;
-    esac
-  done
-  [ "${#files[@]}" -gt 0 ] || die "$COMATE_USAGE" "Usage: comate.sh sources <name> track <file...> [--note <text>]"
-
-  local ref; ref=$(_sources_pin_ref "$yaml")
-  mkdir -p "$(dirname "$manifest")"
-  [ -f "$manifest" ] || : > "$manifest"
-
-  local tracked=0 skipped=0 f rel
-  for f in "${files[@]}"; do
-    if rel=$(validate_kb_path "$f"); then
-      _sources_remove_path "$manifest" "$rel"
-      {
-        [ -s "$manifest" ] && printf -- '---\n'
-        printf 'path:%s\n' "$rel"
-        printf 'sha256:%s\n' "$(hash_file "$rel")"
-        printf 'ref:%s\n' "$ref"
-        [ -n "$note" ] && printf 'note:%s\n' "$note"
-      } >> "$manifest"
-      log_pass "[SOURCES] tracked $rel"
-      tracked=$((tracked + 1))
-    else
-      log_warn "[SOURCES] not in $(comate_kb_root)/ or unreadable, skipped: $f"
-      skipped=$((skipped + 1))
-    fi
-  done
-
-  if [ "$tracked" -gt 0 ]; then
-    yaml_set "$yaml" source_kind file
-    yaml_set "$yaml" source_manifest "$manifest"
-    log_pass "[SOURCES] source_kind=file, source_manifest=$manifest"
-  else
-    log_warn "[SOURCES] no file tracked; source_kind stays conversation"
-  fi
-  [ "$skipped" -eq 0 ] || return "$COMATE_OK"
-}
-
-# _sources_remove_path <manifest> <path> — drop the record block for one path.
-_sources_remove_path() {
-  local manifest="$1" target="$2" tmp
-  [ -f "$manifest" ] || return 0
-  tmp=$(mktemp "${TMPDIR:-/tmp}/comate.XXXXXX") || die "$COMATE_ENV" "ERROR: mktemp failed"
-  awk -v target="$target" '
-    function flush() {
-      if (block != "" && keep) printf "%s", block
-      block=""; keep=1
-    }
-    BEGIN { keep=1 }
-    /^---$/ { flush(); next }
-    /^path:/ { if ($0 == "path:" target) keep=0 }
-    { block = block $0 "\n" }
-    END { flush() }
-  ' "$manifest" > "$tmp"
-  # Collapse any leading blank lines, then normalise record separators.
-  awk 'NF || NR>1 {print}' "$tmp" > "$manifest"
-  rm -f "$tmp"
-}
-
-# sources <name> check — drift check; conversation skips. Mirrors guard codes.
-sources_check() {
-  local name="$1"
-  validate_change_name "$name"
-  local yaml; yaml=$(require_yaml "$name")
-  local kind; kind=$(yaml_get "$yaml" source_kind)
-  if [ "$kind" != "file" ]; then
-    log_info "[SOURCES] source_kind=$kind — no source files to check"
-    exit "$COMATE_OK"
-  fi
-  local manifest; manifest=$(yaml_get "$yaml" source_manifest)
-  if [ -z "$manifest" ] || [ "$manifest" = "null" ]; then
-    die "$COMATE_CORRUPT" "ERROR: source_kind=file but source_manifest is null"
-  fi
-  local out rc=0
-  out=$(sources_drift "$manifest") || rc=$?
-  [ -n "$out" ] && printf '%s\n' "$out" >&2
-  if [ "$rc" -eq 0 ]; then
-    log_pass "[SOURCES] no drift ($manifest)"
-  fi
-  exit "$rc"
-}
-
-# sources <name> list — print the manifest.
-sources_list() {
-  local name="$1"
-  validate_change_name "$name"
-  local manifest; manifest=$(sources_manifest_for "$name")
-  if [ -f "$manifest" ]; then cat "$manifest"; else echo "no source manifest for $name"; fi
-}
-
-# sources find <file> — reverse lookup: which changes reference this file.
-sources_find() {
-  local target="$1"
-  [ -n "$target" ] || die "$COMATE_USAGE" "Usage: comate.sh sources find <file>"
-  local rel="$target"
-  if r=$(validate_kb_path "$target" 2>/dev/null); then rel="$r"; fi
-  local any=0 m chg
-  while IFS= read -r m; do
-    if grep -q "^path:$rel$" "$m" 2>/dev/null; then
-      chg=$(basename "$(dirname "$(dirname "$m")")")
-      echo "$chg ($m)"
-      any=1
-    fi
-  done < <(find openspec/changes -path '*/.comate/sources.manifest' -type f 2>/dev/null | sort)
-  [ "$any" -eq 0 ] && echo "no change references: $rel"
-  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
-# =====================================================================
-
-# 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"
-}
-
-# gate <prd> review — create or refresh gate.yaml next to the PRD and pin the
-# current PRD hash. Existing passed gates are re-opened to `reviewing` only when
-# the PRD changed (hash drift); otherwise the review report path is (re)emitted
-# so the skill knows where to write its human-readable audit. The skill does the
-# semantic scoring and writes score/blocking_open/gate_status via `gate set`.
-gate_review() {
-  local prd; prd=$(require_prd "$1")
-  local gate report cur_hash
-  gate=$(gate_path_for "$prd")
-  report=$(gate_report_for "$prd")
-  cur_hash=$(hash_file "$prd")
-
-  if [ ! -f "$gate" ]; then
-    cat > "$gate" <<EOF
-# comate PRD gate — flat key:value only, no nesting
-schema_version: $GATE_SCHEMA_VERSION
-prd_path: $prd
-prd_hash: $cur_hash
-gate_status: reviewing
-score: null
-blocking_open: null
-review_report: $report
-spawned_changes: null
-changes_map: null
-gated_at: null
-created_at: $(today)
-EOF
-    log_pass "[GATE] created $gate (status=reviewing)"
-  else
-    local old_hash old_status
-    old_hash=$(yaml_get "$gate" prd_hash)
-    old_status=$(yaml_get "$gate" gate_status)
-    gate_yaml_set "$gate" prd_path "$prd"
-    gate_yaml_set "$gate" review_report "$report"
-    if [ "$old_hash" != "$cur_hash" ]; then
-      gate_yaml_set "$gate" prd_hash "$cur_hash"
-      gate_yaml_set "$gate" gate_status reviewing
-      log_warn "[GATE] PRD changed since last review — status reset to reviewing (was $old_status)"
-    else
-      log_info "[GATE] $gate (status=$old_status, unchanged PRD)"
-    fi
-  fi
-  echo "review_report: $report"
-}
-
-# gate <prd> set <field> <value> — write a gate field (score/blocking_open/
-# gate_status/…) with the same validation as gate_yaml_set.
-gate_set() {
-  local prd; prd=$(require_prd "$1")
-  local field="${2:-}" value="${3:-}"
-  [ -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() {
-  local prd; prd=$(require_prd "$1")
-  local tbd=0
-  [ "${2:-}" = "--tbd" ] && tbd=1
-  local gate; gate=$(gate_path_for "$prd")
-  [ -f "$gate" ] || die "$COMATE_CORRUPT" "ERROR: gate not found (run 'gate review' first): $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
-  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"
-  fi
-
-  gate_yaml_set "$gate" prd_hash "$(hash_file "$prd")"
-  if [ "$tbd" -eq 1 ]; then
-    gate_yaml_set "$gate" gate_status passed-with-tbd
-  else
-    gate_yaml_set "$gate" gate_status passed
-  fi
-  gate_yaml_set "$gate" gated_at "$(today)"
-  log_pass "[GATE] $(yaml_get "$gate" gate_status) — changes may now be spawned from $prd"
-}
-
-# gate <prd> spawned <change> — append a change name to spawned_changes
-# (comma-joined), recording which changes this PRD fanned out into.
-gate_spawned() {
-  local prd; prd=$(require_prd "$1")
-  local change="${2:-}"
-  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
-    gate_yaml_set "$gate" spawned_changes "$cur,$change"
-  fi
-  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() {
-  local gate="$1" prd="$2" recorded actual
-  recorded=$(yaml_get "$gate" prd_hash)
-  [ -f "$prd" ] || return 0
-  actual=$(hash_file "$prd")
-  [ "$recorded" != "$actual" ]
-}
-
-# gate <prd> status [--json] — print current gate status, computing stale on the
-# fly (hash drift). Does not mutate the file.
-gate_status() {
-  local prd="$1" json="${2:-}"
-  [ -n "$prd" ] || die "$COMATE_USAGE" "Usage: comate.sh gate <prd> status [--json]"
-  local gate; gate=$(gate_path_for "$prd")
-  if [ ! -f "$gate" ]; then
-    if [ "$json" = "--json" ]; then
-      printf '{"gate":"none","prd":"%s"}\n' "$(json_escape "$prd")"
-    else
-      echo "gate: none ($prd) — run 'gate review' to start"
-    fi
-    return "$COMATE_OK"
-  fi
-  local st score blocking; st=$(yaml_get "$gate" gate_status)
-  score=$(yaml_get "$gate" score); blocking=$(yaml_get "$gate" blocking_open)
-  if [ -f "$prd" ] && _gate_is_stale "$gate" "$prd"; then st="stale"; fi
-  if [ "$json" = "--json" ]; then
-    printf '{"gate":"%s","status":"%s","score":"%s","blocking_open":"%s","report":"%s"}\n' \
-      "$(json_escape "$gate")" "$(json_escape "$st")" "$(json_escape "$score")" \
-      "$(json_escape "$blocking")" "$(json_escape "$(yaml_get "$gate" review_report)")"
-  else
-    echo "gate: $st  score=$score  blocking_open=$blocking  ($gate)"
-  fi
-  return "$COMATE_OK"
-}
-
-# gate <prd> check — the precondition guard comate-open runs before spawning a
-# change. PASS (exit 0) requires: gate.yaml exists, status ∈ {passed,
-# passed-with-tbd}, and prd_hash matches the current PRD. Anything else BLOCKs.
-gate_check() {
-  local prd; prd=$(require_prd "$1")
-  local gate; gate=$(gate_path_for "$prd")
-  if [ ! -f "$gate" ]; then
-    die "$COMATE_BLOCK" "BLOCK: no gate for $prd — run /comate-gate to review the PRD before creating a change"
-  fi
-  local st; st=$(yaml_get "$gate" gate_status)
-  case "$st" in
-    passed|passed-with-tbd) ;;
-    *) die "$COMATE_BLOCK" "BLOCK: gate_status='$st' (not passed) — a change cannot be spawned until the PRD gate passes" ;;
-  esac
-  if _gate_is_stale "$gate" "$prd"; then
-    die "$COMATE_BLOCK" "BLOCK: PRD changed since it passed the gate (hash mismatch) — re-run /comate-gate to re-gate before spawning a change"
-  fi
-  log_pass "[GATE] check PASS ($st) — $prd"
-  return "$COMATE_OK"
-}
-
-# =====================================================================
-# archive
-# =====================================================================
-
-archive() {
-  local name="$1" dry="${2:-}"
-  validate_change_name "$name"
-  local dry_run=0
-  [ "$dry" = "--dry-run" ] && dry_run=1
-
-  local dir="openspec/changes/$name"
-  local yaml="$dir/.comate.yaml"
-  local today archive_name archive_dir
-  today=$(today)
-  archive_name="${today}-${name}"
-  archive_dir="openspec/changes/archive/${archive_name}"
-
-  [ -f "$yaml" ] || die "$COMATE_CORRUPT" "FATAL: .comate.yaml not found in $dir"
-  validate_flat_yaml "$yaml"
-
-  local phase verify_result archived design_doc plan
-  phase=$(yaml_get "$yaml" phase)
-  verify_result=$(yaml_get "$yaml" verify_result)
-  archived=$(yaml_get "$yaml" archived)
-  design_doc=$(yaml_get "$yaml" design_doc)
-  plan=$(yaml_get "$yaml" plan)
-
-  [ "$phase" = "archive" ] || die "$COMATE_BLOCK" "FATAL: phase is '$phase', expected 'archive'"
-  [ "$verify_result" = "pass" ] || die "$COMATE_BLOCK" "FATAL: verify_result is '$verify_result', expected 'pass'"
-  [ "$archived" != "true" ] || die "$COMATE_BLOCK" "FATAL: change already archived"
-  [ ! -d "$archive_dir" ] || die "$COMATE_BLOCK" "FATAL: archive target already exists: $archive_dir"
-
-  local steps_ok=0 steps_total=0
-  _step_ok()  { log_pass "  [OK] $1"; steps_ok=$((steps_ok+1)); steps_total=$((steps_total+1)); }
-  _step_dry() { log_warn "  [DRY-RUN] $1"; steps_ok=$((steps_ok+1)); steps_total=$((steps_total+1)); }
-  _step_fail(){ log_fail "  [FAIL] $1"; steps_total=$((steps_total+1)); }
-
-  log_info "=== comate Archive: $name ==="
-  _step_ok "Entry state verified (phase=archive, verify_result=pass)"
-
-  # OpenSpec owns delta-spec merge semantics. Do not copy change specs over
-  # main specs directly; delta specs may contain ADDED/MODIFIED sections rather
-  # than a complete canonical spec.
-  local has_delta_specs=0
-  if [ -d "$dir/specs" ] && find "$dir/specs" -path '*/spec.md' -type f -print -quit 2>/dev/null | grep -q .; then
-    has_delta_specs=1
-  fi
-
-  # Annotate frontmatter (design doc + plan), and rewrite any body references to
-  # the change's pre-archive OpenSpec path so they survive the move (class B).
-  # NOTE: design_doc/plan live under docs/superpowers and do NOT move with the
-  # change. Annotation runs AFTER openspec has moved the change, using the REAL
-  # archive name discovered from disk — comate must not guess the dir name, as a
-  # locally-computed date can skew vs openspec's across a UTC/local midnight.
-  local old_prefix="openspec/changes/$name/"
-  local new_prefix=""        # set to real archive path after the move
-  local ann_archive_name=""  # set to real archive name after the move
-  _annotate() {
-    local file="$1" extra="$2"
-    [ -f "$file" ] || return 0
-    if [ "$dry_run" -eq 1 ]; then _step_dry "Would annotate: $file"; return 0; fi
-    local tmp; tmp=$(mktemp)
-    if head -1 "$file" | grep -q '^---'; then
-      awk -v archive="$ann_archive_name" -v extra="$extra" \
-          -v oldp="$old_prefix" -v newp="$new_prefix" '
-        /^archived-with:/ { next }
-        NR==1 && /^---/ { print; next }
-        /^---/ && NR>1 && fm==0 { print "archived-with: " archive; if (extra != "") print extra; fm=1; print; next }
-        fm==1 { gsub(oldp, newp) } 1
-      ' "$file" > "$tmp"
-    else
-      {
-        echo "---"; echo "archived-with: $ann_archive_name"; [ -n "$extra" ] && echo "$extra"; echo "status: final"; echo "---"
-        sed "s#$old_prefix#$new_prefix#g" "$file"
-      } > "$tmp"
-    fi
-    mv "$tmp" "$file"
-    _step_ok "Annotated: $file"
-  }
-  # Dry-run previews annotation up front (real name not needed for the message).
-  if [ "$dry_run" -eq 1 ]; then
-    [ -n "$design_doc" ] && [ "$design_doc" != "null" ] && _annotate "$design_doc" "status: final"
-    [ -n "$plan" ] && [ "$plan" != "null" ] && _annotate "$plan" ""
-  fi
-
-  # Delegate spec updates and change movement to OpenSpec.
-  if [ "$dry_run" -eq 1 ]; then
-    if [ "$has_delta_specs" -eq 1 ]; then
-      _step_dry "Would run: openspec archive $name -y"
-    else
-      _step_dry "Would run: openspec archive $name -y --skip-specs"
-    fi
-  else
-    command -v openspec >/dev/null 2>&1 || die "$COMATE_ENV" "FATAL: openspec CLI not found; install OpenSpec before archiving"
-    if [ "$has_delta_specs" -eq 1 ]; then
-      openspec archive "$name" -y
-      _step_ok "OpenSpec archived change and updated main specs"
-    else
-      openspec archive "$name" -y --skip-specs
-      _step_ok "OpenSpec archived change (no delta specs)"
-    fi
-  fi
-
-  # Mark archived via transition. OpenSpec normally uses YYYY-MM-DD-<name>,
-  # but fall back to locating the moved state file if that ever changes.
-  if [ "$dry_run" -eq 1 ]; then
-    _step_dry "Would set archived: true"
-  else
-    local moved_archive_name="$archive_name"
-    if [ ! -f "$archive_dir/.comate.yaml" ]; then
-      local found
-      found=$(find "openspec/changes/archive" -maxdepth 2 -path "*/.comate.yaml" -type f 2>/dev/null | sed 's#^\./##' | grep "/${name}/.comate.yaml$\|-${name}/.comate.yaml$" | sort | tail -1 || true)
-      if [ -n "$found" ]; then
-        moved_archive_name=$(basename "$(dirname "$found")")
-        archive_dir=$(dirname "$found")
-      fi
-    fi
-    if [ -f "$archive_dir/.comate.yaml" ]; then
-      state_transition "$moved_archive_name" archived >/dev/null
-      _step_ok "archived: true"
-      # Now that the change has moved and the REAL archive name is known, annotate
-      # design doc + plan (they stay under docs/superpowers; openspec never moved
-      # them). Using the discovered name avoids any local-vs-openspec date skew.
-      ann_archive_name="$moved_archive_name"
-      new_prefix="$archive_dir/"
-      [ -n "$design_doc" ] && [ "$design_doc" != "null" ] && _annotate "$design_doc" "status: final"
-      [ -n "$plan" ] && [ "$plan" != "null" ] && _annotate "$plan" ""
-      # Rewrite self-pointers that moved with the change (class A): fields under
-      # the change's own .comate/ dir become stale after the move. design_doc /
-      # plan live under docs/superpowers and do not move, so leave them alone.
-      local moved_yaml="$archive_dir/.comate.yaml" k v
-      local actual_old="openspec/changes/$name/"
-      local actual_new="$archive_dir/"
-      for k in source_manifest handoff_context impl_context; do
-        v=$(yaml_get "$moved_yaml" "$k")
-        case "$v" in
-          "$actual_old"*)
-            yaml_set "$moved_yaml" "$k" "$actual_new${v#"$actual_old"}"
-            _step_ok "Repointed $k -> archive path"
-            ;;
-        esac
-      done
-    else
-      _step_fail "archived: true (.comate.yaml not found after move)"
-    fi
-  fi
-
-  echo "" >&2
-  if [ "$dry_run" -eq 1 ]; then
-    log_warn "Dry run complete. $steps_ok/$steps_total steps would succeed."
-  else
-    log_pass "Archive complete. $steps_ok/$steps_total steps succeeded."
-  fi
-  if [ "$steps_ok" -lt "$steps_total" ]; then exit "$COMATE_BLOCK"; fi
-  exit "$COMATE_OK"
-}
-
-# =====================================================================
-# status — list active changes + next command
-# =====================================================================
-
-_next_command() {
-  case "$1" in
-    open) echo "/comate-open" ;;
-    design) echo "/comate-design" ;;
-    build) echo "/comate-build" ;;
-    verify) echo "/comate-verify" ;;
-    archive) echo "/comate-archive" ;;
-    *) echo "" ;;
-  esac
-}
-
-status() {
-  local base="${1:-.}"
-  local changes_dir="$base/openspec/changes"
-  if [ ! -d "$changes_dir" ]; then
-    echo "No active changes."
-    return 0
-  fi
-  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")
-    [ "$name" = "archive" ] && continue
-    yaml="$d/.comate.yaml"
-    [ -f "$yaml" ] || continue
-    [ "$(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)
-    dd=$(yaml_get "$yaml" design_doc)
-    plan=$(yaml_get "$yaml" plan)
-    tasks_file="$d/tasks.md"
-    total=0; done=0
-    if [ -f "$tasks_file" ]; then
-      total=$(grep -c '^- \[' "$tasks_file" 2>/dev/null || echo 0)
-      done=$(grep -c '^- \[x\]' "$tasks_file" 2>/dev/null || echo 0)
-    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"
-    echo "    next: $(_next_command "$phase")"
-    echo ""
-  done
-  [ "$any" -eq 0 ] && echo "No active changes."
-  return 0
-}
-
-# =====================================================================
-# doctor — prerequisite self-check
-# =====================================================================
-
-doctor() {
-  local fail=0 warn=0
-  _d_pass() { log_pass "  ✓ $1"; }
-  _d_warn() { log_warn "  ⚠ $1"; warn=$((warn+1)); }
-  _d_fail() { log_fail "  ✗ $1"; fail=$((fail+1)); }
-
-  log_info "comate doctor"
-
-  # 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 >= 3"
-  fi
-
-  # git.
-  if command -v git >/dev/null 2>&1; then _d_pass "git present"; else _d_fail "git not found — install git"; fi
-
-  # sha256 tool.
-  if command -v sha256sum >/dev/null 2>&1; then _d_pass "sha256sum present"
-  elif command -v shasum >/dev/null 2>&1; then _d_pass "shasum present"
-  else _d_fail "neither sha256sum nor shasum found — install coreutils or perl shasum"; fi
-
-  # openspec CLI.
-  if command -v openspec >/dev/null 2>&1; then
-    _d_pass "openspec CLI present ($(openspec --version 2>/dev/null | head -1 || echo installed))"
-  else
-    _d_warn "openspec CLI not found — install: npm install -g @fission-ai/openspec@latest"
-  fi
-
-  # Superpowers skill directory — check known skill roots only (bounded; an
-  # unbounded $HOME scan is too slow on large home directories). The skills CLI
-  # (including `claude codeskills add`) installs Superpowers as a flat bundle of
-  # named skills (for example using-superpowers/SKILL.md), so looking only for
-  # a directory named "superpowers" produces a false warning.
-  local sp_found=0 root
-  for root 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" \
-    "./.claude/plugins" "$HOME/.claude/plugins"; do
-    if [ -f "$root/using-superpowers/SKILL.md" ] || \
-       [ -f "$root/brainstorming/SKILL.md" ] || \
-       { [ -d "$root" ] && find "$root" -maxdepth 3 -type d -name 'superpowers*' -print -quit 2>/dev/null | grep -q .; }; then
-      sp_found=1; break
-    fi
-  done
-  if [ "$sp_found" -eq 1 ]; then
-    _d_pass "Superpowers skills found"
-  else
-    _d_warn "Superpowers skills not found in known roots — run: comate init from your project directory"
-  fi
-
-  # comate's own files present.
-  local missing=0 f
-  for f in comate-lib.sh comate.sh; do
-    [ -f "$SCRIPT_DIR/$f" ] || { _d_fail "missing comate file: scripts/$f"; missing=1; }
-  done
-  [ "$missing" -eq 0 ] && _d_pass "comate scripts complete"
-
-  # LF line endings on .sh (Windows-critical).
-  local crlf=0
-  for f in "$SCRIPT_DIR"/*.sh; do
-    if grep -lq $'\r' "$f" 2>/dev/null; then _d_warn "CRLF line endings in $(basename "$f") — convert to LF"; crlf=1; fi
-  done
-  [ "$crlf" -eq 0 ] && _d_pass ".sh files use LF line endings"
-
-  echo "" >&2
-  if [ "$fail" -gt 0 ]; then
-    die "$COMATE_ENV" "$fail failure(s), $warn warning(s) — fix failures before using comate"
-  fi
-  log_pass "0 failures, $warn warning(s)"
-  exit "$COMATE_OK"
-}
-
-# =====================================================================
-# main router
-# =====================================================================
-
-CMD="${1:-}"
-shift || true
-
-case "$CMD" in
-  state)
-    NAME="${1:-}"; SUB="${2:-}"
-    [ -n "$NAME" ] && [ -n "$SUB" ] || { usage_top; exit "$COMATE_USAGE"; }
-    shift 2 || true
-    case "$SUB" in
-      init)       state_init "$NAME" "${1:-}" ;;
-      get)        state_get "$NAME" "${1:-}" ;;
-      set)        state_set "$NAME" "${1:-}" "${2:-}" ;;
-      transition) state_transition "$NAME" "${1:-}" ;;
-      check)
-        CHECK_JSON=0
-        [ "${2:-}" = "--json" ] && CHECK_JSON=1
-        state_check "$NAME" "${1:-}"
-        ;;
-      recover)    state_recover "$NAME" "${1:-}" ;;
-      scale)      state_scale "$NAME" ;;
-      validate)   state_validate "$NAME" ;;
-      *) die "$COMATE_USAGE" "Unknown state subcommand: $SUB" ;;
-    esac
-    ;;
-  guard)
-    NAME="${1:-}"; PHASE="${2:-}"
-    [ -n "$NAME" ] && [ -n "$PHASE" ] || { usage_top; exit "$COMATE_USAGE"; }
-    GUARD_APPLY=0; GUARD_JSON=0
-    for arg in "${@:3}"; do
-      case "$arg" in
-        --apply) GUARD_APPLY=1 ;;
-        --json)  GUARD_JSON=1 ;;
-      esac
-    done
-    guard "$NAME" "$PHASE"
-    ;;
-  handoff)
-    handoff "${1:-}" "${2:-}" "${3:-}" "${4:-}"
-    ;;
-  sources)
-    NAME="${1:-}"; SUB="${2:-}"
-    if [ "$NAME" = "find" ]; then
-      sources_find "${2:-}"
-    else
-      [ -n "$NAME" ] && [ -n "$SUB" ] || { usage_top; exit "$COMATE_USAGE"; }
-      shift 2 || true
-      case "$SUB" in
-        track) sources_track "$NAME" "$@" ;;
-        check) sources_check "$NAME" ;;
-        list)  sources_list "$NAME" ;;
-        *) die "$COMATE_USAGE" "Unknown sources subcommand: $SUB" ;;
-      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"; }
-    shift 2 || true
-    case "$SUB" in
-      review)  gate_review "$PRD" ;;
-      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" ;;
-    esac
-    ;;
-  archive)
-    [ -n "${1:-}" ] || { usage_top; exit "$COMATE_USAGE"; }
-    archive "$1" "${2:-}"
-    ;;
-  status)
-    status "${1:-.}"
-    ;;
-  doctor)
-    doctor
-    ;;
-  ""|-h|--help|help)
-    usage_top
-    exit "$COMATE_OK"
-    ;;
-  *)
-    usage_top
-    exit "$COMATE_USAGE"
-    ;;
-esac