@boyingliu01/xp-gate 0.15.5 → 0.18.1

package/skills/sprint-flow/references/phase-2-design.md

@@ -1,212 +1,212 @@
-# Phase 2/6: DESIGN（设计 — 需求探索 + 共识评审）
+# Phase 2/6: DESIGN（设计 — 需求探索 + 双点评审）
 
 **执行时机**: Phase 1/6 PREP 完成后、Phase 3/6 BUILD 之前。
 **对应旧模型**: Phase 0 THINK + Phase 1 PLAN
 
 ## 目标
 
-使用 brainstorming skill 进行结构化需求探索，输出经用户批准的设计文档。然后通过 autoplan + delphi-review 达成 ≥90% 共识，生成 specification.yaml。
+使用 grill-with-docs 进行结构化需求探索（含 CONTEXT.md/ADR 沉淀），经 R1 需求评审验证需求完整性，输出经用户批准的设计文档。然后通过 batch-grill-me 批量前置决策 + R2 delphi-review 达成 ≥90% 共识，生成 specification.yaml。
+
+**新链（v0.18.0+，零外部依赖，双点评审）**:
+```
+grill-with-docs → R1 需求评审(轻量) → 原生设计文档+APPROVAL门 → batch-grill-me → R2 delphi-review(设计维度) → to-issues
+     ↓                ↓ #368                 ↓ HARD-GATE              ↓              ↓ HARD-GATE
+ CONTEXT.md+ADR   需求完整性/AC覆盖     用户审批设计文档      批量前置决策     ≥90% 共识
+```
 
 ---
 
-## Part A: THINK（需求探索与设计）
+## Part A: THINK（需求探索 + 需求评审）
 
 ### Step 0: CONTEXT.md 预检（v0.14.9+ — Issue #322）
 
-在进入 brainstorming 前，检查 `CONTEXT.md` 是否已存在：
+在进入 grill 访谈前，检查 `CONTEXT.md` 是否已存在：
 
 ```
 IF CONTEXT.md 存在于项目根目录:
   → 读取已有设计上下文
-  → SKIP brainstorming（设计已存在，避免重复探索）
-  → 直接进入 Part B PLAN（使用已有 CONTEXT.md 和设计文档作为输入）
-  → 输出: "[sprint-flow] CONTEXT.md 已存在，跳过需求探索，直接进入共识评审"
+  → SKIP grill-with-docs 访谈（设计上下文已存在，避免重复探索）
+  → ⚠️ R1 需求评审仍执行（Round 1 修订：CONTEXT.md 可能陈旧，快速路径同样需要需求评审）
+  → 评审对象为 CONTEXT.md + 本次需求陈述
+  → 输出: "[sprint-flow] CONTEXT.md 已存在，跳过需求访谈，进入 R1 需求评审"
 ELSE:
   → 继续执行 Step 1（结构化需求探索）
 ```
 
 **CONTEXT.md 预检路由表**:
 
