@heihei0299/matt-skills 3.0.20 → 3.0.22

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

@@ -6,23 +6,23 @@ disable-model-invocation: true
 
 # TDD Implement
 
-完成已确认的 spec/task。TDD 的红绿语义、测试质量、seam 和 mock 规则以 [tdd](.agents/skills/tdd/SKILL.md) 为唯一事实源；本技能负责 issue 级实现、证据记录，以及 batch 级 Review 与收尾编排。
+完成已确认的 spec/task。TDD 的红绿语义、测试质量、seam 和 mock 规则以 [tdd](.agents/skills/tdd/SKILL.md) 为唯一事实源；本技能负责 issue 级实现、验证、证据记录与收尾编排。
 
 > Ticket defines WHAT. TDD determines HOW to prove it. Repository determines HOW to implement it.
 
 ## 入口
 
-- **单 issue**：使用下方同一套 issue 与 batch lifecycle，等价于 batch size = 1。
-- **多 issue**：存在多个 `Type: task` 时，读取 [orchestration.md](references/orchestration.md) 后按依赖顺序执行。
+- **单 issue**：直接按下方 issue lifecycle 执行。
+- **多 issue**：存在多个 `Type: task` 时，读取 [orchestration.md](references/orchestration.md) 后按依赖顺序逐个完成。
 - `research`、`prototype`、`grilling` 类型任务分流到对应技能。
 
-正常 Red-Green / Verify 执行由当前 session 原生完成，不为每个 Behavior 或 issue 常规派发 implementer/reviewer。子代理只用于证据不足、证据冲突、复杂诊断等异常升级；常规独立 Review 只发生在 batch 末尾。
+正常 Red-Green / Verify 由当前 session 原生完成，不为每个 Behavior 或 issue 常规派发 implementer/reviewer。子代理只用于证据不足、证据冲突、复杂诊断等异常升级。`code-review` 是独立能力，不属于 `tdd-implement` 的自动生命周期；需要 Review 时由用户显式调用。
 
-## Issue lifecycle:
+## Issue lifecycle
 
-`Red-Green → Verify → Record`
+`Red-Green → Verify → Record → Finalize`
 
-Issue 状态可使用 `ready`、`in_progress`、`verified_pending_review`、`resolved`、`blocked`、`failed`。`verified_pending_review` 不是最终完成；只有 batch Review 与 finding fix 完成后才收敛为 `resolved`。
+Issue 状态使用 `ready`、`in_progress`、`verified`、`resolved`、`blocked`、`failed`。
 
 ### ① Red-Green
 
@@ -36,11 +36,16 @@ Issue 状态可使用 `ready`、`in_progress`、`verified_pending_review`、`res
 
 读取 [verify.md](references/verify.md)，执行当前 issue 所需的最终验证。Verify 只覆盖必要范围，不重复等价验证。
 
-**出口：**当前 issue 所需最终验证通过，并完成要求的真实运行验证；状态进入 `verified_pending_review`。
+**出口：**当前 issue 所需最终验证通过，并完成要求的真实运行验证；状态进入 `verified`。
 
-### ③ Record Evidence
+### ③ Record
 
-Verify 后将每个 issue 的最小充分证据写入 git-ignored `.scratch/tdd-implement/` ledger。只记录命令/场景和结果，不保存完整测试输出；记录 ticket/repository 冲突时使用 `Ruling: <finding> — <decision and why> — <cost if wrong>`。
+Verify 通过后形成当前 issue 唯一的 delivery commit，并记录最小充分证据：
+
+1. 将当前 issue 已完成并验证的代码、测试、交付文档和配置形成 1 个 delivery commit；不得按 Behavior、阶段或验证动作拆 commit；
+2. 设置 `issue_head = HEAD`；
+3. 将 evidence 写入 git-ignored `.scratch/tdd-implement/` ledger，只记录命令/场景和结果，不保存完整测试输出；
+4. ticket/repository 冲突使用 `Ruling: <finding> — <decision and why> — <cost if wrong>` 记录。
 
 ```text
 Issue: <id>
