@boyingliu01/xp-gate 0.18.5 → 0.19.0

package/plugins/dsh/skills/sprint-flow/references/phase-5-ship.md

@@ -0,0 +1,222 @@
+# Phase 5/6: SHIP（发布 — 发布准备 + 合并部署）
+
+**执行时机**: Phase 4/6 VERIFY 完成后、Phase 6/6 CLOSE 之前。
+**对应旧模型**: Phase 5 SHIP + Phase 6 LAND
+
+**摘要**: 结构化分支完成决策（原生 4 选项）, 创建 PR（原生步骤）, 合并部署（原生步骤）, 监控. 生成 Sprint Summary.
+
+---
+
+## Part A: SHIP（发布准备）
+
+**Orchestrator 直接执行**: 分支完成决策和 PR 创建均为交互式步骤（4 选项菜单 + PR 确认），**必须由 orchestrator 直接执行**。
+
+**关键链**: VERSION-GATE(MANDATORY) → 分支完成决策(4选项) → push PR
+
+**HARD-GATE**: Phase 4/6 VERIFY 未完成 → BLOCK。验证 `feedback-log.md` 存在。
+
+**GITHOOKS-GATE**: 验证 hooks 完整性，缺失则 `githooks/install.sh`
+
+**NETWORK-RESILIENCE**: GitHub API 在大中华区存在间歇性 TLS/超时问题。所有 `gh` CLI 调用应容忍偶尔失败：
+- `gh` 命令失败时等待 2-5 秒后重试（最多 3 次）
+- 优先使用 REST API (`gh api /repos/...`) 而非 GraphQL (`gh pr view --json ...`)，REST 更轻量更可靠
+- 验证 CI 状态时使用 `gh run list --branch ... --limit 1 --json status,conclusion` 代替 `gh pr view --json statusCheckRollup`
+- 如果 `gh` 持续超时，fallback 到 `curl + token`:
+  ```
+  curl -s -H "Authorization: token $(gh auth token)" \
+    "https://api.github.com/repos/OWNER/REPO/commits/HEAD/status"
+  ```
+
+### Step 0: VERSION-GATE（MANDATORY — 在分支完成决策之前执行）
+
+**Purpose**: Ensure version bump, changelog update, and sync before creating PR. This MUST run BEFORE the branch completion decision — the "Create PR" option creates the PR immediately, so version changes must be committed first.
+
+**Execution**:
+
+```
+1. 根据变更类型决定 bump 级别:
+   - PATCH (0.14.0 → 0.14.1): bug fixes, docs, minor enhancements
+   - MINOR (0.14.0 → 0.15.0): new features, significant enhancements
+   - MAJOR (0.14.0 → 1.0.0): breaking changes
+
+2. 更新 VERSION 文件 (MAJOR.MINOR.PATCH.MICRO 格式)
+
+3. 更新 CHANGELOG.md:
+   - 添加新版本条目 (## [X.Y.Z.W] - YYYY-MM-DD)
+   - 按 ### Added / ### Fixed / ### Changed 分类
+
+4. 运行 sync-version.sh:
+   bash scripts/sync-version.sh
+
+5. 验证:
+   git diff VERSION              # 确认版本号变更
+   git diff CHANGELOG.md         # 确认 changelog 变更
+   git diff --stat               # 确认 package.json 版本同步
+
+6. 提交版本变更:
+   git add VERSION CHANGELOG.md && git commit -m "release: bump version to X.Y.Z.W"
+
+7. 推送到远程分支:
+   git push
+
+8. 验证 CI 流程触发:
+   gh pr view <PR_NUMBER> --json state  # 确认 CI 已开始
+```
+
+**GATE CHECK** (BEFORE proceeding to branch completion decision):
+```
+[VERSION-GATE] VERSION bump ✓   # VERSION 文件已更新
+[VERSION-GATE] CHANGELOG ✓      # 新版本条目已添加
+[VERSION-GATE] sync-version ✓   # 所有 package.json 已同步
+[VERSION-GATE] committed ✓      # 版本变更已提交并推送
+[VERSION-GATE] PR updated ✓     # PR 已包含版本变更 commit
+```
+
+**⚠️ ANTI-PATTERN**: 先创建 PR 再 bump VERSION 会导致 PR 不含版本变更 → CI 不触发 release workflow → 无新版本发布。
+
+**输出**: 版本变更 commit 包含在 PR 中
+
+### Step 1: 分支完成决策（原生 4 选项 — AskUserQuestion）
+
+VERSION-GATE 通过后，orchestrator 向用户展示 4 选项菜单：
+
+```
+⚠️ Phase 5/6 SHIP: 分支完成决策
+
+Sprint 分支已准备就绪。请选择操作：
+
+1. **Merge to main** — 直接合并到主分支（适用于个人项目或已确认无需 PR 审查）
+2. **Push and create a Pull Request** — 推送并创建 PR（推荐，含 CI 验证）
+3. **Keep branch** — 保留分支，稍后处理
+4. **Discard** — 丢弃分支（⚠️ 需要输入确认）
+
+请选择 (1-4):
+```
+
+**Option 4 (Discard) 安全确认**: 要求用户输入分支名确认，防止误删。
+
+**默认推荐**: Option 2（Push and create a Pull Request）。
+
+### Step 2: 原生 Ship 步骤序列（选择 Option 2 时执行）
+
+```
+1. 运行测试:
+   npm test  # 或项目特定测试命令
+
+2. VERSION-GATE 已通过（Step 0）
+
+3. 提交所有变更:
+   git add -A && git commit -m "feat: <sprint-description>"
+
+4. 推送到远程:
+   git push -u origin <sprint-branch>
+
+5. 创建 PR:
+   gh pr create --title "feat: <description>" --body "<sprint-summary>"
+
+6. 输出 PR URL
+```
+
+**输出**: PR URL (含版本变更 commit)
+
+---
+
+## Part B: LAND（合并 + 部署 — 原生步骤）
+
+**Orchestrator 直接执行**: 合并确认和 rollback 决策均为用户交互点，**必须由 orchestrator 直接执行**。
+
+**输入**: PR URL → 输出: 部署状态 + Canary 报告
+
+### Step 1: Merge 确认
+
+```
+⚠️ 确认合并 PR #<number> 到 main?
+
+PR: <PR URL>
+变更: <files changed> 个文件, +<additions>/-<deletions>
+
+确认合并? (yes/no):
+```
+
+### Step 2: 等待 CI
+
+```
+# 等待 CI 完成（最多 10 分钟）
+gh run list --branch main --limit 1 --json status,conclusion
+
+# 轮询直到完成
+WHILE status != "completed":
+  等待 30 秒
+  重新查询
+```
+
+### Step 3: 等待 Deploy（如适用）
+
+```
+# 等待部署完成（最多 10 分钟）
+# 检测部署平台（Fly.io/Render/Vercel/Netlify/Heroku/GitHub Actions）
+# 查询部署状态
+```
+
+**条件跳过**: 无部署配置时仅 merge + CI。
+
+### Step 4: Canary Health Check（如适用，最多 5 分钟）
+
+```
+# 健康检查端点
+curl -s <health-check-url>
+# 验证返回 200 + 预期响应
+```
+
+### Step 5: 失败回滚
+
+```
+IF CI 失败 OR 部署失败 OR canary 异常:
+  git revert <merge-commit-sha>
+  git push
+  输出 "[ROLLBACK] 已回滚 merge commit"
+```
+
+**输出**: 部署状态 (success/failure/skipped), Canary 报告
+
+---
+
+## SHIP COMPLETION GATE (MANDATORY — v0.14.3+)
+
+**Purpose**: Ensure merge to main + release is complete before Phase 6/6 CLOSE. Without this gate, worktree cleanup fails (uncommitted changes + unmerged branch) and UAT happens on the wrong version (PR branch, not main).
+
+**Execution** (BEFORE transitioning to Phase 6/6):
+
+```
+1. Verify PR is merged:
+   gh pr list --head <sprint-branch> --state merged --json number
+   → If no merged PR: BLOCK. Do NOT proceed to Phase 6/6.
+
+2. Verify current branch is main:
+   CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+   → If not main/master: BLOCK. Switch to main first.
+
+3. Verify git status is clean:
+   git status --porcelain
+   → If not empty: BLOCK. Stash or commit changes first.
+
+4. Verify release exists:
+   gh release view v<X.Y.Z> --json tagName
+   → If not found: WARNING (manual release may have failed). Ask user.
+
+5. Pull latest main:
+   git checkout main && git pull
+```
+
+**GATE CHECK** (BEFORE Phase 6/6 CLOSE):
+```
+[SHIP→CLOSE GATE] PR merged ✓        # PR is in merged state
+[SHIP→CLOSE GATE] on main branch ✓   # Current branch is main/master
+[SHIP→CLOSE GATE] clean status ✓     # No uncommitted changes
+[SHIP→CLOSE GATE] release exists ✓   # GitHub Release created
+[SHIP→CLOSE GATE] main up-to-date ✓  # Pulled latest
+```
+
+**IF GATE FAILS**: Orchestrator MUST complete the merge/release steps BEFORE proceeding to Phase 6/6. Do NOT skip to CLOSE.
+
+**Output**: SHIP completion confirmation, ready for Phase 6/6.

