@heihei0299/matt-skills 3.0.15 → 3.0.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/.agents/skills/tdd-implement/SKILL.md +7 -5
  2. package/.agents/skills/tdd-implement/references/finalize.md +13 -9
  3. package/.agents/skills/tdd-implement/references/orchestration.md +6 -5
  4. package/.agents/skills/tdd-implement/references/review.md +16 -17
  5. package/package.json +1 -1
package/.agents/skills/tdd-implement/SKILL.md CHANGED
@@ -14,7 +14,7 @@ disable-model-invocation: true
14
14
  - **多 issue**：存在多个 `Type: task` 时，读取 [orchestration.md](references/orchestration.md) 后按依赖顺序逐个完成。
15
15
  - `research`、`prototype`、`grilling` 类型任务分流到对应技能。
16
16
 
17
- 每个 issue 开始时记录 `issue_base = HEAD`。一个 issue 可以包含一个或多个 commits；不要求固定 commit 数量，也不为满足数量约束强制 amend、squash 或重写历史。
17
+ 每个 issue 开始时记录 `issue_base = HEAD`。Commit 是交付 artifact，不是流程日志：Red-Green / Verify 期间不因 Behavior、阶段切换或验证动作创建 commit。Verify 通过后形成 1 个 Review Point commit；仅当 Full Review 产生 blocking findings 时，最多再形成 1 个 finding-fix commit。
18
18
 
19
19
  生命周期：
20
20
 
@@ -50,7 +50,7 @@ disable-model-invocation: true
50
50
 
51
51
  Verify 通过后读取 [review.md](references/review.md)。
52
52
 
53
- 先将当前 issue 交付所需的代码、测试、文档和配置形成 committed Review Point，再按 `review.md` 完成一次完整 Review 与必要的增量 Review。
53
+ 先将当前 issue 交付所需的代码、测试、文档和配置形成唯一的 committed Review Point commit，再按 `review.md` 完成一次完整 Review 与必要的增量 Review。
54
54
 
55
55
  完整 Review 的审查维度、reviewer 数量、提示词和输出格式仍以 [code-review](.agents/skills/code-review/SKILL.md) 为唯一事实源。
56
56
 
@@ -65,15 +65,17 @@ Verify 通过后读取 [review.md](references/review.md)。
65
65
 
66
66
  Review 通过后读取 [finalize.md](references/finalize.md)，只做 tracker/progress/status 收尾并记录 `issue_head`。
67
67
 
68
- Finalize 不新增产品 Behavior，也不修改已经 Review 的实现内容。若收尾时发现实现、测试、文档/配置或验证遗漏，停止当前 issue，不标记 `resolved`，并按 `finalize.md` 报告遗漏请求决策；不得在 Finalize 中补改或重新进入 Red-Green、Verify 或 Review。
68
+ Finalize 不新增产品 Behavior，也不修改已经 Review 的实现内容，不为单个 issue 创建收尾 commit。若收尾时发现实现、测试、文档/配置或验证遗漏，停止当前 issue，不标记 `resolved`，并按 `finalize.md` 报告遗漏请求决策；不得在 Finalize 中补改或重新进入 Red-Green、Verify 或 Review。
69
+
70
+ 本次执行批次结束后，如仓库内 tracker/progress/status 存在待同步状态，统一写入并最多形成 1 个 batch state-sync commit；该 commit 不属于任何单个 issue 的实现/Review commit range。
69
71
 
70
72
  ## 运行纪律
71
73
 
72
74
  - Red-Green 必须覆盖当前 issue 的全部待实现 Behavior，不能只对第一个改动执行 TDD。
73
75
  - 一个 Behavior 完成后继续下一个 Behavior，直到 Step ① 出口满足。
74
76
  - Verify 只做当前 issue 必要的最终验证；已通过的等价验证不机械重复。
75
- - 完整 Review 前必须形成 committed Review Point；不得用未提交 working tree 代替 `code-review` 所需的 committed diff。
76
- - 每个 issue 只有一次逻辑上的完整双轴 Review；完整 Review 之后只处理增量 Review。技术失败或中断的恢复规则以 `review.md` 为准。
77
+ - Red-Green / Verify 期间不按 Behavior、阶段或验证动作拆 commit；完整 Review 前只形成 1 个 committed Review Point。
78
+ - 每个 issue 只有一次逻辑上的完整双轴 Review；若有 blocking findings，只允许 1 个 finding-fix commit 与最多 1 次逻辑增量 Review。技术失败或中断的恢复规则以 `review.md` 为准。
77
79
  - 当前 issue Review 与 Finalize 完成后，才能进入下一个 issue；下一个 issue 以当时的 `HEAD` 作为新的 `issue_base`。
