@chenguangyao/devflow-kit 0.1.43

package/skills/apply/references/discipline-checklist.md

@@ -0,0 +1,145 @@
+# apply / discipline-checklist
+
+apply 阶段的纪律 checklist。per-task before / during / after。
+
+---
+
+## Before(每个 task 开始前)
+
+- [ ] 读了 plan.md 里当前 task 的 5 要素(Files / Behavior / Test / Implementation / Commit)
+- [ ] 读了 tests.md 里 linkedF 的 AC(知道要满足什么验收)
+- [ ] 读了 design.md 的相关模块(不需通读,只读 task 涉及的部分)
+- [ ] 确认前置 task 已完成(依赖已绿)
+- [ ] 确认当前在正确分支 / worktree(不是 main)
+- [ ] 项目可编译(基线是绿的)
+
+有一项未满足 → **不要开始**,先搞清再开工。
+
+---
+
+## During(每个 task 执行中)
+
+### 通用
+
+- [ ] 先写失败测试,再写实现
+- [ ] 只改 Files 列表里的文件(发现要改别的 → 停,更新 plan)
+- [ ] 不跨 task 编辑"顺手看到的"问题(记 TODO 交给对应 task)
+- [ ] 每 30-45 分钟跑一次测试(不要到最后才跑)
+- [ ] 复杂实现先画 2-3 行伪代码注释,再翻译成代码
+
+### 数据 / 存储类
+
+- [ ] DDL 变更先跑 migration(本地或 test db),再跑代码
+- [ ] 新字段 / 表有 index 设计?(看 design.md;没考虑 → 提 concern)
+- [ ] 数据迁移有"可以重跑"的幂等性?
+- [ ] 破坏性 DDL(drop column / rename)两阶段发布
+
+### 接口 / 契约类
+
+- [ ] 新 API 的契约文件(OpenAPI / proto / GraphQL schema)先改
+- [ ] 契约改好后跑 lint / generate,不要手动保持一致
+- [ ] 向后兼容?新字段 optional,老 client 不挂
+- [ ] 错误码 / error shape 按 design.md 的契约走
+
+### 异步 / 消息类
+
+- [ ] 消费端幂等(同一 message 消费 2 次结果一样)
+- [ ] Producer 故障策略(重试 / DLQ)实现了
+- [ ] 消息 schema 字段保守扩展(不改名不删)
+- [ ] 本地事务与消息发送的一致性(outbox / 2PC / best-effort)标清
+
+### 并发 / 事务类
+
+- [ ] 临界区的锁粒度最小(不要 `synchronized` 整个 service method)
+- [ ] 数据库事务跨度最小(不要把 RPC 调用包在 `@Transactional` 里)
+- [ ] 幂等键 / 乐观锁按 design.md 实现
+- [ ] 超时配置显式(不要用默认无穷大)
+
+### 安全 / 权限类
+
+- [ ] 权限校验在 controller / filter / interceptor 层
+- [ ] 没有硬编码 secret / token(用配置 / vault)
+- [ ] 入参验证在 API 层(不信任调用方)
+- [ ] SQL 参数化(不拼接字符串)
+
+### 日志 / 监控类
+
+- [ ] 关键路径打了 info 日志(含 traceId / 核心业务 id)
+- [ ] 错误路径打 error + 堆栈(但不 leak PII)
+- [ ] 新增的指标(counter / histogram)按 design.md 的 metric 定义注册
+- [ ] 不要用 log 做大量业务数据 dump(写到对应的数据流 / file)
+
+---
+
+## After(每个 task 完成前)
+
+### 代码自检
+
+- [ ] 每条新代码都有测试覆盖(至少被 1 个测试用到)
+- [ ] 没有 TODO / FIXME 没记录到 plan 或 issue
+- [ ] 没有 `System.out.println` / `fmt.Println` / `console.log` / `print(` 的调试残留
+- [ ] 没有注释掉的大段代码("以防万一")
+- [ ] import / include 无未用
+- [ ] Formatter / linter 跑过,没警告
+
+### 测试自检
+
+- [ ] 所有新测试都跑过且 PASS
+- [ ] 回归测试(所在 module 的全部测试)跑过且 PASS
+- [ ] 没有 `@Disabled` / `t.Skip` / `it.skip` / `pytest.mark.skip` 未记录
+- [ ] 覆盖率未明显下降(如果项目有 coverage gate)
+
+### commit 自检
+
+- [ ] `git status` 工作区干净(没漏加)
+- [ ] `git diff` 的改动都是 task 描述范围内的(没 scope creep)
+- [ ] commit message 按 plan.md 里规定的格式
+- [ ] 如多个 commit:最后一个 sha 记入 `--done --note`
+
+### 文档自检
+
+- [ ] 改动了的外部接口契约同步更新了文档(在本 task 的 Files 范围内)
+- [ ] 改动了的 design.md 关键决策(如果 apply 中发现真有必要调整 → 记录 revise 原因)
+
+### state 自检
+
+- [ ] 执行了 `devflow apply --task N --done --note="commit <sha>"`
+- [ ] state.json 的 tasksCompleted 加 1,当前 task 从 in_progress → done
+
+---
+
+## 整个 slug 的 apply 完成后
+
+- [ ] 所有 task 状态 done
+- [ ] 每个 task 都有对应 commit(sha 留在 state.json)
+- [ ] `devflow doctor` 过
+- [ ] 首次端到端跑一遍所有测试 → 产出 `reports/test-report.md#unit`
+- [ ] state.phase 等 orchestrator 推到 review;自己**不要**跳过
+
+---
+
+## 反偷懒自我审问
+
+做每个 task 时自己问 3 个问题:
+
+1. **"如果 reviewer 问我'这段代码为什么这样写',我能指着 design.md 的哪一段 / AC 的哪一条回答?"**
+   答不出 → scope creep 或设计缺失。
+
+2. **"如果 1 周后有人改这个文件,哪些 test 会失败?是不是精准覆盖我改的行为?"**
+   答"整个服务的集成测试会挂" → 没有精准单测,review 会要求补。
+
+3. **"这个 commit 如果被 revert,会不会破坏系统?"**
+   会 → commit 颗粒度不对,应该和下一个 commit 合并(或之前某个 commit 合并)。
+
+---
+
+## 反模式登记
+
+每次发现自己在做以下事,**停**:
+
+- ❌ "反正最后一块 commit" → NO,每 task 独立 commit
+- ❌ "先 skip 这个测试,后面补" → NO,要么修,要么 quarantine(审计)
+- ❌ "这个变量名不好,顺手改一下别的文件" → NO,出 task 范围
+- ❌ "reviewer 应该能看懂吧" → 代码要让人看懂,不是让 reviewer 猜
+- ❌ "先把主流程跑通,异常分支以后再说" → AC 里的异常分支必须本 task 搞定
+- ❌ "别人的代码写得乱,顺手重构" → 开新 task,开 ADR 讨论

