@wwkit/harness 1.0.17 → 1.0.18

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 (30) hide show
  1. package/agents/todo.md +119 -0
  2. package/agents/work-explore.md +50 -0
  3. package/agents/work-general.md +44 -0
  4. package/agents/work.md +55 -34
  5. package/package.json +1 -1
  6. package/skills/todo-dispatch/SKILL.md +211 -0
  7. package/skills/todo-finalize/SKILL.md +238 -0
  8. package/skills/todo-plan/SKILL.md +174 -0
  9. package/skills/todo-recovery/SKILL.md +179 -0
  10. package/skills/todo-review/SKILL.md +259 -0
  11. package/skills/work-dispatch/SKILL.md +15 -2
  12. package/skills/work-dispatch/references/dispatch-prompt.md +10 -1
  13. package/skills/work-dispatch/references/explore-prompt.md +74 -0
  14. package/skills/work-dispatch/references/report-handling.md +31 -4
  15. package/skills/work-finalize/SKILL.md +2 -2
  16. package/skills/work-finalize/references/final-review.md +5 -3
  17. package/skills/work-finalize/references/handover.md +8 -0
  18. package/skills/work-ledger/SKILL.md +1 -1
  19. package/skills/work-ledger/references/bootstrap.md +12 -4
  20. package/skills/work-plan/SKILL.md +2 -2
  21. package/skills/work-plan/references/self-review.md +1 -1
  22. package/skills/work-plan/references/split-rules.md +1 -1
  23. package/skills/work-plan/references/task-fields.md +10 -10
  24. package/skills/work-recovery/SKILL.md +8 -8
  25. package/skills/work-recovery/references/budget.md +10 -11
  26. package/skills/work-recovery/references/rollback.md +4 -4
  27. package/skills/work-review/SKILL.md +2 -2
  28. package/skills/work-review/references/fix-loop.md +14 -9
  29. package/skills/work-review/references/reviewer-prompt.md +1 -1
  30. package/skills/work-review/references/verdict-handling.md +1 -1