78
80
  - 当前 Step 达到出口后继续进入下一 Step；仅在需要用户决策或存在外部阻塞时暂停。
79
81
 
package/.agents/skills/tdd-implement/references/finalize.md CHANGED
@@ -1,24 +1,28 @@
1
1
  # Finalize
2
2
 
3
- 仅在 Verify 与 Review 通过后执行。Finalize 只负责 tracker/progress/status 收尾，不新增产品 Behavior，也不修改已经 Review 的代码、测试、交付文档或配置。
3
+ 仅在 Verify 与 Review 通过后执行。Finalize 只负责 tracker/progress/status 收尾，不新增产品 Behavior，不修改已经 Review 的代码、测试、交付文档或配置，也不为单个 issue 创建收尾 commit。
4
4
 
5
5
  ## 步骤
6
6
 
7
7
  1. 确认 `review_head` 已记录，且 `issue_base...review_head` 对应的实现范围已经完成 Review。
8
- 2. 更新 Acceptance Criteria 与 progress/tracker，记录已 Review 的实现范围、Review、验证与运行结果；此时不得提前标记 `resolved` 或解除 blockers。
8
+ 2. 准备 Acceptance Criteria 与 progress/tracker 的最终状态，记录已 Review 的实现范围、Review、验证与运行结果。外部 tracker 可在此同步；仓库内 tracker/progress/status 只记录为批次待同步状态，不在当前 issue Finalize 中写入或提交。
9
9
  3. 若 Finalize 过程中发现任何实现、测试、交付文档、配置或验证遗漏，立即停止当前 issue：保持未完成，不标记 `resolved`，不解除 blockers，不设置成功的 `issue_head`，并报告遗漏请求决策。不得在 Finalize 中补改，也不得自动重新进入 Red-Green、Verify 或 Review。
10
- 4. 仅在未发现上述遗漏且所有必要状态同步准备完成后，才同步 `resolved` / blockers 状态。
11
- 5. 若状态同步修改了仓库内的 tracker/progress/status 文件，将这些状态修改提交；不得在该提交中混入产品实现或其它未 Review 的交付修改。
12
- 6. 确认所有必要状态同步成功后，设置 `issue_head = HEAD`。
10
+ 4. 仅在未发现上述遗漏后，将当前 issue 的完成状态视为 `resolved` 并解除已满足的 blockers；仓库内对应状态仍留待批次 state-sync。
11
+ 5. Finalize 不创建 commit；设置 `issue_head = review_head`。此时当前 `HEAD` 应与 `review_head` 一致。
13
12
 
14
- 无需为了固定 commit 数量而 amend、squash 或重写当前 issue 的历史。
13
+ ## 批次状态同步
14
+
15
+ 本次执行批次结束后，如仓库内 tracker/progress/status 存在待同步状态，统一写入全部待同步内容并最多创建 1 个 batch state-sync commit。该 commit：
16
+
17
+ - 不混入产品实现、测试、交付文档或配置修改；
18
+ - 不属于任何单个 issue 的 `issue_base...issue_head` 范围；
19
+ - 不因 issue 数量增加而拆成多个 status commits。
15
20
 
16
21
  ## 出口
17
22
 
18
23
  - Acceptance Criteria 全部通过；
19
24
  - `issue_base...review_head` 的实现范围已经完成 Review；
20
25
  - Finalize 未发现实现、测试、交付文档、配置或验证遗漏；
21
- - tracker/progress/status 与实际 Review、验证和完成状态一致；
22
- - `review_head` 之后若存在 commits，只包含当前 issue 的状态收尾修改；
23
- - `issue_head = HEAD` 已记录；
26
+ - tracker/progress/status 已同步，或已进入本批次唯一的待同步集合；
27
+ - `issue_head = review_head`；
24
28
  - issue 已 `resolved`，已满足的 blockers 已解除。
package/.agents/skills/tdd-implement/references/orchestration.md CHANGED
@@ -22,12 +22,12 @@ for each layer:
22
22
  Verify
23
23
  Review
24
24
  Finalize