package/skills/apply/references/subagent-implementer-prompt.md

@@ -0,0 +1,113 @@
+# 实现子 agent Prompt 模板
+
+controller 分派实现子 agent 时，使用下面的模板。将 `[占位符]` 全部替换后传入。
+
+> **核心原则**：把 task 全文直接粘贴进来，不让子 agent 自己去读 plan.md。
+
+---
+
+## Prompt 模板
+
+```
+你是 devflow apply 阶段的实现子 agent，负责完成以下 task。
+
+## 当前 Change
+
+- slug: [change slug，如 coupon-grant-api]
+- 工作目录: [worktree 绝对路径，如 /path/to/.devflow-worktrees/coupon-grant-api/task-2/]
+  （若无 worktree，填主仓库根目录）
+- 语言: [detect.language，如 java / node / go / python]
+
+## Task 全文
+
+[直接粘贴 plan.md 中该 task 的完整内容，包含 Files / Behavior / Test / Implementation / Commit 五要素]
+
+## 场景说明（Scene-setting）
+
+[说明这个 task 在整个 change 里的定位：
+- 依赖哪些前置 task 的产出（如：task-1 已创建 CouponGrantService，你要在此基础上加 XXX）
+- 绝对不能动哪些文件（如：不要动 controller 层，那是 task-3 的范围）
+- 任何有助于理解上下文的信息]
+
+## design.md 相关改动点摘要
+
+[粘贴 design.md 中与本 task 直接相关的那几段，不用全文]
+
+## tests.md 相关验收条件（AC）
+
+[粘贴 tests.md 中与本 task 对应的测试用例，格式如：
+- F-02 AC-1: 优惠券 ID 不存在时返回 404
+- F-02 AC-2: 重复授予时返回 409]
+
+## 实现前：先问，不要猜
+
+如果以下任何一点不清楚，**现在就问**，不要开始实现：
+- task 描述有歧义
+- 依赖的前置产出不存在或不符合预期
+- 测试框架 / 运行命令不确定
+- 任何会影响实现方向的假设
+
+等我回答清楚后再开始。
+
+## 实现步骤（TDD 循环，必须严格遵守）
+
+1. 读 task 的 5 要素，确认范围
+2. 写失败测试（先跑一次确认红，且失败原因正确）
+3. 最小实现（刚好让测试通过，不做额外重构）
+4. 跑所有相关测试（包含前置 task 的测试，防回归）
+5. commit（使用 task 里规定的 commit message）
+
+**每步完成后再做下一步，不要一次性写完再补测试。**
+
+## 实现中：遇到意外就暂停
+
+如果实现过程中发现：
+- plan 里的文件路径不对
+- 测试框架和预期不符
+- 发现需要改动 task 范围外的文件
+
+**停下来，告诉我，等待指示。** 不要自行扩大 scope。
+
+## 自我审查（commit 前做）
+
+- [ ] 完整实现了 task 描述里的所有要求？
+- [ ] AC 全部对应了测试？测试确实在验证行为而不只是 mock？
+- [ ] 只改动了 task 允许的文件？
+- [ ] 没有 YAGNI 的多余实现？
+- [ ] 代码命名准确（名字匹配行为，不是匹配实现细节）？
+- [ ] 所有测试绿？
+
+如果自我审查发现问题，先修好再汇报。
+
+## 汇报格式
+
+完成后按以下格式汇报：
+
+**实现内容**
+[简述做了什么，1-3 句话]
+
+**commit sha**
+[完整 sha]
+
+**测试结果**
+[通过 N 个，失败 0 个；或具体失败信息]
+
+**改动文件**
+[文件列表]
+
+**自我审查发现**
+[如有问题及修复说明；无问题写"无"]
+
+**疑虑或待确认**
+[如有；无则写"无"]
+```
+
+---
+
+## controller 使用说明
+
+1. **一次读完 plan.md**，把所有 task 全文缓存好，不要每次分派时再读。
+2. **按依赖顺序**分派，有依赖的 task 等前置完成后再分派（无依赖的可并行，但要确认无共享文件）。
+3. **子 agent 提问必须先回答**，不要催它直接实现。
+4. **子 agent 汇报 commit sha 后**，传给 reviewer 子 agent，自己不做代码审查。
+5. **子 agent 报告发现 plan 问题**，按 `when-plan-is-wrong.md` 决策回退，不要在本轮强行继续。

