@namewta/speculo 0.1.0 → 0.1.2

package/speculo/workflows/dev/R-review/R-review.md

@@ -2,13 +2,13 @@
 id: dev/R-review
 category: dev
 name: Review
-description: 从固定比较点开始，按 Standards 与 Spec 两个维度审查当前 diff
-keywords: [review, diff, standards, spec, pr, 审查]
+description: 从固定比较点开始，按 Spec、Engineering、Standards 三个独立维度审查当前 diff，并给出带严重度的裁决
+keywords: [review, diff, spec, engineering, standards, security, solid, pr, 审查]
 ---
 
 # Review 工作流执行指引
 
-本工作流是 `dev/R` 入口，用于审查 `HEAD` 与用户提供的固定点之间的 diff。审查结果必须分成两个并行维度：Standards 与 Spec，避免一个维度掩盖另一个维度。
+本工作流是 `dev/R` 入口，用于审查 `HEAD` 与用户提供的固定点之间的 diff。审查以**资深工程师视角**进行，结果必须分成三个**互相独立、互不掩盖**的维度，每条 finding 带严重度，最后给出整体裁决。
 
 ## 内置指引
 
@@ -16,49 +16,79 @@ keywords: [review, diff, standards, spec, pr, 审查]
 
 当用户想审查分支、PR、进行中的变更，或要求 `review since <fixed-point>` 时使用。
 
-### 输入
+### 三个审查维度
 
-- 固定比较点：commit SHA、分支名、tag、`main`、`HEAD~5` 等
-- 当前 change 目录：`.speculo/dev/<change>/`
-- 可发现的标准来源：`.speculo/.config/RULES.md`、`.speculo/.config/context/`、`.speculo/.config/adr/`、`AGENTS.md`、`CONTRIBUTING.md`、配置文件等
-- spec 来源：当前 change 的 PRD、slices、用户提供路径、commit message 中引用的 issue 或其他规格文档
+三个维度是三种独立的"镜头"，**不合并、不重排、不让一个维度的结论掩盖另一个**：
 
-### 输出
+| 维度 | 问题 | 关注 |
+|------|------|------|
+| **Spec** | 做对了吗？ | 是否忠实实现来源 issue / PRD / spec：缺失需求、范围蔓延、看似实现但有问题的需求 |
+| **Engineering** | 做好了吗？ | 不依赖成文规则的工程质量：SOLID 与架构、安全与可靠性、错误处理、性能、边界、死代码 |
+| **Standards** | 合规吗？ | 是否违反仓库**已记录**的标准：RULES、ADR、CONTRIBUTING、lint / 格式 / 类型配置 |
 
-- `.speculo/dev/<change>/review-sources.md`
-- `.speculo/dev/<change>/review-report.md`
-- Standards 与 Spec 两个分区的 findings，不合并、不重排
+若缺少 spec，Spec 维度跳过并报告 `no spec available`；若仓库无成文标准，Standards 维度报告检查范围并说明覆盖空白。Engineering 维度始终执行。
+
+### 严重度模型
+
+每条 finding 必须标注严重度：
+
+| 级别 | 名称 | 含义 | 动作 |
+|------|------|------|------|
+| **P0** | Critical | 安全漏洞、数据丢失风险、正确性 bug | 必须阻断合并 |
+| **P1** | High | 逻辑错误、显著 SOLID 违背、性能回退、关键需求缺失 | 合并前应修复 |
+| **P2** | Medium | 代码异味、可维护性隐患、轻微 SOLID 违背、范围蔓延 | 本 PR 修或建后续项 |
+| **P3** | Low | 风格、命名、小建议 | 可选改进 |
 
 ### 执行原则
 
-用户说的任何东西都是固定点。若用户没有指定固定点，先询问固定点；拿到前不要继续。
+- 用户说的任何东西都是固定点。若用户没有指定固定点，先询问；拿到前不要继续。
+- 比较命令使用三点语法：`git diff <fixed-point>...HEAD`，同时记录 `git log <fixed-point>..HEAD --oneline`。
+- **Worktree 模式**：若当前 change 为 worktree 隔离模式（`.status.json` 的 `worktree_enabled` 为真），fixed point 默认取 `base_branch`，且审查必须完整覆盖 change 分支树 `base_branch..change_branch` 的**每一个 commit**，不能只看最新工作区状态。此时读取 `../../../skills/worktree-isolation/SKILL.md` 的 `references/audit-branch-tree.md`；非 worktree 模式不读取该 skill。
+- **Review-first**：本工作流默认只产出审查结论，**不修改代码**；除非用户在看到 findings 后明确授权修复。
+- **诚实优先**：无法覆盖的区域要显式声明（见 `review-verdict.md` 的 clean-review 要求），不得用"看起来没问题"代替实际检查。
+- 机器已强制的标准（lint / 类型 / 格式）只记录来源，不重复人工检查工具已覆盖的内容。
+- 如果环境支持并行子代理，三个维度应并行执行；如果不支持，按三个独立上下文顺序执行，并在报告中保持分离。
 
