@wwkit/harness 1.0.16 → 1.0.18

package/skills/todo-plan/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: todo-plan
+description: 规划阶段：创建 doc_dir + Ledger、探索（派 explore）、拆分任务、写 plan.md、计划自审、todowrite 落单。解析 target 后、派发任何 subagent 前加载。
+license: MIT
+metadata:
+  workflow: sequential
+---
+
+# todo-plan 技能
+
+## 输入
+
+| 字段 | 说明 | 默认 |
+|------|------|------|
+| `target` | 要达成的目标 | 必填 |
+| `root_dir` | 工程根目录 | 当前工作目录 |
+| `constraints` | 约束（不改的文件、禁止的操作） | 无 |
+
+## 工作流程
+
+### 步骤 1：创建产物目录
+
+```bash
+# 生成 run_id（纯时间戳；目录已在 .webwork/todo/ 下，无需再前缀）
+run_id="$(date +%Y%m%d-%H%M%S)"
+doc_dir="<root_dir>/.webwork/todo/${run_id}"
+mkdir -p "${doc_dir}"
+
+# 写 .gitignore（如果不存在）
+echo -e '*\n!.gitignore' > <root_dir>/.webwork/todo/.gitignore
+```
+
+### 步骤 2：起始检查
+
+```bash
+# 确认在 Git 仓库内
+git rev-parse --is-inside-work-tree
+
+# 记录运行元数据
+branch=$(git branch --show-current)
+initial_base=$(git rev-parse --short=7 HEAD)
+```
+
+**起始工作树检查（人工介入点）**：
+- 干净（`git status --porcelain` 空）→ 继续
+- **不干净 → 停止，报告脏文件并让人工介入处理**（由用户决定 stash / 保留 / 放弃）。这是**唯一的起始人工介入点**——之后的代码都是 agent 自主修改，提交也由 agent 自己完成，不再为工作树状态问用户
+
+### 步骤 3：写 Ledger
+
+写入 `<doc_dir>/progress.md`：
+
+```
+target: <用户目标摘要>
+doc_dir: <doc_dir 绝对路径>
+branch: <branch>
+initial_base: <initial_base>
+```
+
+### 步骤 4：探索代码库（MUST 派 `explore`）
+
+拆分任务前，只要 `target` 需要理解现有代码、文件结构、既有模式才能产出准确的 `files`/`accept`/`verify`，**你必须派发 `explore` subagent 去调研，绝不自己读源码**。
+
+- 有 1% 需要读源码的可能 → 就派 subagent（禁止「我凭记忆/凭感觉能拆」的借口）
+- 多个独立方向的调研 → **同一消息并行派发 ≤5 个 `explore` subagent**，每个 `background=true`
+- 每个 explore 沿用 `todo-dispatch` 的「只读调研 prompt 模板」约束（只读、不提交、附 file:line 证据）
+- 各 explore 结论写入报告文件；据此拆分任务，报告文件路径记入 Ledger
+
+### 步骤 5：拆分任务
+
+把 `target` 拆成任务列表，每个任务：
+- ≤10 分钟可完成
+- 能独立写出可布尔判定的 `accept`
+- 有明确的 `verify` 命令
+
+**拆分规则（强制）**：
+- 第一约束：每个任务 ≤10 分钟 + 可独立验收
+- **粒度强制**：任何任务拆出后若预估 >10 分钟，或包含多个可独立验收的子目标，**必须继续拆细，绝不塞给一个 subagent**
+- **并行分型强制**：拆分时对每个任务判定 `readonly`——只读 + 无依赖的任务**必须**标 `readonly=true`（可并行），不得一律标可写串行
+- 反模式：按 TDD 步骤拆 / 按文件数硬拆 / 一个任务塞多个不相关目标 / 把多个任务合并进一个 subagent
+- 不需要拆分的情况：target 本身就是单个 ≤10 分钟可验收的任务
+
+**并行分组**：拆分后把无依赖的 `readonly=true` 任务归组，作为 dispatch 并行派发依据（≤5 一批，见 todo-dispatch 步骤 3）。
+
+**任务字段**（每个任务）：
+
+| 字段 | 说明 |
+|------|------|
+| `task_id` | T1, T2, ... |
+| `goal` | 一句话目标 |
+| `files` | 涉及文件 |
+| `accept` | 可布尔判定的验收标准 |
+| `verify` | 验证命令 |
+| `agent` | `explore` / `general`（由 `readonly` 决定） |
+| `readonly` | true=只读调研，false=可写实现 |
+| `writable` | 可写文件白名单（readonly=false 时） |
+| `forbidden` | 禁止改动的文件/操作（至少包含 constraints） |
+| `depends` | 依赖的任务编号 |
+| `budget` | 工具调用上限（默认 readonly=30, 可写=50） |
+
+### 步骤 6：写 plan.md
+
+写入 `<doc_dir>/plan.md`：
+
+```markdown
+# <target 摘要>
+
+## Global Constraints
+<constraints>
+
+### T1: <goal>
+- files: <files>
+- accept: <accept>
+- verify: <verify>
+- agent: general
+- readonly: true/false
+- writable: <writable>
+- forbidden: <forbidden>
+- depends: -
+- budget: <N>
+
+### T2: <goal>
+...
+```
+
+### 步骤 7：计划自审
+
+产出 plan.md 后、todowrite 落单前，逐项自审。**任何一项不通过 → 修正计划后再继续，不派发**。
+
+**范围闸门**：任务数 >20，或 `target` 无法在 ≤20 个独立验收单元内覆盖 → **自主裁决**：本次只规划第一批 ≤20 个任务，剩余范围记入 Ledger 待重规划（`Ruling: 缩小范围 — 本次先做前 20 个任务 — 错了的代价=余下目标延迟`）。不等待用户。
+
+**逐项自检（8 项）**：
+
+1. **Spec 覆盖**：`target` 每个要求都有对应任务？补上未被覆盖的 gap。
+2. **接口一致性**：跨任务的类型名 / 函数签名 / 属性名是否一致（如 T1 产出的 `clearLayers()` 在 T3 也同名）？
+3. **占位符扫描**：有无 "TBD"、"加错误处理"、"类似 T1"、"按需实现" 等模糊描述？有则写具体。
+4. **依赖完整性**：`depends` 引用的 `task_id` 是否存在？无循环依赖？有依赖的任务是否串行？
+5. **文件所有权分区**：只读任务（`readonly=true`）不产生变更；可写任务串行无写冲突；`files`/`writable` 不落在 `constraints` 禁改范围。
+6. **路径合规**：`writable`/`forbidden`/`files` 都落在 `root_dir` 内且不与 `constraints` 冲突。
+7. **验收可判定**：每条 `accept` 可布尔判定？`verify` 命令具体可执行？
+8. **工时约束**：每个任务预估 ≤10 分钟？超出的必须继续拆。
+
+### 步骤 8：todowrite 落单
+
+用 `todowrite` 创建任务清单。每个任务一个 todo 项：
+
+```json
+[
+  {"content": "T1: <goal>", "status": "pending", "priority": "high"},
+  {"content": "T2: <goal>", "status": "pending", "priority": "high"}
+]
+```
+
+### 步骤 9：输出进度
+
+```
+计划完成：T1 <goal> / T2 <goal> / ...（共 N 个任务）
+工作区就绪：branch=<branch>, initial_base=<base7>（doc_dir=<doc_dir>）
+```
+
+## 并发规则
+
+| 任务类型 | 并发 | 条件 |
+|---------|------|------|
+| 只读调研（readonly=true） | **必须并行 ≤5** | 无写冲突；多个独立调研不得串行 |
+| 可写实现（readonly=false） | 必须串行 | 上一任务 review close 后才派下一个 |
+| Review | 与下一个可写实现串行 | 并行会污染 HEAD，使 review diff 范围漂移 |
+
+**串行纪律**：下一个可写任务的 base = 上一任务的 HEAD。
+
+## 约束
+
+- 不读写代码、不跑验证、不派发实现 subagent，只产出：产物目录 + Ledger + plan.md + todowrite 清单
+- **MUST**：需探索代码库才能拆分时派 `explore` 调研（步骤 4），绝不自己读源码
+- 短 SHA 一律取 7 位

