Vibeflow Review

全局变更审查

在所有活跃功能通过后、系统测试前运行。审查整个交付物的结构完整性、一致性和质量。

当前实现保持单一 Review 阶段，但报告会固定拆成两组结果：

• Spec Compliance
• Code Quality

这样可以把“是否按需求/设计做对了”和“代码及实施证据是否站得住”分开表达，而不增加新的用户阶段概念。

Review 的正式真相来源是：

• feature-list.json
• design.md
• rules/
• build reports / implementation result artifacts

如存在 packet，可作为兼容缓存参考，但不应成为阻塞 Review 的唯一依据。

启动宣告： "正在使用 vibeflow-review 运行全局变更审查。"

运行时机

• 所有活跃功能（非废弃）在 feature-list.json 中状态为 "passing"
• 在 vibeflow-test-system 之前
• 此阶段关注跨功能问题，而非单个功能（那是 vibeflow-spec-review 的工作）

安全护栏（可选激活）

在执行审查前，用户可选择激活安全护栏：

启用 careful（危险命令警告）： Skill: vibeflow-careful

启用 freeze（编辑边界保护）： Skill: vibeflow-freeze

同时启用 guard（最大安全模式）： Skill: vibeflow-guard

安全护栏默认不启用。如用户未主动调用上述 skill，审查将以正常权限执行。

检查清单

1. 准备

• 读取 feature-list.json — 确认所有活跃功能为 passing
• 读取 .vibeflow/logs/session-log.md — 会话历史
• 运行 python scripts/get-vibeflow-paths.py --json，读取设计文档 — 架构和全局约束
• 运行 git diff main...HEAD（或对应基线分支）获取完整变更

2-4. 三维度并行审查

结构审查、回归检查、完整性检查互不依赖，使用 Agent 工具并行执行：

准备完成（diff + 文档已读取）
        │
        ├──▶ Agent 1: 结构审查（R1-R5）
        │         检查架构/依赖/API/数据模型一致性
        │
        ├──▶ Agent 2: 回归检查（G1-G4）
        │         运行测试套件 + 覆盖率 + lint + 安全审计
        │
        └──▶ Agent 3: 完整性检查（C1-C4）
                  检查文档/进度/示例一致性
        │
        ├── 三个 Agent 都返回 ──▶ 合并结果到审查报告
        └── 任一发现问题 ──▶ 按严重度处理

执行方式：

在同一条消息中发起三个 Agent 调用。每个 Agent 的提示词包含：feature-list.json 内容、设计文档路径、git diff 输出、quality_gates 阈值。

Agent 1 — 结构审查（含深度代码审查）：

两阶段审查流程：

1. Pass 1（Critical）— 必须先执行： SQL & 数据安全 → 竞态条件 → LLM 信任边界 → Enum 完整性
2. Pass 2（Informational）— Pass 1 完成后执行： 条件副作用 → 魔法数字 → Dead Code → 测试覆盖缺口

Fix-First 分类规则：

Scope Drift 检测（审查前必做）：

• 读取 TODOS.md（如存在）和 commit messages
• 对比 git diff --stat 与需求是否匹配
• 检测：范围蔓延（无关文件变更）、需求遗漏（应做未做）
• 输出格式：

  Scope Check: [CLEAN / DRIFT DETECTED / REQUIREMENTS MISSING]
  Intent: <1行描述请求内容>
  Delivered: <1行描述实际变更>
  

Enum & Value Completeness 特别规则（Diff 新增 enum 值时）： 使用 Grep 找到所有引用同级值的文件，Read 每个文件确认新值被正确处理：

• 检查 switch/if-elsif 链：新值是否落入错误 default？
• 检查 allowlist 数组：新值是否在所有需要的地方添加？
• 检查 frontend dropdown/backend model：两端是否一致？

返回格式：

结构审查：N issues (X critical, Y informational)
**AUTO-FIXED:**
- [file:line] Problem → fix applied
**NEEDS INPUT:**
- [file:line] Problem description
  Recommended fix: suggested fix
  → A) Fix  B) Skip

Agent 2 — 回归检查：

返回格式：每个检查项的 PASS/FAIL + 实际输出证据。

Agent 3 — 完整性检查：

文档陈旧性检查规则：

• 检查 diff 中变更的文件是否被 README.md、ARCHITECTURE.md、CONTRIBUTING.md 等文档描述
• 如文档未更新但代码已变更，标记为 INFORMATIONAL：

  "Documentation may be stale: [file] describes [feature] but code changed in this branch."

返回格式：每个检查项的 PASS/FAIL + 备注。

结果合并： 收集三个 Agent 的返回结果，合并到统一的审查报告中。

回退规则： 如 Agent 工具不可用或执行异常，回退为顺序执行（结构 → 回归 → 完整性）。

5. 生成审查报告

保存到 docs/changes/<change-id>/verification/review.md：

# 全局变更审查报告

**日期**：YYYY-MM-DD
**功能总数**：X 活跃 / Y 废弃
**审查范围**：git diff main...HEAD

## 结构审查
| 检查 | 结果 | 备注 |
|------|------|------|
| R1-R5 | PASS/FAIL | 架构/依赖/API/数据模型/孤立代码 |
| R6-R9 | PASS/FAIL | Critical: SQL安全/竞态/LLM信任/Enum完整性 |
| R10-R13 | PASS/FAIL | Informational: 条件副作用/魔法数字/DeadCode/测试缺口 |

## 回归检查
| 检查 | 结果 | 备注 |
|------|------|------|
| G1-G4 | PASS/FAIL | 测试/覆盖率/lint/安全审计 |

## 完整性检查
| 检查 | 结果 | 备注 |
|------|------|------|
| C1-C4 | PASS/FAIL | 变更记录/进度/文档/示例 |
| C5 | PASS/FAIL | 文档陈旧性 |

## Scope Drift 检测
[审查前执行：对比 Intent vs Delivered]

## 发现的问题
| # | 严重度 | 描述 | 建议 |
|---|--------|------|------|

## 裁定
[PASS — 可进入系统测试 / FAIL — 需修复]

当前自动执行链路会把这些内容收敛成更紧凑的结构：

# Review

## Summary
## Spec Compliance
### Feature Contract Validation
### Implementation Delivery Consistency
### System Test Readiness

## Code Quality
### Required Config Checks
### Implementation Evidence Quality

## Verdict

6. 处理发现

• 严重/重要问题：修复后重新运行受影响检查
• 次要问题：记录，可推迟到下一迭代
• 最多 3 轮修复-重审循环，然后升级到用户

7. 过渡

审查通过后进入 vibeflow-test-system。

集成

调用者： vibeflow-router 或 vibeflow-build-work（步骤 13 当无失败功能时） 依赖： 所有活跃功能 passing 产出： docs/changes/<change-id>/verification/review.md 链接到： vibeflow-test-system