@gepeiyu/smart 0.1.1

package/scripts/smart-archive.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# smart-archive.sh — one-shot archive for the Smart skill.
+# Usage: smart-archive.sh <change-name> [--dry-run]
+# Steps: validate entry -> openspec archive (merge delta, move change) ->
+#        annotate design_doc/plan frontmatter -> smart-state transition archived ->
+#        gh issue close (if issue_number set) -> verify main specs clean.
+# 样板版本: v1
+# v1: set -uo pipefail (no -e; explicit exit 1 + `&&` shorthand). v1.1: if-blocks + set -e.
+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"
+
+SMART_OPENSPEC="${SMART_OPENSPEC:-openspec}"
+DRY_RUN=0
+[[ "${2:-}" == "--dry-run" ]] && DRY_RUN=1
+
+CHANGE="$1"
+validate_change_name "$CHANGE"
+
+CHANGE_DIR="openspec/changes/$CHANGE"
+YAML="$CHANGE_DIR/.smart.yaml"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd -P)"
+STATE_SH="$SCRIPT_DIR/smart-state.sh"
+TODAY=$(date -u +%Y-%m-%d)
+ARCHIVE_NAME="${TODAY}-${CHANGE}"
+ARCHIVE_DIR="openspec/changes/archive/${ARCHIVE_NAME}"
+
+STEPS_OK=0; STEPS_TOTAL=0
+step_ok()   { green "  [OK] $1"; STEPS_OK=$((STEPS_OK+1)); STEPS_TOTAL=$((STEPS_TOTAL+1)); }
+step_fail() { red   "  [FAIL] $1"; STEPS_TOTAL=$((STEPS_TOTAL+1)); }
+step_dry()  { yellow "  [DRY-RUN] $1"; STEPS_OK=$((STEPS_OK+1)); STEPS_TOTAL=$((STEPS_TOTAL+1)); }
+
+echo "=== Smart Archive: $CHANGE ===" >&2
+
+[ -f "$YAML" ] || { red "FATAL: .smart.yaml not found at $YAML"; exit 1; }
+
+DESIGN_DOC=$(yaml_field "design_doc" "$YAML")
+PLAN_PATH=$(yaml_field "plan" "$YAML")
+ISSUE_NUMBER=$(yaml_field "issue_number" "$YAML")
+ISSUE_REPO=$(yaml_field "issue_repo" "$YAML")
+PHASE_VAL=$(yaml_field "phase" "$YAML")
+VERIFY_VAL=$(yaml_field "verify_result" "$YAML")
+ARCHIVED_VAL=$(yaml_field "archived" "$YAML")
+
+[ "$PHASE_VAL" = "archive" ] || { red "FATAL: phase is '$PHASE_VAL', expected 'archive'"; exit 1; }
+[ "$VERIFY_VAL" = "pass" ] || { red "FATAL: verify_result is '$VERIFY_VAL', expected 'pass'. Run smart verify first."; exit 1; }
+[ "$ARCHIVED_VAL" = "true" ] && { red "FATAL: change already archived"; exit 1; }
+step_ok "Entry state verified"
+
+if [ -d "$ARCHIVE_DIR" ]; then red "FATAL: archive target already exists: $ARCHIVE_DIR"; exit 1; fi
+step_ok "Archive target available"
+
+# --- annotate frontmatter ---
+annotate_frontmatter() {
+  local file="$1" extra="$2"
+  [ -f "$file" ] || return 0
+  if [ "$DRY_RUN" -eq 1 ]; then step_dry "Would annotate: $file"; return 0; fi
+  if head -1 "$file" | grep -q '^---'; then
+    local tmp; tmp=$(mktemp); chmod 600 "$tmp"
+    awk -v archive="$ARCHIVE_NAME" -v extra="$extra" '/^archived-with:/{next} NR==1 && /^---/{print;next} /^---/ && NR>1 {print "archived-with: " archive; if(extra!="") print extra; print; next} {print}' "$file" > "$tmp"; mv "$tmp" "$file"
+  else
+    local tmp; tmp=$(mktemp); chmod 600 "$tmp"
+    { echo "---"; echo "archived-with: $ARCHIVE_NAME"; [ -n "$extra" ] && echo "$extra"; echo "status: final"; echo "---"; cat "$file"; } > "$tmp"; mv "$tmp" "$file"
+  fi
+  step_ok "Annotated: $file"
+}
+
+# --- openspec archive ---
+verify_main_specs_clean() {
+  [ -d "openspec/specs" ] || return 0
+  local found=0 matches
+  for spec_file in openspec/specs/*/spec.md; do
+    [ -f "$spec_file" ] || continue
+    matches=$(grep -nE '^## (ADDED|MODIFIED|REMOVED|RENAMED) Requirements$' "$spec_file" 2>/dev/null || true)
+    if [ -n "$matches" ]; then red "FATAL: delta-only heading leaked into main spec: $spec_file"; printf '%s\n' "$matches" >&2; found=1; fi
+  done
+  [ "$found" -eq 0 ]
+}
+resolve_archive_dir() {
+  [ -d "$ARCHIVE_DIR" ] && return 0
+  local found; found=$(find "openspec/changes/archive" -maxdepth 1 -mindepth 1 -type d -name "*-$CHANGE" 2>/dev/null | head -1 || true)
+  [ -n "$found" ] && { ARCHIVE_DIR="$found"; ARCHIVE_NAME=$(basename "$found"); return 0; }
+  return 1
+}
+
+if [ "$DRY_RUN" -eq 1 ]; then
+  step_dry "Would run OpenSpec archive: $CHANGE"
+else
+  if ! command -v "$SMART_OPENSPEC" >/dev/null 2>&1; then
+    if command -v npx >/dev/null 2>&1; then SMART_OPENSPEC="npx --no-install openspec"; else red "FATAL: openspec CLI not found"; exit 1; fi
+  fi
+  "$SMART_OPENSPEC" archive "$CHANGE" --yes >&2
+  if ! resolve_archive_dir; then step_fail "OpenSpec archive output not found"; exit 1; else step_ok "OpenSpec archive completed: $ARCHIVE_DIR"; fi
+  verify_main_specs_clean && step_ok "Main specs verified clean" || step_fail "Main specs clean check"
+fi
+
+# --- annotate design doc + plan ---
+if [ -n "$DESIGN_DOC" ] && [ "$DESIGN_DOC" != "null" ]; then annotate_frontmatter "$DESIGN_DOC" "status: final"; fi
+if [ -n "$PLAN_PATH" ] && [ "$PLAN_PATH" != "null" ]; then annotate_frontmatter "$PLAN_PATH" ""; fi
+
+# --- mark archived via smart-state transition ---
+ARCHIVE_YAML="$ARCHIVE_DIR/.smart.yaml"
+if [ "$DRY_RUN" -eq 1 ]; then
+  step_dry "Would set archived: true in $ARCHIVE_YAML"
+else
+  if [ -f "$ARCHIVE_YAML" ]; then
+    "$SMART_BASH" "$STATE_SH" transition "$ARCHIVE_NAME" archived >/dev/null && step_ok "archived: true" || step_fail "archived: true"
+  else step_fail "archived: true (.smart.yaml not found after move)"; fi
+fi
+
+# --- close the GitHub Issue (Smart extension) ---
+if [ "$ISSUE_NUMBER" != "null" ] && [ -n "$ISSUE_NUMBER" ]; then
+  if [ "$DRY_RUN" -eq 1 ]; then
+    step_dry "Would run: gh issue close $ISSUE_NUMBER${ISSUE_REPO:+ --repo $ISSUE_REPO}"
+  else
+    if [ "$ISSUE_REPO" != "null" ] && [ -n "$ISSUE_REPO" ]; then
+      gh issue close "$ISSUE_NUMBER" --repo "$ISSUE_REPO" && step_ok "closed issue #$ISSUE_NUMBER ($ISSUE_REPO)" || step_fail "gh issue close #$ISSUE_NUMBER"
+    else
+      gh issue close "$ISSUE_NUMBER" && step_ok "closed issue #$ISSUE_NUMBER" || step_fail "gh issue close #$ISSUE_NUMBER"
+    fi
+  fi
+fi
+
+# --- summary ---
+echo "" >&2
+if [ "$DRY_RUN" -eq 1 ]; then yellow "Dry run complete. $STEPS_OK/$STEPS_TOTAL steps would succeed."
+else green "Archive complete. $STEPS_OK/$STEPS_TOTAL steps succeeded."; fi
+if [ "$STEPS_OK" -lt "$STEPS_TOTAL" ]; then exit 1; fi
+exit 0

package/scripts/smart-env.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+# smart-env.sh — Smart skill script locator, bash resolver, and shared helpers.
+# Sourced by other smart-*.sh scripts and by the agent (per SKILL.md).
+# Sets: SMART_BASH, SMART_STATE, SMART_GUARD, SMART_HANDOFF, SMART_ARCHIVE,
+#       SMART_OPENSPEC_ROOT, SMART_CHANGES_DIR, SMART_DIR, SMART_SCRIPTS_DIR.
+# Provides shared helpers: colors, validate_change_name, validate_enum,
+#       validate_path_field, yaml_field, replace_yaml_field, strip_inline_comment,
+#       strip_wrapping_quotes, hash_stream, hash_file, file_nonempty.
+# 样板版本: v1  (keep in sync across all smart-*.sh and SKILL.md)
+
+# --- locate this file ---
+if [ -z "${SMART_ENV:-}" ]; then
+  if [ -n "${BASH_SOURCE[1]:-}" ]; then SMART_ENV="${BASH_SOURCE[1]}"
+  elif [ -n "${BASH_SOURCE[0]:-}" ]; then SMART_ENV="${BASH_SOURCE[0]}"
+  else SMART_ENV="$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/scripts/smart-env.sh' -type f -print -quit 2>/dev/null)"; fi
+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
+  echo "Expected path pattern: */scripts/smart-env.sh under project root or platform skill directories." >&2
+  return 1 2>/dev/null || exit 1
+fi
+
+SMART_SCRIPTS_DIR="$(cd "$(dirname "$SMART_ENV")" && pwd -P)"
+SMART_DIR="$(cd "$SMART_SCRIPTS_DIR/.." && pwd -P)"
+
+export SMART_STATE="${SMART_STATE:-$SMART_SCRIPTS_DIR/smart-state.sh}"
+export SMART_GUARD="${SMART_GUARD:-$SMART_SCRIPTS_DIR/smart-guard.sh}"
+export SMART_HANDOFF="${SMART_HANDOFF:-$SMART_SCRIPTS_DIR/smart-handoff.sh}"
+export SMART_ARCHIVE="${SMART_ARCHIVE:-$SMART_SCRIPTS_DIR/smart-archive.sh}"
+export SMART_OPENSPEC_ROOT="${SMART_OPENSPEC_ROOT:-openspec}"
+export SMART_CHANGES_DIR="${SMART_CHANGES_DIR:-$SMART_OPENSPEC_ROOT/changes}"
+export SMART_DIR
+export SMART_SCRIPTS_DIR
+
+# --- bash resolver (port of comet-env.sh; avoids Windows WSL bash.exe) ---
+_smart_bash_is_usable() {
+  local cand="$1"
+  [ -n "$cand" ] || return 1
+  case "$cand" in
+    */Windows/System32/bash.exe|*/windows/system32/bash.exe|*\\Windows\\System32\\bash.exe|*\\windows\\system32\\bash.exe) return 1 ;;
+  esac
+  "$cand" -lc 'printf smart-bash-ok' >/dev/null 2>&1
+}
+_smart_resolve_bash() {
+  local cand
+  if _smart_bash_is_usable "${SMART_BASH:-}"; then printf '%s\n' "$SMART_BASH"; return 0; fi
+  if _smart_bash_is_usable "${BASH:-}"; then printf '%s\n' "$BASH"; return 0; fi
+  cand="$(command -v sh 2>/dev/null | awk '{ sub(/\/sh(\.exe)?$/, "/bash.exe"); print }')"
+  if _smart_bash_is_usable "$cand"; then printf '%s\n' "$cand"; return 0; fi
+  cand="$(command -v bash 2>/dev/null || true)"
+  if _smart_bash_is_usable "$cand"; then printf '%s\n' "$cand"; return 0; fi
+  return 1
+}
+SMART_BASH="$(_smart_resolve_bash || true)"
+export SMART_BASH
+
+_smart_env_missing=0
+[ -n "$SMART_BASH" ] || { echo "ERROR: usable bash not found. Install Git Bash or set SMART_BASH. Windows WSL launcher bash.exe is not supported." >&2; _smart_env_missing=1; }
+for _s in "$SMART_STATE" "$SMART_GUARD" "$SMART_HANDOFF" "$SMART_ARCHIVE"; do
+  [ -f "$_s" ] || { echo "WARN: expected script not found: $_s" >&2; }
+done
+unset _s _smart_env_missing
+unset -f _smart_bash_is_usable _smart_resolve_bash
+
+# --- shared color helpers ---
+red()    { printf '\033[31m%s\033[0m\n' "$1" >&2; }
+green()  { printf '\033[32m%s\033[0m\n' "$1" >&2; }
+yellow() { printf '\033[33m%s\033[0m\n' "$1" >&2; }
+warn()   { printf '\033[33m%s\033[0m\n' "$1" >&2; }
+
+# --- shared input validation (port of comet-state.sh) ---
+validate_change_name() {
+  local name="$1"
+  [ -n "$name" ] || { red "ERROR: Change name cannot be empty"; exit 1; }
+  [[ "$name" =~ ^[a-zA-Z0-9_-]+$ ]] || { red "ERROR: Invalid change name: '$name' (valid: a-z A-Z 0-9 - _)"; exit 1; }
+  [[ "$name" =~ \.\. ]] && { red "ERROR: Change name cannot contain '..' (path traversal not allowed)"; exit 1; }
+}
+validate_enum() {
+  local value="$1"; shift
+  local valid
+  for valid in "$@"; do [ "$value" = "$valid" ] && return 0; done
+  red "ERROR: Invalid value: '$value' (valid: $*)"; exit 1
+}
+validate_path_field() {
+  local value="$1" field="$2"
+  [ -z "$value" ] || [ "$value" = "null" ] && return 0
+  case "$value" in
+    /*|~*|[A-Za-z]:*|\\*) red "ERROR: $field must be a relative path within the repo: '$value'"; exit 1 ;;
+  esac
+  [[ "$value" =~ \.\. ]] && { red "ERROR: $field cannot contain '..' (path traversal): '$value'"; exit 1; }
+}
+
+# --- shared flat-YAML helpers (port of comet-state.sh; .smart.yaml is key: value) ---
+strip_inline_comment() {
+  local value="$1"
+  printf '%s\n' "$value" | awk -v squote="'" '
+    { out=""; quote=""
+      for (i=1; i<=length($0); i++) { c=substr($0,i,1)
+        if (quote=="") { if (c=="\""||c==squote) { quote=c } else if (c=="#" && (i==1||substr($0,i-1,1)~/[[:space:]]/)) { sub(/[[:space:]]+$/,"",out); print out; next } }
+        else if (c==quote) { quote="" }
+        out=out c }
+      print out }'
+}
+strip_wrapping_quotes() {
+  local value="$1"
+  case "$value" in
+    \"*\") printf '%s\n' "${value:1:${#value}-2}" ;;
+    \'*\") printf '%s\n' "${value:1:${#value}-2}" ;;
+    *) printf '%s\n' "$value" ;;
+  esac
+}
+# yaml_field <field> <yaml_file>  -> prints value (empty if missing)
+yaml_field() {
+  local field="$1" yaml_file="$2"
+  [ -f "$yaml_file" ] || return 0
+  local value
+  value=$(grep "^${field}:" "$yaml_file" 2>/dev/null | sed "s/^${field}: *//" || true)
+  value=$(strip_inline_comment "$value")
+  strip_wrapping_quotes "$value"
+}
+# replace_yaml_field <yaml_file> <field> <value>  -> read-modify-write, dedup keeping last
+replace_yaml_field() {
+  local yaml_file="$1" field="$2" value="$3" tmp_file
+  tmp_file=$(mktemp); chmod 600 "$tmp_file"
+  awk -v field="$field" -v value="$value" '
+    index($0, field ":") == 1 { $0 = field ": " value }
+    { buf[NR]=$0; keys[NR]=$0; sub(/:.*$/,"",keys[NR]); n=NR }
+    END { for (i=1;i<=n;i++) last[keys[i]]=i; for (i=1;i<=n;i++) if (last[keys[i]]==i) print buf[i] }
+  ' "$yaml_file" > "$tmp_file"
+  mv "$tmp_file" "$yaml_file"
+}
+
+# --- shared hash/file helpers ---
+hash_stream() {
+  if command -v sha256sum >/dev/null 2>&1; then sha256sum | awk '{print $1}'
+  elif command -v shasum >/dev/null 2>&1; then shasum -a 256 | awk '{print $1}'
+  else red "ERROR: sha256sum or shasum is required"; exit 1; fi
+}
+hash_file() {
+  local file="$1"
+  if command -v sha256sum >/dev/null 2>&1; then sha256sum "$file" | awk '{print $1}'
+  elif command -v shasum >/dev/null 2>&1; then shasum -a 256 "$file" | awk '{print $1}'
+  else red "ERROR: sha256sum or shasum is required"; exit 1; fi
+}
+file_nonempty() { [ -f "$1" ] && [ -s "$1" ]; }