@@ -62,44 +67,30 @@ Rulings:
 - none
 ```
 
-**出口：**ledger 完整，包含 Acceptance、TDD、Verify 和 Rulings 结果；未将 `verified_pending_review` 对外宣称为最终 `resolved`。
-
-## Batch lifecycle:
-
-`Batch Review → Finding Fix → Finalize → State Sync`
-
-全部当前 batch 可执行 issue 都完成 Red-Green、Verify 和 Evidence Record 后，才进入 batch lifecycle。batch review 是整个 execution batch 唯一的 fresh `code-review`；issue loop 内不调用 `code-review`。
-
-### Batch Review
-
-读取 [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
+**出口：**delivery commit 已形成，`issue_head` 已记录，ledger 包含 Acceptance、TDD、Verify 和 Rulings 结果。
 
-读取 [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
+读取 [finalize.md](references/finalize.md)。Finalize 只做当前 issue 的状态收敛和 tracker/progress/status 记录，不新增 Behavior、不修改产品实现、不补测试。
 
-读取 [finalize.md](references/finalize.md)。Finalize 只归档 Acceptance、Review、finding 和验证证据，将 `verified_pending_review → resolved`，解除已满足的 blockers，并记录最终 issue/batch head；不新增 Behavior、不修改产品实现、不偷偷补测试。
+**出口：**当前 issue 已 `resolved`，已满足的 blockers 已解除；仓库内状态变更进入 batch state-sync 集合。
 
-### State Sync
+## Batch State Sync
 
-batch 结束时统一同步仓库内 tracker/progress/status；如确有待同步状态，最多创建 1 个 batch state-sync commit，且不混入产品实现或任何单个 issue 的提交范围。
+本次执行批次结束后，如仓库内 tracker/progress/status 存在待同步状态，统一写入并最多形成 1 个 batch state-sync commit。该 commit 不混入产品实现，也不属于任何单个 issue 的 `issue_base...issue_head` 范围。
 
 ## 运行纪律
 
 - 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；发现失败时保留实际状态，不把失败静默当作完成。
+- Verify 通过后形成当前 issue 唯一 delivery commit，再记录 evidence；Finalize 不创建实现 commit。
+- `tdd-implement` 不自动调用 `code-review`，不执行 per-issue Review、batch Review 或 Incremental Review。
+- 已有充分或等价证据时不重复搜索、读取或验证；后续 issue 优先消费 ledger 与 git history。
+- 只有外部阻塞、需要用户决策、destructive / irreversible 操作、安全敏感行为或 ticket/spec 已无法可靠解释时才暂停。
+- 当前 Step 达到出口后立即进入下一 Step；发现失败时保留实际状态，不把失败静默当作完成。
 
 ## References
 
 - TDD：[tdd](.agents/skills/tdd/SKILL.md)
 - Verify：[verify.md](references/verify.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,32 +1,30 @@
 # Finalize
 
-仅在 batch Review 完成、所有 blocking findings 已关闭且必要验证通过后执行。Finalize 只负责 batch 内 issue 的状态收敛与证据归档，不新增产品 Behavior，不修改产品实现，不偷偷补测试。
+仅在当前 issue 完成 Red-Green、Verify、delivery commit 和 Evidence Record 后执行。Finalize 只负责当前 issue 的状态收敛与 tracker/progress/status 记录，不新增产品 Behavior，不修改产品实现，不补测试。
 
 ## 步骤
 
-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 后出现状态反转。
+1. 确认当前 issue 的必要验证已通过，`issue_head` 已记录为 delivery commit，evidence ledger 包含 Acceptance、TDD、Verify 和 Rulings 结果。
+2. 准备 Acceptance Criteria 与 progress/tracker 的最终状态；外部 tracker 可在此同步，仓库内 tracker/progress/status 只记录为 batch 待同步状态。
+3. 若发现任何实现、测试、交付文档、配置或验证遗漏，立即停止当前 issue：保持未完成，不标记 `resolved`，不解除 blockers，并报告遗漏请求决策。不得在 Finalize 中补改，也不得自动重新进入 Red-Green 或 Verify。
+4. 仅在未发现上述遗漏后，将当前 issue 标记为 `resolved`，解除已满足的 blockers。
+5. Finalize 不创建 commit；设置最终 `issue_head = HEAD`。
 
 ## Batch State Sync
 
-batch Finalize 完成后，如仓库内 tracker/progress/status 存在待同步状态，统一写入全部待同步内容，最多 1 个 batch state-sync commit。该 commit：
+本次执行批次结束后，如仓库内 tracker/progress/status 存在待同步状态，统一写入全部待同步内容并最多创建 1 个 batch state-sync commit。该 commit：
 
 - 不混入产品实现、测试、交付文档或配置；
 - 不属于任何单个 issue 的 `issue_base...issue_head` 范围；
 - 不因 issue 数量增加而拆成多个 status commits；
-- 不触发新的 `code-review`。
+- 不触发 `code-review`。
 
 ## 出口
 
 - Acceptance Criteria 全部通过；
-- batch Review 已完成，`batch_review_head` 已记录；
-- 如有 finding-fix commit，其必要验证已通过且未执行第二次 Review；
+- 当前 issue 必要验证已通过；
+- delivery commit 与 evidence ledger 已记录；
 - Finalize 未发现实现、测试、交付文档、配置或验证遗漏；
 - tracker/progress/status 已同步，或已进入本批次唯一的待同步集合；
-- 所有完成 issue 的 `issue_head = HEAD`；
-- 完成 issue 已 `resolved`，已满足的 blockers 已解除。
+- `issue_head = HEAD`；
+- issue 已 `resolved`，已满足的 blockers 已解除。

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

@@ -1,6 +1,6 @@
 # 多 issue 编排
 
-仅在存在多个 `Type: task` issue 时生效。单 issue 也使用同一套 batch lifecycle，等价于 batch size = 1。
+仅在存在多个 `Type: task` issue 时生效。每个 issue 都按 `Red-Green → Verify → Record → Finalize` 独立完成；本文件只负责依赖顺序与 batch state sync。
 
 ## 1. 构建依赖图
 
@@ -10,49 +10,29 @@
 - 引用了其它 issue 时建立依赖边；
 - 字段无法解析、依赖节点不存在或出现环时，对受影响 issue 停止调度并报告实际原因，不降级为无依赖。
 
-使用 Kahn 算法按依赖关系分层；层间串行，每层内按 issue 编号串行。状态使用 `ready`、`in_progress`、`verified_pending_review`、`resolved`、`blocked`、`failed`。
+使用 Kahn 算法按依赖关系分层；层间串行，每层内按 issue 编号串行。状态使用 `ready`、`in_progress`、`verified`、`resolved`、`blocked`、`failed`。
 
-## 2. Issue loop
-
-记录 batch 开始时的 `batch_base = HEAD`。每个 issue 只执行 issue-level correctness gate，不在 loop 内进行 Review：
+## 2. 串行执行
 
 ```text
