@boyingliu01/xp-gate 0.8.19 → 0.8.21

package/skills/sprint-flow/references/phase-3-review.md

@@ -34,37 +34,22 @@ Web 前端项目额外增加：系统化 QA、视觉审计、性能基线。
 
 ### Step 1: 调用 delphi-review --mode code-walkthrough
 
-delphi code-walkthrough 在 subagent 中自动执行多轮调度（#218 自动多轮，无需人工中断）：
-
-```bash
-task(
-  category="deep",
-  load_skills=["delphi-review"],
-  run_in_background=false,
-  prompt="--mode code-walkthrough (设计文档 + MVP 代码)"
-)
+```
+skill(name="delphi-review", user_message="--mode code-walkthrough")
 ```
 
-delphi code-walkthrough 内部自动执行：
+delphi code-walkthrough 执行：
 - 2-3 位国内模型专家匿名独立评审（DeepSeek-v4-pro + Kimi-K2.6 + Qwen3.6-Plus）
 - Round 1: 匿名独立评审（防止 anchoring bias）
-- Round 2: 自动交换意见，响应关切
-- Round 3: 自动最终立场（如需）
-- **≥90% 共识 + APPROVED 才通过**
-
-**自动 Round 调度（#218）**:
-- 每轮结束后自动检查共识，自动展开下一轮
-- subagent 内部循环，无需每轮暂停等待 orchestrator
-- 只有最终裁决需要 orchestrator 处理
-
-**如果最终 REQUEST_CHANGES（subagent 尝试自动修复）**:
-- subagent 尝试自动修复常见问题（措辞不清晰、缺少用例覆盖等）
-- 修复成功后自动回到 Round 2 重新评审
-- 如果仍然 REQUEST_CHANGES → subagent 输出详细失败报告
-- ⚠️ Orchestrator 暂停等待用户修复 Critical Issues + 处理 Major Concerns
-- 用户修复后通过 task_id 延续 subagent 重新评审
-
-**如果最终 APPROVED**:
+- Round 2: 交换意见，响应关切
+- Round 3: 最终立场（如需）
+- ≥90% 共识 + APPROVED 才通过
+
+**如果 REQUEST_CHANGES**:
+- ⚠️ 暂停等待用户修复 Critical Issues + 处理 Major Concerns
+- 修复后回到 Round 2 重新评审
+
+**如果 APPROVED**:
 - 写入 `.code-walkthrough-result.json`（1 小时有效期）
 - 进入 Step 2
 
@@ -209,15 +194,13 @@ browse 执行：
 
 | 暂停点 | 触发条件 | 用户操作 |
 |--------|---------|---------|
-| delphi code-walkthrough REQUEST_CHANGES（不可自动修复）| subagent 尝试自动修复后仍 REQUEST_CHANGES | 用户修复 → 重新 dispatch subagent → APPROVED → 继续 |
+| delphi code-walkthrough REQUEST_CHANGES | Critical Issues 未修复 | 用户修复 → 重新评审 → APPROVED → 继续 |
 | test-alignment 失败 | 自动回退 Phase 2（不暂停） | 自动迭代 |
 | qa 发现问题 (web) | 自动回退修复（不暂停） | 自动迭代 |
 | design-review 发现问题 (web) | 自动回退修复（不暂停） | 自动迭代 |
 | api-test 失败 (backend) | 自动回退 Phase 2（不暂停） | 自动迭代 |
 | browse 发现问题 | 自动回退 Phase 2（不暂停） | 自动迭代 |
 
-> **#218 规则**: Delphi code-walkthrough 的 Round 1→2→3 自动调度在 subagent 内部完成，不暂停。只有 subagent 尝试自动修复后仍 REQUEST_CHANGES 时才需要用户介入。
-
 ---
 
 ## 输出

package/skills/sprint-flow/references/phase-6-ship.md

@@ -1,186 +1,9 @@
 # Phase 6: SHIP + DEPLOY（发布）
 
-## 目标
+**完整指令**: @see SKILL.md `## Phase 6: SHIP` section.
 
-结构化分支完成决策、创建 PR、合并部署、监控。生成 Sprint Summary。
+**摘要**: 结构化分支完成决策, 创建 PR, 合并部署, 监控. 生成 Sprint Summary.
 
----
+**关键链**: PHASE5-GATE → verification → finishing-a-development-branch(4选项) → ship → land-and-deploy → canary → Sprint Summary
 
