@boyingliu01/xp-gate 0.19.2 → 0.20.0

package/plugins/qoder/skills/delphi-review/hooks.md

@@ -0,0 +1,19 @@
+# Hooks — Delphi Review
+
+Delphi Review integrates with safety and operational hooks to ensure review integrity
+and context preservation.
+
+## Security Hooks
+
+| Hook | Purpose | Activation |
+|------|---------|------------|
+| `/careful` | Safety guardrails for destructive commands | Ensure review is read-only — block any destructive operations |
+| `/freeze` | Restrict edits to review scope | Prevent accidental changes during review |
+| `/guard` | Full safety mode (careful + freeze) | Maximum protection — read-only review with no accidental edits |
+
+## Operational Hooks
+
+| Hook | Purpose | Activation |
+|------|---------|------------|
+| `/context-save` | Save review context before pause or handoff | Before pausing review or switching tasks |
+| `/context-restore` | Restore review context on resume | When resuming review from pause or handoff |

package/plugins/qoder/skills/delphi-review/opencode.json.delphi.example

@@ -3,23 +3,19 @@
     "Delphi Review Agent Configuration Template",
     "===========================================",
     "Copy the relevant 'agent' block below into your opencode.json.",
-    "Replace YOUR_PROVIDER/YOUR_MODEL with your actual provider and model names.",
-    "All 3 agents must use distinct trimmed executable model IDs; providers may be shared."
+    "Replace the example model IDs with three callable IDs available through your configured provider.",
+    "The three model fields must be different after trimming; providers may be shared."
   ],
 
   "$example_providers": {
-    "OpenAI": "openai/gpt-4o",
-    "Anthropic": "anthropic/claude-sonnet-4-20250514",
-    "Ali_Bailian": "bailian-coding-plan/qwen3.6-plus",
-    "Google_Gemini": "google/gemini-2.5-pro",
-    "DeepSeek": "deepseek/deepseek-chat"
+    "SharedProviderExample": "bailian-tp/qwen-plus"
   },
 
   "agent": {
     "delphi-reviewer-architecture": {
       "description": "Delphi expert reviewer for architecture perspective. Focuses on requirements alignment, system design, and high-level coherence.",
       "mode": "subagent",
-      "model": "YOUR_PROVIDER/YOUR_MODEL_A",
+      "model": "bailian-tp/qwen-plus",
       "prompt": "You are a Delphi expert reviewer specializing in architecture and requirements alignment. Review the input for: 1) Alignment with stated goals 2) Architectural coherence 3) System-level implications 4) Trade-offs and alternatives. Output structured review with verdict (APPROVED/REQUEST_CHANGES/REJECTED) and confidence level.",
       "tools": {
         "read": true,
@@ -31,7 +27,7 @@
     "delphi-reviewer-technical": {
       "description": "Delphi expert reviewer for technical depth. Focuses on implementation details, code correctness, and edge cases. Used in delphi-review.",
       "mode": "subagent",
-      "model": "YOUR_PROVIDER/YOUR_MODEL_B",
+      "model": "bailian-tp/deepseek-v3",
       "prompt": "You are a Delphi expert reviewer specializing in technical implementation. Review the input for: 1) Implementation correctness 2) Code quality and patterns 3) Edge cases and error handling 4) Performance implications. Output structured review with verdict (APPROVED/REQUEST_CHANGES/REJECTED) and confidence level.",
       "tools": {
         "read": true,
@@ -43,7 +39,7 @@
     "delphi-reviewer-feasibility": {
       "description": "Delphi expert reviewer for feasibility analysis. Focuses on practical constraints, risks, and execution viability. Used in delphi-review.",
       "mode": "subagent",
-      "model": "YOUR_PROVIDER/YOUR_MODEL_C",
+      "model": "bailian-tp/glm-4.5",
       "prompt": "You are a Delphi expert reviewer specializing in feasibility and risk analysis. Review the input for: 1) Practical constraints (time, resources, dependencies) 2) Risk identification and mitigation 3) Execution complexity 4) Alternative approaches. Output structured review with verdict (APPROVED/REQUEST_CHANGES/REJECTED) and confidence level.",
       "tools": {
         "read": true,

package/plugins/qoder/skills/delphi-review/references/code-walkthrough.md

@@ -255,9 +255,15 @@ pre-push hook
 |------|------|------|
 | 单次走查成本 | ~$0.03 | 正常执行 |
 | 变更规模 | 无硬性文件数或行数上限 | 大型变更必须完整评审或由用户选择拆分 |
+| 单席位 prompt 体积 | 默认 40000 字节（`max_prompt_bytes` 可按席位覆盖） | runner 发送前拒绝，报错里给出处置办法 |
 
 大型变更没有自动跳过或绕过路径。用户可以选择完整评审，或在评审前主动拆分变更；每个变更仍须通过完整的走查和证据验证。
 
+**prompt 预算是硬约束，不是建议**：实测 `g-glm-5.3-flash` 在 ~40KB 正常应答（225s）、~50KB 直接崩溃
+（305s，`0xC0000409` + libuv `UV_HANDLE_CLOSING`，表现为 "Network error."）——一个席位崩溃就会让整个共识无法完成。
+构造输入时按重要性排序、给每个席位独立预算、并在报告里显式列出因体积省略的文件；
+截断到「核心 hunk 看不见」比超限更糟：席位会花整轮报告「无法审计」，而这是评审者的真实缺陷而非代码缺陷。
+
 ---
 
 ## Agent 可用性检查 (MANDATORY)
@@ -356,9 +362,9 @@ IF 任何检查失败:
   "verdict": "APPROVED",
   "confidence": 9,
   "experts": [
-    { "id": "Expert A", "role": "architecture", "verdict": "APPROVED", "confidence": 9, "result_type": "delphi_expert_result", "requested_model": "provider/model-a", "resolved_model": "provider/model-a" },
-    { "id": "Expert B", "role": "technical", "verdict": "APPROVED", "confidence": 8, "result_type": "delphi_expert_result", "requested_model": "provider/model-b", "resolved_model": null },
-    { "id": "Expert C", "role": "feasibility", "verdict": "APPROVED", "confidence": 8, "result_type": "delphi_expert_result", "requested_model": "provider/model-c", "resolved_model": "provider/model-c" }
+    { "id": "Expert A", "role": "architecture", "verdict": "APPROVED", "confidence": 9, "result_type": "delphi_expert_result", "requested_model": "provider/model-a", "resolved_model": "provider/model-a", "channel": "external" },
+    { "id": "Expert B", "role": "technical", "verdict": "APPROVED", "confidence": 8, "result_type": "delphi_expert_result", "requested_model": "provider/model-b", "resolved_model": "provider/model-b", "channel": "external" },
+    { "id": "Expert C", "role": "feasibility", "verdict": "APPROVED", "confidence": 8, "result_type": "delphi_expert_result", "requested_model": "provider/model-c", "resolved_model": "provider/model-c", "channel": "external" }
   ],
   "issues": [],
   "consensus_ratio": 1.0,
@@ -399,6 +405,33 @@ Hook 验证以下条件（全部满足才允许 push）：
 5. timestamp 未过期
 6. expires 必须是 timestamp 之后恰好 1 小时
 
+### experts[] 必填字段与 #423 的迁移说明
+
+`validate-code-walkthrough.cjs` 对每个 expert 对象强制要求：
+
+| 字段 | 约束 |
+|------|------|
+| `result_type` | 必须等于 `"delphi_expert_result"` |
+| `role` | 非空，三个席位 role 互异 |
+| `requested_model` | 非空；比较前只做 trim，**区分大小写**（规范原文是 "distinct trimmed requested model IDs"，见 AGENTS.md） |
+| `resolved_model` | 非空；比较前 trim + 转小写，三者互异 |
+| `channel` | 必须严格属于 `["external", "local"]`；`provider: local` 的 fallback 记录不能计为成功执行 |
+
+缺字段或取值不在白名单 → Gate MW **FAIL**（不是 SKIP）。
+
+**升级后旧证据怎么处置**：唯一正确做法是在当前 HEAD 重跑一次评审、由 runner 重新生成证据文件。
+不要手工给老文件补 `channel` —— 那等于伪造执行证据，而 `channel` 存在的目的正是让证据可追溯到一次真实调用。
+证据本来就与 commit 绑定（`commit` 必须等于 HEAD，有效期 1 小时），跨 commit 复用从来不是受支持的路径。
+
+**回滚语义**：validator 与证据生产者（`scripts/delphi-external-review.cjs`）必须成对回滚。
+
+- 旧 validator 读新证据：安全，多余字段被忽略。
+- 新 validator 读旧证据：必然 FAIL（缺 `channel`）。这是设计意图——宁可在发布关口停下，
+  也不放行一份无法证明模型来源的证据；把「三个不同模型真的跑过」降级为可选项，等于让门禁只剩形式。
+- 临时降级开关：**没有**。既没有 `XP_GATE_SKIP_MW` 之类的环境变量，也不允许 `--no-verify`
+  （见 `githooks/QUALITY-GATES-CODE-OF-CONDUCT.md`）。如果评审确实无法完成，处理方式是缩小
+  `--range` 或按席位调整 prompt 预算重跑，而不是放行。
+
 ---
 
 ## 与现有系统集成

package/plugins/qoder/skills/delphi-review/references/orchestrator-dispatch.md

@@ -0,0 +1,64 @@
+# Orchestrator Dispatch Rules（#218 自动多轮调度）
+
+## 背景
+
+Delphi review 在 sprint-flow 中通过 subagent 调用时，Round 1→Round 2→Round 3 的调度**必须在 subagent 内部自动完成**，不能每轮暂停等待 orchestrator 或用户干预。只有在以下情况才需要 orchestrator 暂停：
+
+## 自动调度规则
+
+| 场景 | 自动处理 | 需暂停 |
+|------|---------|--------|
+| Round 1 完成，需 Round 2 | ✅ subagent 自动继续 | ❌ |
+| Round 2 完成，需 Round 3 | ✅ subagent 自动继续 | ❌ |
+| Round 3+ 完成，仍需更多轮 | ✅ subagent 自动继续，直到 max_rounds | ❌ |
+| 最终 APPROVED (>=90%) | ✅ subagent 输出结果后退出 | ❌ |
+| 最终 REQUEST_CHANGES（可自动修复） | ✅ subagent 尝试修复措辞、AC 缺失等常见问题后自动重评审 | ❌ |
+| 最终 REQUEST_CHANGES（无法自动修复） | ✅ subagent 输出详细失败报告 | **✅ orchestrator 暂停等用户** |
+| 超过 max_rounds (5) 仍无共识 | ✅ subagent 输出"未达成共识报告" | **✅ orchestrator 暂停等用户决策** |
+
+## Subagent 内部 Round 循环
+
+当 delphi-review 以 subagent 启动时（非交互式），应执行以下自动循环：
+
+```python
+round = 1
+while round <= max_review_rounds:
+    results = execute_round(round)
+    consensus = check_consensus(results)
+
+    if consensus.verdict == "APPROVED" and consensus.ratio >= 0.9:
+        emit_verdict("APPROVED", consensus)
+        break
+
+    if round == max_review_rounds:
+        emit_verdict("NO_CONSENSUS", consensus)
+        break
+
+    round += 1
+
+if verdict == "REQUEST_CHANGES":
+    auto_fix_result = attempt_auto_fix(issues)
+    if auto_fix_result.success:
+        round = 2
+        continue
+    else:
+        emit_verdict("REQUEST_CHANGES", auto_fix_result.failed_issues)
+```
+
+## 终止结果输出
+
+当 subagent 因终态退出时，必须输出清晰的裁决：
+
+- **APPROVED**: 共识报告 + specification.yaml
+- **REQUEST_CHANGES（可自动修复）**: 自动修复后再次评审
+- **REQUEST_CHANGES（不可自动修复）**: 失败报告 + 建议修复方向
+- **NO_CONSENSUS**: 分歧详情报告
+
+## 与 orchestrator 的交互约定
+
+| 状态 | Subagent 输出 | Orchestrator 动作 |
+|------|--------------|------------------|
+| APPROVED | `{verdict:"APPROVED", consensus_ratio: N, ...}` | 自动进入下一 Phase |
+| REQUEST_CHANGES (auto-fixed) | `{verdict:"APPROVED", auto_fixed: ["..."]}` | 自动进入下一 Phase |
+| REQUEST_CHANGES (unfixable) | `{verdict:"REQUEST_CHANGES", failed_issues: [...]}` | ⚠️ 暂停等用户修复后，通过 task_id 重新 dispatch |
+| NO_CONSENSUS | `{verdict:"NO_CONSENSUS", disagreements: [...]}` | ⚠️ 暂停等用户决策（可继续/中止/强制通过） |

package/plugins/qoder/skills/delphi-review/references/requirements.md

@@ -0,0 +1,402 @@
+# Requirements Mode Reference
+
+> Extracted from `SKILL.md`. This file contains ALL content specific to the `requirements` mode of Delphi Review.
+
+---
+
+## Overview
+
+需求评审模式，用于 grill-with-docs 完成共享理解后、设计文档生成前，对需求完整性进行轻量级多专家 Delphi 评审。
+
+**触发命令**: `/delphi-review --mode requirements`
+
+**设计背景**: Issue #368 识别出原始意图中"需求评审一次 + 设计评审一次"的第一次评审被完全丢弃。本模式恢复该评审点，在需求探索（grill-with-docs）与设计文档生成之间插入一道轻量质量门禁。
+
+**定位**:
+- **固定三专家**: architecture + technical + feasibility，最多 5 轮
+- **需求焦点**: 评审对象是需求陈述 + CONTEXT.md，不是设计文档或代码
+- **程序化阻塞**: 输出 `requirements-reviewed.json`，由 `phase-transition 2 completed` 校验
+- **防陈旧绑定**: `requirements_hash`（SHA-256）绑定需求内容，防止旧证据复用
+
+---
+
+## Five Core Properties
+
+1. **匿名性** — Expert A/B/C 互不知道对方意见（Round 1）
+2. **迭代共识** — GAPS_FOUND 时回到 grill-with-docs 补充，最多 5 轮循环
+3. **关键缺口零容忍** — Critical requirement gaps 必须在进入设计前解决
+4. **防陈旧绑定** — requirements_hash 绑定需求内容 + CONTEXT.md，旧证据不可复用
+5. **执行可验证** — 三个专家都必须成功返回结构化结果，且 requested_model 三个 distinct
+
+---
+
+## 触发条件
+
+- **自动触发**: sprint-flow Phase 2 THINK 链中，grill-with-docs 完成后、设计文档生成前（参见 `skills/sprint-flow/references/phase-2-design.md` Step 2）
+- **手动触发**: `/delphi-review --mode requirements`
+
+**⚠️ 重要调用方式说明**:
+
+- ✅ **正确**: sprint-flow 编排层在 Phase 2 Step 2 自动调用
+- ✅ **正确**: 在 Agent session 中执行 `/delphi-review --mode requirements`
+- ❌ **错误**: 在设计文档已生成后调用（应在设计前）
+- ❌ **错误**: 用 requirements 模式评审设计文档或代码（那是 design / code-walkthrough 模式的职责）
+
+**与 sprint-flow 的集成**:
+
+```
+sprint-flow Phase 2 THINK:
+  Step 0: CONTEXT.md 预检
+  Step 1: grill-with-docs（需求访谈）
+  Step 2: delphi-review --mode requirements  ← 本模式
+  Step 3: 原生设计文档生成
+  Step 4: HARD-GATE（用户审批设计文档）
+```
+
+所有 Sprint 路径都执行 R1。Force level 只调整上下文深度和后续迭代预算，不跳过需求评审，也不减少三位专家执行。
+
+---
+
+## 流程概览
+
+```
+grill-with-docs (completed)
+    │
+    ▼
+delphi-review --mode requirements
+    │
+    ├─→ Context gather: CONTEXT.md + grill session summary + user requirements statement
+    │
+    ├─→ Expert A (architecture) anonymous review — focus: requirements completeness,
+    │                                              requirement→AC coverage, scenario coverage
+    │
+   ├─→ Expert B (technical) anonymous review — focus: technical clarity and edge cases
+   │
+   ├─→ Expert C (feasibility) anonymous review — focus: testability of acceptance criteria,
+    │                                              user persona clarity, scope boundaries
+    │
+    ├─→ Consensus check
+    │      │
+    │      ├─→ All three APPROVED → write requirements-reviewed.json verdict=APPROVED
+    │      │
+    │      └─→ Any GAPS_FOUND → record gaps, set verdict=GAPS_FOUND
+    │
+    └─→ Return to sprint-flow orchestrator
+         │
+         ├─→ APPROVED → proceed to design doc generation
+         └─→ GAPS_FOUND → loop back to grill-with-docs (up to 5 total rounds)
+```
+
+---
+
+## 专家角色
+
+| 专家 | 视角 | 配置 |
+|------|------|------|
+| Expert A (architecture) | 需求完整性 + 需求→AC 映射 + 场景覆盖 | `.delphi-config.json` → `experts.architecture` |
+| Expert B (technical) | 技术清晰度 + 边界条件 + 实现约束 | `.delphi-config.json` → `experts.technical` |
+| Expert C (feasibility) | AC 可测试性 + 用户画像 + 范围边界 | `.delphi-config.json` → `experts.feasibility` |
+
+> 三个角色必须使用三个 distinct trimmed executable model IDs。Provider、vendor、gateway 和模型国籍均不受限制；一个 provider 和 token plan 可以服务全部三个角色。
+
+**专家选择理由**:
+- **architecture 专家**: 天然映射范围/覆盖到需求层面——需求完整性、需求→AC 映射、场景覆盖、领域术语一致性
+- **feasibility 专家**: 天然映射可测试性/假设到验收标准——AC 可测试性、用户画像清晰度、范围边界、隐含假设
+- **technical 专家**: 检查需求中的技术清晰度、边界条件和实现约束
+
+---
+
+## 评审焦点（模式切换指令）
+
+### Expert A (architecture) — 需求模式焦点
+
+| 维度 | 检查内容 |
+|------|---------|
+| **需求完整性** | 所有用户场景是否已覆盖，是否有遗漏的用例路径 |
+| **需求→AC 映射** | 每个需求是否有对应的验收标准，映射是否完整 |
+| **场景覆盖** | 正常流、异常流、边界场景是否均已识别 |
+| **领域术语一致性** | 需求陈述中的术语是否与 CONTEXT.md 领域模型一致（交叉引用） |
+| **AC 精确度** | 验收标准是否具体、可度量、无歧义 |
+
+### Expert C (feasibility) — 需求模式焦点
+
+| 维度 | 检查内容 |
+|------|---------|
+| **AC 可测试性** | 每个验收标准是否可被自动化或手动测试验证 |
+| **用户画像清晰度** | 目标用户/角色是否明确定义，场景是否贴合真实使用 |
+| **范围边界清晰度** | 需求边界（in-scope vs out-of-scope）是否明确划定 |
+| **需求间依赖** | 需求之间是否存在隐含依赖或冲突 |
+| **隐含假设** | 是否存在未明确声明的假设（技术、业务、环境） |
+
+---
+
+## 共识标准
+
+| 条件 | 结果 |
+|------|------|
+| 3/3 successful APPROVED + 无 Critical gaps | ✅ verdict=APPROVED，进入设计文档生成 |
+| 3/3 successful APPROVED + 有 Minor gaps | ✅ verdict=APPROVED（记录 gaps 供参考） |
+| 任一专家失败或缺失 | ❌ BLOCK，不能聚合或降级 |
+| 任一专家 GAPS_FOUND | ❌ verdict=GAPS_FOUND，记录 gaps |
+| 有 Critical requirement gaps | ❌ verdict=GAPS_FOUND |
+
+**共识要求**: 三个成功结果全部参与聚合，达到 >=90% 且最终 APPROVED。单个专家结果不能代表全局批准。
+
+---
+
+## 循环控制（Loop Semantics）
+
+```
+Round 1: delphi-review --mode requirements
+    │
+    ├─→ APPROVED → 完成，进入设计文档生成
+    │
+    └─→ GAPS_FOUND
+          │
+          ├─→ gaps 记录到 requirements-reviewed.json
+          ├─→ 返回 sprint-flow → grill-with-docs 补充访谈
+          │
+          ▼
+Round 2: delphi-review --mode requirements（带 Round 1 gaps 上下文）
+    │
+    ├─→ APPROVED → 完成，进入设计文档生成
+    │
+    └─→ GAPS_FOUND
+          │
+          └─→ escalation_needed: true
+              → sprint-flow Phase 2 处理升级 UX（交用户决策）
+```
+
+**硬性限制**:
+- **最多 5 轮**（Round 1 + 可选后续轮次）
+- **禁止无界循环** — Round 5 后仍 GAPS_FOUND 必须升级
+- **Round 2 上下文**: 专家看到 Round 1 的 gaps 列表，评估是否已修复
+- **升级语义**: `escalation_needed: true` 写入 requirements-reviewed.json，sprint-flow 负责 UX
+
+---
+
+## 输出格式
+
+### 证据文件: `.sprint-state/phase-outputs/requirements-reviewed.json`
+
+```json
+{
+  "mode": "requirements",
+  "verdict": "APPROVED",
+  "timestamp": "2026-07-25T10:30:00Z",
+  "consensus_ratio": 1.0,
+  "requirements_hash": "7f650ddf715ebe75ca0317efa1e8618ae39d2c0bafea7a6f85aacfdbf3735a5f",
+  "head_commit": "abc123def456789...",
+  "context_file_used": null,
+  "round": 1,
+   "expert_verdicts": [
+     { "role": "architecture", "verdict": "APPROVED", "confidence": 9, "result_type": "delphi_expert_result", "requested_model": "bailian-tp/qwen-plus", "resolved_model": "qwen-plus", "channel": "external" },
+     { "role": "technical", "verdict": "APPROVED", "confidence": 8, "result_type": "delphi_expert_result", "requested_model": "bailian-tp/deepseek-v3", "resolved_model": "deepseek-v3", "channel": "external" },
+     { "role": "feasibility", "verdict": "APPROVED", "confidence": 8, "result_type": "delphi_expert_result", "requested_model": "bailian-tp/glm-4.5", "resolved_model": "glm-4.5", "channel": "external" }
+   ],
+  "requirements_statement": "实现用户注册流程，支持邮箱验证和密码重置",
+  "gaps_found": [],
+  "rounds_used": 1,
+  "escalation_needed": false
+}
+```
+
+### GAPS_FOUND 示例
+
+```json
+{
+  "mode": "requirements",
+  "verdict": "GAPS_FOUND",
+  "timestamp": "2026-07-25T10:30:00Z",
+  "consensus_ratio": 0.67,
+  "requirements_hash": "7f650ddf715ebe75ca0317efa1e8618ae39d2c0bafea7a6f85aacfdbf3735a5f",
+  "head_commit": "abc123def456789...",
+  "context_file_used": null,
+  "round": 1,
+  "expert_verdicts": [
+    { "role": "architecture", "verdict": "APPROVED", "confidence": 8, "result_type": "delphi_expert_result", "requested_model": "provider/model-a", "resolved_model": "provider/model-a", "channel": "external" },
+    { "role": "technical", "verdict": "GAPS_FOUND", "confidence": 7, "result_type": "delphi_expert_result", "requested_model": "provider/model-b", "resolved_model": "provider/model-b", "channel": "external" },
+    { "role": "feasibility", "verdict": "APPROVED", "confidence": 8, "result_type": "delphi_expert_result", "requested_model": "provider/model-c", "resolved_model": "provider/model-c", "channel": "external" }
+  ],
+  "requirements_statement": "实现用户注册流程，支持邮箱验证和密码重置",
+  "gaps_found": [
+    "密码重置的过期时间未定义",
+    "邮箱验证失败的重试策略缺失",
+    "AC-003 不可测试：'系统应快速响应' 无量化指标"
+  ],
+  "rounds_used": 1,
+  "escalation_needed": false
+}
+```
+
+### 字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `mode` | string | 固定值 `"requirements"` |
+| `verdict` | string | `APPROVED` 或 `GAPS_FOUND` |
+| `timestamp` | string | 评审完成时间 (ISO 8601 UTC) |
+| `consensus_ratio` | number | 三位专家的共识比例；APPROVED 必须为 `0.90` 至 `1.0` |
+| `requirements_hash` | string | SHA-256 hex digest（防陈旧绑定，见下文） |
+| `head_commit` | string | 当前 `git rev-parse HEAD` |
+| `context_file_used` | string \| null | 项目根目录内引用的 context 文件相对路径；未使用时为 `null` 或空字符串 |
+| `round` | number | 当前轮次（1 至 5） |
+| `expert_verdicts` | array | 三位专家的成功结构化结果，包含 `result_type` 和 `requested_model` |
+| `requirements_statement` | string | 被评审需求的简短摘要 |
+| `gaps_found` | array | GAPS_FOUND 时的缺口列表（APPROVED 时为空数组） |
+| `rounds_used` | number | 实际使用的轮次数 |
+| `escalation_needed` | boolean | Round 5 后仍 GAPS_FOUND 时为 `true` |
+
+### 状态文件: `.sprint-state/delphi-reviewed.json`
+
+APPROVED 时同步写入状态文件（与 design / code-walkthrough 模式一致）:
+
+```json
+{
+  "mode": "requirements",
+  "timestamp": "2026-07-25T10:30:00Z",
+  "verdict": "APPROVED",
+  "consensus_ratio": 1.0
+}
+```
+
+> 此文件供 `verify-consensus.sh` 校验。GAPS_FOUND 时**不写入**此文件（评审未完成）。
+
+---
+
+## Hash 绑定（防陈旧绑定 — §8.4）
+
+`requirements_hash` = SHA-256 of:
+
+```
+requirements_statement + CONTEXT.md content + ISO timestamp prefix (YYYY-MM-DD)
+```
+
+**计算规则**:
+1. 从 evidence `timestamp` 解析严格有效的 ISO 8601 UTC 时间，并取其 `YYYY-MM-DD` 前缀
+2. 若 `context_file_used` 非空，只允许项目根目录内的相对路径；拒绝绝对路径、`..` 穿越、缺失/非普通文件，以及 realpath 逃出项目根目录的符号链接
+3. 按 UTF-8 原样读取 context 文件，不添加分隔符或换行；拼接精确字符串 `requirements_statement + context content + YYYY-MM-DD`
+4. 对拼接结果计算 SHA-256；生成值使用 64 位小写 hex，校验时大小写不敏感
+5. 未使用 context 时，精确拼接 `requirements_statement + YYYY-MM-DD`
+
+**目的**: 防止旧证据复用。`phase-transition 2 completed` 校验时：
+- 文件必须存在
+- `verdict` 必须为 `APPROVED`
+- `requirements_hash` 必须为 64 位 hex，并与运行时重新计算值匹配
+- 若 hash 与当前需求内容不匹配 → BLOCK（防陈旧绑定）
+
+**与 phase-transition.js 的集成**:
+
+```javascript
+// EVIDENCE_FILES[2] — 已存在于 phase-transition.js
+{
+  path: '.sprint-state/phase-outputs/requirements-reviewed.json',
+  requiredFields: [
+    'verdict', 'requirements_statement', 'timestamp', 'consensus_ratio',
+    'expert_verdicts', 'head_commit', 'requirements_hash'
+  ],
+  blockingCheck: (data) => data.verdict === 'APPROVED',
+  blockingMessage: 'Requirements review verdict is not APPROVED',
+}
+```
+
+---
+
+## 证据文件路径
+
+| 文件 | 路径 | 校验时机 | 校验方 |
+|------|------|----------|--------|
+| requirements-reviewed.json | `.sprint-state/phase-outputs/` | `phase-transition 2 completed` | phase-transition.js Layer 2 |
+| delphi-reviewed.json | `.sprint-state/` | verify-consensus.sh | verify-consensus.sh |
+
+---
+
+## Anti-Patterns
+
+**只在 `--mode requirements` 时适用：**
+
+| ❌ Don't | ✅ Do | Why |
+|----------|------|-----|
+| 使用少于 3 个专家 | 必须使用 architecture + technical + feasibility | 三个角色共同构成全局证据 |
+| 无界循环评审 | 最多 5 轮，之后升级 | 防止无限循环 |
+| 跳过 CONTEXT.md 交叉引用 | 始终交叉引用领域术语 | 需求应使用 CONTEXT.md 中的规范术语 |
+| 输出泛化批准 | 输出 hash 绑定的需求陈述 | 防陈旧绑定（§8.4，Round 1 设计反馈 #14） |
+| 接受单个专家批准 | 要求三份成功结果参与聚合，并达到 >=90% 共识 | 单个结果不能代表全局批准 |
+| Round 2 中复用 Round 1 gaps 作为新发现 | Round 2 专家获得 Round 1 gaps 上下文 | 迭代改进，避免重复劳动 |
+| 评审设计文档或代码 | 仅评审需求陈述 + CONTEXT.md | 设计/代码评审是 design / code-walkthrough 模式的职责 |
+| GAPS_FOUND 时写入 delphi-reviewed.json | 仅 APPROVED 时写入状态文件 | GAPS_FOUND 表示评审未完成 |
+| 在 lightweight sprint 中减少或跳过 R1 | 所有路径都执行三专家 R1，仅缩短上下文 | Force level 不改变专家数或批准证据 |
+
+---
+
+## Security Notes
+
+- **只读评审**: requirements 模式不修改任何源文件，仅写入证据文件到 `.sprint-state/`
+- **Hash 完整性**: `requirements_hash` 使用 SHA-256，防止需求内容被篡改后复用旧证据
+- **Commit 绑定**: `head_commit` 记录评审时的 git HEAD，提供时间线追溯
+- **调用边界**: 评审内容只传递给用户配置的 callable provider；provider、vendor、gateway 和模型国籍不作额外限制
+- **证据不可伪造**: phase-transition.js 程序化校验证据文件，LLM 无法绕过
+
+---
+
+## Triggers / Negative Triggers
+
+**触发（requirements 模式特有）**:
+- `/delphi-review --mode requirements`
+- "review the requirements"
+- "评审需求"
+- "requirements review"
+- "/requirements-review"
+
+**不触发**:
+- "review my requirements document"（教育性讨论，非执行评审）
+- "requirements template"（询问模板格式）
+- "how to write requirements"（教育性）
+- "check my requirements"（模糊，可能是 Casual 检查）
+
+---
+
+## Terminal State Checklist (requirements mode)
+
+**Pre-requisites (MANDATORY - BLOCK if missing):**
+- [ ] grill-with-docs 已完成（或 CONTEXT.md 快速路径）
+- [ ] 需求陈述可用（非空）
+- [ ] Expert A (architecture)、Expert B (technical)、Expert C (feasibility) 均成功执行
+- [ ] 三个 `requested_model` trimmed 后 distinct
+- [ ] 三份结果均为 `result_type=delphi_expert_result`
+
+**CRITICAL - 共识验证 (requirements):**
+- [ ] 聚合共识 >=90%，且所有 Critical gaps 已处理
+- [ ] 无 Critical requirement gaps 未解决
+- [ ] requirements_hash 已计算并写入
+
+**Final Requirements (requirements):**
+- [ ] `.sprint-state/phase-outputs/requirements-reviewed.json` 已写入
+- [ ] JSON 格式有效，包含所有必需字段
+- [ ] verdict 为 APPROVED 或 GAPS_FOUND
+- [ ] IF APPROVED: `.sprint-state/delphi-reviewed.json` 已写入（mode=requirements）
+- [ ] IF GAPS_FOUND: gaps_found 数组非空，escalation_needed 正确设置
+- [ ] IF Round 5 后仍 GAPS_FOUND: escalation_needed = true
+
+**IF 任何 Pre-requisite 缺失:**
+- **CANNOT 完成评审**
+- **MUST BLOCK 并通知用户**
+
+**IF GAPS_FOUND (Round 1):**
+- 返回 sprint-flow → grill-with-docs 补充
+- 重新执行 requirements 评审（Round 2）
+
+**IF GAPS_FOUND (Round 5):**
+- **escalation_needed = true**
+- **MUST 升级给用户决策**
+- **CANNOT 自动继续**
+
+**⭐ APPROVED 后必做 (requirements mode)：写入证据文件**
+
+IF mode == `requirements` AND 最终裁决是 APPROVED，评审完成后必须：
+
+1. 写入 `.sprint-state/phase-outputs/requirements-reviewed.json`
+2. 写入 `.sprint-state/delphi-reviewed.json`（状态文件）
+3. 验证 JSON 格式有效
+4. 验证 requirements_hash 为 64 位 hex 且运行时重新计算匹配
+5. 验证 head_commit 匹配当前 HEAD