specline 1.1.3 → 1.2.0

package/README.md

@@ -8,8 +8,16 @@
 /specline-pipeline "实现用户登录功能"
 ```
 
+修 bug、改配置、文档微调？用轻量模式：
+
+```
+/specline-quickfix "修复登录按钮样式"
+```
+
 ## 它能做什么
 
+**完整流水线**（新功能、重构）：
+
 ```
 自然语言需求 → Spec → 审核 → 编码 → 审查 → 测试 → 归档
                 ↑       ↑      ↑      ↑      ↑      ↑
@@ -18,12 +26,20 @@
                   并行              reviewer  E2E
 ```
 
+**轻量修复**（修 bug、改配置、文档微调）：
+
+```
+/ specline-quickfix "描述" → 理解代码 → 直接编辑 → Lint+自审 → 现有单测 → 轻量归档
+                             0 个子 Agent      0 个人工确认      0 个 state 文件
+```
+
 每个阶段都经过 **确定性门禁校验** —— 用 `grep`、`jq`、编译器退出码、测试退出码判断通过与否。**质量判断零 LLM 参与**。
 
 ## 核心特性
 
 - **需求驱动**：自然语言 → 结构化规格文档（Requirements + Scenarios + WHEN/THEN）
 - **并行编码**：自动按前端/后端/config 拆分任务，同批次并发派发 Coding Agent
+- **TDD 白盒测试**：无依赖任务自动启用 TDD 模式（先写单测 → 确认失败 → 最小实现 → 重构），与黑盒 test-writer 并行协作
 - **确定性门禁**：每个阶段用 Shell 脚本的退出码判定是否通过，不做模糊判断
 - **黑盒测试**：测试 Agent 只看 Spec 文档，不能读取任何实现源码
 - **断点续跑**：随时中断，下次从最后一个可信门禁自动恢复（tasks.md 的 `[x]`/`[ ]` 标记进度）
@@ -59,8 +75,8 @@ specline sync --dry-run    # 预览变更
 my-project/
 ├── .cursor/
 │   ├── agents/          ← 9 个 Specline Agent 定义
-│   ├── commands/        ← 2 个 Slash 命令入口
-│   ├── skills/          ← 5 个 Skill 指令
+│   ├── commands/        ← 3 个 Slash 命令入口
+│   ├── skills/          ← 6 个 Skill 指令
 │   ├── hooks/           ← 7 个 Gate/Hook 脚本
 │   └── hooks.json       ← Cursor Hook 配置
 ├── specline/            ← 运行时目录
@@ -77,13 +93,36 @@ my-project/
 /specline-pipeline "添加 JWT 用户认证"
 ```
 
+小改动用快速模式：
+
+```
+/specline-quickfix "修改按钮颜色"
+```
+
 开始编码前先探索思路：
 
 ```
 /specline-explore
 ```
 
