@heihei0299/matt-skills 3.0.15 → 3.0.17

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

@@ -14,7 +14,7 @@ disable-model-invocation: true
 - **多 issue**：存在多个 `Type: task` 时，读取 [orchestration.md](references/orchestration.md) 后按依赖顺序逐个完成。
 - `research`、`prototype`、`grilling` 类型任务分流到对应技能。
 
-每个 issue 开始时记录 `issue_base = HEAD`。一个 issue 可以包含一个或多个 commits；不要求固定 commit 数量，也不为满足数量约束强制 amend、squash 或重写历史。
+每个 issue 开始时记录 `issue_base = HEAD`。Commit 是交付 artifact，不是流程日志：Red-Green / Verify 期间不因 Behavior、阶段切换或验证动作创建 commit。Verify 通过后形成 1 个 Review Point commit；若唯一一次 `code-review` 产生 blocking findings，自动直接修复并最多再形成 1 个 finding-fix commit。
 
 生命周期：
 
@@ -50,31 +50,34 @@ disable-model-invocation: true
 
 Verify 通过后读取 [review.md](references/review.md)。
 
-先将当前 issue 交付所需的代码、测试、文档和配置形成 committed Review Point，再按 `review.md` 完成一次完整 Review 与必要的增量 Review。
+先将当前 issue 交付所需的代码、测试、文档和配置形成唯一的 committed Review Point commit，再按 `review.md` 调用且只调用 1 次 `code-review`。若产生 blocking findings，直接自动修复并执行必要验证；修复阶段不进入 Red-Green、不执行 TDD、不执行 Incremental Review，也不再次调用 `code-review`。
 
-完整 Review 的审查维度、reviewer 数量、提示词和输出格式仍以 [code-review](.agents/skills/code-review/SKILL.md) 为唯一事实源。
+唯一一次 `code-review` 的审查维度、reviewer 数量、提示词和输出格式仍以 [code-review](.agents/skills/code-review/SKILL.md) 为唯一事实源。
 
 **出口：**
 
 - `full_review_done = true`；
 - `open_findings` 为空；
-- `review_head` 已记录；
-- 当前 issue 的实现范围已完整进入 Review 证据。
+- `review_head` 已记录为唯一一次 `code-review` 的 Review Point；
+- 若产生 finding-fix commit，其必要验证已通过。
 
 ## Finalize
 
-Review 通过后读取 [finalize.md](references/finalize.md)，只做 tracker/progress/status 收尾并记录 `issue_head`。
+Review 完成后读取 [finalize.md](references/finalize.md)，只做 tracker/progress/status 收尾并记录 `issue_head`。
 
-Finalize 不新增产品 Behavior，也不修改已经 Review 的实现内容。若收尾时发现实现、测试、文档/配置或验证遗漏，停止当前 issue，不标记 `resolved`，并按 `finalize.md` 报告遗漏请求决策；不得在 Finalize 中补改或重新进入 Red-Green、Verify 或 Review。
+Finalize 不新增产品 Behavior，也不修改 Review 阶段已经完成的实现与 finding 修复，不为单个 issue 创建收尾 commit。若收尾时发现实现、测试、文档/配置或验证遗漏，停止当前 issue，不标记 `resolved`，并按 `finalize.md` 报告遗漏请求决策；不得在 Finalize 中补改或重新进入 Red-Green、Verify 或 Review。
+
+本次执行批次结束后，如仓库内 tracker/progress/status 存在待同步状态，统一写入并最多形成 1 个 batch state-sync commit；该 commit 不属于任何单个 issue 的实现/Review commit range。
 
 ## 运行纪律
 
 - Red-Green 必须覆盖当前 issue 的全部待实现 Behavior，不能只对第一个改动执行 TDD。
 - 一个 Behavior 完成后继续下一个 Behavior，直到 Step ① 出口满足。
 - Verify 只做当前 issue 必要的最终验证；已通过的等价验证不机械重复。
