@boyingliu01/xp-gate 0.7.0 → 0.8.0

package/plugins/claude-code/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 更新失败 | 输出错误，不影响最终完成状态 |

package/plugins/claude-code/skills/sprint-flow/references/phase-minus-0-5-auto-estimate.md

@@ -0,0 +1,257 @@
+# Phase -0.5: AUTO-ESTIMATE（自动化规模评估与流程路由）
+
+**执行时机**: Phase -1 ISOLATE 完成后、Phase 0 THINK 之前。**自动执行**。
+
+**目的**: 自动评估需求规模，匹配适度流程，避免小需求走重量级流程造成资源浪费。
+
+**核心原则**: 
+- **客观指标 > 主观判断**：依赖代码结构分析，不依赖人/AI 的主观直觉
+- **显式告知**：用户看到客观指标，不是 AI 主观结论
+- **可纠偏**：用户可接受/修改/取消
+- **学习闭环**：记录用户 override，优化阈值
+
+---
+
+## 执行流程
+
+### 步骤 1: 识别需求类型
+
+分析用户输入的需求描述，判定变更类型：
+
+| 关键词模式 | 变更类型 | AUTO-ESTIMATE 时机 |
+|-----------|---------|-------------------|
+| 删除、移除、去掉、砍掉、清理 + 已有模块名 | 删除已存在代码 | 立即执行 |
+| 修改、改、调整、重构、优化 + 已有模块名 | 修改已存在代码 | 立即执行 |
+| 新增、添加、开发、实现、创建 + 新模块名 | 新增功能 | brainstorming 后执行 |
+| 修复、fix、bug | Bug 修复 | 立即执行 |
+| 无法判断 | 询问用户 | — |
+
+**IF 新增功能**: 跳过当前 AUTO-ESTIMATE，先执行 Phase 0 brainstorming，brainstorming 完成后以设计文档为输入重新执行 AUTO-ESTIMATE。
+
+**IF 删除/修改/Bug 修复**: 继续执行以下步骤。
+
+### 步骤 2: 收集指标
+
+#### 2.1 引用计数
+
+```bash
+# 从用户输入中提取目标关键词（模块名、函数名、类名）
+# 示例：删除平面维护界面 → target="plane", "平面"
+grep -rn "{target_pattern}" --include="*.{ext}" . | grep -v node_modules | grep -v .git | wc -l
+```
+
+**阈值**：
+- ≤3: 轻量
+- 4-10: 标准
+- >10: 复杂
+
+#### 2.2 跨模块依赖
+
+分析引用出现的目录分布：
+
+```bash
+# 提取引用所在的目录（取前两级目录）
+grep -rn "{target_pattern}" --include="*.{ext}" . | grep -v node_modules | grep -v .git | \
+  awk -F: '{print $1}' | sed 's|/[^/]*$||' | sort -u
+```
+
+**阈值**：
+- 1 个目录: 轻量
+- 2 个目录: 标准
+- 3+ 个目录: 复杂
+
+#### 2.3 循环依赖检测
+
+简单检查：如果 A 引用 B 且 B 引用 A，则存在循环依赖。
+
+```bash
+# 简化检测：检查目标是否导入其调用者
+# 这需要根据具体语言调整。对于 TS/JS:
+grep -rn "import.*{target}" --include="*.ts" --include="*.tsx" .
+grep -rn "import.*{caller}" --include="*.ts" --include="*.tsx" {target_dir}/
+```
+
+**阈值**：
+- 无: 正常
+- 存在: 高风险 → 无论如何输出风险警告
+
+#### 2.4 Public API 暴露
+
+```bash
+# 统计目标模块中 export 的数量
+grep -rn "^export " {target_dir}/ --include="*.ts" | wc -l
+```
+
+**阈值**：
+- ≤2: 低影响
+- 3-5: 中影响
+- >5: 高影响 → 输出风险警告
+
+#### 2.5 相关测试文件
+
+```bash
+# 统计与目标相关的测试文件数
+find . -name "*{target}*.test.*" -o -name "*{target}*.spec.*" | grep -v node_modules | wc -l
+```
+
+**阈值**：
+- 0: 无测试覆盖（风险提示）
+- 1-2: 正常
+- >3: 重构工作量大 → 提示
+
+### 步骤 3: 汇总评估
+
+根据各指标得分，汇总整体评估结果：
+
+```
+总分计算：
+- 引用计数：轻量=1, 标准=2, 复杂=3
+- 跨模块：轻量=1, 标准=2, 复杂=3
+- 循环依赖：无=0, 存在=5（强制复杂）
+- Public API：低=0, 中=1, 高=2
+- 测试文件：正常=0, 多=1
+
+总分：1-3 = 轻量 | 4-6 = 标准 | 7+ 或 循环依赖存在 = 复杂
+```
+
+### 步骤 4: 输出评估结果
+
+使用 `templates/auto-estimate-output-template.md` 的标准格式向用户展示评估结果。
+
+**MUST** 遵循模板格式，包含：
+- 需求描述 + 变更类型
+- 影响级别标识
+- 各项指标的具体数值
+- 建议流程
+- 风险警告（如有）
+- 用户操作选项
+
+### 步骤 5: 处理用户选择
+
+#### 用户选择「接受建议」
+
+> 按推荐流程执行。保存评估结果到 sprint-state.json。
+
+```json
+{
+  "auto_estimate": {
+    "change_type": "删除已存在代码",
+    "metrics": {
+      "ref_count": 12,
+      "cross_module_count": 3,
+      "modules": ["auth", "user", "admin"],
+      "circular_dep": true,
+      "public_api_count": 5,
+      "test_file_count": 4
+    },
+    "estimated_level": "复杂",
+    "recommended_flow": "完整 Sprint Flow (Phase 0-8)",
+    "risk_warnings": ["循环依赖: user ↔ plane"],
+    "user_decision": "accepted"
+  }
+}
+```
+
+#### 用户选择「修改流程」
+
+> 展示修改流程子菜单（3 个选项：轻量/标准/完整）。
+> 要求用户输入修改原因（必填）。
+
+记录到学习日志：
+```json
+{
+  "sprint_id": "{sprint_id}",
+  "task_description": "{需求描述}",
+  "estimated_level": "标准",
+  "user_override_level": "轻量",
+  "override_reason": "{用户输入原因}",
+  "timestamp": "{当前时间}"
+}
+```
+
+数据写入 `.sprint-state/auto-estimate-learning.json`（追加模式）。
+
+#### 用户选择「取消」
+
+> 停止本次 sprint。
+> 输出：`[CANCELLED] 用户取消 Sprint，AUTO-ESTIMATE 评估结果为 {estimated_level}`。
+
+### 步骤 6: 路由执行
+
+根据最终确定的流程级别，进入对应 Phase：
+
+| 流程级别 | 路由 |
+|---------|------|
+| **轻量** | → Phase 0 THINK（reduced-intensity 流程，见 references/force-levels.md） |
+| **标准** | → Phase 0 THINK（正常流程） |
+| **复杂** | → Phase 0 THINK（完整流程 + 风险警告提示） |
+
+**DELPHI-GATE invariant**: 所有流程级别（轻量/标准/复杂）的 Phase 2 BUILD 启动前，**必须**检查 `.sprint-state/delphi-reviewed.json` 的 verdict 为 `APPROVED`。未通过 delphi-review 直接路由到 BUILD 属于严重违规。
+
+**轻量级的正确理解**: 轻量级意味着 reduced-intensity 的 delphi-review（**2 专家、1 轮、2/2 APPROVED、较短上下文**），**不是**跳过 delphi-review，**不是** 1 专家评审。见 references/force-levels.md 的轻量级流程定义。
+
+**自动 escalation 规则**（检测到以下情况时，自动提升流程级别）:
+
+| 触发条件 | 原级别 | 提升级别 | 理由 |
+|---------|--------|---------|------|
+| 风险警告（循环依赖、Public API > 5） | 轻量 | 标准 | 技术风险需要标准流程 |
+| 多位专家 disagreement 或 REQUEST_CHANGES | 轻量/标准 | 复杂 | 意见分歧需要更全面评审 |
+| 涉及文件数 > 10 或 LOC > 500 | 轻量 | 标准 | 超出轻量级预算 |
+| 修改公共 API（export 接口） | 轻量/标准 | 复杂 | API 变更影响范围广 |
+| 检测到循环依赖 | 任何级别 | 复杂 | 架构风险强制复杂流程 |
+| 相关测试文件缺失或覆盖率 < 80% | 轻量/标准 | 标准 | 需要补充测试 |
+
+**跨参考**: 详见 references/force-levels.md 的各级别流程定义和强制规则。
+
+---
+
+## 特殊场景处理
+
+### 场景 1: 小改动（总计 < 20 行新增/删除代码）
+
+```bash
+# 检查预估改动量
+git diff --stat HEAD 2>/dev/null  # 如果有局部修改
+```
+
+**处理**: 如果预估改动 < 20 行且涉及 ≤ 2 个文件，自动判定为「轻量」并告知用户，不强制展示完整 AUTO-ESTIMATE 面板。
+
+**注意**: 轻量级仍需要完整的 Sprint Flow 流程（包括 delphi-review），只是 reduced-intensity。见 references/force-levels.md 的轻量级定义。**不会**绕过 DELPHI-GATE 直接路由到 BUILD。
+
+### 场景 2: 无法提取目标关键词
+
+**处理**: 询问用户「无法自动识别目标模块，请指定要分析的关键词（函数名/类名/模块名）：」
+
+### 场景 3: 用户输入包含多个独立需求
+
+**处理**: 提示用户「检测到多个独立需求，建议分别执行 sprint。是否拆分？」→ 等待确认
+
+---
+
+## 与学习循环的集成
+
+### 数据收集
+
+每次 sprint 完成（Phase 8 CLEANUP）后，将以下数据记录到 `.sprint-state/auto-estimate-learning.json`：
+
+```json
+{
+  "entries": [
+    {
+      "sprint_id": "sprint-YYYY-MM-DD-NN",
+      "estimated_level": "标准",
+      "user_decision": "accepted",
+      "actual_effort_phase_count": 5,
+      "actual_duration_minutes": 45,
+      "was_accurate": true
+    }
+  ]
+}
+```
+
+### 阈值优化
+
+当积累 ≥ 20 条记录后，提示用户可以运行阈值分析：
+
+> 已积累 {n} 条 AUTO-ESTIMATE 记录。是否运行阈值优化分析？
+> 分析会检查：过度估计（建议标准但实际轻量）、低估（建议轻量但实际复杂），并推荐阈值调整。

