@house365/comate 0.1.0

package/skills/comate/scripts/comate.sh

@@ -0,0 +1,1681 @@
+#!/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
+#   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
+
+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 | hotfix | tweak
+  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> 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>
+  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|hotfix|tweak>"
+
+  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
+    hotfix|tweak)
+      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
+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" != "hotfix" ] && [ "$workflow" != "tweak" ] && [ "$direct_override" != "true" ]; then
+    die "$COMATE_BLOCK" "ERROR: build_mode=direct is only allowed for hotfix/tweak 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|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"
+
+  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
+      ;;
+    design-complete)
+      _require_phase "$yaml" design
+      yaml_set "$yaml" phase build
+      ;;
+    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
+      ;;
+    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)"
+      ;;
+    verify-fail)
+      _require_phase "$yaml" verify
+      yaml_set "$yaml" verify_result fail
+      yaml_set "$yaml" phase build
+      yaml_set "$yaml" branch_status pending
+      ;;
+    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 "${!ENUMS[@]}"; do
+    v=$(yaml_get "$yaml" "$key")
+    [ -z "$v" ] && continue
+    [ "$v" = "null" ] && continue
+    legal="${ENUMS[$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=$(yaml_get "$yaml" phase)
+  workflow=$(yaml_get "$yaml" workflow)
+  # 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 ""
+
+  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" != "hotfix" ] && [ "$workflow" != "tweak" ]; 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 [ "$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 [ "$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 hotfix|tweak) return 0 ;; esac
+  [ "$direct_override" = "true" ] && return 0
+  echo "build_mode=direct only allowed for hotfix/tweak 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
+        [ "$GUARD_JSON" -eq 0 ] && log_warn "  [WARN] no design_doc recorded"
+      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
+}
+
+# =====================================================================
+# 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 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)
+    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 "$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"
+
+  # bash version >= 4 (need associative arrays).
+  if [ "${BASH_VERSINFO[0]:-0}" -ge 4 ]; then
+    _d_pass "bash ${BASH_VERSION} (>= 4)"
+  else
+    _d_fail "bash ${BASH_VERSION:-unknown} — comate needs bash >= 4 (associative arrays)"
+  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).
+  # Plugin roots matter too: Claude Code installs superpowers as a plugin under
+  # plugins/{cache,data}/, not under skills/. maxdepth 3 keeps deeper
+  # marketplace docs dirs (e.g. marketplaces/*/docs/superpowers) from matching.
+  local sp_found=0 root
+  for root in \
+    "./.claude/skills" "./.cursor/skills" "./.codex/skills" \
+    "$HOME/.claude/skills" "$HOME/.config/skills" "$HOME/.cursor/skills" "$HOME/.codex/skills" "$HOME/.gemini/skills" \
+    "./.claude/plugins" "$HOME/.claude/plugins"; do
+    if [ -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 — install manually (see reference/prerequisites.md)"
+  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
+    ;;
+  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