package/skills/todo-recovery/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: todo-recovery
+description: 恢复与护栏：崩溃/compaction 恢复、重规划（≤3 轮）、退出条件、预算与超时、中断与回滚、防失控护栏。运行期遇上下文丢失、计划级失败、超时、中断、需回滚时加载。
+license: MIT
+metadata:
+  workflow: on-demand
+---
+
+# todo-recovery 技能
+
+## 触发场景
+
+- compaction / 会话重启 / 上下文丢失 → 步骤 0 恢复
+- 计划级失败（多任务失败 / 反复失败 / 依赖断裂）→ 步骤 1 重规划
+- 判定退出（target 验收 / 重规划超限 / 阻塞 / 预算超限 / ESCALATE）→ 步骤 2 退出条件
+- 单任务超时 / 总预算护栏触顶 → 步骤 3 预算与超时
+- 用户中断 / 需回滚 / forbidden 文件被改 → 步骤 4 中断与回滚
+- 防失控周期自检 → 步骤 5 护栏
+
+## 输入
+
+| 字段 | 说明 | 默认 |
+|------|------|------|
+| `target` | 用户目标 | 必填 |
+| `root_dir` | 工程根目录 | 当前工作目录 |
+| `doc_dir` | 产物目录 | 必填 |
+| `run_id` | run id（重规划复用） | 必填 |
+| `initial_base` | 本次运行最初的 base（回滚绝不 reset 早于它） | 必填 |
+| `constraints` | 全局禁改/禁操作清单 | 无 |
+
+## 工作流程
+
+### 0. 恢复（compaction / 崩溃 / 上下文丢失后）
+
+compaction、会话重启、或任何上下文丢失后，按本 SOP **无损续跑**：不重做已完成任务、不丢未提交改动、不误判在途任务。
+
+1. **定位 doc_dir**：优先读 Ledger `doc_dir=` 绝对路径；读不到则退化 `<root_dir>/.webwork/todo/` 下时间戳最新目录。
+2. **读 Ledger + plan.md**：Ledger 首行元数据（`target`/`doc_dir`/`branch`/`initial_base`）+ 全部任务条目 + `plan.md` 任务清单。
+3. **工作树校验**（`git status --porcelain`）：
+   - 干净 → 继续。
+   - 脏 → 判归属：脏文件落在「最近进行中任务」的 writable 白名单内 → 自动 `git add -A && git commit -m "resume: residual changes"`（不丢改动）；超出白名单 → `git checkout -- <file>` 丢弃并记 Ruling。
+   - **绝不 `reset --hard`**（会连同未提交改动一起丢）。
+4. **推断当前任务状态**（Ledger 与 `git log`/`git status` 交叉验证，**信任 git 胜过记忆**）：
+   - 已 `complete` 的任务不改不动。
+   - 找 Ledger 最后一个有 `base=` 但无 `complete` 的任务 = 当前进行中。
+   - `git log <base>..HEAD` 有 commit 且无 review 结论 → 已实现，生成 review package 进入 todo-review。
+   - 无 commit 且工作树干净 → 无产出，重新派发该任务。
+   - 全部任务 `complete` → 进入 todo-finalize。
+5. **todowrite 重建清单**：全量替换，已完成 `completed`、当前任务 `in_progress`。
+6. **继续主循环派发**，**绝不直接实现**——从推断出的状态点续跑，不从头重做。
+
+### 1. 重规划
+
+#### 触发条件（3 种）
+
+1. 多任务失败（≥2 个任务 BLOCKED 且无法通过换模型/拆任务解决）
+2. 某任务反复失败（fix loop 5 轮 + Breaker STOP）
+3. 计划自审结构性冲突在实现后成真（任务间依赖断裂）
+
+#### 规则
+
+- **复用同一 `run_id`/`doc_dir`/Ledger**——不新开 run
+- **增量调整**——只对未完成目标重新拆分，已完成任务保留标记 done 不重派发
+- 更新 `plan.md`，`todowrite` 重建清单（全量替换，仅未完成 + 新拆分的任务）
+- Ledger 记 `replan round <R>/3`
+- **最多 3 轮**，超限升级用户不再自动继续
+
+#### 重规划流程
+
+```
+1. 读 Ledger 确认已完成任务（T<N>: complete 的不重派发）
+2. 读 plan.md + 已有 explore 报告确认未完成任务及拆分依据
+3. 对未完成目标重新拆分（遵循 todo-plan 的拆分规则）
+4. 重新拆分若需探索代码库（已有报告不足）→ 派只读 explore subagent（遵循 todo-plan 步骤 4：只读、不提交、附 file:line 证据）
+5. 更新 plan.md（追加新任务，标记旧任务为 superseded）
+6. todowrite 重建清单（全量替换）
+7. Ledger 记 replan round <R>/3
+8. 继续主循环派发
+```
+
+### 2. 退出条件（5 种）
+
+| 条件 | 动作 |
+|------|------|
+| target 验收通过 | 正常交付（todo-finalize） |
+| 重规划 ≤3 轮仍失败 | 停止，报告用户：已尝试 N 轮重规划，以下任务仍无法完成 |
+| 阻塞无法解除（含与 constraints 不可调和） | 停止，报告用户：阻塞原因 + 已尝试方案 |
+| 总预算超限（见下） | 停止，报告用户：预算超限详情 |
+| subagent ESCALATE 且无法通过拆分/换模型解决 | 停止，报告用户：升级原因 |
+
+退出时 Ledger 记最终状态，向用户输出：
+```
+任务未完成，已停止。
+
+已完成: T1, T2 (review clean)
+未完成: T3 (BLOCKED: <reason>), T4 (not started)
+
+Rulings I made:
+<裁决清单>
+
+建议下一步: <建议>
+```
+
+### 3. 预算与超时
+
+#### 单任务超时
+
+- prompt 软上限：只读调研 ≤30 次工具调用，可写实现 ≤50，fix ≤20，reviewer ≤15
+- 超时立即记 Ledger `T<N>: timeout`，标 BLOCKED/ESCALATE
+- 不无限同步等待
+
+#### 等待纪律（有界等待）
+
+- background 模式下主 agent 不阻塞
+- 派发后继续做本地工作（写 Ledger、准备下一个 review package、读已返回的报告）
+- 收到 subagent 完成通知后处理返回
+- subagent 异常长时间未返回（超过该任务预算对应的 2 倍时长，或绝对上限 10 分钟，取先到者）→ 记 Ledger `T<N>: timeout` 并标 BLOCKED/ESCALATE
+
+#### 总预算护栏（3 项）
+
+| 护栏 | 上限 | 超限动作 |
+|------|------|---------|
+| 总任务数 | ≤20 | 记 Ledger，报告用户，停止派发 |
+| 总运行时长 | ≤30 分钟 | 记 Ledger，报告用户，停止派发 |
+| 最大并行 | ≤5（只读） | 记 Ledger，等待在途返回 |
+
+每项超限如实写进 Ledger 并报告，不静默续跑。
+
+### 4. 中断与回滚
+
+#### 用户中断
+
+- 立即停止派发 + cancel 在途 subagent
+- 记 Ledger `T<N>: interrupted by user`
+- 保留现场，不删除产物目录
+- 向用户输出当前进度
+
+#### 回滚规则
+
+- **回滚仅限本任务 `base..HEAD`**（base 从 Ledger `T<N>: base=` 读取）
+- 工作树脏时禁 `git reset --hard`，改用 `git revert` 或 `git reset --soft` + 手动 checkout
+- forbidden 文件被改 → 强制 `git checkout -- <file>` 恢复
+- **绝不 `reset` 到早于 `initial_base`**
+
+```
+回滚步骤:
+1. 读 Ledger T<N>: base=<base>
+2. git revert <base>..HEAD  (或 git reset --soft <base> + git checkout -- .)
+3. forbidden 文件: git checkout -- <forbidden_file>
+4. 记 Ledger T<N>: reverted to <base>
+5. 重新规划该任务（拆分/换模型/调整方案）
+```
+
+### 5. 防失控护栏（5 条）
+
+| # | 护栏 | 检查 |
+|---|------|------|
+| 1 | 并发分型 | 只读任务可并行 ≤5；可写任务必须串行；下一个可写 base = 上一 HEAD |
+| 2 | task 预算 | 每个 task ≤10 分钟；失败先换模型/拆任务再重规划 |
+| 3 | scoped re-review | 每轮 fix 后必须 scoped re-review，不跳过 |
+| 4 | Round 5 后才裁决 | Breaker 绝不在 Round 5 前提前裁决；每条裁决都是 Ledger 条目，禁止静默丢弃 |
+| 5 | 外部信息 | 需要外部信息用 `explore` 调研，不嵌套再派发 |
+
+## 输出
+
+- Ledger 条目（`replan round <R>/3` / `T<N>: timeout` / `T<N>: interrupted` / `T<N>: reverted to <sha>` / 总预算超限记录）
+- 更新后的 `plan.md`（重规划时）
+- 不派发实现/任务 subagent（重规划后的派发由主流程按新 plan.md 进行）；重新拆分若需探索代码库，按 todo-plan 步骤 4 派只读 explore subagent
+- 不 push / 不 merge / 不 reset 早于 initial_base
+
+## 约束
+
+- 重规划复用同一 run，是增量调整，不重做已完成任务
+- 退出条件 5 种，命中即停止并如实报告
+- 单任务超时不无限等待
+- 总预算护栏 3 项超限即停
+- 用户中断保留现场
+- 回滚仅限本任务范围，绝不 reset 早于 initial_base
+- 防失控护栏 5 条周期自检

