taiyi-review

name	taiyi-review
description	TaiyiForge 第8阶段 — 合并前评审，REVIEW.md。四端通用。
paradigm	Momus

taiyi-review — 合并前评审

进入本阶段前请优先读 .taiyi/changes/<slug>/PHASE-CONTEXT.md（~500 tokens），不要全量加载上游工件。

框架集成

本阶段使用以下框架：

框架	用途	何时加载
Harness	阶段门禁与推进（status → continue --approver；legacy：npx taiyi complete）	全程
GStack	review — 使用 GStack review 做 diff 安全分析	Round 1 FR 步骤前（可选）
OMO	作为 review 门控的工作流入口	全程

Superpowers / OpenSpec / Spec-Kit 在本阶段不涉及。

前置门禁（Pre-flight）

0.1 上游确认

• test 阶段已过关（TEST.md 存在，测试全部通过）
• README.md、CLAUDE.md 等文档的 Diff 已确认
• 当前 git 分支对比 base 的完整 Diff 可读

0.2 Profile 判定

Profile	REVIEW.md 要求
full	4 rounds 完整评审（diff/架构/测试/文档）+ 修订循环 + ⭐ 总体评分
api/ui	同 full
lite	简化为 3 rounds（跳过架构评审）+ 修订循环 + ⭐ 评分
spike/micro	简化到 1 round（代码可读性）+ ⭐ 评分
nano	跳过

0.3 前置检查清单

• TEST.md 存在且测试全部通过
• git diff 与 base 分支的差异已清楚（git diff base-branch..HEAD --stat）
• 无未提交的改动

---

步骤

工件契约

层	路径	职责
语义真源	review.json	Zod（src/schemas/review.ts）
生成视图	REVIEW.md	hbs（src/templates/review.hbs）
流程	本 Skill	4 rounds、修订循环、⭐ 评分

工作流：review-loop 机器审查 → 更新 json findings → render <slug> review → status → continue --approver "名"。

详见 docs/taiyi/artifact-contract.md。

json 字段（Zod 摘要）

字段	要求
title	评审标题
findings	severity / description / file / line / resolved
code_quality	可选；⭐ 各维度 1–5
test_coverage	可选；层覆盖摘要
blocking_items / suggestion_items	可选
verdict / summary	可选；合并门槛与总结

除更新 Finding 状态外，不要手改 reviewer 生成的 REVIEW.md 结构；结构化数据以 review.json 为准。

写作指引（填入 json，render 生成 REVIEW.md）

除了修改实现外，不要修改 reviewer agent 生成的 REVIEW.md 内容。

1. Round 1 — 功能性 FR（Diff 角度）

审查 git diff 中的每个改动（逐文件），检查：

• 逻辑正确性（边界、竞态、类型安全）
• 与 AC 的一致性（每段代码能不能追踪到某条 AC？）
• 错误处理完整（每条错误路径有 check / catch）
• Scope 管控（改动是否超出 TASK.md write_files？）

输出格式 — 每个 finding 一条：

### FR-1: [标题]
**File**: `src/foo/bar.ts:45`
**Issue**: [一句话描述问题]
**Severity**: critical / major / minor
**Suggestion**: [具体修改建议]
**AC Trace**: AC-1.2, AC-3.1

2. Round 2 — 架构 AR（方案角度）

审查实现与 DESIGN.md 的一致性：

• 是否遵循了选定的架构方案？
• 是否有新的抽象或模式未在 DESIGN 中讨论？
• DB Schema / API 签名是否与 DESIGN 一致？

### AR-1: [标题]
**File**: `src/foo/bar.ts`
**Issue**: [架构级问题，如偏离了 DESIGN.md 选定的方案]
**Severity**: critical / major / minor
**Suggestion**: [重构或补充方案]

2.X 集成完备性

对 diff 中所有新增/修改的 export 函数，逐一验证调用链：

• 入口函数（被 CLI/HTTP/定时触发）→ 必须有外部调用者
• 中间函数（被入口函数内部调用）→ 必须在 diff 中有调用者
• 独立函数（无调用者）→ 标记为 dead code 或标注依赖 change

检查方式：grep 新增函数名在整个 codebase 中的调用次数。

• 0 次调用 → critical finding：函数定义但无调用者
• 同步检查 task.json 的 covers_frs 与 requirement.json 的 functional_requirements 覆盖是否完整

3. Round 3 — 测试 TR（覆盖角度）

审查测试覆盖率：

• 全部 AC 是否有测试覆盖？
• 边界值是否覆盖？
• 负测试（错误路径）是否存在？

4. Round 4 — 文档 DR（交付角度）

• README.md 是否需要更新？
• CLAUDE.md / AGENTS.md 是否需要更新？
• CHANGELOG.md 条目是否合理？
• API 文档 / 迁移指南是否需要更新？

---

5. 修订循环（resolve findings）

