@heihei0299/matt-skills 3.0.16 → 3.0.18

package/.agents/skills/tdd-implement/SKILL.md

@@ -6,84 +6,100 @@ disable-model-invocation: true
 
 # TDD Implement
 
-完成已确认的 spec/task。TDD 的红绿语义、测试质量、seam 和 mock 规则以 [tdd](.agents/skills/tdd/SKILL.md) 为唯一事实源；本技能只负责 issue 级实现、验证、Review 与收尾编排。
+完成已确认的 spec/task。TDD 的红绿语义、测试质量、seam 和 mock 规则以 [tdd](.agents/skills/tdd/SKILL.md) 为唯一事实源；本技能负责 issue 级实现、证据记录，以及 batch 级 Review 与收尾编排。
+
+> Ticket defines WHAT. TDD determines HOW to prove it. Repository determines HOW to implement it.
 
 ## 入口
 
-- **单 issue**：直接按下方 Steps 执行。
-- **多 issue**：存在多个 `Type: task` 时，读取 [orchestration.md](references/orchestration.md) 后按依赖顺序逐个完成。
+- **单 issue**：使用下方同一套 issue 与 batch lifecycle，等价于 batch size = 1。
+- **多 issue**：存在多个 `Type: task` 时，读取 [orchestration.md](references/orchestration.md) 后按依赖顺序执行。
 - `research`、`prototype`、`grilling` 类型任务分流到对应技能。
 
-每个 issue 开始时记录 `issue_base = HEAD`。Commit 是交付 artifact，不是流程日志：Red-Green / Verify 期间不因 Behavior、阶段切换或验证动作创建 commit。Verify 通过后形成 1 个 Review Point commit；仅当 Full Review 产生 blocking findings 时，最多再形成 1 个 finding-fix commit。
+正常 Red-Green / Verify 执行由当前 session 原生完成，不为每个 Behavior 或 issue 常规派发 implementer/reviewer。子代理只用于证据不足、证据冲突、复杂诊断等异常升级；常规独立 Review 只发生在 batch 末尾。
 
-生命周期：
+## Issue lifecycle:
 
-`Red-Green → Verify → Review → Finalize`
+`Red-Green → Verify → Record`
 
-## Steps
+Issue 状态可使用 `ready`、`in_progress`、`verified_pending_review`、`resolved`、`blocked`、`failed`。`verified_pending_review` 不是最终完成；只有 batch Review 与 finding fix 完成后才收敛为 `resolved`。
 
 ### ① Red-Green
 
 按 `tdd` 完成当前 issue 的所有 Acceptance Criteria。
 
-将需要实现或修改的内容拆成可独立验证的 Behavior。一次只推进一个 Behavior：每个尚未实现的 Behavior 都必须分别完成 `tdd` 的 Red → Green cycle，完成后才能进入下一个 Behavior。
+将需要实现或修改的内容拆成可独立验证的 Behavior。一次只推进一个 Behavior：每个尚未实现的 Behavior 都必须分别完成 `tdd` 的 Red → Green cycle，完成后才能进入下一个 Behavior。已有行为若无需修改且已由现有测试充分覆盖，不强制制造 Red。
+
+**出口：**所有需要实现或修改的 Behavior 均完成各自的 Red → Green cycle，Acceptance Criteria 对应行为通过相关验证。
 
-前一个 Behavior 已完成 TDD，不代表后续 Behavior 可以直接修改实现代码。
+### ② Verify
 
-已有行为若无需修改且已由现有测试充分覆盖，不强制制造 Red。
+读取 [verify.md](references/verify.md)，执行当前 issue 所需的最终验证。Verify 只覆盖必要范围，不重复等价验证。
 
-**出口：**
+**出口：**当前 issue 所需最终验证通过，并完成要求的真实运行验证；状态进入 `verified_pending_review`。
 
-- 所有需要实现或修改的 Behavior 均完成各自的 Red → Green cycle；
-- Acceptance Criteria 对应行为通过相关验证。
+### ③ Record Evidence
 
