@boyingliu01/xp-gate 0.15.4 → 0.18.0

package/plugins/opencode/skills/sprint-flow/references/phase-4-verify.md

@@ -1,15 +1,15 @@
-# Phase 4/6: VERIFY（验证 — 代码走查 + QA + 反馈获取）
+# Phase 4/6: VERIFY（验证 — 代码走查 + 测试对齐 + 反馈获取）
 
 **执行时机**: Phase 3/6 BUILD 完成后、Phase 5/6 SHIP 之前。
 **对应旧模型**: Phase 3 REVIEW + Phase 4 FEEDBACK
 
 ## 目标
 
-多专家代码走查、测试对齐、浏览器测试、反馈捕获。确保 MVP 符合 specification 并记录经验教训。
+多专家代码走查、测试对齐（#367 程序化 HARD-GATE）、浏览器验证（Layer 4 可选链）、反馈捕获。确保 MVP 符合 specification 并记录经验教训。
 
 **执行者**: orchestrator 直接执行 Part A（非 subagent dispatch — Issue #249）。
 
-Web 前端项目额外增加：系统化 QA、视觉审计、性能基线。
+Web 前端项目额外增加：原生 UI 审查 + 可选增强。
 
 ---
 
@@ -17,20 +17,27 @@ Web 前端项目额外增加：系统化 QA、视觉审计、性能基线。
 
 ### 调用 Skills
 
-**所有项目**:
+**所有项目（原生 HARD-GATE 链）**:
 - `delphi-review --mode code-walkthrough` — 多专家匿名代码走查（2-3 domestic models, ≥90% consensus）
-- `test-specification-alignment` — 测试与 Spec 对齐验证
-- `browse` (gstack) — 浏览器自动化测试
+- `test-specification-alignment` — 测试与 Spec 对齐验证（#367 程序化 HARD-GATE）
+- `xp-gate check --all` — 全量质量门禁（Gate 0–9，含安全审计）
+
+**浏览器验证 — Layer 4 可选链**:
+```
+OPTIONAL: 若检测到 gstack browse 已安装 → 使用 gstack browse 进行浏览器自动化测试
+ELSE IF 平台支持 browser-use MCP → 使用 browser-use MCP
+ELSE → SKIP 并记录 "[sprint-flow] 浏览器验证 SKIP（无可用浏览器工具）"
+```
 
 **Web 前端项目额外注入** (`--type web-nextjs` / `web-react` / `web-vue`):
-- `qa` (gstack) — 三层 QA（Quick/Standard/Exhaustive）系统化测试
-- `design-review` (gstack) — 线上 UI 视觉审计（间距、层级、AI slop 检测）
-- `benchmark` (gstack) — Core Web Vitals 性能基线
+- `xp-gate ui-review`（原生）— UI 视觉审查（间距、层级、一致性）
+- OPTIONAL: 若检测到 gstack `qa` 已安装 → 三层 QA 系统化测试；未安装则 SKIP
+- OPTIONAL: 若检测到 gstack `design-review` 已安装 → 视觉审计增强；未安装则 SKIP
+- OPTIONAL: 若检测到 gstack `benchmark` 已安装 → Core Web Vitals 基线；未安装则 SKIP
 
 **Mobile 项目额外注入** (`--type mobile-flutter` / `mobile-react-native`):
 - `flutter-test` — Flutter 单元测试 + widget 测试 (Flutter only)
 - Detox E2E — React Native 端到端测试 (RN only)
-- `flutter-review` (user) — Flutter 代码审查 (Flutter only)
 
 **Backend 项目额外注入** (`--type backend-go` / `backend-springboot` / `backend-django`):
 - API Testing — 后端 API 自动化测试
@@ -51,7 +58,7 @@ skill(name="delphi-review", user_message="--mode code-walkthrough")
 
 **如果 REQUEST_CHANGES**: 暂停等待用户处理 → 修复后重新评审。**如果 APPROVED**: 写入 `.code-walkthrough-result.json`（1 小时有效期）→ 进入 Step 2。
 