-比较命令使用三点语法：`git diff <fixed-point>...HEAD`。同时记录 `git log <fixed-point>..HEAD --oneline`。
+### 渐进披露（Engineering 维度深度清单）
 
-Standards 维度检查 diff 是否违反仓库已记录标准；Spec 维度检查 diff 是否忠实实现来源 issue、PRD 或 spec。若缺少 spec，Spec 维度跳过并报告 `no spec available`。
+进入 Engineering 维度审查时，按需读取同目录清单：
 
-如果环境支持并行子代理，Standards 与 Spec 审查应并行执行；如果不支持，按两个独立上下文顺序执行，并在报告中保持分离。
+- `solid-checklist.md`：检查 SOLID 违背与架构异味、给重构启发式时读取。
+- `security-checklist.md`：检查安全漏洞、竞态、密钥、密码学与运行时风险时读取。
+- `code-quality-checklist.md`：检查错误处理、性能 / 缓存、边界条件时读取。
+- `removal-checklist.md`：识别死代码与删除候选、产出删除 / 推迟计划时读取。
 
 ## 阶段
 
-### 1. Review Setup — 固定点与来源收集
+### 1. Review Setup — 固定点、范围与来源收集
 - 规范：`review-setup.md`
 - 模板：`../_templates/review-sources-template.md`
 - 产物：`review-sources.md`
 - 完成准则：
-  - 已记录 fixed point、diff 命令、commit 列表
-  - 已列出 standards 来源和 spec 来源，或记录 spec 缺失
+  - 已记录 fixed point、diff 命令、commit 列表、diff 规模与分批策略
+  - 已列出 standards 来源与 spec 来源，或记录各自缺失
+  - 已标识关键路径（auth / 支付 / 数据写入 / 网络）
   - `review-sources.md` 无残留 `[TODO:]`
 
-### 2. Two-Axis Review — 双维度审查
-- 规范：`review-two-axis.md`
+### 2. Multi-Axis Review — 三维度审查
+- 规范：`review-axes.md`
 - 模板：`../_templates/review-report-template.md`
 - 产物：`review-report.md`
 - 完成准则：
-  - Standards 与 Spec 分区独立呈现
-  - 每条 finding 有文件/行或 hunk 依据，以及对应标准或 spec 引用
+  - Spec / Engineering / Standards 分区独立呈现，不合并、不重排
+  - 每条 finding 带严重度（P0–P3）、文件/行或 hunk 依据，以及对应 spec / 清单 / 标准引用
   - `review-report.md` 无残留 `[TODO:]`
 
+### 3. Verdict & Next Steps — 裁决与后续确认
+- 规范：`review-verdict.md`
+- 模板：`../_templates/review-verdict-template.md`
+- 产物：`review-verdict.md`
+- 完成准则：
+  - 给出整体裁决（APPROVE / REQUEST_CHANGES / COMMENT）与严重度汇总
+  - 完成 clean-review 声明：检查了什么、未覆盖什么、残留风险
+  - 已向用户给出后续选项，未经确认不实施修复
+  - `review-verdict.md` 无残留 `[TODO:]`
+
 ## 依赖
 
 - 软依赖：`../02-prd/02-prd.md` 或 `../I-to-issues/I-to-issues.md`，scope: same-change
@@ -71,12 +101,16 @@ Standards 维度检查 diff 是否违反仓库已记录标准；Spec 维度检
 - `dev_entry` (string) — 固定为 `dev/R`
 - `review_fixed_point` (string) — 用户提供的比较点
 - `review_diff_command` (string) — 实际使用的 diff 命令
+- `review_axes` (array) — 实际执行的维度，取值自 `spec` | `engineering` | `standards`
 - `standards_sources` (array) — Standards 审查读取的规则来源
 - `spec_sources` (array) — Spec 审查读取的规格来源