-### ② Verify
+Verify 后将每个 issue 的最小充分证据写入 git-ignored `.scratch/tdd-implement/` ledger。只记录命令/场景和结果，不保存完整测试输出；记录 ticket/repository 冲突时使用 `Ruling: <finding> — <decision and why> — <cost if wrong>`。
+
+```text
+Issue: <id>
+issue_base: <sha>
+issue_head: <sha>
+
+Acceptance:
+- AC1 → PASS
+- AC2 → PASS
+
+TDD:
+- behavior A → RED → GREEN
+- behavior B → RED → GREEN
+
+Verify:
+- <command/scenario> → PASS
 
-读取 [verify.md](references/verify.md)，执行当前 issue 所需的最终验证。
+Rulings:
+- none
+```
 
-**出口：**
+**出口：**ledger 完整，包含 Acceptance、TDD、Verify 和 Rulings 结果；未将 `verified_pending_review` 对外宣称为最终 `resolved`。
 
-- 当前 issue 所需最终验证通过；
-- 要求的真实运行验证完成。
+## Batch lifecycle:
 
-### ③ Review
+`Batch Review → Finding Fix → Finalize → State Sync`
 
-Verify 通过后读取 [review.md](references/review.md)。
+全部当前 batch 可执行 issue 都完成 Red-Green、Verify 和 Evidence Record 后，才进入 batch lifecycle。batch review 是整个 execution batch 唯一的 fresh `code-review`；issue loop 内不调用 `code-review`。
 
-先将当前 issue 交付所需的代码、测试、文档和配置形成唯一的 committed Review Point commit，再按 `review.md` 完成一次完整 Review 与必要的增量 Review。
+### Batch Review
 
-完整 Review 的审查维度、reviewer 数量、提示词和输出格式仍以 [code-review](.agents/skills/code-review/SKILL.md) 为唯一事实源。
+读取 [review.md](references/review.md)，将 batch 内全部交付代码、测试、文档和配置形成唯一的 committed Review Point，再以 `batch_base...batch_review_head` 调用一次 `code-review`。继续复用 [code-review](.agents/skills/code-review/SKILL.md) 的 Standards / Spec 双轴结构，不修改其机制。
 
-**出口：**
+### Finding Fix
 
-- `full_review_done = true`；
-- `open_findings` 为空；
-- `review_head` 已记录；
-- 当前 issue 的实现范围已完整进入 Review 证据。
+读取 [review.md](references/review.md) 的 finding-fix contract。Behavioral finding 通过真实 RED → GREEN 证据修复；non-behavioral finding 直接修复并做必要验证。全部 blocking findings 一次处理，最多一个 finding-fix commit；修复后不再次调用 `code-review`，不执行 Incremental Review。
 
-## Finalize
+### Finalize
 
-Review 通过后读取 [finalize.md](references/finalize.md)，只做 tracker/progress/status 收尾并记录 `issue_head`。
+读取 [finalize.md](references/finalize.md)。Finalize 只归档 Acceptance、Review、finding 和验证证据，将 `verified_pending_review → resolved`，解除已满足的 blockers，并记录最终 issue/batch head；不新增 Behavior、不修改产品实现、不偷偷补测试。
 
-Finalize 不新增产品 Behavior，也不修改已经 Review 的实现内容，不为单个 issue 创建收尾 commit。若收尾时发现实现、测试、文档/配置或验证遗漏，停止当前 issue，不标记 `resolved`，并按 `finalize.md` 报告遗漏请求决策；不得在 Finalize 中补改或重新进入 Red-Green、Verify 或 Review。
+### State Sync
 
-本次执行批次结束后，如仓库内 tracker/progress/status 存在待同步状态，统一写入并最多形成 1 个 batch state-sync commit；该 commit 不属于任何单个 issue 的实现/Review commit range。
+batch 结束时统一同步仓库内 tracker/progress/status；如确有待同步状态，最多创建 1 个 batch state-sync commit，且不混入产品实现或任何单个 issue 的提交范围。
 
 ## 运行纪律
 