package/skills/todo-review/SKILL.md ADDED
@@ -0,0 +1,259 @@
1
+ ---
2
+ name: todo-review
3
+ description: 审查与修复阶段：生成 review package、派发 reviewer（Spec+Quality 两阶段）、处理结论、fix loop（≤5 轮）+ scoped re-review、Breaker 裁决。implementer 返回 DONE/DONE_WITH_CONCERNS 后加载。
4
+ license: MIT
5
+ metadata:
6
+ workflow: sequential
7
+ ---
8
+
9
+ # todo-review 技能
10
+
11
+ ## 输入
12
+
13
+ | 输入 | 说明 |
14
+ |------|------|
15
+ | `doc_dir` | 产物目录绝对路径 |
16
+ | `task_id` (`T<N>`) | 当前任务编号 |
17
+ | `base` | Ledger 中该任务的 `base=` 值 |
18
+ | `HEAD` | 当前 HEAD |
19
+ | `brief_file` | `<doc_dir>/task-<N>-brief.md` |
20
+ | `report_file` | `<doc_dir>/task-<N>-report.md` |
21
+
22
+ ## 工作流程
23
+
24
+ ### 步骤 1：生成 review package
25
+
26
+ ```bash
27
+ # 生成 diff 包（commits + stat + full diff with 10 lines context）
28
+ diff_file="<doc_dir>/task-<N>-review-<base7>..<head7>.diff"
29
+ git log --oneline <base>..<HEAD> > "$diff_file"
30
+ echo "" >> "$diff_file"
31
+ git diff --stat <base>..<HEAD> >> "$diff_file"
32
+ echo "" >> "$diff_file"
33
+ git diff -U10 <base>..<HEAD> >> "$diff_file"
34
+ ```
35
+
36
+ 写入 Ledger：`T<N>: reviewed_head=<HEAD7>`
37
+
38
+ ### 步骤 2：派发 reviewer（串行：一个任务一个 reviewer）
39
+
40
+ 一次任务级审查 = 一个 reviewer subagent，不并行拆分（多个 reviewer 重复读同一 diff，无并行收益）。用 `task` 工具派发，`subagent_type: "general"`，`background: true`。
41
+
42
+ #### Reviewer prompt 模板
43
+
44
+ ```
45
+ 你是审查 subagent，审查一个任务的实现。这是任务级审查，不是合并审查。
46
+
47
+ ## What Was Requested
48
+ Read the task brief: <brief_file>
49
+
50
+ Global constraints: <constraints>
51
+
52
+ ## What the Implementer Claims
53
+ Read the implementer's report: <report_file>
54
+
55
+ ## Diff Under Review
56
+ Base: <base>
57
+ Head: <HEAD>
58
+ Diff file: <diff_file>
59
+
60
+ Read the diff file once — it contains the commit list, stat summary, and full diff
61
+ with context. Do not re-run git commands. Do not crawl the broader codebase.
62
+
63
+ Your review is read-only. Do not mutate the working tree, index, HEAD, or branch.
64
+
65
+ ## You Do Not Dispatch Subagents
66
+ Do all review yourself. Never spawn a subagent.
67
+
68
+ ## Do Not Trust the Report
69
+ Treat the implementer's report as unverified claims. Verify against the diff.
70
+
71
+ ## Tests
72
+ The implementer already ran tests. Do not re-run the suite. Run a focused test only
73
+ when reading the code raises a specific doubt.
74
+
75
+ ## Part 1: Spec Compliance
76
+ - Missing: requirements skipped or claimed without implementing
77
+ - Extra: features not requested, over-engineering
78
+ - Misunderstood: right feature built the wrong way
79
+
80
+ ## Part 2: Code Quality
81
+ - Clean separation of concerns?
82
+ - Proper error handling?
83
+ - DRY without premature abstraction?
84
+ - Edge cases handled?
85
+ - Tests verify real behavior, not mocks?
86
+
87
+ ## Output Format
88
+ Write your review to <review_file> (<doc_dir>/task-<N>-review.md):
89
+
90
+ ### Spec Compliance
91
+ - ✅ Spec compliant | ❌ Issues found: [what's missing/extra/misunderstood, with file:line]
92
+
93
+ ### Strengths
94
+ [What's well done? Be specific.]
95
+
96
+ ### Issues
97
+ #### Critical (Must Fix)
98
+ #### Important (Should Fix)
99
+ #### Minor (Nice to Have)
100
+ For each issue: file:line, what's wrong, why it matters, how to fix.
101
+
102
+ ### Assessment
103
+ **Task quality:** Approved | Needs fixes
104
+ **Reasoning:** [1-2 sentence technical assessment]
105
+
106
+ Then report back with ONLY (≤15 lines):
107
+ - Spec: ✅/❌
108
+ - Quality: Approved/Needs fixes
109
+ - Finding count (Critical/Important/Minor)
110
+ - One-line summary
111
+ - Review file path
112
+ ```
113
+
114
+ ### 步骤 3：处理结论
115
+
116
+ 读取 `<doc_dir>/task-<N>-review.md`，按结论分派：
117
+
118
+ | 结论 | 动作 |
119
+ |------|------|
120
+ | ✅ Spec + Approved | 任务完成，写 Ledger `T<N>: complete (commits <base7>..<head7>, review clean)`，勾单 |
121
+ | ❌ 或有 Critical/Important | 进入 fix loop |
122
+ | ⚠️ Cannot verify | 主 agent 不得读源码核实——派只读 verify subagent 运行聚焦验证，据报告裁决（详见下） |
123
+ | Minor only | 记录 Ledger `T<N>: minor (deferred): <one-liner>`，任务完成，勾单 |
124
+ | Plan-mandated | 主 agent 裁决：weigh finding against plan text，record `Ruling: <决定> — <原因> — <代价>`，不打断流程 |
125
+
126
+ **⚠️ Cannot verify 的处理**：reviewer 无法只凭 diff 判断某点时，主 agent **绝不自己读源码 / 跑测试核实**。派发一个只读 verify subagent（`subagent_type: "general"`，`background=true`），prompt 约束：只运行 reviewer 指出的聚焦验证命令（focused test / 单条命令），只读相关文件 + 附 file:line 证据，不提交、不改工作树、不嵌套派发。据其报告裁决：
127
+ - 聚焦验证 PASS → 记录 `Ruling: <点> 验证通过 — 聚焦测试 PASS — cost if wrong low`，任务完成，勾单
128
+ - 聚焦验证 FAIL → 视为 spec ❌，进入 fix loop
129
+ - 仍无法判定（需环境/需 implementer 补证据）→ 视为 spec ❌，退回 implementer 补证据后重审
130
+
131
+ **勾单语义**：`todowrite` 全量替换整个清单——当前任务标 `completed`（下一个任务的 `in_progress` 由 todo-dispatch 派发时统一标记）。绝不只改一项。
132
+
133
+ ### 步骤 4：Fix Loop（如触发）
134
+
135
+ 最多 5 轮，每轮 = 一次 fix dispatch + 一次 scoped re-review。
136
+
137
+ #### 轮次策略
138
+
139
+ | 轮次 | Implementer | 理由 |
140
+ |------|-------------|------|
141
+ | 1-3 | 恢复原 implementer（context 完整） | 它知道任务、代码、自己的选择 |
142
+ | 4-5 | 新 implementer + 更详细 brief | fresh eyes，原 implementer 可能看不到自己的问题 |
143
+
144
+ #### 每轮流程
145
+
146
+ 1. **Fix dispatch（串行）**：派发 fix implementer（`general`, `background=true`）——一个 fix subagent 修本轮全部 findings（findings 常共享文件，并行修复会冲突）。prompt 包含：
147
+ - brief_file 路径
148
+ - report_file 路径（fix 报告 append 到同一文件）
149
+ - open findings（逐条列出）
150
+ - "Fix these findings, re-run covering tests, append fix report to <report_file>"
151
+
152
+ 2. **生成 scoped review package**：
153
+ ```bash
154
+ fix_base=<上一轮 reviewed_head>
155
+ scope_diff="<doc_dir>/task-<N>-rereview-<R>-<fix_base7>..<head7>.diff"
156
+ git log --oneline <fix_base>..<HEAD> > "$scope_diff"
157
+ git diff --stat <fix_base>..<HEAD> >> "$scope_diff"
158
+ git diff -U10 <fix_base>..<HEAD> >> "$scope_diff"
159
+ ```
160
+
161
+ 3. **Scoped re-review**：派发 re-reviewer（`general`, `background=true`），prompt 包含：
162
+ - brief_file 路径
163
+ - findings 列表
164
+ - report_file 路径
165
+ - scope_diff 路径
166
+ - "Verdict each finding: ADDRESSED / NOT ADDRESSED. Check fix diff for new breakage only."
167
+
168
+ 4. **写 Ledger**：
169
+ ```
170
+ T<N>: fix round <R>/5 (<X> addressed, <Y> open — <finding one-liners>; commits <base7>..<head7>)
171
+ ```
172
+
173
+ 5. **判断**：
174
+ - 全部 ADDRESSED + 无新 Critical/Important → 任务完成，勾单
175
+ - 有 open findings 且 R < 5 → 下一轮
176
+ - 有 open findings 且 R = 5 → Breaker
177
+
178
+ #### Re-reviewer prompt 模板
179
+
180
+ ```
181
+ 你是 scoped re-review subagent。验证上一轮 review 的 findings 是否已解决，检查 fix diff 是否引入新问题。
182
+
183
+ ## The Task
184
+ Read the task brief: <brief_file>
185
+
186
+ ## The Findings Under Verification
187
+ <findings — 逐条列出>
188
+
189
+ ## The Fix
190
+ Read the implementer's report (fix reports appended at end): <report_file>
191
+
192
+ Fix base: <fix_base>
193
+ Head: <HEAD>
194
+ Diff file: <scope_diff>
195
+
196
+ Read the diff file once. Do not re-run git commands. Read-only review.
197
+
198
+ ## Scope
199
+ Your scope is the findings list and the fix diff. Verdict every finding.
200
+ Inspect the fix diff for new problems only. Do NOT re-review code the fix did not touch.
201
+ Out-of-scope observations → report as non-blocking, do not extend the loop.
202
+
203
+ ## You Do Not Dispatch Subagents
204
+
205
+ ## Output Format
206
+ Write your re-review to <rereview_file> (<doc_dir>/task-<N>-rereview-<R>.md):
207
+
208
+ ### Finding Verdicts
209
+ For each finding, in order:
210
+ - **<finding one-liner>** — ADDRESSED | NOT ADDRESSED, with file:line evidence
211
+
212
+ ### New Breakage in the Fix Diff
213
+ Anything the fix broke. "None" if clean.
214
+
215
+ ### Out-of-Scope Observations
216
+ Non-blocking. "None" if none.
217
+
218
+ ### Verdict
219
+ **Fix round:** All findings addressed, no new Critical/Important breakage | Findings remain open — list them
220
+
221
+ Then report back with ONLY (≤10 lines):
222
+ - Verdict: All addressed | <N> open
223
+ - New breakage: None | <count>
224
+ - Re-review file path
225
+ ```
226
+
227
+ ### 步骤 5：Breaker（Round 5 仍有 open findings）
228
+
229
+ **绝不**在 Round 5 前提前裁决。只有 Round 5 re-review 仍有 open findings 时才触发。
230
+
231
+ 主 agent 裁决每条 open finding：
232
+
233
+ | 情况 | 裁决 | Ledger 记录 |
234
+ |------|------|------------|
235
+ | reviewer 错误/可争议 | park with ruling | `T<N>: parked — <finding> — Ruling: <why code stands>` |
236
+ | 真问题但不 load-bearing | park with ruling | `T<N>: parked — <finding> — Ruling: real but deferred` |
237
+ | 真问题且 load-bearing | 最小修复裁决 | `T<N>: Ruling: <finding> — <what you decided> — <cost if wrong>` |
238
+ | 每条路都是猜测 | STOP | `T<N>: BLOCKED — <reason>` |
239
+
240
+ 裁决后：
241
+ - 全部 parked → 任务完成，勾单
242
+ - 有 load-bearing ruling → 继续执行裁决的修复
243
+ - STOP → 加载 todo-recovery
244
+
245
+ ## 输出
246
+
247
+ - `<doc_dir>/task-<N>-review-<base7>..<head7>.diff`（review package）
248
+ - `<doc_dir>/task-<N>-review.md`（reviewer 报告）
249
+ - fix loop 期间：scoped diff + `<doc_dir>/task-<N>-rereview-<R>.md`
250
+ - Ledger 条目：`T<N>: reviewed_head=` / `T<N>: complete` / `T<N>: fix round <R>/5` / `T<N>: minor (deferred)` / `T<N>: parked` / `Ruling:`
251
+
252
+ ## 约束
253
+
254
+ - reviewer/re-reviewer 只读约束写在 prompt 里，不得改源码、不得 add/commit
255
+ - reviewer 不重跑测试：信任 implementer 报告的测试结果
256
+ - fix prompt **内联 open findings（verbatim）+ 引用 review 文件路径**（implementer 需更多上下文时自读完整 review），与 superpowers 一致
257
+ - fix 轮次硬上限 5 轮；Breaker 绝不在 Round 5 前提前裁决
258
+ - 主 agent 不自己 fix findings——controller fixes skip review
259
+ - 只审查与 fix，不规划、不派发初次 implementer
package/skills/work-dispatch/SKILL.md CHANGED
@@ -39,6 +39,7 @@ work agent 完成第三步「产物目录与 Ledger」、并已通过 work-plan
39
39
 
