@gepeiyu/smart 0.1.1

package/scripts/smart-state.sh

@@ -0,0 +1,365 @@
+#!/usr/bin/env bash
+# smart-state.sh — .smart.yaml state machine for the Smart skill.
+# Usage: smart-state.sh <subcommand> <change-name> [args...]
+# Subcommands: init / get / set / transition / check [--recover] / scale / task-checkoff / next
+# 样板版本: v1
+# v1: set -uo pipefail (no -e; scripts use explicit exit 1 + `&&` shorthand).
+# v1.1 TODO: convert `A && B` to if-blocks and re-enable `set -e` for full comet parity.
+set -uo pipefail
+
+_smart_script_dir="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd -P)"
+SMART_ENV="${SMART_ENV:-$_smart_script_dir/smart-env.sh}"
+if [ ! -f "$SMART_ENV" ]; then
+  SMART_ENV="$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/scripts/smart-env.sh' -type f -print -quit 2>/dev/null)"
+fi
+if [ -z "${SMART_ENV:-}" ] || [ ! -f "$SMART_ENV" ]; then
+  echo "ERROR: smart-env.sh not found. Ensure the smart skill is installed (scripts/smart-env.sh)." >&2
+  exit 1
+fi
+. "$SMART_ENV"
+
+# --- path helpers ---
+change_dir_for() {
+  local n="$1"
+  if [ -d "openspec/changes/$n" ]; then echo "openspec/changes/$n"
+  elif [ -d "openspec/changes/archive/$n" ]; then echo "openspec/changes/archive/$n"
+  else echo "openspec/changes/$n"; fi
+}
+yaml_file_for() { echo "$(change_dir_for "$1")/.smart.yaml"; }
+
+# --- project config readers (.smart/config.yaml) ---
+project_context_compression() {
+  local value="off"
+  if [ -n "${SMART_CONTEXT_COMPRESSION:-}" ]; then value="$SMART_CONTEXT_COMPRESSION"
+  elif [ -f ".smart/config.yaml" ]; then value=$(yaml_field "context_compression" ".smart/config.yaml"); value="${value:-off}"; fi
+  case "$value" in off|beta) printf '%s\n' "$value" ;; *) red "ERROR: invalid context_compression: '$value' (off|beta)"; exit 1 ;; esac
+}
+project_auto_transition_default() {
+  local value="true"
+  if [ -n "${SMART_AUTO_TRANSITION:-}" ]; then value="$SMART_AUTO_TRANSITION"
+  elif [ -f ".smart/config.yaml" ]; then local raw; raw=$(yaml_field "auto_transition" ".smart/config.yaml" 2>/dev/null || true); [ -n "$raw" ] && value="$raw"; fi
+  case "$value" in true|false) printf '%s\n' "$value" ;; *) red "ERROR: invalid auto_transition: '$value' (true|false)"; exit 1 ;; esac
+}
+project_review_mode_default() {
+  local value="null"
+  if [ -n "${SMART_REVIEW_MODE:-}" ]; then value="$SMART_REVIEW_MODE"
+  elif [ -f ".smart/config.yaml" ]; then local raw; raw=$(yaml_field "review_mode" ".smart/config.yaml" 2>/dev/null || true); [ -n "$raw" ] && value="$raw"; fi
+  case "$value" in null|off|standard|thorough) printf '%s\n' "$value" ;; *) red "ERROR: invalid review_mode: '$value' (off|standard|thorough)"; exit 1 ;; esac
+}
+
+# --- cmd_init ---
+cmd_init() {
+  local change_name="$1" workflow="$2"
+  local issue_number="${3:-null}" issue_repo="${4:-null}"
+  validate_change_name "$change_name"
+  validate_enum "$workflow" "full" "hotfix" "tweak"
+  case "$issue_number" in null|[0-9]*) ;; *) red "ERROR: issue_number must be null or a number: '$issue_number'"; exit 1 ;; esac
+  case "$issue_repo" in null) ;; *[!A-Za-z0-9._/-]*) red "ERROR: issue_repo invalid: '$issue_repo'"; exit 1 ;; esac
+
+  local change_dir yaml_file
+  change_dir=$(change_dir_for "$change_name")
+  yaml_file=$(yaml_file_for "$change_name")
+  if [ -f "$yaml_file" ]; then red "ERROR: .smart.yaml already exists at $yaml_file"; exit 1; fi
+  mkdir -p "$change_dir"
+
+  local build_mode isolation verify_mode tdd_mode review_mode context_compression auto_transition
+  context_compression=$(project_context_compression)
+  auto_transition=$(project_auto_transition_default)
+  case "$workflow" in
+    full) build_mode="null"; tdd_mode="null"; review_mode="$(project_review_mode_default)"; isolation="null"; verify_mode="null" ;;
+    hotfix|tweak) build_mode="direct"; tdd_mode="direct"; review_mode="off"; isolation="branch"; verify_mode="light" ;;
+  esac
+
+  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
+
+  cat > "$yaml_file" <<EOF
+change_name: $change_name
+workflow: $workflow
+phase: issue
+issue_number: $issue_number
+issue_repo: $issue_repo
+context_compression: $context_compression
+build_mode: $build_mode
+build_pause: null
+subagent_dispatch: null
+tdd_mode: $tdd_mode
+review_mode: $review_mode
+isolation: $isolation
+verify_mode: $verify_mode
+auto_transition: $auto_transition
+base_ref: $base_ref
+design_doc: null
+plan: null
+verify_result: pending
+verification_report: null
+branch_status: pending
+created_at: $(date -u +%Y-%m-%d)
+verified_at: null
+archived: false
+direct_override: null
+build_command: null
+verify_command: null
+handoff_context: null
+handoff_hash: null
+EOF
+  green "Initialized: $yaml_file (workflow=$workflow, issue_number=$issue_number)"
+}
+
+# --- cmd_get ---
+cmd_get() {
+  local change_name="$1" field="$2"
+  validate_change_name "$change_name"
+  local yaml_file; yaml_file=$(yaml_file_for "$change_name")
+  [ -f "$yaml_file" ] || { red "ERROR: .smart.yaml not found at $yaml_file"; exit 1; }
+  local value; value=$(yaml_field "$field" "$yaml_file")
+  if [ "$field" = "auto_transition" ] && { [ -z "$value" ] || [ "$value" = "null" ]; }; then value="$(project_auto_transition_default)"; fi
+  echo "${value:-}"
+}
+
+# --- cmd_set ---
+cmd_set() {
+  local change_name="$1" field="$2" value="$3"
+  validate_change_name "$change_name"
+  local yaml_file; yaml_file=$(yaml_file_for "$change_name")
+  [ -f "$yaml_file" ] || { red "ERROR: .smart.yaml not found at $yaml_file"; exit 1; }
+
+  case "$field" in
+    phase)
+      if [ "${_SMART_IN_TRANSITION:-}" != "1" ] && [ "${SMART_FORCE_PHASE:-}" != "1" ]; then
+        red "ERROR: Setting 'phase' directly is not allowed; it bypasses state machine evidence checks." >&2
+        red "  Use: smart-state.sh transition <change-name> <event>" >&2
+        red "  Repair escape hatch: SMART_FORCE_PHASE=1 smart-state.sh set <change-name> phase <value>" >&2
+        exit 1
+      fi
+      validate_enum "$value" "issue" "design" "build" "verify" "archive" ;;
+    workflow|context_compression|build_mode|build_pause|subagent_dispatch|tdd_mode|review_mode|isolation|verify_mode|auto_transition|verify_result|verification_report|branch_status|archived|design_doc|plan|verified_at|created_at|direct_override|build_command|verify_command|handoff_context|handoff_hash|base_ref|issue_number|issue_repo|change_name|verify_mode) ;;
+    *) red "ERROR: Unknown field: '$field'"; exit 1 ;;
+  esac
+
+  case "$field" in
+    workflow) validate_enum "$value" "full" "hotfix" "tweak" ;;
+    context_compression) validate_enum "$value" "off" "beta" ;;
+    build_mode) validate_enum "$value" "subagent-driven-development" "executing-plans" "direct" ;;
+    build_pause) validate_enum "$value" "null" "plan-ready" ;;
+    subagent_dispatch) validate_enum "$value" "null" "confirmed" ;;
+    tdd_mode) validate_enum "$value" "tdd" "direct" ;;
+    review_mode) validate_enum "$value" "off" "standard" "thorough" ;;
+    isolation) validate_enum "$value" "branch" "worktree" ;;
+    verify_mode) validate_enum "$value" "light" "full" ;;
+    auto_transition) validate_enum "$value" "true" "false" ;;
+    verify_result) validate_enum "$value" "pending" "pass" "fail" ;;
+    branch_status) validate_enum "$value" "pending" "handled" ;;
+    archived) validate_enum "$value" "true" "false" ;;
+    direct_override) validate_enum "$value" "true" "false" ;;
+    design_doc|plan|verification_report|handoff_context|handoff_hash) validate_path_field "$value" "$field" ;;
+    issue_number) case "$value" in null|[0-9]*) ;; *) red "ERROR: issue_number must be null or number"; exit 1 ;; esac ;;
+  esac
+
+  if grep -q "^${field}:" "$yaml_file"; then replace_yaml_field "$yaml_file" "$field" "$value"
+  else echo "${field}: ${value}" >> "$yaml_file"; fi
+  green "[SET] ${field}=${value}"
+}
+
+# --- transition require_* helpers ---
+require_phase() {
+  local change_name="$1" expected="$2" actual
+  actual=$(cmd_get "$change_name" "phase")
+  [ "$actual" = "$expected" ] || { red "ERROR: Cannot transition '$change_name': expected phase $expected, got $actual"; exit 1; }
+}
+require_open_artifacts() {
+  local change_name="$1" change_dir workflow f
+  change_dir=$(change_dir_for "$change_name"); workflow=$(cmd_get "$change_name" "workflow")
+  for f in proposal.md tasks.md; do [ -s "$change_dir/$f" ] || { red "ERROR: $f must exist and be non-empty before leaving issue"; exit 1; }; done
+  if [ "$workflow" = "full" ] && [ ! -s "$change_dir/design.md" ]; then red "ERROR: design.md must be non-empty before leaving issue (full workflow)"; exit 1; fi
+}
+require_design_evidence() {
+  local design_doc; design_doc=$(cmd_get "$1" "design_doc")
+  { [ -n "$design_doc" ] && [ "$design_doc" != "null" ] && [ -s "$design_doc" ]; } || { red "ERROR: design_doc must point to an existing Design Doc before leaving design"; exit 1; }
+}
+require_verification_evidence() {
+  local report branch_status
+  report=$(cmd_get "$1" "verification_report"); branch_status=$(cmd_get "$1" "branch_status")
+  { [ -n "$report" ] && [ "$report" != "null" ] && [ -f "$report" ]; } || { red "ERROR: verification_report must point to an existing report"; exit 1; }
+  [ "$branch_status" = "handled" ] || { red "ERROR: branch_status must be handled"; exit 1; }
+}
+require_build_decisions() {
+  local change_name="$1" workflow build_mode isolation direct_override subagent_dispatch tdd_mode review_mode
+  workflow=$(cmd_get "$change_name" "workflow"); build_mode=$(cmd_get "$change_name" "build_mode")
+  isolation=$(cmd_get "$change_name" "isolation"); direct_override=$(cmd_get "$change_name" "direct_override" 2>/dev/null || true)
+  subagent_dispatch=$(cmd_get "$change_name" "subagent_dispatch" 2>/dev/null || true)
+  tdd_mode=$(cmd_get "$change_name" "tdd_mode" 2>/dev/null || true); review_mode=$(cmd_get "$change_name" "review_mode" 2>/dev/null || true)
+  case "$isolation" in branch|worktree) ;; *) red "ERROR: isolation must be branch|worktree, got '${isolation:-null}'"; exit 1 ;; esac
+  case "$build_mode" in subagent-driven-development|executing-plans|direct) ;; *) red "ERROR: build_mode must be selected, got '${build_mode:-null}'"; exit 1 ;; esac
+  if [ "$build_mode" = "direct" ] && [ "$workflow" != "hotfix" ] && [ "$workflow" != "tweak" ] && [ "$direct_override" != "true" ]; then red "ERROR: build_mode=direct only for hotfix/tweak unless direct_override=true"; exit 1; fi
+  if [ "$build_mode" = "subagent-driven-development" ] && [ "$subagent_dispatch" != "confirmed" ]; then red "ERROR: subagent_dispatch must be confirmed for subagent-driven-development"; exit 1; fi
+  if [ "$workflow" = "full" ] && { [ "$tdd_mode" = "null" ] || [ -z "$tdd_mode" ]; }; then red "ERROR: tdd_mode must be selected (full workflow)"; exit 1; fi
+  if [ "$workflow" = "full" ]; then case "$review_mode" in off|standard|thorough) ;; *) red "ERROR: review_mode must be off|standard|thorough (full), got '${review_mode:-null}'"; exit 1 ;; esac; fi
+}
+
+# --- cmd_transition ---
+cmd_transition() {
+  local change_name="$1" event="$2"
+  local _SMART_IN_TRANSITION=1
+  validate_change_name "$change_name"
+  validate_enum "$event" "issue-complete" "design-complete" "build-complete" "verify-pass" "verify-fail" "archive-reopen" "archived"
+  case "$event" in
+    issue-complete)
+      require_phase "$change_name" "issue"; require_open_artifacts "$change_name"
+      local workflow; workflow=$(cmd_get "$change_name" "workflow")
+      if [ "$workflow" = "full" ]; then cmd_set "$change_name" phase design; else cmd_set "$change_name" phase build; fi ;;
+    design-complete)
+      require_phase "$change_name" "design"; require_design_evidence "$change_name"
+      cmd_set "$change_name" phase build ;;
+    build-complete)
+      require_phase "$change_name" "build"; require_build_decisions "$change_name"
+      local cur; cur=$(cmd_get "$change_name" "verify_result")
+      cmd_set "$change_name" phase verify; cmd_set "$change_name" verify_result pending
+      if [ "$cur" != "fail" ]; then cmd_set "$change_name" verification_report null; cmd_set "$change_name" branch_status pending; fi ;;
+    verify-pass)
+      require_phase "$change_name" "verify"; require_verification_evidence "$change_name"
+      cmd_set "$change_name" verify_result pass; cmd_set "$change_name" phase archive; cmd_set "$change_name" verified_at "$(date -u +%Y-%m-%d)" ;;
+    verify-fail)
+      require_phase "$change_name" "verify"
+      cmd_set "$change_name" verify_result fail; cmd_set "$change_name" phase build ;;
+    archive-reopen)
+      require_phase "$change_name" "archive"
+      local archived; archived=$(cmd_get "$change_name" "archived")
+      [ "$archived" != "true" ] || { red "ERROR: Cannot archive-reopen: already archived"; exit 1; }
+      cmd_set "$change_name" verify_result pending; cmd_set "$change_name" phase verify; cmd_set "$change_name" verified_at null ;;
+    archived)
+      require_phase "$change_name" "archive"
+      local vr; vr=$(cmd_get "$change_name" "verify_result")
+      [ "$vr" = "pass" ] || { red "ERROR: verify_result must be pass before archiving"; exit 1; }
+      cmd_set "$change_name" archived true ;;
+  esac
+  green "[TRANSITION] ${event}"
+}
+
+# --- cmd_check ---
+CHECK_BLOCK=0
+check_pass() { printf '  \033[32m[PASS]\033[0m %s\n' "$1" >&2; }
+check_fail() { printf '  \033[31m[FAIL]\033[0m %s\n' "$1" >&2; CHECK_BLOCK=1; }
+check_nonempty() { file_nonempty "$2" && check_pass "$1 non-empty" || check_fail "$1 missing or empty"; }
+check_yaml_is() { local a; a=$(cmd_get "$3" "$1"); [ "$a" = "$2" ] && check_pass "$1=$a (expected $2)" || check_fail "$1=$a (expected $2)"; }
+check_yaml_empty() { local v; v=$(cmd_get "$2" "$1"); { [ -z "$v" ] || [ "$v" = "null" ]; } && check_pass "$1 empty/null" || check_fail "$1=$v (expected empty/null)"; }
+
+cmd_check() {
+  local change_name="$1" phase="$2"
+  validate_change_name "$change_name"; validate_enum "$phase" "issue" "design" "build" "verify" "archive"
+  local change_dir; change_dir=$(change_dir_for "$change_name")
+  local yaml_file="$change_dir/.smart.yaml"
+  echo "=== Entry Check: smart-$phase ===" >&2
+  [ -f "$yaml_file" ] || { red "ERROR: .smart.yaml not found at $yaml_file"; exit 1; }
+  case "$phase" in
+    issue) check_pass ".smart.yaml exists"; check_yaml_is "phase" "issue" "$change_name" ;;
+    design) check_pass ".smart.yaml exists"; check_yaml_is "phase" "design" "$change_name"; check_yaml_is "workflow" "full" "$change_name"; check_yaml_empty "design_doc" "$change_name"; check_nonempty "proposal.md" "$change_dir/proposal.md"; check_nonempty "design.md" "$change_dir/design.md"; check_nonempty "tasks.md" "$change_dir/tasks.md" ;;
+    build)  check_pass ".smart.yaml exists"; check_yaml_is "phase" "build" "$change_name";
+            local workflow; workflow=$(cmd_get "$change_name" "workflow")
+            if [ "$workflow" = "full" ]; then local dd; dd=$(cmd_get "$change_name" "design_doc"); { [ -n "$dd" ] && [ "$dd" != "null" ] && [ -f "$dd" ]; } && check_pass "design_doc=$dd (exists)" || check_fail "design_doc=$dd (expected non-null, file exists)"; else check_pass "workflow=$workflow (design_doc not required)"; fi
+            check_nonempty "proposal.md" "$change_dir/proposal.md"; check_nonempty "tasks.md" "$change_dir/tasks.md" ;;
+    verify) check_pass ".smart.yaml exists"; check_yaml_is "phase" "verify" "$change_name";
+            local vr; vr=$(cmd_get "$change_name" "verify_result"); { [ "$vr" = "pending" ] || [ -z "$vr" ] || [ "$vr" = "null" ]; } && check_pass "verify_result=$vr" || check_fail "verify_result=$vr (expected pending/null)" ;;
+    archive) check_pass ".smart.yaml exists"; check_yaml_is "phase" "archive" "$change_name"; check_yaml_is "verify_result" "pass" "$change_name";
+             local ar; ar=$(cmd_get "$change_name" "archived"); [ "$ar" != "true" ] && check_pass "archived=$ar (not true)" || check_fail "archived=$ar (expected not true)" ;;
+    *) red "ERROR: Unknown phase: $phase"; exit 1 ;;
+  esac
+  echo "" >&2
+  if [ "$CHECK_BLOCK" -eq 1 ]; then red "BLOCKED — fix failing checks before proceeding"; exit 1; fi
+  green "ALL CHECKS PASSED — ready to proceed"
+}
+
+# --- cmd_scale ---
+cmd_scale() {
+  local change_name="$1"
+  validate_change_name "$change_name"
+  local change_dir; change_dir=$(change_dir_for "$change_name")
+  local yaml_file="$change_dir/.smart.yaml"
+  [ -f "$yaml_file" ] || { red "ERROR: .smart.yaml not found at $yaml_file"; exit 1; }
+  local tasks_file="$change_dir/tasks.md" task_count=0 delta_spec_count=0 changed_files=0
+  [ -f "$tasks_file" ] && task_count=$(grep -c '^\- \[' "$tasks_file" 2>/dev/null || echo 0)
+  [ -d "$change_dir/specs" ] && delta_spec_count=$(find "$change_dir/specs" -name spec.md -type f 2>/dev/null | wc -l | tr -d ' ')
+  if git rev-parse --git-dir >/dev/null 2>&1; then
+    local plan_file base_ref=""
+    plan_file=$(cmd_get "$change_name" "plan" 2>/dev/null || true)
+    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: *//' || true); fi
+    if [ -z "$base_ref" ] || [ "$base_ref" = "null" ]; then base_ref=$(cmd_get "$change_name" "base_ref" 2>/dev/null || true); 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 ' '); 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: $change_name ===" >&2
+  echo "  Tasks: $task_count (thr 3); Delta specs: $delta_spec_count (thr 1); Changed files: $changed_files (thr 4) -> $result" >&2
+  replace_yaml_field "$yaml_file" "verify_mode" "$result"
+  green "[SCALE] verify_mode=$result"
+}
+
+# --- cmd_task_checkoff ---
+cmd_task_checkoff() {
+  local task_file="$1" task_text="$2"
+  validate_path_field "$task_file" "task file"
+  [ -n "$task_text" ] || { red "ERROR: Task text cannot be empty"; exit 1; }
+  [ -f "$task_file" ] || { red "ERROR: Task file not found: $task_file"; exit 1; }
+  local counts; counts=$(TASK_TEXT="$task_text" awk 'BEGIN{task=ENVIRON["TASK_TEXT"]} {sub(/\r$/,""); if($0=="- [ ] "task||$0=="- [x] "task||$0=="- [X] "task)total++; if($0=="- [x] "task||$0=="- [X] "task)checked++} END{printf "%d %d\n",total+0,checked+0}' "$task_file")
+  local total="${counts%% *}" checked="${counts##* }"
+  [ "$total" -eq 1 ] || { red "ERROR: task text must appear exactly once (found $total): $task_text"; exit 1; }
+  [ "$checked" -eq 1 ] || { red "ERROR: task not checked: $task_text"; exit 1; }
+  echo "TASK_CHECKOFF: PASS"; echo "FILE: $task_file"; echo "TASK: $task_text"
+}
+
+# --- cmd_next (single-skill: SKILL=smart, PHASE=current) ---
+cmd_next() {
+  local change_name="$1"
+  validate_change_name "$change_name"
+  local yaml_file; yaml_file=$(yaml_file_for "$change_name")
+  [ -f "$yaml_file" ] || { red "ERROR: .smart.yaml not found at $yaml_file"; exit 1; }
+  local phase workflow auto_transition archived skill
+  phase=$(cmd_get "$change_name" "phase" 2>/dev/null || true)
+  workflow=$(cmd_get "$change_name" "workflow" 2>/dev/null || true)
+  auto_transition=$(cmd_get "$change_name" "auto_transition" 2>/dev/null || true)
+  archived=$(cmd_get "$change_name" "archived" 2>/dev/null || true)
+  if [ -z "$auto_transition" ] || [ "$auto_transition" = "null" ]; then auto_transition="$(project_auto_transition_default)"; fi
+  if [ "$archived" = "true" ]; then echo "NEXT: done"; return 0; fi
+  case "$phase" in
+    issue)  skill="smart-issue" ;;
+    design) skill="smart-design" ;;
+    build)  case "$workflow" in hotfix) skill="smart-hotfix" ;; tweak) skill="smart-tweak" ;; *) skill="smart-build" ;; esac ;;
+    verify) skill="smart-verify" ;;
+    archive) skill="smart-archive" ;;
+    *) red "ERROR: unknown phase: ${phase:-null}"; exit 1 ;;
+  esac
+  if [ "$auto_transition" = "false" ]; then
+    echo "NEXT: manual"; echo "SKILL: $skill"; echo "HINT: phase is '$phase'; run /$skill manually to continue"
+  else
+    echo "NEXT: auto"; echo "SKILL: $skill"
+  fi
+}
+
+# --- main ---
+SUBCOMMAND="${1:-}"; shift || true
+case "$SUBCOMMAND" in
+  init) [ $# -lt 2 ] && { red "Usage: smart-state.sh init <name> <full|hotfix|tweak> [issue_number] [issue_repo]"; exit 1; }; cmd_init "$@" ;;
+  get)  [ $# -lt 2 ] && { red "Usage: smart-state.sh get <name> <field>"; exit 1; }; cmd_get "$@" ;;
+  set)  [ $# -lt 3 ] && { red "Usage: smart-state.sh set <name> <field> <value>"; exit 1; }; cmd_set "$@" ;;
+  transition) [ $# -lt 2 ] && { red "Usage: smart-state.sh transition <name> <event>"; red "Events: issue-complete, design-complete, build-complete, verify-pass, verify-fail, archive-reopen, archived"; exit 1; }; cmd_transition "$@" ;;
+  check) [ $# -lt 2 ] && { red "Usage: smart-state.sh check <name> <phase> [--recover]"; exit 1; }; cmd_check "$@" ;;
+  scale) [ $# -lt 1 ] && { red "Usage: smart-state.sh scale <name>"; exit 1; }; cmd_scale "$@" ;;
+  task-checkoff) [ $# -lt 2 ] && { red "Usage: smart-state.sh task-checkoff <file> <task-text>"; exit 1; }; cmd_task_checkoff "$@" ;;
+  next) [ $# -lt 1 ] && { red "Usage: smart-state.sh next <name>"; exit 1; }; cmd_next "$@" ;;
+  -h|--help|help)
+    cat <<'EOF'
+Usage: smart-state.sh <subcommand> <change-name> [args...]
+Subcommands:
+  init <name> <full|hotfix|tweak> [issue_number] [issue_repo]
+  get <name> <field>
+  set <name> <field> <value>
+  transition <name> <event>   (issue-complete|design-complete|build-complete|verify-pass|verify-fail|archive-reopen|archived)
+  check <name> <phase>        (issue|design|build|verify|archive)
+  scale <name>
+  task-checkoff <file> <task-text>
+  next <name>
+EOF
+    ;;
+  *) red "Unknown subcommand: $SUBCOMMAND"; exit 1 ;;
+esac