-## 流水线阶段
+## 工作流选择
+
+Specline 提供两种工作流，按变更规模选择：
+
+| 维度 | Quickfix (`/specline-quickfix`) | Pipeline (`/specline-pipeline`) |
+|------|-------------------------------|-------------------------------|
+| 文件改动数 | 1-3 个 | 4+ 个 |
+| 关注点 | 单一关注点 | 多关注点/跨模块 |
+| 架构变更 | 无新架构/新组件 | 需要新组件/新 API |
+| 测试 | 不需要新测试 | 需要写新测试 |
+| 典型场景 | 修 bug、改配置、文档微调 | 新增功能、重构 |
+| 产出 | summary.md + files-changed.json | proposal/design/tasks/specs + 全部测试 |
+| 人工确认 | 0 个 | 3 个 |
+| 耗时 | 1-3 分钟 | 10-30 分钟 |
+
+**使用建议**：如果不确定，优先用 quickfix。如果需要更严格的流程保证，用 pipeline。
+
+## 完整流水线阶段
 
 ```
 PHASE 1: SPEC（规格）
@@ -91,15 +130,16 @@ PHASE 1: SPEC（规格）
     ├── proposal.md    — 需求提案（What/Why/Scope）
     ├── specs/*/spec.md — 功能规格（Requirements/Scenarios/WHEN-THEN）
     ├── design.md      — 技术设计（架构/数据流/决策）
-    └── tasks.md       — 任务清单（Type/Depends/Covers/Files + [ ] 进度标记）
+    └── tasks.md       — 任务清单（Type/Depends/Covers/Testable/Files + [ ] 进度标记）
   → specline-spec-reviewer 审核
   → Gate: grep + jq 格式校验
   → 🟡 人工确认 Spec 和任务规划
 
 PHASE 2: CODING（编码）
   解析 tasks.md → 按依赖 DAG 分层 → 同批次前后端/config Agent 并发
+  无依赖 + 可测试任务 → 自动启用 TDD 模式（RED-GREEN-REFACTOR）
   每完成一个任务，[ ] 自动标记为 [x]
-  → Gate: 编译检查（tsc --noEmit / python -m compileall）
+  → Gate: 编译检查（tsc --noEmit / python -m compileall） + 单元测试文件存在性检查
 
 PHASE 3: REVIEW（审查）
   specline-code-reviewer + specline-config-reviewer 分别审查代码和配置/文档
@@ -116,16 +156,55 @@ PHASE 5: ARCHIVE（归档）
   → delta specs 合并到主规格目录
   → 按日期归档到 specline/changes/archive/
   ✅ 完成
+
+### TDD 白盒测试
+
+Pipeline 采用「两层测试分离」架构：
+
+```
+Coding Agent（白盒 TDD）              Test-Writer（黑盒）
+─────────────────────────            ─────────────────
+产出: tests/unit/**                  产出: tests/integration/**
+      tests/models/**                      tests/e2e/**
+测试: 单个函数的输入输出              测试: 跨模块的用户行为
+      边界条件、异常路径                     API 端到端契约
+      Spec Scenario 全覆盖
+触发: 编码时同步产出                   触发: Phase 2 与 Coding 并行启动
+      先写测试 → 确认失败 → 写实现        只读 Spec，不读源码
+```
+
+tasks.md 中 `Testable: true` 的任务自动启用 TDD 模式（完整 RED-GREEN-REFACTOR 循环），`Testable: false` 的任务保持原有流程。两个测试域严格目录隔离，冲突检测自动识别越界。
+```
+
+## 轻量修复流程
+
+```
+PHASE 1: UNDERSTAND（理解）
+  读取相关代码 → 理解上下文 → 意图模糊时 AskUserQuestion 确认
+
+PHASE 2: IMPLEMENT（实现）
+  直接 Write/StrReplace 编辑 1-3 个文件
+  不需要 Spec 文档、DAG 构建、批次调度
+
+PHASE 3: REVIEW（审查）
+  ReadLints 检查 + 自动修复（最多 2 次）→ Agent 自审逻辑正确性
+
+PHASE 4: TEST（测试）
+  仅运行项目已有单元测试，无测试则跳过
+  失败自动修复最多 2 次
+
+PHASE 5: ARCHIVE（归档）
+  生成 summary.md + files-changed.json → 询问是否 git commit
 ```
 
 ## 架构
 
 ```
-/specline-pipeline       ← 你输入这个
-    │
-    ▼
-specline-pipeline SKILL  ← 编排层（读状态、派发 Agent、调 Gate）
-    │
+/specline-pipeline       ← 完整流水线（大功能）    /specline-quickfix    ← 轻量修复（小改动）
+    │                                                  │
+    ▼                                                  ▼
+specline-pipeline SKILL  ← 编排层                 编排者直接执行（无子 Agent）
+    │                                               Read → Write → ReadLints → Shell → 归档
 ┌───┼──────────────────┬──────────────────────┐
 ▼   ▼                  ▼                      ▼
 9 个子 Agent      specline-pipeline-     Cursor Hooks
@@ -149,13 +228,13 @@ specline-pipeline SKILL  ← 编排层（读状态、派发 Agent、调 Gate）
 |-------|------|
 | `specline-spec-creator` | 根据自然语言需求，基于内联模板直接生成 proposal/design/tasks/spec 四个文件 |
 | `specline-spec-reviewer` | 审核规格的完整性、一致性和覆盖度 |
-| `specline-frontend-dev` | UI 组件、页面、样式、交互逻辑（单个任务级别） |
-| `specline-backend-dev` | API 端点、数据模型、业务逻辑（单个任务级别） |
+| `specline-frontend-dev` | UI 组件、页面、样式、交互逻辑（单个任务级别，Testable 任务启用 TDD） |
+| `specline-backend-dev` | API 端点、数据模型、业务逻辑（单个任务级别，Testable 任务启用 TDD） |
 | `specline-config-dev` | Shell 脚本、配置文件（JSON/YAML）、Markdown 文档（处理 Type: config/docs 任务） |
 | `specline-code-reviewer` | 前端/后端代码质量、安全性、可维护性审查 |
 | `specline-config-reviewer` | Shell 脚本安全性、配置文件语法和一致性、Markdown 文档结构审查 |
-| `specline-test-writer` | 黑盒测试编写——只能看 Spec，不能读源码 |
-| `specline-test-runner` | 执行测试并分类失败原因（测试问题/代码问题/Spec 模糊） |
+| `specline-test-writer` | 黑盒测试编写——只能看 Spec 不能读源码，仅写集成测试（tests/integration/）和 E2E 测试 |
+| `specline-test-runner` | 执行测试并分类失败原因（测试问题/代码问题/Spec 模糊），区分单元测试（回 coding agent）和集成/E2E 测试（回 test-writer） |
 
 ## 确定性门禁
 
@@ -163,8 +242,8 @@ specline-pipeline SKILL  ← 编排层（读状态、派发 Agent、调 Gate）
 
 | 门禁 | 检查内容 |
 |------|---------|
-| Spec | `grep` 检查 Purpose/Requirements/Scenarios 章节完整性、WHEN/THEN 配对 |
-| Build | `tsc --noEmit` / `python -m compileall` 编译检查 |
+| Spec | `grep` 检查 Purpose/Requirements/Scenarios 章节完整性、WHEN/THEN 配对、Testable 字段格式与一致性 |
+| Build | `tsc --noEmit` / `python -m compileall` 编译检查 + Testable 任务单元测试文件存在性与语法检查 |
 | Lint | `ruff` / `eslint` 退出码 + code-review.json 中 error 数量 |
 | Test | 测试框架退出码 + 覆盖率阈值 |
 | Archive | 归档目录结构 + 必要文件完整性 |

package/package.json

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

package/templates/.cursor/agents/specline-spec-reviewer.md

@@ -49,6 +49,7 @@ description: 审核 spec.md、design.md、tasks.md 的完整性和一致性。
    - 每个任务含 `Depends:` 标注
    - 每个任务含 `Covers:` 标注（链接到具体的 Requirement 和 Scenario）
    - 每个任务含 `Files:` 标注（非空，列出预期文件）
+   - 每个任务含 `Testable:` 标注（值在 true/false 范围内，可选但建议标注）
 
 2. **独立性**：
    - `Depends: (none)` 的任务占比 ≥ 50%（否则标记为 warning）
@@ -63,6 +64,12 @@ description: 审核 spec.md、design.md、tasks.md 的完整性和一致性。
    - backend 类型的任务应涉及 API/模型/逻辑
    - 没有 fullstack 类型（前端和后端必须拆开）
 
+5. **Testable 合理性**：
+   - `Testable: true` 的任务必须满足：Depends: (none) + Type ≠ config/docs + 有可拆分的独立逻辑单元
+   - `Testable: false` 的任务如果同时满足 Depends: (none) + Type ≠ config/docs + 有独立逻辑单元 → warning（建议标记为 Testable: true）
+   - 有上游依赖的任务 Testable 必须为 false
+   - Type 为 config/docs 的任务 Testable 必须为 false
+
 ## 输出格式
 
 产出 `specline/changes/<change-name>/specs/<capability>/spec-review.json`：
@@ -81,6 +88,7 @@ description: 审核 spec.md、design.md、tasks.md 的完整性和一致性。
     "total": 6,
     "independent": 4,
     "parallel_ratio": 0.67,
+    "testable_count": 3,
     "types": { "frontend": 2, "backend": 3, "config": 1 }
   },
   "design_review": {
@@ -98,11 +106,13 @@ description: 审核 spec.md、design.md、tasks.md 的完整性和一致性。
     "[spec.md] 缺少异常路径场景：未定义 'worker 数量为 0' 时的行为",
     "[tasks.md] 任务 3 缺少 Covers 标注",
     "[tasks.md] 任务 1 和 任务 2 的 Files 有交集：都包含了 src/utils/api.ts",
+    "[tasks.md] 任务 3 Testable=true 但存在上游依赖 (Depends: 1)，应为 false",
+    "[tasks.md] 任务 5 (Depends: none, Type: backend) 建议标记为 Testable: true",
     "[design.md] 提到使用 Redis 缓存，但 tasks.md 中没有对应的 infra 任务",
     "[coverage] Scenario '用户登出' 未被任何任务覆盖"
   ],
   "coverage": { "requirements_covered": 4, "requirements_total": 5, "scenarios_covered": 10, "scenarios_total": 14 },
-  "task_stats": { "total": 6, "independent": 4, "parallel_ratio": 0.67, "types": { "frontend": 2, "backend": 3, "config": 1 } },
+  "task_stats": { "total": 6, "independent": 4, "parallel_ratio": 0.67, "testable_count": 3, "types": { "frontend": 2, "backend": 3, "config": 1 } },
   "design_review": { "issues": ["Redis 缓存方案缺少对应的 infra 任务"] }
 }
 ```

package/templates/.cursor/commands/specline-quickfix.md

@@ -0,0 +1,24 @@
+---
+name: /specline-quickfix
+id: specline-quickfix
+category: Workflow
+description: 轻量修改 Skill —— 小改动用 quickfix，大功能用 pipeline
+---
+
+轻量修改流程，在不创建规划文档的情况下快速执行小改动。
+
+**用法：**
+- `/specline-quickfix <描述>` — 执行轻量修改流程（修 bug、改配置、文档微调等小改动）
+
+**阶段：**
+1. UNDERSTAND — 读取相关代码，理解变更上下文
+2. IMPLEMENT — 直接编辑文件（单 Agent，无子 Agent）
+3. REVIEW — ReadLints 自动校验 + 修复（最多 2 次）+ Agent 自审
+4. TEST — 运行项目已有单元测试（失败修复最多 2 次），无测试则跳过
+5. ARCHIVE — 生成 summary.md + files-changed.json，询问 git commit
+
+**适用场景**：1-3 个文件改动、单一关注点、不涉及架构变更、不需要新测试。
+
+**不适合的场景**（应使用 `/specline-pipeline`）：4+ 个文件改动、新增功能/重构、需要新测试、跨模块/多关注点。
+
+0 个人工确认点，全程自动质量保证。

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

@@ -15,19 +15,27 @@
 
 set -euo pipefail
 
-# ===== 参数解析 =====
 PHASE="${1:-}"
 CHANGE=""
-if [ "$#" -ge 3 ] && [ "$2" = "--change" ]; then
-  CHANGE="$3"
-fi
-
-if [ -z "$PHASE" ]; then
-  echo "Usage: specline-pipeline-gate.sh <phase> --change <change-name>"
-  echo "Phases: new | list | artifacts | spec | build | lint | test-unit | test-integration | test-e2e | archive | status"
-  exit 2
-fi
-
+EXECUTE_ARCHIVE=""
+
+# 遍历所有参数，不依赖位置
+shift  # 跳过 PHASE
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --change)
+      CHANGE="$2"
+      shift 2
+      ;;
+    --execute)
+      EXECUTE_ARCHIVE="--execute"
+      shift
+      ;;
+    *)
+      shift
+      ;;
+  esac
+done
 # ===== 项目根目录 =====
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
@@ -300,7 +308,31 @@ gate_spec() {
   fi
   pass "tasks.md 标注完整性检查通过 ($task_count 个任务)"
 
-  # 10. 至少 1 个任务无依赖
+  # 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
@@ -337,6 +369,86 @@ gate_build() {
     pass "Python 语法检查通过"
   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/ 下的测试文件"
+          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 ! python -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_unit_test = 0
+            for (i in paths) {
+              gsub(/^[ \t]+|[ \t]+$/, "", paths[i])
+              if (paths[i] ~ /^tests\/(unit|models)\//) {
+                print task_id "|" paths[i]
+                has_unit_test = 1
+              }
+            }
+            if (has_unit_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 全部通过"
 }
@@ -551,7 +663,7 @@ gate_archive() {
   fi
 
   # 如果传了 --execute，执行实际归档动作
-  if [ "${1:-}" = "--execute" ]; then
+  if [ -n "$EXECUTE_ARCHIVE" ]; then
     local src_dir="$PROJECT_ROOT/specline/changes/$CHANGE"
     local archive_dir="$PROJECT_ROOT/specline/changes/archive"
     local date_prefix

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

@@ -6,10 +6,7 @@
 #   2. 检查当前 session 是否已有绑定
 #   3. 有绑定且 pipeline 仍活跃 → 使用已有绑定，注入上下文
 #   4. 有绑定但 pipeline 已失效 → 清理脏数据，重新扫描
-#   5. 无绑定 → 扫描活跃 pipeline：
-#      - 0 个 → 透明放行（echo '{}'）
-#      - 1 个 → 自动绑定并注入上下文
-#      - 2+ 个 → 注入"请选择"提示
+#   5. 无绑定 → 透明放行（echo '{}'）——不自动绑定，避免跨窗口污染
 #
 # Input (stdin JSON):
 #   { "session_id": "...", "is_background_agent": bool, ... }
@@ -254,63 +251,9 @@ if [ -n "$existing_change" ]; then
   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"
+# 3. No (valid) binding → transparent pass-through
+# 不再自动绑定或注入任何 pipeline 上下文，避免跨窗口污染。
+# 用户需通过 /specline-pipeline --change <name> 显式绑定。
+echo '{}'
 exit 0

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

@@ -13,42 +13,18 @@ description: >-
 
 ### 概述
 
-每个 Cursor 会话通过 `session_id` 绑定到特定的 Pipeline。Hook 脚本通过查 `specline/.pipeline-sessions.json` 表获得确定性映射，替代原有的非确定性 `find_active_pipeline()` 扫描逻辑。
+每个 Cursor 会话通过 `session_id` **显式绑定**到特定的 Pipeline（通过 `/specline-pipeline --change <name>` 命令）。Hook 脚本通过查 `specline/.pipeline-sessions.json` 表获得确定性映射。
 
-### 启动时自动绑定
+### 启动时行为
 
 `sessionStart` Hook (`specline-session-start.sh`) 自动处理：
 
 1. **已绑定且有效** → 直接使用，注入正确的阶段约束
-2. **无绑定 + 1 个活跃 Pipeline** → 自动绑定当前 session 到该 Pipeline
-3. **无绑定 + 2+ 个活跃 Pipeline** → 注入提示，编排者必须用 AskUserQuestion 让用户选择
-4. **过期绑定清理** → `bound_at` 超过 7 天的绑定自动删除
-5. **脏数据清理** → 绑定指向已归档/不存在的 Pipeline 时自动删除
+2. **无绑定** → 透明放行（`echo '{}'`），不自动扫描活跃 pipeline，不注入任何上下文
+3. **过期绑定清理** → `bound_at` 超过 7 天的绑定自动删除
+4. **脏数据清理** → 绑定指向已归档/不存在的 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>
-```
+> **重要**：sessionStart 不再自动扫描和绑定活跃 pipeline。要绑定到一个 Pipeline，需要显式执行 `/specline-pipeline --change <name>`。
 
 ### 用户要求切换 Pipeline 时
 
@@ -105,6 +81,21 @@ AskUserQuestion({
 
 归档到 `specline/changes/archive/YYYY-MM-DD-<name>/`
 
+### Quickfix vs Pipeline 边界判断
+
+| 维度 | Quickfix (`/specline-quickfix`) | Pipeline (`/specline-pipeline`) |
+|------|-------------------------------|-------------------------------|
+| 文件改动数 | 1-3 个 | 4+ 个 |
+| 关注点 | 单一关注点 | 多关注点/跨模块 |
+| 架构变更 | 无新架构/新组件 | 需要新组件/新 API |
+| 测试 | 不需要新测试 | 需要写新测试 |
+| 典型场景 | 修 bug、改配置、文档微调 | 新增功能、重构 |
+| 产出 | summary.md + files-changed.json | proposal/design/tasks/specs + 全部测试 |
+| 人工确认 | 0 个 | 3 个 |
+| 耗时 | 1-3 分钟 | 10-30 分钟 |
+
+**使用建议**：如果不确定，优先用 quickfix。如果需要更严格的流程保证，用 pipeline。
+
 ---
 
 ## Layer 2: Happy Path — 新建流水线
@@ -266,6 +257,7 @@ Task({
 2. 先检测项目的测试框架（读配置文件），按项目实际语言和框架编写测试
 3. 每个 Scenario 至少生成 1 个对应的测试函数（命名遵循框架约定）
 4. 基于 Covers 追溯链，确保每个 Scenario 都有测试
+5. 只编写 tests/integration/** 和 tests/e2e/** 目录下的测试，不得编写 tests/unit/** 和 tests/models/** 下的测试（单元测试由 coding agent 的 TDD 流程负责）
 
 ## 产出报告
 完成后在 specline/changes/${changeName}/.tmp/test-code-result.json 写入状态（含 test_framework / language / test_dir / scenarios_covered 等字段）
@@ -285,16 +277,17 @@ Task({
 TASKS_FILE="specline/changes/<name>/tasks.md"
 
 # 提取每个任务的核心元数据
-# 期望输出格式：TASK_NUM|TYPE|DEPS|COVERS|FILES
-rg -N --no-line-number '^## \d+\.|^- \*\*Type\*\*:|^- \*\*Depends\*\*:|^- \*\*Covers\*\*:|^- \*\*Files\*\*:' "$TASKS_FILE" | while read -r line; do
+# 期望输出格式：TASK_NUM|TYPE|DEPS|COVERS|FILES|TESTABLE
+rg -N --no-line-number '^## \d+\.|^- \*\*Type\*\*:|^- \*\*Depends\*\*:|^- \*\*Covers\*\*:|^- \*\*Files\*\*:|^- \*\*Testable\*\*:' "$TASKS_FILE" | while read -r line; do
   # 解析并按批次分组
   ...
 done
 
-# 构建任务列表写入状态文件（含 Files 用于冲突检测，Covers 用于追溯）
+# 构建任务列表写入状态文件（含 Files 用于冲突检测，Covers 用于追溯，Testable 用于 TDD 判定）
+# Testable 缺失时默认为 false（向后兼容）
 jq --argjson tasks '[
-  {"id":"1","type":"backend","deps":[],"batch":1,"status":"pending","covers":"Requirement: 数据模型","files":["server/models.py"]},
-  {"id":"2","type":"frontend","deps":[],"batch":1,"status":"pending","covers":"Requirement: 登录页面","files":["src/components/Login.tsx"]}
+  {"id":"1","type":"backend","deps":[],"batch":1,"status":"pending","testable":true,"covers":"Requirement: 数据模型","files":["server/models.py"]},
+  {"id":"2","type":"frontend","deps":[],"batch":1,"status":"pending","testable":false,"covers":"Requirement: 登录页面","files":["src/components/Login.tsx"]}
 ]' '.phases.coding.tasks = $tasks' "$STATE_FILE" > tmp && mv tmp "$STATE_FILE"
 ```
 
@@ -304,12 +297,31 @@ jq --argjson tasks '[
 
 **6c. 文件冲突检测（每批次派发前）**：
 
-在派发每批任务之前，检查该批次中所有任务的 `Files` 集合是否有交集：
+在派发每批任务之前，将当前批次所有任务的 `Files` 按路径前缀分为三类进行冲突检测：
+
+**文件类型分类规则**：
+
+| 文件类型 | 路径前缀 | 编写者 | 说明 |
+|---------|---------|--------|------|
+| `implementation` | 不以 `tests/` 开头 | coding agent | 实现代码、配置文件、文档等 |
+| `unit_test` | `tests/unit/` 或 `tests/models/` | coding agent（TDD） | 白盒单元测试 |
+| `other_test` | `tests/integration/` 或 `tests/e2e/` | test-writer | 黑盒集成/E2E 测试 |
+
+**冲突判定逻辑**：
+
+| 场景 | 判定 |
+|------|------|
+| 同类型文件重叠（均为 `implementation`、`unit_test` 或 `other_test`） | **冲突** |
+| `unit_test` 与 `other_test` 重叠 | **不冲突**（目录隔离保证互不干扰） |
+| `implementation` 与任何测试文件重叠 | **不冲突**（实现和测试天然分离） |
 
 ```bash
-# 伪代码：检测当前批次任务的文件冲突
-# 读取当前批次所有任务的 files 数组
-# 如果有任意两个任务的 files 有交集 → 标记冲突任务对，暂停并报告用户
+# 伪代码：基于文件类型的三类冲突检测算法
+# 1. 读取当前批次所有任务的 files 数组
+# 2. 对每个文件按路径前缀分类：implementation / unit_test / other_test
+# 3. 在同类型文件集合内检查是否有交集
+# 4. 如果同类型 files 有交集 → 标记冲突任务对，暂停并报告用户
+# 5. 跨类型重叠不标记为冲突
 ```
 
 #### Step 7: 按批次并发派发 Coding Agent
@@ -340,10 +352,114 @@ for (const task of currentBatchTasks) {
     default: agentType = "specline-backend-dev";
   }
 
-  Task({
-    subagent_type: agentType,
-    description: `实现任务 ${task.id}: ${task.title} [${task.type}]`,
-    prompt: `
+  // 根据 Testable 和 Type 构造 Prompt
+  let prompt;
+  if (task.testable === true) {
+    // === TDD prompt（Testable: true） ===
+    prompt = `
+你收到一个编码任务（Type: ${task.type}, Testable: true），请按 TDD（测试驱动开发）方式实现本任务范围内的代码。
+
+## 上下文文件（只读参考）
+- Spec: specline/changes/${changeName}/specs/${capability}/spec.md
+- Design: specline/changes/${changeName}/design.md
+- Tasks: specline/changes/${changeName}/tasks.md
+
+## 当前任务（只实现这个）
+任务 ID: ${task.id}
+覆盖需求: ${task.covers}
+预期文件: ${task.files}
+
+从 tasks.md 中提取的任务 ${task.id} 的完整描述：
+---
+${task.content}
+---
+
+## TDD 约束（RED-GREEN-REFACTOR）
+
+你必须按以下 TDD 循环编写代码：
+
+### RED 阶段
+1. 分析 Spec 中本任务覆盖的 Scenario，提取需要测试的逻辑单元
+2. 在 tests/unit/<module>/test_<feature>.{ext} 下编写测试文件
+3. 每个 Scenario 至少 1 个测试函数/方法
+4. 覆盖：Happy Path + 边界条件（空值、极值、边界值）+ 异常路径（错误输入、异常状态）
+5. 运行测试，确认全部 FAIL（RED）
+
+### GREEN 阶段
+6. 编写最小实现代码，只使当前测试通过
+7. 不编写测试未覆盖的逻辑
+8. 运行测试，确认全部 PASS（GREEN）
+
+### REFACTOR 阶段
+9. 重构实现代码改善结构（提取方法、消除重复、优化命名）
+10. 运行测试，确保持续 PASS
+11. 如果需要，补充缺失的边界条件测试
+
+## 关键约束
+1. 只修改本任务 Files 范围内的文件
+2. 不修改其他任务负责的文件
+3. 与已完成任务的接口约定必须遵守（参考已生成的接口/类型定义文件）
+4. 确认过 design.md 中的技术决策后再动手
+5. 测试文件只能写入 tests/unit/ 或 tests/models/ 目录
+6. 不得修改 tests/integration/ 或 tests/e2e/ 目录下的文件（属于 test-writer）
+7. **完成后必须将 tasks.md 中本任务的 \`[ ]\` 改为 \`[x]\`**（方便断点续跑识别进度）
+
+## 产出报告
+完成后在 specline/changes/${changeName}/.tmp/task-${task.id}-result.json 写入：
+{
+  "task_id": "${task.id}",
+  "type": "${task.type}",
+  "testable": true,
+  "covers": "${task.covers}",
+  "status": "completed",
+  "files_changed": [...],
+  "test_files": ["tests/unit/...", ...],
+  "tests_passed": true,
+  "summary": "..."
+}
+`;
+  } else if (["frontend", "backend", "infra", "db"].includes(task.type)) {
+    // === 标准编码 prompt（Testable: false，有代码逻辑） ===
+    prompt = `
+你收到一个编码任务（Type: ${task.type}, Testable: false），请只实现本任务范围内的代码。
+
+## 上下文文件（只读参考）
+- Spec: specline/changes/${changeName}/specs/${capability}/spec.md
+- Design: specline/changes/${changeName}/design.md
+- Tasks: specline/changes/${changeName}/tasks.md
+
+## 当前任务（只实现这个）
+任务 ID: ${task.id}
+覆盖需求: ${task.covers}
+预期文件: ${task.files}
+
+从 tasks.md 中提取的任务 ${task.id} 的完整描述：
+---
+${task.content}
+---
+
+## 约束
+1. 只修改本任务 Files 范围内的文件
+2. 不修改其他任务负责的文件
+3. 与已完成任务的接口约定必须遵守（参考已生成的接口/类型定义文件）
+4. 确认过 design.md 中的技术决策后再动手
+5. **完成后必须将 tasks.md 中本任务的 \`[ ]\` 改为 \`[x]\`**（方便断点续跑识别进度）
+
+## 产出报告
+完成后在 specline/changes/${changeName}/.tmp/task-${task.id}-result.json 写入：
+{
+  "task_id": "${task.id}",
+  "type": "${task.type}",
+  "testable": false,
+  "covers": "${task.covers}",
+  "status": "completed",
+  "files_changed": [...],
+  "summary": "..."
+}
+`;
+  } else {
+    // === 配置/文档 prompt（Type: config/docs） ===
+    prompt = `
 你收到一个编码任务（Type: ${task.type}），请只实现本任务范围内的代码。
 
 ## 上下文文件（只读参考）
@@ -378,15 +494,25 @@ ${task.content}
   "files_changed": [...],
   "summary": "..."
 }
-`
+`;
+  }
+
+  Task({
+    subagent_type: agentType,
+    description: `实现任务 ${task.id}: ${task.title} [${task.type}]${task.testable ? ' (TDD)' : ''}`,
+    prompt: prompt
   })
 }
 ```
 
 **7b. 等待当前批次所有 Agent 完成后**：
 1. 验证每个 Agent 的产出报告（`specline/changes/<name>/.tmp/task-<id>-result.json`）
-2. 更新状态文件中对应 task 的 `status` 和 `completed_at`
-3. **验证 tasks.md 中对应任务的 checkbox 已从 `[ ]` 变为 `[x]`**（如果未标记，自动补标）
+2. **对 Testable=true 的任务**，验证 `task-<id>-result.json` 中是否包含 `test_files` 字段且其值非空。如果 Testable=true 但 agent 未产出测试文件，标记为 warning 并记录到事件日志：
+   ```
+   {"ts":"...","event":"tdd_warning","task":"<id>","reason":"Testable=true but no test_files produced"}
+   ```
+3. 更新状态文件中对应 task 的 `status` 和 `completed_at`
+4. **验证 tasks.md 中对应任务的 checkbox 已从 `[ ]` 变为 `[x]`**（如果未标记，自动补标）
 
 ```bash
 # 更新状态文件
@@ -411,6 +537,10 @@ sed -i '' "s/^## ${task_id}\. \[ \]/## ${task_id}. [x]/" specline/changes/<name>
 .cursor/hooks/specline-pipeline-gate.sh build --change "<name>"
 ```
 
+Build Gate 校验内容：
+- 编译/语法检查（原有逻辑）
+- **单元测试文件存在性检查**（新增）：对 Testable=true 的任务，检查其 `tests/unit/` 和 `tests/models/` 下的单元测试文件是否存在且语法正确。如果 Testable=true 的任务未产出对应测试文件，Build Gate 失败
+
 exit code 0 = 通过，进入 Phase 3。失败处理见 [Layer 3: Build Gate 失败处理](#build-gate-失败处理)。
 
 ### Phase 3: CODE REVIEW
@@ -423,11 +553,21 @@ exit code 0 = 通过，进入 Phase 3。失败处理见 [Layer 3: Build Gate 失
 
 审查前端/后端代码变更。审查时利用 tasks.md 的 `Covers` 追溯链：每个 finding 应标注涉及的文件和对应的 Requirement/Scenario。
 
+对 Testable=true 的任务，额外审查其 `tests/unit/` 和 `tests/models/` 下的单元测试文件质量，包括：
+- 边界条件覆盖（空值、极值、边界值）
+- 异常路径覆盖（错误输入、异常状态）
+- 测试断言的有效性
+
+code-review.json 中 unit test 相关的 finding 标注 `type` 为 `"unit_test_quality"`，示例：
+```json
+{ "severity": "warning", "type": "unit_test_quality", "file": "tests/unit/auth/test_login.py", "covers": "Requirement: Coding Agent Prompt 条件化 TDD 注入", "message": "缺少空密码输入边界条件测试" }
+```
+
 **9b. specline-config-reviewer**（有 config/docs 类型任务时）：
 
 审查 config/docs 变更——shell 脚本安全性、配置文件语法和一致性、Markdown 文档结构完整性。
 
-> 两种审查 Agent 可并发启动。产出均为 `specline/changes/<name>/.tmp/code-review.json`（`{ "findings": [{ "severity": "error"|"warning", "file": "...", "covers": "Requirement: xxx", "message": "..." }] }`）。
+> 两种审查 Agent 可并发启动。产出均为 `specline/changes/<name>/.tmp/code-review.json`（`{ "findings": [{ "severity": "error"|"warning", "type": "unit_test_quality"|"style"|"security"|"logic", "file": "...", "covers": "Requirement: xxx", "message": "..." }] }`）。
 
 #### Step 10: Lint Gate
 
@@ -568,13 +708,46 @@ jq '.phases.coding.gates.build_gate.passed = null' "$STATE_FILE" > tmp && mv tmp
 
 ### 测试失败处理
 
-⚠️ 任何测试失败 → specline-test-runner 分析原因：
-- **测试代码问题** → specline-test-writer 自修（最多 2 次）
-- **实现代码问题** → 利用 `Covers` 追溯链定位到具体任务，只回对应 coding agent 修复 → **使用影响范围算法精确重置受影响任务的 Gate**
-- **`spec_ambiguity`**（Spec 模糊）→ **不自动循环修复**，暂停流水线并展示模糊点给用户，等待用户澄清 Spec 后继续
+⚠️ 测试失败根据失败文件所在的目录区分处理路径：
+
+#### 单元测试失败处理
+
+失败文件在 `tests/unit/` 或 `tests/models/` 目录下：
+
+- 利用 `Covers` 追溯链定位到具体 coding 任务
+- 回对应 coding agent 修复实现代码或测试代码（最多 2 次循环）
+- `spec_ambiguity`（Spec 模糊）→ **不自动循环修复**，暂停流水线并展示模糊点给用户
+
+Gate 重置（仅重置 test_unit_gate）：
+
+```bash
+jq '.phases.test.sub_phases.unit.gates.test_unit_gate.passed = null' "$STATE_FILE" > tmp && mv tmp "$STATE_FILE"
+```
+
+#### 集成/E2E 测试失败处理
+
+失败文件在 `tests/integration/` 或 `tests/e2e/` 目录下：
+
+- specline-test-runner 分析原因：
+  - **测试代码问题** → specline-test-writer 自修（最多 2 次）
+  - **实现代码问题** → 利用 `Covers` 追溯链定位到具体任务，回对应 coding agent 修复 → **使用影响范围算法精确重置受影响任务的 Gate**
+  - **`spec_ambiguity`**（Spec 模糊）→ **不自动循环修复**，暂停流水线并展示模糊点给用户
 - 循环最多 2 次
 
-代码修复后 Gate 重置：
+Gate 重置：
+
+```bash
+jq '
+  .phases.test.sub_phases.integration.gates.test_integration_gate.passed = null |
+  .phases.test.sub_phases.e2e.gates.test_e2e_gate.passed = null
+' "$STATE_FILE" > tmp && mv tmp "$STATE_FILE"
+```
+
+#### 优先级规则
+
+当单元测试和集成/E2E 测试同时失败时：**优先修复单元测试**（先执行 coding agent 修复循环），单元测试通过后再处理集成/E2E 测试失败。
+
+代码修复后 Gate 全部重置（所有测试类型）：
 
 ```bash
 jq '

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

@@ -65,6 +65,7 @@ specline-pipeline-gate.sh new --change "<name>"
   - **Type**: frontend | backend | infra | db | config | docs
   - **Depends**: (none) | 依赖的任务编号
   - **Covers**: Requirement: xxx, Scenario: xxx
+  - **Testable**: true | false
   - **Files**: 任务涉及的文件路径列表
 
   任务拆分原则：
@@ -100,8 +101,9 @@ specline-pipeline-gate.sh artifacts --change "<name>" --json
 ## 1. 数据模型 [x]
 - Type: backend
 - Depends: (none)
-- Files: server/models/user.py
 - Covers: Requirement: 用户数据模型
+- Testable: true
+- Files: server/models/user.py
 ```
 
 > 任务粒度适中，Files 范围明确，Covers 可追溯到具体 Requirement。
@@ -126,6 +128,7 @@ specline-pipeline-gate.sh artifacts --change "<name>" --json
 | 独立可测 | 每个任务可独立验证完成状态 |
 | 文件不交叠 | 第 1 批次（Depends: none）任务的文件集合无交集 |
 | 可追溯 | 每个任务必须通过 Covers 追溯到具体 Requirement/Scenario |
+| Testable 标注 | 无依赖 + 有可测代码 + 非 config/docs → Testable: true |
 
 ---
 

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

@@ -0,0 +1,239 @@
+---
+name: specline-quickfix
+description: 轻量修改 Skill —— 小改动用 quickfix，大功能用 pipeline
+---
+
+# /specline-quickfix 轻量修改 Skill
+
+---
+
+## Layer 1: 速览与定位
+
+**一句话定位**：小改动用 quickfix，大功能用 pipeline。
+
+**入口**：`/specline-quickfix <描述>`
+
+**你做：**
+- 读取相关代码理解上下文
+- 直接 Write/StrReplace 编辑文件（不使用子 Agent）
+- ReadLints 自动校验 + 修复（最多 2 次循环）
+- 运行项目已有单元测试（失败修复最多 2 次循环）
+- 生成轻量归档（summary.md + files-changed.json）
+
+**你不做：**
+- 创建 proposal.md、design.md、tasks.md、specs/ 等规划文档
+- 启动任何 specline-* 子 Agent
+- 创建 `.pipeline-state.json` 或 `.pipeline-sessions.json`
+- 写新测试、跑集成/E2E 测试
+
+### 流程概览
+
+```
+    UNDERSTAND ──→ IMPLEMENT ──→ REVIEW ──→ TEST ──→ ARCHIVE
+     (读代码)       (直编辑)    (Lint+自审)  (现有单测)  (轻量归档)
+```
+
+### Hook 透明
+
+Quickfix 不绑定 Pipeline session，所有 Hook（sessionStart、preToolUse、postToolUse、subagentStart、beforeShellExecution）自动透明放行，不产生任何拦截或提醒。
+
+---
+
+## Layer 2: Happy Path
+
+### Phase 1: UNDERSTAND
+
+**目标**：理解变更上下文，明确修改范围。
+
+**Steps**：
+
+1. 解析用户描述，提取关键词（文件名、函数名、错误信息等）
+2. 使用 Read 工具读取相关源文件，理解当前逻辑
+3. 确认变更范围：
+   - 1-3 个文件 ✓
+   - 单一关注点 ✓
+   - 不涉及架构变更 ✓
+   - 不需要新测试 ✓
+4. **意图模糊时**：使用 AskUserQuestion 向用户确认变更范围和目标，不要猜测
+
+**准入条件**：变更范围已验证在 quickfix 适用范围内（参见 Layer 3 边界判断）
+
+---
+
+### Phase 2: IMPLEMENT
+
+**目标**：直接编辑源文件，完成修改。
+
+**Steps**：
+
+1. 使用 Write / StrReplace 工具直接编辑文件
+2. **不使用子 Agent**，不调用 Task 工具
+3. 编辑完成后，运行 ReadLints 检查新增的 lint 错误
+
+**约束**：
+- 只修改 UNDERSTAND 阶段确认的文件
+- 如果发现需要修改第 4 个文件 → 暂停并建议转 `/specline-pipeline`
+- 保持现有代码风格和命名约定
+
+---
+
+### Phase 3: REVIEW
+
+**目标**：通过 Lint 检查和 Agent 自审确保代码质量。
+
+**Steps**：
+
+1. 运行 ReadLints 收集所有 lint 问题
+2. **如有 lint 错误**：自动修复 → 再次 ReadLints → 最多循环 2 次
+   - 第 1 次修复后仍有错误 → 分析原因，再次修复
+   - 第 2 次修复后仍有错误 → 报告用户，附错误列表和修复尝试记录，暂停
+3. **Agent 自审**：
+   - 变更逻辑是否正确？
+   - 是否处理了边界条件？
+   - 是否引入了新问题（如未使用的导入、副作用）？
+   - 是否破坏现有功能？
+4. 自审通过 → 进入 TEST 阶段
+
+---
+
+### Phase 4: TEST
+
+**目标**：运行项目已有单元测试，确保不引入回归。
+
+**Steps**：
+
+1. **自动检测测试框架**：
+   - 检查 `package.json` scripts → Jest / Mocha / Vitest
+   - 检查 `pytest` / `go test` / `cargo test` 配置
+2. **有测试配置**：运行现有单元测试
+   - 通过 → 进入 ARCHIVE 阶段
+   - 失败 → 分析失败原因，修复代码 → 重新运行 → 最多循环 2 次
+   - 第 2 次修复后仍失败 → 报告用户（附失败详情和修复尝试记录），暂停
+3. **无测试配置**：跳过 TEST 阶段，进入 ARCHIVE 阶段（在 summary.md 中标注）
+
+**不运行**：集成测试、E2E 测试、新编写的测试。
+
+---
+
+### Phase 5: ARCHIVE
+
+**目标**：生成轻量归档，提供变更可追溯性。
+
+**Steps**：
+
+1. 在 `specline/changes/archive/` 下创建归档目录：
+   ```
+   specline/changes/archive/YYYY-MM-DD-<description>/
+       ├── summary.md
+       └── files-changed.json
+   ```
+2. **summary.md** 内容：
+   ```markdown
+   # <变更标题>
+   
+   ## What
+   <一句话描述做了什么>
+   
+   ## Why
+   <为什么要做这个修改>
+   
+   ## Files Changed
+   - path/to/file1 — <修改简述>
+   - path/to/file2 — <修改简述>
+   
+   ## Test Result
+   - 通过 / 跳过（无现有单元测试）/ 失败（附详情）
+   ```
+3. **files-changed.json** 内容：
+   ```json
+   {
+     "files": ["path/to/file1", "path/to/file2"],
+     "change_count": 2,
+     "description": "<变更描述>"
+   }
+   ```
+4. 展示变更摘要，**询问用户**：是否需要 git commit？
+
+**无人确认点**：整个 quickfix 流程不暂停等待人工确认（lint + test 是自动质量底线）。
+
+---
+
+## Layer 3: 异常与边界
+
+### Quickfix vs Pipeline 边界判断
+
+使用以下规则判断变更是否适合 quickfix：
+
+| 维度 | Quickfix (`/specline-quickfix`) | Pipeline (`/specline-pipeline`) |
+|------|-------------------------------|-------------------------------|
+| 文件改动数 | 1-3 个 | 4+ 个 |
+| 关注点 | 单一关注点 | 多关注点/跨模块 |
+| 架构变更 | 无新架构/新组件 | 需要新组件/新 API |
+| 测试 | 不需要新测试 | 需要写新测试 |
+| 典型场景 | 修 bug、改配置、文档微调 | 新增功能、重构 |
+| 产出 | summary.md + files-changed.json | proposal/design/tasks/specs + 全部测试 |
+| 人工确认 | 0 个 | 3 个 |
+| 耗时 | 1-3 分钟 | 10-30 分钟 |
+
+**边界处理规则**：
+
+| 异常情况 | 处理方式 |
+|----------|----------|
+| 变更范围 > 3 个文件 | 暂停，建议转 `/specline-pipeline` |
+| 需要写新测试 | 暂停，建议转 `/specline-pipeline` |
+| 涉及架构变更/新 API | 暂停，建议转 `/specline-pipeline` |
+| Lint 修复 2 次后仍有错误 | 报告用户（附错误列表和修复记录），暂停 |
+| 测试失败 2 次后仍失败 | 报告用户（附失败详情和修复记录），暂停 |
+| 实现过程中发现需要额外文件 | 如果总数仍 ≤ 3 → 继续；如果 > 3 → 暂停并建议转 pipeline |
+| 项目无测试配置 | 跳过 TEST 阶段，在 summary.md 中标注 |
+
+### 不适合 Quickfix 的典型场景
+
+- 新增功能模块（需要 spec/design 规划）
+- 跨 3+ 模块的接口变更
+- 数据库 schema 变更
+- 需要新增测试覆盖的复杂修复
+- 需要多人/多步骤协调的改动
+
+**使用建议**：如果不确定，优先用 quickfix。如果需要更严格的流程保证，用 pipeline。
+
+---
+
+## Layer 4: 附录
+
+### 与 Pipeline 的关系
+
+```
+specline-pipeline (完整流程)           specline-quickfix (轻量流程)
+    SPEC                                  UNDERSTAND
+     ↓                                       ↓
+    CODING (子 Agent 并发)                   IMPLEMENT (单 Agent 直编)
+     ↓                                       ↓
+    CODE REVIEW (review Agent)              REVIEW (ReadLints + 自审)
+     ↓                                       ↓
+    TEST (unit → integration → e2e)         TEST (现有单测 only)
+     ↓                                       ↓
+    ARCHIVE (Delta sync)                    ARCHIVE (summary + files-changed)
+```
+
+两者完全独立，通过边界判断规则选择。不共享状态文件，不互相依赖。
+
+### 归档目录结构兼容性
+
+Quickfix 归档目录结构与 Pipeline 归档保持一致：
+
+```
+specline/changes/archive/
+├── YYYY-MM-DD-<pipeline-change>/       ← Pipeline 归档
+│   ├── proposal.md
+│   ├── design.md
+│   ├── tasks.md
+│   ├── specs/
+│   └── ...
+│
+└── YYYY-MM-DD-<quickfix-description>/   ← Quickfix 归档
+    ├── summary.md
+    └── files-changed.json
+```
+
+两种归档方式共存于同一目录，通过内容区分（Pipeline 归档有 proposal.md 等完整文档，Quickfix 归档只有 summary.md + files-changed.json）。