@heihei0299/matt-skills 2.1.8 → 2.1.13

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 (16) hide show
  1. package/.agents/skills/tdd-implement/SKILL.md +56 -31
  2. package/.agents/skills/tdd-implement/references/finalize.md +8 -19
  3. package/.agents/skills/tdd-implement/references/orchestration.md +35 -152
  4. package/.agents/skills/tdd-implement/references/verify.md +7 -16
  5. package/package.json +1 -1
  6. package/template/.agents/skills/tdd-implement/SKILL.md +56 -31
  7. package/template/.agents/skills/tdd-implement/references/finalize.md +8 -19
  8. package/template/.agents/skills/tdd-implement/references/orchestration.md +35 -152
  9. package/template/.agents/skills/tdd-implement/references/verify.md +7 -16
  10. package/template/AGENTS.md +0 -2
  11. package/.agents/skills/tdd-implement/references/contract.md +0 -21
  12. package/.agents/skills/tdd-implement/references/red-green.md +0 -25
  13. package/.agents/skills/tdd-implement/references/stages.md +0 -254
  14. package/template/.agents/skills/tdd-implement/references/contract.md +0 -21
  15. package/template/.agents/skills/tdd-implement/references/red-green.md +0 -25
  16. package/template/.agents/skills/tdd-implement/references/stages.md +0 -254
package/.agents/skills/tdd-implement/SKILL.md CHANGED
@@ -6,51 +6,76 @@ disable-model-invocation: true
6
6
 
7
7
  # TDD Implement
8
8
 
9
- `seam` + `red-green` 是本技能的领衔词。它把一个 spec 或 task issue 编排成三个交付阶段，并在 Verify 后执行一次非阶段的 Finalize 收尾；TDD 的红-绿语义、测试质量和 mock 边界以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，本技能只定义交付编排。
9
+ 完成已确认的 spec/task。TDD 的红绿语义、测试质量、seam 和 mock 规则以 [tdd](.agents/skills/tdd/SKILL.md) 为唯一事实源；本技能只负责 issue 级实现、验证、Review 与收尾编排。
10
10
 
11
- 本技能是 **Long-Horizon Skill**：阶段按顺序连续执行，并自带 **Turn Continuity** 与 **Chunking**。术语见 `CONTEXT.md`，技能设计规则见 `docs/agents/skill-design.md`。
11
+ ## 入口
12
12
 
13
- ## 入口与分支
13
+ - **单 issue**：直接按下方 Steps 执行。
14
+ - **多 issue**：存在多个 `Type: task` 时，读取 [orchestration.md](references/orchestration.md) 后按依赖顺序逐个完成。
15
+ - `research`、`prototype`、`grilling` 类型任务分流到对应技能。
14
16
 
15
- - **单 issue**：单个 `.scratch/<feature>/spec.md`、等价 spec 或 `Type: task` issue，按下方三个 Steps 完成验证，再执行 Finalize 收尾。
16
- - **多 issue**：`.scratch/<feature>/issues/` 下存在多个 `Type: task` 文件时，先读取 [orchestration.md](references/orchestration.md)，按 `Blocked by` 构建 DAG、Kahn 分层，再由主代理按层串行完成各 issue。
17
- - `Type: research`、`prototype`、`grilling` 分流到对应技能，不进入本技能。
17
+ ## Steps
18
18
 
19
- 多 issue 的 A0-A5 是编排控制活动，不是额外的产品交付阶段：依赖图、分层、串行调度、层收敛、最终收敛和回退/冲突处理的详规只在 [orchestration.md](references/orchestration.md) 中维护。
19
+ ### ① Red-Green
20
20
 
21
- ## 三阶段 Steps
21
+ 按 `tdd` 完成当前 issue 的所有 Acceptance Criteria。
22
22
 
23
- 按序执行；每步达到可验证出口条件后立即进入下一步。每步只读取自己的轻量 reference，避免在每个阶段重复注入完整 `stages.md`。
23
+ 将需要实现或修改的内容拆成可独立验证的 Behavior。一次只推进一个 Behavior：每个尚未实现的 Behavior 都必须分别完成 `tdd` 的 Red → Green cycle，完成后才能进入下一个 Behavior。
24
24
 
25
- | Step | Reference | 做什么 | 出口条件 |
26
- |---|---|---|---|
27
- | ① **Contract** | [contract.md](references/contract.md) | 读取入口，提取 Acceptance Criteria，建立 Scope Ledger、Preflight、验证矩阵和 Behavior/Seam 边界 | 需求无待决歧义，验证命令已确定；知道做什么、从哪里验证、什么不做 |
28
- | ② **Red-Green** | [red-green.md](references/red-green.md) | 以 Behavior 为粒度执行有效 Red → 最小 Green → formatter/typecheck → 最小相关测试 | 所有 Behaviors 均有有效 Red、实现全绿，formatter/typecheck 和最小相关测试通过 |
29
- | ③ **Verify** | [verify.md](references/verify.md) | 运行当前 issue 影响范围测试、必要 build、要求的真实运行验证；在最终 diff 稳定后调用一次 [code-review](.agents/skills/code-review/SKILL.md) | 最终 diff 的相关证据通过，真实运行验证完成（如要求），code-review 已完成且无 blocking finding |
25
+ 前一个 Behavior 已完成 TDD，不代表后续 Behavior 可以直接修改实现代码。
30
26
 