package/skills/todo-review/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: todo-review
+description: 审查与修复阶段：生成 review package、派发 reviewer（Spec+Quality 两阶段）、处理结论、fix loop（≤5 轮）+ scoped re-review、Breaker 裁决。implementer 返回 DONE/DONE_WITH_CONCERNS 后加载。
+license: MIT
+metadata:
+  workflow: sequential
+---
+
+# todo-review 技能
+
+## 输入
+
+| 输入 | 说明 |
+|------|------|
+| `doc_dir` | 产物目录绝对路径 |
+| `task_id` (`T<N>`) | 当前任务编号 |
+| `base` | Ledger 中该任务的 `base=` 值 |
+| `HEAD` | 当前 HEAD |
+| `brief_file` | `<doc_dir>/task-<N>-brief.md` |
+| `report_file` | `<doc_dir>/task-<N>-report.md` |
+
+## 工作流程
+
+### 步骤 1：生成 review package
+
+```bash
+# 生成 diff 包（commits + stat + full diff with 10 lines context）
+diff_file="<doc_dir>/task-<N>-review-<base7>..<head7>.diff"
+git log --oneline <base>..<HEAD> > "$diff_file"
+echo "" >> "$diff_file"
+git diff --stat <base>..<HEAD> >> "$diff_file"
+echo "" >> "$diff_file"
+git diff -U10 <base>..<HEAD> >> "$diff_file"
+```
+
+写入 Ledger：`T<N>: reviewed_head=<HEAD7>`
+
+### 步骤 2：派发 reviewer（串行：一个任务一个 reviewer）
+
+一次任务级审查 = 一个 reviewer subagent，不并行拆分（多个 reviewer 重复读同一 diff，无并行收益）。用 `task` 工具派发，`subagent_type: "general"`，`background: true`。
+
+#### Reviewer prompt 模板
+
+```
+你是审查 subagent，审查一个任务的实现。这是任务级审查，不是合并审查。
+
+## What Was Requested
+Read the task brief: <brief_file>
+
+Global constraints: <constraints>
+
+## What the Implementer Claims
+Read the implementer's report: <report_file>
+
+## Diff Under Review
+Base: <base>
+Head: <HEAD>
+Diff file: <diff_file>
+
+Read the diff file once — it contains the commit list, stat summary, and full diff
+with context. Do not re-run git commands. Do not crawl the broader codebase.
+
+Your review is read-only. Do not mutate the working tree, index, HEAD, or branch.
+
+## You Do Not Dispatch Subagents
+Do all review yourself. Never spawn a subagent.
+
+## Do Not Trust the Report
+Treat the implementer's report as unverified claims. Verify against the diff.
+
+## Tests
+The implementer already ran tests. Do not re-run the suite. Run a focused test only
+when reading the code raises a specific doubt.
+
+## Part 1: Spec Compliance
+- Missing: requirements skipped or claimed without implementing
+- Extra: features not requested, over-engineering
+- Misunderstood: right feature built the wrong way
+
+## Part 2: Code Quality
+- Clean separation of concerns?
+- Proper error handling?
+- DRY without premature abstraction?
+- Edge cases handled?
+- Tests verify real behavior, not mocks?
+
+## Output Format
+Write your review to <review_file> (<doc_dir>/task-<N>-review.md):
+
+### Spec Compliance
+- ✅ Spec compliant | ❌ Issues found: [what's missing/extra/misunderstood, with file:line]
+
+### Strengths
+[What's well done? Be specific.]
+
+### Issues
+#### Critical (Must Fix)
+#### Important (Should Fix)
+#### Minor (Nice to Have)
+For each issue: file:line, what's wrong, why it matters, how to fix.
+
+### Assessment
+**Task quality:** Approved | Needs fixes
+**Reasoning:** [1-2 sentence technical assessment]
+
+Then report back with ONLY (≤15 lines):
+- Spec: ✅/❌
+- Quality: Approved/Needs fixes
+- Finding count (Critical/Important/Minor)
+- One-line summary
+- Review file path
+```
+
+### 步骤 3：处理结论
+
+读取 `<doc_dir>/task-<N>-review.md`，按结论分派：
+
+| 结论 | 动作 |
+|------|------|
+| ✅ Spec + Approved | 任务完成，写 Ledger `T<N>: complete (commits <base7>..<head7>, review clean)`，勾单 |
+| ❌ 或有 Critical/Important | 进入 fix loop |
+| ⚠️ Cannot verify | 主 agent 不得读源码核实——派只读 verify subagent 运行聚焦验证，据报告裁决（详见下） |
+| Minor only | 记录 Ledger `T<N>: minor (deferred): <one-liner>`，任务完成，勾单 |
+| Plan-mandated | 主 agent 裁决：weigh finding against plan text，record `Ruling: <决定> — <原因> — <代价>`，不打断流程 |
+
+**⚠️ Cannot verify 的处理**：reviewer 无法只凭 diff 判断某点时，主 agent **绝不自己读源码 / 跑测试核实**。派发一个只读 verify subagent（`subagent_type: "general"`，`background=true`），prompt 约束：只运行 reviewer 指出的聚焦验证命令（focused test / 单条命令），只读相关文件 + 附 file:line 证据，不提交、不改工作树、不嵌套派发。据其报告裁决：
+- 聚焦验证 PASS → 记录 `Ruling: <点> 验证通过 — 聚焦测试 PASS — cost if wrong low`，任务完成，勾单
+- 聚焦验证 FAIL → 视为 spec ❌，进入 fix loop
+- 仍无法判定（需环境/需 implementer 补证据）→ 视为 spec ❌，退回 implementer 补证据后重审
+
+**勾单语义**：`todowrite` 全量替换整个清单——当前任务标 `completed`（下一个任务的 `in_progress` 由 todo-dispatch 派发时统一标记）。绝不只改一项。
+
+### 步骤 4：Fix Loop（如触发）
+
+最多 5 轮，每轮 = 一次 fix dispatch + 一次 scoped re-review。
+
+#### 轮次策略
+
+| 轮次 | Implementer | 理由 |
+|------|-------------|------|
+| 1-3 | 恢复原 implementer（context 完整） | 它知道任务、代码、自己的选择 |
+| 4-5 | 新 implementer + 更详细 brief | fresh eyes，原 implementer 可能看不到自己的问题 |
+
+#### 每轮流程
+
+1. **Fix dispatch（串行）**：派发 fix implementer（`general`, `background=true`）——一个 fix subagent 修本轮全部 findings（findings 常共享文件，并行修复会冲突）。prompt 包含：
+   - brief_file 路径
+   - report_file 路径（fix 报告 append 到同一文件）
+   - open findings（逐条列出）
+   - "Fix these findings, re-run covering tests, append fix report to <report_file>"
+
+2. **生成 scoped review package**：
+   ```bash
+   fix_base=<上一轮 reviewed_head>
+   scope_diff="<doc_dir>/task-<N>-rereview-<R>-<fix_base7>..<head7>.diff"
+   git log --oneline <fix_base>..<HEAD> > "$scope_diff"
+   git diff --stat <fix_base>..<HEAD> >> "$scope_diff"
+   git diff -U10 <fix_base>..<HEAD> >> "$scope_diff"
+   ```
+
+3. **Scoped re-review**：派发 re-reviewer（`general`, `background=true`），prompt 包含：
+   - brief_file 路径
+   - findings 列表
+   - report_file 路径
+   - scope_diff 路径
+   - "Verdict each finding: ADDRESSED / NOT ADDRESSED. Check fix diff for new breakage only."
+
+4. **写 Ledger**：
+   ```
+   T<N>: fix round <R>/5 (<X> addressed, <Y> open — <finding one-liners>; commits <base7>..<head7>)
+   ```
+
+5. **判断**：
+   - 全部 ADDRESSED + 无新 Critical/Important → 任务完成，勾单
+   - 有 open findings 且 R < 5 → 下一轮
+   - 有 open findings 且 R = 5 → Breaker
+
+#### Re-reviewer prompt 模板
+
+```
+你是 scoped re-review subagent。验证上一轮 review 的 findings 是否已解决，检查 fix diff 是否引入新问题。
+
+## The Task
+Read the task brief: <brief_file>
+
+## The Findings Under Verification
+<findings — 逐条列出>
+
+## The Fix
+Read the implementer's report (fix reports appended at end): <report_file>
+
+Fix base: <fix_base>
+Head: <HEAD>
+Diff file: <scope_diff>
+
+Read the diff file once. Do not re-run git commands. Read-only review.
+
+## Scope
+Your scope is the findings list and the fix diff. Verdict every finding.
+Inspect the fix diff for new problems only. Do NOT re-review code the fix did not touch.
+Out-of-scope observations → report as non-blocking, do not extend the loop.
+
+## You Do Not Dispatch Subagents
+
+## Output Format
+Write your re-review to <rereview_file> (<doc_dir>/task-<N>-rereview-<R>.md):
+
+### Finding Verdicts
+For each finding, in order:
+- **<finding one-liner>** — ADDRESSED | NOT ADDRESSED, with file:line evidence
+
+### New Breakage in the Fix Diff
+Anything the fix broke. "None" if clean.
+
+### Out-of-Scope Observations
+Non-blocking. "None" if none.
+
+### Verdict
+**Fix round:** All findings addressed, no new Critical/Important breakage | Findings remain open — list them
+
+Then report back with ONLY (≤10 lines):
+- Verdict: All addressed | <N> open
+- New breakage: None | <count>
+- Re-review file path
+```
+
+### 步骤 5：Breaker（Round 5 仍有 open findings）
+
+**绝不**在 Round 5 前提前裁决。只有 Round 5 re-review 仍有 open findings 时才触发。
+
+主 agent 裁决每条 open finding：
+
+| 情况 | 裁决 | Ledger 记录 |
+|------|------|------------|
+| reviewer 错误/可争议 | park with ruling | `T<N>: parked — <finding> — Ruling: <why code stands>` |
+| 真问题但不 load-bearing | park with ruling | `T<N>: parked — <finding> — Ruling: real but deferred` |
+| 真问题且 load-bearing | 最小修复裁决 | `T<N>: Ruling: <finding> — <what you decided> — <cost if wrong>` |
+| 每条路都是猜测 | STOP | `T<N>: BLOCKED — <reason>` |
+
+裁决后：
+- 全部 parked → 任务完成，勾单
+- 有 load-bearing ruling → 继续执行裁决的修复
+- STOP → 加载 todo-recovery
+
+## 输出
+
+- `<doc_dir>/task-<N>-review-<base7>..<head7>.diff`（review package）
+- `<doc_dir>/task-<N>-review.md`（reviewer 报告）
+- fix loop 期间：scoped diff + `<doc_dir>/task-<N>-rereview-<R>.md`
+- Ledger 条目：`T<N>: reviewed_head=` / `T<N>: complete` / `T<N>: fix round <R>/5` / `T<N>: minor (deferred)` / `T<N>: parked` / `Ruling:`
+
+## 约束
+
+- reviewer/re-reviewer 只读约束写在 prompt 里，不得改源码、不得 add/commit
+- reviewer 不重跑测试：信任 implementer 报告的测试结果
+- fix prompt **内联 open findings（verbatim）+ 引用 review 文件路径**（implementer 需更多上下文时自读完整 review），与 superpowers 一致
+- fix 轮次硬上限 5 轮；Breaker 绝不在 Round 5 前提前裁决
+- 主 agent 不自己 fix findings——controller fixes skip review
+- 只审查与 fix，不规划、不派发初次 implementer