package/plugins/claude-code/skills/sprint-flow/templates/auto-estimate-learning-log.md

@@ -0,0 +1,136 @@
+# AUTO-ESTIMATE 学习日志
+
+本文件记录 AUTO-ESTIMATE 的用户纠偏历史和完成数据，用于阈值迭代优化。
+
+## 文件位置
+
+`.sprint-state/auto-estimate-learning.json`
+
+## JSON Schema
+
+```json
+{
+  "entries": [
+    {
+      "sprint_id": "sprint-2026-06-01-14",
+      "task_description": "实现issue92 auto-estimate",
+      "change_type": "新增功能",
+      "estimated_level": "标准",
+      "estimated_metrics": {
+        "ref_count": null,
+        "cross_module_count": 2,
+        "circular_dep": false,
+        "public_api_count": 0,
+        "test_file_count": 0
+      },
+      "user_decision": "accepted",
+      "override_reason": null,
+      "actual_outcome": {
+        "phase_count": 3,
+        "duration_estimate": "30-45min",
+        "was_accurate": true,
+        "notes": "纯文档修改，实际确实为标准级别"
+      },
+      "timestamp": "2026-06-01T23:35:00+08:00"
+    }
+  ],
+  "summary": {
+    "total_entries": 1,
+    "accepted_count": 1,
+    "overridden_count": 0,
+    "accurate_count": 1,
+    "over_estimate_count": 0,
+    "under_estimate_count": 0,
+    "last_updated": "2026-06-01T23:35:00+08:00"
+  }
+}
+```
+
+## 字段说明
+
+### Entry 级别
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `sprint_id` | string | ✅ | Sprint 标识符 |
+| `task_description` | string | ✅ | 需求描述 |
+| `change_type` | string | ✅ | 变更类型：`删除已存在代码` / `修改已存在代码` / `新增功能` / `Bug修复` |
+| `estimated_level` | string | ✅ | 评估级别：`轻量` / `标准` / `复杂` |
+| `estimated_metrics` | object | ✅ | 评估时的指标数据 |
+| `user_decision` | string | ✅ | 用户决定：`accepted` / `overridden` / `cancelled` |
+| `override_reason` | string | 条件 | 当 `user_decision` 为 `overridden` 时必填 |
+| `actual_outcome` | object | 条件 | Sprint 完成后回填 |
+| `timestamp` | string | ✅ | ISO 8601 时间戳 |
+
+### actual_outcome 级别
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `phase_count` | number | ✅ | 实际执行的 phase 数 |
+| `duration_estimate` | string | 推荐 | 实际耗时估算 |
+| `was_accurate` | boolean | ✅ | 评估是否准确 |
+| `notes` | string | 推荐 | 备注说明 |
+
+### summary 级别
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `total_entries` | number | 总条目数 |
+| `accepted_count` | number | 接受建议数 |
+| `overridden_count` | number | 用户修改数 |
+| `accurate_count` | number | 评估准确数 |
+| `over_estimate_count` | number | 高估数（建议标准但实际轻量） |
+| `under_estimate_count` | number | 低估数（建议轻量但实际复杂） |
+
+## 初始化
+
+新 sprint 创建时，自动创建 `.sprint-state/auto-estimate-learning.json`：
+
+```json
+{
+  "entries": [],
+  "summary": {
+    "total_entries": 0,
+    "accepted_count": 0,
+    "overridden_count": 0,
+    "accurate_count": 0,
+    "over_estimate_count": 0,
+    "under_estimate_count": 0,
+    "last_updated": null
+  }
+}
+```
+
+## 阈值优化触发
+
+当 `total_entries >= 20` 时，在 Phase 8 CLEANUP 阶段提示用户：
+
+```
+已积累 20 条 AUTO-ESTIMATE 记录。是否运行阈值优化分析？
+
+当前准确率：{accurate_count / total_entries * 100}%
+高估率：{over_estimate_count / total_entries * 100}%
+低估率：{under_estimate_count / total_entries * 100}%
+
+[运行分析] [跳过]
+```
+
+## 阈值优化规则
+
+### 高估模式检测
+
+IF `over_estimate_count / total_entries > 30%`:
+→ 建议降低「标准」→「复杂」的引用计数阈值（当前 >10）
+→ 分析高估的共性：是否某个指标权重过高？
+
+### 低估模式检测
+
+IF `under_estimate_count / total_entries > 20%`:
+→ 建议增加额外检查项（如循环依赖、测试文件数）
+→ 分析低估的共性：是否遗漏了关键复杂度信号？
+
+### 纠偏频率检测
+
+IF `overridden_count / total_entries > 30%`:
+→ 用户频繁修改建议 → 阈值体系可能有问题
+→ 建议全面阈值校准