-## 调用 Skills
-
-- **`finishing-a-development-branch`** _(新增)_ — 结构化完成流：4 选项决策（merge/PR/discard/keep）
-- `ship` (gstack) — 创建 PR
-- `land-and-deploy` (gstack) — 合并部署
-- `canary` (gstack) — 监控告警
-
----
-
-## 执行步骤
-
-### Step 0: ⚠️ PHASE 5 硬门禁验证（不可跳过）
-
-**必须首先验证 Phase 5 已完成**:
-
-```bash
-if [ ! -f ".sprint-state/phase-outputs/feedback-log.md" ]; then
-  echo "[BLOCKED] Phase 5 FEEDBACK not completed. feedback-log.md not found."
-  echo "Phase 5 must execute: learn + retro → generate feedback-log.md"
-  echo "Return to Phase 5 before proceeding to SHIP."
-  exit 1
-fi
-echo "✅ Phase 5 FEEDBACK verified — feedback-log.md exists"
-```
-
-**失败**: ⚠️ BLOCK → 返回 Phase 5 执行 learn + retro
-**通过**: 进入 Step 1
-
-### Step 1: 最终验证
-
-```
-skill(name="verification-before-completion", user_message="最终验证: [MVP v1] 完整性")
-```
-
-**验证内容**：
-- 测试全部通过
-- Lint 无错误
-- 覆盖率 ≥ 80%
-
-**失败**: ⚠️ BLOCK → 回退 Phase 2 修复
-
-**通过**: 进入 Step 2
-
-### Step 2: 结构化完成决策 — 调用 finishing-a-development-branch（新增 — ISSUE31）
-
-```
-skill(name="finishing-a-development-branch")
-```
-
-finishing-a-development-branch 执行 4 选项决策：
-
-| 选项 | 行为 | 适用场景 |
-|------|------|---------|
-| **merge** | 直接合并到主分支 | 小功能、确信变更正确 |
-| **PR** | 创建 PR 等待 review | 标准流程、需要团队审核 |
-| **discard** | 删除分支、丢弃变更 | 实验失败、不再需要 |
-| **keep** | 保留分支待后续处理 | 半成品、暂时搁置 |
-
-**决策逻辑**:
-```
-IF 测试全部通过 + 用户确信 → merge → land-and-deploy (Step 4)
-IF 测试全部通过 + 需要 review → PR → ship (Step 3a) → land-and-deploy (Step 4)
-IF 实验失败 → discard → 清理 worktree → 结束 Sprint
-IF 半成品 → keep → 保留分支 → 结束 Sprint
-```
-
-> **#218**: `finishing-a-development-branch` 的 4 选项决策已包含用户确认（Step 2），不再需要独立的 Step 3 重复确认。用户选择后直接路由到对应步骤。
-
-**worktree 清理**: finishing-a-development-branch 自动清理不再需要的 worktree。
-
-**分支完成选项路由**:
-| 用户选择 | 路由 |
-|---------|------|
-| **merge** | → Step 4 (land-and-deploy) |
-| **PR** | → Step 3a (ship) → PR URL → Step 4 (land-and-deploy) |
-| **discard** | → Step 5 (cleanup + summary) |
-| **keep** | → Step 5 (cleanup + summary) |
-
-### Step 3a: 调用 ship skill（PR 路径）
-
-```
-skill(name="ship", user_message="[MVP v1 代码]")
-```
-
-ship 执行：
-- 检测 base branch
-- run tests
-- review diff
-- bump VERSION
-- update CHANGELOG
-- commit, push, create PR
-
-**输出**: PR URL
-
-> **注意**: PR 创建后不暂停等待用户确认合并。用户已通过 finishing-a-development-branch 选择了 PR 路径（Step 2），ship 自动完成后直接进入 Step 4 land-and-deploy 继续执行。如果用户需要暂停审查 PR，应在 Sprint 开始时指定 `--stop-at ship`。
-
-### Step 4: 调用 land-and-deploy（用户确认后）
-
-```
-skill(name="land-and-deploy", user_message="--pr [PR URL]")
-```
-
-执行：
-- merge PR（或直接合并当前分支）
-- wait for CI
-- verify production health
-
-**如果失败**:
-- ⚠️ 暂停等待用户处理
-
-**如果成功**:
-- 自动进入 Step 5
-
-### Step 5: 调用 canary skill
-
-```
-skill(name="canary", user_message="--url [production URL]")
-```
-
-执行：
-- post-deploy monitoring
-- console errors detection
-- performance regression check
-
-**如果发现异常**:
-- 回退或修复
-
-**如果正常**:
-- 进入 Step 6
-
-### Step 6: 生成 Sprint Summary
-
-使用模板：`@templates/sprint-summary-template.md`
-
-包含：
-- Sprint ID
-- 执行阶段统计
-- 分支完成决策结果（merge/PR/discard/keep）
-- emergent 发现统计
-- Sprint 2 是否需要
-
-### Step 7: 保存 Sprint Summary
-
-保存到 `<project-root>/.sprint-state/phase-outputs/sprint-summary.md`
-
----
-
-## 暂停点
-
-| 暂停点 | 触发条件 | 用户操作 |
-|--------|---------|---------|
-| finishing-a-development-branch | 4 选项决策 | 用户选择 merge/PR/discard/keep |
-| land-and-deploy 失败 | CI 或部署失败 | 用户处理问题 |
-
-> **#218**: PR 创建后不再暂停等待确认 — 用户已通过 finishing-a-development-branch 选择了 PR 路径，ship 自动完成后直接进入 land-and-deploy。如果用户需要暂停审查 PR，应在 Sprint 开始时指定 `--stop-at ship`。
-
----
-
-## Sprint 2 提示
-
-如果 Sprint Summary 显示有 emergent issues：
-```
-Sprint 完成！发现 N 个 emergent issues。
-
-是否开始 Sprint 2？
-- "开始 Sprint 2" → 使用 sprint2-pain.md 重新进入 Phase 0
-- "结束" → 记录未解决的问题，结束流程
-
-Critical issues 将自动进入 Sprint 2。
-Major/Minor issues 需您确认是否纳入。
-```
-
----
-
-## 输出
-
-- Sprint Summary (`sprint-summary.md`)
-- Sprint 完成（或 Sprint 2 开始）
+**输出**: PR URL, Sprint Summary