-- `review_status` (collecting | reviewing | completed | blocked) — 审查状态
+- `severity_summary` (object) — 各严重度 finding 计数：`{ "p0": n, "p1": n, "p2": n, "p3": n }`
+- `review_verdict` (approve | request_changes | comment | null) — 整体裁决
+- `review_status` (collecting | reviewing | judged | completed | blocked) — 审查状态
 
 ## 完成与状态更新
 
 - 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
-- 完成 setup 后写入 fixed point、diff 命令和来源清单。
-- 完成报告后更新 `review_status`，但不自动完成 change；是否进入修复或收尾由用户决定。
+- 完成 setup 后写入 fixed point、diff 命令、`review_axes` 和来源清单。
+- 完成报告后更新 `severity_summary`，置 `review_status: judged`。
+- 完成裁决后写入 `review_verdict`，置 `review_status: completed`；但不自动完成 change —— 是否进入修复（`../03-tdd/03-tdd.md`）、收尾归档（`../04-finalize/04-finalize.md`）或其他动作由用户决定。

package/speculo/workflows/dev/R-review/code-quality-checklist.md

@@ -0,0 +1,118 @@
+# 代码质量清单
+
+服务 `R-review.md` 的 **Engineering 维度**。审查 diff 的错误处理、性能与边界条件时读取本文。重点标记会导致**静默失败**或**生产事故**的问题，并按下方"严重度提示"定级。
+
+## 错误处理
+
+### 需要标记的反模式
+
+- **吞掉异常**：空 catch，或只打日志的 catch
+  ```javascript
+  try { ... } catch (e) { }            // 静默失败
+  try { ... } catch (e) { console.log(e) }  // 打了日志就不管
+  ```
+- **过宽的 catch**：捕获 `Exception` / `Error` 基类而非具体类型
+- **错误信息泄露**：把堆栈或内部细节暴露给用户
+- **缺少错误处理**：可失败操作（I/O、网络、解析）周围没有 try-catch
+- **异步错误处理**：未处理的 promise rejection、缺 `.catch()`、无 error boundary
+
+### 应核对的最佳实践
+
+- [ ] 错误在恰当的边界被捕获
+- [ ] 错误信息对用户友好（不暴露内部细节）
+- [ ] 错误带足够上下文记录，便于调试
+- [ ] 异步错误被正确传播或处理
+- [ ] 可恢复错误有定义好的兜底行为
+- [ ] 关键错误触发告警 / 监控
+
+### 追问
+- "这个操作失败时会发生什么？"
+- "调用方会知道出错了吗？"
+- "有足够上下文调试这个错误吗？"
+
+## 性能与缓存
+
+### CPU 密集操作
+- **热路径上的昂贵操作**：循环中编译正则、解析 JSON、做加密
+- **阻塞主线程**：同步 I/O、无 worker / async 的重计算
+- **重复计算**：同一计算被多次执行
+- **缺少记忆化**：相同输入反复调用的纯函数
+
+### 数据库与 I/O
+- **N+1 查询**：循环里每个元素查一次，而非批量
+  ```javascript
+  // 差：N+1
+  for (const id of ids) {
+    const user = await db.query(`SELECT * FROM users WHERE id = ?`, id)
+  }
+  // 好：批量
+  const users = await db.query(`SELECT * FROM users WHERE id IN (?)`, ids)
+  ```
+- **缺索引**：在未建索引的列上查询
+- **过度取数**：只需几列却 SELECT *
+- **无分页**：把整个数据集加载进内存
+
+### 缓存问题
+- **昂贵操作缺缓存**：重复的 API 调用、DB 查询、计算
+- **缓存无 TTL**：脏数据被无限期返回
+- **缓存无失效策略**：数据更新了但缓存没清
+- **缓存键碰撞**：键唯一性不足
+- **把用户私有数据全局缓存**：安全 / 隐私问题
+
+### 内存
+- **无界集合**：不断增长的数组 / map
+- **大对象滞留**：持有引用阻止 GC
+- **循环中字符串拼接**：应改用 StringBuilder / join
+- **整文件加载**：应改用流式
+
+### 追问
+- "这个操作的时间复杂度是多少？"
+- "数据量 10 倍 / 100 倍时行为如何？"
+- "结果可缓存吗？该缓存吗？"
+- "能批量代替逐条吗？"
+
+## 边界条件
+
+### Null / Undefined 处理
+- **缺空值检查**：在可能为 null 的对象上访问属性
+- **truthy / falsy 混淆**：`if (value)` 而 `0` 或 `""` 是合法值
+- **过度可选链**：`a?.b?.c?.d` 掩盖了结构性问题
+- **null 与 undefined 不一致**：混用且无明确约定
+
+### 空集合
+- **未处理空数组**：代码假设数组非空
+- **空对象边界**：在空对象上 `for...in` 或 `Object.keys`
+- **首 / 末元素访问**：`arr[0]` 或 `arr[arr.length-1]` 未先判空
+
+### 数值边界
+- **除零**：除法前缺检查
+- **整数溢出**：超出安全整数范围的大数
+- **浮点比较**：用 `===` 而非 epsilon 比较
+- **负值**：本不该为负的索引或计数
+- **off-by-one**：循环边界、数组切片、分页
+
+### 字符串边界
+- **空字符串**：未作为边界处理
+- **纯空白字符串**：通过 truthy 检查但实际为空
+- **超长字符串**：无长度上限导致内存 / 展示问题
+- **Unicode 边界**：emoji、RTL 文本、组合字符
+
+### 需要标记的危险模式
+```javascript
+const name = user.profile.name   // 危险：无空值检查
+const first = items[0]           // 危险：数组访问未判空
+const avg = total / count        // 危险：除法未判零
+if (value) { ... }               // 危险：truthy 检查排除了 0、""、false
+```
+
+### 追问
+- "如果它是 null / undefined 会怎样？"
+- "如果集合为空会怎样？"
+- "这个数的合法范围是什么？"
+- "边界值（0、-1、MAX_INT）处会怎样？"
+
+## 严重度提示
+
+- 会导致正确性 bug、数据损坏或生产事故的静默失败 → **P0 / P1**
+- 性能回退、可维护性隐患、未覆盖的边界 → **P1 / P2**
+- 局部健壮性改进 → **P3**