package/skills/work-dispatch/SKILL.md

@@ -39,6 +39,7 @@ work agent 完成第三步「产物目录与 Ledger」、并已通过 work-plan
 
 - `references/prepare.md` → 4.1 准备（BASE 记录、Ledger 写 base+session、brief 渲染、report 路径指定）
 - `references/dispatch-prompt.md` → 4.2 派发 prompt 模板（自包含结构 + 执行边界 50 次 + 防循环 + 自审 + 报告格式）与「禁止」清单
+- `references/explore-prompt.md` → 只读调研 prompt 模板（explore 专属，执行边界 30 次 + 只读约束 + 报告格式）
 - `references/report-handling.md` → 4.3 status 处理表 + 异常返回表 + 重试上限 1 次 + background 派发与串行衔接
 
 ### 阶段 2：派发前准备
@@ -47,7 +48,18 @@ work agent 完成第三步「产物目录与 Ledger」、并已通过 work-plan
 
 ### 阶段 3：派发 implementer
 
-按 `references/dispatch-prompt.md` 渲染自包含 prompt（所有占位符展开为绝对路径），用 `task` 工具派发，`subagent_type` 取 `explore`（只读）或 `general`（可写）。写 Ledger `T<N>: session=<session_ref>`。
+按 `references/dispatch-prompt.md` 渲染自包含 prompt（所有占位符展开为绝对路径），用 `task` 工具派发，`subagent_type` 取 `work-explore`（只读）或 `work-general`（可写）。写 Ledger `T<N>: session=<session_ref>`。
+
+### 阶段 3a：并行派发 explore（可选）
+
+当 plan.md 中存在多个可并行的 `work-explore`（只读）任务时，按以下流程批量派发：
+
+1. **识别可并行任务**：从 plan.md 中筛选出当前轮次可同时执行的 explore 任务（无依赖或依赖已满足）。
+2. **批量派发 ≤5**：在同一条消息中发出多个 `task` 调用，`subagent_type=work-explore`，`background=true`，每个使用 `references/explore-prompt.md` 模板渲染 prompt。写 Ledger `T<N>: session=<session_ref>`（每个任务各写一行）。
+3. **等待全部返回**：所有 explore 任务返回后再逐个处理，不边收边派。
+4. **逐个处理返回**：对每个 explore 返回按 `references/report-handling.md` 写 Ledger 状态行并分派动作。
+
+> general 任务仍保持串行：派发后等 review close 才派下一个 general，不与 explore 混合并行。
 
 ### 阶段 4：处理返回
 