-- 完整 Review 前必须形成 committed Review Point；不得用未提交 working tree 代替 `code-review` 所需的 committed diff。
-- 每个 issue 只有一次逻辑上的完整双轴 Review；完整 Review 之后只处理增量 Review。技术失败或中断的恢复规则以 `review.md` 为准。
-- 当前 issue Review 与 Finalize 完成后，才能进入下一个 issue；下一个 issue 以当时的 `HEAD` 作为新的 `issue_base`。
+- Red-Green / Verify 期间不按 Behavior、阶段或验证动作拆 commit；完整 Review 前只形成 1 个 committed Review Point。
+- 每个 issue 最多调用 1 次 `code-review`；该调用一旦启动即消耗唯一机会，不因 findings、修复或技术失败再次调用。
+- blocking findings 自动直接修复；修复阶段禁止 TDD、禁止 Incremental Review，最多形成 1 个 finding-fix commit。
+- 当前 issue Review 与 Finalize 完成后，才能进入下一个 issue；下一个 issue 以当时的 `issue_head` 作为新的 `issue_base`。
 - 当前 Step 达到出口后继续进入下一 Step；仅在需要用户决策或存在外部阻塞时暂停。
 
 ## References
@@ -83,5 +86,5 @@ Finalize 不新增产品 Behavior，也不修改已经 Review 的实现内容。
 - 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)
+- 唯一 Review：[code-review](.agents/skills/code-review/SKILL.md)
 - 多 issue 编排：[orchestration.md](references/orchestration.md)

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

@@ -1,24 +1,30 @@
 # Finalize
 
-仅在 Verify 与 Review 通过后执行。Finalize 只负责 tracker/progress/status 收尾，不新增产品 Behavior，也不修改已经 Review 的代码、测试、交付文档或配置。
+仅在 Verify 与 Review 完成后执行。Finalize 只负责 tracker/progress/status 收尾，不新增产品 Behavior，不修改 Review 阶段已经完成的实现或 finding 修复，也不为单个 issue 创建收尾 commit。
 
 ## 步骤
 
-1. 确认 `review_head` 已记录，且 `issue_base...review_head` 对应的实现范围已经完成 Review。
-2. 更新 Acceptance Criteria 与 progress/tracker，记录已 Review 的实现范围、Review、验证与运行结果；此时不得提前标记 `resolved` 或解除 blockers。
-3. 若 Finalize 过程中发现任何实现、测试、交付文档、配置或验证遗漏，立即停止当前 issue：保持未完成，不标记 `resolved`，不解除 blockers，不设置成功的 `issue_head`，并报告遗漏请求决策。不得在 Finalize 中补改，也不得自动重新进入 Red-Green、Verify 或 Review。
-4. 仅在未发现上述遗漏且所有必要状态同步准备完成后，才同步 `resolved` / blockers 状态。
-5. 若状态同步修改了仓库内的 tracker/progress/status 文件，将这些状态修改提交；不得在该提交中混入产品实现或其它未 Review 的交付修改。
-6. 确认所有必要状态同步成功后，设置 `issue_head = HEAD`。
+1. 确认 `review_head` 已记录为当前 issue 唯一一次 `code-review` 的 Review Point。
+2. 若 `HEAD != review_head`，确认 `review_head...HEAD` 只包含唯一的 finding-fix commit，且该修复已经完成必要验证；不得对该 commit 再执行 Review。
+3. 准备 Acceptance Criteria 与 progress/tracker 的最终状态，记录唯一 Review、finding 修复（如有）、验证与运行结果。外部 tracker 可在此同步；仓库内 tracker/progress/status 只记录为批次待同步状态，不在当前 issue Finalize 中写入或提交。
+4. 若 Finalize 过程中发现任何实现、测试、交付文档、配置或验证遗漏，立即停止当前 issue：保持未完成，不标记 `resolved`，不解除 blockers，不设置成功的 `issue_head`，并报告遗漏请求决策。不得在 Finalize 中补改，也不得自动重新进入 Red-Green、Verify 或 Review。
+5. 仅在未发现上述遗漏后，将当前 issue 的完成状态视为 `resolved` 并解除已满足的 blockers；仓库内对应状态仍留待批次 state-sync。
+6. Finalize 不创建 commit；设置 `issue_head = HEAD`。
 
