@heihei0299/matt-skills 3.0.7 → 3.0.9

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

@@ -14,6 +14,12 @@ disable-model-invocation: true
 - **多 issue**：存在多个 `Type: task` 时，读取 [orchestration.md](references/orchestration.md) 后按依赖顺序逐个完成。
 - `research`、`prototype`、`grilling` 类型任务分流到对应技能。
 
+每个 issue 开始时记录 `issue_base = HEAD`。一个 issue 可以包含一个或多个 commits；不要求固定 commit 数量，也不为满足数量约束强制 amend、squash 或重写历史。
+
+生命周期：
+
+`Red-Green → Verify → Review → Finalize`
+
 ## Steps
 
 ### ① Red-Green
@@ -35,53 +41,47 @@ disable-model-invocation: true
 
 读取 [verify.md](references/verify.md)，执行当前 issue 所需的最终验证。
 
-最终验证通过且 diff 稳定后进入 Review。
-
-#### Review
-
-每个 issue 维护以下 Review 状态：
+**出口：**
 
-- `full_review_done = false`
-- `open_findings = []`
+- 当前 issue 所需最终验证通过；
+- 要求的真实运行验证完成。
 
-当 `full_review_done = false` 时，只调用一次完整 `code-review`。完成后立即设置 `full_review_done = true`，并将 blocking findings 写入 `open_findings`。
+### ③ Review
 
-当 `full_review_done = true` 时，完整 `code-review` 路径关闭，不得再次启动完整双轴 Review。后续仅处理 `open_findings`：
+Verify 通过后读取 [review.md](references/review.md)。
 
-1. 仅修复对应 finding，不扩大当前 issue 范围；
-2. 重新验证该修复直接影响的证据；
-3. 直接针对该 finding 与修复 diff 做增量 Review；增量 Review 不调用完整 `code-review`；
-4. 复核通过后从 `open_findings` 移除该 finding；
-5. 若修复产生新的 Behavior，返回 Red-Green 对该 Behavior 执行 TDD，再回 Verify 验证受影响范围；`full_review_done` 保持为 `true`。
+先将当前 issue 交付所需的代码、测试、文档和配置形成 committed Review Point，再按 `review.md` 完成一次完整 Review 与必要的增量 Review。
 
-`full_review_done = true` 且 `open_findings` 为空时 Review 才算通过。审查维度、reviewer 数量、提示词和输出格式仍以 `code-review` 为唯一事实源。
+完整 Review 的审查维度、reviewer 数量、提示词和输出格式仍以 [code-review](.agents/skills/code-review/SKILL.md) 为唯一事实源。
 
 **出口：**
 
-- 当前 issue 所需最终验证通过；
-- 要求的真实运行验证完成；
 - `full_review_done = true`；
-- `open_findings` 为空。
+- `open_findings` 为空；
+- `review_head` 已记录；
+- 当前 issue 的实现范围已完整进入 Review 证据。
 
 ## Finalize
 
-Verify 与 Review 通过后读取 [finalize.md](references/finalize.md)，完成当前 issue 的必要同步、独立 commit 与 tracker/progress 收尾。
+Review 通过后读取 [finalize.md](references/finalize.md)，只做 tracker/progress/status 收尾并记录 `issue_head`。
 
-Finalize 不新增产品 Behavior；若发现实现或验证遗漏，回到对应 Step 完成后再收尾。
+Finalize 不新增产品 Behavior，也不修改已经 Review 的实现内容。若收尾时发现实现、测试、文档/配置或验证遗漏，停止当前 issue，不标记 `resolved`，并按 `finalize.md` 报告遗漏请求决策；不得在 Finalize 中补改或重新进入 Red-Green、Verify 或 Review。
 
 ## 运行纪律
 
 - Red-Green 必须覆盖当前 issue 的全部待实现 Behavior，不能只对第一个改动执行 TDD。
 - 一个 Behavior 完成后继续下一个 Behavior，直到 Step ① 出口满足。
 - Verify 只做当前 issue 必要的最终验证；已通过的等价验证不机械重复。
