@chenguangyao/devflow-kit 0.1.43

package/skills/code-review/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: devflow-code-review
+description: |
+  devflow-kit 流程中，当用户提及 "代码审查"、"Code Review"、"CR"、"代码检视"、"代码走查"、"review 代码"、"审一下代码",
+  或 apply 阶段产出代码后需要质量把关时,必须立刻触发本 skill。独立 reviewer 视角,基于 design.md /
+  requirement.md / tests.md(若存在) / plan.md 的测试字段逐项核对代码实现,产出结构化审查结论与 feedbackIssues 供下一轮 apply 修复。
+  若用户意图是整体开发流程,由 `devflow-df-orchestrator` 统一编排;若只需单独执行这一步,直接触发本 skill。
+when_to_use: |
+  apply 阶段的所有任务已 done、单元测试已跑过(`devflow test unit` 产出 `reports/test-report.md#unit`)之后,
+  由 `devflow review --round` 或 `/df:review` 触发。也可以在 bugfix 轮次(iteration N>0)重复触发。
+---
+
+# code-review
+
+独立代码审查 skill。3 轮硬闭环,每轮产 structured findings;MUST > 0 → 回 apply;round 3 若仍 MUST > 0 → hard-block(需 `--force-pass --reason` 审计放行)。
+
+## 独立审查身份(硬规则)
+
+- 本 skill 以**独立 reviewer** 身份执行,上下文隔离于 apply 过程,模拟"换人审查"。
+- Reviewer **不参考** coding agent 的对话历史、不认同 coder 自述的"我这么写是因为…",仅基于:
+  - `git diff <baseBranch>...HEAD` 的实际代码
+  - `design.md`(实现契约)
+  - `requirement.md`(功能与边界契约)
+  - `tests.md`(若存在)或 `plan.md` 每个 task 的 Test 字段
+  - `reports/test-report.md#unit`(自测结果,如有)
+- 若上一轮 review 已留 findings,本轮**继承未 resolved 项**并聚焦复核。
+
+## 前置检查(任一必需项缺失则停止并询问用户)
+
+| 输入项 | 必需 | 缺失时行为 |
+| --- | --- | --- |
+| 代码变更(git diff) | 是 | 停止并要求用户提供 baseBranch 或确认不在 git worktree |
+| `design.md` | 是(L2/L3)/ 可选(L1) | L1 bug fix 若无 design.md 可用 `requirement.md` + diff 进行;L2/L3 缺失直接 BLOCKED |
+| `requirement.md` | 是 | 缺失直接 BLOCKED(无法做需求覆盖度扫描) |
+| `tests.md` | 可选 | 存在时做 TC 对照；缺失时用 plan.md 的 Test 字段和 requirement.md 的 AC 做覆盖检查 |
+| `reports/test-report.md#unit` | 否 | 若存在,相信其 PASS 结果,只复核 FAIL 与未覆盖项 |
+| `baseBranch` | 否 | 默认 `master` / `main`,自动探测;可由 `devflow apply` 的 worktree 元数据传入 |
+| `iterationCount` | 否 | 由 `state.json.phases.review.rounds.length` 推导;第 1 轮起算 |
+
+## Step 0：先跑工具（必须在 AI 审查前）
+
+> **核心原则**：工具能自动发现的问题不让 AI 重新发现 —— AI 专注工具覆盖不到的地方。
+
+```bash
+# 1. 获取变更列表
+git diff --name-only <baseBranch>...HEAD
+
+# 2. 按语言运行已有工具（用项目里现有配置，不要新装）
+# Go
+golangci-lint run ./... 2>&1
+go vet ./... 2>&1
+
+# Java
+mvn checkstyle:check 2>&1 | tail -30  # 或 ./gradlew checkstyleMain
+mvn compile 2>&1 | grep -E "ERROR|WARNING" | tail -20
+
+# Node / TypeScript
+npx eslint . --max-warnings=0 2>&1 | tail -30
+npx tsc --noEmit 2>&1 | tail -20
+
+# Python
+ruff check . 2>&1 | tail -30  # 或 flake8/pylint
+mypy . 2>&1 | tail -20
+```
+
+**工具输出处理规则：**
+- 工具报 0 错误 → 直接跳过该维度，不重复检查
+- 工具报错误 → 列入 findings（标注 `source: tooling`），不需要 AI 再分析原因
+- NIT 级别的 style issue，工具输出即结论，AI 不重复描述
+
+**AI 审查只覆盖工具盲区：**
+
+| 维度 | 工具能覆盖 | AI 额外覆盖 |
+| --- | --- | --- |
+| 语法 / 格式 / 命名 | ✅ linter/formatter | 仅工具未覆盖的语义命名 |
+| 类型安全 | ✅ type-checker | 业务类型语义是否合理 |
+| 需求覆盖度 | ❌ | **全部由 AI** |
+| 设计 / 契约对齐 | ❌ | **全部由 AI** |
+| 业务逻辑正确性 | ❌ | **全部由 AI** |
+| 安全（注入 / 泄漏） | 部分 semgrep | AI 补充业务特定风险 |
+| 并发 / 事务边界 | ❌ | **全部由 AI** |
+
+若项目没有配置 linter，在 `review.md` 开头注明 `linting: unconfigured`，建议补配置，然后 AI 按全维度扫。
+
+## 代码获取方式
+
+优先通过 git diff 获取本次变更,不要读全量文件 —— review 只关注改动:
+
+```bash
+git diff --name-only <baseBranch>...HEAD   # 文件列表
+git diff <baseBranch>...HEAD               # 带上下文的变更内容
+```
+
+若当前不在 git worktree(如 `--no-worktree` 模式),从 `state.json.phases.apply.tasks[].files` 读取 coder 声明的改动文件清单。
+
+## 变更范围分类(节 token,跳过不相关步骤)
+
+按 `git diff --name-only` 的文件列表判定变更范围,只跑相关检查:
+
+| 变更范围 | 判定条件(示例) | 跳过的子检查 |
+| --- | --- | --- |
+| `data-layer` | 仅 SQL / migration / schema / ORM mapper | 跳过 UX / 前端契约 / 性能基线 |
+| `test-only` | 仅 `*_test.*` / `test/**/*` / `spec/**` | 仅做"测试代码质量 + 断言有效性"检查 |
+| `api-change` | 含 Controller / Handler / Route / DTO / Request / Response / OpenAPI | 执行全部维度 |
+| `config-only` | 仅 `*.yaml` / `*.toml` / `*.env` | 只做"配置漂移 + 环境一致性"检查 |
+| `docs-only` | 仅 `*.md` / `docs/**` | 只做"文档与代码/接口一致性"检查,不跑代码检查 |
+| `full` | 其他(跨多层) | 执行全部维度 |
+
+规则:按文件列表匹配,**取最宽的范围**;无法判定默认 `full`。
+
+## 审查维度(按这 7 个维度逐项检查)
+
+| 维度 | 关注点 | 详见 |
+| --- | --- | --- |
+| Correctness | 实现是否符合 design.md?业务逻辑、边界、并发 | `references/review-checklist.md` §1 |
+| Completeness | requirement.md 的 BEHAVIOR / EDGE CASES 每条都有代码 + 测试? | `references/review-checklist.md` §2 |
+| Security | 输入校验、鉴权、密钥、日志脱敏、资源泄漏 | `references/review-checklist.md` §3 |
+| Performance | 明显的 N+1 / O(N²)、无界循环、不必要的同步阻塞 | `references/review-checklist.md` §4 |
+| Maintainability | 命名、注释、魔法值、重复、职责单一、长函数 | `references/review-checklist.md` §5 |
+| Tests | 用例 ↔ tests.md 一一对照;断言有效;Mock 合理;无 skip/only | `references/review-checklist.md` §6 |
+| Observability / Migration | 日志 / 指标 / 告警 / DDL 可重入 / 回滚预案 | `references/review-checklist.md` §7 |
+
+> 不要在 SKILL.md 里重复这些检查项的具体条目 —— 审查时打开 `references/review-checklist.md` 按维度逐项打勾。
+
+## 按项目语言自动加载 cheatsheet(全语言支持)
+
+通用 checklist 是语言无关的骨架。每门语言还有自己的踩坑习语,放在 `references/language-cheatsheets/*.md`。reviewer 必须按下面规则**挑选 1-2 份** cheatsheet 一起读(不相关的不要加载,节 token)。
+
+### 挑选规则
+
+1. 读 `devflow/config.json` 的 `detect.language`(由 `devflow init` 写入)拿初始语言。
+2. 再看本次 `git diff --name-only` 的文件扩展名,若变更涉及多种语言(monorepo),每种语言各加载一份 cheatsheet。
+3. 同一语言内再按下面"二级判定"选具体 cheatsheet 版本(框架差异大的才分叉):
+
+| detect.language | 二级判定信号(文件 / 依赖) | 挑选 cheatsheet |
+| --- | --- | --- |
+| `java` | `pom.xml` 或 `build.gradle` 含 `mybatis` / `*Mapper.xml` 文件存在 | `java-spring-mybatis.md` |
+| `java` | 含 `spring-data-jpa` / `hibernate` / `@Entity` 广泛使用 | `java-spring-jpa.md`(暂未提供 → 先用 `java-spring-mybatis.md` §1/§4/§5/§6/§7/§8,跳 §2/§3) |
+| `go` | 任何情况 | `go.md` |
+| `python` | 任何情况(Django / FastAPI / Flask 共用一份) | `python.md` |
+| `node` | `package.json` 的 `dependencies` 含 `vue` | `vue.md` |
+| `node` | 含 `react` | (暂未提供 → 仅用通用 checklist,在 findings 里标注 `cheatsheet_missing: react`) |
+| `node` 纯后端(express / nestjs / koa) | 无前端框架依赖 | (暂未提供 → 仅用通用 checklist,标注 `cheatsheet_missing: node-backend`) |
+| 其他 / `unknown` | — | 仅用通用 checklist;在 `review.md` 开头 note 语言未识别 |
+
+### 多语言组合例子
+
+- 一个 Vue 前端 + Go 后端 monorepo,本轮 diff 涉及 `src/**/*.vue` 和 `server/**/*.go`:同时加载 `vue.md` + `go.md`。
+- 一个 Java 后端项目,本轮 diff 只改了 `*.sql` + `*Mapper.xml`:只加载 `java-spring-mybatis.md`(通用 checklist 用 `data-layer` diffScope 跳过无关维度)。
+- 一个 FastAPI + Vue 的项目:`python.md` + `vue.md`,各自按维度报告。
+
+### cheatsheet 缺失时
+
+在 `review.md` 开头加一段:
+
+```markdown
+> [!NOTE] Language cheatsheet missing: <lang>
+> 本次审查未找到 `<lang>` 的 cheatsheet,仅按通用 checklist 进行。
+> 建议后续补充至 `skills/code-review/references/language-cheatsheets/<lang>.md`。
+```
+
+并在 `review.findings.json` 的 top-level 加 `cheatsheetMissing: ["<lang>"]` 字段,方便 `devflow doctor audit` 统计。
+
+### 禁止反模式
+
+- **把所有 cheatsheet 一起加载**:极度浪费 token;且无关语言的条目会诱导 reviewer 误报 finding。
+- **忽略 cheatsheet 直接按通用 checklist**:会漏掉语言特有的高危坑(如 Go nil interface、Java MyBatis 全链路、Python 可变默认参数、Vue ref 漏 .value)。
+- **自己临时"加一条规则"而不先查 cheatsheet**:reviewer 的个人习惯不应取代沉淀;如确实发现新坑,记录到下次 cheatsheet 更新。
+
+## 严重度(MUST / SHOULD / NIT,`devflow review` 只识别这三个词)
+
+| 级别 | 含义 | 处理要求 | fixMode |
+| --- | --- | --- | --- |
+| **MUST** | 阻塞:正确性 / 安全 / 数据丢失 / 契约破坏 / 需求覆盖缺失 / 状态值不一致 | 必须修复才能通过 | 通常 REVIEW |
+| **SHOULD** | 严重:风险 / 可维护性 / 性能 / UX 降级 | 强烈建议修;本轮可以降级放行,但要写 "accepted with justification" | 常见 REVIEW,少量 AUTO-FIX |
+| **NIT** | 一般:风格、命名、排版 | 可选修;连续 3 轮仍未修由 reviewer 决定去留 | AUTO-FIX |
+
+判定矩阵与实例见 `references/review-checklist.md` §严重度速查。
+
+## 3 轮闭环 CLI 契约
+
+```
+round 1   devflow review --slug=<slug> --round
+  ↳ MUST > 0 → outcome=back_to_apply  → phases.apply.status=in_progress,去 apply 修
+  ↳ MUST = 0 → outcome=pass           → phases.review.status=completed,创建 verify_start 检查点,等待用户确认
+
+round 2   devflow review --slug=<slug> --round
+  ↳ 同上逻辑,MUST 计数继承 round 1 未 resolved 项 + 本轮新发现
+
+round 3   devflow review --slug=<slug> --round
+  ↳ MUST > 0 → outcome=BLOCKED, exit 1
+               三选一:
+               a) 回 apply 修复后 `devflow review --slug=<slug> --round --continue-rounds`    (审计)
+               b) `devflow review --slug=<slug> --force-pass --reason="..."`                  (审计)
+               c) 回 tech-spec 重设计 design.md(多半是设计缺陷,见下)
+```
+
+`devflow review --round` 读 `review.md`:解析 `MUST` / `SHOULD` / `NIT` 字面出现次数(大小写敏感,表格行内出现计数);也可以 headless `--must=N --should=M --nit=K` 手动给。
+
+## 输出契约
+
+审查产物分两个文件,不可合并:
+
+1. **`review.md`** —— 每轮 append 一个 section(Round N),**人类可读**。模板见 `references/output-template.md` §1。
+2. **`review.findings.json`** —— 机器可解析,`state.json` 里 `phases.review.rounds[N].findingsPath` 指向它。**下一轮 apply 用它自动定位修复位置**。Schema 见 `references/output-template.md` §2。
+
+`devflow review --round` 保证两者同步写入,丢一个就报 inconsistency。
+
+## 引爆路径(超出 3 轮怎么办)
+
+**同一 MUST 跨 2 轮复现 ≠ coder 没改**,更可能是 design 本身漏了 —— 别再迭代 apply,回 tech-spec 重开一轮。
+
+完整路径(设计缺陷 / 需求偏差 / reviewer-applier 冲突)见 `references/escalation-playbook.md`。
+
+## 反模式(踩了直接 back_to_apply 或 BLOCKED)
+
+- **带着未 resolved MUST 盖 `pass`**:用 `--force-pass --reason="..."` 走审计,不要作弊改 `state.json`。
+- **只看 diff,不比对 `design.md` / `requirement.md`**:会漏掉"要求做但没做"这一类最危险的缺失。
+- **跳过 2.6 需求覆盖度扫描**(见 `references/review-checklist.md` §2):会放过隐性遗漏。
+- **用第 4 轮 review**:没有 `--continue-rounds` 会被 CLI 拒绝。第 4 轮意味着之前的评审没抓住要害 —— 先反省。
+- **把 MUST/SHOULD/NIT 当叙事词写进正文**:`devflow review` 会把散文里的 "should" / "must" 也计数;只在 findings 表格的 `level` 列用它们,其他地方用小写。
+- **在 docs-only 变更里逐行审代码**:变更范围分类就是为了避免这种无意义 token 消耗。
+
+## 完成状态协议
+
+执行完毕必须输出(被 df-orchestrator 解析):
+
+```
+---STATUS---
+result: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_INPUT
+outputs:
+  - devflow/changes/<slug>/review.md
+  - devflow/changes/<slug>/review.findings.json
+round: N
+mustCount: K
+shouldCount: K
+nitCount: K
+outcome: pass | back_to_apply | blocked | force-pass
+---END_STATUS---
+```
+
+**下一步卡片（硬约束）**：
+
+每一轮 review 结束，都必须在用户可见正文最后展示下一步卡片。不能只列 findings、变更和校验，不能只写 `---STATUS---`，也不能让用户猜下一步。
+
+```markdown
+## 下一步
+状态：DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_INPUT
+审查结果：pass | back_to_apply | blocked | force-pass
+下一步：[一句话说明]
+命令：`<nextAction command>`
+需要你确认：[是否开始 verify / 是否回 apply 修复 / 是否接受风险放行 / 需要补充的信息]
+```
+
+按 outcome 填写：
+
+- `pass`：说明 review 已通过，但不得自动执行 verify；状态填 `NEEDS_INPUT`，等待用户在**本轮 review 通过之后**明确确认是否允许进入验证。命令只写：`devflow checkpoint resolve --id=<checkpoint-id> --decision=start-verify`。不得把它和 `devflow verify --slug=<slug>` 串成一条命令。
+- `back_to_apply`：列出 MUST / SHOULD 摘要，下一步回 apply 修复；命令：`devflow apply --slug=<slug> --task=<id> --resume` 或 `devflow apply --slug=<slug> --task=<id> --note="fix review findings"`。
+- `blocked`：不要给推进命令；必须说明解除阻塞的最小动作，例如补齐 design/tests、修复无法运行的检查、回 tech-spec 重设计。
+- `force-pass`：必须列出已接受风险和审计原因；仍然不得自动执行 verify，等待用户在 force-pass 之后重新确认；命令只写：`devflow checkpoint resolve --id=<checkpoint-id> --decision=start-verify`。不得把它和 `devflow verify --slug=<slug>` 串成一条命令。
+
+**verify_start 确认硬规则**：
+
+- 早前在 apply / plan / requirement 阶段说过的"继续"、"按推荐"、"剩余按推荐"、"继续吧"，不能被复用为 review 通过后的 verify 确认。
+- 用户必须在本轮 review pass / force-pass 的下一步卡片出现之后，重新明确回复"开始验证"、"确认进入 verify"、"允许 verify"或执行 checkpoint resolve 命令。
+- 在收到上述新确认前，agent 只能展示下一步卡片或运行 `devflow status`，不得调用 `devflow verify`、`devflow test`、Jenkins、部署或任何验证动作。
+- 即使用户回复"继续"，也只能执行 `devflow checkpoint resolve --id=<checkpoint-id> --decision=start-verify`；resolve 完成后必须再次停止并提示下一条命令 `devflow verify --slug=<slug>`，不能在同一轮继续执行。
+
+## 参考
+
+- [`references/review-checklist.md`](references/review-checklist.md) — 7 维度逐项清单 + 正反例 + 严重度判定矩阵
+- [`references/output-template.md`](references/output-template.md) — `review.md` 每轮模板 + `review.findings.json` schema + `code-review-report.md` 规范
+- [`references/escalation-playbook.md`](references/escalation-playbook.md) — 超轮 / 设计缺陷 / reviewer-applier 冲突的处置流程
+- [`references/language-cheatsheets/`](references/language-cheatsheets/) — 按语言挑选 1-2 份一起读:
+  - `java-spring-mybatis.md` — Java + Spring Boot + MyBatis(含 DDL-DO 一致性、全链路字段、@Transactional 坑、JUnit 5 + Mockito)
+  - `go.md` — Go(nil 安全、goroutine 泄漏、context、gorm/sqlc、testify)
+  - `python.md` — Python(可变默认参数、asyncio、SQLAlchemy / Django ORM、pytest、FastAPI / Django / DRF)
+  - `vue.md` — Vue 3 + TypeScript(响应性、Composition API、Pinia、路由鉴权、Vitest)
+  - 其他语言(React / Rust / Node 纯后端等)按"挑选规则"章节处置,按需补充