-- Red-Green 必须覆盖当前 issue 的全部待实现 Behavior，不能只对第一个改动执行 TDD。
-- 一个 Behavior 完成后继续下一个 Behavior，直到 Step ① 出口满足。
-- Verify 只做当前 issue 必要的最终验证；已通过的等价验证不机械重复。
-- Red-Green / Verify 期间不按 Behavior、阶段或验证动作拆 commit；完整 Review 前只形成 1 个 committed Review Point。
-- 每个 issue 只有一次逻辑上的完整双轴 Review；若有 blocking findings，只允许 1 个 finding-fix commit 与最多 1 次逻辑增量 Review。技术失败或中断的恢复规则以 `review.md` 为准。
-- 当前 issue Review 与 Finalize 完成后，才能进入下一个 issue；下一个 issue 以当时的 `HEAD` 作为新的 `issue_base`。
-- 当前 Step 达到出口后继续进入下一 Step；仅在需要用户决策或存在外部阻塞时暂停。
+- Red-Green 必须覆盖当前 issue 的全部待实现 Behavior；Red-Green / Verify 不按 Behavior、阶段或验证动作拆 commit。
+- Verify 通过后先记录 evidence；不要因单个 issue 已验证就提前 Review 或宣称 resolved。
+- batch Review 前必须满足全部 issue Verify、ledger 完整、交付修改已提交且 working tree 没有遗漏。
+- 整个 execution batch 的 `code-review calls = 1`、`per-issue review = 0`、`incremental review = 0`。
+- 只有外部阻塞、需要用户决策、destructive / irreversible 操作、安全敏感行为或 ticket/plan 已无法可靠解释时才暂停。
+- 仅在当前 Step 达到出口后继续下一 Step；发现失败时保留实际状态，不把失败静默当作完成。
 
 ## References
 
 - TDD：[tdd](.agents/skills/tdd/SKILL.md)
 - Verify：[verify.md](references/verify.md)
-- Review：[review.md](references/review.md)
-- Finalize：[finalize.md](references/finalize.md)
-- 完整 Review：[code-review](.agents/skills/code-review/SKILL.md)
+- Batch Review / Finding Fix：[review.md](references/review.md)
+- Finalize / State Sync：[finalize.md](references/finalize.md)
+- 唯一 Review：[code-review](.agents/skills/code-review/SKILL.md)
 - 多 issue 编排：[orchestration.md](references/orchestration.md)

package/.agents/skills/tdd-implement/references/finalize.md

@@ -1,28 +1,32 @@
 # Finalize
 
-仅在 Verify 与 Review 通过后执行。Finalize 只负责 tracker/progress/status 收尾，不新增产品 Behavior，不修改已经 Review 的代码、测试、交付文档或配置，也不为单个 issue 创建收尾 commit。
+仅在 batch Review 完成、所有 blocking findings 已关闭且必要验证通过后执行。Finalize 只负责 batch 内 issue 的状态收敛与证据归档，不新增产品 Behavior，不修改产品实现，不偷偷补测试。
 
 ## 步骤
 
