# 2026-05-20 ai-review 多轮迭代 + known v1.0 gap 不可消除 → 退出策略

## 背景

本月做 #409 PRD / #410 PR-A 系列 PR (#449 #455 #457 #474),
经历多次"ai-review verdict 卡 pass_with_risk 不到 pass → auto-merge daemon
不合"循环。每次修完 ai-review 又找新 finding,真实迭代 3-5 轮才合。

具体案例:

- **PR #449 standards/21**: 5 轮 ai-review。第 1 轮 5 finding 修完,第 2 轮发现
  3 处新 finding (主键 / Dashboard 角色 / ai_mode 枚举混用),第 3 轮 enum
  UPPER_SNAKE 漏改, 第 4 轮 6 处 lowercase 残留,第 5 轮 verdict pass → 人工合
- **PR #457 收尾**: 4 轮。enum 大小写迭代 3 次还有残留;每轮 ai-review 都说
  "上轮 N 项,本轮新发现 M 项小残留"
- **PR #474 PR-A 第 2 批**: 3 轮。useClass 双实例 + token 撞 + 顶部注释漂移
  分 3 轮才修干净

## 根因 (3 层)

### 表面症状
ai-review 总能找新 finding,verdict 持续 pass_with_risk;auto-merge daemon
严格 `verdict == pass` 才合,卡门口。

### 直接原因
1. **ai-review 是按 v1.0 标准的 LLM,每轮上下文略不同 + 知识库迭代**:
   不能保证"上轮没说 = 本轮也不说";新增 commit 改动会触发它"对全文重新审"。
2. **修复一处可能引入新的不一致**:
   #474 修 useClass 双实例时改了 forFeature 实现,但顶部 block 注释没同步 →
   ai-review 立刻发现"文档漂移"。
3. **每轮 finding 越改越细**:
   从 P1 risk → enum 大小写 → 注释 typo → 文档微漂移,呈递减的边际价值。

### 元根因
某些 risk 本质上**无法在 v1.0 文档/代码层消除**,只能 bounded:
- PR #449 §3.7 v1.0 audit 不屏蔽 sensitive 字段 — 已 by §9.2 hard 触发 bounded,
  但完整消除需 PR-A 包装层落地 → ai-review 每轮都会标这条
- 文档草稿期的"前向引用" (CLAUDE.md 已强制要求 standards/21,但 import 路径
  PR-A 合后才存在) — 永远在,直到 PR-A 合
- 标准制定 PR 内固有跟代码 + 测试不一致 — pure-docs PR 跟接入规范本身脱节

这类 risk **持续迭代不会消除** —— 修文档 wording 顶多让 ai-review verdict 升,
但底层 gap 还在;ai-review 第 N 轮可能再发现"另一处"同形态残留。

## 退出策略 (项目级 SOP)

每个 PR 应有**修复轮次预算**,达到后切换为 ack + 人工合,避免无限循环。

### 决策树

```
ai-review verdict
  ├─ pass → auto-merge daemon 合 ✓
  ├─ should_fix / pass_with_risk
  │    ├─ finding 含 hard_block / 真实代码 bug → 修
  │    ├─ finding 是文档漂移 / 命名风格 / 内部一致性 → 修 1 轮
  │    ├─ finding 是 v1.0 暂缓项 (PR body 已 ack 留后续) → 不修,ack 接受
  │    ├─ 累计 ≥ 3 轮 ai-review 仍 pass_with_risk → ack + 人工合
  │    └─ 单次 finding 数 ≥ 5 但都 sugg 级 → ack + 人工合
  └─ block → 必修
```

### ack 模板 (PR body 评论)

```markdown
## Ack:等人工合 (文档质量已饱和 / 迭代收益递减)

第 N 轮 ai-review M 项修复完成 (commit XXXX)。

**剩余 risk/sugg 是 known v1.0 gap,本质上无法在 v1.0 [文档/代码] 层消除**:
- [risk 名]: 由 [§X.Y hard 触发 / PR-A 后续 commit / 独立 PR] bounded
- [前向依赖]: 等 [依赖 PR] 合后才能消除

迭代到 verdict=pass 不可达。**建议人工 review + 合并** (CI 全绿 + 主题单一 +
不动 [code/schema/CI/契约面])。

劳烦另一位团队成员看完 Approve → Merge。
```

### 人工合通道 (CLAUDE.md Git 规则)

- 作者**严禁自合 feature PR**
- 找 chentao.jia / hongwei.zhang 等团队成员
- 让对方读 PR body + ack 评论 + 抽查 1-2 项决策
- 对方 Approve → Merge (squash)
- pass_with_risk 时 daemon 不自动合,完全靠人工

## 跨任务可复用经验

1. **ai-review 是 advisor 不是 gate**: pass_with_risk + 0 hard_block 时就能合,
   只是 daemon 严格化要求 pass。daemon 严格性是 trade-off,不该让 PR 卡 5 轮迭代。
2. **PR body 提前 ack 已知 v1.0 gap**: 写 PR 时就在 body 里列 "v1.0 limitations"
   段,ai-review 会识别 PR body 的 ack 把对应 finding 降权 (实测 #474 PR body
   ack 的 surface=web 默认 / L1 测试缺失 被 ai-review 标 "PR body 已 ack 留后续")。
3. **修复优先级**: 真实 bug > 内部一致性 > 文档漂移 > 命名风格 > 注释 typo。
   达到第 3-4 级就该 stop + ack 而非追求 pass。
4. **审 ai-review 的发现是否真值得修的判据**:
   - "实现者照这文档/示例会落错值" → 修 (实际影响)
   - "reviewer 读起来矛盾" → 修 1 轮
   - "命名风格不统一但语义清晰" → 视情况
   - "可能未来重现" → 写 .learnings 不必本 PR 修
5. **ai-review 第 4 轮+ 多是边际价值**: 沉淀代价 < 修复价值

## 相关链接

- PR #449 / #457 / #474 ai-review 评论历史
- CLAUDE.md § Gitea 平台配置 § 合并路径 (auto-merge daemon 行为)
- docs/standards/21 § "v1.0 代码层生效条件" banner (前向依赖 ack 写法)
- docs/ops/03-auto-merge-daemon.md (verdict=pass 严格要求来源)