package/plugins/dsh/skills/sprint-flow/references/phase-6-close.md

@@ -0,0 +1,266 @@
+# Phase 6/6: CLOSE（收尾 — ⚠️ 人工验收 + 清理）
+
+**执行时机**: Phase 5/6 SHIP 完成后（merge to main + release 已完成）。
+**对应旧模型**: Phase 7 USER ACCEPTANCE + Phase 8 CLEANUP
+
+**NETWORK-RESILIENCE**: 与 Phase 5/6 相同，GitHub API 在大中华区存在间歇性超时。CLEANUP 中的 `gh pr list` 和 `git push --delete` 需容忍重试。详见 `phase-5-ship.md` NETWORK-RESILIENCE 指南。
+
+---
+
+## ⚠️ HARD-GATE: SHIP→CLOSE GATE (MANDATORY — v0.14.3+)
+
+**Purpose**: Verify that Phase 5/6 SHIP fully completed (merge to main + release) before entering Phase 6/6 CLOSE. This gate prevents:
+- Worktree cleanup failure (uncommitted changes prevent `git worktree remove`)
+- UAT on wrong version (PR branch instead of merged main)
+
+**Execution**: Before ANY Phase 6/6 step, run the SHIP→CLOSE GATE checks defined in `phase-5-ship.md#ship-completion-gate`.
+
+**If gate fails**: Return to Phase 5/6 SHIP to complete merge/release. Do NOT proceed with CLOSE.
+
+---
+
+## Backup Sprint State (MANDATORY — v0.14.3+)
+
+**Purpose**: `.sprint-state/` is gitignored and lives inside the worktree. When the worktree is removed during CLEANUP, all sprint state is lost. This step copies it into the main repository before cleanup.
+
+**Execution** (immediately after SHIP→CLOSE GATE passes):
+
+```bash
+# 1. Read sprint ID
+SPRINT_ID=$(cat .sprint-state/sprint-state.json | grep '"id"' | head -1 | sed 's/.*"id": *"\([^"]*\)".*/\1/')
+
+# 2. Backup to repo-tracked path (.sprint-history is NOT in .gitignore)
+BACKUP_DIR=".sprint-history/${SPRINT_ID}"
+mkdir -p "$BACKUP_DIR"
+cp -r .sprint-state/* "$BACKUP_DIR/"
+
+# 3. Verify backup
+ls "$BACKUP_DIR/sprint-state.json" && echo "✅ Sprint state backed up to $BACKUP_DIR"
+```
+
+**GATE CHECK**:
+```
+[BACKUP] sprint-state.json copied ✓
+[BACKUP] phase-outputs/ preserved ✓
+```
+
+**Output**: `.sprint-history/<sprint-id>/` contains full sprint state, safely outside the worktree.
+
+---
+
+## Part A: USER ACCEPTANCE（⚠️ 人工验收）
+
+### 目标
+
+用户实际使用 MVP，发现 Emergent 问题。这是 AI 无法预测的环节。
+
+### ⚠️ 关键说明
+
+**这是 Emergent Requirements 发现环节。**
+
+- AI 无法预测用户看到产品后才发现的问题
+- 78% 的软件失败是用户使用时发现的，不是开发阶段发现的
+- 必须由用户实际使用验收
+
+### 调用 Skills
+
+**无** — 必须人工
+
+### 执行步骤
+
+#### Step 1: 提示用户开始验收
+
+```
+⚠️ Phase 6/6 CLOSE: USER ACCEPTANCE
+
+MVP 已通过自动化验证，现在需要您实际使用验收。
+
+请按照以下步骤：
+1. 启动应用（或访问部署地址）
+2. 使用 Emergent Issues 检查清单进行验收
+3. 记录发现的问题
+4. 完成后确认是否继续
+
+验收完成后，请回复：
+- "验收通过" → 进入 Part B CLEANUP
+- "发现问题" → 填写 emergent-issues.md
+```
+
+#### Step 2: 用户实际使用 MVP
+
+用户按照 Emergent Issues 检查清单验收，使用模板：`@templates/emergent-issues-template.md`
+
+检查维度：
+1. **核心功能体验** (Core Functionality UX)
+2. **多轮交互体验** (Multi-turn Interaction UX)
+3. **视觉/交互体验** (Visual/Interaction UX)
+4. **用户认知负担** (Cognitive Load)
+5. **意外发现** (Unexpected Observations)
+
+#### Step 3: 记录 Emergent Issues
+
+用户填写 `emergent-issues.md`：
+
+```markdown
+# Emergent Issues - [需求名称]
+
+## 验收日期: YYYY-MM-DD
+
+## 发现的问题
+
+### Critical
+### Major
+### Minor
+
+## 验收结论
+- [ ] ✅ 验收通过，进入 CLEANUP
+- [ ] ⚠️ 发现问题需 Sprint 2 迭代
+```
+
+#### Step 4: 保存 Emergent Issues
+
+保存到 `<project-root>/.sprint-state/phase-outputs/emergent-issues.md`
+
+### 暂停点
+
+**⚠️ 必须等待用户验收完成**
+
+- 用户确认验收结果后才能继续
+- 如果发现重大问题 → Sprint 2 回到 Phase 2/6 DESIGN
+
+### Sprint 2 触发逻辑
+
+```
+Phase 6/6 CLOSE 完成时:
+  IF emergent_issues_count == 0 → sprint_completed，结束流程
+  
+  IF emergent_issues_count > 0:
+    ├─ IF emergent_issues 有 Critical → 自动启动 Sprint 2
+    ├─ IF emergent_issues 仅 Major/Minor → 询问用户
+    └─ Sprint 2 Pain Document 从 emergent-issues.md 转化
+```
+
+### 输出
+
+- Emergent Issues List (`emergent-issues.md`)
+- 进入 Part A.5 ARCHIVE 自动执行（如果用户确认验收）
+
+---
+
+## Part A.5: ARCHIVE（归档 — v0.14.0+ Issue #308）
+
+**Purpose**: Preserve sprint decision records before cleanup. `.sprint-state/` is gitignored and deleted during CLEANUP; this step copies structured outputs to `.sprint-history/` which is tracked by git.
+
+**Execution**: After USER ACCEPTANCE (Part A) confirms continuation, BEFORE CLEANUP (Part B).
+
+### Step 1: Read Sprint ID
+
+Read `sprint-state.json` → `id` field (e.g., `sprint-2026-07-09-01`).
+
+### Step 2: Check for Conflicts
+
+```
+IF .sprint-history/<sprint-id>/ already exists:
+  → Append timestamp suffix: <sprint-id>-20260709T120000
+  → Log warning: "Sprint archive conflict, using timestamp suffix"
+```
+
+### Step 3: Archive Files
+
+Copy from `.sprint-state/` to `.sprint-history/<sprint-id>/`:
+
+**Included** (all `.yaml`, `.json`, `.md` files under `.sprint-state/`):
+- `specification.yaml` (if in phase-outputs/)
+- `delphi-reviewed.json`
+- `sprint-state.json`
+- `phase-outputs/*.yaml`, `phase-outputs/*.json`, `phase-outputs/*.md`
+- `tdd-gate-log.json`, `uncommitted-gate-log.json`
+
+**Excluded** (temporary/cache):
+- `*.tmp`, `*.cache` files
+- `sprint.lock` (session lock file)
+
+### Step 4: Verify Git Tracking
+
+```bash
+# .sprint-history/ is NOT in .gitignore (verified — no change needed)
+# Verify files are trackable:
+git status .sprint-history/
+```
+
+**No `.gitignore` change needed**: `.sprint-history/` is NOT currently listed in `.gitignore`. The `.sprint-state/` ignore (line 59) only matches `.sprint-state/` exactly — it does NOT match `.sprint-history/`.
+
+### Step 5: Commit Archive (Optional)
+
+The orchestrator MAY commit the archive:
+```
+git add .sprint-history/<sprint-id>/ && git commit -m "archive: sprint <sprint-id>"
+```
+
+### Output
+
+- `.sprint-history/<sprint-id>/` directory with archived sprint state
+- Git-tracked sprint decision records for future retro/review
+
+---
+
+## Part B: CLEANUP（清理 + 总结 + 返工追踪）
+
+**摘要**: 写入 #369 返工指标, 自动清理 worktree, 更新 sprint-state.json, 输出 Sprint Summary, 处理 emergent issues.
+
+### Step 0: #369 返工追踪指标写入（v0.18.0+）
+
+**Purpose**: Sprint 完成后追踪返工率，暴露"门禁全过但仍返工"的质量问题。
+
+**Execution** (CLEANUP 开始时，worktree 清理前):
+
+```
+1. 写入 metrics.completed_at:
+   ISO 8601 时间戳 → sprint-state.json metrics.completed_at
+
+2. 计算 metrics.total_sprint_commits:
+   精确定义: sprint 分支 base（merge-base）到 sprint 合并点的提交数
+   CLOSE 时由 CLI 计算写入:
+   npx xp-gate sprint-status --rework-check
+
+3. 写入 metrics.merge_base_sha:
+   merge-base SHA → sprint-state.json metrics.merge_base_sha
+   （SHIP 阶段存入，供删分支后 rework-check 使用 — C5 澄清）
+```
+
+**返工率计算** (`xp-gate sprint-status --rework-check [--window-days N]`):
+- 默认窗口: 7 天（可配置）
+- 扫描范围: **仓库范围**（不限同一分支 — 主工作流"合并 PR + 删除分支"下同分支判定恒为 0）
+- fix 提交匹配: conventional commits 优先 `^fix(\(.+\))?:`，辅以词边界关键词 `\b(fix|bugfix|hotfix|patch|修复)\b`
+- 计算: `rework_rate = fix_commits_in_window / total_sprint_commits`
+- 写回 `metrics.rework_rate`
+
+**告警**: `rework_rate > 30%` → 告警输出（并纳入 `xp-gate retro` 报告区块）
+
+**注意**: "重新打开的 issue 数"指标已删除（Round 1 修订：零依赖原则下无可靠数据源）。
+
+### 执行步骤
+
+1. **保存分支信息** → 记录清理前的分支和工作树信息
+2. **清理 worktree**: `git worktree remove <worktree_path>`（精确路径，禁止通配符）
+   - 重试机制: 失败后重试最多 3 次，每次间隔 3 秒
+   - 仍失败: 输出 `[ERROR]` + 手动清理命令
+3. **删除本地分支**: `git branch -D sprint/YYYY-MM-DD-NN`
+4. **删除远程分支**: `git push origin --delete sprint/YYYY-MM-DD-NN`
+5. **关闭遗留 OPEN PR**: `gh pr list --head sprint/YYYY-MM-DD-NN --state open`
+6. **更新 sprint-state.json**: 设置 `phase: 6`, `status: "completed"`, 写入 `metrics.completed_at` + `metrics.total_sprint_commits`（#369）
+7. **释放 Sprint Lock** (Issue #144): 删除 `.sprint-state/sprint.lock`
+8. **Learnings 写入**（原生）: 将 Sprint 中发现的模式/教训追加到 `.sprint-history/learnings.md`
+9. **Sprint Summary**: 使用 `templates/sprint-summary-template.md` 生成总结
+10. **处理 Emergent Issues**: 如 Part A 发现 emergent issues → 触发 Sprint 2 逻辑
+
+### 输出
+
+- Cleanup Report
+- Sprint Summary
+- 条件跳过: `--no-isolate` 路径下跳过 worktree 清理（无 worktree 可清理）
+
+### 暂停点
+
+- **清理失败**: 输出 `[ERROR]` 日志 + 建议手动清理命令 → 用户确认后继续
+- **Sprint Summary**: 展示完整 Sprint 总结 → 用户确认 → 结束流程