-1. 确认 `review_head` 已记录，且 `issue_base...review_head` 对应的实现范围已经完成 Review。
-2. 准备 Acceptance Criteria 与 progress/tracker 的最终状态，记录已 Review 的实现范围、Review、验证与运行结果。外部 tracker 可在此同步；仓库内 tracker/progress/status 只记录为批次待同步状态，不在当前 issue Finalize 中写入或提交。
-3. 若 Finalize 过程中发现任何实现、测试、交付文档、配置或验证遗漏，立即停止当前 issue：保持未完成，不标记 `resolved`，不解除 blockers，不设置成功的 `issue_head`，并报告遗漏请求决策。不得在 Finalize 中补改，也不得自动重新进入 Red-Green、Verify 或 Review。
-4. 仅在未发现上述遗漏后，将当前 issue 的完成状态视为 `resolved` 并解除已满足的 blockers；仓库内对应状态仍留待批次 state-sync。
-5. Finalize 不创建 commit；设置 `issue_head = review_head`。此时当前 `HEAD` 应与 `review_head` 一致。
+1. 确认 `batch_review_head` 已记录为本 batch 唯一一次 `code-review` 的 Review Point，且 `full_review_done = true`。
+2. 若存在 finding-fix，确认它位于 `batch_review_head` 之后、是本轮唯一 finding-fix commit，且已完成必要验证；不得对它再次 Review。
+3. 汇总全部 issue 的 Acceptance、TDD、Verify、Review 和 finding-fix evidence，准备 tracker/progress/status 的最终状态。
+4. 若发现任何实现、测试、交付文档、配置或验证遗漏，立即停止 batch：保持 issue 为 `verified_pending_review` 或 `failed`，不标记 `resolved`，不解除 blockers，并报告遗漏请求决策。不得在 Finalize 中补改或自动重新进入 Red-Green、Verify 或 Review。
+5. 仅在未发现遗漏后，将 `verified_pending_review → resolved`，解除已满足的 blockers，并设置每个完成 issue 的 `issue_head = HEAD`。
 
-## 批次状态同步
+Finalize 不为单个 issue 创建 status commit；普通 Finalize 不创建 commit。Issue 的最终状态只能在 batch Review/fix 完成后统一收敛，避免 reviewer 发现 blocking bug 后出现状态反转。
 
-本次执行批次结束后，如仓库内 tracker/progress/status 存在待同步状态，统一写入全部待同步内容并最多创建 1 个 batch state-sync commit。该 commit：
+## Batch State Sync
 
-- 不混入产品实现、测试、交付文档或配置修改；
+batch Finalize 完成后，如仓库内 tracker/progress/status 存在待同步状态，统一写入全部待同步内容，最多 1 个 batch state-sync commit。该 commit：
+
+- 不混入产品实现、测试、交付文档或配置；
 - 不属于任何单个 issue 的 `issue_base...issue_head` 范围；
-- 不因 issue 数量增加而拆成多个 status commits。
+- 不因 issue 数量增加而拆成多个 status commits；
+- 不触发新的 `code-review`。
 
 ## 出口
 
 - Acceptance Criteria 全部通过；
-- `issue_base...review_head` 的实现范围已经完成 Review；
+- batch Review 已完成，`batch_review_head` 已记录；
+- 如有 finding-fix commit，其必要验证已通过且未执行第二次 Review；
 - Finalize 未发现实现、测试、交付文档、配置或验证遗漏；
 - tracker/progress/status 已同步，或已进入本批次唯一的待同步集合；
-- `issue_head = review_head`；
-- issue 已 `resolved`，已满足的 blockers 已解除。
+- 所有完成 issue 的 `issue_head = HEAD`；
+- 完成 issue 已 `resolved`，已满足的 blockers 已解除。

package/.agents/skills/tdd-implement/references/orchestration.md

@@ -1,6 +1,6 @@
 # 多 issue 编排
 
-仅在存在多个 `Type: task` issue 时生效。每个 issue 仍按 `Red-Green → Verify → Review → Finalize` 独立完成；本文件只负责依赖顺序与 issue 边界推进。
+仅在存在多个 `Type: task` issue 时生效。单 issue 也使用同一套 batch lifecycle，等价于 batch size = 1。
 
 ## 1. 构建依赖图
 
@@ -10,57 +10,73 @@
 - 引用了其它 issue 时建立依赖边；
 - 字段无法解析、依赖节点不存在或出现环时，对受影响 issue 停止调度并报告实际原因，不降级为无依赖。
 
-使用 Kahn 算法按依赖关系分层；层间串行，每层内按 issue 编号串行。
+使用 Kahn 算法按依赖关系分层；层间串行，每层内按 issue 编号串行。状态使用 `ready`、`in_progress`、`verified_pending_review`、`resolved`、`blocked`、`failed`。
 