@@ -65,7 +77,7 @@ implementer 返回后立即按 `references/report-handling.md` 写 Ledger 状态
 - prompt 必须自包含：subagent 看不到主 agent 历史，所有占位符（`<BRIEF_FILE>`/`<REPORT_FILE>`/`<doc_dir>/...` 等）一律展开为绝对路径。
 - 派发前禁止：粘贴计划全文到 prompt、粘贴之前任务摘要到后续 prompt、让 subagent 读整个计划文件、在 prompt 中重复 brief 的 accept/verify。
 - 异常处理纪律：绝不忽略升级或强制同一模型无变化重试；空输出/无 status 最多重试 1 次，再失败按 BLOCKED 处理。
-- 串行硬规则：下一个 `general` 必须在上一任务 review close 后才派发，且 `BASE` 自动等于上一任务 `HEAD`；`explore` 可并行且 ≤5 个/轮。
+- 串行硬规则：下一个 `work-general` 必须在上一任务 review close 后才派发，且 `BASE` 自动等于上一任务 `HEAD`；`work-explore` 可并行且 ≤5 个/轮。
 - 本技能只派发与处理返回，不审查、不 fix、不改源码。
 
 ## 资源目录
@@ -74,5 +86,6 @@ implementer 返回后立即按 `references/report-handling.md` 写 Ledger 状态
 references/
 ├── prepare.md          # 4.1 准备（BASE/Ledger/brief/report 路径）
 ├── dispatch-prompt.md  # 4.2 派发 prompt 模板 + 禁止清单