package/skills/apply/references/subagent-orchestration.md

@@ -0,0 +1,150 @@
+# apply / subagent-orchestration
+
+子 agent 编排模式：每个 task 分派独立实现子 agent，完成后过两轮 reviewer 子 agent 闭环，再标记 `--done`。
+
+---
+
+## 何时用子 agent 模式（强制规则）
+
+| task 数量 | 复杂度 | 执行模式 | 强制程度 |
+| --- | --- | --- | --- |
+| 1 个 task | 任意 | 当前 agent 直接做 | — |
+| ≥ 2 个 task，task 间有强依赖 / 共享文件 | 任意 | 子 agent + worktree，按依赖 wave 串行推进 | **必须** |
+| ≥ 2 个 task，同一 ready wave 内有 ≥ 2 个独立 task | 任意 | 子 agent 并行 + worktree | **必须** |
+
+> **⛔ HARD GATE**：只要 task 数量 ≥ 2，父 agent 就不能自己写代码，必须分派子 agent。
+> 父 agent 在多 task 场景里顺序执行代码 = 跳过 pre-review 质量门，是反模式。
+> **并行分派注意**：只有真正无共享文件的 task 才可并行分派；否则用串行。
+> **反向硬闸**：只要同一批 ready task 中有 ≥ 2 个满足并行条件，就不能串行启动。先做完 T-02 再启动本可并行的 T-03，视为执行错误。
+
+**授权解释**：用户触发 `devflow apply` / `/df:apply` 且 plan 已经审查确认后，devflow apply 本身就是子 agent 授权。controller 不得等待用户再说"子 agent"、"并行"或"分派 agent"；命中 ready wave 后应直接调用 subagent / spawn_agent 工具。若工具环境不支持，必须标记 BLOCKED 或 DONE_WITH_CONCERNS 并说明原因。
+
+**不需要显式指定并行**：并行是从 `plan.md` 的依赖图 / Files 列表 / ready wave 自动推导出来的执行策略，不是用户每轮要手动输入的口令。用户只在想覆盖默认策略时才需要说"直接做"、"不用子 agent"或"强制并行/不并行"。
+
+---
+
+## 编排流程（ready wave）
+
+```
+controller（父 agent）读 plan.md，提取所有 task 全文 + 上下文，建 TodoWrite
+
+Step 0 ─ 计算 ready wave
+  · 已完成依赖全部满足
+  · task 之间没有共享 Files
+  · task 之间没有 contract→consumer / DDL→business / feature flag→consumer 等强依赖
+
+对每个 ready wave：
+
+  Step 1 ─ 并行分派实现子 agent
+    · wave 内只有 1 个 task：启动 1 个实现子 agent
+    · wave 内 ≥ 2 个 task：必须在同一条工具消息中一次性启动多个实现子 agent
+    · 每个 prompt 都直接传入该 task 全文（不让子 agent 自己读 plan.md 找任务）
+    · 每个 prompt 都传入：change slug、独立 worktree 路径、design.md 摘要、tests.md 相关条目
+    · 子 agent 可在实现前提问 → controller 回答 → 子 agent 继续
+    · 子 agent 执行 TDD 循环：写失败测试 → 最小实现 → 跑测试 → commit
+    · 子 agent 自我审查后汇报（实现了什么 / commit sha / 测试结果 / 疑虑）
+
+  Step 2 ─ wave 返回后逐 task 分派规格合规 reviewer 子 agent
+    · 传入：task 全文、design.md 相关改动点、tests.md 相关 AC、commit sha
+    · reviewer 核对：实现是否覆盖所有 AC？有无多实现（over-build）？
+    · ❌ 不合规 → 实现子 agent 修复 → 重新审查（循环至 ✅）
+    · ✅ 合规 → 进入 Step 3
+
+  Step 3 ─ 逐 task 分派代码质量 reviewer 子 agent
+    · 传入：commit sha、diff 内容、语言 cheatsheet 路径
+    · reviewer 核对：命名、测试质量、边界处理、与现有代码风格一致性
+    · ❌ 有问题 → 实现子 agent 修复 → 重新审查（循环至 ✅）
+    · ✅ 通过 → controller 执行 `devflow apply --task N --done --note="<sha>"`
+
+  Step 4 ─ TodoWrite 标记 wave 内通过的 task completed，重新计算下一批 ready wave
+```
+
+所有 task done 后 → `devflow review --round`（正式 review phase，不省略）
+
+---
+
+## controller 的职责
+
+controller（父 agent）在整个编排中**只做协调**，不写代码：
+
+1. **一次性读完 plan.md**，提取所有 task 全文和上下文，避免多次文件 IO。
+2. **计算 ready wave**，明确哪些 task 必须并行、哪些必须等待依赖。
+3. **传完整信息给子 agent**，而不是让子 agent 自己去读文件（子 agent 上下文干净）。
+4. **回答子 agent 的问题**，子 agent 实现前提问要先回答，不催促。
+5. **管理 TodoWrite**，实时更新 task 状态（pending → in_progress → completed）。
+6. **执行 `devflow apply --task N --done`**，子 agent 不直接操作 state.json。
+7. **判断回退**：子 agent 汇报 BLOCKED / 发现 plan 不对 → 按 `when-plan-is-wrong.md` 回退。
+
+---
+
+## 子 agent 的边界
+
+实现子 agent **只能**：
+- 在分配的 worktree 目录内编码
+- 写测试、跑测试、commit
+- 问问题、汇报结果
+
+实现子 agent **不能**：
+- 修改 plan.md / design.md / tests.md（发现问题向 controller 报告）
+- 执行 `devflow apply --done`（由 controller 执行）
+- 读其他 task 的上下文（保持上下文隔离）
+
+---
+
+## 分派 prompt 的三要素
+
+每次分派子 agent，prompt 必须包含：
+
+| 要素 | 说明 |
+| --- | --- |
+| **task 全文** | 直接粘贴 plan.md 中该 task 的完整文本（5 要素：Files/Behavior/Test/Implementation/Commit） |
+| **scene-setting** | 这个 task 在整个 change 里的定位、依赖哪些 task 的产出、不要碰哪些文件 |
+| **工作目录** | worktree 路径（如 `.devflow-worktrees/<slug>/task-N/`）或 `--no-worktree` 时的主目录 |
+
+reviewer 子 agent 额外需要：
+
+| 要素 | 说明 |
+| --- | --- |
+| **commit sha** | 实现子 agent 汇报的 commit sha |
+| **diff 内容** | `git diff <base>..<sha>` 的输出（直接传，不让 reviewer 自己跑 git） |
+| **审查维度** | 规格合规 reviewer 侧重 AC 覆盖；代码质量 reviewer 侧重命名/测试质量/风格 |
+
+---
+
+## 回审循环上限
+
+| reviewer | 最多回审轮次 | 超出时 |
+| --- | --- | --- |
+| 规格合规 | 3 轮 | controller 上报 BLOCKED，回退 plan |
+| 代码质量 | 2 轮 | controller 上报 DONE_WITH_CONCERNS，在 state 打标签，deliver 时写进 PR |
+
+---
+
+## 与正式 review phase 的关系
+
+子 agent 内嵌的 reviewer 是 **pre-review**（apply 阶段质量门），目的是让进入 `devflow review --round` 时代码已经「可以过」。
+
+- pre-review 通过 ≠ 跳过正式 review
+- 正式 review 面向整个 change（跨 task 一致性、全局架构、安全），pre-review 面向单 task
+- pre-review 不写 `review.md`；正式 review 才写
+
+---
+
+## 反模式
+
+- **并行分派有共享文件的 task**：合并时冲突，controller 无法自动解决
+- **把可并行 wave 串行执行**：浪费 worktree 隔离能力，也违背 subagent-driven-development 目标
+- **让子 agent 读 plan.md 自己找 task**：引入无关上下文，子 agent 容易越权修改其他 task
+- **跳过 pre-review 直接 `--done`**：等于取消了 apply 阶段质量门
+- **controller 替子 agent 写代码**：职责混淆，两者上下文都污染
+- **pre-review 通过后跳过正式 review**：pre-review 不覆盖跨 task 一致性
+
+---
+
+## 参考
+
+- [`implementer-prompt.md`](subagent-implementer-prompt.md) — 实现子 agent 的 prompt 模板
+- [`reviewer-prompt.md`](subagent-reviewer-prompt.md) — reviewer 子 agent 的 prompt 模板（规格合规 + 代码质量两用）
+- [`tdd-loop.md`](tdd-loop.md) — 实现子 agent 遵守的 TDD 循环细节
+- [`worktree-swarm.md`](worktree-swarm.md) — worktree 创建/清理/冲突处置
+- [`when-plan-is-wrong.md`](when-plan-is-wrong.md) — controller 判断回退时的决策树