package/skills/code-review/references/escalation-playbook.md

@@ -0,0 +1,192 @@
+# code-review / escalation-playbook
+
+3 轮是硬上限。大部分任务在第 2 轮就该收敛。如果 MUST 还在冒出来,**问题不在 coder**,先按本文诊断根因,对应升级处置。
+
+---
+
+## 什么时候走这个 playbook
+
+下面任一信号出现,立即停下当前 review,按对应 path 走:
+
+| 信号 | 根因分类 | 处置 path |
+| --- | --- | --- |
+| round 1 MUST=0、round 2 MUST>0 又冒出一批新的 | 需求理解偏差 | path A |
+| 同一 MUST 或等价问题跨 2 轮都没修掉 | 设计缺陷或 coder 能力/上下文不足 | path B |
+| round 3 结束仍有 MUST | 上面两类之一的终局 | path C |
+| reviewer 与 coder 对"是不是 MUST"反复争论 | reviewer-applier 冲突 | path D |
+| MUST 里有 `fixMode: SPEC` 超过 1 项 | 方案问题 | path B |
+
+---
+
+## Path A:需求理解偏差 —— 回 requirement.md
+
+### 识别
+
+- 新发现的 MUST 集中在 `dimension: completeness` 或"实现不符合 requirement.md"
+- coder 在 `apply.md` 里说"这段是按需求 X 做的",但 requirement.md 根本没明确
+- 代码实现的业务规则与 QA / PM 读 requirement.md 的理解不一致
+
+### 处置步骤
+
+1. **暂停 review**,outcome 置 `back_to_apply` 但附加 `reason: "requirement_ambiguous"`。
+2. 在 `review.md` 当前 round 末尾加一个 `## 需求澄清请求` section,列出所有 ambiguous 的点。
+3. 回到 intake / brainstorming 阶段:
+
+   ```
+   devflow status                          # 确认当前在 review
+   devflow brainstorming --from review     # 把 review 里的澄清请求作为 input 重启 brainstorming
+   ```
+
+4. brainstorming 产出新的 `requirement.md`(增量 delta),由 df-orchestrator 决定是否需要重跑 tech-spec。
+5. 回到 apply 继续,`iterationCount` 不自增(因为这一轮不算 coder 的问题)。
+
+### 防御:下次避免
+
+- requirement.md 里每条 BEHAVIOR / EDGE CASE 都要有可验证的断言(例子:"超 100 次/天 → 返回 429" 而不是"不能被刷")。
+- brainstorming 阶段用 clarifying questions 强制暴露 ambiguous 项;arb 的 L1/L2/L3 复杂度分级就是为此,复杂度高的强制 clarification rounds ≥ 2。
+
+---
+
+## Path B:设计缺陷 —— 回 tech-spec / design.md
+
+### 识别
+
+- 同一 MUST 在 round 2 仍未 resolved,且 coder 在 apply.md 里写"按原设计改不过去"
+- findings 里出现 `fixMode: SPEC` ≥ 1
+- MUST 集中在 `dimension: correctness` 的"并发 / 事务 / 接口契约"
+- 修一个问题引出另外两个问题(改 A 崩 B)—— 模块职责 / 依赖关系本身有问题
+
+### 处置步骤
+
+1. **暂停 review**,outcome 置 `blocked`,在 `review.md` 写 `## 设计回退请求`。
+2. 收集 evidence:所有跨轮复现或 `fixMode: SPEC` 的 finding ID。
+3. 回到 tech-spec 阶段:
+
+   ```
+   devflow tech-spec --revise --from review
+   ```
+
+   这个命令会把当前 `design.md` 移到 `design.v1.md`(保留历史),并以 review findings 为输入重新产出 `design.md`(v2)。
+
+4. 新设计评审通过后,回到 plan 阶段:
+
+   ```
+   devflow plan --redo              # 根据 design v2 重新出 tasks.md,已完成的任务保留 done 状态
+   devflow apply                    # 从头跑,review 计数归零(新设计是新 review context)
+   ```
+
+5. 归档时两个 design 版本都保留在 `archive/<slug>/` 里,作为学习素材。
+
+### 防御
+
+- tech-spec 产出时要强制"并发 / 事务 / 接口契约"三项的显式设计(而不是默认值)。
+- design.md 的"决策记录"section 要写明 trade-off,避免 coder 只能猜。
+
+---
+
+## Path C:round 3 结束仍有 MUST —— hard block,3 选 1
+
+### 处置步骤
+
+`devflow review --round` 在 round 3 发现 MUST>0 会直接 exit 1。三种合法放行方式:
+
+### C.1 回 apply 再修,但要用 `--continue-rounds`(审计)
+
+```
+devflow review --round --continue-rounds
+```
+
+- 这会开第 4 轮及以后,**每一轮都写进 state.json 的 audit log**。
+- 仅当 MUST 已知、范围收敛、预期一轮内能修完时用。
+- `state.json.phases.review.audit[]` 里会多一条 `{ type: "continue-rounds", reason, operator, at }`,PR 里也会强制展示。
+
+### C.2 接受 MUST 放行(`--force-pass --reason`)
+
+```
+devflow review --force-pass --reason="CR-102 已在 hotfix 分支单独上线,此处只做回刷"
+```
+
+- reason 必填且 ≥ 10 字符;
+- 审计同上,进入 PR description 永久留档;
+- `finalOutcome=force-pass`,下游 verify/deliver 不会再次拦截,但会在 PR 模板里自动挂 `needs-post-merge-followup` 标签。
+
+### C.3 回 tech-spec(最保险 / 最慢)
+
+走 Path B 流程。这条适合:不确定是设计还是实现问题、MUST 覆盖面 ≥ 3 个维度。
+
+### 选择依据
+
+| 情况 | 选 |
+| --- | --- |
+| 只剩 1-2 个 MUST,定位清晰,改法确定 | C.1 |
+| MUST 范围失控,coder 每修一轮都引入新问题 | C.3 |
+| 明确是边缘场景,风险低或已有 mitigation | C.2 |
+| reviewer 与 coder 反复争论 MUST/SHOULD 边界 | Path D 先 |
+
+---
+
+## Path D:reviewer-applier 冲突
+
+### 识别
+
+- coder 在 `apply.md` 里对 finding 反复标 `resolved: true`,reviewer 反复标回 `resolved: false`
+- `review.md` 的"上轮问题修复情况"里,coder 与 reviewer 对同一 ID 描述完全不同
+- 同一 finding 两轮都存在,coder 坚持"已经按建议改了",reviewer 坚持"没改或改错了"
+
+### 处置步骤
+
+1. **停止迭代**,不要再自动 back_to_apply。
+2. 在 `review.md` 当前 round 写 `## 评审分歧` section,逐 ID 列:
+   - coder 的立场(引用 apply.md 原文)
+   - reviewer 的立场(引用本 skill 的 checklist 哪一条)
+   - 物证(git diff 片段 / 测试运行结果)
+3. 触发"第三视角"复核:
+
+   ```
+   devflow review --arbitrate --finding-id=CR-xxx
+   ```
+
+   这会以全新上下文(不带 coder 也不带上轮 reviewer 的历史)再看一次,仅基于 diff + checklist + reason。
+
+4. arbitrate 输出三种结果之一:
+   - **uphold**:维持 reviewer 判定 → 继续 back_to_apply
+   - **overrule**:reviewer 判定错误 → 自动把该 finding 改为 resolved,reviewer 这一轮记一条"误判"
+   - **downgrade**:MUST 降级为 SHOULD → 同轮 MUST 计数减 1
+
+5. 仲裁结果进入 `state.json.phases.review.arbitrations[]`,PR description 里展示。
+
+### 防御
+
+- review-checklist.md 的每个"检查点"都配了"反例 / 正例 / 判定"三栏,reviewer 要用原文引用做判定依据,而不是个人偏好。
+- coder 在 apply 里 resolve 一个 finding 时,必须引用 `review.findings.json` 的 ID + 在 `apply.md` 里贴 diff snippet 说明"怎么改的",避免纯口头声明。
+
+---
+
+## 统计:防止陷入"review 循环消耗"
+
+3 轮上限不是拍脑袋定的。经验数据:
+
+| 现象 | 成因 | 解决方向 |
+| --- | --- | --- |
+| 持续 MUST 冒出 | 需求 / 设计问题 | Path A / B |
+| 总 MUST 数逐轮递减但>0 | coder 能力匹配,多给 1-2 轮通常就能收敛 | C.1 |
+| MUST 数逐轮反而递增 | 问题不在代码层 | C.3 强制 |
+| 同一 MUST 跨轮复现 | 设计或沟通缺陷 | B / D |
+
+**90% 以上的任务在 round 2 应该 pass**。如果你的项目 round 3 出现频率 > 20%,可能是:
+
+- requirement / design 阶段的 clarifying 不充分 —— 调 brainstorming / tech-spec 的 L2/L3 清单;
+- reviewer 判定尺度过严 —— 回顾 review-checklist.md 的严重度速查,把过多 "NIT 升 SHOULD" 的习惯改掉;
+- coder 上下文给得不够 —— 在 apply 阶段把 design.md / checklist 作为 system prompt 强制注入。
+
+---
+
+## 审计 / 留档
+
+所有 escalation 都在:
+
+- `state.json.phases.review.audit[]` —— 结构化 log
+- `review.md` 当前 round 的 `## 设计回退请求` / `## 需求澄清请求` / `## 评审分歧` section
+- PR description(`devflow deliver` 自动聚合)—— reviewer 无法再通过重命名文件绕过
+
+`devflow doctor audit` 会扫描所有 change 的 review audit log,对 "force-pass 比例 > 10%" 或 "continue-rounds 比例 > 20%" 发出警告,用于团队侧的质量回溯。