31
- ## Finalize（非阶段）
27
+ 已有行为若无需修改且已由现有测试充分覆盖，不强制制造 Red。
32
28
 
33
- Verify 出口满足后读取 [finalize.md](references/finalize.md) 并立即收尾。Finalize 不计入交付阶段，只负责必要的 docs/README 对齐、直接创建当前 issue 的独立 commit 与 Tracker/progress 更新；不执行额外安全扫描、staged diff 复核或 commit message 门禁。若发现实现、测试或文档证据不完整，回到对应阶段修复后再 Finalize。
29
+ **出口：**
34
30
 
35
- Finalize 出口：commit 已创建、Acceptance Criteria 全部通过，Tracker 与工作区反映真实完成状态。
31
+ - 所有需要实现或修改的 Behavior 均完成各自的 Red → Green cycle；
32
+ - Acceptance Criteria 对应行为通过相关验证。
36
33
 
37
- ## 运行时纪律
34
+ ### ② Verify
38
35
 
39
- - 三个阶段都从入口连续执行到自身出口；Verify 出口满足后立即进入 Finalize：预告下一步后立即执行；进度输出并入工具调用序列，输出后继续执行。只有合规交互点、明确的外部阻塞或阶段出口条件结束当前回合。
40
- - 一个 seam 是公共可观察边界；一个 Behavior 是一个红-绿 cycle；一个 seam 可以包含多个 Behaviors。Seam/Behavior 的细节和 Todo 粒度只在进入 Step ② 时读取 [red-green.md](references/red-green.md)。
41
- - 每个 issue 只在 Verify 的最终 diff 稳定后调用一次 `code-review`；审查维度、reviewer 数量、提示词和输出格式全部由 `code-review` 自己定义，`tdd-implement` 不复制这些规则。`code-review` 未完成或存在 blocking finding 时 issue 不得收敛；A3 层收敛不再次调用 review。
42
- - 当前 issue 的范围、Acceptance Criteria、Out of Scope、测试/typecheck/build/真实运行证据和最终 commit 必须可追溯。Seam 或专项测试绿色不代表 issue 完成；三个阶段出口与 Finalize 全部满足后才可标记 `resolved`。
43
- - 多 issue 模式中，每个 issue 只提交一个独立 commit；issue 影响范围测试在 Step ③ 执行，A4 只做最终编排收敛，不额外扩大测试范围。
36
+ 读取 [verify.md](references/verify.md)，执行当前 issue 所需的最终验证。
44
37
 
45
- ## 引用
38
+ 最终验证通过且 diff 稳定后执行完整 `code-review`。
46
39
 
47
- - TDD 核心规则：[tdd 技能](.agents/skills/tdd/SKILL.md)
48
- - 测试标准：[tdd/tests.md](.agents/skills/tdd/tests.md)
49
- - Mock 指南：[tdd/mocking.md](.agents/skills/tdd/mocking.md)
50
- - Contract：[contract.md](references/contract.md)
51
- - Red-Green：[red-green.md](references/red-green.md)
40
+ #### Review
41
+
42
+ 每个 issue 只在 Verify 的最终 diff 稳定后调用一次完整 `code-review`；审查维度、reviewer 数量、提示词和输出格式全部由 `code-review` 自己定义，`tdd-implement` 不复制这些规则。`code-review` 未完成或存在 blocking finding 时 issue 不得收敛；多 issue 层收敛不再次调用完整 Review。
43
+
44
+ 若完整 Review 存在 blocking finding：
45
+
46
+ 1. 仅修复对应 finding，不扩大当前 issue 范围；
47
+ 2. 修复后仅对该 finding 及其直接影响执行增量 Review；
48
+ 3. 未受影响的 Review 结论继续有效；
49
+ 4. 不重新执行完整双轴 Review；
50
+ 5. 若增量 Review 仍存在问题，仅继续修复并复核剩余 finding。
51
+
52
+ 所有 blocking finding 关闭后 Review 才算通过。
53
+
54
+ **出口：**
55
+
56
+ - 当前 issue 所需最终验证通过；
57
+ - 要求的真实运行验证完成；
58
+ - 完整 Review 已完成；
59
+ - 所有 blocking finding 已关闭。
60
+
61
+ ## Finalize
62
+
63
+ Verify 通过后读取 [finalize.md](references/finalize.md)，完成当前 issue 的必要同步、独立 commit 与 tracker/progress 收尾。
64
+
65
+ Finalize 不新增产品 Behavior；若发现实现或验证遗漏，回到对应 Step 完成后再收尾。
66
+
67
+ ## 运行纪律
68
+
69
+ - Red-Green 必须覆盖当前 issue 的全部待实现 Behavior，不能只对第一个改动执行 TDD。
70
+ - 一个 Behavior 完成后继续下一个 Behavior，直到 Step ① 出口满足。
71
+ - Verify 只做当前 issue 必要的最终验证；已通过的等价验证不机械重复。
72
+ - 完整双轴 Review 每个 issue 只执行一次；后续修复只执行受影响 finding 的增量 Review。
73
+ - 当前 Step 达到出口后继续进入下一 Step；仅在需要用户决策或存在外部阻塞时暂停。
74
+
75
+ ## References
76
+
77
+ - TDD：[tdd](.agents/skills/tdd/SKILL.md)
52
78
  - Verify：[verify.md](references/verify.md)