25
- issue_head = HEAD
25
+ issue_head = review_head
26
26
  ```
27
27
 
28
28
  `Review` 包含当前 issue committed Review Point 的形成以及完整/增量 Review；具体以 `SKILL.md` 与 `review.md` 为准。
29
29
 
30
- 一个 issue Finalize 完成后立即进入下一个可调度 issue。下一个 issue 以当前 `issue_head` 作为新的 `issue_base`。前置 issue 未完成时，其依赖项保持 `blocked`。
30
+ 一个 issue Finalize 完成后立即进入下一个可调度 issue。Finalize 不为单个 issue 创建 commit，因此 `issue_head = review_head`；下一个 issue 以当前 `issue_head` 作为新的 `issue_base`。前置 issue 未完成时，其依赖项保持 `blocked`。
31
31
 
32
32
  验证与 Finalize 分别以 `verify.md`、`finalize.md` 为准，本文件不重复定义其内部规则。
33
33
 
@@ -45,10 +45,10 @@ for each layer:
45
45
  其中：
46
46
 
47
47
  - `issue_base...review_head` 是已完成 Review 的实现范围；
48
- - `issue_base...issue_head` 是当前 issue 的完整提交范围；
48
+ - `issue_head = review_head`，因此 `issue_base...issue_head` 只包含当前 issue 的 Review Point commit，以及可选的唯一 finding-fix commit；
49
49
  - `issue_head` 是下一个 issue 的 `issue_base`。
50
50
 
51
- 当前层所有 issue 完成后进入下一层。全部层完成后，确认 issue 与 progress 状态一致即可结束；不额外扩大验证范围，也不再次执行完整 Review。
51
+ 当前层所有 issue 完成后进入下一层。全部层完成后，如仓库内 tracker/progress/status 存在待同步状态，统一写入并最多创建 1 个 batch state-sync commit；该 commit 不属于任何单个 issue 的提交范围。随后确认 issue 与 progress 状态一致即可结束；不额外扩大验证范围，也不再次执行完整 Review。
52
52
 
53
53
  ## 冲突与失败
54
54
 
@@ -61,5 +61,6 @@ for each layer:
61
61
 
62
62
  - 所有可执行 issue 均按依赖顺序完成；
63
63
  - issue、依赖状态与 progress 一致；
64
- - 每个完成 issue 的 `issue_base`、`review_head` 与 `issue_head` 边界明确；
64
+ - 每个完成 issue 的 `issue_base`、`review_head` 与 `issue_head` 边界明确，且每个 issue 最多包含 2 个由本技能产生的实现/Review commits；
65
+ - 仓库内状态同步如有需要，只形成最多 1 个批次 state-sync commit；
65
66
  - 不存在被误当作已完成的 blocked issue。
package/.agents/skills/tdd-implement/references/review.md CHANGED
@@ -19,10 +19,10 @@
19
19
 
20
20
  1. 确认当前 issue 交付所需的代码、测试、文档和配置均已完成；
21
21
  2. 若最后的文档/配置修改影响已验证证据，重新验证受影响范围；
22
- 3. 将当前 issue 已完成并验证的交付修改提交到当前 branch；
22
+ 3. 将当前 issue 已完成并验证的交付修改合并形成当前 issue 唯一的 Review Point commit；不得按 Behavior、阶段或验证动作拆分 commit；
23
23
  4. 确认不存在属于当前 issue 交付内容的未提交修改。
24
24
 
25
- 一个 issue 可以在这里已有一个或多个 commits。Commit 是 Review artifact，不代表 issue 已完成。
25
+ 完整 Review 前每个 issue 只形成 1 个 Review Point commit。Commit 是交付 artifact，不是流程日志。
26
26
 
27
27
  完整 Review 使用：
28
28
 
@@ -51,32 +51,32 @@
51
51
 
52
52
  ## 3. 增量 Review
53
53
 
54
- 存在 `open_findings` 时，只处理已有 finding，不扩大当前 issue 范围。可将由同一改动共同解决的相关 findings 一起处理，不要求“一 finding 一 commit”。
54
+ 存在 `open_findings` 时，只处理已有 finding，不扩大当前 issue 范围。一次性处理当前全部 open findings，不按 finding 拆分 commit。
55
55
 
56
- 每个 issue 最多执行 2 个逻辑增量 Review 轮次。只有正常形成增量 Review 结论的轮次才计数；工具错误、stream interruption、sub-agent failure 或其它未形成完整结论的技术失败不消耗轮次，只重试当前逻辑轮次。
56
+ 每个 issue 最多执行 1 个逻辑增量 Review 轮次。只有正常形成增量 Review 结论的轮次才计数；工具错误、stream interruption、sub-agent failure 或其它未形成完整结论的技术失败不消耗轮次，只重试当前逻辑轮次。
57
57
 
58
- 每轮修复前，若 `incremental_review_rounds >= 2` 且 `open_findings` 仍非空，则停止当前 issue：不得再次启动增量 Review，不设置 `review_head`，不得进入 Finalize，并报告剩余 findings 请求决策。
58
+ 若 `incremental_review_rounds >= 1` 且 `open_findings` 仍非空，则停止当前 issue：不得再次启动增量 Review，不设置 `review_head`，不得进入 Finalize，并报告剩余 findings 请求决策。
59
59
 
60
- 每轮修复：
60
+ 唯一一轮 finding 修复：
61
61
 
62
- 1. 修复选定的 open findings；
62
+ 1. 一次性修复当前全部 open findings；
63
63
  2. 若修复产生新的 Behavior，返回 Red-Green 对该 Behavior 执行 TDD；否则直接进入受影响证据的重新验证；
64
- 3. 重新验证修复直接影响的证据；
65
- 4. 将本轮修复提交到当前 issue 的 commit range，并确认不存在属于本轮修复的未提交修改；
66
- 5. 只针对 `last_reviewed_head...HEAD` 与本轮目标 findings 做增量 Review；增量 Review 不调用完整 `code-review`。
64
+ 3. 重新验证全部修复直接影响的证据；
65
+ 4. 将本轮全部修复合并形成最多 1 个 finding-fix commit，并确认不存在属于本轮修复的未提交修改；不得按 finding 拆分 commit；
66
+ 5. 只针对 `last_reviewed_head...HEAD` 与现有 findings 做增量 Review；增量 Review 不调用完整 `code-review`。
67
67
 
68
68
  若增量 Review 正常形成结论，先设置 `incremental_review_rounds += 1`。
69
69
 
70
70
  增量 Review 通过时：
71
71
 
72
- - 仅关闭本轮已由证据确认解决的 findings；
72
+ - 仅关闭已由证据确认解决的 findings；
73
73
  - 设置 `last_reviewed_head = HEAD`。
74
74
 
75
- 增量 Review 正常完成但未通过时：
75
+ 增量 Review 正常完成但仍有 open findings 时：
76
76
 
77
77
  - 保留未关闭 findings；
78
78
  - 不推进 `last_reviewed_head`；
79
- - 若尚未达到 2 轮上限，下一轮继续从上一次成功的 `last_reviewed_head` 审查累计的未 Review 修复。
79
+ - 停止当前 issue，不设置 `review_head`，不进入 Finalize，并报告剩余 findings 请求决策。
80
80
 
81
81
  增量 Review 发生技术失败时：
82
82
 
@@ -87,13 +87,12 @@
87
87
 
88
88
  当 `open_findings` 为空时，设置 `review_head = last_reviewed_head`，Review 通过。
89
89
 
90
- 当 `incremental_review_rounds = 2` 且 `open_findings` 仍非空时，Review 不通过：保持 issue 未完成，不设置 `review_head`，不进入 Finalize，并报告剩余 findings 请求决策。
91
-
92
90
  ## 出口
93
91
 
94
92
  - `full_review_done = true`；
95
93
  - `open_findings` 为空；
96
94
  - `review_head` 非空；
97
- - `incremental_review_rounds <= 2`；
98
- - `issue_base...review_head` 是已经完成 Review 的当前 issue 实现范围；
95
+ - `incremental_review_rounds <= 1`；
96
+ - `review_head` 指向 Review Point commit，或唯一的 finding-fix commit；
97
+ - `issue_base...review_head` 是已经完成 Review 的当前 issue 实现范围，最多包含 2 个由本技能产生的 issue commits；
99
98
  - 不存在属于该实现范围的未提交交付修改。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@heihei0299/matt-skills",
3
- "version": "3.0.15",
3
+ "version": "3.0.16",
4
4
  "description": "Agent skills + 项目配置模板：一条命令初始化 opencode / pi-agent 项目（含 mattpocock/skills 上游技能）",
5
5
  "type": "module",
6
6
  "bin": {