-#### Step 2: 调用 test-specification-alignment
+#### Step 2: 调用 test-specification-alignment（#367 程序化 HARD-GATE）
 
 ```
 skill(name="test-specification-alignment", user_message="--spec specification.yaml --tests mvp-v1/tests")
@@ -59,28 +66,61 @@ skill(name="test-specification-alignment", user_message="--spec specification.ya
 
 Phase 1: 验证对齐（可修改测试） → Phase 2: 执行测试（禁止修改测试）
 
+**#367 修复 — 程序化 HARD-GATE**:
+
+test-specification-alignment 执行后**必须**输出 `.sprint-state/phase-outputs/test-alignment-report.json`：
+
+```json
+{
+  "alignment_status": "PASS | FAIL",
+  "head_commit": "<git rev-parse HEAD>",
+  "spec_hash": "<SHA-256 of specification.yaml>",
+  "req_test_mapping": {},
+  "ac_assertion_mapping": {},
+  "timestamp": "<ISO 8601>"
+}
+```
+
+**`phase-transition 4 completed` 程序化校验**:
+- 文件缺失 → BLOCK
+- `alignment_status` 非 PASS → BLOCK
+- `head_commit` 与当前 HEAD 不符 → BLOCK（防陈旧绑定）
+- `spec_hash` 与当前 specification.yaml 不符 → BLOCK（防陈旧绑定）
+
+**--skip-evidence 逃生口护栏**:
+- `--skip-evidence` 必须同时提供 `--reason "<text>"`
+- 每次使用写入 audit.jsonl（`event: evidence_skipped, reason, phase`）
+- `xp-gate retro` 报告设曝光区块
+- 单 sprint 使用 >2 次 → 告警
+
 #### Step 2.5: 质量门禁全量验证
 
 ```
 npx xp-gate check --all
 ```
 
-运行所有可用的质量门禁（Gate 0–9）并输出汇总报告。任何 BLOCK 状态 → 回退 Phase 3/6 修复。
+运行所有可用的质量门禁（Gate 0–9，含安全审计 Gate 7/8/9）并输出汇总报告。任何 BLOCK 状态 → 回退 Phase 3/6 修复。
 
-> 此步骤自动调用各独立门禁（lint、复杂度、principles、架构、安全扫描等），无需手动逐个执行。
+> 此步骤自动调用各独立门禁（lint、复杂度、principles、架构、安全扫描等），无需手动逐个执行。替代原 `cso` 外部 skill 调用。
 
 #### Step 2.5-2.10: 项目类型特定验证（Web/Mobile/Backend）
 
-- **Web**: qa → design-review → benchmark
+- **Web**: `xp-gate ui-review`（原生）→ OPTIONAL gstack qa/design-review/benchmark（如已安装）
 - **Mobile**: flutter-test / detox E2E
 - **Backend**: API automation tests
 
-#### Step 3: 调用 browse skill
+#### Step 3: 浏览器验证（Layer 4 可选链）
 
 ```