package/speculo/workflows/dev/R-review/removal-checklist.md

@@ -0,0 +1,53 @@
+# 删除候选与迭代计划清单
+
+服务 `R-review.md` 的 **Engineering 维度**。审查 diff 引入或暴露的死代码、冗余、关停特性时读取本文。区分**现在可安全删除**与**需计划后再删**，审查阶段只给出候选与计划，**不在审查中直接删除代码**。
+
+## 优先级
+
+- [ ] **P0**：需立即删除（安全风险、显著成本、阻塞其他工作）
+- [ ] **P1**：本迭代删除
+- [ ] **P2**：进 backlog / 下个迭代
+
+## 现在可安全删除
+
+### 候选项：[名称 / 描述]
+
+| 字段 | 内容 |
+|------|------|
+| **位置** | `path/to/file.ts:line` |
+| **理由** | 为什么应该删除 |
+| **证据** | 无引用、死特性开关、已废弃 API |
+| **影响** | 无 / 低 —— 无活跃消费者 |
+| **删除步骤** | 1. 删代码 2. 删测试 3. 删配置 |
+| **验证** | 跑测试、确认无运行时错误、观察日志 |
+
+## 推迟删除（需计划）
+
+### 候选项：[名称 / 描述]
+
+| 字段 | 内容 |
+|------|------|
+| **位置** | `path/to/file.ts:line` |
+| **为何推迟** | 有活跃消费者、需迁移、需干系人签字 |
+| **前置条件** | 特性开关关闭 2 周、遥测显示 0 使用 |
+| **破坏性变更** | 列出 API / 契约变更 |
+| **迁移计划** | 消费者迁移步骤 |
+| **时间线** | 目标日期或迭代 |
+| **负责人** | 责任人 / 团队 |
+| **验证** | 确认可安全删除的指标（错误率、使用计数） |
+| **回滚计划** | 出问题时如何恢复 |
+
+## 删除前核对
+
+- [ ] 全代码库搜索过所有引用（`rg`、`grep`）
+- [ ] 检查过动态 / 反射式调用
+- [ ] 确认无外部消费者（API、SDK、文档）
+- [ ] 复核过特性开关遥测（如适用）
+- [ ] 测试已更新 / 删除
+- [ ] 文档已更新
+- [ ] 已通知团队（如为共享代码）
+
+## 严重度提示
+
+- 引入的死代码 / 冗余本身一般是 **P3**；但当它**掩盖了正确性或安全风险**，或带来显著维护 / 成本负担时升级到 **P2 / P1**。
+- 审查只产出删除候选与计划；实际删除交由后续 `../03-tdd/03-tdd.md` 或专门的清理任务执行。

package/speculo/workflows/dev/R-review/review-axes.md