package/smart-archive/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: smart-archive
+description: "Smart 阶段 5：归档。用 /smart-archive 调用。按 OpenSpec delta 语义合并主 spec，归档 change。"
+---
+
+# Smart 阶段 5：归档（Archive）
+
+## 前置条件
+
+- 验证已通过（阶段 4 完成）
+- 分支已处理
+- `openspec/changes/<name>/.smart.yaml` 中 `verify_result: pass`
+
+## 步骤
+
+### 0. 输出语言约束
+
+归档摘要和生命周期闭环说明必须使用触发本次工作流的用户请求语言。
+
+### 0b. 入口状态验证（Entry Check）
+
+执行入口验证：
+
+```bash
+SMART_ENV="${SMART_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/smart/scripts/smart-env.sh' -type f -print -quit 2>/dev/null)}"
+if [ -z "$SMART_ENV" ]; then
+  echo "ERROR: smart-env.sh not found. Ensure the smart skill is installed." >&2
+  return 1
+fi
+. "$SMART_ENV"
+"$SMART_BASH" "$SMART_STATE" check <name> archive
+```
+
+验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
+
+### 1. 归档前最终确认（阻塞点）
+
+入口验证通过后，**必须按 `smart/reference/decision-point.md` 的协议暂停并等待用户确认是否立即归档**。不得在用户确认前运行 `"$SMART_BASH" "$SMART_ARCHIVE" "<change-name>"`。
+
+确认前必须向用户展示简短摘要：
+- change 名称
+- 验证报告路径和结论
+- 分支处理状态
+- 本次归档将执行的不可逆动作：按 OpenSpec delta 语义合并主 spec、标注 design doc / plan、移动 change 到 archive 目录
+
+用户确认问题必须以单选题形式呈现，包含以下选项：
+- 「确认归档」— 立即执行归档脚本，完成 spec 合并和 change 移动
+- 「需要调整或重新验证」— 不执行归档；运行 `"$SMART_BASH" "$SMART_STATE" transition <change-name> archive-reopen` 回到 `phase: verify`，再调用 `/smart-verify`。若验证阶段确认需要修复，再按 `/smart-verify` 的验证失败决策回到 `/smart-build`
+- 「暂不归档」— 不执行归档，保留当前 `phase: archive` 状态，等待用户稍后再次调用 `/smart-archive`
+
+只有用户选择「确认归档」后，才允许继续 Step 2。用户选择「需要调整或重新验证」后，必须先执行 `archive-reopen` 状态回退，不得手动编辑 `.smart.yaml`。
+
+### 2. 执行归档
+
+运行归档脚本，自动完成以下全部步骤：
+
+```bash
+"$SMART_BASH" "$SMART_ARCHIVE" "<change-name>"
+```
+
+脚本自动执行：
+1. 入口状态验证（phase=archive, verify_result=pass, archived=false）
+2. Design doc 前置元数据标注（archived-with, status）
+3. Plan 前置元数据标注（archived-with）
+4. 调用 OpenSpec archive 按 delta 语义合并主 spec 并移动 change 到归档目录
+5. 校验主 spec 未残留 delta-only section 标题
+6. 通过 `smart-state transition <archive-name> archived` 更新 `archived: true`
+
+如脚本返回非零退出码，报告错误并停止。
+如脚本返回零退出码，归档完成。
+脚本摘要中的 `X/Y steps succeeded` 以真实执行步骤计数，不会因 delta spec 同步或文档标注重复累计。
+
+脚本会调用 OpenSpec 归档能力按 `ADDED/MODIFIED/REMOVED/RENAMED` 语义合并主 spec，并在归档后校验主 spec 中没有残留 delta-only section 标题。
+
+如需预览而不实际执行，使用 `--dry-run` 参数。
+
+Smart 扩展：归档脚本 smart-archive.sh 在合并主 spec、移动 change、设置 archived=true 后，若 issue_number 非 null，会执行 `gh issue close <n>`（issue_repo 已设时带 `--repo`）—— Issue 关闭即 change 归档。
+
+### 3. 生命周期闭环
+
+Spec 生命周期在此完成：
+```
+brainstorming → delta spec → 实施 → 验证 → 主 spec 合并 → design doc 标注 → 归档
+```
+
+## 退出条件
+
+- 归档脚本执行成功（退出码 0）
+- 归档目录 `openspec/changes/archive/YYYY-MM-DD-<change-name>/` 存在
+- 归档后的 `.smart.yaml` 中 `archived: true`
+
+归档脚本会把 `openspec/changes/<name>/` 移动到 `openspec/changes/archive/YYYY-MM-DD-<name>/`。
+
+> **WARNING**: 归档成功后**不要再对原 change 名运行** `"$SMART_BASH" "$SMART_GUARD" <change-name> archive`，因为原活跃目录已经不存在。误调会导致 guard 报错"change directory not found"。归档完整性以脚本退出码和归档目录状态为准。
+
+## 完成
+
+Smart 流程全部完成。如需开始新工作，调用 `/smart` 或 `/smart-issue`。
+
+## 上下文压缩恢复
+
+按 `smart/reference/context-recovery.md` 执行，phase 参数为 `archive`。若 `archived: true` 且归档目录存在，归档已完成，无需再次执行归档操作。