package/skills/sprint-flow/references/phase-7-land.md

@@ -1,140 +1,9 @@
 # Phase 7: LAND（合并 + 部署）
 
-## 目标
+**完整指令**: @see SKILL.md `## Phase 7: LAND` section.
 
-自动合并 PR、等待 CI、执行部署、运行 Canary Health Check、失败时自动回滚。
+**摘要**: 自动合并 PR, 等待 CI, 执行部署, Canary Health Check, 失败自动回滚.
 
----
+**关键链**: merge PR → wait CI(10min) → wait Deploy(10min) → Canary Health Check(5min) → auto-rollback on failure
 
-## 输入
-
-- Phase 6 SHIP 输出的 PR URL
-- 或 `--phase ship-only` 时手动提供 PR 编号
-
----
-
-## 调用 Skills
-
-- `land-and-deploy` (gstack) — 合并部署
-- `canary` (gstack) — 监控告警
-
----
-
-## 执行步骤
-
-### Step 1: 合并 PR
-
-```bash
-gh pr merge <PR_NUMBER> --squash
-```
-
-**失败**: 输出 `[ERROR] PR merge failed` → 询问用户是否重试或手动处理
-
-**成功**: 进入 Step 2
-
-### Step 2: 等待 CI 完成
-
-```bash
-# Poll CI checks every 10s, timeout after 10min
-gh pr checks <PR_NUMBER> --watch --interval 10
-```
-
-**超时 (10min)**: 输出 `[WARN] CI checks timed out after 10min` → 询问用户是否继续
-
-**CI 失败**: 输出 `[ERROR] CI checks failed, aborting deployment` → BLOCK
-
-**CI 成功**: 进入 Step 3
-
-### Step 3: 等待 Deploy 完成
-
-**条件**: 项目已配置部署平台（Fly.io/Vercel/Render/GitHub Actions 等）
-
-```bash
-# Poll deploy status every 10s, timeout after 10min
-gh pr checks <PR_NUMBER> --watch --interval 10
-```
-
-**无部署配置**: 跳过 Step 3-4，直接进入 Phase 8
-
-**部署成功**: 进入 Step 4
-
-**部署失败**: 进入 Step 5（自动回滚）
-
-### Step 4: Canary Health Check
-
-**健康检查端点**: 
-- 默认：项目根路径 `/`
-- 自定义：`$HEALTH_CHECK_URL` 环境变量或 `.sprint-load-test.yaml` 中的 `health_endpoint`
-
-**SLA 指标**:
-| 指标 | 阈值 | 说明 |
-|------|------|------|
-| HTTP 响应状态 | 200 | 服务正常运行 |
-| 错误率 | <1% | 5 分钟窗口内 5xx 错误占比 |
-| p99 响应时间 | <2s | 99 分位响应时间 |
-| 超时总时长 | 5min | health check 最长等待时间 |
-| Polling 间隔 | 10s | 健康检查轮询频率 |
-
-**实现**:
-```bash
-START_TIME=$(date +%s)
-while [ $(( $(date +%s) - START_TIME )) -lt 300 ]; do
-  RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" "$HEALTH_CHECK_URL" 2>/dev/null || echo "000")
-  if [ "$RESPONSE" = "200" ]; then
-    echo "✅ Canary health check passed: HTTP 200"
-    break
-  fi
-  echo "[WARN] Canary health check returned HTTP $RESPONSE, retrying in 10s..."
-  sleep 10
-done
-
-if [ "$RESPONSE" != "200" ]; then
-  echo "[ERROR] Canary health check failed after 5min timeout"
-  # Auto-rollback
-  LAST_MERGE_COMMIT=$(git log -1 --oneline --format="%H" 2>/dev/null)
-  git revert "$LAST_MERGE_COMMIT" --no-edit
-  echo "[ROLLBACK] Auto-reverted merge commit: $LAST_MERGE_COMMIT"
-  exit 1
-fi
-```
-
-**通过**: 进入 Phase 8 CLEANUP
-
-**失败**: 自动回滚 → 输出 `[ERROR] Deploy failed, auto-rolled back merge` → Phase 8 仍执行（清理 worktree）
-
-### Step 5: 自动回滚（部署失败时）
-
-```bash
-# Revert the last merge commit
-LAST_MERGE_COMMIT=$(git log -1 --oneline --format="%H" 2>/dev/null)
-git revert "$LAST_MERGE_COMMIT" --no-edit
-echo "[ERROR] Deploy failed, auto-rolled back merge commit: $LAST_MERGE_COMMIT"
-```
-
----
-
-## 输出
-
-- 部署状态: success | failure | skipped
-- Canary 报告: SLA 指标是否达标
-- 如果自动回滚：reverted commit hash
-
----
-
-## 暂停点
-
-- **CI 超时**: 用户确认是否继续等待或跳过
-- **部署失败**: 用户确认自动回滚或手动处理
-- **Canary 失败**: 用户确认回滚或保留状态调查
-
----
-
-## 错误处理
-
-| 错误场景 | 处理 |
-|---------|------|
-| PR 合并冲突 | 输出错误 → 询问用户是否 rebase 或手动解决 |
-| CI 超时 (10min) | 输出警告 → 询问是否继续或跳过部署 |
-| 部署失败 | 自动 `git revert` merge commit + 输出错误 |
-| Canary 失败 | 自动回滚 + 输出 `[ERROR] Canary health check failed` |
-| 无部署配置 | 跳过部署/canary，仅 merge + CI checks |
+**输出**: 部署状态 (success/failure/skipped), Canary 报告