@@ -0,0 +1,57 @@
+# Multi-Axis Review Phase
+
+## 输入
+
+- `.speculo/dev/<change>/review-sources.md`
+- `git diff <fixed-point>...HEAD`
+- spec 来源文件或 `no spec available`
+- standards 来源文件或覆盖空白说明
+- Engineering 深度清单：同目录 `solid-checklist.md`、`security-checklist.md`、`code-quality-checklist.md`、`removal-checklist.md`
+
+## 产物
+
+- `.speculo/dev/<change>/review-report.md`，由 `../_templates/review-report-template.md` 填写
+
+## 填写引导
+
+三个维度各自独立成区，每条 finding 都要带**严重度（P0–P3）**、**文件/行或 hunk 依据**、**引用来源**，并尽量给出**可执行的修复建议**。
+
+### Spec 维度（做对了吗）
+
+1. 先读 spec，再读 diff。
+2. 报告：缺失需求、范围蔓延（spec 外的实现）、看似实现但有问题的需求。
+3. 每条引用 spec 原文。缺少 spec 时整区写 `no spec available`。
+
+### Engineering 维度（做好了吗）
+
+按需读取四份清单，逐项扫描 diff：
+
+1. **SOLID 与架构**（`solid-checklist.md`）：SRP/OCP/LSP/ISP/DIP 违背、代码异味；提重构时说明为何改善内聚 / 降低耦合，非平凡重构给增量计划。
+2. **安全与可靠性**（`security-checklist.md`）：注入 / XSS / SSRF / 路径穿越、认证授权、密钥泄露、竞态（TOCTOU、共享状态、DB 并发）、密码学、运行时风险；每条说明可利用性与影响。
+3. **代码质量**（`code-quality-checklist.md`）：错误处理（吞异常、异步错误）、性能（N+1、热路径昂贵操作、缓存）、边界条件（null、空集合、数值 / 字符串边界、off-by-one）。
+4. **删除候选**（`removal-checklist.md`）：死代码、冗余、关停特性；区分可安全删除与需计划，只产出候选与计划，不在审查中删代码。
+
+### Standards 维度（合规吗）
+
+1. 先读已记录标准（RULES、ADR、CONTRIBUTING、配置），再读 diff。
+2. 报告违反**已成文**标准的位置，引用标准来源。
+3. 工具已机器强制的项不重复人工检查；无成文标准时说明覆盖空白。
+
+### 并行与隔离
+
+- 如果可用，使用三个并行子代理分别审查 Spec、Engineering、Standards。
+- 如果没有子代理，分三个独立小节顺序执行，不让任一维度的结论影响另一维度。
+- 最终报告在 `## Spec`、`## Engineering`、`## Standards` 下并排呈现，可轻微清理措辞，但不要合并或重排 findings。
+
+## 边界
+
+- 不修复代码（review-first）。
+- 不把三个维度混成一个优先级列表。
+- 缺少 spec 时跳过 Spec 维度并明确写 `no spec available`；Engineering 维度始终执行。
+- 严重度按各清单的"严重度提示"判定，不凭印象拔高或压低。
+
+## 完成准则
+
+- `review-report.md` 已按 Spec / Engineering / Standards 三区呈现
+- 每条 finding 有严重度、明确依据和来源引用
+- `.status.json` 写入 `severity_summary`，`review_status: judged`

package/speculo/workflows/dev/R-review/review-setup.md

@@ -12,28 +12,36 @@
 
 ## 填写引导
 
-1. 沿用用户提供的 fixed point，不自行替换为其他分支。
+1. 沿用用户提供的 fixed point，不自行替换为其他分支。**Worktree 模式**（`.status.json` 的 `worktree_enabled` 为真）下，若用户未另行指定，fixed point 默认取 `base_branch`，并按 `../../../skills/worktree-isolation/SKILL.md` 的 `references/audit-branch-tree.md` 用 `git log <base_branch>..<change_branch> --oneline` 记录 change 分支树**全部 commit**、`git diff <base_branch>...<change_branch>` 取全量 diff，确保审查覆盖每个 commit。
 2. 记录 `git diff <fixed-point>...HEAD` 和 `git log <fixed-point>..HEAD --oneline`。