40
40
  - `references/prepare.md` → 4.1 准备（BASE 记录、Ledger 写 base+session、brief 渲染、report 路径指定）
41
41
  - `references/dispatch-prompt.md` → 4.2 派发 prompt 模板（自包含结构 + 执行边界 50 次 + 防循环 + 自审 + 报告格式）与「禁止」清单
42
+ - `references/explore-prompt.md` → 只读调研 prompt 模板（explore 专属，执行边界 30 次 + 只读约束 + 报告格式）
42
43
  - `references/report-handling.md` → 4.3 status 处理表 + 异常返回表 + 重试上限 1 次 + background 派发与串行衔接
43
44
 
44
45
  ### 阶段 2：派发前准备
@@ -47,7 +48,18 @@ work agent 完成第三步「产物目录与 Ledger」、并已通过 work-plan
47
48
 
48
49
  ### 阶段 3：派发 implementer
49
50
 
50
- 按 `references/dispatch-prompt.md` 渲染自包含 prompt（所有占位符展开为绝对路径），用 `task` 工具派发，`subagent_type` 取 `explore`（只读）或 `general`（可写）。写 Ledger `T<N>: session=<session_ref>`。
51
+ 按 `references/dispatch-prompt.md` 渲染自包含 prompt（所有占位符展开为绝对路径），用 `task` 工具派发，`subagent_type` 取 `work-explore`（只读）或 `work-general`（可写）。写 Ledger `T<N>: session=<session_ref>`。
52
+
53
+ ### 阶段 3a：并行派发 explore（可选）
54
+
55
+ 当 plan.md 中存在多个可并行的 `work-explore`（只读）任务时，按以下流程批量派发：
56
+
57
+ 1. **识别可并行任务**：从 plan.md 中筛选出当前轮次可同时执行的 explore 任务（无依赖或依赖已满足）。
58
+ 2. **批量派发 ≤5**：在同一条消息中发出多个 `task` 调用，`subagent_type=work-explore`，`background=true`，每个使用 `references/explore-prompt.md` 模板渲染 prompt。写 Ledger `T<N>: session=<session_ref>`（每个任务各写一行）。
59
+ 3. **等待全部返回**：所有 explore 任务返回后再逐个处理，不边收边派。
60
+ 4. **逐个处理返回**：对每个 explore 返回按 `references/report-handling.md` 写 Ledger 状态行并分派动作。
61
+
62
+ > general 任务仍保持串行：派发后等 review close 才派下一个 general，不与 explore 混合并行。
51
63
 
52
64
  ### 阶段 4：处理返回
53
65
 
@@ -65,7 +77,7 @@ implementer 返回后立即按 `references/report-handling.md` 写 Ledger 状态
65
77
  - prompt 必须自包含：subagent 看不到主 agent 历史，所有占位符（`<BRIEF_FILE>`/`<REPORT_FILE>`/`<doc_dir>/...` 等）一律展开为绝对路径。
66
78
  - 派发前禁止：粘贴计划全文到 prompt、粘贴之前任务摘要到后续 prompt、让 subagent 读整个计划文件、在 prompt 中重复 brief 的 accept/verify。
