specline 1.1.2 → 1.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specline",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "Spec-driven AI coding pipeline with deterministic quality gates for Cursor IDE",
   "bin": {
     "specline": "./cli.mjs"

package/templates/.cursor/hooks/specline-agent-guard.sh

@@ -12,6 +12,7 @@ set -euo pipefail
 
 input=$(cat)
 subagent_type=$(echo "$input" | jq -r '.subagent_type // empty')
+SESSION_ID=$(echo "$input" | jq -r '.session_id // empty')
 
 # 非 specline agent → 放行（不受 Specline 管控）
 if ! echo "$subagent_type" | grep -qE "^specline-"; then
@@ -32,29 +33,36 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 CHANGES_DIR="$PROJECT_ROOT/specline/changes"
 
-# 查找活跃 pipeline
-find_active_pipeline() {
-  if [ ! -d "$CHANGES_DIR" ]; then
-    echo ""
-    return
+# 通过 session_id 解析绑定的 pipeline
+resolve_pipeline_for_session() {
+  local session_id="$1"
+  local bindings_file="$PROJECT_ROOT/specline/.pipeline-sessions.json"
+
+  if [ ! -f "$bindings_file" ]; then
+    return 1
   fi
-  for f in "$CHANGES_DIR"/*/.pipeline-state.json; do
-    [ -f "$f" ] || continue
-    if echo "$f" | grep -q "/archive/"; then continue; fi
-    local ph
-    ph=$(jq -r '.current_phase // ""' "$f" 2>/dev/null)
-    if [ "$ph" != "archive" ] && [ "$ph" != "" ]; then
-      echo "$f"
-      return
-    fi
-  done
-  echo ""
-}
 
-STATE_FILE=$(find_active_pipeline)
+  local change_name
+  change_name=$(jq -r --arg sid "$session_id" '.[$sid].change // empty' "$bindings_file" 2>/dev/null)
+
+  if [ -z "$change_name" ]; then
+    return 1
+  fi
+
+  local state_file="$CHANGES_DIR/$change_name/.pipeline-state.json"
+
+  if [ ! -f "$state_file" ]; then
+    # 脏数据：pipeline 已归档或不存在，清理绑定
+    jq --arg sid "$session_id" 'del(.[$sid])' "$bindings_file" > "${bindings_file}.tmp" && mv "${bindings_file}.tmp" "$bindings_file"
+    return 1
+  fi
+
+  STATE_FILE="$state_file"
+  return 0
+}
 
-# 无活跃 pipeline → 放行（不在流水线中的会话可以使用任何 specline agent）
-if [ -z "$STATE_FILE" ]; then
+STATE_FILE=""
+if ! resolve_pipeline_for_session "$SESSION_ID"; then
   echo '{"permission": "allow"}'
   exit 0
 fi

package/templates/.cursor/hooks/specline-phase-guard.sh

@@ -11,6 +11,7 @@
 set -euo pipefail
 
 input=$(cat)
+SESSION_ID=$(echo "$input" | jq -r '.session_id // empty')
 tool_name=$(echo "$input" | jq -r '.tool_name // empty')
 tool_input=$(echo "$input" | jq -r '.tool_input // "{}"')
 
@@ -18,27 +19,27 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 CHANGES_DIR="$PROJECT_ROOT/specline/changes"
 
-# ===== 辅助函数 =====
+BINDINGS_FILE="$PROJECT_ROOT/specline/.pipeline-sessions.json"
+[ ! -f "$BINDINGS_FILE" ] && echo '{}' > "$BINDINGS_FILE"
 
-# 查找第一个活跃 pipeline（排除 archive/）
-find_active_pipeline() {
-  if [ ! -d "$CHANGES_DIR" ]; then
-    echo ""
-    return
+resolve_pipeline_for_session() {
+  local session_id="$1"
+  local change_name
+  change_name=$(jq -r --arg sid "$session_id" '.[$sid].change // empty' "$BINDINGS_FILE" 2>/dev/null)
+  if [ -z "$change_name" ]; then
+    return 1
   fi
-  for f in "$CHANGES_DIR"/*/.pipeline-state.json; do
-    [ -f "$f" ] || continue
-    if echo "$f" | grep -q "/archive/"; then continue; fi
-    local ph
-    ph=$(jq -r '.current_phase // ""' "$f" 2>/dev/null)
-    if [ "$ph" != "archive" ] && [ "$ph" != "" ]; then
-      echo "$f"
-      return
-    fi
-  done
-  echo ""
+  local sf="$PROJECT_ROOT/specline/changes/$change_name/.pipeline-state.json"
+  if [ ! -f "$sf" ]; then
+    jq --arg sid "$session_id" 'del(.[$sid])' "$BINDINGS_FILE" > "${BINDINGS_FILE}.tmp" && mv "${BINDINGS_FILE}.tmp" "$BINDINGS_FILE"
+    return 1
+  fi
+  STATE_FILE="$sf"
+  return 0
 }
 
+# ===== 辅助函数 =====
+
 deny() {
   local user_msg="$1"
   local agent_msg="$2"
@@ -60,11 +61,9 @@ allow() {
 
 # ===== 主逻辑 =====
 
-STATE_FILE=$(find_active_pipeline)
-
-# 无活跃 pipeline → 透明放行
-if [ -z "$STATE_FILE" ]; then
-  allow
+STATE_FILE=""
+if ! resolve_pipeline_for_session "$SESSION_ID"; then
+  allow   # 无绑定 → 透明放行
   exit 0
 fi
 

package/templates/.cursor/hooks/specline-pipeline-gate.sh

@@ -595,6 +595,15 @@ gate_archive() {
       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
 
@@ -639,6 +648,31 @@ gate_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'"
+}
+
 # ===== 分派 =====
 
 case "$PHASE" in
@@ -669,9 +703,12 @@ case "$PHASE" in
   test-e2e)
     gate_test_e2e
     ;;
+  bind)
+    gate_bind "$2" "$3"
+    ;;
   archive)
     gate_archive "$@"
-    ;;
+    ;; 
   status)
     gate_status
     ;;