-| CONTEXT.md 状态 | brainstorming | 输入到 Part B | 说明 |
-|----------------|---------------|---------------|------|
-| 不存在 | ✅ 执行 | brainstorming 输出 + autoplan 输出 | 标准路径 |
-| 存在 | ❌ SKIP | 已有 CONTEXT.md + 设计文档 | 快速路径 (Issue #322) |
+| CONTEXT.md 状态 | grill-with-docs | R1 需求评审 | 输入到 Part B | 说明 |
+|----------------|-----------------|-------------|---------------|------|
+| 不存在 | ✅ 执行 | ✅ 执行 | grill 输出 + R1 结论 | 标准路径 |
+| 存在 | ❌ SKIP | ✅ 执行 | 已有 CONTEXT.md + R1 结论 | 快速路径 (Issue #322) |
+
+### Step 1: 调用 grill-with-docs（需求访谈）
 
-### 调用 Skills
+**仅当 CONTEXT.md 不存在时执行。**
+
+```
+skill(name="grill-with-docs", user_message="[需求描述]")
+```
 
-- `brainstorming` (superpowers) — **HARD-GATE**: 设计未批准 → 不可进入实现
-- 可选补充：`office-hours` (gstack) — 当用户需求非常模糊、需要先验证产品方向时
+grill-with-docs 执行：
+1. **逐个追问决策树** — 每题附推荐答案；事实自行探查，决策留给用户
+2. **同步维护 CONTEXT.md** — 项目上下文沉淀（`domain-modeling` 内置）
+3. **同步维护 ADR** — `docs/adr/ADR-NNNN-*.md` 架构决策记录
+4. **达成共享理解** — 需求边界、用户场景、验收标准清晰化
 
-**关键变更（ISSUE30）**: 从 `office-hours` 切换到 `brainstorming`，原因:
-- brainstorming 有 **HARD-GATE**（设计未批准 → 不可进入实现），防止 "觉得已经理解了就直接开始写代码"
-- brainstorming 输出结构化设计文档，可直接作为 Phase 2/6 Part B PLAN 的输入
-- office-hours 的 YC 六问适合新产品方向验证，brainstorming 更适合"具体功能实现前设计"的场景
+### Step 2: R1 需求评审（#368 恢复的第一点评审）
 
-### HARD-GATE 机制
+grill 访谈达成共享理解后（或 CONTEXT.md 快速路径下读取已有上下文后）、设计文档生成前，调用需求评审：
 
 ```
-DO NOT enter Part B (PLAN) or do any implementation
-until the brainstorming design has been APPROVED by the user.
+npx xp-gate delphi-review --mode requirements
 ```
 
-brainstorming skill 内部会执行：
+**评审配置**（轻量）：
+- 复用现有 3 专家（architecture/feasibility/technical），`--mode requirements` 切换评审焦点提示词
+- 轻量配置：2 专家、1 轮
+- lightweight sprint（`change_type == "修改已存在代码"`）：跳过 R1，需求评审合并入 R2
+
+**评审焦点**：
+- 用户场景遗漏
+- 验收标准覆盖度与可测试性
+- 用户画像清晰度
+- 需求边界
+
+**阻塞语义（程序化）**：
+
+输出 `.sprint-state/phase-outputs/requirements-reviewed.json`：
+
+```json
+{
+  "verdict": "APPROVED | GAPS_FOUND",
+  "timestamp": "<ISO 8601>",
+  "requirements_hash": "<SHA-256 of 需求陈述 + CONTEXT.md 内容>",
+  "experts": 2,
+  "rounds": 1,
+  "gaps": []
+}
+```
 
-1. **Explore project context** — 检查文件、文档、最近 commits
-2. **Ask clarifying questions** — 一次一个，理解目的/约束/成功标准
-3. **Propose approaches** — 2-3 个方案，含 trade-offs 和建议
-4. **Present design** — 分节展示，每节获得用户批准
-5. **Write design doc** — 保存到 `docs/plans/YYYY-MM-DD-<topic>-design.md`
-6. **Transition to implementation** — brainstorming 自动调用 writing-plans
+**GAPS_FOUND 处理**：
+- 回到 Step 1 补充访谈（或补充 CONTEXT.md 内容）
+- 最多 2 轮循环后升级给用户决策
 
-**sprint-flow 编排层行为**:
-- 收到 brainstorming APPROVED 设计文档后，自动进入 Part B
-- 如果 brainstorming 未完成（用户未 APPROVED），BLOCK 并等待
+**程序化校验**：
+- `phase-transition 2 completed` 校验该文件存在、`verdict=APPROVED` 且 `requirements_hash` 匹配当前需求内容
+- 不匹配 → BLOCK（防陈旧绑定）
 
-### 执行步骤
+### Step 3: 原生设计文档生成
 
-#### Step 1: 调用 brainstorming skill
+orchestrator 基于访谈记录 + CONTEXT.md + R1 评审结论生成设计文档：
 
-```
-skill(name="brainstorming", user_message="[需求描述]")
-```
+**路径**: `docs/plans/YYYY-MM-DD-<topic>-design.md`
+
+**内容结构**:
+1. 需求摘要（来自 grill 访谈 + R1 评审结论）
+2. 2–3 候选方案与 trade-offs
+3. 推荐方案
+4. 成功标准
 
-#### Step 2: 等待 HARD-GATE APPROVED
+### Step 4: HARD-GATE — 用户审批设计文档
 
 ```
 ⚠️ HARD-GATE: 设计未 APPROVED → 不可进入 Part B
 
-等待用户审批 brainstorming 输出的设计文档。
+等待用户审批设计文档。
+用户 APPROVE 前，禁止进入 Part B (PLAN) 或任何实现。
 ```
 
-#### Step 3: 保存设计文档路径
-
-保存到 `<project-root>/.sprint-state/phase-outputs/design-doc.md`
-
-### 可选补充: office-hours（方向验证）
-
-当用户输入非常模糊时（如 "我想做一个 AI 工具" 而不是 "开发用户登录功能"），可以先调用 `office-hours` 验证产品方向，再进入 brainstorming 详细设计。
+**sprint-flow 编排层行为**:
+- 收到用户 APPROVED 后，自动进入 Part B
+- 如果用户未 APPROVED，BLOCK 并等待
 
 ### 暂停点
 
 | 暂停点 | 触发条件 | 用户操作 | 自动恢复条件 |
 |--------|---------|---------|-------------|
-| **HARD-GATE** | brainstorming 设计未 APPROVED | 用户审批设计文档 | 设计 APPROVED 后自动进入 Part B |
+| R1 GAPS_FOUND | 需求评审发现缺口 | 补充访谈/上下文 | 重新 R1 评审（最多 2 轮） |
+| **HARD-GATE** | 设计文档未 APPROVED | 用户审批设计文档 | 设计 APPROVED 后自动进入 Part B |
 
 ### 输出
 
-- Design Document (`docs/plans/YYYY-MM-DD-<topic>-design.md`)
-- Implementation Plan（brainstorming 内部 writing-plans 输出）
+- CONTEXT.md（项目上下文沉淀）
+- ADR 文件（`docs/adr/ADR-NNNN-*.md`）
+- requirements-reviewed.json（`.sprint-state/phase-outputs/`）
+- Design Document（`docs/plans/YYYY-MM-DD-<topic>-design.md`）
 - 进入 Part B 自动执行（使用设计文档作为输入）
 
 ---
 
 ## Part B: PLAN（共识评审）
 
-### 调用 Skills
-
-- `autoplan` (gstack) — CEO → Design → Eng 自动流水线
-- `delphi-review` — 多轮匿名评审直到共识
-- specification.yaml 从 APPROVED 设计文档自动生成（无需独立 skill）
-
-**Web 前端项目额外注入**:
-- `design-shotgun` (gstack) — 生成多版 UI 设计变体
-
-**Mobile 项目额外注入** (`--type mobile-flutter` / `mobile-react-native`):
-- `design-shotgun` (gstack) — 移动端 UI 设计探索
-
-### 执行步骤
-
-#### Step 0: Web 前端项目 — 调用 design-shotgun（如适用）
-
-**IF project_type is web-nextjs / web-react / web-vue / mobile-flutter / mobile-react-native:**
-```
-skill(name="design-shotgun", user_message="[Pain Document 内容 + 需求描述]")
-```
-
-#### Step 0.5: DESIGN 路由分叉（v0.14.0+ — Issue #306, #322）
+### Step 5: 路由分叉（v0.14.0+ — Issue #306, #322）
 
-根据 Phase 1/6 PREP (AUTO-ESTIMATE) 的 `change_type` 以及 Part A 的 CONTEXT.md 预检结果，决定走哪条路径：
+根据 Phase 1/6 PREP (AUTO-ESTIMATE) 的 `change_type` 决定路径：
 
 ```
 读取 .sprint-state/sprint-state.json → auto_estimate.change_type
-读取 CONTEXT.md 存在状态
-
-IF CONTEXT.md 存在（Part A Step 0 预检结果）:
-  → 快速路径: SKIP brainstorming, 使用已有 CONTEXT.md + 设计文档
-  → 直接进入 autoplan (标准) 或 delphi-review (增量)
-ELSE IF change_type == "修改已存在代码":
-  → 增量优化路径: SKIP autoplan
-  → 直接进入 Step 2b: delphi-review (lightweight: 2 专家, 1 轮)
+
+IF change_type == "修改已存在代码":
+  → 增量优化路径: SKIP batch-grill-me
+  → 直接进入 Step 7: lightweight R2 delphi-review (2 专家, 1 轮)
 ELSE (change_type == "新增功能" 或 未定义):
-  → 标准路径: 继续 Step 1 (autoplan) → Step 2
+  → 标准路径: 继续 Step 6 (batch-grill-me) → Step 7
 ```
 
 **路由决策表**:
 
-| CONTEXT.md | change_type | brainstorming | autoplan | delphi-review |
-|-----------|------------|---------------|----------|---------------|
-| 存在 | 任意 | ❌ SKIP | ✅ 执行 (标准) | 标准 (3 专家) |
-| 不存在 | `修改已存在代码` | ✅ 执行 | ❌ SKIP | lightweight (2 专家, 1 轮) |
-| 不存在 | `新增功能` | ✅ 执行 | ✅ 执行 | 标准 (3 专家) |
-| 不存在 | `undefined` / 缺失 | ✅ 执行 | ✅ 执行 | 标准 (3 专家) |
+| change_type | batch-grill-me | R2 delphi-review |
+|------------|----------------|------------------|
+| `修改已存在代码` | ❌ SKIP | lightweight (2 专家, 1 轮) |
+| `新增功能` | ✅ 执行 | 标准 (3 专家) |
+| `undefined` / 缺失 | ✅ 执行 | 标准 (3 专家) |
 
 **HARD-GATE 不变**: 两条路径最终都必须产出 APPROVED 的 delphi-reviewed.json。
 
-#### Step 1: 调用 autoplan skill（仅标准路径）
+### Step 6: 调用 batch-grill-me（仅标准路径）
 
 **仅当 change_type != "修改已存在代码" 时执行。**
 
 ```
-skill(name="autoplan", user_message="[Pain Document 内容]")
+skill(name="batch-grill-me", user_message="[设计文档 + 待确认决策列表]")
 ```
 
-autoplan 自动执行 `plan-ceo-review` → `plan-design-review` → `plan-eng-review`，使用 6 个决策原则自动决策：
-
-```yaml
-autoplan_result:
-  taste_decisions: [] | [decision1, decision2, ...]
-  verdict: "AUTO_APPROVED" | "NEEDS_REVIEW"
-```
+batch-grill-me 替代 autoplan 的 taste_decisions 功能：
+- 前置已确定决策整批提出
+- 用户一轮确认
+- 输出批量决策结果
 
-#### Step 2: 条件分支
+### Step 7: R2 设计评审（delphi-review，原生 HARD-GATE）
 
 ```
-┌───────────────────────────────────────────────────────────────────┐
-│ Phase 2/6: 条件分支逻辑                                            │
-├───────────────────────────────────────────────────────────────────┤
-│ IF autoplan_result.verdict == "AUTO_APPROVED"                      │
-│    AND autoplan_result.taste_decisions == []                       │
-│  → 调用 lightweight delphi-review（2 专家、1 轮、2/2 APPROVED）     │
-│                                                                    │
-│ IF autoplan_result.verdict == "NEEDS_REVIEW"                       │
-│    OR autoplan_result.taste_decisions.length > 0                   │
-│  → ⚠️ 暂停等待用户确认 taste_decisions                             │
-│  → 用户确认后，调用标准 delphi-review（3 专家）                     │
-└───────────────────────────────────────────────────────────────────┘
+# 标准路径（3 专家）
+skill(name="delphi-review", user_message="[设计文档 + batch-grill-me 决策结果]")
+
+# 增量优化路径（2 专家, 1 轮 — 来自 Step 5 路由）
+skill(name="delphi-review", user_message="[设计文档]", experts=2, max_rounds=1)
 ```
 
-#### Step 2a: 如果需要用户确认 taste_decisions
+- **标准路径**: Round 1: 3 专家匿名独立评审 → Round 2+: 交换意见直到共识
+- **增量优化路径**: 2 专家, 1 轮
+- ≥90% 共识 + APPROVED 才通过
+- 输出: APPROVED / REQUEST_CHANGES
 
-暂停并提示用户决策选项。
+**如果 REQUEST_CHANGES**: 暂停等待用户处理 → 修复后重新评审 → 直到 APPROVED
 
-#### Step 2b: 调用 delphi-review（强制，orchestrator 直接执行）
+### Step 8: 调用 to-issues（原生保留）
 
 ```
-# 标准路径（3 专家）
-skill(name="delphi-review", user_message="[设计文档 + taste_decisions 确认结果]")
-
-# 增量优化路径（2 专家, 1 轮 — 来自 Step 0.5 路由）
-skill(name="delphi-review", user_message="[设计文档]", experts=2, max_rounds=1)
+skill(name="to-issues")
 ```
 
-- **标准路径**: Round 1: 3 专家匿名独立评审
-- **增量优化路径**: 2 专家, 1 轮 (来自 Step 0.5 DESIGN 路由分叉)
-- Round 2+: 交换意见直到共识
-- 输出: APPROVED / REQUEST_CHANGES
+垂直切片 Issue 拆分 → `slices-manifest.json`（格式不变，ralph-loop 零改动）
 
-**如果 REQUEST_CHANGES**: 暂停等待用户处理 → 修复后重新评审 → 直到 APPROVED
+to-issues 原生能力：blocked_by/dependency_graph/DAG 循环检测/拓扑排序 → Phase 3/6 BUILD 按 execution_order 执行
+
+### Step 9: 生成 specification.yaml
 
-#### Step 3: 从 APPROVED 设计文档提取 specification.yaml
+从 APPROVED 设计文档提取：
 
 ```yaml
 specification:
@@ -217,7 +217,7 @@ specification:
   acceptance_criteria:
     - id: AC-001
       requirement: REQ-001
-      criteria: [验收标准]
+      criteria: [验收标准]    # #368: 每个 REQ 必须含清晰验收标准
       test_type: [unit/integration/e2e]
   design_decisions:
     - id: DD-001
@@ -226,26 +226,38 @@ specification:
       alternatives_considered: [备选方案]
 ```
 
-#### Step 4: 调用 to-issues
+### Step 10: 保存产出物
 
-```
-skill(name="to-issues")
-```
-垂直切片 Issue 拆分 → `slices-manifest.json` → Phase 3/6 BUILD 按 execution_order 执行
+保存到 `<project-root>/.sprint-state/phase-outputs/`:
+- `specification.yaml`
+- `slices-manifest.json`（to-issues 输出）
 
-#### Step 5: 保存 specification.yaml
+### Web 前端项目额外注入
 
-保存到 `<project-root>/.sprint-state/phase-outputs/specification.yaml`
+**IF project_type is web-nextjs / web-react / web-vue / mobile-flutter / mobile-react-native:**
+
+OPTIONAL: 若检测到 `design-shotgun` skill 已安装，可生成多版 UI 设计变体辅助设计评审。未安装则 SKIP。
 
 ### 暂停点
 
 | 暂停点 | 触发条件 | 用户操作 |
 |--------|---------|---------|
-| taste_decisions 确认 | autoplan 无法自动决策 | 用户确认每个决策 |
-| delphi-review APPROVED | Round 结果 REQUEST_CHANGES | 用户修复并重新评审 |
+| batch-grill-me 决策确认 | 批量决策需要用户确认 | 用户一轮确认所有决策 |
+| R2 delphi-review APPROVED | Round 结果 REQUEST_CHANGES | 用户修复并重新评审 |
 
 ### 输出
 
-- specification.yaml
+- specification.yaml（每 REQ 含验收标准 — #368）
 - slices-manifest.json
 - 进入 Phase 3/6 BUILD（除非 `--stop-at design`）
+
+---
+
+## 证据文件汇总
+
+| 证据文件 | 路径 | 校验时机 | 防陈旧绑定 |
+|----------|------|----------|-----------|
+| requirements-reviewed.json | `.sprint-state/phase-outputs/` | `phase-transition 2 completed` | `requirements_hash`（SHA-256） |
+| delphi-reviewed.json | `.sprint-state/` | DELPHI-GATE (Phase 2→3) | verdict + timestamp |
+| specification.yaml | `.sprint-state/phase-outputs/` | `phase-transition 3 in_progress` | slice↔REQ 一致性 |
+| slices-manifest.json | `.sprint-state/phase-outputs/` | `phase-transition 3 in_progress` | schema + REQ 引用校验 |

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

@@ -6,7 +6,7 @@
 
 **摘要**: TDD 执行, 多 Agent 并行加速, 盲评验证, Gate 1 验证通过。
 
-**关键链路**: DELPHI-GATE → parallel-dispatch/ralph-loop → TDD → freeze → blind-review → unfreeze → verification → cost monitor
+**关键链路**: BUILD-ENTRY-CONTRACT → DELPHI-GATE → parallel-dispatch/ralph-loop → TDD → blind-review (read-only subagent) → verification → cost monitor
 
 **输出**: MVP v1
 
@@ -22,6 +22,27 @@
 
 ---
 
+## BUILD Entry Contract Check (MANDATORY — v0.18.0+, 程序化)
+
+**Purpose**: Validate `slices-manifest.json` schema and slice↔REQ cross-artifact consistency before entering BUILD.
+
+**Execution**: `phase-transition 3 in_progress` 时程序化校验：
+
+```
+1. slices-manifest.json 存在且 schema 合法
+2. manifest 每个 slice 引用的 REQ 必须存在于 specification.yaml
+3. 不合法 → BLOCK
+```
+
+**GATE CHECK**:
+```
+[BUILD-ENTRY] slices-manifest.json exists ✓
+[BUILD-ENTRY] manifest schema valid ✓
+[BUILD-ENTRY] slice↔REQ consistency ✓    # 每个 slice 的 REQ 引用在 specification.yaml 中存在
+```
+
+**IF GATE FAILS**: BLOCK — 返回 Phase 2/6 修复 manifest 或 specification.yaml。
+
 ---
 
 ## Uncommitted Changes Gate
@@ -215,6 +236,52 @@ Without these events, the Harness can only infer changes from file diffs and has
 
 ---
 
+## Blind Review — Read-Only Subagent Convention (v0.18.0+, 证据型标准步骤)
+
+**Purpose**: Code review by an isolated subagent with read-only tool access. Replaces the former `freeze/unfreeze` mechanism.
+
+**Convention**: The blind-review reviewer runs as a Task subagent with restricted tools:
+
+```
+tools: [Read, Grep, Glob]    # 只读 — 禁止 Write/Edit/Bash 写操作
+```
+
+**Execution**:
+1. Orchestrator dispatches a Task subagent with `tools: [Read, Grep, Glob]`
+2. Subagent reviews all changed files (from `git diff` or slices-manifest scope)
+3. Subagent outputs review findings (issues, suggestions, risks)
+4. Orchestrator records findings to `.sprint-state/phase-outputs/blind-review-report.md`
+
+**Classification**: 证据型标准步骤（非 HARD-GATE）— 执行并留存评审记录，不设程序化阻断。Worktree 本身已是隔离边界。
+
+**Anti-Pattern**: Reviewer subagent MUST NOT have Write, Edit, or Bash permissions. This ensures the review is truly read-only and cannot accidentally modify code under review.
+
+---
+
+## Learnings Capture (v0.18.0+, 原生)
+
+**Purpose**: Record patterns and lessons learned during BUILD for future sprints.
+
+**Execution**: ralph-loop 迭代中或 BUILD 完成后，将有价值的模式/教训写入：
+
+```
+.sprint-history/learnings.md
+```
+
+**Format**:
+```markdown
+## [YYYY-MM-DD] Sprint <id> — BUILD Learnings
+
+### Pattern: <title>
+- **Context**: <when this applies>
+- **Insight**: <what was learned>
+- **Action**: <how to apply in future>
+```
+
+**Note**: 替代原 `gstack/learn` 调用，纯原生文件写入，零外部依赖。
+
+---
+
 ## TDD 强制执行
 
 ### Gate 5a-BLOCK: 新增文件测试强制
@@ -249,7 +316,7 @@ SKIP_GATE_5A_BLOCK=1 git commit -m "message"
 | ralph-loop (per REQ) | TDD + verification per requirement | 5-15 min | 30 min/REQ | Mark REQ as `timeout`, continue next REQ |
 | parallel dispatch | Multi-agent parallel build | 10-30 min | 45 min | Collect partial results, continue |
 | TDD cycle (per unit) | RED → GREEN → REFACTOR | 2-5 min | 10 min | Skip unit, log failure |
-| freeze + blind-review | Code review in isolation | 5-10 min | 20 min | WARNING, continue |
+| blind-review (read-only subagent) | Code review via read-only subagent | 5-10 min | 20 min | WARNING, continue |
 | verification | Test suite + coverage check | 2-5 min | 15 min | Retry once, then BLOCK |
 | cost monitor | Token cost accounting | <1s | 5s | Skip, log warning |
 | Phase 3/6 total (lightweight) | ≤3 REQs | 15-30 min | 45 min | — |