-3. 寻找 spec 来源，顺序为：
+3. 用 `git diff <fixed-point>...HEAD --stat` 评估 diff 规模并定分批策略：
+   - **无变更**：`git diff` 为空时，告知用户并询问是否改审 staged 变更或某个 commit 区间，拿到前不继续。
+   - **大 diff（> 500 行）**：先按文件 / 模块汇总，再按模块或功能分批审查。
+   - **混合关注点**：按逻辑功能分组，不只按文件顺序。
+4. 标识关键路径：auth / 授权、支付 / 金额、数据写入、网络 / 外部调用、并发 —— 这些区域在 Engineering 维度需重点审查。
+5. 寻找 spec 来源，顺序为：
    - commit message 中的 issue / PR 引用
    - 用户作为参数传入的路径
    - `.speculo/dev/<change>/prd.md`、`slices.md`、`decision-log.md`
    - 仓库中与分支名或功能匹配的规格文档
-4. 寻找 standards 来源，常见路径包括：
+6. 寻找 standards 来源，常见路径包括：
    - `.speculo/.config/RULES.md`
    - `.speculo/.config/context/`
    - `.speculo/.config/adr/`
    - `AGENTS.md`、`CONTRIBUTING.md`
    - `.editorconfig`、`eslint.config.*`、`biome.json`、`prettier.config.*`、`tsconfig.json`
-5. 机器强制的标准只记录来源，不重复检查工具已覆盖的内容。
+7. 机器强制的标准只记录来源，不重复检查工具已覆盖的内容。
+8. Engineering 维度不需要外部来源，但记录将依据同目录的 `solid-checklist.md`、`security-checklist.md`、`code-quality-checklist.md`、`removal-checklist.md`。
 
 ## 边界
 
-- 不开始主观审查，先完成来源收集。
+- 不开始主观审查，先完成来源与范围收集。
 - 找不到 spec 时不要编造；记录 `no spec available`。
+- 找不到成文标准时记录覆盖空白，不把缺失当作"无问题"。
 
 ## 完成准则
 
-- fixed point、diff 命令、commit 列表已记录
-- standards 与 spec 来源已记录
-- `.status.json` 的 review setup 字段已更新
+- fixed point、diff 命令、commit 列表、diff 规模与分批策略已记录
+- worktree 模式下已记录 change 分支树 `base_branch..change_branch` 的全部 commit
+- standards 来源、spec 来源、关键路径已记录
+- `.status.json` 写入 `review_fixed_point`、`review_diff_command`、`review_axes`、`standards_sources`、`spec_sources`，`review_status: collecting`

package/speculo/workflows/dev/R-review/review-verdict.md

@@ -0,0 +1,40 @@
+# Verdict & Next Steps Phase
+
+## 输入
+
+- `.speculo/dev/<change>/review-report.md`（三维度 findings）
+- `.status.json` 的 `severity_summary`
+
+## 产物
+
+- `.speculo/dev/<change>/review-verdict.md`，由 `../_templates/review-verdict-template.md` 填写
+
+## 填写引导
+
+1. **严重度汇总**：统计三维度合计的 P0 / P1 / P2 / P3 计数。
+2. **整体裁决**，依据汇总给出其一：
+   - `REQUEST_CHANGES`：存在任何 P0，或存在合并前应修复的 P1
+   - `COMMENT`：无 P0/P1，但有值得跟进的 P2/P3
+   - `APPROVE`：无阻断项，至多少量 P3
+3. **Clean-review 诚实声明**（无论是否发现问题都必须写）：
+   - **检查了什么**：覆盖到的文件 / 模块 / 维度（worktree 模式下须确认已覆盖 `base_branch..change_branch` 的每个 commit）
+   - **未覆盖什么**：未审的区域及原因（如 "未验证数据库迁移"、"大 diff 仅抽样审查了 X 模块"）
+   - **残留风险**：建议补充的测试或后续验证
+4. **后续选项**：向用户给出明确选项并等待选择，未经确认不实施修复：
+   1. 修复全部
+   2. 仅修复 P0 / P1
+   3. 修复指定项（由用户点名）
+   4. 不改动，审查到此为止
+5. 用户选择修复时，移交 `../03-tdd/03-tdd.md` 的红绿重构循环执行，并在该 change 内继续维护状态。
+
+## 边界
+
+- 不修复代码；本阶段只裁决与确认。
+- 不夸大或弱化裁决；裁决必须与 `severity_summary` 一致。
+- 不把"未覆盖"伪装成"无问题"。
+
+## 完成准则
+
+- `review-verdict.md` 含整体裁决、严重度汇总、clean-review 三项声明、后续选项
+- `review-verdict.md` 无残留 `[TODO:]`
+- `.status.json` 写入 `review_verdict`，`review_status: completed`

