@boyingliu01/xp-gate 0.7.0 → 0.8.0

package/plugins/opencode/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小时

package/plugins/opencode/skills/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: improve-codebase-architecture
+description: Find deepening opportunities in a codebase, informed by domain language in CONTEXT.md and decisions in ADRs. Use when user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more AI-navigable. Run periodically (weekly or after surges of development).
+---
+
+# Improve Codebase Architecture
+
+周期性架构健康检查：发现 **shallow module → deep module** 的深度化机会。目标是提升可测试性、AI 可导航性、模块边界清晰度。
+
+与 XP-Gate 质量门禁的分工：
+| 机制 | 时机 | 作用 |
+|------|------|------|
+| **6 道门禁** | 每次 commit | 被动拦截明显问题（函数过长、重复代码等） |
+| **improve-codebase-architecture** | 每周/开发潮后 | 主动深度化改进（seam 识别、模块合并、接口提炼） |
+
+---
+
+## 术语（与 XP-Gate Principles 一致）
+
+| 术语 | 定义 |
+|------|------|
+| **Module** | 任何有接口和实现的东西（函数、类、包、slice） |
+| **Interface** | 调用者使用前必须知道的一切：类型、不变量、错误模式、顺序、配置 |
+| **Implementation** | 接口背后的代码 |
+| **Depth** | 接口的杠杆率：大量行为隐藏在简单接口后。**Deep = 高杠杆**。**Shallow = 接口几乎与实现一样复杂** |
+| **Seam** | 接口所在位置；可以在不修改实现的情况下改变行为的地方 |
+| **Adapter** | 在 seam 处满足接口的具体实现 |
+| **Locality** | 深度带来的可维护性收益：变更、bug、知识集中在一处 |
+
+---
+
+## 核心判断工具
+
+### Deletion Test
+想象删除某个模块：
+- 如果复杂性消失 → 它是 pass-through，不值得保留
+- 如果复杂性在 N 个调用方中重新出现 → **它真正提供了价值**
+- **"Yes, concentrates" = 你想发现的信号**
+
+### The Interface Is the Test Surface
+接口就是测试的边界。如果测试需要深入实现细节，说明接口太浅。
+
+### One Adapter = Hypothetical Seam. Two Adapters = Real Seam.
+只有一个实现满足接口 → 可能过度抽象。两个以上 → 真正的可替换边界。
+
+---
+
+## 流程
+
+### 1. 探索
+
+先读项目的 `CONTEXT.md`（领域语言）和 `docs/adr/`（架构决策）。
+
+然后有机地走查代码库（不要遵循死板启发式），注意你在哪里感受到摩擦：
+
+- 理解一个概念是否需要在多个小文件间跳来跳去？
+- 模块是否 **shallow** — 接口几乎与实现一样复杂？
+- 纯函数是否仅仅为了可测试性而被提取，但真正的 bug 隐藏在调用方式中？（缺乏 **locality**）
+- 紧密耦合的模块是否在其 seams 之处泄漏？
+- 哪些部分难以通过当前接口进行测试？
+
+对任何怀疑 shallow 的模块执行 **Deletion Test**：删除它会让复杂性集中还是分散？"是的，会集中"就是你要的信号。
+
+### 2. 呈现候选项
+
+以编号列表呈现深度化机会。每项包含：
+
+- **Files** — 涉及哪些文件/模块
+- **Problem** — 当前架构为何造成摩擦（使用 CONTEXT.md 中的领域术语）
+- **Solution** — 自然语言描述会怎样改变
+- **Benefits** — 用 locality 和 leverage 解释收益，以及测试会怎样改善
+
+**使用 CONTEXT.md 领域术语。如果与 ADR 冲突**，仅在摩擦值得重新讨论 ADR 时才标注：
+> *"Contradicts ADR-0007 — 但值得重新打开，因为…"*
+
+不要列出 ADR 禁止的每个理论重构。
+
+**此时不要提出接口设计**。先问用户："你想探索哪个候选项？"
+
+### 3. 用户选择候选项
+
+仅当用户明确选择某个候选项时，才进入步骤 4。
+
+### 4. Grilling 循环（设计树遍历）
+
+用户选中某个候选项后，进入 grilling 对话：
+- 遍历约束、依赖、深度化模块的形状
+- seam 背后放什么、什么不放在 seam 背后
+- 哪些测试能在深度化后存活/新增
+
+**对话中的副作用**（决策固化时立即执行）：
+- 命名不在 CONTEXT.md 中的新概念 → **新增到 CONTEXT.md**
+- 模糊术语在对话中变清晰 → **更新 CONTEXT.md**
+- 用户拒绝候选项且有有理由 → **提议记录为 ADR**（避免未来重复建议）
+- 需要探索替代接口 → **按接口设计原则引导**
+
+### 5. 输出（可选）
+
+如果用户在 grilling 后决定执行重构：
+- 生成重构计划（含文件列表、步骤顺序、风险点）
+- 调用 test-driven-development skill 执行重构（保持行为不变）
+
+---
+
+## 与 XP-Gate 集成
+
+### 触发时机
+```
+Phase 5 (FEEDBACK) 后推荐调用：
+  → learn + retro + **improve-codebase-architecture**
+  → 发现架构摩擦 → 记录到 retro → 下一 Sprint 纳入 backlog
+
+或作为独立周期性任务：
+  → /improve-codebase-architecture  → 每周/开发潮后
+```
+
+### 与 ralph-loop 的关系
+架构改进本身可以作为一个独立的 REQ 通过 ralph-loop 执行：
+- REQ: "深度化 Order 模块（从 N 个散文件合并为 deep module）"
+- 通过 test-driven-development 保证行为不变
+
+### 与质量门禁的关系
+架构改进后，质量门禁的 violation 数量应减少：
+- God class → 拆分为 deep modules → SOLID-001 (SRP) 告警消失
+- Deep nesting → 封装为简单接口 → CC-002 告警消失
+- Code duplication → 提取公共 deep module → Gate 2 (Dup Code) 改善
+
+---
+
+## Anti-Patterns
+
+| ❌ 错误 | ✅ 正确 |
+|---------|---------|
+| 仅在文件层面重构（拆分大文件） | 在概念边界处重构（deep module 封装行为） |
+| 为了测试而提取纯函数 | 为了 locality 和组织行为边界而重构 |
+| 过度设计接口（只有一个 adapter） | 发现真实 seam（≥2 adapters 或需要可测试性）后再抽象 |
+| 忽视现有 ADR 提出重构 | 尊重 ADR，仅在摩擦值得重新讨论时标注冲突 |
+| 一次性重构整个模块 | 逐个候选项执行，使用 TDD 保证行为不变 |
+| 与 ADR 冲突但不记录决策 | 记录为 ADR，避免未来重复建议 |
+
+---
+
+## 使用示例
+
+```
+/improve-codebase-architecture
+
+→ Explore: 读取 CONTEXT.md, 走查代码库
+→ 发现 3 个浅模块候选项
+→ 呈现: #1 Order 模块过浅 / #2 Auth 适配器泄漏 / #3 支付领域缺乏 locality
+→ 用户选中 #1
+→ Grilling: 讨论 Order 的 seam 应该在哪
+→ 更新 CONTEXT.md: 新增 "Order Intake" 术语
+→ 提议 ADR: "Order 状态机封装" → 用户同意 → 创建 docs/adr/000X.md
+→ 输出: 重构计划 → TDD 执行
+```