53
- - Review 方法：[code-review](.agents/skills/code-review/SKILL.md)
54
79
  - Finalize：[finalize.md](references/finalize.md)
55
- - 完整兼容规范：[stages.md](references/stages.md)
80
+ - Review：[code-review](.agents/skills/code-review/SKILL.md)
56
81
  - 多 issue 编排：[orchestration.md](references/orchestration.md)
package/.agents/skills/tdd-implement/references/finalize.md CHANGED
@@ -1,27 +1,16 @@
1
- # Finalize（非阶段）
1
+ # Finalize
2
2
 
3
- 仅在 `tdd-implement` Step ③ Verify 通过后读取。Finalize 不计入交付阶段；开始后不新增产品 Behavior，发现实现、测试或文档遗漏时回到对应阶段。
3
+ 仅在 Verify 通过后执行；不新增产品 Behavior。
4
4
 
5
- ## Commit
5
+ 1. 完成实现要求的必要 docs/config 同步。
6
+ 2. 为当前 issue 创建一个独立 commit。
7
+ 3. 更新 progress/tracker，记录 commit、Review、验证与运行结果，并解除已满足的 blockers。
8
+ 4. 将 Acceptance Criteria 标记完成，issue 标记 `resolved`。
6
9
 
7
- 1. 如本次实现要求 README/docs/config/package 同步，完成必要更新。
8
- 2. 按当前 issue 范围直接创建一个独立 commit。
9
- 3. 不执行额外敏感信息/安全扫描，不做 `git diff --cached` 复核，也不设置额外 commit message 门禁。
10
-
11
- 仓库级 Git 安全与历史保护规则仍然适用；Finalize 不重复定义或扩展这些规则。
12
-
13
- ## Tracker 收尾
14
-
15
- Commit 成功后：
16
-
17
- - 勾选 Acceptance Criteria；
18
- - issue 标记 `resolved`；
19
- - 写实施总结并同步 `.scratch/<feature>/progress.md` 的 Status/Commit/Review/Tests；
20
- - 记录 commit hash/message、最终测试和真实运行结果；
21
- - 确认后续 blockers 是否解除。
10
+ 若发现实现或验证遗漏，返回对应 Step 完成后再收尾。
22
11
 
23
12
  ## 出口
24
13
 
25
14
  - 当前 issue 的独立 commit 已创建；
26
15
  - Acceptance Criteria 全部通过；
27
- - Tracker/progress 与真实完成度一致。
16
+ - tracker/progress 与实际完成状态一致。
package/.agents/skills/tdd-implement/references/orchestration.md CHANGED
@@ -1,171 +1,54 @@
1
- # 多 issue 编排（按依赖分层串行）
1
+ # 多 issue 编排
2
2
 
3
- 本文件仅在 `.scratch/<feature>/issues/` 下存在多个 `Type: task` issue 时生效。单 `spec` / 单 `task` 直接按 [stages.md](stages.md) 的三个交付阶段执行，并在 Verify 后 Finalize。A0-A5 是编排控制活动，不是额外的产品交付阶段。
3
+ 仅在存在多个 `Type: task` issue 时生效。每个 issue 仍按 `Red-Green → Verify → Finalize` 独立完成；本文件只负责依赖顺序与状态推进。
4
4
 
5
- 主代理按依赖分层、层内按编号串行执行；每个 issue 由同一个主代理完成 Contract → Red-Green → Verify，再执行非阶段 Finalize 并创建一个独立 commit。实现细节以 [stages.md](stages.md) 为准，TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为准。
5
+ ## 1. 构建依赖图
6
6
 
7
- ## 目录
7
+ 读取每个 issue 的 `Blocked by`：
8
8
 