package/templates/.cursor/hooks/specline-reminder.sh

@@ -13,6 +13,7 @@ set -euo pipefail
 input=$(cat)
 tool_name=$(echo "$input" | jq -r '.tool_name // empty')
 tool_input=$(echo "$input" | jq -r '.tool_input // "{}"')
+SESSION_ID=$(echo "$input" | jq -r '.session_id // empty')
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
@@ -20,28 +21,35 @@ CHANGES_DIR="$PROJECT_ROOT/specline/changes"
 
 # ===== 辅助函数 =====
 
-find_active_pipeline() {
-  if [ ! -d "$CHANGES_DIR" ]; then
-    echo ""
-    return
+resolve_pipeline_for_session() {
+  local session_id="$1"
+  local bindings_file="$PROJECT_ROOT/specline/.pipeline-sessions.json"
+
+  if [ ! -f "$bindings_file" ]; then
+    return 1
   fi
-  for f in "$CHANGES_DIR"/*/.pipeline-state.json; do
-    [ -f "$f" ] || continue
-    if echo "$f" | grep -q "/archive/"; then continue; fi
-    local ph
-    ph=$(jq -r '.current_phase // ""' "$f" 2>/dev/null)
-    if [ "$ph" != "archive" ] && [ "$ph" != "" ]; then
-      echo "$f"
-      return
-    fi
-  done
-  echo ""
-}
 
-STATE_FILE=$(find_active_pipeline)
+  local change_name
+  change_name=$(jq -r --arg sid "$session_id" '.[$sid].change // empty' "$bindings_file" 2>/dev/null)
+
+  if [ -z "$change_name" ]; then
+    return 1
+  fi
+
+  local state_file="$CHANGES_DIR/$change_name/.pipeline-state.json"
+
+  if [ ! -f "$state_file" ]; then
+    # 脏数据：绑定存在但 pipeline 已不存在，清理绑定
+    jq --arg sid "$session_id" 'del(.[$sid])' "$bindings_file" > "$bindings_file.tmp" && mv "$bindings_file.tmp" "$bindings_file"
+    return 1
+  fi
+
+  STATE_FILE="$state_file"
+  return 0
+}
 
-# 无活跃 pipeline → 透明
-if [ -z "$STATE_FILE" ]; then
+STATE_FILE=""
+if ! resolve_pipeline_for_session "$SESSION_ID"; then
   echo '{}'
   exit 0
 fi

package/templates/.cursor/hooks/specline-session-start.sh

@@ -1,15 +1,28 @@
 #!/usr/bin/env bash
-# specline-session-start.sh — sessionStart Hook
-# 新会话启动时检测活跃 pipeline 并注入上下文到 Agent 系统提示
+# specline-session-start.sh — sessionStart Hook (Pipeline Session Binding)
+#
+# 新会话启动时:
+#   1. 清理过期绑定（7 天未更新）
+#   2. 检查当前 session 是否已有绑定
+#   3. 有绑定且 pipeline 仍活跃 → 使用已有绑定，注入上下文
+#   4. 有绑定但 pipeline 已失效 → 清理脏数据，重新扫描
+#   5. 无绑定 → 扫描活跃 pipeline：
+#      - 0 个 → 透明放行（echo '{}'）
+#      - 1 个 → 自动绑定并注入上下文
+#      - 2+ 个 → 注入"请选择"提示
 #
 # Input (stdin JSON):
-#   { "session_id": "...", "is_background_agent": bool, "composer_mode": "agent"|"ask"|"edit", ... }
+#   { "session_id": "...", "is_background_agent": bool, ... }
 #
 # Output (stdout JSON):
 #   { "additional_context": "<pipeline 上下文>" }  或  {}（无活跃 pipeline）
 
 set -euo pipefail
 
+# ============================================================================
+# Input
+# ============================================================================
+
 input=$(cat)
 
 # 跳过 background agent（子 Agent 不需要 pipeline 上下文）
@@ -19,116 +32,285 @@ if [ "$is_bg" = "true" ]; then
   exit 0
 fi
 
+session_id=$(echo "$input" | jq -r '.session_id // empty')
+if [ -z "$session_id" ]; then
+  echo '{}'
+  exit 0
+fi
+
+# ============================================================================
+# Paths
+# ============================================================================
+
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+BINDINGS_FILE="$PROJECT_ROOT/specline/.pipeline-sessions.json"
 CHANGES_DIR="$PROJECT_ROOT/specline/changes"
 
-# 无 changes 目录 → 无 pipeline
-if [ ! -d "$CHANGES_DIR" ]; then
-  echo '{}'
-  exit 0
-fi
+# ============================================================================
+# Helper Functions
+# ============================================================================
 
-# 扫描活跃 pipeline（排除 archive/）
-active_pipelines=""
-pipeline_count=0
-first_change=""
-first_phase=""
+# init_bindings_file — ensure bindings file exists with a valid JSON object
+init_bindings_file() {
+  if [ ! -f "$BINDINGS_FILE" ]; then
+    mkdir -p "$(dirname "$BINDINGS_FILE")"
+    echo '{}' > "$BINDINGS_FILE"
+  fi
 
-for state_file in "$CHANGES_DIR"/*/.pipeline-state.json; do
-  [ -f "$state_file" ] || continue
+  # Validate it's readable JSON; reset if corrupted
+  if ! jq empty "$BINDINGS_FILE" 2>/dev/null; then
+    echo '{}' > "$BINDINGS_FILE"
+  fi
+}
 
-  # 跳过 archive/
-  parent_dir=$(dirname "$state_file")
-  if echo "$parent_dir" | grep -q "/archive/"; then
-    continue
+# clean_expired_bindings — remove bindings where bound_at > 7 days ago
+# Uses ISO-8601 lexical comparison: works on both macOS and Linux
+clean_expired_bindings() {
+  [ -f "$BINDINGS_FILE" ] || return 0
+
+  local cutoff_date
+  # macOS date, fallback to Linux date
+  cutoff_date=$(date -u -v-7d +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || \
+                date -u -d '7 days ago' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null)
+
+  if [ -z "$cutoff_date" ]; then
+    return 0  # Cannot determine cutoff, skip cleanup
   fi
 
-  change_name=$(jq -r '.change_name // "unknown"' "$state_file" 2>/dev/null)
+  local tmp_file="${BINDINGS_FILE}.tmp"
+  # Keep only entries whose bound_at is >= cutoff (i.e. within the last 7 days)
+  jq --arg cutoff "$cutoff_date" \
+    'with_entries(select(.value.bound_at >= $cutoff))' \
+    "$BINDINGS_FILE" > "$tmp_file" 2>/dev/null && \
+    mv "$tmp_file" "$BINDINGS_FILE" 2>/dev/null || true
+}
+
+# is_pipeline_active — check if a pipeline's state file exists and is not archived
+# Returns 0 (active) or 1 (inactive)
+is_pipeline_active() {
+  local change_name="$1"
+  local state_file="$CHANGES_DIR/$change_name/.pipeline-state.json"
+
+  [ -f "$state_file" ] || return 1
+
+  local phase
   phase=$(jq -r '.current_phase // "unknown"' "$state_file" 2>/dev/null)
-  status=$(jq -r ".phases.${phase}.status // \"unknown\"" "$state_file" 2>/dev/null)
+  [ "$phase" != "archive" ] || return 1
 
-  # 跳过已完成/已归档的
-  if [ "$phase" = "archive" ] || [ "$status" = "completed" ]; then
-    continue
-  fi
+  return 0
+}
 
-  # 收集活跃 pipeline 信息
-  if [ $pipeline_count -eq 0 ]; then
-    first_change="$change_name"
-    first_phase="$phase"
+# scan_active_pipelines — scan changes/ (excluding archive/) for active pipelines
+# Output: one line per pipeline: change_name|phase|state_file_path
+scan_active_pipelines() {
+  if [ ! -d "$CHANGES_DIR" ]; then
+    return 0
   fi
-  pipeline_count=$((pipeline_count + 1))
 
-  # 构建任务进度信息
-  completed=$(jq -r '[.phases.coding.tasks[]? | select(.status == "completed")] | length' "$state_file" 2>/dev/null || echo "0")
-  total=$(jq -r '[.phases.coding.tasks[]?] | length' "$state_file" 2>/dev/null || echo "0")
+  for state_file in "$CHANGES_DIR"/*/.pipeline-state.json; do
+    [ -f "$state_file" ] || continue
 
-  active_pipelines="${active_pipelines}- **${change_name}**: ${phase} 阶段"
-  if [ "$total" != "0" ] && [ "$phase" = "coding" ]; then
-    active_pipelines="${active_pipelines} (${completed}/${total} 任务完成)"
-  fi
-  active_pipelines="${active_pipelines}\n"
-done
+    # Exclude archive/
+    case "$state_file" in
+      */archive/*) continue ;;
+    esac
 
-# 无活跃 pipeline → 透明放行
-if [ $pipeline_count -eq 0 ]; then
-  echo '{}'
-  exit 0
-fi
+    local change_name phase
+    change_name=$(jq -r '.change_name // ""' "$state_file" 2>/dev/null)
+    phase=$(jq -r '.current_phase // ""' "$state_file" 2>/dev/null)
+
+    [ -n "$change_name" ] || continue
+    [ "$phase" != "archive" ] || continue
 
-# 构建阶段约束说明
+    printf '%s|%s|%s\n' "$change_name" "$phase" "$state_file"
+  done
+}
+
+# phase_constraints — output constraint text for a given phase (to stdout)
 phase_constraints() {
-  case "$1" in
+  local phase="$1"
+  case "$phase" in
     spec)
-      echo "- 只能通过 specline-spec-creator / specline-spec-reviewer 子 Agent 工作"
-      echo "- 禁止编辑任何应用代码文件（.ts/.tsx/.py/.go 等）"
-      echo "- 规划文件生成后需运行 Spec Gate"
+      printf '%s\n' "- 只能通过 specline-spec-creator / specline-spec-reviewer 子 Agent 工作"
+      printf '%s\n' "- 禁止编辑任何应用代码文件（.ts/.tsx/.py/.go 等）"
+      printf '%s\n' "- 规划文件生成后需运行 Spec Gate"
       ;;
     coding)
-      echo "- 编码必须通过子 Agent：specline-frontend-dev / specline-backend-dev"
-      echo "- 禁止直接编辑应用代码文件"
-      echo "- 每批次任务完成后运行 Build Gate"
-      echo "- 每个 Task 完成后更新 tasks.md 的 checkbox"
+      printf '%s\n' "- 编码必须通过子 Agent：specline-frontend-dev / specline-backend-dev / specline-config-dev"
+      printf '%s\n' "- 禁止直接编辑应用代码文件"
+      printf '%s\n' "- 每批次任务完成后运行 Build Gate"
+      printf '%s\n' "- 每个 Task 完成后更新 tasks.md 的 checkbox"
       ;;
     code_review)
-      echo "- 只能运行 specline-code-reviewer + Lint Gate"
-      echo "- 如需修复代码，通过子 Agent 完成"
+      printf '%s\n' "- 只能运行 specline-code-reviewer + Lint Gate"
+      printf '%s\n' "- 如需修复代码，通过子 Agent 完成"
       ;;
     test)
-      echo "- 运行测试 Gate 链：unit → integration → e2e"
-      echo "- 测试失败时通过 specline-test-runner 分析原因"
-      echo "- 代码修复通过子 Agent，测试修复通过 specline-test-writer"
+      printf '%s\n' "- 运行测试 Gate 链：unit → integration → e2e"
+      printf '%s\n' "- 测试失败时通过 specline-test-runner 分析原因"
+      printf '%s\n' "- 代码修复通过子 Agent，测试修复通过 specline-test-writer"
       ;;
     *)
-      echo "- 遵循 specline-pipeline SKILL 的当前阶段约束"
+      printf '%s\n' "- 遵循 specline-pipeline SKILL 的当前阶段约束"
       ;;
   esac
 }
 
-# 生成上下文
-constraints=$(phase_constraints "$first_phase")
-
-# 用 printf 构建 JSON，避免 heredoc 中的转义问题
-# 注意：additional_context 内容中的换行符和引号需要正确转义
-context_text=""
-context_text+="🚨 **Specline Pipeline 运行中**\n\n"
-if [ $pipeline_count -eq 1 ]; then
-  context_text+="**当前变更**: ${first_change}\n"
-  context_text+="**当前阶段**: ${first_phase}\n\n"
-else
-  context_text+="**活跃变更** (${pipeline_count} 个):\n${active_pipelines}\n"
-fi
-context_text+="**阶段约束**:\n${constraints}\n\n"
-context_text+="**重要**: 你是 Specline Pipeline 编排者。上述约束具有最高优先级，必须在每个操作前检查是否符合当前阶段要求。"
+# build_context — generate a JSON-escaped additional_context string for a bound pipeline
+build_context() {
+  local change_name="$1"
+  local phase="$2"
+  local state_file="$3"
+
+  {
+    printf '🚨 **Specline Pipeline 运行中**\n\n'
+    printf '**当前变更**: %s\n' "$change_name"
+    printf '**当前阶段**: %s\n' "$phase"
 
-# 转义 JSON 字符串
-escaped_context=$(echo -e "$context_text" | jq -Rs '.')
+    # Task progress for coding phase
+    if [ "$phase" = "coding" ] && [ -f "$state_file" ]; then
+      local completed total
+      completed=$(jq -r '[.phases.coding.tasks[]? | select(.status == "completed")] | length' "$state_file" 2>/dev/null || printf '0')
+      total=$(jq -r '[.phases.coding.tasks[]?] | length' "$state_file" 2>/dev/null || printf '0')
+      if [ "$total" != "0" ]; then
+        printf '**任务进度**: %s/%s 完成\n' "$completed" "$total"
+      fi
+    fi
 
-cat << EOF
-{
-  "additional_context": ${escaped_context}
+    printf '\n**阶段约束**:\n'
+    phase_constraints "$phase"
+    printf '\n'
+    printf '**重要**: 你是 Specline Pipeline 编排者。上述约束具有最高优先级，必须在每个操作前检查是否符合当前阶段要求。'
+  } | jq -Rs '.'
 }
-EOF
 
+# phase_constraint_table — static phase constraint reference table (markdown)
+phase_constraint_table() {
+  cat << 'TABLEEOF'
+| 阶段 | 约束 |
+|------|------|
+| spec | 只能通过 specline-spec-creator/specline-spec-reviewer 子 Agent 工作，禁止编辑代码 |
+| coding | 必须通过子 Agent 编码，批次完成后运行 Build Gate，更新 tasks.md |
+| code_review | 只能运行 specline-code-reviewer + Lint Gate |
+| test | 运行测试 Gate 链：unit → integration → e2e |
+TABLEEOF
+}
+
+# write_binding — write a session_id → change_name binding to .pipeline-sessions.json
+write_binding() {
+  local sid="$1"
+  local change="$2"
+
+  local now_iso
+  now_iso=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+  local tmp_file="${BINDINGS_FILE}.tmp"
+  jq --arg sid "$sid" --arg change "$change" --arg now "$now_iso" \
+    '.[$sid] = {"change": $change, "bound_at": $now}' \
+    "$BINDINGS_FILE" > "$tmp_file" 2>/dev/null && \
+    mv "$tmp_file" "$BINDINGS_FILE" 2>/dev/null || true
+}
+
+# delete_binding — remove a session_id entry from .pipeline-sessions.json
+delete_binding() {
+  local session_id="$1"
+
+  [ -f "$BINDINGS_FILE" ] || return 0
+
+  local tmp_file="${BINDINGS_FILE}.tmp"
+  jq --arg sid "$session_id" 'del(.[$sid])' "$BINDINGS_FILE" > "$tmp_file" 2>/dev/null && \
+    mv "$tmp_file" "$BINDINGS_FILE" 2>/dev/null || true
+}
+
+# ============================================================================
+# Main Logic
+# ============================================================================
+
+init_bindings_file
+
+# 1. Clean expired bindings (bound_at > 7 days ago)
+clean_expired_bindings
+
+# 2. Check existing binding for this session
+existing_change=""
+if [ -f "$BINDINGS_FILE" ]; then
+  existing_change=$(jq -r --arg sid "$session_id" '.[$sid].change // empty' "$BINDINGS_FILE" 2>/dev/null)
+fi
+
+if [ -n "$existing_change" ]; then
+  if is_pipeline_active "$existing_change"; then
+    # Binding is still valid — use it
+    state_file="$CHANGES_DIR/$existing_change/.pipeline-state.json"
+    phase=$(jq -r '.current_phase // "unknown"' "$state_file" 2>/dev/null)
+
+    ctx_json=$(build_context "$existing_change" "$phase" "$state_file")
+
+    printf '{\n  "additional_context": %s\n}\n' "$ctx_json"
+    exit 0
+  else
+    # Dirty data: pipeline archived or deleted — clean up and rescan
+    delete_binding "$session_id"
+  fi
+fi
+
+# 3. No (valid) binding — scan active pipelines
+scan_result=$(scan_active_pipelines)
+
+# Count active pipelines
+pipeline_count=0
+if [ -n "$scan_result" ]; then
+  pipeline_count=$(printf '%s\n' "$scan_result" | wc -l | tr -d ' ')
+fi
+
+# 0 active pipelines → transparent pass-through
+if [ "$pipeline_count" -eq 0 ]; then
+  echo '{}'
+  exit 0
+fi
+
+# 1 active pipeline → auto-bind and inject context
+if [ "$pipeline_count" -eq 1 ]; then
+  change_name=$(printf '%s' "$scan_result" | cut -d'|' -f1)
+  phase=$(printf '%s' "$scan_result" | cut -d'|' -f2)
+  state_file=$(printf '%s' "$scan_result" | cut -d'|' -f3)
+
+  # Auto-bind
+  write_binding "$session_id" "$change_name"
+
+  # Inject context
+  ctx_json=$(build_context "$change_name" "$phase" "$state_file")
+
+  printf '{\n  "additional_context": %s\n}\n' "$ctx_json"
+  exit 0
+fi
+
+# 4. 2+ active pipelines → inject selection prompt (do NOT auto-bind)
+ctx_json=$({
+  printf '🚨 **Specline Pipeline 运行中 — 请选择 Pipeline**\n\n'
+  printf '**活跃 Pipeline** (%s 个):\n' "$pipeline_count"
+
+  while IFS='|' read -r change_name phase state_file; do
+    [ -n "$change_name" ] || continue
+    printf -- '- **%s**: %s 阶段' "$change_name" "$phase"
+
+    # Add task progress for coding phase
+    if [ "$phase" = "coding" ] && [ -f "$state_file" ]; then
+      completed=$(jq -r '[.phases.coding.tasks[]? | select(.status == "completed")] | length' "$state_file" 2>/dev/null || printf '0')
+      total=$(jq -r '[.phases.coding.tasks[]?] | length' "$state_file" 2>/dev/null || printf '0')
+      if [ "$total" != "0" ]; then
+        printf ' (%s/%s 任务完成)' "$completed" "$total"
+      fi
+    fi
+    printf '\n'
+  done <<< "$scan_result"
+
+  printf '\n**说明**: 当前发现了 %s 个活跃 Pipeline，但尚未绑定到本会话。\n' "$pipeline_count"
+  printf '**操作**: 请使用 `/specline-pipeline --change <名称>` 选择一个 Pipeline 以继续工作。\n\n'
+  printf '**阶段约束参考**:\n'
+  phase_constraint_table
+  printf '\n**提示**: 绑定后系统会自动注入正确的阶段上下文和约束。\n'
+} | jq -Rs '.')
+
+printf '{\n  "additional_context": %s\n}\n' "$ctx_json"
 exit 0

package/templates/.cursor/skills/specline-explore/SKILL.md

@@ -9,6 +9,23 @@ metadata:
   generatedBy: "1.3.1"
 ---
 
+## ⚠️ Mode Check — Read Before Anything Else
+
+探索模式 MUST run in **Ask Mode** for hard read-only enforcement by Cursor.
+
+### Your very first action
+
+1.  Check which Cursor mode you are currently in (agent / ask / plan).
+2.  **If you are NOT in Ask Mode** — Output ONLY the following message and STOP. Do not explore, do not read files, do not do anything else:
+
+    > 探索模式需要在只读（Ask）模式下运行。请点击输入框左侧的模式选择器，切换到 **Ask 模式**，然后重新输入 `/specline-explore`。
+
+3.  **If you are in Ask Mode** — You are in a safe, read-only environment. The system guarantees you cannot edit files, create files, rewrite files, delete files, or run commands. Proceed with exploration freely.
+
+### Why this matters
+
+Ask Mode is Cursor's only truly read-only mode. In Agent/Plan mode, only Prompt-level instructions prevent code changes — and those can be ignored. Ask Mode enforces read-only at the system level, making it impossible to accidentally modify files during exploration.
+
 > **One-liner**: You're a thinking partner, not an implementer.
 > **What you can do**: Read code, draw diagrams, compare options, ask questions, challenge assumptions
 > **What you can't do**: Write implementation code

package/templates/.cursor/skills/specline-pipeline/SKILL.md

@@ -9,6 +9,67 @@ description: >-
 
 ---
 
+## Layer 0: Session 绑定与 Pipeline 切换
+
+### 概述
+
+每个 Cursor 会话通过 `session_id` 绑定到特定的 Pipeline。Hook 脚本通过查 `specline/.pipeline-sessions.json` 表获得确定性映射，替代原有的非确定性 `find_active_pipeline()` 扫描逻辑。
+
+### 启动时自动绑定
+
+`sessionStart` Hook (`specline-session-start.sh`) 自动处理：
+
+1. **已绑定且有效** → 直接使用，注入正确的阶段约束
+2. **无绑定 + 1 个活跃 Pipeline** → 自动绑定当前 session 到该 Pipeline
+3. **无绑定 + 2+ 个活跃 Pipeline** → 注入提示，编排者必须用 AskUserQuestion 让用户选择
+4. **过期绑定清理** → `bound_at` 超过 7 天的绑定自动删除
+5. **脏数据清理** → 绑定指向已归档/不存在的 Pipeline 时自动删除
+
+### 编排者收到「多 Pipeline 未绑定」提示时
+
+当 sessionStart 注入上下文提示有多个 pipeline 未绑定时，编排者**必须**使用 AskUserQuestion 让用户选择：
+
+```javascript
+AskUserQuestion({
+  title: "选择 Pipeline",
+  questions: [{
+    id: "pipeline_select",
+    prompt: "当前有 " + count + " 个活跃 Pipeline，请选择要绑定到本会话的：",
+    options: [
+      { id: "change-a", label: "change-a (SPEC 阶段)" },
+      { id: "change-b", label: "change-b (CODING 阶段, 3/7 任务)" },
+    ],
+    allow_multiple: false
+  }]
+})
+```
+
+用户选择后，编排者执行绑定命令：
+
+```bash
+.cursor/hooks/specline-pipeline-gate.sh bind <session_id> <selected_change>
+```
+
+### 用户要求切换 Pipeline 时
+
+当用户在对话中说「帮我处理 \<other-change\>」：
+
+1. 检查当前 Pipeline 是否在安全切换点（Gate 之后、批次之间）
+2. 如果当前在 CODING 批次中间 → 提示「请先完成当前批次」
+3. 否则执行切换：
+
+```bash
+.cursor/hooks/specline-pipeline-gate.sh bind <session_id> <other_change>
+```
+
+绑定后，下一个 Hook 调用立即生效。
+
+### Pipeline 归档时自动解绑
+
+`gate archive --execute` 会自动清理所有绑定到该 Pipeline 的 session 记录，无需手工操作。
+
+---
+
 ## Layer 1: 速览与定位
 
 你是**流水线编排者**，不是执行者。