package/skills/sprint-flow/references/phase-8-cleanup.md

@@ -1,192 +1,9 @@
 # Phase 8: CLEANUP（清理 + 总结）
 
-## 目标
+**完整指令**: @see SKILL.md `## Phase 8: CLEANUP` section.
 
-自动清理 worktree、更新 sprint-state.json、输出 Sprint Summary、处理 emergent issues。
+**摘要**: 自动清理 worktree, 更新 sprint-state.json, 输出 Sprint Summary, 处理 emergent issues.
 
----
+**关键链**: worktree detection → remove(retry×3) → residual check → sprint-state update → Sprint Summary → emergent issues(→Sprint 2?)
 
-## 输入
-
-- Phase 7 LAND 完成后的部署状态
-- 或 Phase 6 Option 1（本地 Merge）后的完成状态
-- `.sprint-state/sprint-state.json`（包含 worktree 路径信息）
-
----
-
-## 执行步骤
-
-### Step 1: 检测 worktree 是否存在
-
-```bash
-# Read worktree path from sprint-state.json
-WORKTREE_PATH=$(node -e "const fs=require('fs'); const state=JSON.parse(fs.readFileSync('.sprint-state/sprint-state.json','utf8')); console.log(state.isolation?.worktree_path || '')" 2>/dev/null)
-
-if [ -z "$WORKTREE_PATH" ]; then
-  echo "[CLEANUP] No worktree path found in sprint-state.json — skipping cleanup"
-  exit 0
-fi
-
-if [ ! -d "$WORKTREE_PATH" ]; then
-  echo "[CLEANUP] Worktree already removed: $WORKTREE_PATH"
-  HAS_WORKTREE=false
-else
-  HAS_WORKTREE=true
-fi
-```
-
-**跳过**: `--no-isolate` 路径（无 worktree 可清理）或 worktree 已不存在
-
-**存在**: 进入 Step 2
-
-### Step 2: 删除 worktree（带重试机制）
-
-```bash
-MAX_RETRIES=3
-RETRY_COUNT=0
-REMOVED=false
-
-while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
-  if git worktree remove "$WORKTREE_PATH" 2>/dev/null; then
-    REMOVED=true
-    echo "[CLEANUP] ✅ Worktree removed: $WORKTREE_PATH"
-    break
-  else
-    RETRY_COUNT=$((RETRY_COUNT + 1))
-    if [ $RETRY_COUNT -lt $MAX_RETRIES ]; then
-      echo "[WARN] Worktree remove failed, retry $RETRY_COUNT/$MAX_RETRIES in 1s..."
-      sleep 1
-    fi
-  fi
-done
-
-if [ "$REMOVED" = "false" ]; then
-  echo "[WARN] Failed to remove worktree after $MAX_RETRIES attempts."
-  echo "[WARN] Please manually run: git worktree remove $WORKTREE_PATH"
-fi
-```
-
-**成功**: 进入 Step 3
-
-**失败**: 输出警告 + 手动命令提示 → 进入 Step 3
-
-### Step 3: 检测残留目录
-
-```bash
-if [ -d "$WORKTREE_PATH" ]; then
-  echo "[WARN] ⚠️ Residual worktree directory detected: $WORKTREE_PATH"
-  echo "[WARN] Please manually remove it if needed"
-else
-  echo "[CLEANUP] ✅ No residual directory detected"
-fi
-```
-
-**残留**: 输出警告
-
-**干净**: 输出成功消息 → 进入 Step 4
-
-### Step 4: 更新 sprint-state.json
-
-```bash
-node -e "
-const fs = require('fs');
-const statePath = '.sprint-state/sprint-state.json';
-const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
-state.phase = 8;
-state.status = 'merged';
-if (!state.metrics) state.metrics = {};
-state.metrics.completed_at = new Date().toISOString();
-fs.writeFileSync(statePath, JSON.stringify(state, null, 2) + '\n');
-console.log('[CLEANUP] sprint-state.json updated → phase: 8, status: merged');
-"
-```
-
-### Step 5: 输出 Sprint Summary
-
-根据 `.sprint-state/phase-outputs/sprint-summary-template.md` 生成总结：
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  SPRINT SUMMARY
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Sprint ID: sprint-2026-05-28-01
-Status: merged
-Phase: 8 (CLEANUP complete)
-
-Timeline:
-  - Phase -1 ISOLATE: ✅
-  - Phase 0 THINK: ✅
-  - Phase 1 PLAN: ✅
-  - Phase 2 BUILD: ✅
-  - Phase 3 REVIEW: ✅
-  - Phase 4 ACCEPTANCE: ✅
-  - Phase 5 FEEDBACK: ✅
-  - Phase 6 SHIP: ✅
-  - Phase 7 LAND: ✅ (deploy: success/failure/skipped)
-  - Phase 8 CLEANUP: ✅ (worktree: clean/residual)
-
-Emergent Issues: <N> found
-  - IF Critical → Sprint 2 auto-triggered
-  - IF Major/Minor → Ask user
-
-Worktree cleaned: <yes/no/manual>
-PR merged: <PR_URL>
-```
-
-### Step 6: 处理 Emergent Issues
-
-```bash
-# Check for emergent issues file
-if [ -f ".sprint-state/phase-outputs/emergent-issues.md" ]; then
-  ISSUE_COUNT=$(grep -c "^## " ".sprint-state/phase-outputs/emergent-issues.md" 2>/dev/null || echo "0")
-  
-  if [ "$ISSUE_COUNT" -gt 0 ]; then
-    HAS_CRITICAL=$(grep -i "critical" ".sprint-state/phase-outputs/emergent-issues.md" 2>/dev/null || echo "")
-    
-    if [ -n "$HAS_CRITICAL" ]; then
-      echo ""
-      echo "⚠️ Critical emergent issues detected — auto-triggering Sprint 2"
-      echo "Sprint 2 Pain Document will be generated from emergent-issues.md"
-      # Auto-trigger Sprint 2
-    else
-      echo ""
-      echo "ℹ️ $ISSUE_COUNT emergent issue(s) found — ask user about Sprint 2"
-    fi
-  else
-    echo ""
-    echo "✅ No emergent issues — sprint completed successfully"
-  fi
-else
-  echo ""
-  echo "✅ No emergent issues — sprint completed successfully"
-fi
-```
-
----
-
-## 输出
-
-- Cleanup Report:
-  - Worktree removed: ✅ / ⚠️ residual / ❌ manual required
-  - sprint-state.json: phase 8, status merged
-- Sprint Summary
-- IF emergent issues with Critical → Sprint 2 auto-trigger
-- IF emergent issues without Critical → ask user
-
----
-
-## 暂停点
-
-- **Worktree 手动清理**: 用户确认已手动清理或保留残留
-- **Sprint 2 决策**: 用户确认是否开始 Sprint 2（仅 Major/Minor issues 时）
-
----
-
-## 错误处理
-
-| 错误场景 | 处理 |
-|---------|------|
-| worktree 路径不存在于 sprint-state.json | 跳过清理，输出警告 |
-| `git worktree remove` 失败 | 重试 3 次 → 输出手动命令提示 |
-| 残留目录检测 | 输出警告，用户决策 |
-| sprint-state.json 更新失败 | 输出错误，不影响最终完成状态 |
+**输出**: Cleanup Report, Sprint Summary

package/skills/sprint-flow/references/phase-minus-1-isolate.md

@@ -0,0 +1,58 @@
+# Phase -1: ISOLATE（git worktree 隔离）
+
+**执行时机**: `/sprint-flow` 启动后、Phase 0 THINK 之前。**自动执行**。
+
+**目的**: 默认在 git worktree 中隔离 sprint 工作，防止在保护分支上直接运行导致代码污染。
+
+**AI agent 直接执行 bash 命令**（不需要调用外部 skill），步骤如下：
+
+| 步骤 | 动作 | 说明 |
+|------|------|------|
+| 0 | **检测当前环境** | 运行 `git rev-parse --git-dir` 和 `git rev-parse --git-common-dir`。如果 `GIT_DIR != GIT_COMMON`：已在 worktree 中 → 输出 "Already in isolated worktree" → 进入 Phase 0 |
+| 0.5 | **Sprint Lock 检测（Issue #144）** | 检查 `.sprint-state/sprint.lock` 是否存在: `[ -f .sprint-state/sprint.lock ]`。如果存在: 读取锁内容，检查是否 stale（超过 24 小时或 worktree 目录不存在）→ stale → 输出 `[WARN] 发现过期 sprint lock，将覆盖` → 更新锁。非 stale → 输出 `[BLOCK] 已有活跃 sprint (ID: {sprint_id}, started: {started_at})。请先完成当前 sprint 或手动删除 .sprint-state/sprint.lock` → 退出。锁不存在 → 创建锁: `echo '{"sprint_id":"sprint-YYYY-MM-DD-NN","started_at":"<ISO8601>"}' > .sprint-state/sprint.lock` |
+| 1 | **检查保护分支** | 获取当前分支名 `git branch --show-current`。保护分支列表: `main, master, develop, trunk, mainline`。保护分支 → 强制创建 worktree。非保护分支 → 依然创建 worktree（推荐，不阻断） |
+| 2 | **创建 worktree** | 创建目录: `mkdir -p .worktrees/sprint`。检测已有 NN 编号: `ls .worktrees/sprint/ 2>/dev/null \| grep -oE '[0-9]{2}$' \| sort -n \| tail -1`（取最后两位数字，数值排序，取最大），NN = 结果 + 1（无结果则从 01 开始）。运行 `git worktree add .worktrees/sprint/sprint-YYYY-MM-DD-NN -b sprint/YYYY-MM-DD-NN`。**注意**: `cd` 在 AI agent 单次工具调用中不保持状态，步骤 3-6 必须通过 `workdir` 参数或 `&&` 链式命令在新 worktree 目录下执行 |
+| 3 | **项目 setup** | 在 worktree 目录下: 检测项目类型: `package.json` → `npm install`, `go.mod` → `go mod download`, `pyproject.toml` → `pip/poetry install` |
+| 4 | **.gitignore 校验** | 在**仓库根目录**（非 worktree）执行: `git check-ignore -q .worktrees`。如果未忽略 → 将 `.worktrees/` 添加到 `.gitignore` → `git add .gitignore` → `git commit -m 'chore: ignore .worktrees directory'` |
+| 5 | **Sprint State 记录** | `mkdir -p .sprint-state` 在 worktree 目录下。写入 `.sprint-state/sprint-state.json`（如已存在则合并，保留原有字段），新增/更新 `isolation` 对象，设置 `phase: -1`，`status: "running"` |
+| 6 | **基线验证** | 在 worktree 目录下: 检测测试方式（package.json 有 "test" script → `npm test`, go.mod → `go test ./...`, pyproject.toml → `pytest`）。测试失败 → 输出失败信息 → 询问用户是否继续 |
+
+## 参数处理
+
+- `--no-isolate`: 跳过自动创建，输出 ⚠️ 警告 `'[WARN] 未创建 worktree 隔离，在 {branch} 分支上直接运行 sprint 有污染风险'` → 进入 Phase 0
+- `--branch-name <name>`: 使用自定义分支名（默认自动生成 `sprint/YYYY-MM-DD-NN`），分支名中的 `/` 在 worktree 路径中自动替换为 `-`（如 `feat/user-login` → 分支名 `feat/user-login`，路径 `.worktrees/sprint/feat-user-login`）
+- `--force`: 强制在当前分支继续（即使已是保护分支），**要求用户显式确认**: 输出 ⚠️ 警告 `'[WARN] 使用 --force 在 {branch} 分支上直接运行 sprint。此操作绕过隔离保护，请确认风险。'` → 等待用户确认（"继续" / "取消"） → 确认后进入 Phase 0
+
+## 参数交互规则
+
+| 参数组合 | 行为 |
+|---------|------|
+| `--no-isolate` 单独 | 跳过隔离，输出警告 → Phase 0 |
+| `--force` 单独 | 跳过隔离，要求确认 → Phase 0 |
+| `--no-isolate` + `--branch-name` | `--branch-name` 忽略，仅 `--no-isolate` 生效 |
+| `--force` + `--branch-name` | `--branch-name` 忽略，仅 `--force` 生效 |
+| `--no-isolate` + `--force` | 等效，输出 `--no-isolate` 警告 → Phase 0 |
+| `--resume-from build` + `--no-isolate` | `--resume-from` 优先，直接跳过 Phase -1 |
+
+## 错误处理和回退
+
+| 错误场景 | 回退行为 |
+|---------|---------|
+| `git worktree add` 失败（沙箱/权限问题） | 输出 `[ERROR] git worktree add 失败: {error}` → `[WARN] 无法创建 worktree 隔离，将在当前目录继续。请手动设置隔离分支。` → 在当前目录继续 |
+| `.gitignore` 自动添加失败 | 输出 `[WARN] 无法自动添加 .gitignore，请手动将 .worktrees/ 添加到 .gitignore` → 继续 |
+| 基线测试失败 | 输出 `[FAIL] 基线测试未通过:` + 失败详情 → 询问用户 `'基线测试失败，是否继续 sprint？(y/N)'` |
+
+## sprint-state.json isolation 对象格式
+
+```json
+{
+  "isolation": {
+    "worktree_path": ".worktrees/sprint/sprint-2026-05-24-01",
+    "branch": "sprint/2026-05-24-01",
+    "created_from": "main",
+    "created_from_commit": "abc123def..."
+  }
+}
+```
+
+> **清理提示**: Sprint 完成（Phase 6 SHIP）后，执行 `git worktree remove <worktree_path>` 清理 worktree 目录，同时保留 `.sprint-state/` 中的历史记录。

package/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
 **Generated:** 2026-06-17
-**Commit:** d8388b4
-**Branch:** sprint/2026-06-17-01
-**Version:** 0.8.19.0
+**Commit:** c0c52f4
+**Branch:** main
+**Version:** 0.8.21.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.