-batch_base = HEAD
-
 for each dependency layer:
   for each executable issue:
     issue_base = HEAD
     Red-Green
     Verify
-    Record Evidence
+    Record
+    Finalize
     issue_head = HEAD
-    status = verified_pending_review
-```
-
-每个 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 完整，才执行：
-
-```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。
+- `Red-Green` 与 `Verify` 是当前 issue 的 correctness gate；
+- `Record` 形成当前 issue 唯一 delivery commit，设置 `issue_head` 并记录 evidence ledger；
+- `Finalize` 只收敛状态、解除已满足 blockers，并把仓库内 tracker/progress/status 变更加入 batch state-sync 集合；
+- Issue loop 不调用 `code-review`，不执行 per-issue Review、batch Review 或 Incremental Review。
 
-`batch_review_head` 只记录 batch 的 fresh Review Point；finding-fix 若存在位于其后，但不重新调用 `code-review`。整个 execution batch 的 `code-review calls = 1`、`per-issue review = 0`、`incremental review = 0`。
+当前 issue Finalize 完成后，依赖它的 issue 才可进入可执行状态。下一个 issue 以当前 `issue_head` 作为新的 `issue_base`。
 
-## 4. 状态与证据
+## 3. 状态与证据
 
 每个完成 issue 只携带后续调度所需的最小状态：
 
@@ -60,23 +40,31 @@ after all executable issues:
 - `issue_base`；
 - `issue_head`；
 - Acceptance、TDD、Verify 和 Rulings evidence；
-- batch Review、finding-fix 与最终状态；
 - 已解除的 blockers。
 
 Issue evidence 使用 `.scratch/tdd-implement/` ledger。后续 issue 不重复研究前序 issue 已确认且已记录的事实；context compact 后优先使用 ledger 与 git history。Ledger 不保存完整测试输出，只保存命令/场景及结果。
 
+## 4. Batch State Sync
+
+全部可执行 issue 完成后，如仓库内 tracker/progress/status 存在待同步状态，统一写入并最多创建 1 个 batch state-sync commit。该 commit：
+
+- 不混入产品实现、测试、交付文档或配置；
+- 不属于任何单个 issue 的 `issue_base...issue_head` 范围；
+- 不因 issue 数量增加而拆成多个 status commits；
+- 不触发 `code-review`。
+
 ## 冲突与失败
 
 - `Blocked by` 无法解析、依赖缺失或存在环：停止受影响调度并报告；
 - issue 执行失败：保持未完成，按失败所在 Step 处理；其依赖项继续保持 `blocked`；
 - 多个 issue 修改同一位置且无法安全串行归属：暂停相关 issue，请求用户决定；
 - 外部权限、工具或环境阻塞：记录实际状态，不把失败静默当作完成；