package/speculo/workflows/dev/R-review/security-checklist.md

@@ -0,0 +1,126 @@
+# 安全与可靠性清单
+
+服务 `R-review.md` 的 **Engineering 维度**。审查 diff 是否引入安全漏洞或运行时风险时读取本文。每条命中都要同时说明**可利用性（exploitability）**与**影响（impact）**，并按下方"严重度提示"定级。
+
+## 输入 / 输出安全
+
+- **XSS**：不安全的 HTML 注入、`dangerouslySetInnerHTML`、未转义模板、`innerHTML` 赋值
+- **注入**：通过字符串拼接或模板串构造的 SQL / NoSQL / 命令 / GraphQL 注入
+- **SSRF**：用户可控 URL 在无 allowlist 校验下访问内部服务
+- **路径穿越**：用户输入未经清洗进入文件路径（`../` 攻击）
+- **原型污染**：JavaScript 中用用户输入做不安全的对象合并（`Object.assign`、带用户输入的展开）
+
+## 认证 / 授权（AuthN/AuthZ）
+
+- 读写操作缺少租户或归属（ownership）校验
+- 新端点没有 auth guard 或 RBAC 约束
+- 信任客户端传入的 role / flag / ID
+- 越权访问（IDOR —— 不安全的直接对象引用）
+- 会话固定或弱会话管理
+
+## JWT 与令牌安全
+
+- 算法混淆攻击（期望 `RS256` 却接受 `none` 或 `HS256`）
+- 弱密钥或硬编码密钥
+- 缺少 `exp` 过期或未校验
+- 敏感数据放进 JWT payload（token 是 base64，不是加密）
+- 不校验 `iss`（签发者）或 `aud`（受众）
+
+## 密钥与 PII
+
+- API key、token、凭据出现在代码 / 配置 / 日志
+- 密钥进入 git 历史，或环境变量暴露给客户端
+- 过度记录 PII 或敏感载荷
+- 错误信息缺少数据脱敏
+
+## 供应链与依赖
+
+- 未锁版本的依赖，允许恶意更新
+- 依赖混淆（私有包名冲突）
+- 从不可信源或 CDN 引入且无完整性校验
+- 含已知 CVE 的过期依赖
+
+## CORS 与响应头
+
+- 过宽的 CORS（带 credentials 时 `Access-Control-Allow-Origin: *`）
+- 缺少安全响应头（CSP、X-Frame-Options、X-Content-Type-Options）
+- 暴露内部头或堆栈信息
+
+## 运行时风险
+
+- 无界循环、递归调用或大块内存缓冲
+- 外部调用缺少超时、重试或限流
+- 请求路径上的阻塞操作（async 上下文中的同步 I/O）
+- 资源耗尽（文件句柄、连接、内存）
+- ReDoS（正则表达式拒绝服务）
+
+## 密码学
+
+- 弱算法（用于安全目的的 MD5、SHA1）
+- 硬编码 IV 或 salt
+- 只加密不认证（ECB 模式、无 HMAC）
+- 密钥长度不足
+
+## 竞态条件（Race Conditions）
+
+竞态是引发间歇性故障和安全漏洞的隐蔽缺陷，重点关注：
+
+### 共享状态访问
+- 多线程 / 协程 / 异步任务无同步地访问共享变量
+- 并发修改全局状态或单例
+- 无正确加锁的惰性初始化（double-checked locking 问题）
+- 在并发上下文使用非线程安全集合
+
+### 先检查后行动（TOCTOU）
+- `if (exists) then use` 无原子操作
+- `if (authorized) then perform`，而授权可能变化
+- 文件存在性检查后再做文件操作
+- 余额检查后扣减（金融操作）
+- 库存检查后下单
+
+### 数据库并发
+- 缺少乐观锁（`version` 列、`updated_at` 校验）
+- 缺少悲观锁（`SELECT FOR UPDATE`）
+- 无事务隔离的 read-modify-write
+- 非原子的计数器自增（应用 `UPDATE SET count = count + 1`）
+- 并发插入触发唯一约束冲突
+
+### 分布式系统
+- 共享资源缺少分布式锁
+- 领导选举竞态
+- 缓存失效竞态（写后读到脏数据）
+- 缺少正确排序的事件顺序依赖
+- 集群操作的脑裂
+
+### 需要标记的危险模式
+```
+# 危险模式：
+if not exists(key):       # TOCTOU
+    create(key)
+
+value = get(key)          # read-modify-write
+value += 1
+set(key, value)
+
+if user.balance >= amount:  # 先检查后行动
+    user.balance -= amount
+```
+
+### 追问
+- "两个请求同时进入这段代码会怎样？"
+- "这个操作是原子的，还是可被打断？"
+- "这段代码访问了哪些共享状态？"
+- "高并发下它的行为如何？"
+
+## 数据完整性
+
+- 缺少事务、部分写入或状态更新不一致
+- 持久化前校验薄弱（类型强转问题）
+- 可重试操作缺少幂等性
+- 并发修改导致的丢失更新（lost update）
+
+## 严重度提示
+
+- 可被利用的安全漏洞、数据丢失风险、敏感信息泄露 → **P0**（阻断合并）
+- 需特定条件触发但影响显著的安全 / 可靠性缺陷 → **P1**
+- 纵深防御缺口、低影响硬化项 → **P2**