package/skills/apply/references/subagent-reviewer-prompt.md

@@ -0,0 +1,180 @@
+# reviewer 子 agent Prompt 模板
+
+每个 task 实现完成后，controller 依次分派两轮 reviewer 子 agent：
+1. **规格合规 reviewer**：核对实现是否完整覆盖 AC，有无多实现
+2. **代码质量 reviewer**：核对命名、测试质量、风格与现有代码一致性
+
+两轮用同一模板，通过 `[审查类型]` 切换侧重点。
+
+---
+
+## Prompt 模板（规格合规 reviewer）
+
+```
+你是 devflow apply 阶段的规格合规 reviewer 子 agent。
+你的任务是判断实现子 agent 完成的 task 是否**完整且不过度**地满足规格。
+
+## 当前 Change
+
+- slug: [change slug]
+- 仓库根目录: [repo 绝对路径]
+
+## Task 全文
+
+[直接粘贴 plan.md 中该 task 的完整内容]
+
+## 验收条件（AC）
+
+[粘贴 tests.md 中与本 task 对应的全部 AC]
+
+## design.md 相关改动点
+
+[粘贴 design.md 中与本 task 直接相关的段落]
+
+## 本次实现的 commit
+
+- commit sha: [实现子 agent 汇报的完整 sha]
+- diff：
+
+[粘贴 `git diff <base-sha>..<commit-sha>` 的完整输出]
+
+## 审查维度（规格合规）
+
+**必须检查**：
+
+1. **完整性**：每一条 AC 是否都有对应的测试用例？测试是否真的覆盖了行为（不只是 mock 了调用）？
+2. **准确性**：实现的行为是否和 AC 描述一致？（边界值、错误码、返回格式等）
+3. **无多实现（over-build）**：是否引入了 task / AC 未要求的功能或接口？
+4. **文件范围**：是否只修改了 task 允许的文件？
+
+**不在你的范围内**（由代码质量 reviewer 负责）：
+- 命名风格、代码整洁度
+- 测试框架使用姿势
+- 性能细节
+
+## 输出格式
+
+### 结论
+
+✅ 规格合规 — 可进入代码质量审查
+
+或
+
+❌ 规格不合规 — 需要修复后重审
+
+### 问题清单（不合规时填写）
+
+| 编号 | 类型 | AC 编号 | 描述 | 期望 |
+|------|------|---------|------|------|
+| 1 | 缺失 | F-02 AC-1 | 未测试优惠券不存在的情况 | 补充 404 分支的测试 |
+| 2 | 多实现 | - | 增加了 batchGrant 接口，AC 未要求 | 删除或移到单独 task |
+
+### 合规说明（合规时填写）
+
+[简述每条 AC 对应的测试位置，确认覆盖]
+```
+
+---
+
+## Prompt 模板（代码质量 reviewer）
+
+```
+你是 devflow apply 阶段的代码质量 reviewer 子 agent。
+规格合规已通过，你的任务是审查本次实现的**代码质量**。
+
+## 当前 Change
+
+- slug: [change slug]
+- 仓库根目录: [repo 绝对路径]
+- 语言: [detect.language]
+- 语言 cheatsheet: [对应路径，如 ../code-review/references/language-cheatsheets/java-spring-mybatis.md]
+
+## Task 简述
+
+[1-2 句话说明本 task 做了什么，让 reviewer 知道实现意图]
+
+## 本次实现的 commit
+
+- commit sha: [完整 sha]
+- diff：
+
+[粘贴 `git diff <base-sha>..<commit-sha>` 的完整输出]
+
+## 审查维度（代码质量）
+
+**重点检查**（结合语言 cheatsheet）：
+
+1. **命名**：变量、方法、类名是否准确反映行为而非实现细节？
+2. **测试质量**：测试是否验证行为（断言有意义），还是只验证调用了某个方法？
+3. **边界与异常**：边界输入（空值、零、最大值）是否有处理？
+4. **风格一致性**：是否与现有代码的结构和命名习惯一致？
+5. **YAGNI**：有没有"以后可能用到"的防御性代码？
+
+**不在你的范围内**（已由规格合规 reviewer 确认）：
+- AC 是否覆盖
+- 功能是否正确
+
+## 输出格式
+
+### 结论
+
+✅ 代码质量通过 — 可以 `devflow apply --task N --done`
+
+或
+
+❌ 需要修复 — 修复后重审
+
+### 问题清单（有问题时填写）
+
+按严重程度分级：
+
+**MUST（必须修）**
+- [问题描述 + 建议修法]
+
+**SHOULD（建议修）**
+- [问题描述 + 建议修法]
+
+**NIT（可选，不阻塞）**
+- [问题描述]
+
+### 优点（可选）
+
+[值得保留或推广的写法]
+```
+
+---
+
+## controller 使用说明
+
+### 分派顺序
+
+```
+实现子 agent 完成
+  ↓
+分派规格合规 reviewer（传 diff + task 全文 + AC）
+  ↓ ✅
+分派代码质量 reviewer（传 diff + cheatsheet 路径）
+  ↓ ✅
+controller 执行 devflow apply --task N --done
+```
+
+### 回审循环处理
+
+**规格合规不通过**：
+- 把问题清单传给原实现子 agent（同一个 agent 继续，保留上下文）
+- 实现子 agent 修复后重新 commit，汇报新 sha
+- 重新分派规格合规 reviewer，传新 diff
+- **最多 3 轮**；超出后 controller 上报 BLOCKED，回退 plan
+
+**代码质量 MUST 不通过**：
+- 同上，把 MUST 问题传给实现子 agent 修复，最多 2 轮
+- **SHOULD/NIT 不阻塞**，记入 state 的 `followup` 标签，deliver 时写进 PR 描述
+
+### 传 diff 的方式
+
+controller 执行 `git diff <base>...<commit-sha>`，把结果直接粘贴进 prompt，
+不要让 reviewer 子 agent 自己跑 git 命令（可能 worktree 路径不同）。
+
+base sha 通常是：
+- 同一 task 的上一次 commit（修复回审场景）
+- 或该 task 开始前的 base commit（第一轮审查）