-- 每个 issue 的完整双轴 Review 只允许从 `full_review_done = false` 进入一次；之后只处理 `open_findings` 的增量 Review。
-- 每个 issue 的完整 Review 通过后创建一个独立 commit；该 commit 完成后才能进入下一个 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`。
 - 当前 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)
+- 完整 Review：[code-review](.agents/skills/code-review/SKILL.md)
 - 多 issue 编排：[orchestration.md](references/orchestration.md)

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

@@ -1,16 +1,24 @@
 # Finalize
 
-仅在 Verify 与 Review 通过后执行；不新增产品 Behavior。
+仅在 Verify 与 Review 通过后执行。Finalize 只负责 tracker/progress/status 收尾，不新增产品 Behavior，也不修改已经 Review 的代码、测试、交付文档或配置。
 
-1. 完成实现要求的必要 docs/config 同步。
-2. 为当前 issue 创建一个独立 commit。
-3. 更新 Acceptance Criteria 与 progress/tracker，记录 commit、Review、验证与运行结果。
-4. 收尾状态同步成功后，将 issue 标记 `resolved`，并解除已满足的 blockers。
+## 步骤
 
-若发现实现或验证遗漏，返回对应 Step 完成后再收尾。
+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`。
+
+无需为了固定 commit 数量而 amend、squash 或重写当前 issue 的历史。
 
 ## 出口
 
-- 当前 issue 的独立 commit 已创建；
 - Acceptance Criteria 全部通过；
-- issue、blockers 与 tracker/progress 和实际完成状态一致。
+- `issue_base...review_head` 的实现范围已经完成 Review；
+- Finalize 未发现实现、测试、交付文档、配置或验证遗漏；
+- tracker/progress/status 与实际 Review、验证和完成状态一致；
+- `review_head` 之后若存在 commits，只包含当前 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 → Finalize` 独立完成；本文件只负责依赖顺序与状态推进。
+仅在存在多个 `Type: task` issue 时生效。每个 issue 仍按 `Red-Green → Verify → Review → Finalize` 独立完成；本文件只负责依赖顺序与 issue 边界推进。
 
 ## 1. 构建依赖图
 
@@ -17,27 +17,38 @@
 ```text
 for each layer:
   for each issue:
+    issue_base = HEAD
     Red-Green
     Verify