-skill(name="browse", user_message="--url [URL] --test-ui")
+OPTIONAL: 若检测到 gstack browse 已安装:
+  skill(name="browse", user_message="--url [URL] --test-ui")
+ELSE IF 平台支持 browser-use MCP:
+  使用 browser-use MCP 进行浏览器验证
+ELSE:
+  SKIP 并记录 "[sprint-flow] 浏览器验证 SKIP（无可用浏览器工具）"
 ```
-默认: `localhost:3000`。发现问题 → 回退 Phase 3/6 修复。
+
+默认 URL: `localhost:3000`。发现问题 → 回退 Phase 3/6 修复。
 
 #### Step 4: 保存 Review Report
 
@@ -92,13 +132,14 @@ skill(name="browse", user_message="--url [URL] --test-ui")
 |--------|---------|---------|
 | delphi code-walkthrough REQUEST_CHANGES | Critical Issues 未修复 | 用户修复 → 重新评审 |
 | test-alignment 失败 | 自动回退 Phase 3/6（不暂停） | 自动迭代 |
-| browse 发现问题 | 自动回退 Phase 3/6（不暂停） | 自动迭代 |
+| 浏览器验证发现问题 | 自动回退 Phase 3/6（不暂停） | 自动迭代 |
 
 ### 输出
 
 - `.code-walkthrough-result.json`（pre-push hook 验证）
+- `.sprint-state/phase-outputs/test-alignment-report.json`（#367 程序化 HARD-GATE 证据）
 - Review Report (`review-report.md`)
-- Web 前端附加: QA report + design-review report + benchmark baseline
+- Web 前端附加: ui-review report + OPTIONAL QA/design-review/benchmark reports
 - 验证通过的 MVP
 
 ---
@@ -107,28 +148,49 @@ skill(name="browse", user_message="--url [URL] --test-ui")
 
 ### 调用 Skills
 
-- `learn` (gstack) — 模式记录（个人级）
-- `retro` (gstack) — 周工程回顾：提交历史、工作模式、代码质量趋势（团队级）
-- `systematic-debugging` (superpowers) _(可选)_ — 根因调试：反馈中的 bug 做根因分析
+**原生**:
+- `learnings.md` 写入 — 模式记录（替代原 gstack `learn`）
+- `xp-gate retro` — 工程回顾：提交历史、工作模式、代码质量趋势、返工率区块
+
+**可选（Layer 4）**:
+- OPTIONAL: 若检测到 `systematic-debugging` skill 已安装 → 根因调试（保留"无根因不修复"纪律）；未安装则使用"根因分析后方可修复"文本纪律
 
 ### 执行步骤
 
-#### Step 1: 调用 learn skill
-```
-skill(name="learn", user_message="[Emergent Issues 内容 + Sprint 总结]")
+#### Step 1: Learnings 写入（原生）
+
+将 Sprint 中发现的模式/教训写入 `.sprint-history/learnings.md`：
+
+```markdown
+## [YYYY-MM-DD] Sprint <id> — VERIFY Learnings
+
+### Pattern: <title>
+- **Context**: <when this applies>
+- **Insight**: <what was learned>
+- **Action**: <how to apply in future>
 ```
 
-#### Step 2: 工程回顾 — 调用 retro
+#### Step 2: 工程回顾 — xp-gate retro（原生）
+
 ```
-skill(name="retro")
+npx xp-gate retro
 ```
-- 提交历史分析、代码质量趋势、团队贡献分解、改进建议
 
-#### Step 3: 根因调试（可选）
+- 提交历史分析、代码质量趋势、改进建议
+- 含 #369 返工率趋势区块
+- 含 --skip-evidence 使用曝光区块
+
+#### Step 3: 根因调试（可选 — Layer 4）
+
 **IF Phase 6/6 CLOSE 发现 bug 或 Part A 验证失败**:
+
 ```
-skill(name="systematic-debugging", user_message="[具体 bug 描述]")
+OPTIONAL: 若检测到 systematic-debugging skill 已安装:
+  skill(name="systematic-debugging", user_message="[具体 bug 描述]")
+ELSE:
+  遵循"无根因不修复"文本纪律 — 先分析根因，确认后再修复
 ```
+
 Iron Law: 无调查 → 不修复
 
 #### Step 4: 转化 Emergent Issues 为 Sprint 2 Pain Document
@@ -158,6 +220,6 @@ Iron Law: 无调查 → 不修复
 ### 输出
 
 - Feedback Log (`feedback-log.md`)
-- Retro Report（retro 输出）
+- Retro Report（`xp-gate retro` 输出）
 - Sprint 2 Pain Document (`sprint2-pain.md`) — 如果有 emergent issues
 - 进入 Phase 5/6 SHIP 自动执行

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

@@ -3,17 +3,15 @@
 **执行时机**: Phase 4/6 VERIFY 完成后、Phase 6/6 CLOSE 之前。
 **对应旧模型**: Phase 5 SHIP + Phase 6 LAND
 
-**摘要**: 结构化分支完成决策, 创建 PR, 合并部署, 监控. 生成 Sprint Summary.
+**摘要**: 结构化分支完成决策（原生 4 选项）, 创建 PR（原生步骤）, 合并部署（原生步骤）, 监控. 生成 Sprint Summary.
 
 ---
 
 ## Part A: SHIP（发布准备）
 
-**完整指令**: @see SKILL.md Phase 5/6 SHIP section.
+**Orchestrator 直接执行**: 分支完成决策和 PR 创建均为交互式步骤（4 选项菜单 + PR 确认），**必须由 orchestrator 直接执行**。
 
