xp-gate 0.5.1

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

@@ -0,0 +1,486 @@
+# Code Walkthrough Mode Reference
+
+> Extracted from `SKILL.md`. This file contains ALL content specific to the `code-walkthrough` mode of Delphi Review.
+
+---
+
+## Overview
+
+代码走查模式，用于 git push 前对代码变更进行多专家 Delphi 评审。
+
+**触发命令**: `/code-walkthrough` (等价于 `/delphi-review --mode code-walkthrough`)
+
+---
+
+## Five Core Properties
+
+1. **匿名性** — Expert A/B 互不知道对方意见
+2. **迭代共识** — 多轮直到 APPROVED
+3. **零容忍** — Critical Issues 必须修复
+4. **零降级** — 环境/资源问题必须阻断，通知用户解决
+5. **强制覆盖** — 超过阈值必须 BLOCK，不能跳过
+
+---
+
+## 触发条件
+
+- **自动触发**：`git push` 前（通过 pre-push hook 验证结果文件）
+- **手动触发**：`/code-walkthrough` 命令（等价于 `/delphi-review --mode code-walkthrough`）
+
+**⚠️ 重要调用方式说明**：
+
+- ✅ **正确**: 在 Agent session 中执行 `/code-walkthrough`
+- ❌ **错误**: Shell 脚本调用 `opencode code-walkthrough` (OpenCode CLI 不支持 skill 子命令)
+- ❌ **错误**: CLI 子命令 `opencode run --skill code-walkthrough --diff` (不支持)
+
+**设计决策**: code-walkthrough 是 **强制但手动触发** 的质量门禁：
+- **强制**: push 必须有有效的 `.code-walkthrough-result.json` 文件
+- **手动**: Skill 执行由用户在 Agent session 内触发
+- **理由**: 避免 OpenCode CLI 架构限制，保持正常工作模式
+
+**⚠️ 门禁零容忍声明**:
+
+code-walkthrough 是强制性质控门禁，以下行为严格禁止：
+- ❌ 使用 `git push --no-verify` 绕过 pre-push hook 验证
+- ❌ 伪造 `.code-walkthrough-result.json` 文件
+- ❌ 因为"时间紧急"或"变更很小"而跳过评审
+- ❌ 修改门禁阈值让告警消失
+
+**门禁工具检测出的问题 = 必须修复，不允许绕过。**
+
+详见: [质量门禁行为准则](../../githooks/QUALITY-GATES-CODE-OF-CONDUCT.md)
+
+---
+
+## 流程概览
+
+```
+git push
+    │
+    ▼
+pre-push hook
+    │
+    ├─→ 获取 git diff main...HEAD
+    │
+    ├─→ 提取变更摘要
+    │
+    ├─→ 运行 Principles Checker (Clean Code + SOLID)
+    │
+    ├─→ 触发 Delphi 评审 (code-walkthrough mode)
+    │         │
+    │         ├─→ Expert A (架构 + 设计) 匿名评审 (含 principles_findings)
+    │         │
+    │         ├─→ Expert B (实现 + 代码质量) 匿名评审 (含 principles_findings)
+    │         │
+    │         ├─→ 共识检查
+    │         │      │
+    │         │      ├─→ 2/2 APPROVED → 允许推送
+    │         │      │
+    │         │      ├─→ 分歧 → Expert C 仲裁
+    │         │      │
+    │         │      └─→ REQUEST_CHANGES → 阻塞推送
+    │         │
+    │         └─→ 写入 .code-walkthrough-result.json
+    │
+    └─→ 允许/阻塞推送
+```
+
+---
+
+## 专家角色
+
+| 专家 | 视角 | 配置 |
+|------|------|------|
+| Expert A | 架构 + 设计评审 | `.delphi-config.json` → `experts.architecture` |
+| Expert B | 实现 + 代码质量 | `.delphi-config.json` → `experts.technical` |
+| Expert C (仲裁) | 冲突裁决 | `.delphi-config.json` → `experts.feasibility` |
+
+> ⚠️ **注意**: 至少配置 **两个不同 provider** 的模型。详见 [INSTALL.md](./INSTALL.md)。
+
+---
+
+## 评审维度
+
+**必检项**：
+
+| 维度 | 检查内容 |
+|------|---------|
+| **正确性** | 逻辑是否正确，边界条件是否处理 |
+| **安全性** | 是否有注入、泄露、越权风险 |
+| **可维护性** | 命名、结构、注释是否清晰 |
+| **测试覆盖** | 是否有足够的测试 |
+
+**选检项**（根据变更类型）：
+
+| 变更类型 | 额外检查 |
+|---------|---------|
+| API 变更 | 接口兼容性、文档更新 |
+| 数据库变更 | 迁移脚本、回滚方案 |
+| 性能敏感 | 性能测试、基准对比 |
+
+---
+
+## Principles Module Integration
+
+作为代码走查的一部分，自动运行 principles checker 分析：
+
+```yaml
+principles_module:
+  enabled: true
+  trigger: pre-push
+  rules:
+    - clean-code.all      # 9 rules
+    - solid.all           # 5 rules
+  integration_point: expert_prompt
+  output_format: principles_findings section
+```
+
+**Principles 检查流程**：
+
+```
+git push
+    │
+    ▼
+pre-push hook
+    │
+    ├─→ Step 1: Principles Checker
+    │         │
+    │         ├─→ 检测变更文件语言
+    │         ├─→ 选择对应 Adapter
+    │         ├─→ 运行 14 个规则
+    │         │      │
+    │         │      ├─→ Clean Code (9 rules)
+    │         │      │   - long-function (>50 lines)
+    │         │      │   - large-file (>500 lines)
+    │         │      │   - magic-numbers (非语义数字)
+    │         │      │   - god-class (>15 methods)
+    │         │      │   - deep-nesting (>4 levels)
+    │         │      │   - too-many-params (>7)
+    │         │      │   - missing-error-handling (IO 无 try-catch)
+    │         │      │   - unused-imports (未使用的导入)
+    │         │      │   - code-duplication (>15% 相似度)
+    │         │      │
+    │         │      ├─→ SOLID (5 rules)
+    │         │      │   - srp (单一职责)
+    │         │      │   - ocp (开闭原则)
+    │         │      │   - lsp (里氏替换)
+    │         │      │   - isp (接口隔离)
+    │         │      │   - dip (依赖倒置)
+    │         │      │
+    │         │      └─→ 输出 violations
+    │         │
+    │         └─→ Step 2: Delphi Code Walkthrough
+    │                  │
+    │                  ├─→ Expert A 评审 (含 principles_findings)
+    │                  ├─→ Expert B 评审 (含 principles_findings)
+    │                  └─→ 共识检查
+    │
+    └─→ 允许/阻塞推送
+```
+
+**Principles Findings 输出格式**（在 Expert 评审报告中添加）：
+
+```markdown
+## Principles Findings
+
+### Clean Code Violations
+
+| Rule | Severity | File | Line | Description |
+|------|----------|------|------|-------------|
+| clean-code.long-function | warning | src/api.ts | 45 | Function "processData" exceeds 50 lines |
+| clean-code.deep-nesting | warning | src/utils.ts | 12 | Nesting depth 5 > threshold 4 |
+
+### SOLID Violations
+
+| Rule | Severity | File | Line | Description |
+|------|----------|------|------|-------------|
+| solid.srp | warning | src/user.ts | 1 | Class has 18 methods (>15 threshold) |
+| solid.dip | warning | src/service.ts | 23 | Direct instantiation of UserRepository |
+
+### Summary
+- Total violations: [N]
+- Errors: [N]
+- Warnings: [N]
+- Infos: [N]
+```
+
+**Principles 检查与 Delphi 评审的关系**：
+
+| Principles 结果 | Delphi 评审行为 |
+|-----------------|-----------------|
+| 无 violations | Expert 正常评审，无额外关注点 |
+| 有 info 级别 | Expert 评审时参考，不阻塞 |
+| 有 warning 级别 | Expert 必须在评审中提及并给出意见 |
+| 有 error 级别 | **自动阻塞推送**，无需 Delphi 评审 |
+
+**阈值配置**：项目级配置文件 `.principlesrc` 可覆盖默认阈值：
+
+```json
+{
+  "rules": {
+    "clean-code": {
+      "long-function": { "threshold": 50 },
+      "god-class": { "threshold": 15 },
+      "deep-nesting": { "threshold": 4 }
+    },
+    "solid": {
+      "srp": { "methodThreshold": 15 },
+      "isp": { "methodThreshold": 10 }
+    }
+  }
+}
+```
+
+---
+
+## 共识标准
+
+| 条件 | 结果 |
+|------|------|
+| 2/2 APPROVED + 无 Critical Issues | ✅ 允许推送 |
+| 2/2 APPROVED + 有 Minor Issues | ✅ 允许推送（记录问题） |
+| 1/2 APPROVED | ⚠️ 需要 Expert C 仲裁 |
+| 0/2 APPROVED | ❌ 阻塞推送 |
+| 有 Critical Issues | ❌ 阻塞推送 |
+| 有 Major Issues 且未处理 | ❌ 阻塞推送 |
+
+---
+
+## 成本控制 (零降级原则)
+
+| 指标 | 阈值 | 处理 |
+|------|------|------|
+| 单次走查成本 | ~$0.03 | 正常执行 |
+| 最大评审文件数 | 20 个文件 | 超过 → **BLOCK** |
+| 最大 diff 行数 | 500 行 | 超过 → **BLOCK** |
+
+**超过阈值处理 (零降级)**：
+
+```
+IF 超过阈值:
+  → BLOCK 推送
+  → 通知用户：变更过大，无法有效评审
+  → 用户选项：
+     A. 拆分变更（推荐）
+     B. 用户明确授权跳过走查（需书面确认风险）
+
+  ❌ 禁止自动跳过走查
+  ❌ 禁止自动分批并批准
+```
+
+**设计原则**：
+- 大变更跳过评审 = 质量风险泄露到生产环境
+- 用户有权决定是否接受风险，AI 不能自动跳过
+
+---
+
+## Agent 可用性检查 (MANDATORY)
+
+**启动前检查**：
+
+```
+BEFORE code walkthrough:
+  ├─ 检查 Expert A 模型可用性
+  ├─ 检查 Expert B 模型可用性
+  ├─ 检查 Expert C 模型可用性（仲裁时需要）
+  └─ 检查 OpenCode CLI 可用性
+
+IF 任何检查失败:
+  → BLOCK 推送
+  → 通知用户具体缺失项
+  → 提供修复指引
+  → ❌ 禁止跳过走查直接推送
+```
+
+**模型不可用处理**：
+
+| 情况 | 处理 |
+|------|------|
+| Expert A API 错误 | BLOCK + 提示用户检查 API key |
+| Expert B API 错误 | BLOCK + 提示用户检查 API key |
+| OpenCode CLI 缺失 | BLOCK + 提示用户安装 OpenCode |
+
+---
+
+## Expert 评审输出格式
+
+```markdown
+## Code Walkthrough - Expert [A/B]
+
+### 变更摘要
+[变更的主要内容]
+
+### 发现问题
+
+| ID | 严重程度 | 问题描述 | 代码位置 | 修复建议 |
+|----|----------|----------|---------|---------|
+| ... | ... | ... | ... | ... |
+
+### 裁决
+[APPROVED / REQUEST_CHANGES]
+
+### 置信度
+[X/10]
+```
+
+---
+
+## 共识报告格式
+
+```markdown
+## Code Walkthrough 共识报告
+
+### 变更信息
+- 分支: [branch name]
+- 提交数: [N]
+- 文件数: [N]
+- 新增行数: +[N]
+- 删除行数: -[N]
+
+### 专家意见汇总
+- Expert A: [APPROVED / REQUEST_CHANGES]
+- Expert B: [APPROVED / REQUEST_CHANGES]
+
+### 共识结果
+[CONSENSUS / DISAGREEMENT]
+
+### 最终裁决
+[APPROVED / REQUEST_CHANGES / NEED_ARBITRATION]
+
+### 问题清单（如有）
+[需要修复的问题]
+```
+
+---
+
+## 结果输出文件 (MANDATORY)
+
+完成评审后，Skill 必须写入结果文件以供 Hook 验证：
+
+**输出文件位置**：`.code-walkthrough-result.json`
+
+**输出文件格式**：
+
+```json
+{
+  "commit": "abc123def456",
+  "branch": "feature/xp-rewrite",
+  "timestamp": "2026-04-14T10:30:00Z",
+  "expires": "2026-04-14T11:30:00Z",
+  "verdict": "APPROVED",
+  "confidence": 9,
+  "experts": [
+    { "id": "Expert A", "verdict": "APPROVED", "confidence": 9 },
+    { "id": "Expert B", "verdict": "APPROVED", "confidence": 8 }
+  ],
+  "issues": [],
+  "consensus_ratio": 1.0,
+  "files_reviewed": 5,
+  "lines_added": 120,
+  "lines_deleted": 45
+}
+```
+
+**字段说明**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `commit` | string | 当前 HEAD commit hash (git rev-parse HEAD) |
+| `branch` | string | 当前分支名 |
+| `timestamp` | string | 评审完成时间 (ISO 8601 UTC) |
+| `expires` | string | 过期时间 (timestamp + 1小时) |
+| `verdict` | string | 最终裁决: APPROVED / REQUEST_CHANGES |
+| `confidence` | number | 整体置信度 (1-10) |
+| `experts` | array | 专家评审结果 |
+| `issues` | array | 未解决的问题（如有） |
+| `consensus_ratio` | number | 问题共识比例 (≥0.95 为共识) |
+
+**有效期机制**：
+
+- **有效期**: 1小时
+- **过期后**: Hook 将提示重新执行 `/code-walkthrough`
+- **commit 必须匹配**: 文件中的 commit 必须等于当前 HEAD
+
+**Hook 验证逻辑**：
+
+Hook 验证以下条件（全部满足才允许 push）：
+
+1. 文件存在
+2. JSON 格式有效
+3. commit hash 匹配当前 HEAD
+4. verdict = APPROVED
+5. timestamp 未过期 (< 1小时)
+
+---
+
+## 与现有系统集成
+
+| 集成点 | 说明 |
+|--------|------|
+| `pre-push` hook | 验证 `.code-walkthrough-result.json` 文件（不调用 Skill） |
+| `gstack-ship` | 推送后进入发布流程 |
+| `verification-loop` | 走查通过后运行验证 |
+
+---
+
+## Anti-Patterns
+
+**只在 `--mode code-walkthrough` 时适用：**
+
+| 错误 | 正确 |
+|------|------|
+| Expert 不可用时跳过走查 | BLOCK + 提示用户修复环境 |
+| 超过阈值自动跳过走查 | BLOCK + 提示用户拆分变更 |
+| 超过阈值自动分批评审 | BLOCK + 用户决定是否拆分或授权跳过 |
+| OpenCode CLI 缺失时允许推送 | BLOCK + 提示用户安装 OpenCode |
+| 模型 API 错误时降级单模型 | BLOCK + 提示用户检查 API 配置 |
+| 未写入 `.code-walkthrough-result.json` 就声明完成 | MUST 写入结果文件后才能完成 |
+| 结果文件 commit hash 不匹配 | MUST 重新执行走查 |
+
+---
+
+## Terminal State Checklist (code-walkthrough mode)
+
+**Pre-requisites (MANDATORY - BLOCK if missing):**
+- [ ] OpenCode CLI 已安装且可用
+- [ ] Expert A 模型 API 可用
+- [ ] Expert B 模型 API 可用
+- [ ] 变更大小在阈值内（文件 ≤20，行数 ≤500）
+- [ ] Expert A 完成匿名评审
+- [ ] Expert B 完成匿名评审
+- [ ] 共识检查完成
+
+**CRITICAL - 共识验证 (code-walkthrough):**
+- [ ] 至少 2/2 或 2/3 专家 APPROVED
+- [ ] 无 Critical Issues 未解决
+- [ ] 无 Major Issues 未处理（或有处理计划）
+
+**Final Requirements (code-walkthrough):**
+- [ ] 共识报告已生成
+- [ ] 问题已记录（如有）
+- [ ] `.code-walkthrough-result.json` 已写入项目根目录
+- [ ] 结果文件 commit hash 匹配当前 HEAD
+- [ ] 结果文件未过期 (< 1小时)
+
+**IF 任何 Pre-requisite 缺失:**
+- **CANNOT 允许推送**
+- **MUST BLOCK 并通知用户**
+- **用户必须修复环境问题后重试**
+
+**IF 有 Critical Issues:**
+- **CANNOT 允许推送**
+- **MUST 修复后重新走查**
+
+**IF 超过大小阈值:**
+- **CANNOT 允许推送**
+- **MUST BLOCK 并提示拆分变更**
+- **用户可明确授权跳过（需确认风险）**
+
+**⭐ APPROVED 后必做 (code-walkthrough mode)：写入结果文件**
+
+IF mode == `code-walkthrough` AND 最终裁决是 APPROVED，评审完成后必须：
+
+1. 写入 `.code-walkthrough-result.json` 到项目根目录
+2. 验证 JSON 格式有效
+3. 验证 commit hash 匹配当前 HEAD
+4. 验证 expires 字段 = timestamp + 1小时