specline 1.1.2 → 1.2.0

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,25 @@
 #!/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. 无绑定 → 透明放行（echo '{}'）——不自动绑定，避免跨窗口污染
 #
 # 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 +29,231 @@ 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
+# ============================================================================
+
+# 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
+
+  # Validate it's readable JSON; reset if corrupted
+  if ! jq empty "$BINDINGS_FILE" 2>/dev/null; then
+    echo '{}' > "$BINDINGS_FILE"
+  fi
+}
 
-# 扫描活跃 pipeline（排除 archive/）
-active_pipelines=""
-pipeline_count=0
-first_change=""
-first_phase=""
+# 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
 
-for state_file in "$CHANGES_DIR"/*/.pipeline-state.json; do
-  [ -f "$state_file" ] || continue
+  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)
 
-  # 跳过 archive/
-  parent_dir=$(dirname "$state_file")
-  if echo "$parent_dir" | grep -q "/archive/"; then
-    continue
+  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 → transparent pass-through
+# 不再自动绑定或注入任何 pipeline 上下文，避免跨窗口污染。
+# 用户需通过 /specline-pipeline --change <name> 显式绑定。
+echo '{}'
 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