9
- - [A0：依赖图与编排 Preflight](#a0依赖图与编排-preflight)
10
- - [A1：Kahn 拓扑分层](#a1kahn-拓扑分层)
11
- - [A2：分层串行调度](#a2分层串行调度)
12
- - [A3：层收敛](#a3层收敛)
13
- - [A4：最终收敛](#a4最终收敛)
14
- - [A5：回退与冲突处理](#a5回退与冲突处理)
9
+ - 无依赖时视为可直接调度；
10
+ - 引用了其它 issue 时建立依赖边；
11
+ - 字段无法解析、依赖节点不存在或出现环时，对受影响 issue 停止调度并报告实际原因，不降级为无依赖。
15
12
 
16
- ---
13
+ 使用 Kahn 算法按依赖关系分层；层间串行，每层内按 issue 编号串行。
17
14
 
18
- ## A0：依赖图与编排 Preflight
19
-
20
- 1. 扫描 `.scratch/<feature>/issues/` 下全部 `NN-<slug>.md`，逐文件解析 `Blocked by`：
21
- - `Blocked by: None`、`Blocked by: （无）` 或无此行：无依赖；
22
- - `Blocked by: 01, 02` 或 `Blocked by: 01（…）`：依赖对应编号 issue；
23
- - `Blocked by` 行存在但无法解析：**fail closed**。将该 issue 标记为 `blocked`，记录原始字段和值，不把它加入可调度 DAG，也不得按“无依赖”继续。只有字段修正或用户明确确认依赖后才能继续编排。
24
- 2. 以 issue 编号为节点、`Blocked by` 为有向边构建 DAG；检测到环时列出环上节点并停止调度。依赖引用了不存在的 issue 时同样 fail closed：对应 issue 保持 `blocked`，报告缺失节点，不静默忽略该依赖。
25
- 3. 读取共享 `spec.md`（若存在）、`CONTEXT.md` 和与本次改动有关的 ADR。
26
- 4. 完成编排级 Preflight：记录当前 `HEAD`、工作区状态、`BASE_HEAD=$(git rev-parse HEAD)`、测试/typecheck/build 命令、真实运行路径和敏感信息扫描脚本可用性。后续只使用已经确认的命令和路径。
27
- 5. 强制初始化 `.scratch/<feature>/progress.md`：
28
-
29
- ```markdown
30
- ## DAG
31
- ## Layers (Kahn L1..Ln)
32
- ## Progress
33
- | NN | Status | Commit | Review | Tests |
34
- |---|---|---|---|---|
35
- ```
36
-
37
- `progress.md` 是派生视图，真相源仍是 `spec.md` 与 `issues/*.md`。
38
-
39
- ### A0 出口
40
-
41
- - 所有 `Blocked by` 字段均可解析且依赖节点存在；否则相关 issue 保持 `blocked`，A1 不开始；
42
- - DAG 已构建且无环；
43
- - 编排 Preflight 和 `BASE_HEAD` 已记录；
44
- - `progress.md` 已存在并可回写；
45
- - 依赖解析或缺失节点问题已明确报告，而不是降级成无依赖。
46
-
47
- ## A1：Kahn 拓扑分层
48
-
49
- 对 DAG 做 Kahn 分层：
15
+ ## 2. 串行执行
50
16
 
51
17
  ```text
52
- L1 = 全部入度为 0 的节点
53
- L2 = 移除 L1 后入度为 0 的节点
54
- ...
55
- Ln = 最后一层
18
+ for each layer:
19
+ for each issue:
20
+ Red-Green
21
+ Verify
22
+ Finalize
23
+ 更新 issue 与 progress
56
24
  ```
57
25
 
58
- 每层内节点互无依赖，但仍由主代理按编号串行执行。层间必须串行。编排开始前一次性向用户展示 DAG 和 `L1..Ln`，得到确认后进入 A2；这是合规交互点，不把每个 seam 或每个 issue 的正常切换变成确认点。
59
-
60
- ### A1 出口
61
-
62
- - Kahn 分层结果已展示并确认；
63
- - 每个可调度 issue 都属于一个层；
64
- - 不存在因无法解析依赖而被误放入 L1 的 issue；
65
- - 同文件预期冲突已记录，必要时已通过依赖顺序隔离。
66
-
67
- ## A2：分层串行调度
68
-
69
- ```text
70
- for each layer Li in L1..Ln:
71
- for each issue in Li（按编号顺序）:
72
- 主代理执行三个阶段：
73
- ① Contract
74
- ② Red-Green
75
- ③ Verify（当前 issue 影响范围 + 当前 issue review）
76
- 执行 Finalize（非阶段：独立 commit + Tracker 收尾）
77
- 产出回执卡片并回写 issue
78
- 强制更新 progress.md 的 Status/Commit/Review/Tests
79
- 通过 A3 层收敛后进入下一层
80
- 全部层完成后进入 A4
81
- ```
82
-
83
- 每个 issue 的 Verify 只运行当前 issue 影响范围内的测试；编排层不额外扩大测试范围。当前 issue 的最终 diff 稳定后只调用一次 `code-review`；review 的内部方法完全由 `code-review` 定义。修复 blocking finding 后执行受影响验证和 finding delta recheck，不重复调用完整 `code-review`。
84
-
85
- 主代理在层内和层间连续调度：一个 issue 的 Finalize 出口满足后，立即取下一个 issue，直到全部层完成或发生明确外部阻塞。进度输出并入执行序列，不在正常切换点等待用户“继续”。
86
-
87
- 进入 A2 前记录的 `BASE_HEAD` 必须在每个 issue 的三个阶段出口和 Finalize commit 前校验：
88
-
89
- ```bash
90
- git merge-base --is-ancestor $BASE_HEAD HEAD
91
- ```
92
-
93
- 为达到工作区干净只删除本次产生的 `[DEBUG-...]` 和一次性临时产物；未经用户确认不使用 `git reset --hard`、`git checkout .`、`git clean -fd`、`git stash push --include-untracked` 或其他改写/丢弃历史的命令。
94
-
95
- ### Issue 回执卡片
96
-
97
- 每个 issue 完成后记录并回写：
98
-
99
- ```text
100
- Issue: NN
101
- Status: resolved
102
- Commit: <hash> — <message>
103
- Behaviors: <completed list>
104
- Acceptance Criteria: <checkbox result>
105
- Review: code-review completed once, no blocking finding
106
- Tests: <targeted command and actual result>
107
- Runtime: <actual request/page-visible result or not required>
108
- Docs: <updated files or no update required>
109
- ```
110
-
111
- ### A2 出口
112
-
113
- - 当前层每个 issue 均完成三个阶段与 Finalize 并有独立 commit；
114
- - issue、回执卡片和 `progress.md` 一致；
115
- - 相关测试通过，工作区卫生和历史校验通过；
116
- - 没有未记录的跨 issue 改动。
117
-
118
- ## A3：层收敛
119
-
120
- A3 只做编排收敛，不再次调用 `code-review`；正式 review 已在每个 issue 的 Verify 中完成。
121
-
122
- 每层全部 issue 串行完成后检查以下项目，全部通过才进入下一层：
123
-
124
- 1. 所有 issue `Status: resolved`，实施总结已落盘，`progress.md` 对应行已为 `done`；
125
- 2. 该层 issue 的相关测试通过；
126
- 3. `git status` 只显示预期改动或干净；
127
- 4. `git merge-base --is-ancestor $BASE_HEAD HEAD` 通过；
128
- 5. 不存在未分类的 scope 扩张、review blocking finding 或未清理临时产物。
129
-
130
- 任一项失败，定位到该层失败 issue，按 A5 回退并重做该 issue 的受影响阶段或 Behavior，然后重新收敛本层。
131
-
132
- ## A4：最终收敛
133
-
134
- 全部层完成且各层收敛通过后：
26
+ 一个 issue Finalize 完成后立即进入下一个可调度 issue。前置 issue 未完成时，其依赖项保持 `blocked`。
135
27
 
136
- 1. 汇总并确认各 issue 的相关测试、typecheck/build、真实运行和 review 证据仍对应最终状态；若后续改动使证据失效，只重新验证受影响范围；
137
- 2. 执行 `git merge-base --is-ancestor $BASE_HEAD HEAD`；失败时按 A5 恢复后重验；
138
- 3. 执行 `git status`，确认无 `[DEBUG-...]`、一次性脚本或未跟踪临时文件；
139
- 4. 汇总各 issue 回执卡片的 commit、Behaviors、Acceptance Criteria、测试、真实运行和文档对齐结果；汇总只在对话输出，不另写汇总文件。
28
+ 每个 issue 的 TDD、验证、Review 与 Finalize 规则分别以 `SKILL.md`、`red-green.md`、`verify.md`、`finalize.md` 为准，本文件不重复定义。
140
29
 
141
- ### A4 出口
30
+ ## 3. 状态收敛
142
31
 
143
- - 全部 issue 已有独立 commit、实施总结和 `progress.md` 派生记录；
144
- - 各 issue 的受影响验证证据仍对应最终状态；
145
- - 工作区卫生、历史校验和真实运行要求均满足；
146
- - `progress.md` 与 `issues/*.md` 一致，不一致时以 issue 真相源为准并修复派生视图。
32
+ 每个 issue 完成后同步：
147
33
 
148
- ## A5：回退与冲突处理
34
+ - `Status`；
35
+ - commit；
36
+ - Review 状态；
37
+ - 验证结果；
38
+ - 已解除的 blockers。
149
39
 
150
- A5 负责所有编排级失败，不把失败静默吞掉，也不把不相关问题塞入当前 issue：
40
+ 当前层所有 issue 完成后进入下一层。全部层完成后，确认 issue 与 progress 状态一致即可结束；不额外扩大验证范围，也不再次执行完整 Review。
151
41
 
152
- | 失败类别 | 处理 |
153
- |---|---|
154
- | `Blocked by` 存在但无法解析，或依赖节点不存在 | fail closed：该 issue 保持 `blocked`，保留原始依赖值并停止其调度；字段修正或用户明确确认依赖后才重新构建 DAG |
155
- | Contract 歧义、验收缺口、范围变化 | 回到该 issue 的 Contract，补 Scope Ledger、Behavior 和验证矩阵 |
156
- | Red-Green 的有效 Red、实现、typecheck 或 targeted test 失败 | 回到该 issue 的 Red-Green，修复当前 Behavior 并重新验证 |
157
- | Verify 的测试、build、真实运行或 review blocking finding 失败 | 回到受影响 issue 的对应阶段；修复后只做受影响检查和 delta review |
158
- | Finalize 的必要 docs、commit 或 Tracker 失败 | 保持 issue 未 resolved，修复 Finalize 问题后重新验证 |
159
- | A4 收敛发现验证证据失效 | 定位到受影响 issue，按上述路径修复；只重新验证受影响范围 |
160
- | `Blocked by` 依赖未完成 | 后续 issue 保持 `blocked`，前置 issue resolved 后自动解阻 |
161
- | 多 issue 预期修改同一文件 | 记录冲突，按编号串行；无法安全归属时暂停并请求用户决定 |
162
- | Git 历史祖先校验失败 | 立即停止写入，使用 `git reflog` 找回 `BASE_HEAD` 之后的提交，校验通过后继续 |
42
+ ## 冲突与失败
163
43
 
164
- 主代理不跨 issue 无记录改动；不通过第二次完整 `code-review` 来掩盖定向修复。外部权限、model、browser 或 tool 不可用时遵循 [stages.md](stages.md) 的 Tool Failure Budget，最多一次有依据的 fallback，仍失败则标记 `blocked/unavailable` 并报告实际状态。
44
+ - `Blocked by` 无法解析、依赖缺失或存在环：停止受影响调度并报告。
45
+ - issue 执行失败：保持未完成，按失败所在 Step 处理；其依赖项继续保持 `blocked`。
46
+ - 多个 issue 修改同一位置且无法安全串行归属：暂停相关 issue，请求用户决定。
47
+ - 外部权限、工具或环境阻塞：记录实际状态，不把失败静默当作完成。
165
48
 
166
- ### A5 出口
49
+ ## 出口
167
50
 
168
- - 失败原因已分类并记录；
169
- - 回退目标明确，受影响证据已重新验证；
170
- - 冲突已按依赖顺序解决或已明确请求用户决策；
171
- - DAG 顺序、issue 状态、commit 和 `progress.md` 保持一致。
51
+ - 所有可执行 issue 均按依赖顺序完成；
52
+ - 每个完成的 issue 均有独立 commit；
53
+ - issue、依赖状态与 progress 一致；
54
+ - 不存在被误当作已完成的 blocked issue。
package/.agents/skills/tdd-implement/references/verify.md CHANGED
@@ -1,24 +1,15 @@
1
1
  # Verify
2
2
 
3
- 仅在 `tdd-implement` Step ③ 读取。验证必须对应当前最终 diff；产品代码或测试再次变化时，测试/typecheck/build 等受影响证据失效。
4
-
5
- ## 固定顺序
6
-
7
- `影响范围测试 → 必要 build → 必要真实运行验证 → code-review 一次 → blocking 修复后的定向复核`
3
+ 验证必须对应当前最终 diff；实现或测试变化后，只重新验证受影响证据。
8
4
 
9
5
  ## 规则
10
6
 
11
- - 单 issue / 单 spec 与多 issue 均按 Contract 验证矩阵运行当前 issue 影响范围测试；不因进入 Verify 自动扩大测试范围。
12
- - ticket 要求真实运行时，优先专用 browser，其次项目已有 Playwright；HTTP/CLI 不能替代 WebUI 可见验证。
13
- - 临时进程必须使用隔离配置/端口，记录 PID 与实际结果，结束后清理。
14
- - 当前 issue 的最终 diff 稳定后，调用一次 [code-review](.agents/skills/code-review/SKILL.md)。`tdd-implement` 只规定调用时机；审查维度、reviewer 数量、提示词、上下文与输出格式以 `code-review` 为唯一事实源。
15
- - `code-review` 未完成或返回 blocking finding 时，issue 保持未完成；只修当前 issue 的 blocking finding，其余按 review 结果记录。
16
- - 修复 blocking finding 后，只重跑受影响测试/typecheck 并对该 finding 做 delta recheck；不再次调用完整 `code-review`。若修复引入新的 Behavior、改变 Scope 或使原 Review 对象不再成立，则回到 Contract/Red-Green，重新形成稳定最终 diff 后再进入 Verify。
7
+ - 只验证当前 issue 的必要范围，不因进入 Verify 自动扩大验证范围。
8
+ - ticket 要求真实运行验证时，执行与验收目标匹配的实际验证。
9
+ - 验证通过后不机械重复等价验证。
10
+ - 若修改产生新的 Behavior，返回 Red-Green 对该 Behavior 执行 TDD，完成后再验证受影响范围。
17
11
 
18
12
  ## 出口
19
13
 
20
- - 最终 diff 的相关测试/typecheck/build 通过；
21
- - 要求的真实运行验证有实际证据；
22
- - 当前稳定 diff 已完成一次 `code-review`；
23
- - 无 blocking finding；
24
- - post-review 修复（如有）的受影响验证与 finding delta recheck 已完成。
14
+ - 当前 issue 的必要验证通过；
15
+ - 要求的真实运行验证完成。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@heihei0299/matt-skills",
3
- "version": "2.1.8",
3
+ "version": "2.1.13",
4
4
  "description": "Agent skills + 项目配置模板：一条命令初始化 opencode / pi-agent 项目（含 mattpocock/skills 上游技能）",
5
5
  "type": "module",
6
6
  "bin": {
package/template/.agents/skills/tdd-implement/SKILL.md CHANGED
@@ -6,51 +6,76 @@ disable-model-invocation: true
6
6
 
7
7
  # TDD Implement
8
8
 
9
- `seam` + `red-green` 是本技能的领衔词。它把一个 spec 或 task issue 编排成三个交付阶段，并在 Verify 后执行一次非阶段的 Finalize 收尾；TDD 的红-绿语义、测试质量和 mock 边界以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，本技能只定义交付编排。
9
+ 完成已确认的 spec/task。TDD 的红绿语义、测试质量、seam 和 mock 规则以 [tdd](.agents/skills/tdd/SKILL.md) 为唯一事实源；本技能只负责 issue 级实现、验证、Review 与收尾编排。
10
10
 
11
- 本技能是 **Long-Horizon Skill**：阶段按顺序连续执行，并自带 **Turn Continuity** 与 **Chunking**。术语见 `CONTEXT.md`，技能设计规则见 `docs/agents/skill-design.md`。
11
+ ## 入口
12
12
 
13
- ## 入口与分支
13
+ - **单 issue**：直接按下方 Steps 执行。
14
+ - **多 issue**：存在多个 `Type: task` 时，读取 [orchestration.md](references/orchestration.md) 后按依赖顺序逐个完成。
15
+ - `research`、`prototype`、`grilling` 类型任务分流到对应技能。
14
16
 
15
- - **单 issue**：单个 `.scratch/<feature>/spec.md`、等价 spec 或 `Type: task` issue，按下方三个 Steps 完成验证，再执行 Finalize 收尾。
16
- - **多 issue**：`.scratch/<feature>/issues/` 下存在多个 `Type: task` 文件时，先读取 [orchestration.md](references/orchestration.md)，按 `Blocked by` 构建 DAG、Kahn 分层，再由主代理按层串行完成各 issue。
17
- - `Type: research`、`prototype`、`grilling` 分流到对应技能，不进入本技能。
17
+ ## Steps
18
18
 
19
- 多 issue 的 A0-A5 是编排控制活动，不是额外的产品交付阶段：依赖图、分层、串行调度、层收敛、最终收敛和回退/冲突处理的详规只在 [orchestration.md](references/orchestration.md) 中维护。
19
+ ### ① Red-Green
20
20
 
21
- ## 三阶段 Steps
21
+ 按 `tdd` 完成当前 issue 的所有 Acceptance Criteria。
22
22
 
23
- 按序执行；每步达到可验证出口条件后立即进入下一步。每步只读取自己的轻量 reference，避免在每个阶段重复注入完整 `stages.md`。
23
+ 将需要实现或修改的内容拆成可独立验证的 Behavior。一次只推进一个 Behavior：每个尚未实现的 Behavior 都必须分别完成 `tdd` 的 Red → Green cycle，完成后才能进入下一个 Behavior。
24
24
 
25
- | Step | Reference | 做什么 | 出口条件 |
26
- |---|---|---|---|
27
- | ① **Contract** | [contract.md](references/contract.md) | 读取入口，提取 Acceptance Criteria，建立 Scope Ledger、Preflight、验证矩阵和 Behavior/Seam 边界 | 需求无待决歧义，验证命令已确定；知道做什么、从哪里验证、什么不做 |
28
- | ② **Red-Green** | [red-green.md](references/red-green.md) | 以 Behavior 为粒度执行有效 Red → 最小 Green → formatter/typecheck → 最小相关测试 | 所有 Behaviors 均有有效 Red、实现全绿，formatter/typecheck 和最小相关测试通过 |
29
- | ③ **Verify** | [verify.md](references/verify.md) | 运行当前 issue 影响范围测试、必要 build、要求的真实运行验证；在最终 diff 稳定后调用一次 [code-review](.agents/skills/code-review/SKILL.md) | 最终 diff 的相关证据通过，真实运行验证完成（如要求），code-review 已完成且无 blocking finding |
25
+ 前一个 Behavior 已完成 TDD，不代表后续 Behavior 可以直接修改实现代码。
30
26
 
31
- ## Finalize（非阶段）
27
+ 已有行为若无需修改且已由现有测试充分覆盖，不强制制造 Red。
32
28
 
33
- Verify 出口满足后读取 [finalize.md](references/finalize.md) 并立即收尾。Finalize 不计入交付阶段，只负责必要的 docs/README 对齐、直接创建当前 issue 的独立 commit 与 Tracker/progress 更新；不执行额外安全扫描、staged diff 复核或 commit message 门禁。若发现实现、测试或文档证据不完整，回到对应阶段修复后再 Finalize。
29
+ **出口：**
34
30
 
35
- Finalize 出口：commit 已创建、Acceptance Criteria 全部通过，Tracker 与工作区反映真实完成状态。
31
+ - 所有需要实现或修改的 Behavior 均完成各自的 Red → Green cycle；
32
+ - Acceptance Criteria 对应行为通过相关验证。
36
33
 
37
- ## 运行时纪律
34
+ ### ② Verify
38
35
 
39
- - 三个阶段都从入口连续执行到自身出口；Verify 出口满足后立即进入 Finalize：预告下一步后立即执行；进度输出并入工具调用序列，输出后继续执行。只有合规交互点、明确的外部阻塞或阶段出口条件结束当前回合。
40
- - 一个 seam 是公共可观察边界；一个 Behavior 是一个红-绿 cycle；一个 seam 可以包含多个 Behaviors。Seam/Behavior 的细节和 Todo 粒度只在进入 Step ② 时读取 [red-green.md](references/red-green.md)。
41
- - 每个 issue 只在 Verify 的最终 diff 稳定后调用一次 `code-review`；审查维度、reviewer 数量、提示词和输出格式全部由 `code-review` 自己定义，`tdd-implement` 不复制这些规则。`code-review` 未完成或存在 blocking finding 时 issue 不得收敛；A3 层收敛不再次调用 review。
42
- - 当前 issue 的范围、Acceptance Criteria、Out of Scope、测试/typecheck/build/真实运行证据和最终 commit 必须可追溯。Seam 或专项测试绿色不代表 issue 完成；三个阶段出口与 Finalize 全部满足后才可标记 `resolved`。
43
- - 多 issue 模式中，每个 issue 只提交一个独立 commit；issue 影响范围测试在 Step ③ 执行，A4 只做最终编排收敛，不额外扩大测试范围。
36
+ 读取 [verify.md](references/verify.md)，执行当前 issue 所需的最终验证。
44
37
 
45
- ## 引用
38
+ 最终验证通过且 diff 稳定后执行完整 `code-review`。
46
39
 
47
- - TDD 核心规则：[tdd 技能](.agents/skills/tdd/SKILL.md)
48
- - 测试标准：[tdd/tests.md](.agents/skills/tdd/tests.md)
49
- - Mock 指南：[tdd/mocking.md](.agents/skills/tdd/mocking.md)
50
- - Contract：[contract.md](references/contract.md)
51
- - Red-Green：[red-green.md](references/red-green.md)
40
+ #### Review
41
+
42
+ 每个 issue 只在 Verify 的最终 diff 稳定后调用一次完整 `code-review`；审查维度、reviewer 数量、提示词和输出格式全部由 `code-review` 自己定义，`tdd-implement` 不复制这些规则。`code-review` 未完成或存在 blocking finding 时 issue 不得收敛；多 issue 层收敛不再次调用完整 Review。
43
+
44
+ 若完整 Review 存在 blocking finding：
45
+
46
+ 1. 仅修复对应 finding，不扩大当前 issue 范围；
47
+ 2. 修复后仅对该 finding 及其直接影响执行增量 Review；
48
+ 3. 未受影响的 Review 结论继续有效；
49
+ 4. 不重新执行完整双轴 Review；
50
+ 5. 若增量 Review 仍存在问题，仅继续修复并复核剩余 finding。
51
+
52
+ 所有 blocking finding 关闭后 Review 才算通过。
53
+
54
+ **出口：**
55
+
56
+ - 当前 issue 所需最终验证通过；
57
+ - 要求的真实运行验证完成；
58
+ - 完整 Review 已完成；
59
+ - 所有 blocking finding 已关闭。
60
+
61
+ ## Finalize
62
+
63
+ Verify 通过后读取 [finalize.md](references/finalize.md)，完成当前 issue 的必要同步、独立 commit 与 tracker/progress 收尾。
64
+
65
+ Finalize 不新增产品 Behavior；若发现实现或验证遗漏，回到对应 Step 完成后再收尾。
66
+
67
+ ## 运行纪律
68
+
69
+ - Red-Green 必须覆盖当前 issue 的全部待实现 Behavior，不能只对第一个改动执行 TDD。
70
+ - 一个 Behavior 完成后继续下一个 Behavior，直到 Step ① 出口满足。
71
+ - Verify 只做当前 issue 必要的最终验证；已通过的等价验证不机械重复。
72
+ - 完整双轴 Review 每个 issue 只执行一次；后续修复只执行受影响 finding 的增量 Review。
73
+ - 当前 Step 达到出口后继续进入下一 Step；仅在需要用户决策或存在外部阻塞时暂停。
74
+
75
+ ## References
76
+
77
+ - TDD：[tdd](.agents/skills/tdd/SKILL.md)
52
78
  - Verify：[verify.md](references/verify.md)
53
- - Review 方法：[code-review](.agents/skills/code-review/SKILL.md)
54
79
  - Finalize：[finalize.md](references/finalize.md)
55
- - 完整兼容规范：[stages.md](references/stages.md)
80
+ - Review：[code-review](.agents/skills/code-review/SKILL.md)
56
81
  - 多 issue 编排：[orchestration.md](references/orchestration.md)
package/template/.agents/skills/tdd-implement/references/finalize.md CHANGED
@@ -1,27 +1,16 @@
1
- # Finalize（非阶段）
1
+ # Finalize
2
2
 
3
- 仅在 `tdd-implement` Step ③ Verify 通过后读取。Finalize 不计入交付阶段；开始后不新增产品 Behavior，发现实现、测试或文档遗漏时回到对应阶段。
3
+ 仅在 Verify 通过后执行；不新增产品 Behavior。
4
4
 
5
- ## Commit
5
+ 1. 完成实现要求的必要 docs/config 同步。
6
+ 2. 为当前 issue 创建一个独立 commit。
7
+ 3. 更新 progress/tracker，记录 commit、Review、验证与运行结果，并解除已满足的 blockers。
8
+ 4. 将 Acceptance Criteria 标记完成，issue 标记 `resolved`。
6
9
 
7
- 1. 如本次实现要求 README/docs/config/package 同步，完成必要更新。
8
- 2. 按当前 issue 范围直接创建一个独立 commit。
9
- 3. 不执行额外敏感信息/安全扫描，不做 `git diff --cached` 复核，也不设置额外 commit message 门禁。
10
-
11
- 仓库级 Git 安全与历史保护规则仍然适用；Finalize 不重复定义或扩展这些规则。
12
-
13
- ## Tracker 收尾
14
-
15
- Commit 成功后：
16
-
17
- - 勾选 Acceptance Criteria；
18
- - issue 标记 `resolved`；
19
- - 写实施总结并同步 `.scratch/<feature>/progress.md` 的 Status/Commit/Review/Tests；
20
- - 记录 commit hash/message、最终测试和真实运行结果；
21
- - 确认后续 blockers 是否解除。
10
+ 若发现实现或验证遗漏，返回对应 Step 完成后再收尾。
22
11
 
23
12
  ## 出口
24
13
 
25
14
  - 当前 issue 的独立 commit 已创建；
26
15
  - Acceptance Criteria 全部通过；
27
- - Tracker/progress 与真实完成度一致。
16
+ - tracker/progress 与实际完成状态一致。