+├── explore-prompt.md   # 只读调研 prompt 模板（explore 专属）
 └── report-handling.md  # 4.3 status 表 + 异常表 + 重试上限 + 串行衔接
 ```

package/skills/work-dispatch/references/dispatch-prompt.md

@@ -1,6 +1,8 @@
 # 4.2 派发 prompt 模板
 
-使用 `task` 工具，`subagent_type` 取 `explore`（只读）或 `general`（可写）。
+使用 `task` 工具，`subagent_type` 取 `work-explore`（只读）或 `work-general`（可写）。
+
+- **所有 task 派发必须传 `background=true`**：subagent 异步运行，主 agent 不阻塞，完成时自动通知。这是防止主 agent 卡死的硬性约束。
 
 ## 自包含原则
 
@@ -85,3 +87,10 @@ brief 是你的唯一需求来源——不要假设 brief 之外的任何上下
 - 粘贴之前任务的摘要到后续任务的 prompt
 - 让 subagent 读整个计划文件
 - 在 prompt 中重复 brief 的 accept/verify（implementer 自己读 brief）
+
+## 并行派发
+
+- **explore 任务可同轮批量派发（≤5）**：当存在多个可并行的只读调研任务时，在同一条消息中发出多个 `task` 调用，`subagent_type=work-explore`，`background=true`，每个使用 `references/explore-prompt.md` 模板渲染 prompt。
+- **general 任务必须串行**：使用本文件（dispatch-prompt.md）模板，派发后等 review close 才派下一个 general。
+- **批量派发 explore 时**：同一条消息发出多个 task 调用，全部 `background=true`；等待全部 explore 返回后再逐个处理返回，不边收边派。
+- **explore 与 general 衔接**：所有 explore 返回并处理完毕后，再进入 general 串行链。