67
79
  - 异常处理纪律：绝不忽略升级或强制同一模型无变化重试；空输出/无 status 最多重试 1 次，再失败按 BLOCKED 处理。
68
- - 串行硬规则：下一个 `general` 必须在上一任务 review close 后才派发，且 `BASE` 自动等于上一任务 `HEAD`；`explore` 可并行且 ≤5 个/轮。
80
+ - 串行硬规则：下一个 `work-general` 必须在上一任务 review close 后才派发，且 `BASE` 自动等于上一任务 `HEAD`；`work-explore` 可并行且 ≤5 个/轮。
69
81
  - 本技能只派发与处理返回，不审查、不 fix、不改源码。
70
82
 
71
83
  ## 资源目录
@@ -74,5 +86,6 @@ implementer 返回后立即按 `references/report-handling.md` 写 Ledger 状态
74
86
  references/
75
87
  ├── prepare.md # 4.1 准备（BASE/Ledger/brief/report 路径）
76
88
  ├── dispatch-prompt.md # 4.2 派发 prompt 模板 + 禁止清单
89
+ ├── explore-prompt.md # 只读调研 prompt 模板（explore 专属）
77
90
  └── report-handling.md # 4.3 status 表 + 异常表 + 重试上限 + 串行衔接
78
91
  ```
package/skills/work-dispatch/references/dispatch-prompt.md CHANGED
@@ -1,6 +1,8 @@
1
1
  # 4.2 派发 prompt 模板
2
2
 
3
- 使用 `task` 工具，`subagent_type` 取 `explore`（只读）或 `general`（可写）。
3
+ 使用 `task` 工具，`subagent_type` 取 `work-explore`（只读）或 `work-general`（可写）。
4
+
5
+ - **所有 task 派发必须传 `background=true`**：subagent 异步运行，主 agent 不阻塞，完成时自动通知。这是防止主 agent 卡死的硬性约束。
4
6
 
5
7
  ## 自包含原则
6
8
 
@@ -85,3 +87,10 @@ brief 是你的唯一需求来源——不要假设 brief 之外的任何上下
85
87
  - 粘贴之前任务的摘要到后续任务的 prompt
86
88
  - 让 subagent 读整个计划文件
87
89
  - 在 prompt 中重复 brief 的 accept/verify（implementer 自己读 brief）
90
+
91
+ ## 并行派发
92
+
93
+ - **explore 任务可同轮批量派发（≤5）**：当存在多个可并行的只读调研任务时，在同一条消息中发出多个 `task` 调用，`subagent_type=work-explore`，`background=true`，每个使用 `references/explore-prompt.md` 模板渲染 prompt。
94
+ - **general 任务必须串行**：使用本文件（dispatch-prompt.md）模板，派发后等 review close 才派下一个 general。
95
+ - **批量派发 explore 时**：同一条消息发出多个 task 调用，全部 `background=true`；等待全部 explore 返回后再逐个处理返回，不边收边派。
96
+ - **explore 与 general 衔接**：所有 explore 返回并处理完毕后，再进入 general 串行链。
package/skills/work-dispatch/references/explore-prompt.md ADDED
@@ -0,0 +1,74 @@
1
+ # 4.3 只读调研 prompt 模板
2
+
3
+ 使用 `task` 工具，`subagent_type` 取 `work-explore`（只读）。
4
+
5
+ - **所有 task 派发必须传 `background=true`**：subagent 异步运行，主 agent 不阻塞，完成时自动通知。这是防止主 agent 卡死的硬性约束。
6
+
7
+ ## 自包含原则
8
+
9
+ > 派发前，prompt 中所有占位符（`<BRIEF_FILE>`、`<REPORT_FILE>`、`<doc_dir>/...` 等）一律展开为绝对路径，subagent 直接可读，不再含任何待解引用符号。
10
+
11
+ subagent 看不到主 agent 历史，prompt 必须自包含。
12
+
13
+ ## prompt 结构
14
+
15
+ ```
16
+ 你是一个被派发的只读调研者。你的任务是执行 T<N>: <task name>
17
+
18
+ ## 任务详情
19
+
20
+ 读取你的任务 brief：<BRIEF_FILE>
21
+ 它包含完整任务文本：goal、files、accept（验收标准）、verify、约束。
22
+ brief 是你的唯一需求来源——不要假设 brief 之外的任何上下文。
23
+
24
+ ## 上下文
25
+
26
+ <场景设置：任务在项目中的位置、依赖、架构上下文>
27
+ <接口信息：前序任务产出的接口、类型、签名——从 plan.md 的 interfaces 字段提取>
28
+
29
+ ## 约束
30
+
31
+ - 只读：绝不提交、绝不改写工作树/index/HEAD
32
+ - 工作目录：<root_dir>
33
+
34
+ ## 执行边界（硬约束）
35
+
36
+ - **最多 30 次工具调用**：每调用一次工具（read/grep/glob/bash 等）计一次。到 30 次仍未完成必须停止并报告 ESCALATE。
37
+ - **禁止无限循环**：同一个文件不要读超过 3 次；同一个搜索不要连续运行超过 3 次。
38
+ - **进度自检**：每 10 次工具调用后，评估剩余工作是否还能在剩余调用次数内完成。不能则立即停止并报告 ESCALATE。
39
+ - **范围**：只调研 brief 指定范围，不发散。
40
+ - **遇到以下情况立即停止并报告**：
41
+ - 无法理解代码（已读 3 次仍不明确）→ BLOCKED
42
+ - 调研范围超出 brief 预期 → BLOCKED
43
+ - 工具调用次数即将耗尽且未完成 → ESCALATE
44
+
45
+ ## 你的工作
46
+
47
+ 1. 按 brief 执行调研/搜索/验证
48
+ 2. 收集 file:line 证据
49
+ 3. 对照 brief 中的 accept 验收标准逐条自检
50
+ 4. 报告
51
+
52
+ ## 报告格式
53
+
54
+ 将完整报告写入 <REPORT_FILE>：
55
+ - 调研发现
56
+ - 关键 file:line 证据
57
+ - accept 逐条对照结果
58
+ - 顾虑或问题
59
+
60
+ 然后用 ≤10 行回报（详情在报告文件中）：
61
+ - Status: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT | ESCALATE
62
+ - 一行结论摘要
63
+ - 关键 file:line 证据（≤5 条）
64
+ - 工具调用次数（如 "used 12/30"）
65
+ - 报告文件路径
66
+ ```
67
+
68
+ ## 禁止
69
+
70
+ - 黏贴计划全文到 prompt（brief 文件是单一来源）
71
+ - 黏贴之前任务的摘要到后续任务的 prompt
72
+ - 让 subagent 读整个计划文件
73
+ - 在 prompt 中重复 brief 的 accept/verify（implementer 自己读 brief）
74
+ - 写代码、改文件、跑测试（只读场景）
package/skills/work-dispatch/references/report-handling.md CHANGED
@@ -2,6 +2,18 @@
2
2
 
3
3
  implementer 返回后，**立即写入 Ledger** 状态行，然后按 status 处理。
4
4
 
5
+ ## 任务后工作区验证（强制）
6
+
7
+ > **explore 豁免**：`work-explore`（只读）返回时**跳过工作区验证**——explore 不产生任何 git 变更，无需检查 `git status --porcelain`。仅 `work-general`（可写）返回时执行以下工作区验证。
8
+
9
+ implementer 返回后、按 status 处理前，执行工作区干净检查：
10
+
11
+ 1. 检查 `git status --porcelain`：
12
+ - **空（干净）**：继续按 status 处理
13
+ - **非空（脏）**：
14
+ - 如果脏文件全部在 implementer 的 writable 白名单内 → implementer 忘记提交 → **主 agent 自动提交**（`git add <writable files> && git commit -m "<task_id>: auto-commit uncommitted writable files"`），记 Ledger `T<N>: auto-committed uncommitted writable`，继续按 status 处理
15
+ - 如果脏文件有不在 writable 白名单内的 → **forbidden 文件被改** → 记 Critical finding，强制 `git checkout -- <file>` 恢复，记 Ledger `T<N>: reverted forbidden <file>`
16
+
5
17
  ## status 处理表
6
18
 
7
19
  | Status | Ledger 记录 | 动作 |
@@ -12,6 +24,19 @@ implementer 返回后，**立即写入 Ledger** 状态行，然后按 status 处
12
24
  | `BLOCKED` | `T<N>: blocked (<reason>)` | 评估：上下文问题→补充重派；推理不足→换更强模型；任务过大→拆分；计划错误→重规划（见「重规划」节） |
13
25
  | `ESCALATE` | `T<N>: escalate (<reason>)` | 停止该分支。如实向用户说明为何超出边界/需人工介入，不再重试。如果是工具调用耗尽，考虑拆分任务后重新派发 |
14
26
 
27
+ ## explore 专用处理路径
28
+
29
+ `work-explore`（只读）的返回处理与 `work-general` 不同——explore 不产生 git 变更，无需 BASE/HEAD 记录：
30
+
31
+ | explore 返回 | 处理 |
32
+ |-------------|------|
33
+ | `DONE` | 直接进入 review（review 范围 = 报告内容，无 diff）。review 标准：brief 的 accept 是否满足 + 证据是否充分（file:line） |
34
+ | `DONE_WITH_CONCERNS` | 读报告中的顾虑段，正确性/范围问题先处理，观察类问题记录后进入 review |
35
+ | `NEEDS_CONTEXT` / `BLOCKED` / `ESCALATE` | 同 status 处理表 |
36
+
37
+ - explore **不生成 review package**（无 BASE/HEAD diff），review 直接基于报告文件内容。
38
+ - explore **无 Commits 字段**属正常（只读，不提交），不按"无 status"处理。
39
+
15
40
  ## 异常返回处理
16
41
 
17
42
  subagent 返回不符合预期时按以下表处理：
@@ -22,6 +47,8 @@ subagent 返回不符合预期时按以下表处理：
22
47
  | 无 status 行 | 返回文本不含 Status 关键字 | 计 Ledger `T<N>: no status`，从 report 文件读取实际状态；report 文件也无 → 按 BLOCKED 处理 |
23
48
  | 报告文件未写入 | report 文件不存在或为空 | 记 Ledger `T<N>: report missing`，按 BLOCKED 处理 |
24
49
  | task 工具返回错误 | task 工具返回 state="error" | 记 Ledger `T<N>: task error (<error>)`，评估错误类型后决定重派或升级 |
50
+ | explore 返回脏工作区 | `git status --porcelain` 非空且 subagent_type=work-explore | 不应发生（只读权限）。若发生记 Critical finding，强制 `git checkout -- <file>` 恢复，记 Ledger `T<N>: explore dirty workspace (reverted)` |
51
+ | explore 无 Commits 字段 | 返回文本不含 Commits 关键字且 subagent_type=work-explore | 正常（只读不提交），不按"无 status"处理，直接按 status 行处理 |
25
52
 
26
53
  ## 重试上限
27
54
 
@@ -29,10 +56,10 @@ subagent 返回不符合预期时按以下表处理：
29
56
 
30
57
  ## background 派发与串行衔接
31
58
 
32
- 派发后记 Ledger → 做本地工作 → 收到通知 → 处理 → review close 后才派下一个 general；等待期间不派下一个。
59
+ 派发后记 Ledger → 做本地工作 → 收到通知 → 处理 → review close 后才派下一个 `work-general`；等待期间不派下一个。
33
60
 
34
61
  - 派发后：立即写 Ledger `T<N>: session=` 与状态行，不要等返回。
35
- - 等待期间：可做不依赖该任务产物的本地工作（如准备下一任务 brief、整理 Ledger），但**不派发下一个 `general`**。
62
+ - 等待期间：可做不依赖该任务产物的本地工作（如准备下一任务 brief、整理 Ledger），但**不派发下一个 `work-general`**。
36
63
  - 收到通知：按上方 status 处理表分派动作。
37
- - review close 后：下一任务的 `BASE` 自动等于本任务 `HEAD`，才派发下一个 `general`。
38
- - `explore`（只读）可并行且 ≤5 个/轮，不受串行约束限制。
64
+ - review close 后：下一任务的 `BASE` 自动等于本任务 `HEAD`，才派发下一个 `work-general`。
65
+ - `work-explore`（只读）可并行且 ≤5 个/轮，不受串行约束限制。
package/skills/work-finalize/SKILL.md CHANGED
@@ -41,7 +41,7 @@ work agent 所有任务 review close 后、向用户交付前加载本技能，
41
41
 
42
42
  ### 阶段 2：Final Review
43
43
 
44
- 按 `references/final-review.md` 取 `MERGE_BASE` = Ledger 首行 `merge_base`，生成全分支 review package 到 `<doc_dir>/final-review-<merge_base7>..<head7>.diff`；派发 final reviewer（`general`，唯一写操作 `<doc_dir>/final-review.md`，≤30 次工具调用，不重跑测试）让其 triage parked/minor 项；有 findings → 一次 fix dispatch + 一次 scoped re-review（`FIX_BASE` = `final_review_head`）；残留 load-bearing → 报告用户。
44
+ 按 `references/final-review.md` 取 `MERGE_BASE` = Ledger 首行 `merge_base`，生成全分支 review package 到 `<doc_dir>/final-review-<merge_base7>..<head7>.diff`；派发 final reviewer（`work-general`，唯一写操作 `<doc_dir>/final-review.md`，≤30 次工具调用，不重跑测试）让其 triage parked/minor 项；有 findings → 一次 fix dispatch + 一次 scoped re-review（`FIX_BASE` = `final_review_head`）；残留 load-bearing → 报告用户。
45
45
 
46
46
  ### 阶段 3：最终 target 验收
47
47
 
@@ -66,7 +66,7 @@ work agent 所有任务 review close 后、向用户交付前加载本技能，
66
66
  - final reviewer 最多 30 次工具调用，到 30 次仍未完成必须停止并报告未完成。
67
67
  - final reviewer 写操作白名单 = 仅 `<doc_dir>/final-review.md`：不修改源码、不 add、不 commit、不改工作树/index/HEAD/分支。
68
68
  - final reviewer 不重跑测试：信任 Ledger 记录的测试结果；整体验收由主 agent 在第八步执行。
69
- - 有 findings 时只做**一次** fix dispatch（不是 per-finding）+ **一次** scoped re-review；final fix 一律派新 `general`（findings 可能跨多任务，无原 session 可复用）。
69
+ - 有 findings 时只做**一次** fix dispatch（不是 per-finding）+ **一次** scoped re-review；final fix 一律派新 `work-general`（findings 可能跨多任务，无原 session 可复用）。
70
70
  - 派发 final fix 前必须写 Ledger 首段 `final_review_head=<sha>`；scoped re-review 的 `FIX_BASE` 取该值。
71
71
  - 最终 target 验收运行**强制**：任务级 accept 通过并不代表 target 整体可用；退出判据三者缺一不可（所有任务 done + review 通过 + 整体验收通过）。
72
72
  - 本 agent 不 push / merge；交付即当前分支上的提交串，是否推送到远端由用户决定。
package/skills/work-finalize/references/final-review.md CHANGED
@@ -5,14 +5,16 @@
5
5
  ## 流程
6
6
 
7
7
  1. 定义 `MERGE_BASE`：取 Ledger 首行元数据中的 `merge_base`（取值规则见「起始检查」）。生成全分支 review package（`${MERGE_BASE}..HEAD`）到 `<doc_dir>/final-review-<merge_base7>..<head7>.diff`
8
- 2. 派发 final reviewer（`subagent_type` 取 `general`；唯一写操作是 `<doc_dir>/final-review.md`，不得改源码/add/commit），指向 Ledger 的 parked/minor 项让它 triage
8
+ 2. 派发 final reviewer（`subagent_type` 取 `work-general`；唯一写操作是 `<doc_dir>/final-review.md`，不得改源码/add/commit），指向 Ledger 的 parked/minor 项让它 triage
9
9
  3. final reviewer 写入 `<doc_dir>/final-review.md`
10
10
  4. 有 findings → **一次** fix dispatch（不是 per-finding）+ **一次** scoped re-review：
11
- - **final fix 一律派新 `general`**（findings 可能跨多任务，无原 session 可复用）。
11
+ - **final fix 一律派新 `work-general`**（findings 可能跨多任务，无原 session 可复用）。
12
+ - final fix implementer 工具调用上限 ≤20（同 fix 标准，非 work-general 默认的 50）。
12
13
  - 派发前写 Ledger 首段 `final_review_head=<sha>`（= 上次 final review 时的 HEAD）。
13
14
  - fix report 写入 `<doc_dir>/final-fix-report.md`（不覆盖 final-review.md）。
15
+ - **final fix 返回后执行工作区验证**（同 work-dispatch 的任务后工作区验证）：检查 `git status --porcelain`，脏文件在 fix 的 writable 内 → 主 agent 自动提交；不在 writable 内 → `git checkout` 恢复 + Critical finding。
14
16
  - fix 后 scoped re-review 的 `FIX_BASE` 取该 `final_review_head` 值，HEAD = 当前 HEAD，diff 写入 `<doc_dir>/final-fix-review-<final_review_head7>..<head7>.diff`。
15
- 5. 招留 load-bearing findings → 报告用户
17
+ 5. 残留 load-bearing findings → 报告用户
16
18
 
17
19
  ## final reviewer prompt
18
20
 
package/skills/work-finalize/references/handover.md CHANGED
@@ -6,6 +6,14 @@
6
6
 
7
7
  **交付即当前分支上的这串提交；本 agent 不 push / merge（那是 worktree 外的副作用），是否推送到远端由用户自行决定。**
8
8
 
9
+ ## 3.1 残留改动自动提交
10
+
11
+ target 交付后检查 `git status --porcelain`，若有残留 tracked 改动，自动执行 `git add -A && git commit -m "[auto] target 交付后残留提交"`。
12
+
13
+ - 保证下一个 target 起始时工作区干净，无需用户确认。
14
+ - `.webwork/` 产物目录已被 `.gitignore` 忽略，不触发脏检查。
15
+ - 所有改动均为计划内、review 过的改动，自动 commit 即可。
16
+
9
17
  ## 4. 裁决清单（显式列出）
10
18
 
11
19
  向用户输出结果摘要：交付物 + **本运行全部裁决**（parked / ruled / blocked / escalate / reverted / interrupted / replan，按发生顺序，每条附理由）。
package/skills/work-ledger/SKILL.md CHANGED
@@ -44,7 +44,7 @@ work agent 进入第三步「产物目录与 Ledger」时（创建运行时）
44
44
 
45
45
  ### 阶段 3：起始检查（仅此一次）
46
46
 
47
- 按 `references/bootstrap.md`：确认在 Git 仓库内；检查工作树干净（非空则 `git stash push -u` 并把脏文件清单记入 Ledger，此为人工确认点之一）；记录运行元数据 `branch`/`initial_base`/`merge_base` 并写入 Ledger 首行。
47
+ 按 `references/bootstrap.md`：确认在 Git 仓库内；检查工作树干净（非空则**停止，不自动 stash**，向用户输出脏文件清单，要求用户先 commit 或 stash，用户确认工作树干净后才继续，此为人工确认点之一）；记录运行元数据 `branch`/`initial_base`/`merge_base` 并写入 Ledger 首行。
48
48
 
49
49
  ### 阶段 4：Ledger 读写维护
50
50
 
package/skills/work-ledger/references/bootstrap.md CHANGED
@@ -11,12 +11,21 @@
11
11
 
12
12
  **创建产物目录**：创建 `<root_dir>/.webwork/harness/work/<session_id>/` 目录，并写入 `<root_dir>/.webwork/harness/work/.gitignore`（内容为 `*` + `!.gitignore`：忽略所有中间产物，但保留 `.gitignore` 自身）。归档目录 `<root_dir>/.webwork/harness/archive/` **不写** `.gitignore`——保留审计产物，可纳入版本控制。
13
13
 
14
- ## 起始检查（仅一次，创建产物目录时执行，L236-245）
14
+ ## 起始检查（每个 target 开始时执行）
15
15
 
16
- 派发任何 subagent 前，先确认工作树安全并记录运行元数据：
16
+ 派发任何 subagent 前，先确认工作树安全并记录运行元数据。区分**首次 target**（编排启动后的第一个 target）与**非首次 target**（后续 target 切换）：
17
17
 
18
18
  1. **在 Git 仓库内**：非 Git 仓 → 报告用户并停止。
19
- 2. **工作树是否干净**（`git status --porcelain`）：非空 → 默认 `git stash push -u` 后继续，并把 existing 文件清单记录到 Ledger。**这是人工确认点之一（另一处在范围闸门）**：若用户在场可询问 stash/保留，但全自动运行不因询问卡住。
19
+ 2. **工作树是否干净**（`git status --porcelain`）——按首次/非首次分别处理：
20
+
21
+ **首次 target**：
22
+ - **空（干净）**：继续。
23
+ - **非空（脏）**：**停止，不自动 stash**。向用户输出脏文件清单，要求用户先 commit 或 stash。这是人工确认点——用户确认工作树干净后才继续。在 `--auto --pure` 模式下（无交互用户），脏工作树直接报错终止并输出脏文件清单，不继续派发。
24
+ - 清理后再次检查 `git status --porcelain`，如果仍非空则继续等待用户确认。
25
+
26
+ **非首次 target**（上一步 handover 已自动 commit 残留改动，工作区应已干净）：
27
+ - **空（干净）**：跳过 stash/用户确认流程，直接进入记录元数据。
28
+ - **非空（脏）**：**不应发生**——报错终止并输出脏文件清单，不继续派发。不等待用户确认，不自动 stash。
20
29
  3. **记录运行元数据**（写入 Ledger 首行，字段语义如下）：
21
30
  - `branch` = 当前分支名
22
31
  - `initial_base` = 当前 HEAD
@@ -24,5 +33,4 @@
24
33
 
25
34
  ## 后续约束（L247-249）
26
35
 
27
- - **脏文件不得被 implementer 一起提交**：每个任务 brief 的 `forbidden` 中追加「不得 add/commit 任何未在 `writable` 白名单中的文件」。
28
36
  - 回滚锚点：`initial_base` 是本运行所有提交的回滚参照（见「中断与回滚」）。
package/skills/work-plan/SKILL.md CHANGED
@@ -3,7 +3,7 @@ name: work-plan
3
3
  description: |
4
4
  [work 专属 runbook] 仅供 work agent 通过 skill 工具显式调用（name=work-plan），其他 agent / 普通对话禁止触发
5
5
  规划阶段技能：按 1.1 任务拆分把 target 拆成 ≤10 分钟、可布尔验收的任务，按 2.1 填写 11 字段任务计划，
6
- 按 2.2 写入 plan.md，按 2.3 自审（范围闸门 + 8 项），核对 2.4 并发硬规则（explore ≤5 并行 / general 串行 / BASE=上一 HEAD）。
6
+ 按 2.2 写入 plan.md，按 2.3 自审（范围闸门 + 8 项），核对 2.4 并发硬规则（work-explore ≤5 并行 / work-general 串行 / BASE=上一 HEAD）。
7
7
  适用：work agent 第一步规划到派发前的「规划 → 落单」环节。
8
8
  不适用：执行/派发/审查/产物目录与 Ledger（用 work-ledger）；非 work 流程的普通规划。
9
9
  license: MIT
@@ -66,7 +66,7 @@ work agent 完成第一步解析用户输入（`target`/`root_dir`/`constraints`
66
66
 
67
67
  - 拆分第一约束：每个任务 ≤10 分钟可完成，且能独立写出可布尔判定的 `accept`；超预算必须继续拆，宁可多小任务串行。
68
68
  - 反模式禁止：按 TDD 步骤拆 / 按文件数硬拆 / 一个任务塞多个不相关目标。
69
- - 并发硬规则：`explore`（只读）可并行且 ≤5 个/轮；`general`（可写）必须串行，须在上一任务 review close 后才派发下一个；下一个 `general` 的 `BASE` 自动等于上一任务 `HEAD`。
69
+ - 并发硬规则：`work-explore`（只读）可并行且 ≤5 个/轮；`work-general`（可写）必须串行，须在上一任务 review close 后才派发下一个；下一个 `work-general` 的 `BASE` 自动等于上一任务 `HEAD`。
70
70
  - 范围闸门：任务数 >20 或 `target` 无法在 ≤20 个独立验收单元内覆盖 → 暂停规划，向用户确认拆分范围。
71
71
  - 本技能不读写代码、不执行验证命令，只产出计划与 plan.md。
72
72
 
package/skills/work-plan/references/self-review.md CHANGED
@@ -12,7 +12,7 @@
12
12
  2. **接口一致性**：跨任务的类型名、函数签名、属性名是否匹配？T1 Produces 的 `clearLayers()` 在 T3 中是否也叫 `clearLayers()` 而非 `clearFullLayers()`？
13
13
  3. **占位符扫描**：有无 "TBD"、"加错误处理"、"类似 T1"、"按需实现" 等模糊描述？有则补具体。
14
14
  4. **依赖完整性**：`depends` 引用的 `task_id` 是否存在？有无循环依赖？有依赖的任务是否串行？
15
- 5. **文件所有权分区**：可写任务（`general`）强制串行，故无并发写冲突；只读任务（`explore`）不产生文件变更。此条仅用于校验 `files`/`writable` 不落在 `constraints` 禁改范围之内。
15
+ 5. **文件所有权分区**：可写任务（`work-general`）强制串行，故无并发写冲突；只读任务（`work-explore`）不产生文件变更。此条仅用于校验 `files`/`writable` 不落在 `constraints` 禁改范围之内。
16
16
  6. **路径合规**：`writable`/`forbidden`/`files` 都落在 `root_dir` 内且不与 `constraints` 冲突。
17
17
  7. **验收可判定**：每条 `accept` 是否可布尔判定？`verify` 命令是否具体可执行？
18
18
  8. **工时约束**：每个任务的 `budget` 是否 ≤10 分钟？超过的必须继续拆。
package/skills/work-plan/references/split-rules.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  ## 拆分第一约束
6
6
 
7
- 每个任务必须在 10 分钟内可完成，且能独立写出可布尔判定的 `accept`。这是 subagent 的硬预算（implementer 最多 50 次工具调用）；超过预算的任务必须继续拆，直到每个子任务都在预算内。宁可拆成多个小任务串行，也不要留 1 个超出预算的任务。若平台支持 `maxSteps`，用它作为工具调用次数的硬兜底。
7
+ 每个任务必须在 10 分钟内可完成，且能独立写出可布尔判定的 `accept`。这是 subagent 的硬预算（implementer 最多 50 次工具调用）；超过预算的任务必须继续拆，直到每个子任务都在预算内。宁可拆成多个小任务串行，也不要留 1 个超出预算的任务。工具调用次数通过 prompt 软约束控制。
8
8
 
9
9
  ## 拆分维度
10
10
 
package/skills/work-plan/references/task-fields.md CHANGED
@@ -12,7 +12,7 @@ interfaces: Consumes: funcA(x: string) → number（来自 T1，T2 需调用
12
12
  （无跨任务接口依赖时填 无）
13
13
  accept: 验收标准，≤3 条，每条可布尔判定（如 "Foo.bar() 返回 true"、"npm test 通过"）
14
14
  verify: 验证命令（如 `npm test -- src/foo.test.ts`；无测试时填 `无`）
15
- agent: explore（只读调研）| general（执行改动/多步）— 选择规则见下
15
+ agent: work-explore（只读调研）| work-general（执行改动/多步）— 选择规则见下
16
16
  writable: 可写文件白名单（为空 ⇒ 该任务只读；路径相对 root_dir；须与 files 的 Create/Modify 一致）
17
17
  forbidden: 禁改文件清单（至少含 constraints 全部内容）
18
18
  depends: 依赖任务：T1, T3（必须先完成）| 无
@@ -23,22 +23,22 @@ budget: 预计 ≤10 分钟
23
23
 
24
24
  | agent 类型 | 适用场景 | 工具权限 |
25
25
  |-----------|---------|---------|
26
- | `explore` | 只读调研：搜索代码、读取文件、理解结构、验证假设 | read/grep/glob（只读） |
27
- | `general` | 可写改动：编辑代码、执行命令、多步实现、写测试 | 全部工具 |
26
+ | `work-explore` | 只读调研：搜索代码、读取文件、理解结构、验证假设 | read/grep/glob（只读） |
27
+ | `work-general` | 可写改动：编辑代码、执行命令、多步实现、写测试 | 全部工具 |
28
28
 
29
29
  **选择规则**：
30
- - 任务涉及任何文件创建/修改/删除 → `general`
31
- - 任务只读不改（调研、审查、验证） → `explore`
32
- - 不确定时按 `general`（权限更大不会卡住）
30
+ - 任务涉及任何文件创建/修改/删除 → `work-general`
31
+ - 任务只读不改（调研、审查、验证） → `work-explore`
32
+ - 不确定时按 `work-general`（权限更大不会卡住）
33
33
 
34
- **注意**：审查类 subagent 取 `general`（需写审查文件），以 prompt 强约束「只读源码 + 写白名单仅审查文件」；审查处于任务串行链上，天然满足串行。
34
+ **注意**：审查类 subagent 取 `work-general`（需写审查文件），以 prompt 强约束「只读源码 + 写白名单仅审查文件」；审查处于任务串行链上，天然满足串行。
35
35
 
36
36
  ## 2.4 并发硬性规则（提取自 L193-200）
37
37
 
38
38
  - **并发分型（Git 隔离的核心约束）**：
39
- - `explore`（只读）**绝不提交、绝不改写工作树/index/HEAD**，只做搜索/读取/理解；可并行，**≤ 5 个/轮**。
40
- - `general`（可写）**必须串行**，同一轮最多 1 个在跑，且须在上一任务的 review close 后才派发下一个；下一个 general 的 `BASE` 自动等于上一任务的 `HEAD`，保证 `BASE..HEAD` 恰好是本任务自己的改动。
41
- - 凡任务可能产生任何文件或 git 变更，一律 `general`（从而落入串行）。
39
+ - `work-explore`（只读）**绝不提交、绝不改写工作树/index/HEAD**，只做搜索/读取/理解；可并行，**≤ 5 个/轮**。
40
+ - `work-general`（可写）**必须串行**，同一轮最多 1 个在跑，且须在上一任务的 review close 后才派发下一个；下一个 work-general 的 `BASE` 自动等于上一任务的 `HEAD`，保证 `BASE..HEAD` 恰好是本任务自己的改动。
41
+ - 凡任务可能产生任何文件或 git 变更，一律 `work-general`（从而落入串行）。
42
42
  - 串行还是并行由 `depends` 字段 + agent 类型共同决定：有依赖必须串行；无依赖但写操作同样串行；仅只读任务可并行。
43
43
  - 一个 subagent 对应一个可独立验收的任务，不把多个不相关目标塞给一个 subagent。
44
44
  - 状态如需跨轮保留，把状态写进 Ledger/文件，不要依赖子代理记忆。