specline 1.3.4 → 2.0.0

package/core/gates/pipeline-gate.sh

@@ -0,0 +1,1456 @@
+#!/usr/bin/env bash
+#
+# specline-pipeline-gate.sh — 确定性门禁脚本（零 LLM 参与）
+#
+# Usage:
+#   specline-pipeline-gate.sh <phase> --change <change-name>
+#
+# Phases:
+#   new | list | artifacts | spec | semantic | build | lint | test-unit | test-integration | test-e2e | detect-modules | bind | archive | status
+#
+# Exit codes:
+#   0 = 通过
+#   1 = 失败
+#   2 = 输入参数错误
+
+set -euo pipefail
+
+PHASE="${1:-}"
+CHANGE=""
+EXECUTE_ARCHIVE=""
+POSITIONAL_ARGS=()
+
+# 遍历所有参数，不依赖位置
+shift  # 跳过 PHASE
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --change)
+      CHANGE="$2"
+      shift 2
+      ;;
+    --execute)
+      EXECUTE_ARCHIVE="--execute"
+      shift
+      ;;
+    *)
+      POSITIONAL_ARGS+=("$1")
+      shift
+      ;;
+  esac
+done
+# ===== 项目根目录 =====
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# ===== 状态文件 =====
+if [ -n "$CHANGE" ]; then
+  STATE_FILE="$PROJECT_ROOT/specline/changes/$CHANGE/.pipeline-state.json"
+else
+  STATE_FILE=""
+fi
+
+# ===== 辅助函数 =====
+now_iso8601() {
+  date -u +"%Y-%m-%dT%H:%M:%SZ"
+}
+
+write_gate_passed() {
+  local gate_path="$1"  # e.g., "phases.spec.gates.spec_gate"
+  if [ -n "$STATE_FILE" ] && [ -f "$STATE_FILE" ]; then
+    local time
+    time=$(now_iso8601)
+    jq --arg time "$time" \
+      ".updated_at = \$time | .${gate_path} = { \"passed\": true, \"run_at\": \$time }" \
+      "$STATE_FILE" > "$STATE_FILE.tmp" && mv "$STATE_FILE.tmp" "$STATE_FILE"
+  fi
+}
+
+fail() {
+  echo "❌ $1" >&2
+  exit 1
+}
+
+pass() {
+  echo "✅ $1"
+}
+
+# ===== 获取 Spec 文件路径 =====
+find_spec_file() {
+  if [ -z "$CHANGE" ]; then
+    echo ""
+    return
+  fi
+  find "$PROJECT_ROOT/specline/changes/$CHANGE/specs" -name "spec.md" 2>/dev/null | head -1
+}
+
+MODULES_JSON=""
+
+detect_project_modules() {
+  # 扫描 maxdepth 2 的语言标记文件，输出 JSON 数组
+  # 格式: [{"path":"backend/","language":"go"},{"path":"frontend/","language":"typescript"}]
+  # 排除: node_modules/, .git/, vendor/, dist/
+
+  local modules='[]'
+
+  while IFS= read -r marker; do
+    [ -z "$marker" ] && continue
+    local dir
+    dir=$(dirname "$marker")
+    local rel_dir="${dir#$PROJECT_ROOT/}"
+    [ "$rel_dir" = "$dir" ] && rel_dir="."
+    [ "$rel_dir" != "." ] && rel_dir="${rel_dir}/"
+
+    case "$(basename "$marker")" in
+      go.mod)
+        modules=$(echo "$modules" | jq --arg p "$rel_dir" '. + [{"path":$p,"language":"go"}]')
+        ;;
+      Cargo.toml)
+        modules=$(echo "$modules" | jq --arg p "$rel_dir" '. + [{"path":$p,"language":"rust"}]')
+        ;;
+      pyproject.toml|setup.cfg|requirements.txt)
+        local exists
+        exists=$(echo "$modules" | jq --arg p "$rel_dir" '[.[] | select(.path == $p and .language == "python")] | length')
+        if [ "$exists" = "0" ]; then
+          modules=$(echo "$modules" | jq --arg p "$rel_dir" '. + [{"path":$p,"language":"python"}]')
+        fi
+        ;;
+      package.json)
+        if ! grep -q '"workspaces"' "$marker" 2>/dev/null; then
+          local lang="javascript"
+          [ -f "${dir}/tsconfig.json" ] && lang="typescript"
+          modules=$(echo "$modules" | jq --arg p "$rel_dir" --arg l "$lang" '. + [{"path":$p,"language":$l}]')
+        fi
+        ;;
+      pom.xml)
+        modules=$(echo "$modules" | jq --arg p "$rel_dir" '. + [{"path":$p,"language":"java"}]')
+        ;;
+      build.gradle|build.gradle.kts)
+        local exists
+        exists=$(echo "$modules" | jq --arg p "$rel_dir" '[.[] | select(.path == $p)] | length')
+        if [ "$exists" = "0" ]; then
+          modules=$(echo "$modules" | jq --arg p "$rel_dir" '. + [{"path":$p,"language":"kotlin"}]')
+        fi
+        ;;
+    esac
+  done < <(find "$PROJECT_ROOT" -maxdepth 2 \
+    \( -name "go.mod" -o -name "package.json" -o -name "Cargo.toml" \
+       -o -name "pyproject.toml" -o -name "setup.cfg" -o -name "requirements.txt" \
+       -o -name "pom.xml" -o -name "build.gradle" -o -name "build.gradle.kts" \) \
+    -not -path "*/node_modules/*" -not -path "*/.git/*" \
+    -not -path "*/vendor/*" -not -path "*/dist/*" -not -path "*/.tmp*/*" -not -path "*/.tmp-*" 2>/dev/null)
+
+  echo "$modules"
+}
+
+load_project_config() {
+  local config_file="$PROJECT_ROOT/specline/config.yaml"
+  MODULES_JSON=""
+
+  if [ -f "$config_file" ] && grep -q '^project:' "$config_file" 2>/dev/null; then
+    if grep -q '^    - path:' "$config_file" 2>/dev/null; then
+      MODULES_JSON=$(awk '
+        /^  modules:/ { in_modules=1; next }
+        /^  [a-z]/ && !/^    / { in_modules=0 }
+        /^[a-z]/ { in_modules=0 }
+        in_modules && /^    - path:/ {
+          if (path != "") printf ","
+          path=$NF; gsub(/["'\'']/, "", path)
+          printf "{\"path\":\"%s\"", path
+        }
+        in_modules && /^      language:/ {
+          lang=$NF; gsub(/["'\'']/, "", lang)
+          printf ",\"language\":\"%s\"}", lang
+        }
+      ' "$config_file")
+      if [ -n "$MODULES_JSON" ]; then
+        MODULES_JSON="[${MODULES_JSON}]"
+      fi
+    fi
+  fi
+
+  if [ -z "$MODULES_JSON" ] || [ "$MODULES_JSON" = "[]" ]; then
+    MODULES_JSON=$(detect_project_modules)
+  fi
+}
+
+module_absolute_path() {
+  local rel_path="$1"
+  if [ "$rel_path" = "." ] || [ "$rel_path" = "./" ]; then
+    echo "$PROJECT_ROOT"
+  else
+    echo "$PROJECT_ROOT/${rel_path%/}"
+  fi
+}
+
+module_has_eslint_config() {
+  local mod_dir="$1"
+  local f
+  for f in eslint.config.js eslint.config.mjs eslint.config.cjs .eslintrc.js .eslintrc.cjs .eslintrc.json; do
+    [ -f "$mod_dir/$f" ] && return 0
+  done
+  return 1
+}
+
+build_module() {
+  local rel_path="$1"
+  local lang="$2"
+  local mod_dir
+  mod_dir=$(module_absolute_path "$rel_path")
+
+  case "$lang" in
+    go)
+      echo "正在 build Go 模块: $rel_path"
+      if ! (cd "$mod_dir" && go build ./...); then
+        fail "Go build 失败 ($rel_path)"
+      fi
+      ;;
+    typescript)
+      echo "正在 build TypeScript 模块: $rel_path"
+      if ! (cd "$mod_dir" && npx tsc --noEmit); then
+        fail "TypeScript 编译失败 ($rel_path)"
+      fi
+      ;;
+    javascript)
+      echo "ℹ️  JavaScript 模块 $rel_path 无 compile 步骤，跳过 build"
+      ;;
+    python)
+      echo "正在检查 Python 语法: $rel_path"
+      if ! (cd "$mod_dir" && python3 -m compileall -q .); then
+        fail "Python 语法错误 ($rel_path)"
+      fi
+      ;;
+    rust)
+      echo "正在 build Rust 模块: $rel_path"
+      if ! (cd "$mod_dir" && cargo build); then
+        fail "Rust build 失败 ($rel_path)"
+      fi
+      ;;
+    java)
+      echo "正在 build Java 模块: $rel_path"
+      if ! (cd "$mod_dir" && mvn compile -q); then
+        fail "Java build 失败 ($rel_path)"
+      fi
+      ;;
+    kotlin)
+      echo "正在 build Kotlin 模块: $rel_path"
+      if [ -f "$mod_dir/build.gradle.kts" ] || [ -f "$mod_dir/build.gradle" ]; then
+        if ! (cd "$mod_dir" && ./gradlew compileKotlin -q 2>/dev/null || gradle compileKotlin -q); then
+          fail "Kotlin build 失败 ($rel_path)"
+        fi
+      fi
+      ;;
+    *)
+      echo "⚠️  未知语言 '$lang' ($rel_path)，跳过 build"
+      ;;
+  esac
+}
+
+lint_module() {
+  local rel_path="$1"
+  local lang="$2"
+  local mod_dir
+  mod_dir=$(module_absolute_path "$rel_path")
+
+  case "$lang" in
+    go)
+      echo "正在 lint Go 模块: $rel_path"
+      if command -v go &>/dev/null; then
+        if ! (cd "$mod_dir" && go vet ./...); then
+          fail "Go vet 失败 ($rel_path)"
+        fi
+        if command -v golangci-lint &>/dev/null; then
+          if ! (cd "$mod_dir" && golangci-lint run ./...); then
+            fail "golangci-lint 失败 ($rel_path)"
+          fi
+        fi
+      else
+        echo "⚠️  go 未安装，跳过 Go lint ($rel_path)"
+      fi
+      ;;
+    typescript|javascript)
+      if module_has_eslint_config "$mod_dir"; then
+        echo "正在 lint JS/TS 模块: $rel_path"
+        if command -v npx &>/dev/null; then
+          if ! (cd "$mod_dir" && npx eslint . --quiet); then
+            fail "ESLint 失败 ($rel_path)"
+          fi
+        fi
+      else
+        echo "ℹ️  模块 $rel_path 无 eslint 配置，跳过 JS/TS lint"
+      fi
+      ;;
+    python)
+      if command -v ruff &>/dev/null; then
+        echo "正在 lint Python 模块: $rel_path"
+        if ! (cd "$mod_dir" && ruff check . --quiet); then
+          fail "Python lint 失败 ($rel_path)"
+        fi
+      else
+        echo "⚠️  ruff 未安装，跳过 Python lint ($rel_path)"
+      fi
+      ;;
+    rust)
+      echo "正在 lint Rust 模块: $rel_path"
+      if ! (cd "$mod_dir" && cargo clippy -- -D warnings 2>/dev/null || cargo clippy); then
+        fail "Rust clippy 失败 ($rel_path)"
+      fi
+      ;;
+    java|kotlin)
+      echo "ℹ️  Java/Kotlin lint 暂未集成 ($rel_path)，跳过"
+      ;;
+    *)
+      echo "⚠️  未知语言 '$lang' ($rel_path)，跳过 lint"
+      ;;
+  esac
+}
+
+run_default_unit_test() {
+  local rel_path="$1"
+  local lang="$2"
+  local mod_dir
+  mod_dir=$(module_absolute_path "$rel_path")
+
+  case "$lang" in
+    go)
+      echo "正在执行 Go 单元测试: $rel_path"
+      if ! (cd "$mod_dir" && go test ./...); then
+        fail "Go 单元测试失败 ($rel_path)"
+      fi
+      ;;
+    python)
+      echo "正在执行 Python 单元测试: $rel_path"
+      if ! (cd "$mod_dir" && pytest); then
+        fail "Python 单元测试失败 ($rel_path)"
+      fi
+      ;;
+    typescript|javascript)
+      if [ -f "$mod_dir/package.json" ]; then
+        if grep -q '"vitest"' "$mod_dir/package.json" 2>/dev/null; then
+          echo "正在执行 Vitest 单元测试: $rel_path"
+          if ! (cd "$mod_dir" && npx vitest run); then
+            fail "Vitest 单元测试失败 ($rel_path)"
+          fi
+        elif grep -q '"jest"' "$mod_dir/package.json" 2>/dev/null; then
+          echo "正在执行 Jest 单元测试: $rel_path"
+          if ! (cd "$mod_dir" && npx jest); then
+            fail "Jest 单元测试失败 ($rel_path)"
+          fi
+        else
+          echo "⚠️  模块 $rel_path 未检测到 vitest/jest，跳过单元测试"
+        fi
+      fi
+      ;;
+    rust)
+      echo "正在执行 Rust 单元测试: $rel_path"
+      if ! (cd "$mod_dir" && cargo test); then
+        fail "Rust 单元测试失败 ($rel_path)"
+      fi
+      ;;
+    java)
+      echo "正在执行 Java 单元测试: $rel_path"
+      if [ -f "$mod_dir/pom.xml" ]; then
+        if ! (cd "$mod_dir" && mvn test -q); then
+          fail "Java 单元测试失败 ($rel_path)"
+        fi
+      fi
+      ;;
+    kotlin)
+      echo "正在执行 Kotlin 单元测试: $rel_path"
+      if [ -f "$mod_dir/build.gradle.kts" ] || [ -f "$mod_dir/build.gradle" ]; then
+        if ! (cd "$mod_dir" && ./gradlew test -q 2>/dev/null || gradle test -q); then
+          fail "Kotlin 单元测试失败 ($rel_path)"
+        fi
+      fi
+      ;;
+    *)
+      echo "⚠️  未知语言 '$lang' ($rel_path)，跳过单元测试"
+      ;;
+  esac
+}
+
+run_default_integration_test() {
+  local rel_path="$1"
+  local lang="$2"
+  local mod_dir
+  mod_dir=$(module_absolute_path "$rel_path")
+
+  case "$lang" in
+    go)
+      echo "正在执行 Go 集成测试: $rel_path"
+      if ! (cd "$mod_dir" && go test ./...); then
+        fail "Go 集成测试失败 ($rel_path)"
+      fi
+      ;;
+    python)
+      if [ -d "$mod_dir/tests/integration" ]; then
+        echo "正在执行 Python 集成测试: $rel_path"
+        if ! (cd "$mod_dir" && pytest tests/integration -v); then
+          fail "Python 集成测试失败 ($rel_path)"
+        fi
+      else
+        echo "ℹ️  模块 $rel_path 无 tests/integration/，跳过集成测试"
+      fi
+      ;;
+    typescript|javascript)
+      if [ -d "$mod_dir/tests/integration" ]; then
+        if grep -q '"vitest"' "$mod_dir/package.json" 2>/dev/null; then
+          if ! (cd "$mod_dir" && npx vitest run tests/integration); then
+            fail "Vitest 集成测试失败 ($rel_path)"
+          fi
+        elif grep -q '"jest"' "$mod_dir/package.json" 2>/dev/null; then
+          if ! (cd "$mod_dir" && npx jest tests/integration); then
+            fail "Jest 集成测试失败 ($rel_path)"
+          fi
+        fi
+      else
+        echo "ℹ️  模块 $rel_path 无 tests/integration/，跳过集成测试"
+      fi
+      ;;
+    rust)
+      if [ -d "$mod_dir/tests" ]; then
+        if ! (cd "$mod_dir" && cargo test --test '*' 2>/dev/null || cargo test); then
+          fail "Rust 集成测试失败 ($rel_path)"
+        fi
+      fi
+      ;;
+    *)
+      echo "ℹ️  语言 '$lang' 集成测试默认命令未定义 ($rel_path)，跳过"
+      ;;
+  esac
+}
+
+run_default_e2e_test() {
+  local rel_path="$1"
+  local lang="$2"
+  local mod_dir
+  mod_dir=$(module_absolute_path "$rel_path")
+
+  case "$lang" in
+    python)
+      if [ -d "$mod_dir/tests/e2e" ]; then
+        if ! (cd "$mod_dir" && pytest tests/e2e -v); then
+          fail "Python E2E 测试失败 ($rel_path)"
+        fi
+      else
+        echo "ℹ️  模块 $rel_path 无 tests/e2e/，跳过 E2E 测试"
+      fi
+      ;;
+    typescript|javascript)
+      if [ -d "$mod_dir/tests/e2e" ] || [ -d "$mod_dir/e2e" ]; then
+        local e2e_dir="tests/e2e"
+        [ -d "$mod_dir/e2e" ] && e2e_dir="e2e"
+        if grep -q '"vitest"' "$mod_dir/package.json" 2>/dev/null; then
+          if ! (cd "$mod_dir" && npx vitest run "$e2e_dir"); then
+            fail "Vitest E2E 测试失败 ($rel_path)"
+          fi
+        elif grep -q '"jest"' "$mod_dir/package.json" 2>/dev/null; then
+          if ! (cd "$mod_dir" && npx jest "$e2e_dir"); then
+            fail "Jest E2E 测试失败 ($rel_path)"
+          fi
+        fi
+      else
+        echo "ℹ️  模块 $rel_path 无 E2E 测试目录，跳过"
+      fi
+      ;;
+    *)
+      echo "ℹ️  语言 '$lang' E2E 测试默认命令未定义 ($rel_path)，跳过"
+      ;;
+  esac
+}
+
+verify_test_result_files() {
+  local result_file="$1"
+  local files_key="$2"
+  local missing=""
+
+  while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    if [ ! -f "$PROJECT_ROOT/$f" ]; then
+      missing="${missing}
+  - $f"
+    fi
+  done < <(jq -r --arg key "$files_key" '.[$key][]?' "$result_file" 2>/dev/null)
+
+  if [ -n "$missing" ]; then
+    fail "${files_key} 中的测试文件不存在:${missing}"
+  fi
+}
+
+run_tests_by_modules() {
+  local test_kind="$1"
+  local count
+  count=$(echo "$MODULES_JSON" | jq 'length')
+
+  if [ "$count" -eq 0 ]; then
+    echo "⚠️  未检测到项目模块，跳过${test_kind}测试"
+    return 0
+  fi
+
+  local i=0
+  while [ "$i" -lt "$count" ]; do
+    local path lang
+    path=$(echo "$MODULES_JSON" | jq -r ".[$i].path")
+    lang=$(echo "$MODULES_JSON" | jq -r ".[$i].language")
+
+    case "$test_kind" in
+      unit) run_default_unit_test "$path" "$lang" ;;
+      integration) run_default_integration_test "$path" "$lang" ;;
+      e2e) run_default_e2e_test "$path" "$lang" ;;
+    esac
+
+    i=$((i + 1))
+  done
+}
+
+# ===== Phase Handlers =====
+
+gate_new() {
+  if [ -z "$CHANGE" ]; then
+    fail "需要 --change <name>"
+  fi
+
+  local change_dir="$PROJECT_ROOT/specline/changes/$CHANGE"
+
+  if [ -d "$change_dir" ]; then
+    echo "⚠️  Change '$CHANGE' 已存在"
+    exit 0
+  fi
+
+  mkdir -p "$change_dir/specs"
+  mkdir -p "$change_dir/.tmp"
+
+  # 写入 .specline.yaml
+  cat > "$change_dir/.specline.yaml" << YAML
+schema: spec-driven
+created: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+YAML
+
+  # 初始化 .pipeline-state.json
+  cat > "$change_dir/.pipeline-state.json" << 'JSON'
+{
+  "version": 1,
+  "change_name": "CHANGE_NAME_PLACEHOLDER",
+  "created_at": "CREATED_AT_PLACEHOLDER",
+  "updated_at": "CREATED_AT_PLACEHOLDER",
+  "current_phase": "spec",
+  "current_step": "spec-creator",
+  "phases": {
+    "spec": { "status": "in_progress", "retry_count": 0, "sub_phases": {}, "gates": { "spec_gate": { "passed": null }, "human_gate_1": { "passed": null } } },
+    "coding": { "status": "pending", "tasks": [], "sub_phases": {}, "gates": { "build_gate": { "passed": null } } },
+    "code_review": { "status": "pending", "retry_count": 0, "gates": { "lint_gate": { "passed": null }, "human_gate_2": { "passed": null } } },
+    "test": { "status": "pending", "framework": null, "sub_phases": { "unit": { "status": "pending", "gates": { "test_unit_gate": { "passed": null } } }, "integration": { "status": "pending", "gates": { "test_integration_gate": { "passed": null } } }, "e2e": { "status": "pending", "gates": { "test_e2e_gate": { "passed": null } } } } },
+    "archive": { "status": "pending", "gates": { "human_gate_3": { "passed": null }, "archive_gate": { "passed": null } } }
+  }
+}
+JSON
+
+  # 用实际值替换占位符
+  local now
+  now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+  # 跨平台 sed（macOS/Linux 兼容）
+  if [[ "$OSTYPE" == "darwin"* ]]; then
+    sed -i '' "s/CHANGE_NAME_PLACEHOLDER/$CHANGE/g" "$change_dir/.pipeline-state.json"
+    sed -i '' "s/CREATED_AT_PLACEHOLDER/$now/g" "$change_dir/.pipeline-state.json"
+  else
+    sed -i "s/CHANGE_NAME_PLACEHOLDER/$CHANGE/g" "$change_dir/.pipeline-state.json"
+    sed -i "s/CREATED_AT_PLACEHOLDER/$now/g" "$change_dir/.pipeline-state.json"
+  fi
+
+  echo "✅ Change '$CHANGE' 已创建: $change_dir"
+  echo "   .specline.yaml + .pipeline-state.json + specs/"
+
+  write_gate_passed "phases.spec.gates.spec_gate"
+}
+
+gate_list() {
+  local changes_dir="$PROJECT_ROOT/specline/changes"
+  local json_output=false
+
+  if [ "${1:-}" = "--json" ]; then
+    json_output=true
+  fi
+
+  if [ ! -d "$changes_dir" ]; then
+    if $json_output; then
+      echo '[]'
+    else
+      echo "(无活跃 change)"
+    fi
+    exit 0
+  fi
+
+  if $json_output; then
+    echo "["
+    local first=true
+    for f in "$changes_dir"/*/.pipeline-state.json; do
+      [ -f "$f" ] || continue
+      # 跳过 archive/
+      if echo "$f" | grep -q "/archive/"; then continue; fi
+      local dir name phase
+      dir=$(dirname "$f")
+      name=$(basename "$dir")
+      phase=$(jq -r '.current_phase // "unknown"' "$f" 2>/dev/null)
+      if [ "$first" = true ]; then first=false; else echo ","; fi
+      echo "  {\"name\":\"$name\",\"phase\":\"$phase\"}"
+    done
+    echo "]"
+  else
+    for f in "$changes_dir"/*/.pipeline-state.json; do
+      [ -f "$f" ] || continue
+      if echo "$f" | grep -q "/archive/"; then continue; fi
+      local dir name phase
+      dir=$(dirname "$f")
+      name=$(basename "$dir")
+      phase=$(jq -r '.current_phase // "unknown"' "$f" 2>/dev/null)
+      echo "  $name (phase: $phase)"
+    done
+  fi
+}
+
+gate_artifacts() {
+  if [ -z "$CHANGE" ]; then
+    fail "需要 --change <name>"
+  fi
+
+  local dir="$PROJECT_ROOT/specline/changes/$CHANGE"
+  local json_output=false
+
+  if [ "${1:-}" = "--json" ]; then
+    json_output=true
+  fi
+
+  local has_proposal=false has_design=false has_tasks=false has_specs=false
+
+  [ -f "$dir/proposal.md" ] && has_proposal=true
+  [ -f "$dir/design.md" ] && has_design=true
+  [ -f "$dir/tasks.md" ] && has_tasks=true
+  [ -d "$dir/specs" ] && [ -n "$(find "$dir/specs" -name 'spec.md' 2>/dev/null)" ] && has_specs=true
+
+  if $json_output; then
+    echo "{"
+    echo "  \"proposal\": $has_proposal,"
+    echo "  \"design\": $has_design,"
+    echo "  \"tasks\": $has_tasks,"
+    echo "  \"specs\": $has_specs"
+    echo "}"
+  else
+    echo "Artifacts for '$CHANGE':"
+    echo "  proposal.md: $has_proposal"
+    echo "  design.md:   $has_design"
+    echo "  tasks.md:    $has_tasks"
+    echo "  spec.md:     $has_specs"
+  fi
+}
+
+gate_spec() {
+  local spec_file
+  spec_file=$(find_spec_file)
+
+  if [ -z "$spec_file" ] || [ ! -f "$spec_file" ]; then
+    fail "spec.md 不存在。请确保 spec-creator 已生成 spec 文件。"
+  fi
+
+  # 1. H1 含 "Specification"
+  if ! grep -q "^# .* Specification" "$spec_file"; then
+    fail "标题格式错误：H1 必须包含 'Specification' 关键词"
+  fi
+
+  # 2. 含 Purpose 章节
+  if ! grep -q "^## Purpose" "$spec_file"; then
+    fail "缺少 ## Purpose 章节"
+  fi
+
+  # 3. 含 Requirements 章节
+  if ! grep -q "^## Requirements" "$spec_file"; then
+    fail "缺少 ## Requirements 章节"
+  fi
+
+  # 4. 至少 1 个 Requirement
+  local req_count
+  req_count=$(grep -c "^### Requirement:" "$spec_file" || echo "0")
+  if [ "$req_count" -lt 1 ]; then
+    fail "至少需要 1 个 Requirement，当前: $req_count"
+  fi
+  pass "Requirements 数量: $req_count"
+
+  # 5. 每个 Requirement 至少 1 个 Scenario（简化检查：Scenario 总数 >= Requirement 总数）
+  local scenario_count
+  scenario_count=$(grep -c "^#### Scenario:" "$spec_file" || echo "0")
+  if [ "$scenario_count" -lt "$req_count" ]; then
+    fail "每个 Requirement 至少需要 1 个 Scenario。Requirement: $req_count, Scenario: $scenario_count"
+  fi
+  pass "Scenario 数量: $scenario_count"
+
+  # 6. WHEN/THEN 语义检查（每个 Scenario 至少 1 WHEN + 1 THEN）
+  local bad_scenarios=""
+  local current_scenario="" has_when=0 has_then=0
+
+  while IFS= read -r line; do
+    if [[ "$line" =~ ^####\ Scenario: ]]; then
+      if [ -n "$current_scenario" ] && { [ "$has_when" -eq 0 ] || [ "$has_then" -eq 0 ]; }; then
+        bad_scenarios="${bad_scenarios}\n  - ${current_scenario} (WHEN=${has_when}, THEN=${has_then})"
+      fi
+      current_scenario="${line#*Scenario: }"
+      has_when=0; has_then=0
+    fi
+    [[ "$line" == *'**WHEN**'* ]] && ((has_when++)) || true
+    [[ "$line" == *'**THEN**'* ]] && ((has_then++)) || true
+  done < "$spec_file"
+
+  if [ -n "$current_scenario" ] && { [ "$has_when" -eq 0 ] || [ "$has_then" -eq 0 ]; }; then
+    bad_scenarios="${bad_scenarios}\n  - ${current_scenario} (WHEN=${has_when}, THEN=${has_then})"
+  fi
+
+  if [ -n "$bad_scenarios" ]; then
+    fail "以下 Scenario 缺少 WHEN 或 THEN:${bad_scenarios}"
+  fi
+  pass "WHEN/THEN 语义检查通过 (每个 Scenario 至少 1 WHEN + 1 THEN)"
+
+  # 7. review.json 状态检查（如果存在）
+  local review_file
+  review_file="$(dirname "$spec_file")/spec-review.json"
+  if [ -f "$review_file" ]; then
+    local review_status
+    review_status=$(jq -r '.status' "$review_file" 2>/dev/null || echo "missing")
+    if [ "$review_status" != "approved" ]; then
+      fail "spec-review.json 审核未通过 (status: $review_status)"
+    fi
+    pass "审核状态: approved"
+
+    # 7b. 检查 coverage（所有 Requirement 和 Scenario 被 task 的 Covers 覆盖）
+    local cov_req_total cov_req_covered
+    cov_req_total=$(jq -r '.coverage.requirements_total' "$review_file" 2>/dev/null || echo "0")
+    cov_req_covered=$(jq -r '.coverage.requirements_covered' "$review_file" 2>/dev/null || echo "0")
+    if [ "$cov_req_covered" -lt "$cov_req_total" ]; then
+      fail "Requirement 覆盖不全: $cov_req_covered/$cov_req_total"
+    fi
+    pass "Requirement 覆盖率: $cov_req_covered/$cov_req_total"
+  else
+    pass "审核状态: 无 spec-review.json（跳过审核检查）"
+  fi
+
+  # 8. 检查 tasks.md 是否存在且含完整的 Type/Depends/Covers/Files 标注
+  local tasks_file="$PROJECT_ROOT/specline/changes/$CHANGE/tasks.md"
+  if [ ! -f "$tasks_file" ]; then
+    fail "tasks.md 不存在"
+  fi
+  pass "tasks.md 存在"
+
+  # 9. 检查每个任务标注完整性
+  local task_count type_count deps_count covers_count files_count
+  task_count=$(grep -c '^## ' "$tasks_file" || echo "0")
+  type_count=$(grep -c '\*\*Type\*\*:' "$tasks_file" || echo "0")
+  deps_count=$(grep -c '\*\*Depends\*\*:' "$tasks_file" || echo "0")
+  covers_count=$(grep -c '\*\*Covers\*\*:' "$tasks_file" || echo "0")
+  files_count=$(grep -c '\*\*Files\*\*:' "$tasks_file" || echo "0")
+
+  if [ "$type_count" -lt "$task_count" ] || [ "$deps_count" -lt "$task_count" ] || \
+     [ "$covers_count" -lt "$task_count" ] || [ "$files_count" -lt "$task_count" ]; then
+    fail "tasks.md 标注不完整：任务=$task_count, Type=$type_count, Depends=$deps_count, Covers=$covers_count, Files=$files_count"
+  fi
+  pass "tasks.md 标注完整性检查通过 ($task_count 个任务)"
+
+  # 10. Testable 字段校验
+  local testable_count
+  testable_count=$(grep -c '\*\*Testable\*\*:' "$tasks_file" || echo "0")
+
+  if [ "$testable_count" -eq 0 ]; then
+    echo "⚠️  Testable 标注缺失（向后兼容模式：缺失字段的任务将被视为 Testable: false）"
+  elif [ "$testable_count" -gt 0 ] && [ "$testable_count" -lt "$task_count" ]; then
+    local missing_testable_tasks
+    missing_testable_tasks=$(awk '
+      /^## / {
+        if (in_task && !has_testable) missing = missing (missing ? ", " : "") prev_task
+        prev_task = $2; gsub(/\..*/, "", prev_task)
+        in_task = 1; has_testable = 0
+      }
+      /\*\*Testable\*\*:/ { has_testable = 1 }
+      END {
+        if (in_task && !has_testable) missing = missing (missing ? ", " : "") prev_task
+        print missing
+      }' "$tasks_file")
+    echo "⚠️  Testable 标注不完整：任务=$task_count, Testable=$testable_count（缺失任务: $missing_testable_tasks；缺失字段的任务将被视为 Testable: false）"
+  else
+    pass "Testable 标注完整性检查通过 ($testable_count/$task_count)"
+  fi
+
+  # 11. 至少 1 个任务无依赖
+  local independent_count
+  independent_count=$(grep -c '\*\*Depends\*\*: (none)' "$tasks_file" || echo "0")
+  if [ "$independent_count" -lt 1 ]; then
+    fail "至少需要 1 个无依赖任务 (Depends: none)，当前: $independent_count"
+  fi
+  pass "无依赖任务数: $independent_count"
+
+  write_gate_passed "phases.spec.gates.spec_gate"
+  pass "Spec Gate 全部通过"
+}
+
+gate_build() {
+  load_project_config
+
+  local module_count
+  module_count=$(echo "$MODULES_JSON" | jq 'length')
+
+  if [ "$module_count" -eq 0 ]; then
+    echo "⚠️  未检测到项目模块，跳过 build 命令"
+  else
+    local i=0
+    while [ "$i" -lt "$module_count" ]; do
+      local path lang
+      path=$(echo "$MODULES_JSON" | jq -r ".[$i].path")
+      lang=$(echo "$MODULES_JSON" | jq -r ".[$i].language")
+      build_module "$path" "$lang"
+      i=$((i + 1))
+    done
+    pass "模块 build 检查通过 ($module_count 个模块)"
+  fi
+
+  # Agent 产出 JSON 验证（task-result.json files_changed / files）
+  if [ -n "$CHANGE" ]; then
+    local task_result="$PROJECT_ROOT/specline/changes/$CHANGE/.tmp/task-result.json"
+    if [ -f "$task_result" ]; then
+      echo "正在验证 task-result.json 声明的文件..."
+      local missing_files=""
+      while IFS= read -r f; do
+        [ -z "$f" ] && continue
+        if [ ! -f "$PROJECT_ROOT/$f" ]; then
+          missing_files="${missing_files}
+  - $f"
+        fi
+      done < <(jq -r '(.files_changed // .files // [])[]?' "$task_result" 2>/dev/null)
+
+      if [ -n "$missing_files" ]; then
+        fail "task-result.json 声明的文件不存在:${missing_files}"
+      fi
+      pass "task-result.json 文件验证通过"
+    fi
+  fi
+
+  # 单元测试文件存在性检查（Testable=true 任务）
+  local tasks_file="$PROJECT_ROOT/specline/changes/$CHANGE/tasks.md"
+  if [ -f "$tasks_file" ]; then
+    local testable_true_count
+    testable_true_count=$(grep -c '\*\*Testable\*\*:.*true' "$tasks_file" || echo "0")
+
+    if [ "$testable_true_count" -gt 0 ]; then
+      echo "正在检查 $testable_true_count 个 Testable=true 任务的单元测试文件..."
+
+      local missing_files=""
+      local syntax_errors=""
+
+      while IFS='|' read -r task_id file_path; do
+        if [ -z "$file_path" ]; then
+          missing_files="${missing_files}
+  任务 $task_id: 未在 Files 列表中声明测试文件（支持 tests/unit/、tests/models/、*_test.go、*.test.ts 等）"
+          continue
+        fi
+
+        if [ ! -f "$PROJECT_ROOT/$file_path" ]; then
+          missing_files="${missing_files}
+  任务 $task_id: $file_path"
+          continue
+        fi
+
+        case "$file_path" in
+          *.py)
+            if ! python3 -m py_compile "$PROJECT_ROOT/$file_path" 2>&1; then
+              syntax_errors="${syntax_errors}
+  任务 $task_id: $file_path (Python 语法错误)"
+            fi
+            ;;
+          *.ts|*.tsx)
+            if ! npx tsc --noEmit "$PROJECT_ROOT/$file_path" 2>&1; then
+              syntax_errors="${syntax_errors}
+  任务 $task_id: $file_path (TypeScript 语法错误)"
+            fi
+            ;;
+        esac
+      done < <(awk '
+        /^## / {
+          task_id = $2; gsub(/\..*/, "", task_id)
+          testable = ""; files_line = ""
+        }
+        /\*\*Testable\*\*:.*true/ { testable = "true" }
+        /\*\*Files\*\*:/ {
+          if (testable == "true") {
+            files_line = $0
+            gsub(/.*\*\*Files\*\*:[ \t]*/, "", files_line)
+            split(files_line, paths, /,[ \t]*/)
+            has_test = 0
+            for (i in paths) {
+              gsub(/^[ \t]+|[ \t]+$/, "", paths[i])
+              if (paths[i] ~ /^tests\/(unit|models)\// ||
+                  paths[i] ~ /_test\.go$/ ||
+                  paths[i] ~ /\.test\.(ts|tsx|js|jsx)$/ ||
+                  paths[i] ~ /\.spec\.(ts|tsx|js|jsx)$/ ||
+                  paths[i] ~ /^src\/.*\/tests\.rs$/) {
+                print task_id "|" paths[i]
+                has_test = 1
+              }
+            }
+            if (has_test == 0) {
+              print task_id "|"
+            }
+          }
+        }
+      ' "$tasks_file")
+
+      if [ -n "$missing_files" ]; then
+        fail "单元测试文件缺失:${missing_files}"
+      fi
+
+      if [ -n "$syntax_errors" ]; then
+        fail "单元测试文件语法错误:${syntax_errors}"
+      fi
+
+      pass "单元测试文件存在性检查通过"
+    else
+      echo "ℹ️  无 Testable=true 任务，跳过单元测试文件检查"
+    fi
+  fi
+
+  write_gate_passed "phases.coding.gates.build_gate"
+  pass "Build Gate 全部通过"
+}
+
+gate_lint() {
+  load_project_config
+
+  local module_count
+  module_count=$(echo "$MODULES_JSON" | jq 'length')
+
+  if [ "$module_count" -eq 0 ]; then
+    echo "⚠️  未检测到项目模块，跳过 lint"
+  else
+    local i=0
+    while [ "$i" -lt "$module_count" ]; do
+      local path lang
+      path=$(echo "$MODULES_JSON" | jq -r ".[$i].path")
+      lang=$(echo "$MODULES_JSON" | jq -r ".[$i].language")
+      lint_module "$path" "$lang"
+      i=$((i + 1))
+    done
+    pass "模块 lint 检查通过 ($module_count 个模块)"
+  fi
+
+  # code-review.json error 计数（位于 change 的 .tmp/ 目录下）
+  local review_file="$PROJECT_ROOT/specline/changes/$CHANGE/.tmp/code-review.json"
+  if [ -f "$review_file" ]; then
+    local error_count
+    error_count=$(jq '[.findings[] | select(.severity=="error")] | length' "$review_file" 2>/dev/null || echo "0")
+    if [ "$error_count" -gt 0 ]; then
+      fail "code-review.json 中发现 $error_count 个 error，必须修复"
+    fi
+    pass "Review errors: 0"
+  fi
+
+  write_gate_passed "phases.code_review.gates.lint_gate"
+  pass "Lint Gate 全部通过"
+}
+
+# ===== 测试框架自动检测 =====
+# 优先级：.pipeline-state.json > test-code-result.json > MODULES_JSON 推导 > 无兜底
+detect_test_framework() {
+  framework="" test_cmd="" coverage_cmd=""
+
+  # 1. 先尝试从状态文件读取 test-writer 的检测结果
+  if [ -f "$STATE_FILE" ]; then
+    local recorded
+    recorded=$(jq -r '.phases.test.framework // empty' "$STATE_FILE" 2>/dev/null)
+    if [ -n "$recorded" ]; then
+      framework="$recorded"
+    fi
+  fi
+
+  # 2. 从 test-code-result.json 读取
+  if [ -z "$framework" ] && [ -n "$CHANGE" ]; then
+    local test_result="$PROJECT_ROOT/specline/changes/$CHANGE/.tmp/test-code-result.json"
+    if [ -f "$test_result" ]; then
+      framework=$(jq -r '.test_framework // empty' "$test_result" 2>/dev/null)
+      test_cmd=$(jq -r '.test_cmd // empty' "$test_result" 2>/dev/null)
+    fi
+  fi
+
+  # 3. 从 MODULES_JSON 推导
+  if [ -z "$framework" ]; then
+    load_project_config
+    local module_count
+    module_count=$(echo "$MODULES_JSON" | jq 'length')
+    if [ "$module_count" -gt 0 ]; then
+      local lang
+      lang=$(echo "$MODULES_JSON" | jq -r '.[0].language')
+      case "$lang" in
+        go) framework="go-test" ;;
+        python) framework="pytest" ;;
+        rust) framework="cargo-test" ;;
+        java) framework="junit" ;;
+        kotlin) framework="junit" ;;
+        typescript|javascript)
+          local mod_path
+          mod_path=$(echo "$MODULES_JSON" | jq -r '.[0].path')
+          local mod_dir
+          mod_dir=$(module_absolute_path "$mod_path")
+          if [ -f "$mod_dir/package.json" ]; then
+            if grep -q '"vitest"' "$mod_dir/package.json" 2>/dev/null; then
+              framework="vitest"
+            elif grep -q '"jest"' "$mod_dir/package.json" 2>/dev/null; then
+              framework="jest"
+            elif grep -q '"mocha"' "$mod_dir/package.json" 2>/dev/null; then
+              framework="mocha"
+            fi
+          fi
+          ;;
+      esac
+    fi
+  fi
+
+  # 4. 无兜底 pytest — 检测失败时 framework 为空
+  if [ -z "$framework" ]; then
+    echo "⚠️  未检测到测试框架"
+    return 0
+  fi
+
+  # 根据框架确定命令（test_cmd 可能已由 JSON 提供）
+  if [ -z "$test_cmd" ]; then
+    case "$framework" in
+      jest)
+        test_cmd="npx jest"
+        coverage_cmd="npx jest --coverage"
+        ;;
+      vitest)
+        test_cmd="npx vitest run"
+        coverage_cmd="npx vitest run --coverage"
+        ;;
+      mocha)
+        test_cmd="npx mocha"
+        coverage_cmd="npx nyc mocha"
+        ;;
+      go-test)
+        test_cmd="go test ./..."
+        coverage_cmd="go test -cover ./..."
+        ;;
+      cargo-test)
+        test_cmd="cargo test"
+        coverage_cmd="cargo tarpaulin 2>/dev/null || cargo test"
+        ;;
+      junit)
+        local mod_path mod_dir
+        mod_path=$(echo "$MODULES_JSON" | jq -r '.[0].path // "."')
+        mod_dir=$(module_absolute_path "$mod_path")
+        if [ -f "$mod_dir/pom.xml" ]; then
+          test_cmd="mvn test"
+          coverage_cmd="mvn jacoco:report"
+        else
+          test_cmd="gradle test"
+          coverage_cmd="gradle jacocoTestReport"
+        fi
+        ;;
+      pytest)
+        test_cmd="pytest"
+        coverage_cmd="pytest --cov --cov-fail-under=80"
+        ;;
+      *)
+        test_cmd=""
+        coverage_cmd=""
+        ;;
+    esac
+  fi
+
+  if [ -n "$framework" ] && [ -n "$test_cmd" ]; then
+    echo "检测到测试框架: $framework (命令: $test_cmd)"
+  fi
+}
+
+gate_test_unit() {
+  echo "正在执行单元测试..."
+  load_project_config
+
+  local test_result=""
+  if [ -n "$CHANGE" ]; then
+    test_result="$PROJECT_ROOT/specline/changes/$CHANGE/.tmp/test-code-result.json"
+  fi
+
+  if [ -n "$test_result" ] && [ -f "$test_result" ]; then
+    local test_cmd
+    test_cmd=$(jq -r '.test_cmd // empty' "$test_result" 2>/dev/null)
+
+    verify_test_result_files "$test_result" "test_files"
+
+    if [ -n "$test_cmd" ]; then
+      echo "执行 Agent 声明的 test_cmd: $test_cmd"
+      if ! (cd "$PROJECT_ROOT" && eval "$test_cmd"); then
+        fail "单元测试失败"
+      fi
+    else
+      echo "⚠️  test-code-result.json 无 test_cmd，回退到模块默认命令"
+      run_tests_by_modules "unit"
+    fi
+  else
+    local module_count
+    module_count=$(echo "$MODULES_JSON" | jq 'length')
+    if [ "$module_count" -eq 0 ]; then
+      echo "⚠️  未检测到项目模块且无 test-code-result.json，跳过单元测试"
+      write_gate_passed "phases.test.sub_phases.unit.gates.test_unit_gate"
+      pass "单元测试已跳过"
+      return 0
+    fi
+    run_tests_by_modules "unit"
+  fi
+
+  # 覆盖率检查（非阻塞）
+  detect_test_framework
+  if [ -n "${coverage_cmd:-}" ]; then
+    echo "正在检查覆盖率..."
+    if ! (cd "$PROJECT_ROOT" && eval "$coverage_cmd" 2>&1); then
+      echo "⚠️  覆盖率检查未通过（不阻塞，由 test-runner agent 深入分析）"
+    fi
+  fi
+
+  write_gate_passed "phases.test.sub_phases.unit.gates.test_unit_gate"
+  pass "单元测试通过"
+}
+
+gate_test_integration() {
+  echo "正在执行集成测试..."
+  load_project_config
+
+  local test_result=""
+  if [ -n "$CHANGE" ]; then
+    test_result="$PROJECT_ROOT/specline/changes/$CHANGE/.tmp/test-code-result.json"
+  fi
+
+  if [ -n "$test_result" ] && [ -f "$test_result" ]; then
+    local test_cmd
+    test_cmd=$(jq -r '.integration_test_cmd // empty' "$test_result" 2>/dev/null)
+
+    if jq -e '.integration_test_files | length > 0' "$test_result" &>/dev/null; then
+      verify_test_result_files "$test_result" "integration_test_files"
+    fi
+
+    if [ -n "$test_cmd" ]; then
+      echo "执行 Agent 声明的 integration_test_cmd: $test_cmd"
+      if ! (cd "$PROJECT_ROOT" && eval "$test_cmd"); then
+        fail "集成测试失败"
+      fi
+    else
+      run_tests_by_modules "integration"
+    fi
+  else
+    local module_count
+    module_count=$(echo "$MODULES_JSON" | jq 'length')
+    if [ "$module_count" -eq 0 ]; then
+      echo "⚠️  未检测到项目模块且无 test-code-result.json，跳过集成测试"
+    else
+      run_tests_by_modules "integration"
+    fi
+  fi
+
+  write_gate_passed "phases.test.sub_phases.integration.gates.test_integration_gate"
+  pass "集成测试通过"
+}
+
+gate_test_e2e() {
+  echo "正在执行 E2E 测试..."
+  load_project_config
+
+  local test_result=""
+  if [ -n "$CHANGE" ]; then
+    test_result="$PROJECT_ROOT/specline/changes/$CHANGE/.tmp/test-code-result.json"
+  fi
+
+  if [ -n "$test_result" ] && [ -f "$test_result" ]; then
+    local test_cmd
+    test_cmd=$(jq -r '.e2e_test_cmd // empty' "$test_result" 2>/dev/null)
+
+    if jq -e '.e2e_test_files | length > 0' "$test_result" &>/dev/null; then
+      verify_test_result_files "$test_result" "e2e_test_files"
+    fi
+
+    if [ -n "$test_cmd" ]; then
+      echo "执行 Agent 声明的 e2e_test_cmd: $test_cmd"
+      if ! (cd "$PROJECT_ROOT" && eval "$test_cmd"); then
+        fail "E2E 测试失败"
+      fi
+    else
+      run_tests_by_modules "e2e"
+    fi
+  else
+    local module_count
+    module_count=$(echo "$MODULES_JSON" | jq 'length')
+    if [ "$module_count" -eq 0 ]; then
+      echo "⚠️  未检测到项目模块且无 test-code-result.json，跳过 E2E 测试"
+    else
+      run_tests_by_modules "e2e"
+    fi
+  fi
+
+  write_gate_passed "phases.test.sub_phases.e2e.gates.test_e2e_gate"
+  pass "E2E 测试通过"
+}
+
+gate_archive() {
+  if [ -z "$CHANGE" ]; then
+    fail "需要 --change <name>"
+  fi
+
+  # 如果传了 --execute，执行实际归档动作
+  if [ -n "$EXECUTE_ARCHIVE" ]; then
+    local src_dir="$PROJECT_ROOT/specline/changes/$CHANGE"
+    local archive_dir="$PROJECT_ROOT/specline/changes/archive"
+    local date_prefix
+    date_prefix=$(date -u +"%Y-%m-%d")
+    local dest="$archive_dir/${date_prefix}-${CHANGE}"
+
+    if [ ! -d "$src_dir" ]; then
+      fail "Change '$CHANGE' 不存在: $src_dir"
+    fi
+
+    # 检查基本文件
+    if [ ! -f "$src_dir/proposal.md" ]; then
+      fail "缺少 proposal.md"
+    fi
+    if [ ! -f "$src_dir/tasks.md" ]; then
+      fail "缺少 tasks.md"
+    fi
+
+    # 同步 delta specs 到主 specs
+    if [ -d "$src_dir/specs" ]; then
+      echo "正在同步 delta specs 到 specline/specs/..."
+      cp -r "$src_dir/specs/"* "$PROJECT_ROOT/specline/specs/" 2>/dev/null || true
+    fi
+
+    # 移动到归档
+    mkdir -p "$archive_dir"
+    if [ -d "$dest" ]; then
+      fail "归档目标已存在: $dest"
+    fi
+
+    mv "$src_dir" "$dest"
+    echo "✅ 已归档到: $dest"
+
+    # 临时文件（.tmp/）随 change 目录一起归档，无需单独清理
+
+    # 更新状态文件
+    if [ -f "$dest/.pipeline-state.json" ]; then
+      local now
+      now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+      # macOS sed 兼容
+      sed -i '' "s/\"current_phase\": \"[^\"]*\"/\"current_phase\": \"archived\"/g" "$dest/.pipeline-state.json" 2>/dev/null || true
+    fi
+
+    # 清理所有绑定到该 change 的 session
+    local bindings_file="$PROJECT_ROOT/specline/.pipeline-sessions.json"
+    if [ -f "$bindings_file" ]; then
+      jq --arg change "$CHANGE" \
+        'with_entries(select(.value.change != $change))' \
+        "$bindings_file" > "${bindings_file}.tmp" && mv "${bindings_file}.tmp" "$bindings_file"
+      echo "✅ 已清理 pipeline '$CHANGE' 的所有 session 绑定"
+    fi
+
+    exit 0
+  fi
+
+  # 验证模式（原有逻辑，路径改为 specline）
+  local archive_dir="$PROJECT_ROOT/specline/changes/archive"
+  local found
+  found=$(find "$archive_dir" -maxdepth 1 -type d -name "*$CHANGE" 2>/dev/null | head -1)
+
+  if [ -z "$found" ]; then
+    fail "归档目录不存在: $archive_dir/*$CHANGE"
+  fi
+
+  if [ ! -f "$found/proposal.md" ]; then
+    fail "归档目录缺少 proposal.md"
+  fi
+  if [ ! -f "$found/tasks.md" ]; then
+    fail "归档目录缺少 tasks.md"
+  fi
+
+  write_gate_passed "phases.archive.gates.archive_gate"
+  pass "Archive Gate 全部通过"
+}
+
+gate_status() {
+  if [ ! -f "$STATE_FILE" ]; then
+    echo '{"status":"no_pipeline","message":"未找到流水线状态文件"}'
+    exit 0
+  fi
+
+  jq '{
+    change: .change_name,
+    phase: .current_phase,
+    step: .current_step,
+    tasks: .phases.coding.tasks | map({id: .id, type: .type, status: .status, batch: .batch}),
+    progress: {
+      spec: .phases.spec.status,
+      coding: .phases.coding.status,
+      code_review: .phases.code_review.status,
+      test: .phases.test.status,
+      archive: .phases.archive.status
+    }
+  }' "$STATE_FILE"
+}
+
+gate_bind() {
+  local session_id="$1"
+  local target_change="$2"
+
+  if [ -z "$session_id" ] || [ -z "$target_change" ]; then
+    fail "需要 <session_id> <change_name>"
+  fi
+
+  local state_file="$PROJECT_ROOT/specline/changes/$target_change/.pipeline-state.json"
+  if [ ! -f "$state_file" ]; then
+    fail "Change '$target_change' 不存在"
+  fi
+
+  local bindings_file="$PROJECT_ROOT/specline/.pipeline-sessions.json"
+  [ ! -f "$bindings_file" ] && echo '{}' > "$bindings_file"
+
+  local now
+  now=$(now_iso8601)
+  jq --arg sid "$session_id" --arg change "$target_change" --arg time "$now" \
+    '.[$sid] = {"change": $change, "bound_at": $time}' \
+    "$bindings_file" > "${bindings_file}.tmp" && mv "${bindings_file}.tmp" "$bindings_file"
+
+  echo "✅ 已绑定 session '$session_id' → pipeline '$target_change'"
+}
+
+# ===== Semantic Gate — 跨文件语义检查 =====
+gate_semantic() {
+  if [ -z "$CHANGE" ]; then
+    fail "需要 --change <name>"
+  fi
+
+  # 定位 spec.md 和 tasks.md
+  local spec_file tasks_file
+  spec_file=$(find_spec_file)
+  tasks_file="$PROJECT_ROOT/specline/changes/$CHANGE/tasks.md"
+
+  if [ ! -f "$spec_file" ] || [ ! -f "$tasks_file" ]; then
+    fail "spec.md 或 tasks.md 不存在，无法执行语义检查"
+  fi
+
+  local checks_dir="$SCRIPT_DIR/pipeline-gate-checks"
+  local common_sh="$checks_dir/common.sh"
+
+  if [ ! -f "$common_sh" ]; then
+    fail "common.sh 不存在: $common_sh"
+  fi
+
+  # source common.sh 初始化计数器
+  source "$common_sh"
+
+  # 设定文件路径环境变量，供各检查脚本使用
+  export SPEC_FILE="$spec_file"
+  export TASKS_FILE="$tasks_file"
+
+  # 依次执行 6 项语义检查
+  local check_scripts=(
+    "a1-covers-ref.sh"
+    "d1-cycle.sh"
+    "c1-exception.sh"
+    "c2-vague.sh"
+    "a2-a3-reverse.sh"
+    "d3-type-file.sh"
+  )
+
+  local check_functions=(
+    "run_a1_covers_ref"
+    "run_d1_cycle"
+    "run_c1_exception"
+    "run_c2_vague"
+    "run_a2_a3_reverse"
+    "run_d3_type_file"
+  )
+
+  local i=0
+  for script in "${check_scripts[@]}"; do
+    local script_path="$checks_dir/$script"
+    if [ -f "$script_path" ]; then
+      source "$script_path"
+      if declare -f "${check_functions[$i]}" > /dev/null 2>&1; then
+        "${check_functions[$i]}"
+      fi
+    else
+      echo "⚠️  检查脚本不存在，跳过: $script"
+    fi
+    i=$((i + 1))
+  done
+
+  # 汇总结果
+  local total_issues=$((SEMANTIC_ERRORS + SEMANTIC_WARNINGS + SEMANTIC_INFOS))
+
+  echo ""
+  echo "========== Semantic Gate 汇总 =========="
+  echo "  ❌ 错误:   $SEMANTIC_ERRORS"
+  echo "  ⚠️  警告:  $SEMANTIC_WARNINGS"
+  echo "  ℹ️  信息:  $SEMANTIC_INFOS"
+  echo "  总计:      $total_issues"
+  echo "========================================="
+
+  if [ "$SEMANTIC_ERRORS" -gt 0 ]; then
+    echo ""
+    echo "❌ Semantic Gate 未通过：发现 $SEMANTIC_ERRORS 个错误"
+    exit 1
+  fi
+
+  write_gate_passed "phases.spec.gates.semantic_gate"
+  pass "✅ Semantic Gate 全部通过"
+}
+
+# ===== 分派 =====
+
+case "$PHASE" in
+  new)
+    gate_new
+    ;;
+  list)
+    gate_list "$@"
+    ;;
+  artifacts)
+    gate_artifacts "$@"
+    ;;
+  spec)
+    gate_spec
+    ;;
+  semantic)
+    gate_semantic "$@"
+    ;;
+  build)
+    gate_build
+    ;;
+  lint)
+    gate_lint
+    ;;
+  test-unit)
+    gate_test_unit
+    ;;
+  test-integration)
+    gate_test_integration
+    ;;
+  test-e2e)
+    gate_test_e2e
+    ;;
+  bind)
+    gate_bind "${POSITIONAL_ARGS[0]:-}" "${POSITIONAL_ARGS[1]:-}"
+    ;;
+  detect-modules)
+    load_project_config
+    echo "$MODULES_JSON"
+    ;;
+  archive)
+    gate_archive "$@"
+    ;; 
+  status)
+    gate_status
+    ;;
+  *)
+    echo "未知 phase: $PHASE"
+    echo "可用: new | list | artifacts | spec | semantic | build | lint | test-unit | test-integration | test-e2e | detect-modules | bind | archive | status"
+    exit 2
+    ;;
+esac
+
+exit 0