xp-gate 0.5.1

package/skills/sprint-flow/references/phase-5-feedback.md

@@ -0,0 +1,100 @@
+# Phase 5: FEEDBACK CAPTURE（反馈捕获）
+
+## 目标
+
+记录 Emergent 发现，工程回顾（团队级），持续改进。为 Sprint 2 准备 Pain Document。
+
+---
+
+## 调用 Skills
+
+- `learn` (gstack) — 模式记录（个人级）
+- `retro` (gstack) _(新增)_ — 周工程回顾：提交历史、工作模式、代码质量趋势（团队级）
+- `systematic-debugging` (superpowers) _(可选)_ — 根因调试：反馈中的 bug 做根因分析
+
+---
+
+## 执行步骤
+
+### Step 1: 调用 learn skill
+
+```
+skill(name="learn", user_message="[Emergent Issues 内容 + Sprint 总结]")
+```
+
+learn 执行：
+- 记录本次 Sprint 的 emergent 发现
+- 转化为 CLAUDE.md 规则
+- 更新 institutional memory
+
+### Step 2: 工程回顾 — 调用 retro（新增 — ISSUE32）
+
+```
+skill(name="retro")
+```
+
+retro 执行：
+- **提交历史分析**: 本次 Sprint 的 commits、工作模式
+- **代码质量趋势**: 结合 Phase 3 的 benchmark 数据，展示质量变化
+- **团队贡献分解**: 每人贡献比例 + praise + growth areas
+- **改进建议**: 下次 Sprint 的改进点
+
+输出: Retro 报告（周级工程回顾）
+
+### Step 3: 根因调试（可选 — ISSUE32）
+
+**IF Phase 4 发现 bug 或 Phase 3 验证失败**:
+```
+skill(name="systematic-debugging", user_message="[具体 bug 描述]")
+```
+
+systematic-debugging 执行 4 阶段：
+1. Investigate（根因调查）
+2. Analyze（分析）
+3. Hypothesize（假设验证）
+4. Implement（修复）
+
+**Iron Law**: 无调查 → 不修复
+
+### Step 4: 转化 Emergent Issues 为 Sprint 2 Pain Document
+
+如果有 emergent issues，转化为新需求：
+```markdown
+# Sprint 2 Pain Document
+
+## 来源
+基于 Sprint 1 的 Emergent Issues
+
+## Critical Issues (自动进入 Sprint 2)
+| Issue | Sprint 1 描述 | Sprint 2 目标 |
+|-------|--------------|--------------|
+
+## Major Issues (询问用户是否纳入)
+| Issue | Sprint 1 描述 | Sprint 2 目标 |
+|-------|--------------|--------------|
+
+## Minor Issues (可选纳入)
+| Issue | Sprint 1 描述 | Sprint 2 目标 |
+|-------|--------------|--------------|
+```
+
+### Step 5: 保存 Feedback Log 和 Sprint 2 Pain Document
+
+保存到：
+- `<project-root>/.sprint-state/phase-outputs/feedback-log.md`
+- `<project-root>/.sprint-state/phase-outputs/sprint2-pain.md` (如有 emergent issues)
+
+---
+
+## 暂停点
+
+**无** — Phase 5 完成后自动进入 Phase 6
+
+---
+
+## 输出
+
+- Feedback Log (`feedback-log.md`)
+- Retro Report（retro 输出）
+- Sprint 2 Pain Document (`sprint2-pain.md`) — 如果有 emergent issues
+- 进入 Phase 6 自动执行

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

@@ -0,0 +1,193 @@
+# Phase 6: SHIP + DEPLOY（发布）
+
+## 目标
+
+结构化分支完成决策、创建 PR、合并部署、监控。生成 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
+IF 测试全部通过 + 需要 review → PR → ship → 等待 review → land-and-deploy
+IF 实验失败 → discard → 清理 worktree → 结束 Sprint
+IF 半成品 → keep → 保留分支 → 结束 Sprint
+```
+
+**worktree 清理**: finishing-a-development-branch 自动清理不再需要的 worktree。
+
+### Step 3: 用户确认合并/发布
+
+提示用户：
+```
+⚠️ 分支完成决策:
+
+- [merge] → 直接合并 + 部署
+- [PR] → PR 已创建: [URL]，请确认合并
+- [discard] → 清理分支，结束 Sprint
+- [keep] → 保留分支，待后续处理
+
+请确认选项：
+```
+
+**discard/keep**: 进入 Step 5（清理 + 生成 Summary）
+
+**merge/PR 确认**: 进入 Step 4
+
+### 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 创建后等待用户确认合并
+
+### 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 |
+| ship PR 创建（PR 路径） | PR 已创建 | 用户确认合并 |
+| land-and-deploy 失败 | CI 或部署失败 | 用户处理问题 |
+
+---
+
+## 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 开始）

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

@@ -0,0 +1,140 @@
+# Phase 7: LAND（合并 + 部署）
+
+## 目标
+
+自动合并 PR、等待 CI、执行部署、运行 Canary Health Check、失败时自动回滚。
+
+---
+
+## 输入
+
+- 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 |

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

@@ -0,0 +1,192 @@
+# Phase 8: CLEANUP（清理 + 总结）
+
+## 目标
+
+自动清理 worktree、更新 sprint-state.json、输出 Sprint Summary、处理 emergent issues。
+
+---
+
+## 输入
+
+- 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 更新失败 | 输出错误，不影响最终完成状态 |