-## 2. 串行执行
+## 2. Issue loop
+
+记录 batch 开始时的 `batch_base = HEAD`。每个 issue 只执行 issue-level correctness gate，不在 loop 内进行 Review：
 
 ```text
-for each layer:
-  for each issue:
+batch_base = HEAD
+
+for each dependency layer:
+  for each executable issue:
     issue_base = HEAD
     Red-Green
     Verify
-    Review
-    Finalize
-    issue_head = review_head
+    Record Evidence
+    issue_head = HEAD
+    status = verified_pending_review
 ```
 
-`Review` 包含当前 issue committed Review Point 的形成以及完整/增量 Review；具体以 `SKILL.md` 与 `review.md` 为准。
+每个 issue Verify 后必须有完整 evidence ledger，才能进入 `verified_pending_review`。该状态不是最终 `resolved`，也不能提前对外宣称完成。前置 issue 未完成时，其依赖项保持 `blocked`；当前 issue 失败时保持 `failed`，依赖项不被错误放行。
+
+下一个 issue 以当前 `issue_head` 作为新的 `issue_base`。Issue loop 不调用 `code-review`，不执行 Incremental Review，也不因 issue 数量拆分 Review Point。
+
+## 3. Batch lifecycle
+
+全部当前 batch 可执行 issue 完成后，确认 batch 内全部 issue 已 Verify，且 Red-Green、Evidence Record 和 evidence ledger 完整，才执行：
 
-一个 issue Finalize 完成后立即进入下一个可调度 issue。Finalize 不为单个 issue 创建 commit，因此 `issue_head = review_head`；下一个 issue 以当前 `issue_head` 作为新的 `issue_base`。前置 issue 未完成时，其依赖项保持 `blocked`。
+```text
+after all executable issues:
+  Batch Review
+  Finding Fix
+  Finalize completed issues
+  Batch State Sync
+```
+
+- `Batch Review` 以 `batch_base` 为 fixed point，以当前全部交付修改形成的 `batch_review_head` 为唯一 Review Point，整个 batch 只调用 1 次 `code-review`；
+- `Finding Fix` 一次处理全部 blocking findings。Behavioral finding 必须有 RED → GREEN 证据；修复后不再 Review；
+- `Finalize completed issues` 将 `verified_pending_review` 统一收敛为 `resolved`，记录 Acceptance、Review、finding 和 Verify 证据；
+- `Batch State Sync` 统一同步 tracker/progress/status，最多创建 1 个不属于任何单个 issue 范围的 state-sync commit。
 
-验证与 Finalize 分别以 `verify.md`、`finalize.md` 为准，本文件不重复定义其内部规则。
+`batch_review_head` 只记录 batch 的 fresh Review Point；finding-fix 若存在位于其后，但不重新调用 `code-review`。整个 execution batch 的 `code-review calls = 1`、`per-issue review = 0`、`incremental review = 0`。
 
-## 3. 状态收敛
+## 4. 状态与证据
 
-每个 issue Finalize 后只携带后续调度所需的最小状态：
+每个完成 issue 只携带后续调度所需的最小状态：
 
 - `Status`；
 - `issue_base`；
-- `review_head`；
 - `issue_head`；
-- Review 与验证结果；
+- Acceptance、TDD、Verify 和 Rulings evidence；
+- batch Review、finding-fix 与最终状态；
 - 已解除的 blockers。
 