-**Orchestrator 直接执行**: `finishing-a-development-branch` 和 `ship` 均为交互式 skill（4 选项菜单 + PR 确认），**必须由 orchestrator 直接调用**。
-
-**关键链**: VERSION-GATE(MANDATORY) → finishing-a-development-branch(4选项) → push PR
+**关键链**: VERSION-GATE(MANDATORY) → 分支完成决策(4选项) → push PR
 
 **HARD-GATE**: Phase 4/6 VERIFY 未完成 → BLOCK。验证 `feedback-log.md` 存在。
 
@@ -29,9 +27,9 @@
     "https://api.github.com/repos/OWNER/REPO/commits/HEAD/status"
   ```
 
-### Step 0: VERSION-GATE（MANDATORY — 在 finishing-a-development-branch 之前执行）
+### Step 0: VERSION-GATE（MANDATORY — 在分支完成决策之前执行）
 
-**Purpose**: Ensure version bump, changelog update, and sync before creating PR. This MUST run BEFORE calling `finishing-a-development-branch` — the skill's "Create PR" option creates the PR immediately, so version changes must be committed first.
+**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**:
 
@@ -65,7 +63,7 @@
    gh pr view <PR_NUMBER> --json state  # 确认 CI 已开始
 ```
 
-**GATE CHECK** (BEFORE proceeding to finishing-a-development-branch):
+**GATE CHECK** (BEFORE proceeding to branch completion decision):
 ```
 [VERSION-GATE] VERSION bump ✓   # VERSION 文件已更新
 [VERSION-GATE] CHANGELOG ✓      # 新版本条目已添加
@@ -74,23 +72,110 @@
 [VERSION-GATE] PR updated ✓     # PR 已包含版本变更 commit
 ```
 
-**⚠️ ANTI-PATTERN**: 先调用 finishing-a-development-branch 创建 PR，再 bump VERSION 会导致 PR 不含版本变更 → CI 不触发 release workflow → 无新版本发布。
+**⚠️ 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（合并 + 部署）
+## Part B: LAND（合并 + 部署 — 原生步骤）
 
-**Orchestrator 直接执行**: `land-and-deploy` 包含 merge 确认和 rollback 决策，**必须由 orchestrator 直接调用** `skill(name="land-and-deploy")`
+**Orchestrator 直接执行**: 合并确认和 rollback 决策均为用户交互点，**必须由 orchestrator 直接执行**。
 
 **输入**: PR URL → 输出: 部署状态 + Canary 报告
 
-**流程**: Merge PR → 等待 CI (10min) → 等待 Deploy (10min) → Canary Health Check (5min)
+### Step 1: Merge 确认
 
-**回滚**: `git revert` 最后一次 merge commit
+```
+⚠️ 确认合并 PR #<number> 到 main?
+
+PR: <PR URL>
+变更: <files changed> 个文件, +<additions>/-<deletions>
+
+确认合并? (yes/no):
+```
+
+### Step 2: 等待 CI
 
-**条件跳过**: 无部署配置时仅 merge + 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 报告
 

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

@@ -204,9 +204,40 @@ git add .sprint-history/<sprint-id>/ && git commit -m "archive: sprint <sprint-i
 
 ---
 
-## Part B: CLEANUP（清理 + 总结）
+## Part B: CLEANUP（清理 + 总结 + 返工追踪）
 
-**摘要**: 自动清理 worktree, 更新 sprint-state.json, 输出 Sprint Summary, 处理 emergent issues.
+**摘要**: 写入 #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 修订：零依赖原则下无可靠数据源）。
 
 ### 执行步骤
 
@@ -217,10 +248,11 @@ git add .sprint-history/<sprint-id>/ && git commit -m "archive: sprint <sprint-i
 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"`
+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. **Sprint Summary**: 使用 `templates/sprint-summary-template.md` 生成总结
-9. **处理 Emergent Issues**: 如 Part A 发现 emergent issues → 触发 Sprint 2 逻辑
+8. **Learnings 写入**（原生）: 将 Sprint 中发现的模式/教训追加到 `.sprint-history/learnings.md`
+9. **Sprint Summary**: 使用 `templates/sprint-summary-template.md` 生成总结
+10. **处理 Emergent Issues**: 如 Part A 发现 emergent issues → 触发 Sprint 2 逻辑
 
 ### 输出