-无需为了固定 commit 数量而 amend、squash 或重写当前 issue 的历史。
+## 批次状态同步
+
+本次执行批次结束后，如仓库内 tracker/progress/status 存在待同步状态，统一写入全部待同步内容并最多创建 1 个 batch state-sync commit。该 commit：
+
+- 不混入产品实现、测试、交付文档或配置修改；
+- 不属于任何单个 issue 的 `issue_base...issue_head` 范围；
+- 不因 issue 数量增加而拆成多个 status commits。
 
 ## 出口
 
 - Acceptance Criteria 全部通过；
-- `issue_base...review_head` 的实现范围已经完成 Review；
+- `review_head` 已记录为唯一一次 `code-review` 的 Review Point；
+- 如有 finding-fix commit，其必要验证已通过且未执行第二次 Review；
 - Finalize 未发现实现、测试、交付文档、配置或验证遗漏；
-- tracker/progress/status 与实际 Review、验证和完成状态一致；
-- `review_head` 之后若存在 commits，只包含当前 issue 的状态收尾修改；
-- `issue_head = HEAD` 已记录；
+- tracker/progress/status 已同步，或已进入本批次唯一的待同步集合；
+- `issue_head = HEAD`；
 - issue 已 `resolved`，已满足的 blockers 已解除。

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