-其中：
-
-- `issue_base...review_head` 是已完成 Review 的实现范围；
-- `issue_head = review_head`，因此 `issue_base...issue_head` 只包含当前 issue 的 Review Point commit，以及可选的唯一 finding-fix commit；
-- `issue_head` 是下一个 issue 的 `issue_base`。
-
-当前层所有 issue 完成后进入下一层。全部层完成后，如仓库内 tracker/progress/status 存在待同步状态，统一写入并最多创建 1 个 batch state-sync commit；该 commit 不属于任何单个 issue 的提交范围。随后确认 issue 与 progress 状态一致即可结束；不额外扩大验证范围，也不再次执行完整 Review。
+Issue evidence 使用 `.scratch/tdd-implement/` ledger。后续 issue 不重复研究前序 issue 已确认且已记录的事实；context compact 后优先使用 ledger 与 git history。Ledger 不保存完整测试输出，只保存命令/场景及结果。
 
 ## 冲突与失败
 
-- `Blocked by` 无法解析、依赖缺失或存在环：停止受影响调度并报告。
-- issue 执行失败：保持未完成，按失败所在 Step 处理；其依赖项继续保持 `blocked`。
-- 多个 issue 修改同一位置且无法安全串行归属：暂停相关 issue，请求用户决定。
-- 外部权限、工具或环境阻塞：记录实际状态，不把失败静默当作完成。
+- `Blocked by` 无法解析、依赖缺失或存在环：停止受影响调度并报告；
+- issue 执行失败：保持未完成，按失败所在 Step 处理；其依赖项继续保持 `blocked`；
+- 多个 issue 修改同一位置且无法安全串行归属：暂停相关 issue，请求用户决定；
+- 外部权限、工具或环境阻塞：记录实际状态，不把失败静默当作完成；
+- Batch Review 或 finding-fix 未完成、无法修复或必要验证失败：batch 不进入 Finalize。
 
 ## 出口
 
-- 所有可执行 issue 均按依赖顺序完成；
-- issue、依赖状态与 progress 一致；
-- 每个完成 issue 的 `issue_base`、`review_head` 与 `issue_head` 边界明确，且每个 issue 最多包含 2 个由本技能产生的实现/Review commits；
-- 仓库内状态同步如有需要，只形成最多 1 个批次 state-sync commit；
-- 不存在被误当作已完成的 blocked issue。
+- 所有可执行 issue 均按依赖顺序完成并有 evidence ledger；
+- 依赖状态、Acceptance、Review、Verify 与 progress 一致；
+- batch 只调用 1 次 `code-review`，Incremental Review 调用次数为 0；
+- 不存在被误当作已完成的 blocked issue；
+- 仓库内状态同步如有需要，只形成最多 1 个 batch state-sync commit。

package/.agents/skills/tdd-implement/references/review.md

@@ -1,98 +1,105 @@
-# Review
+# Batch Review
 
-仅在 Verify 通过后执行。本文件负责当前 issue 的 committed Review Point、Review 状态与增量复核；完整 Review 的维度、reviewer 数量、提示词和输出格式仍以 `code-review` 为唯一事实源。
+仅在 batch 内全部可执行 issue 完成 Red-Green、Verify 和 Evidence Record 后执行。本文件负责 batch 的 committed Review Point、唯一一次 `code-review` 和 finding-fix；`code-review` 的维度、reviewer 数量、提示词和输出格式仍以 [code-review](.agents/skills/code-review/SKILL.md) 为唯一事实源。
 
 ## 状态
 
-当前 issue 首次进入 Review 时初始化以下状态，且仅初始化一次；后续因 finding 修复返回 Red-Green / Verify 后继续 Review 时保留现有状态，不得重新初始化：
+batch 首次进入 Review 时初始化以下状态，且仅初始化一次：
 
-- `issue_base`：当前 issue 开始时的 `HEAD`；
+- `batch_base`：batch 开始时的 `HEAD`；
+- `batch_review_head = null`；
 - `full_review_done = false`；
-- `open_findings = []`；
-- `last_reviewed_head = null`；
-- `review_head = null`；
-- `incremental_review_rounds = 0`。
+- `open_findings = []`。
 
-## 1. 形成 committed Review Point
+整个 execution batch 的调用约束是：
 
-完整 Review 前：
+```text
+code-review calls = 1
+per-issue review = 0
+incremental review = 0
+```
 