package/skills/code-review/references/language-cheatsheets/go.md

@@ -0,0 +1,175 @@
+# Language Cheatsheet — Go
+
+配套 `review-checklist.md` 使用。通用 checklist 告诉你"要找什么",本 cheatsheet 告诉你"在 Go 项目里长什么样"。
+
+适配栈:`net/http` / `gin` / `echo`、`gorm` / `sqlc` / `sqlx`、`go-redis`、`golang/sync`、`context`、`testify` / `gomock`。
+
+---
+
+## §1 nil 安全(最常见 panic 来源)
+
+| 检查点 | 反例 | 正例 | 判定 |
+| --- | --- | --- | --- |
+| nil map 写入 | `var m map[string]int; m["a"] = 1` → panic | `m := make(map[string]int)` 或字面量初始化 | **MUST** |
+| nil slice append | 读是安全的,但 `len(s)` / `s[0]` 崩 | 字面量 / `make([]T, 0, cap)` | 下标访问 **MUST** |
+| nil interface ≠ nil pointer | `var p *Foo; var i Foo = p; i != nil` 为 true(陷阱) | 返回 `error` 时 `return nil`,不要返回 `return myErr`(myErr 是 nil *MyError) | **MUST** |
+| nil channel | close(nil ch) / send 到 nil ch → block/panic | 显式初始化 + close 前检查 ownership | **MUST** |
+| 结构体指针 deref | `user.Profile.Name`(Profile 可能 nil) | 显式 nil check 或 Option 模式 | **MUST** |
+| 错误 type assertion | `err.(*MyError).Code`(err 为 nil → panic) | `var e *MyError; if errors.As(err, &e) { ... }` | **MUST** |
+
+---
+
+## §2 goroutine 泄漏 / 生命周期(最隐蔽的生产事故源)
+
+| 检查点 | 反例 | 正例 | 判定 |
+| --- | --- | --- | --- |
+| goroutine 无退出条件 | `go func() { for { work() } }()` | 带 `context.Done()` / `quit chan` | **MUST** |
+| fire-and-forget 无 recover | `go func() { panic(x) }()` 直接干掉进程 | 顶层 `defer recover()` + log | **MUST** |
+| `time.After` 循环使用 | `select { case <-time.After(t): ...}` 在 for 里,泄漏 timer | `timer := time.NewTimer(t); defer timer.Stop()` | 长 loop **MUST** |
+| `sync.WaitGroup.Add` 位置 | `go func() { wg.Add(1); ... }()` 在 goroutine 内加 | 在启动 goroutine **前**调 `wg.Add(1)` | 竞态 **MUST** |
+| channel 泄漏 | 生产者发完不 close,消费者 for-range 永远等 | producer 独占 close 权 + 显式 close | **MUST** |
+| errgroup / singleflight | 无 | 并发调用用 `errgroup.Group` + first-error-cancel,热点 key 用 `singleflight` | 并发批量 **SHOULD**;缓存穿透场景 **MUST** |
+
+---
+
+## §3 context 传播与取消
+
+| 检查点 | 反例 | 正例 | 判定 |
+| --- | --- | --- | --- |
+| context 断链 | 处理请求时起子 goroutine 传 `context.Background()` | 一直传入参 `ctx`,或派生 `context.WithTimeout(ctx, t)` | **MUST**(取消/超时失效) |
+| context.Value 存业务数据 | `ctx.WithValue(ctx, "user", u)` 当成全局状态 | 只存 request-scoped 元数据(traceId、authUser),不存业务 | **SHOULD** |
+| 对外调用无 timeout | `http.Client{}` 无 Timeout + 无 ctx | 每个 HTTP/DB 调用都有 `context.WithTimeout` | 对外调用无 timeout **MUST** |
+| `ctx.Err()` 忽略 | 长 loop 只 select 业务 chan 不 select ctx.Done | `case <-ctx.Done(): return ctx.Err()` | **MUST** |
+| cancel func 泄漏 | `ctx, _ := context.WithTimeout(...)`(忽略 cancel) | `ctx, cancel := ...; defer cancel()` | **MUST**(timer 泄漏) |
+
+---
+
+## §4 error 处理与 wrapping
+
+| 检查点 | 反例 | 正例 | 判定 |
+| --- | --- | --- | --- |
+| 吞错误 | `_, _ = f()` / `if err != nil { log.Print(err) }`(吞掉 + 继续) | 显式处理或 return | **MUST** |
+| 裸返回 err | `return err` 丢上下文 | `return fmt.Errorf("fetch user %d: %w", id, err)` | 生产排障困难 **SHOULD** |
+| `==` 比较错误 | `if err == sql.ErrNoRows`(包装后 false) | `errors.Is(err, sql.ErrNoRows)` | **MUST** |
+| type assertion 不用 errors.As | `e, ok := err.(*MyErr)`(wrap 后 false) | `var e *MyErr; errors.As(err, &e)` | **MUST** |
+| `panic` 作业务错 | handler 里 panic 做控制流 | 只在真·不可恢复状态 panic | **MUST** |
+| 业务错误码 | 用字符串判 err.Error() == "not found" | 定义 sentinel `var ErrNotFound = errors.New(...)` + `errors.Is` | **SHOULD** |
+| 错误分级 | 所有错都 log.Error | 业务可预期错 Info/Warn、系统错 Error | **NIT** |
+
+---
+
+## §5 defer / 资源关闭 / panic recover
+
+| 检查点 | 反例 | 正例 | 判定 |
+| --- | --- | --- | --- |
+| 忘关资源 | `rows, _ := db.Query(...)`(不 close) | `defer rows.Close()`(紧随获取) | **MUST**(连接泄漏) |
+| loop 里 defer | `for { f, _ := os.Open(x); defer f.Close() }` defer 到函数退出才执行 | 包装成独立函数或 `func() { defer; ... }()` | **MUST**(句柄泄漏) |
+| defer 捕获变量 | `defer log.Print(x)` x 取值在声明时 vs `defer func() { log.Print(x) }()` 在执行时 | 明确需要哪种 | 语义错 **MUST** |
+| panic 炸 HTTP server | handler 没 recover 中间件 | `gin.Recovery()` / 自定义 recover + log + 500 | **MUST** |
+| defer 操作 err | `defer rows.Close()` 忽略 close 错误 | 需要时聚合 err(多 return 合并) | **SHOULD** |
+
+---
+
+## §6 ORM / 数据库
+
+### 6.1 GORM
+
+| 检查点 | 反例 | 正例 | 判定 |
+| --- | --- | --- | --- |
+| N+1 | `db.Find(&users)` 后 for 每人 `db.First(&profile)` | `db.Preload("Profile").Find(&users)` | 线上热点 **MUST**;低频 **SHOULD** |
+| 软删除误开/误关 | model 带 `gorm.DeletedAt` 但预期硬删 | 明确 `Unscoped().Delete(...)` 或去 DeletedAt | 语义错 **MUST** |
+| `Update` 零值陷阱 | `db.Model(&u).Update("age", 0)` 不生效(零值被忽略) | 用 `Select("Age").Updates(...)` 或 `UpdateColumn` | **MUST** |
+| `Save` 全字段更新 | `db.Save(&u)` 覆盖所有字段(含零值) | 改用 `Updates` + 指定字段 | 覆盖数据 **MUST** |
+| AutoMigrate 生产 | 生产代码跑 `AutoMigrate` | 单独 migration 工具(goose / atlas / golang-migrate) | **MUST** |
+| 连接池 | 默认 `SetMaxOpenConns` 不配 | 按 QPS × 响应时间配置 + 监控 | **SHOULD** |
+| `First` vs `Find` | `First(&u)` 找不到返回 `ErrRecordNotFound`,容易漏判 | 统一策略 + `errors.Is(err, gorm.ErrRecordNotFound)` | **SHOULD** |
+
+### 6.2 sqlc / sqlx
+
+| 检查点 | 反例 | 正例 | 判定 |
+| --- | --- | --- | --- |
+| `db.Exec` 忽略 result | 没检查 `RowsAffected` | 关键 UPDATE/DELETE 必检查,配合事务 | **MUST** |
+| 动态 SQL 拼接 | `fmt.Sprintf("... WHERE id=%d", id)` | 预编译 + `$1 / ?` 占位 | **MUST**(SQL 注入) |
+| `rows.Next` 漏 `rows.Err` | 循环后不判错 | `if err := rows.Err(); err != nil { ... }` | **SHOULD** |
+
+### 6.3 事务
+
+| 检查点 | 反例 | 正例 | 判定 |
+| --- | --- | --- | --- |
+| 事务中跨进程调用 | 事务内调 HTTP / 发 MQ(长事务) | 事务外做,或本地消息表 | **MUST** |
+| 嵌套事务 | 多层 `tx.Begin()` 语义混乱 | 只在一处开事务 / savepoint | **MUST** |
+| 事务传播 | goroutine 内重用外层 tx | tx 不要跨 goroutine 共享 | **MUST**(数据竞争) |
+| `defer tx.Rollback()` | 忘写 defer rollback,panic 后 tx 悬挂 | 显式 `defer func() { if err != nil { tx.Rollback() } else { tx.Commit() } }()` | **MUST** |
+
+---
+
+## §7 HTTP handler / 中间件
+
+| 检查点 | 反例 | 正例 | 判定 |
+| --- | --- | --- | --- |
+| 参数校验 | 手写判空 + 类型转换散乱 | `binding` tag + `c.ShouldBindJSON` / `validator.v10` | **SHOULD** |
+| 错误响应格式 | 各 handler 自定义 json | 全局 error middleware 统一格式 | **MUST**(前端对接一致性) |
+| body size 未限制 | 接收任意大 JSON | `http.MaxBytesReader` / Gin `MaxMultipartMemory` | **MUST**(DoS) |
+| CORS 配置 | `AllowAllOrigins = true` + 带 credentials | 显式 origin 白名单 | **MUST** |
+| HTTP 客户端 | 全局 `http.DefaultClient`(无 timeout) | 自建 `http.Client{Timeout, Transport}` | **MUST** |
+| keep-alive / 连接池 | 短连接每次重建 | 复用 Client 或 Transport | **SHOULD** |
+| 请求上下文 | handler 里起 goroutine 用 `context.Background()` | 派生自 `c.Request.Context()` | **MUST**(取消失效) |
+| graceful shutdown | 直接 `os.Exit` | `srv.Shutdown(ctx)` + 等待 in-flight | **SHOULD** |
+
+---
+
+## §8 并发原语
+
+| 检查点 | 反例 | 正例 | 判定 |
+| --- | --- | --- | --- |
+| race detector | 开发/CI 不跑 `go test -race` | CI 强制开 | **SHOULD** |
+| `sync.Mutex` 拷贝 | 结构体值传递含 Mutex | 用指针或 `noCopy` | **MUST** |
+| `atomic` vs `Mutex` | 简单计数也用 Mutex 性能差 | `atomic.Int64` | **NIT** |
+| map 并发 | 多 goroutine 读写 `map[K]V` | `sync.Map`(读多) 或 `sync.RWMutex` 包裹 | **MUST**(fatal error) |
+| channel direction | 函数参数 `ch chan T`(双向) | 明确 `ch <-chan T` 或 `ch chan<- T` | **SHOULD** |
+
+---
+
+## §9 单元测试(testify / gomock)
+
+| 检查点 | 反例 | 正例 | 判定 |
+| --- | --- | --- | --- |
+| 测试落点 | 新增黑盒 / 接口 / 回归测试散落到各业务 package 同目录 | 默认放项目根目录 `test/`;只有包内白盒测试需要访问未导出符号时才同目录 | **SHOULD** |
+| 断言强度 | `assert.NoError(t, err)` 就结束 | + `assert.Equal(t, want, got)` 验证业务结果 | **SHOULD** |
+| `t.Parallel` 陷阱 | 循环里 `tt := tt` 漏写(Go < 1.22) | Go < 1.22 必须 `tt := tt`;Go ≥ 1.22 自动 rebind | 竞态 **MUST** |
+| Mock 生成 | 手写 mock 与接口不同步 | `go:generate mockgen` / `mockery` | **SHOULD** |
+| `subtests` / 表驱动 | 多个 case 复制粘贴 | `for _, tt := range cases { t.Run(tt.name, ...) }` | **SHOULD** |
+| `httptest` | 用真 HTTP 端口 | `httptest.NewServer` / `httptest.NewRecorder` | **SHOULD** |
+| 时间依赖 | 直接 `time.Now()` | 注入 clock 接口 + 测试用 fake | **SHOULD** |
+| 环境变量 | 测试依赖真 env | `t.Setenv(...)`(Go 1.17+)自动清理 | **SHOULD** |
+| `go test` 覆盖率 | 不跑 / 不收集 | `go test -cover -coverprofile=c.out` + CI 阈值 | L2 < 60% **SHOULD**;L3 < 75% **MUST** |
+| golden file | 硬编码期望值巨长 | `testdata/*.golden` + `-update` flag | **NIT** |
+
+---
+
+## §10 依赖与构建
+
+| 检查点 | 反例 | 正例 | 判定 |
+| --- | --- | --- | --- |
+| `go.mod` / `go.sum` | `go.sum` 未提交 / 冲突未解决 | 每次 commit 保证一致 | **MUST** |
+| init() 副作用 | 全局 `init()` 连 DB / 读配置 | main 里显式初始化 + error 处理 | **SHOULD** |
+| replace 指令 | `replace` 指向本地路径上了主干 | 合并前替换为 tag | **MUST** |
+| CGO 依赖 | 无必要开 CGO | 除非必须,保持 `CGO_ENABLED=0` | **SHOULD** |
+| Dockerfile | 跑 root + 基础镜像含 bash | distroless / scratch + USER 1000 | **SHOULD** |
+
+---
+
+## 快速映射到 `review-checklist.md`
+
+| Cheatsheet 章节 | 对应通用 checklist |
+| --- | --- |
+| §1 nil 安全 | §1.4 边界 + §3 null 安全 |
+| §2 goroutine 泄漏 | §4 Performance + §1.5 并发 |
+| §3 context 传播 | §1.5 并发 + §4 Performance |
+| §4 error 处理 | §5 Maintainability + §1.1 正确性 |
+| §5 defer / 资源 | §3 资源泄漏 |
+| §6 ORM / 事务 | §1.6 事务幂等 + §7.3 全链路 |
+| §7 HTTP handler | §1.3 接口契约 + §3 Security |
+| §8 并发原语 | §1.5 并发 |
+| §9 单元测试 | §6 Tests |
+| §10 依赖构建 | §5 Maintainability + §3 Security |