-    Finalize  # 包含当前 issue 独立 commit
-    更新 issue 与 progress
+    Review
+    Finalize
+    issue_head = HEAD
 ```
 
-一个 issue Finalize 完成后立即进入下一个可调度 issue。前置 issue 未完成时，其依赖项保持 `blocked`。
+`Review` 包含当前 issue committed Review Point 的形成以及完整/增量 Review；具体以 `SKILL.md` 与 `review.md` 为准。
 
-每个 issue 的 Red-Green 与 Review 编排以 `SKILL.md` 为准；验证与 Finalize 分别以 `verify.md`、`finalize.md` 为准，本文件不重复定义。
+一个 issue Finalize 完成后立即进入下一个可调度 issue。下一个 issue 以当前 `issue_head` 作为新的 `issue_base`。前置 issue 未完成时，其依赖项保持 `blocked`。
+
+验证与 Finalize 分别以 `verify.md`、`finalize.md` 为准，本文件不重复定义其内部规则。
 
 ## 3. 状态收敛
 
-每个 issue 完成后同步：
+每个 issue Finalize 后只携带后续调度所需的最小状态：
 
 - `Status`；
-- Review 状态；
-- 验证结果；
-- 已解除的 blockers；
-- 当前 issue 的独立 commit。
+- `issue_base`；
+- `review_head`；
+- `issue_head`；
+- Review 与验证结果；
+- 已解除的 blockers。
+
+其中：
+
+- `issue_base...review_head` 是已完成 Review 的实现范围；
+- `issue_base...issue_head` 是当前 issue 的完整提交范围；
+- `issue_head` 是下一个 issue 的 `issue_base`。
 
-当前 issue 的完整 Review 通过并完成独立 commit 后，才进入下一个 issue。当前层所有 issue 完成后进入下一层。全部层完成后，确认 issue 与 progress 状态一致即可结束；不额外扩大验证范围，也不再次执行完整 Review。
+当前层所有 issue 完成后进入下一层。全部层完成后，确认 issue 与 progress 状态一致即可结束；不额外扩大验证范围，也不再次执行完整 Review。
 
 ## 冲突与失败
 
@@ -50,5 +61,5 @@ for each layer:
 
 - 所有可执行 issue 均按依赖顺序完成；
 - issue、依赖状态与 progress 一致；
-- 每个完成的 issue 均有独立 commit；
+- 每个完成 issue 的 `issue_base`、`review_head` 与 `issue_head` 边界明确；
 - 不存在被误当作已完成的 blocked issue。

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

@@ -0,0 +1,99 @@
+# Review
+
+仅在 Verify 通过后执行。本文件负责当前 issue 的 committed Review Point、Review 状态与增量复核；完整 Review 的维度、reviewer 数量、提示词和输出格式仍以 `code-review` 为唯一事实源。
+
+## 状态
+
+当前 issue 首次进入 Review 时初始化以下状态，且仅初始化一次；后续因 finding 修复返回 Red-Green / Verify 后继续 Review 时保留现有状态，不得重新初始化：
+
+- `issue_base`：当前 issue 开始时的 `HEAD`；
+- `full_review_done = false`；
+- `open_findings = []`；
+- `last_reviewed_head = null`；
+- `review_head = null`；
+- `incremental_review_rounds = 0`。
+
+## 1. 形成 committed Review Point
+
+完整 Review 前：
+
+1. 确认当前 issue 交付所需的代码、测试、文档和配置均已完成；
+2. 若最后的文档/配置修改影响已验证证据，重新验证受影响范围；
+3. 将当前 issue 已完成并验证的交付修改提交到当前 branch；
+4. 确认不存在属于当前 issue 交付内容的未提交修改。
+
+一个 issue 可以在这里已有一个或多个 commits。Commit 是 Review artifact，不代表 issue 已完成。
+
+完整 Review 使用：
+
+- fixed point：`issue_base`；
+- review target：当前 `HEAD`；
+- diff：`issue_base...HEAD`；
+- spec source：当前 issue/spec。
+
+不得用未提交 working tree 代替该 committed diff。
+
+## 2. 完整 Review
+
+当 `full_review_done = false` 时，只启动一次逻辑上的完整 `code-review`。
+
+只有 `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”。
+
+每个 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 通过时：
+
+- 仅关闭本轮已由证据确认解决的 findings；
+- 设置 `last_reviewed_head = HEAD`。
+
+增量 Review 正常完成但未通过时：
+
+- 保留未关闭 findings；
+- 不推进 `last_reviewed_head`；
+- 若尚未达到 2 轮上限，下一轮继续从上一次成功的 `last_reviewed_head` 审查累计的未 Review 修复。
+
+增量 Review 发生技术失败时：
+
+- 不增加 `incremental_review_rounds`；
+- 不推进 `last_reviewed_head`；
+- 不移除未确认关闭的 findings；
+- 恢复后重试当前逻辑轮次。
+
+当 `open_findings` 为空时，设置 `review_head = last_reviewed_head`，Review 通过。
+
+当 `incremental_review_rounds = 2` 且 `open_findings` 仍非空时，Review 不通过：保持 issue 未完成，不设置 `review_head`，不进入 Finalize，并报告剩余 findings 请求决策。
+
+## 出口
+
+- `full_review_done = true`；
+- `open_findings` 为空；
+- `review_head` 非空；
+- `incremental_review_rounds <= 2`；
+- `issue_base...review_head` 是已经完成 Review 的当前 issue 实现范围；
+- 不存在属于该实现范围的未提交交付修改。

package/package.json

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