-1. 确认当前 issue 交付所需的代码、测试、文档和配置均已完成；
-2. 若最后的文档/配置修改影响已验证证据，重新验证受影响范围；
-3. 将当前 issue 已完成并验证的交付修改合并形成当前 issue 唯一的 Review Point commit；不得按 Behavior、阶段或验证动作拆分 commit；
-4. 确认不存在属于当前 issue 交付内容的未提交修改。
+## Review 前置条件
 
-完整 Review 前每个 issue 只形成 1 个 Review Point commit。Commit 是交付 artifact，不是流程日志。
+开始 Review 前确认：
 
-完整 Review 使用：
+- batch 内全部 issue 已完成 Red-Green 和 Verify；
+- 每个 issue 的 evidence ledger 完整；
+- 所有交付代码、测试、文档和配置均已完成并提交；
+- working tree 不包含当前 batch 的交付遗漏；
+- 当前 `HEAD` 可作为唯一 batch Review Point。
 
-- fixed point：`issue_base`；
-- review target：当前 `HEAD`；
-- diff：`issue_base...HEAD`；
-- spec source：当前 issue/spec。
+未满足前置条件时，不调用 `code-review`，保持 issue 为 `verified_pending_review` 并报告缺口。
 
-不得用未提交 working tree 代替该 committed diff。
+## 1. 形成 batch Review Point
 
-## 2. 完整 Review
+调用 `code-review` 前，将 batch 内全部已验证交付修改合并形成唯一的 committed Review Point。不得按 issue、Behavior、阶段或验证动作拆分 Review Point；不得用未提交 working tree 代替 committed diff。
 
-当 `full_review_done = false` 时，只启动一次逻辑上的完整 `code-review`。
+唯一一次 Review 的输入是：
 
-只有 `code-review` 要求的审查轴均正常返回并形成完整聚合结果后，才：
+- fixed point = `batch_base`；
+- review target = `batch_review_head`；
+- diff = `batch_base...batch_review_head`；
+- spec sources = batch 内全部 tickets；
+- evidence = execution ledger。
 
-- 设置 `full_review_done = true`；
-- 将 blocking findings 写入 `open_findings`；
-- 设置 `last_reviewed_head = HEAD`。
-
-工具错误、stream interruption、sub-agent failure 或其它未形成完整聚合结果的技术失败，不改变 `full_review_done`、`open_findings` 或 `last_reviewed_head`。恢复时只补足缺失的执行结果；这种技术重试不算新的逻辑完整 Review。
+## 2. 唯一一次 code-review
 
-`full_review_done = true` 后，完整 `code-review` 路径关闭，不得再次启动完整双轴 Review。
+整个 execution batch 只调用 1 次 `code-review`，且发生在全部 issue Verify 之后。调用开始前确认 `full_review_done = false`；调用一旦启动即消耗本 batch 唯一机会。
 
-若 `open_findings` 为空，设置 `review_head = last_reviewed_head`，Review 通过。
+若调用正常形成完整聚合结果：
 
-## 3. 增量 Review
-
-存在 `open_findings` 时，只处理已有 finding，不扩大当前 issue 范围。一次性处理当前全部 open findings，不按 finding 拆分 commit。
+- 设置 `full_review_done = true`；
+- 设置 `batch_review_head = HEAD`，记录本次唯一 fresh Review 的 committed Review Point；
+- 将 blocking findings 写入 `open_findings`。
 
-每个 issue 最多执行 1 个逻辑增量 Review 轮次。只有正常形成增量 Review 结论的轮次才计数；工具错误、stream interruption、sub-agent failure 或其它未形成完整结论的技术失败不消耗轮次，只重试当前逻辑轮次。
+若该次调用因技术原因未形成完整聚合结果，停止当前 batch 并报告实际失败；不得重跑 `code-review`，不得进入 Finalize。
 