对每个 critical / major finding → agent 修复 → 提交 → 重跑测试 → 更新 REVIEW.md Finding 状态为 "Resolved"。

修订循环规则：

• critical: 必须全部 resolved 才能过关（continue）
• major: 至少 80% resolved，剩余标注为 deferred（需人工确认）
• minor: 可选，可全部 deferred

6. ⭐ 总体评分

## ⭐ 总体评分

| 维度 | Score (1-5) | 备注 |
|------|------------|------|
| 功能性 | 5 | 所有 AC 满足 |
| 架构 | 4 | 方案一致，Singleton 模式不完全适用 |
| 测试 | 5 | 边界/错误路径全覆盖 |
| 文档 | 5 | README/CLAUDE.md 已更新 |
| 维护性 | 4 | 部分函数可进一步拆分 |

**汇总**: 4.6 / 5.0 — 可合并

合并门槛：

• 汇总 < 3.5 → 不可合并，需要大改
• 3.5 ≤ 汇总 < 4.0 → 有条件合并，major findings 标注 deferred 需人工确认
• 汇总 ≥ 4.0 → 可合并

---

过关（Harness）

1. 逐项检查 ## 质量自检；有未通过项则不要过关。
2. 机器审查（review 阶段强制）：scripts/taiyi-forge.sh review-loop <slug> 或 /taiyi:review-loop，直到无 blocking findings（见 engineTruth / review-loop 输出）。
3. health 门禁（仅当 status 显示 medium/high 复杂度且未 mark-aux）：加载 @taiyi-health → 产出 health-report.md → scripts/taiyi-forge.sh mark-aux <slug> taiyi-health。
4. 预检：scripts/taiyi-forge.sh status <slug> --json --compact — 解析 engineTruth（qualityReady / blockers）。
5. 用户确认后过关：scripts/taiyi-forge.sh continue <slug> --approver "名"（review 人工门）。
6. 过关后再 status --json --compact，读 engineTruth；若 currentPhase 已变为 integration，切换到 taiyi-integration Skill 并通知用户。

Legacy：npx taiyi complete <slug> review --approver "名" 仍可用；聊天优先 /taiyi:continue。

产出

• .taiyi/changes/<slug>/REVIEW.md
• .taiyi/changes/<slug>/review.json

与下游衔接

下游	需要
taiyi-integration	REVIEW.md → 归档的必要附件；修订记录 → 变更历史；⭐ 评分 → 归档报告的重要组成部分

异常处理

场景	处理
git diff 为空（无改动）	评审所有已过关阶段的 artifact（CHANGE/REQUIREMENT/DESIGN/TASK/TEST），检查一致性
发现 critical 问题	agent 立即修复 → 测试 → 更新 REVIEW.md。不要等待人工
修订循环中测试挂了	修复 → 更新 Finding 状态 → 重跑全部测试。不删除 finding
汇总 < 3.5	不能过关 review 阶段，列出需要大改的项目，等用户指示
人工 reviewer 建议大改	走修订循环，每次走完检查 diff + regress 测试。禁止直接 apply 所有建议
误过关本阶段或后续	scripts/taiyi-forge.sh undo <slug> review

<fatal_constraints>

• NEVER modify the generated REVIEW.md content except to update Finding status from "Open" to "Resolved" or marking as "Deferred".
• NEVER skip the 修订循环 for critical/major findings — they must be addressed before completion.
• NEVER claim a review is complete without a ⭐ 总体评分.
• NEVER skip 架构审查 (Round 2) for full/api/ui profiles.
• NEVER manually cherry-pick which findings to resolve — follow severity priority (critical → major → minor).
• NEVER advance with ⭐ < 4.0 unless user explicitly approves deferred items. </fatal_constraints>

质量自检

• 前置门禁已通过（0.1–0.3）
• review-loop 已通过（无 blocking）
• health 门禁已满足（若 status 要求）
• Round 1-4 全部完成（功能性/架构/测试/文档）
• 每条 Finding 有 severity 标签 + 文件:行号
• 修订循环已完成：critical 全部 resolved，major ≥ 80% resolved
• ⭐ 总体评分已给出
• 汇总 ≥ 3.5（合并门槛）
• REVIEW.md 没有被 AI 大幅修改——只更新了 Finding 状态
• 全部测试在修订后重新通过

引擎门控（自动，无需手动确认）

• export 调用者检查: git diff 中所有新增/修改 export，grep 查找调用者。零调用者 → 阻止过关
• 上游工件完整性: 所有非跳过阶段工件必须存在且非种子模板 → 阻止过关
• 分数门控: 代码/文档/测试/总评 四项分数不达标 → 阻止过关（TAIYI_REVIEW_ENFORCE_SCORES=0 关闭）
• 轮次门控: review-loop 必须完成全部轮次 → 阻止过关
• TDD 证据: TEST.md 不能只写 "build passes" 而无实际 .test.ts 文件引用