package/speculo/workflows/dev/R-review/solid-checklist.md

@@ -0,0 +1,73 @@
+# SOLID 与架构异味清单
+
+服务 `R-review.md` 的 **Engineering 维度**。在审查 diff 的设计质量时读取本文，按 SOLID 与常见代码异味定位结构性问题，并对照下方"严重度提示"给出 P0–P3。
+
+## SOLID 异味提示
+
+### SRP（单一职责）
+
+- 一个文件承担互不相关的关注点（如 HTTP + DB + 领域规则混在一起）
+- 大类 / 大模块内聚低，存在多个变更原因
+- 函数编排了大量互不相关的步骤
+- 知道太多系统细节的 God Object
+- **追问**："这个模块只因为哪一个原因而改变？"
+
+### OCP（开闭）
+
+- 新增一种行为要修改多个 switch / if 分支
+- 功能增长需要改核心逻辑，而不是扩展点
+- 没有 plugin / strategy / hook 等变化点
+- **追问**："不动现有代码能加一个新变体吗？"
+
+### LSP（里氏替换）
+
+- 子类检查具体类型，或对基类方法抛异常
+- 重写方法弱化了前置条件、强化了后置条件
+- 子类忽略或空实现父类行为
+- **追问**："调用方无感知地替换任意子类能成立吗？"
+
+### ISP（接口隔离）
+
+- 接口方法很多，实现者大多用不到
+- 调用方为很窄的需求依赖很宽的接口
+- 接口方法出现空 / 桩实现
+- **追问**："每个实现者都用到了全部方法吗？"
+
+### DIP（依赖倒置）
+
+- 高层逻辑直接依赖具体 IO、存储或网络类型
+- 硬编码实现，而不是抽象或注入
+- import 链把业务逻辑耦合到基础设施
+- **追问**："不改业务逻辑能换掉实现吗？"
+
+## 常见代码异味（SOLID 之外）
+
+| 异味 | 信号 |
+|------|------|
+| **Long method** | 函数 > 30 行，多层嵌套 |
+| **Feature envy** | 方法用别的类的数据多过用自己的 |
+| **Data clumps** | 同一组参数反复一起传递 |
+| **Primitive obsession** | 用 string / number 代替领域类型 |
+| **Shotgun surgery** | 一处改动要散落地改多个文件 |
+| **Divergent change** | 一个文件因多个无关原因反复改 |
+| **Dead code** | 不可达或从不被调用的代码（详见 `removal-checklist.md`） |
+| **Speculative generality** | 为假想的未来需求做的抽象 |
+| **Magic numbers/strings** | 没有命名常量的硬编码值 |
+
+## 重构启发式
+
+1. **按职责拆，而不是按体积拆** —— 小文件也可能违反 SRP
+2. **需要时才引入抽象** —— 等到第二个用例再抽
+3. **重构保持增量** —— 先隔离行为再搬移
+4. **先保行为** —— 重构前先有测试兜底
+5. **按意图命名** —— 命名困难往往说明抽象有问题
+6. **组合优于继承** —— 继承带来强耦合
+7. **让非法状态不可表达** —— 用类型固化不变量
+
+## 严重度提示
+
+- 导致正确性问题或架构性返工的结构缺陷 → **P1**
+- 明显但局部的 SOLID 违背、可维护性隐患 → **P2**
+- 命名、轻微异味、可选改进 → **P3**
+
+> 提出重构时，必须说明它**为什么**改善内聚 / 降低耦合，并给出最小、安全的拆分；非平凡重构给增量计划，不给大重写。