-若 `incremental_review_rounds >= 1` 且 `open_findings` 仍非空，则停止当前 issue：不得再次启动增量 Review，不设置 `review_head`，不得进入 Finalize，并报告剩余 findings 请求决策。
+若 `open_findings` 为空，batch Review 完成，进入 Finding Fix 的空步骤，再进入 Finalize。
 
-唯一一轮 finding 修复：
+## 3. Finding Fix
 
-1. 一次性修复当前全部 open findings；
-2. 若修复产生新的 Behavior，返回 Red-Green 对该 Behavior 执行 TDD；否则直接进入受影响证据的重新验证；
-3. 重新验证全部修复直接影响的证据；
-4. 将本轮全部修复合并形成最多 1 个 finding-fix commit，并确认不存在属于本轮修复的未提交修改；不得按 finding 拆分 commit；
-5. 只针对 `last_reviewed_head...HEAD` 与现有 findings 做增量 Review；增量 Review 不调用完整 `code-review`。
+若 `open_findings` 非空，一次性处理当前全部 blocking findings，不扩大当前 batch 范围，最多一个 finding-fix commit。
 
-若增量 Review 正常形成结论，先设置 `incremental_review_rounds += 1`。
+### Behavioral finding
 
-增量 Review 通过时：
+行为性 finding 必须走真实的最小 TDD 修复证据：
 
-- 仅关闭已由证据确认解决的 findings；
-- 设置 `last_reviewed_head = HEAD`。
+```text
+Behavioral finding
+    ↓
+write reproducing test
+    ↓
+RED
+    ↓
+minimal fix
+    ↓
+GREEN
+    ↓
+affected verification
+```
 
-增量 Review 正常完成但仍有 open findings 时：
+### Non-behavioral finding
 
-- 保留未关闭 findings；
-- 不推进 `last_reviewed_head`；
-- 停止当前 issue，不设置 `review_head`，不进入 Finalize，并报告剩余 findings 请求决策。
+文档、naming、配置说明或其它非行为性 finding 直接修复，再执行 targeted verification，不为它制造虚假的行为测试。
 
-增量 Review 发生技术失败时：
+Finding Fix 的共同约束：
 
-- 不增加 `incremental_review_rounds`；
-- 不推进 `last_reviewed_head`；
-- 不移除未确认关闭的 findings；
-- 恢复后重试当前逻辑轮次。
+- 不按 finding 拆分 commit；
+- behavioral finding 必须有真实 RED → GREEN 证据；
+- 所有必要验证必须通过；
+- 修复后不得再次调用 `code-review`；
+- 不执行 Incremental Review；
+- 修复无法完成或验证失败时，batch 不进入 Finalize，保留未解决 findings。
 
-当 `open_findings` 为空时，设置 `review_head = last_reviewed_head`，Review 通过。
+验证通过后，将全部修复合并为最多 1 个 finding-fix commit。该 commit 位于 `batch_review_head` 之后，不属于再次 Review 的输入。
 
 ## 出口
 
 - `full_review_done = true`；
+- `batch_review_head` 非空，且指向唯一一次 `code-review` 的 Review Point；
 - `open_findings` 为空；
-- `review_head` 非空；
-- `incremental_review_rounds <= 1`；
-- `review_head` 指向 Review Point commit，或唯一的 finding-fix commit；
-- `issue_base...review_head` 是已经完成 Review 的当前 issue 实现范围，最多包含 2 个由本技能产生的 issue commits；
-- 不存在属于该实现范围的未提交交付修改。
+- Incremental Review 调用次数为 0；
+- `code-review` 调用次数为 1；
+- 当前 `HEAD` 为 `batch_review_head`，或为其后的唯一 finding-fix commit；
+- 不存在属于当前 batch 的未提交交付修改。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heihei0299/matt-skills",
-  "version": "3.0.16",
+  "version": "3.0.18",
   "description": "Agent skills + 项目配置模板：一条命令初始化 opencode / pi-agent 项目（含 mattpocock/skills 上游技能）",
   "type": "module",
   "bin": {