@@ -25,9 +25,9 @@ for each layer:
     issue_head = HEAD
 ```
 
-`Review` 包含当前 issue committed Review Point 的形成以及完整/增量 Review；具体以 `SKILL.md` 与 `review.md` 为准。
+`Review` 包含当前 issue committed Review Point 的形成、唯一一次 `code-review`，以及 blocking findings 的直接自动修复（如有）；不执行 Incremental Review。
 
-一个 issue Finalize 完成后立即进入下一个可调度 issue。下一个 issue 以当前 `issue_head` 作为新的 `issue_base`。前置 issue 未完成时，其依赖项保持 `blocked`。
+一个 issue Finalize 完成后立即进入下一个可调度 issue。Finalize 不为单个 issue 创建 commit，因此 `issue_head = HEAD`；下一个 issue 以当前 `issue_head` 作为新的 `issue_base`。前置 issue 未完成时，其依赖项保持 `blocked`。
 
 验证与 Finalize 分别以 `verify.md`、`finalize.md` 为准，本文件不重复定义其内部规则。
 
@@ -44,11 +44,12 @@ for each layer:
 
 其中：
 
-- `issue_base...review_head` 是已完成 Review 的实现范围；
-- `issue_base...issue_head` 是当前 issue 的完整提交范围；
+- `issue_base...review_head` 是唯一一次 `code-review` 审查的 committed Review Point 范围；
+- 若存在 finding-fix commit，则 `review_head...issue_head` 只包含该唯一自动修复 commit，且不再 Review；
+- `issue_base...issue_head` 是当前 issue 的完整提交范围，最多包含 Review Point commit 与可选的 finding-fix commit；
 - `issue_head` 是下一个 issue 的 `issue_base`。
 
-当前层所有 issue 完成后进入下一层。全部层完成后，确认 issue 与 progress 状态一致即可结束；不额外扩大验证范围，也不再次执行完整 Review。
+当前层所有 issue 完成后进入下一层。全部层完成后，如仓库内 tracker/progress/status 存在待同步状态，统一写入并最多创建 1 个 batch state-sync commit；该 commit 不属于任何单个 issue 的提交范围。随后确认 issue 与 progress 状态一致即可结束；不额外扩大验证范围，也不再次执行 `code-review`。
 
 ## 冲突与失败
 
@@ -61,5 +62,7 @@ for each layer:
 
 - 所有可执行 issue 均按依赖顺序完成；
 - issue、依赖状态与 progress 一致；
-- 每个完成 issue 的 `issue_base`、`review_head` 与 `issue_head` 边界明确；
+- 每个完成 issue 只调用 1 次 `code-review`，Incremental Review 调用次数为 0；
+- 每个完成 issue 最多包含 2 个由本技能产生的实现/修复 commits；
+- 仓库内状态同步如有需要，只形成最多 1 个批次 state-sync commit；
 - 不存在被误当作已完成的 blocked issue。

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

@@ -1,30 +1,28 @@
 # Review
 
-仅在 Verify 通过后执行。本文件负责当前 issue 的 committed Review Point、Review 状态与增量复核；完整 Review 的维度、reviewer 数量、提示词和输出格式仍以 `code-review` 为唯一事实源。
+仅在 Verify 通过后执行。本文件负责当前 issue 的 committed Review Point、唯一一次 `code-review` 以及 finding 自动修复；`code-review` 的维度、reviewer 数量、提示词和输出格式仍以 `code-review` 为唯一事实源。
 
 ## 状态
 
-当前 issue 首次进入 Review 时初始化以下状态，且仅初始化一次；后续因 finding 修复返回 Red-Green / Verify 后继续 Review 时保留现有状态，不得重新初始化：
+当前 issue 首次进入 Review 时初始化以下状态，且仅初始化一次：
 
 - `issue_base`：当前 issue 开始时的 `HEAD`；
 - `full_review_done = false`；
 - `open_findings = []`；
-- `last_reviewed_head = null`；
-- `review_head = null`；
-- `incremental_review_rounds = 0`。
+- `review_head = null`。
 
 ## 1. 形成 committed Review Point
 
-完整 Review 前：
+调用 `code-review` 前：
 
 1. 确认当前 issue 交付所需的代码、测试、文档和配置均已完成；
 2. 若最后的文档/配置修改影响已验证证据，重新验证受影响范围；
-3. 将当前 issue 已完成并验证的交付修改提交到当前 branch；
+3. 将当前 issue 已完成并验证的交付修改合并形成当前 issue 唯一的 Review Point commit；不得按 Behavior、阶段或验证动作拆分 commit；
 4. 确认不存在属于当前 issue 交付内容的未提交修改。
 
-一个 issue 可以在这里已有一个或多个 commits。Commit 是 Review artifact，不代表 issue 已完成。
+每个 issue 只形成 1 个 Review Point commit。Commit 是交付 artifact，不是流程日志。
 
-完整 Review 使用：
+唯一一次 `code-review` 使用：
 
 - fixed point：`issue_base`；
 - review target：当前 `HEAD`；
@@ -33,67 +31,43 @@
 
 不得用未提交 working tree 代替该 committed diff。
 
-## 2. 完整 Review
+## 2. 唯一一次 code-review
 
-当 `full_review_done = false` 时，只启动一次逻辑上的完整 `code-review`。
+每个 issue 最多调用 1 次 `code-review`。
 
-只有 `code-review` 要求的审查轴均正常返回并形成完整聚合结果后，才：
+调用开始前确认 `full_review_done = false`。调用一旦启动，即消耗当前 issue 唯一的 `code-review` 机会；不得因 findings、修复、工具错误、stream interruption、sub-agent failure 或其它原因再次调用 `code-review`。
 
-- 设置 `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。
-
-`full_review_done = true` 后，完整 `code-review` 路径关闭，不得再次启动完整双轴 Review。
-
-若 `open_findings` 为空，设置 `review_head = last_reviewed_head`，Review 通过。
-
-## 3. 增量 Review
-
-存在 `open_findings` 时，只处理已有 finding，不扩大当前 issue 范围。可将由同一改动共同解决的相关 findings 一起处理，不要求“一 finding 一 commit”。
+若 `code-review` 正常形成完整聚合结果：
 