-- Batch Review 或 finding-fix 未完成、无法修复或必要验证失败：batch 不进入 Finalize。
+- Finalize 发现实现、测试、交付文档、配置或验证遗漏：当前 issue 不标记 `resolved`，其依赖项继续保持 `blocked`。
 
 ## 出口
 
 - 所有可执行 issue 均按依赖顺序完成并有 evidence ledger；
-- 依赖状态、Acceptance、Review、Verify 与 progress 一致；
-- batch 只调用 1 次 `code-review`，Incremental Review 调用次数为 0；
+- issue、依赖状态、Acceptance、Verify 与 progress 一致；
+- `tdd-implement` 的 `code-review` 调用次数为 0；
 - 不存在被误当作已完成的 blocked issue；
 - 仓库内状态同步如有需要，只形成最多 1 个 batch state-sync commit。

package/package.json

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

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

@@ -1,105 +0,0 @@
-# Batch 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) 为唯一事实源。
-
-## 状态
-
-batch 首次进入 Review 时初始化以下状态，且仅初始化一次：
-
-- `batch_base`：batch 开始时的 `HEAD`；
-- `batch_review_head = null`；
-- `full_review_done = false`；
-- `open_findings = []`。
-
-整个 execution batch 的调用约束是：
-
-```text
-code-review calls = 1
-per-issue review = 0
-incremental review = 0
-```
-
-## Review 前置条件
-
-开始 Review 前确认：
-
-- batch 内全部 issue 已完成 Red-Green 和 Verify；
-- 每个 issue 的 evidence ledger 完整；
-- 所有交付代码、测试、文档和配置均已完成并提交；
-- working tree 不包含当前 batch 的交付遗漏；
-- 当前 `HEAD` 可作为唯一 batch Review Point。
-
-未满足前置条件时，不调用 `code-review`，保持 issue 为 `verified_pending_review` 并报告缺口。
-
-## 1. 形成 batch Review Point
-
-调用 `code-review` 前，将 batch 内全部已验证交付修改合并形成唯一的 committed Review Point。不得按 issue、Behavior、阶段或验证动作拆分 Review Point；不得用未提交 working tree 代替 committed diff。
-
-唯一一次 Review 的输入是：
-
-- fixed point = `batch_base`；
-- review target = `batch_review_head`；
-- diff = `batch_base...batch_review_head`；
-- spec sources = batch 内全部 tickets；
-- evidence = execution ledger。
-
-## 2. 唯一一次 code-review
-
-整个 execution batch 只调用 1 次 `code-review`，且发生在全部 issue Verify 之后。调用开始前确认 `full_review_done = false`；调用一旦启动即消耗本 batch 唯一机会。
-
-若调用正常形成完整聚合结果：
-
-- 设置 `full_review_done = true`；
-- 设置 `batch_review_head = HEAD`，记录本次唯一 fresh Review 的 committed Review Point；
-- 将 blocking findings 写入 `open_findings`。
-
-若该次调用因技术原因未形成完整聚合结果，停止当前 batch 并报告实际失败；不得重跑 `code-review`，不得进入 Finalize。
-
-若 `open_findings` 为空，batch Review 完成，进入 Finding Fix 的空步骤，再进入 Finalize。
-
-## 3. Finding Fix
-
-若 `open_findings` 非空，一次性处理当前全部 blocking findings，不扩大当前 batch 范围，最多一个 finding-fix commit。
-
-### Behavioral finding
-
-行为性 finding 必须走真实的最小 TDD 修复证据：
-
-```text
-Behavioral finding
-    ↓
-write reproducing test
-    ↓
-RED
-    ↓
-minimal fix
-    ↓
-GREEN
-    ↓
-affected verification
-```
-
-### Non-behavioral finding
-
-文档、naming、配置说明或其它非行为性 finding 直接修复，再执行 targeted verification，不为它制造虚假的行为测试。
-
-Finding Fix 的共同约束：
-
-- 不按 finding 拆分 commit；
-- behavioral finding 必须有真实 RED → GREEN 证据；
-- 所有必要验证必须通过；
-- 修复后不得再次调用 `code-review`；
-- 不执行 Incremental Review；
-- 修复无法完成或验证失败时，batch 不进入 Finalize，保留未解决 findings。
-
-验证通过后，将全部修复合并为最多 1 个 finding-fix commit。该 commit 位于 `batch_review_head` 之后，不属于再次 Review 的输入。
-
-## 出口
-
-- `full_review_done = true`；
-- `batch_review_head` 非空，且指向唯一一次 `code-review` 的 Review Point；
-- `open_findings` 为空；
-- Incremental Review 调用次数为 0；
-- `code-review` 调用次数为 1；
-- 当前 `HEAD` 为 `batch_review_head`，或为其后的唯一 finding-fix commit；
-- 不存在属于当前 batch 的未提交交付修改。