package/scripts/smart-guard.sh

@@ -0,0 +1,214 @@
+#!/usr/bin/env bash
+# smart-guard.sh — phase exit-condition guard for the Smart skill.
+# Usage: smart-guard.sh <change-name> <issue|design|build|verify|archive> [--apply]
+# --apply: if checks pass, advance phase via smart-state transition.
+# 样板版本: v1
+# v1: set -uo pipefail (no -e; explicit exit 1 + `&&` shorthand). v1.1: if-blocks + set -e.
+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"
+
+CHANGE="$1"; PHASE="$2"; APPLY=0
+validate_change_name "$CHANGE"
+[ "${3:-}" = "--apply" ] && APPLY=1
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd -P)"
+CHANGE_DIR="openspec/changes/$CHANGE"
+[ "$PHASE" = "archive" ] && [ ! -d "$CHANGE_DIR" ] && [ -d "openspec/changes/archive/$CHANGE" ] && CHANGE_DIR="openspec/changes/archive/$CHANGE"
+
+# local convenience: read field from this change's .smart.yaml
+yaml_field_value() { local f="$1"; yaml_field "$f" "$CHANGE_DIR/.smart.yaml"; }
+
+project_config_value() {
+  local field="$1" value
+  value=$(yaml_field_value "$field" 2>/dev/null || true)
+  { [ -n "$value" ] && [ "$value" != "null" ]; } && { echo "$value"; return 0; }
+  for cfg in ".smart/config.yaml" ".smart.yaml" ".smart.yml"; do
+    if [ -f "$cfg" ]; then value=$(yaml_field "$field" "$cfg"); { [ -n "$value" ] && [ "$value" != "null" ]; } && { echo "$value"; return 0; }; fi
+  done
+}
+
+# --- check primitives ---
+BLOCK=0
+check() { local desc="$1"; shift; local out; if out=$("$@" 2>&1); then green "  [PASS] $desc"; else red "  [FAIL] $desc"; printf '%s\n' "$out" | sed 's/^/    /' >&2; BLOCK=1; fi; }
+
+tasks_all_done() {
+  local tasks="$CHANGE_DIR/tasks.md"
+  [ -f "$tasks" ] || { echo "tasks.md missing at $tasks" >&2; return 1; }
+  grep -q '\- \[x\]' "$tasks" || { echo "tasks.md has no completed tasks" >&2; return 1; }
+  if grep -q '\- \[ \]' "$tasks"; then echo "Unfinished tasks:" >&2; grep -n '\- \[ \]' "$tasks" >&2 || true; return 1; fi
+}
+tasks_has_any() { [ -f "$CHANGE_DIR/tasks.md" ] && grep -q '\- \[' "$CHANGE_DIR/tasks.md"; }
+plan_tasks_all_done() {
+  local plan; plan=$(yaml_field_value "plan" 2>/dev/null || true)
+  [ -z "$plan" ] || [ "$plan" = "null" ] && return 0
+  [ -f "$plan" ] || { echo "plan file missing: $plan" >&2; return 1; }
+  ! grep -q '^[[:space:]]*- \[ \]' "$plan"
+}
+
+# --- handoff hash + traceability ---
+handoff_source_files() {
+  printf '%s\n' "$CHANGE_DIR/proposal.md" "$CHANGE_DIR/design.md" "$CHANGE_DIR/tasks.md"
+  [ -d "$CHANGE_DIR/specs" ] && find "$CHANGE_DIR/specs" -path '*/spec.md' -type f 2>/dev/null | sort
+}
+compute_handoff_hash() {
+  local inp; inp=$(handoff_source_files | while IFS= read -r f; do [ -f "$f" ] && { printf 'path:%s\n' "$f"; printf 'sha256:%s\n' "$(hash_file "$f")"; }; done)
+  printf '%s' "$inp" | hash_stream
+}
+design_handoff_context_valid() {
+  local context recorded_hash actual_hash markdown
+  context=$(yaml_field_value "handoff_context"); recorded_hash=$(yaml_field_value "handoff_hash")
+  { [ -n "$context" ] && [ "$context" != "null" ]; } || { echo "handoff_context missing" >&2; return 1; }
+  [ -s "$context" ] || { echo "handoff_context not non-empty: $context" >&2; return 1; }
+  [[ "$recorded_hash" =~ ^[a-f0-9]{64}$ ]] || { echo "handoff_hash missing/invalid: ${recorded_hash:-null}" >&2; return 1; }
+  actual_hash=$(compute_handoff_hash)
+  [ "$actual_hash" = "$recorded_hash" ] || { echo "OpenSpec artifacts changed after handoff. expected=$recorded_hash actual=$actual_hash" >&2; return 1; }
+  markdown="${context%.json}.md"; [ -s "$markdown" ] || { echo "handoff markdown missing/empty: $markdown" >&2; return 1; }
+}
+design_handoff_markdown_traceable() {
+  local context markdown missing=0
+  context=$(yaml_field_value "handoff_context"); [ -n "$context" ] && [ "$context" != "null" ] || { echo "handoff_context missing" >&2; return 1; }
+  markdown="${context%.json}.md"; [ -s "$markdown" ] || { echo "handoff markdown missing: $markdown" >&2; return 1; }
+  grep -q '^Generated-by: smart-handoff\.sh$' "$markdown" || { echo "markdown missing Generated-by marker" >&2; missing=1; }
+  grep -Eq '^- Mode: (compact|full|beta)$' "$markdown" || { echo "markdown missing Mode marker" >&2; missing=1; }
+  handoff_source_files | while IFS= read -r f; do [ -f "$f" ] || continue
+    grep -q "^- Source: $f$" "$markdown" || { echo "markdown missing source ref: $f" >&2; exit 2; }
+    grep -q "^- SHA256: $(hash_file "$f")$" "$markdown" || { echo "markdown missing sha256 for: $f" >&2; exit 2; }
+  done || missing=1
+  [ "$missing" -eq 0 ]
+}
+
+# --- build / verify commands (lenient for skill repos: skip if no build system) ---
+is_windows_bash() { case "$(uname -s 2>/dev/null || true)" in MINGW*|MSYS*|CYGWIN*) return 0 ;; *) return 1 ;; esac; }
+run_command_string() {
+  local cmd="$1"; [ -n "$cmd" ] || { red "ERROR: build/verify command empty"; return 1; }
+  [[ "$cmd" =~ [\;\|\&\$\`] ]] && { red "ERROR: command contains shell metacharacters: $cmd"; return 1; }
+  echo "+ $cmd" >&2; "$SMART_BASH" -lc "$cmd"
+}
+build_passes() {
+  if [ "${SMART_SKIP_BUILD:-0}" = "1" ]; then return 0; fi
+  local cb; cb=$(project_config_value "build_command"); if [ -n "$cb" ]; then run_command_string "$cb"; 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 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
+  warn "  [WARN] no build system detected; skipping build check (skill repo)"
+  return 0
+}
+verification_command_passes() {
+  if [ "${SMART_SKIP_BUILD:-0}" = "1" ]; then return 0; fi
+  local cv; cv=$(project_config_value "verify_command"); if [ -n "$cv" ]; then run_command_string "$cv"; return $?; fi
+  build_passes
+}
+
+# --- design doc frontmatter ---
+design_doc_frontmatter_has() { local doc="$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}' "$doc" | grep -Eq "^${field}: ['\"]?${expected}['\"]?[[:space:]]*$"
+}
+design_doc_links_current_change() { local dd; dd=$(yaml_field_value "design_doc"); { [ -n "$dd" ] && [ "$dd" != "null" ] && [ -s "$dd" ]; } || { echo "design_doc must point to existing Design Doc" >&2; return 1; }; design_doc_frontmatter_has "$dd" "smart_change" "$CHANGE"; }
+design_doc_declares_technical_role() { local dd; dd=$(yaml_field_value "design_doc"); { [ -n "$dd" ] && [ "$dd" != "null" ] && [ -s "$dd" ]; } && design_doc_frontmatter_has "$dd" "role" "technical-design"; }
+design_doc_declares_canonical_spec() { local dd; dd=$(yaml_field_value "design_doc"); { [ -n "$dd" ] && [ "$dd" != "null" ] && [ -s "$dd" ]; } && design_doc_frontmatter_has "$dd" "canonical_spec" "openspec"; }
+design_doc_recorded() { local dd; dd=$(yaml_field_value "design_doc"); { [ -n "$dd" ] && [ "$dd" != "null" ] && [ -f "$dd" ]; } && return 0; echo "design_doc must point to existing Design Doc (full workflow)" >&2; return 1; }
+
+# --- decision selectors (reused from comet) ---
+isolation_selected() { local i; i=$(yaml_field_value "isolation"); case "$i" in branch|worktree) return 0 ;; *) echo "isolation must be branch|worktree, got '${i:-null}'" >&2; return 1 ;; esac; }
+build_mode_selected() { local b; b=$(yaml_field_value "build_mode"); case "$b" in subagent-driven-development|executing-plans|direct) return 0 ;; *) echo "build_mode must be selected, got '${b:-null}'" >&2; return 1 ;; esac; }
+build_mode_allowed_for_workflow() { local w b d; w=$(yaml_field_value "workflow"); b=$(yaml_field_value "build_mode"); d=$(yaml_field_value "direct_override"); [ "$b" != "direct" ] && return 0; case "$w" in hotfix|tweak) return 0 ;; *) [ "$d" = "true" ] && return 0; echo "build_mode=direct only for hotfix/tweak unless direct_override=true" >&2; return 1 ;; esac; }
+subagent_dispatch_confirmed() { local b s; b=$(yaml_field_value "build_mode"); s=$(yaml_field_value "subagent_dispatch"); [ "$b" != "subagent-driven-development" ] && return 0; [ "$s" = "confirmed" ] && return 0; echo "subagent_dispatch must be confirmed for subagent-driven-development" >&2; return 1; }
+tdd_mode_selected() { local w t; w=$(yaml_field_value "workflow"); t=$(yaml_field_value "tdd_mode"); case "$w" in hotfix|tweak) return 0 ;; esac; case "$t" in tdd|direct) return 0 ;; *) echo "tdd_mode must be tdd|direct, got '${t:-null}'" >&2; return 1 ;; esac; }
+review_mode_selected() { local w r; w=$(yaml_field_value "workflow"); r=$(yaml_field_value "review_mode"); case "$w" in hotfix|tweak) return 0 ;; esac; case "$r" in off|standard|thorough) return 0 ;; *) echo "review_mode must be off|standard|thorough, got '${r:-null}'" >&2; return 1 ;; esac; }
+verification_report_exists() { local r; r=$(yaml_field_value "verification_report"); [ -n "$r" ] && [ "$r" != "null" ] && [ -f "$r" ]; }
+branch_status_handled() { local s; s=$(yaml_field_value "branch_status"); [ "$s" = "handled" ]; }
+archived_is_true() { local v; v=$(yaml_field_value "archived"); [ "$v" = "true" ]; }
+
+# --- phase guards ---
+preflight() {
+  [ -d "$CHANGE_DIR" ] || { red "FATAL: change directory not found: $CHANGE_DIR"; exit 1; }
+  [ -f "$CHANGE_DIR/.smart.yaml" ] || { red "FATAL: .smart.yaml not found in $CHANGE_DIR"; exit 1; }
+}
+guard_issue() {
+  echo "=== Guard: issue -> next ===" >&2
+  local workflow; workflow=$(yaml_field_value "workflow")
+  check "proposal.md non-empty" file_nonempty "$CHANGE_DIR/proposal.md"
+  if [ "$workflow" = "full" ]; then check "design.md non-empty" file_nonempty "$CHANGE_DIR/design.md"; fi
+  check "tasks.md non-empty" file_nonempty "$CHANGE_DIR/tasks.md"
+  check "tasks.md has a task" tasks_has_any
+}
+guard_design() {
+  echo "=== Guard: design -> build ===" >&2
+  local design_doc workflow
+  design_doc=$(yaml_field_value "design_doc"); workflow=$(yaml_field_value "workflow")
+  check "proposal.md exists" file_nonempty "$CHANGE_DIR/proposal.md"
+  check "design.md exists" file_nonempty "$CHANGE_DIR/design.md"
+  check "tasks.md exists" file_nonempty "$CHANGE_DIR/tasks.md"
+  check "design handoff context valid" design_handoff_context_valid
+  check "design handoff markdown traceable" design_handoff_markdown_traceable
+  if [ "$workflow" = "full" ]; then check "design_doc recorded (full)" design_doc_recorded; fi
+  if [ -n "$design_doc" ] && [ "$design_doc" != "null" ]; then
+    check "Design Doc exists" file_nonempty "$design_doc"
+    check "Design Doc links current change" design_doc_links_current_change
+    check "Design Doc declares technical-design role" design_doc_declares_technical_role
+    check "Design Doc declares openspec canonical spec" design_doc_declares_canonical_spec
+  elif [ "$workflow" != "full" ]; then warn "  [WARN] No design_doc (optional for hotfix/tweak)"; fi
+}
+guard_build() {
+  echo "=== Guard: build -> verify ===" >&2
+  check "isolation selected" isolation_selected
+  check "build_mode selected" build_mode_selected
+  check "build_mode allowed for workflow" build_mode_allowed_for_workflow
+  check "subagent dispatch confirmed" subagent_dispatch_confirmed
+  check "tdd_mode selected" tdd_mode_selected
+  check "review_mode selected" review_mode_selected
+  check "tasks.md all checked" tasks_all_done
+  check "plan tasks all checked" plan_tasks_all_done
+  check "proposal.md exists" file_nonempty "$CHANGE_DIR/proposal.md"
+  check "Build passes" build_passes
+}
+guard_verify() {
+  echo "=== Guard: verify -> archive ===" >&2
+  check "tasks.md all checked" tasks_all_done
+  check "verify command passes" verification_command_passes
+  check "verification_report exists" verification_report_exists
+  check "branch_status=handled" branch_status_handled
+}
+guard_archive() {
+  echo "=== Guard: archive completeness ===" >&2
+  check "archived is true" archived_is_true
+  check "proposal.md exists" file_nonempty "$CHANGE_DIR/proposal.md"
+  check "design.md exists" file_nonempty "$CHANGE_DIR/design.md"
+  check "tasks.md all checked" tasks_all_done
+}
+
+apply_state_update() {
+  local p="$1"
+  case "$p" in
+    issue) "$SMART_BASH" "$SMART_STATE" transition "$CHANGE" issue-complete ;;
+    design) "$SMART_BASH" "$SMART_STATE" transition "$CHANGE" design-complete ;;
+    build)  "$SMART_BASH" "$SMART_STATE" transition "$CHANGE" build-complete ;;
+    verify) "$SMART_BASH" "$SMART_STATE" transition "$CHANGE" verify-pass ;;
+  esac
+}
+
+case "$PHASE" in
+  issue)  preflight; guard_issue ;;
+  design)  preflight; guard_design ;;
+  build)   preflight; guard_build ;;
+  verify)  preflight; guard_verify ;;
+  archive) preflight; guard_archive ;;
+  *) red "Unknown phase: $PHASE"; echo "Valid: issue, design, build, verify, archive" >&2; exit 1 ;;
+esac
+
+if [ "$BLOCK" -eq 1 ]; then echo "" >&2; red "BLOCKED — fix failing checks before proceeding"; exit 1; fi
+echo "" >&2; green "ALL CHECKS PASSED — ready for next phase"
+if [ "$APPLY" -eq 1 ]; then
+  apply_state_update "$PHASE"
+  green "  [APPLY] .smart.yaml updated (phase advanced)"
+fi
+exit 0

package/scripts/smart-handoff.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# smart-handoff.sh — machine-owned context pack between phases.
+# Usage: smart-handoff.sh <change-name> design --write [--full]
+#        smart-handoff.sh <change-name> --hash-only
+# 样板版本: v1
+# v1: set -uo pipefail (no -e; explicit exit 1 + `&&` shorthand). v1.1: if-blocks + set -e.
+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"
+
+CHANGE="${1:-}"; PHASE="${2:-}"; MODE="${3:-}"; FULL_FLAG="${4:-}"
+validate_change_name "$CHANGE"
+
+json_escape() { printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'; }
+file_line_count() { wc -l < "$1" | tr -d ' '; }
+
+source_files() {
+  printf '%s\n' "$CHANGE_DIR/proposal.md" "$CHANGE_DIR/design.md" "$CHANGE_DIR/tasks.md"
+  [ -d "$CHANGE_DIR/specs" ] && find "$CHANGE_DIR/specs" -path '*/spec.md' -type f 2>/dev/null | sort
+}
+compute_context_hash() {
+  local inp; inp=$(source_files | while IFS= read -r f; do [ -f "$f" ] && { printf 'path:%s\n' "$f"; printf 'sha256:%s\n' "$(hash_file "$f")"; }; done)
+  printf '%s' "$inp" | hash_stream
+}
+
+# --hash-only
+if [ "${PHASE:-}" = "--hash-only" ]; then
+  CHANGE_DIR="openspec/changes/$CHANGE"
+  [ -d "$CHANGE_DIR" ] || { red "ERROR: change dir not found: $CHANGE_DIR"; exit 1; }
+  for req in proposal.md design.md tasks.md; do [ -s "$CHANGE_DIR/$req" ] || { red "ERROR: required file missing/empty: $req"; exit 1; }; done
+  compute_context_hash; exit 0
+fi
+
+[ "$PHASE" = "design" ] && [ "$MODE" = "--write" ] || { red "Usage: smart-handoff.sh <change-name> design --write [--full]"; red "       smart-handoff.sh <change-name> --hash-only"; exit 1; }
+case "$FULL_FLAG" in "") HANDOFF_MODE="compact" ;; --full) HANDOFF_MODE="full" ;; *) red "Usage: smart-handoff.sh <change> design --write [--full]"; exit 1 ;; esac
+
+CHANGE_DIR="openspec/changes/$CHANGE"
+YAML="$CHANGE_DIR/.smart.yaml"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd -P)"
+STATE_SH="$SCRIPT_DIR/smart-state.sh"
+[ -d "$CHANGE_DIR" ] || { red "ERROR: change dir not found: $CHANGE_DIR"; exit 1; }
+[ -f "$YAML" ] || { red "ERROR: .smart.yaml not found at $YAML"; exit 1; }
+[ "$(yaml_field phase "$YAML")" = "design" ] || { red "ERROR: design handoff requires phase: design"; exit 1; }
+for req in proposal.md design.md tasks.md; do [ -s "$CHANGE_DIR/$req" ] || { red "ERROR: required artifact missing/empty: $req"; exit 1; }; done
+
+HANDOFF_DIR="$CHANGE_DIR/.smart/handoff"
+CONTEXT_COMPRESSION="$(yaml_field context_compression "$YAML" 2>/dev/null || true)"; CONTEXT_COMPRESSION="${CONTEXT_COMPRESSION:-off}"
+case "$CONTEXT_COMPRESSION" in
+  off) CONTEXT_JSON="$HANDOFF_DIR/design-context.json"; CONTEXT_MD="$HANDOFF_DIR/design-context.md" ;;
+  beta) [ "$HANDOFF_MODE" = "full" ] && warn "[HANDOFF] --full ignored in beta mode"; HANDOFF_MODE="beta"; CONTEXT_JSON="$HANDOFF_DIR/spec-context.json"; CONTEXT_MD="$HANDOFF_DIR/spec-context.md" ;;
+  *) red "ERROR: invalid context_compression: $CONTEXT_COMPRESSION (off|beta)"; exit 1 ;;
+esac
+mkdir -p "$HANDOFF_DIR"
+CONTEXT_HASH="$(compute_context_hash)"
+
+write_file_excerpt() {
+  local file="$1" max="$2" total; total=$(file_line_count "$file")
+  echo "## $file"; echo ""
+  echo "- Source: $file"; echo "- Lines: 1-$total"; echo "- SHA256: $(hash_file "$file")"; echo ""
+  if [ "$HANDOFF_MODE" = "full" ] || [ "$total" -le "$max" ]; then echo '```md'; cat "$file"; echo '```'; else echo "[TRUNCATED]"; echo ""; echo '```md'; sed -n "1,${max}p" "$file"; echo '```'; echo ""; echo "Full source: $file"; fi
+  echo ""
+}
+write_markdown_context() {
+  local out="$1"
+  { echo "# Smart Design Handoff"; echo ""
+    echo "- Change: $CHANGE"; echo "- Phase: design"; echo "- Mode: $HANDOFF_MODE"; echo "- Context hash: $CONTEXT_HASH"; echo ""
+    echo "Generated-by: smart-handoff.sh"; echo ""
+    echo "OpenSpec remains the canonical capability spec. This handoff is a deterministic, source-traceable context pack, not an agent-authored summary."; echo ""
+    source_files | while IFS= read -r f; do [ -f "$f" ] && write_file_excerpt "$f" 80; done
+  } > "$out"
+}
+write_json_context() {
+  local out="$1"
+  { echo "{"
+    echo "  \"change\": \"$(json_escape "$CHANGE")\","
+    echo "  \"phase\": \"design\","
+    echo "  \"mode\": \"$HANDOFF_MODE\","
+    echo "  \"canonical_spec\": \"openspec\","
+    echo "  \"generated_by\": \"smart-handoff.sh\","
+    echo "  \"context_hash\": \"$CONTEXT_HASH\","
+    echo "  \"files\": ["
+    local first=1; while IFS= read -r f; do [ -f "$f" ] || continue; [ "$first" -eq 0 ] && echo ","; first=0; printf '    { "path": "%s", "sha256": "%s" }' "$(json_escape "$f")" "$(hash_file "$f")"; done < <(source_files)
+    echo ""; echo "  ]"; echo "}"
+  } > "$out"
+}
+write_spec_projection_for_file() { local f="$1"; echo "## $f"; echo "- Source: $f"; echo "- Lines: 1-$(file_line_count "$f")"; echo "- SHA256: $(hash_file "$f")"; echo ""; echo '```md'; cat "$f"; echo '```'; echo ""; }
+write_spec_markdown_context() {
+  local out="$1"
+  { echo "# Smart Spec Context"; echo "- Change: $CHANGE"; echo "- Phase: design"; echo "- Mode: beta"; echo "- Context hash: $CONTEXT_HASH"; echo ""; echo "Generated-by: smart-handoff.sh"; echo ""
+    echo "OpenSpec remains canonical. This beta context pack verbatim-projects spec files and references supporting artifacts by hash."; echo ""
+    echo "## Source References"; echo ""; source_files | while IFS= read -r f; do [ -f "$f" ] && { echo "- Source: $f"; echo "- SHA256: $(hash_file "$f")"; }; done; echo ""
+    echo "## Acceptance Projection"; echo ""
+    if [ -d "$CHANGE_DIR/specs" ]; then find "$CHANGE_DIR/specs" -path '*/spec.md' -type f 2>/dev/null | sort | while IFS= read -r f; do write_spec_projection_for_file "$f"; done; else echo "No delta spec files found."; echo ""; fi
+    echo "Full source files remain canonical."
+  } > "$out"
+}
+write_spec_json_context() {
+  local out="$1"
+  { echo "{"
+    echo "  \"change\": \"$(json_escape "$CHANGE")\","
+    echo "  \"phase\": \"design\","
+    echo "  \"mode\": \"beta\","
+    echo "  \"canonical_spec\": \"openspec\","
+    echo "  \"generated_by\": \"smart-handoff.sh\","
+    echo "  \"context_hash\": \"$CONTEXT_HASH\","
+    echo "  \"files\": ["
+    local first=1; while IFS= read -r f; do [ -f "$f" ] || continue; local role="supporting"; case "$f" in */specs/*/spec.md) role="spec" ;; esac; [ "$first" -eq 0 ] && echo ","; first=0; printf '    { "path": "%s", "sha256": "%s", "role": "%s" }' "$(json_escape "$f")" "$(hash_file "$f")" "$role"; done < <(source_files)
+    echo ""; echo "  ]"; echo "}"
+  } > "$out"
+}
+
+if [ "$CONTEXT_COMPRESSION" = "beta" ]; then write_spec_markdown_context "$CONTEXT_MD"; write_spec_json_context "$CONTEXT_JSON"; else write_markdown_context "$CONTEXT_MD"; write_json_context "$CONTEXT_JSON"; fi
+
+if [ -f "$STATE_SH" ]; then
+  "$SMART_BASH" "$STATE_SH" set "$CHANGE" handoff_context "$CONTEXT_JSON" >/dev/null
+  "$SMART_BASH" "$STATE_SH" set "$CHANGE" handoff_hash "$CONTEXT_HASH" >/dev/null
+else red "ERROR: smart-state.sh not found; cannot record handoff fields"; exit 1; fi
+green "[HANDOFF] wrote $CONTEXT_JSON"; green "[HANDOFF] wrote $CONTEXT_MD"; green "[HANDOFF] handoff_hash=$CONTEXT_HASH"