-每个 issue 最多执行 2 个逻辑增量 Review 轮次。只有正常形成增量 Review 结论的轮次才计数；工具错误、stream interruption、sub-agent failure 或其它未形成完整结论的技术失败不消耗轮次，只重试当前逻辑轮次。
-
-每轮修复前，若 `incremental_review_rounds >= 2` 且 `open_findings` 仍非空，则停止当前 issue：不得再次启动增量 Review，不设置 `review_head`，不得进入 Finalize，并报告剩余 findings 请求决策。
-
-每轮修复：
-
-1. 修复选定的 open findings；
-2. 若修复产生新的 Behavior，返回 Red-Green 对该 Behavior 执行 TDD；否则直接进入受影响证据的重新验证；
-3. 重新验证修复直接影响的证据；
-4. 将本轮修复提交到当前 issue 的 commit range，并确认不存在属于本轮修复的未提交修改；
-5. 只针对 `last_reviewed_head...HEAD` 与本轮目标 findings 做增量 Review；增量 Review 不调用完整 `code-review`。
-
-若增量 Review 正常形成结论，先设置 `incremental_review_rounds += 1`。
-
-增量 Review 通过时：
+- 设置 `full_review_done = true`；
+- 设置 `review_head = HEAD`，记录本次唯一 Review 的 committed Review Point；
+- 将 blocking findings 写入 `open_findings`。
 
-- 仅关闭本轮已由证据确认解决的 findings；
-- 设置 `last_reviewed_head = HEAD`。
+若该次调用因技术原因未形成完整聚合结果，停止当前 issue并报告实际失败；不得重跑 `code-review`，不得进入 Finalize。
 
-增量 Review 正常完成但未通过时：
+若 `open_findings` 为空，Review 完成，进入 Finalize。
 
-- 保留未关闭 findings；
-- 不推进 `last_reviewed_head`；
-- 若尚未达到 2 轮上限，下一轮继续从上一次成功的 `last_reviewed_head` 审查累计的未 Review 修复。
+## 3. blocking findings 自动修复
 
-增量 Review 发生技术失败时：
+若 `open_findings` 非空：
 
-- 不增加 `incremental_review_rounds`；
-- 不推进 `last_reviewed_head`；
-- 不移除未确认关闭的 findings；
-- 恢复后重试当前逻辑轮次。
+1. 一次性直接修复当前全部 blocking findings，不扩大当前 issue 范围；
+2. 修复阶段不得返回 Red-Green，不执行 TDD；
+3. 对修复直接影响的证据执行必要验证；
+4. 验证通过后，将全部修复合并形成最多 1 个 finding-fix commit；不得按 finding 拆分 commit；
+5. 修复后禁止 Incremental Review，禁止再次调用 `code-review`；
+6. 确认 findings 已按本轮修复处理后清空 `open_findings`。
 
-当 `open_findings` 为空时，设置 `review_head = last_reviewed_head`，Review 通过。
+若修复无法完成或必要验证不通过，停止当前 issue，保留未解决 findings，不进入 Finalize。
 
-当 `incremental_review_rounds = 2` 且 `open_findings` 仍非空时，Review 不通过：保持 issue 未完成，不设置 `review_head`，不进入 Finalize，并报告剩余 findings 请求决策。
+finding-fix commit 位于 `review_head` 之后；它是唯一 Review 后的自动修复，不属于再次 Review 的输入。
 
 ## 出口
 
 - `full_review_done = true`；
+- `review_head` 非空，且指向唯一一次 `code-review` 的 Review Point；
 - `open_findings` 为空；
-- `review_head` 非空；
-- `incremental_review_rounds <= 2`；
-- `issue_base...review_head` 是已经完成 Review 的当前 issue 实现范围；
-- 不存在属于该实现范围的未提交交付修改。
+- Incremental Review 调用次数为 0；
+- `code-review` 调用次数为 1；
+- 当前 `HEAD` 为 `review_head`，或为其后的唯一 finding-fix commit；
+- 不存在属于当前 issue 的未提交交付修改。

package/package.json

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