@wwkit/harness 1.0.15 → 1.0.16

package/skills/work-plan/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: work-plan
+description: |
+  [work 专属 runbook] 仅供 work agent 通过 skill 工具显式调用（name=work-plan），其他 agent / 普通对话禁止触发
+  规划阶段技能：按 1.1 任务拆分把 target 拆成 ≤10 分钟、可布尔验收的任务，按 2.1 填写 11 字段任务计划，
+  按 2.2 写入 plan.md，按 2.3 自审（范围闸门 + 8 项），核对 2.4 并发硬规则（explore ≤5 并行 / general 串行 / BASE=上一 HEAD）。
+  适用：work agent 第一步规划到派发前的「规划 → 落单」环节。
+  不适用：执行/派发/审查/产物目录与 Ledger（用 work-ledger）；非 work 流程的普通规划。
+license: MIT
+metadata:
+  workflow: sequential
+---
+
+# work-plan 技能
+
+## 触发时机
+
+work agent 完成第一步解析用户输入（`target`/`root_dir`/`constraints` 三字段）后、派发任何 subagent 前加载本技能，执行「任务拆分 → 字段填写 → plan.md 落盘 → 计划自审」。
+
+## 输入
+
+从 work.md 流程传入三个贯穿全程的字段：
+
+| 字段 | 说明 | 默认 |
+|------|------|------|
+| `target` | 要达成的目标（定义验收标准，第五步按它判定成败） | 必填 |
+| `root_dir` | 工程根目录（所有任务路径、`writable`/`forbidden`、prompt 内路径、bash 命令的基准） | 当前工作目录 |
+| `constraints` | 约束（不改的文件、禁止的操作等；展开为全局禁改/禁操作清单，每个任务的 `forbidden` 至少包含它的全部内容） | 无 |
+| `doc_dir` | 产物目录绝对路径（来自 work-ledger，`plan.md` 写入其下） | 必填 |
+
+## 工作流程
+
+### 阶段 1：加载 references
+
+用 `read` 工具加载本技能 `references/` 下的全部流程文件（相对路径基于本 skill 目录）：
+
+- `references/split-rules.md` → 1.1 任务拆分规则（第一约束、拆分维度、3 个反模式、不需要拆分的情况）
+- `references/task-fields.md` → 2.1 任务 11 字段 + agent 类型选择 + 2.4 并发硬性规则
+- `references/plan-file.md` → 2.2 plan.md 持久化格式
+- `references/self-review.md` → 2.3 计划自审（范围闸门 + 8 项）
+
+### 阶段 2：任务拆分
+
+按 `references/split-rules.md` 的规则，把 `target` 拆成任务列表（可能仅 1 个任务）。
+
+### 阶段 3：填写任务字段
+
+按 `references/task-fields.md` 为每个任务填写全部 11 个字段：
+`task_id`/`goal`/`files`/`interfaces`/`accept`/`verify`/`agent`/`writable`/`forbidden`/`depends`/`budget`。`agent` 类型与并发安排按同一文件的规则与 2.4 硬性规则确定。
+
+### 阶段 4：写 plan.md
+
+按 `references/plan-file.md` 的模板，将完整计划写入 `<doc_dir>/plan.md`（`doc_dir` 的确定见 work-ledger skill）。
+
+### 阶段 5：计划自审
+
+按 `references/self-review.md` 先查范围闸门（任务数 >20 暂停向用户确认），再逐项自检 8 项；任何一项不通过则修正计划后再进入派发。
+
+## 输出
+
+- 完整任务计划（写入 `<doc_dir>/plan.md`，compaction 后恢复用）
+- 每个任务的 11 字段已确定，可供派发 implementer / reviewer 使用
+- 本技能**不派发、不执行、不写任务 brief**（派发与 Ledger 属 work agent 流程的其他环节）
+
+## 约束
+
+- 拆分第一约束：每个任务 ≤10 分钟可完成，且能独立写出可布尔判定的 `accept`；超预算必须继续拆，宁可多小任务串行。
+- 反模式禁止：按 TDD 步骤拆 / 按文件数硬拆 / 一个任务塞多个不相关目标。
+- 并发硬规则：`explore`（只读）可并行且 ≤5 个/轮；`general`（可写）必须串行，须在上一任务 review close 后才派发下一个；下一个 `general` 的 `BASE` 自动等于上一任务 `HEAD`。
+- 范围闸门：任务数 >20 或 `target` 无法在 ≤20 个独立验收单元内覆盖 → 暂停规划，向用户确认拆分范围。
+- 本技能不读写代码、不执行验证命令，只产出计划与 plan.md。
+
+## 资源目录
+
+```
+references/
+├── split-rules.md   # 1.1 任务拆分（第一约束/维度/反模式/不需拆分）
+├── task-fields.md   # 2.1 任务 11 字段 + 1.2 agent 类型选择 + 2.4 并发硬规则
+├── plan-file.md     # 2.2 plan.md 持久化格式
+└── self-review.md   # 2.3 计划自审（范围闸门 + 8 项）
+```

package/skills/work-plan/references/plan-file.md

@@ -0,0 +1,29 @@
+# 2.2 计划文件持久化（提取自 docs/plans/work-copy.md L154-176）
+
+规划完成后，将完整计划写入 `<doc_dir>/plan.md`（`doc_dir` 见 work-ledger 第三步，即 `<root_dir>/.webwork/harness/work/<session_id>/`）。
+
+## plan.md 格式
+
+```markdown
+# Plan — target: <target>
+## Global Constraints
+<constraints 原文>
+## Tasks
+### T1: <goal>
+files: ...
+interfaces: ...
+accept: ...
+verify: ...
+agent: ...
+writable: ...
+forbidden: ...
+depends: ...
+budget: ...
+### T2: ...
+```
+
+结构要点：`# Plan — target: <target>` 标题 + `## Global Constraints`（constraints 原文）+ `## Tasks`（下挂 `### T<N>: <goal>` 及全部任务字段）。
+
+## 恢复约定
+
+compaction 后：先读 `plan.md` 恢复计划，再读 `progress.md` 恢复进度。

package/skills/work-plan/references/self-review.md

@@ -0,0 +1,18 @@
+# 2.3 计划自审（提取自 docs/plans/work-copy.md L178-191）
+
+## 范围闸门（先于逐项自检，人工确认点之一）
+
+若任务数 > 20，或 `target` 无法在 ≤20 个独立验收单元内覆盖 → **暂停规划**，向用户确认拆分范围（本次只做 A 部分，还是分批多次运行）。避免大 target 在规划期就写爆 plan、派出一堆任务，直到运行时总预算才触发。
+
+## 逐项自检（8 项）
+
+产出计划后逐项自检，**任何一项不通过则修正后再派发**：
+
+1. **Spec 覆盖**：`target` 的每个要求是否有任务覆盖？列出未覆盖的 gap 并补任务。
+2. **接口一致性**：跨任务的类型名、函数签名、属性名是否匹配？T1 Produces 的 `clearLayers()` 在 T3 中是否也叫 `clearLayers()` 而非 `clearFullLayers()`？
+3. **占位符扫描**：有无 "TBD"、"加错误处理"、"类似 T1"、"按需实现" 等模糊描述？有则补具体。
+4. **依赖完整性**：`depends` 引用的 `task_id` 是否存在？有无循环依赖？有依赖的任务是否串行？
+5. **文件所有权分区**：可写任务（`general`）强制串行，故无并发写冲突；只读任务（`explore`）不产生文件变更。此条仅用于校验 `files`/`writable` 不落在 `constraints` 禁改范围之内。
+6. **路径合规**：`writable`/`forbidden`/`files` 都落在 `root_dir` 内且不与 `constraints` 冲突。
+7. **验收可判定**：每条 `accept` 是否可布尔判定？`verify` 命令是否具体可执行？
+8. **工时约束**：每个任务的 `budget` 是否 ≤10 分钟？超过的必须继续拆。

package/skills/work-plan/references/split-rules.md

@@ -0,0 +1,23 @@
+# 1.1 任务拆分（提取自 docs/plans/work-copy.md L65-82）
+
+所有任务都必须经过规划→派发→review 流程，无论任务是 1 个还是多个。
+
+## 拆分第一约束
+
+每个任务必须在 10 分钟内可完成，且能独立写出可布尔判定的 `accept`。这是 subagent 的硬预算（implementer 最多 50 次工具调用）；超过预算的任务必须继续拆，直到每个子任务都在预算内。宁可拆成多个小任务串行，也不要留 1 个超出预算的任务。若平台支持 `maxSteps`，用它作为工具调用次数的硬兜底。
+
+## 拆分维度
+
+按可独立验收的单元拆。一个任务拆出来后，必须能独立写出 `accept` 验收标准，reviewer 能不依赖其他任务的结果就判断它是否完成。如果 accept 必须引用其他任务的中间产物，说明拆错了边界。
+
+## 拆分反模式（禁止）
+
+| 反模式 | 问题 |
+|--------|------|
+| 按 TDD 步骤拆（RED 一个任务、GREEN 一个任务） | TDD 是一个任务内的流程，拆开导致 RED 任务的测试代码无法独立验收 |
+| 按文件数硬拆（每个文件一个任务） | 一个验收单元可能跨多文件，强行按文件拆产生大量微依赖 |
+| 一个任务塞多个不相关目标 | subagent context 膨胀，focus 下降 |
+
+## 不需要拆分的情况
+
+- 单一验收单元，预计 ≤10 分钟，不可再分（派 1 个 subagent）。

package/skills/work-plan/references/task-fields.md

@@ -0,0 +1,44 @@
+# 2.1 任务字段（提取自 docs/plans/work-copy.md L133-151）
+
+产出任务计划，每项含全部 11 个字段：
+
+```
+task_id:      T1 / T2 / ...
+goal:         目标，≤1 句话，可验收（必须服务于 target 的验收标准）
+files:        Create: path/to/new.ts | Modify: path/to/existing.ts:120-145 | Touch: path/to/config.json
+              （路径相对 root_dir；为空 ⇒ 该任务不涉及文件改动）
+interfaces:   Consumes: funcA(x: string) → number（来自 T1，T2 需调用）
+              Produces: class Foo { bar(): void }（本任务产出，供后续任务使用）
+              （无跨任务接口依赖时填 无）
+accept:       验收标准，≤3 条，每条可布尔判定（如 "Foo.bar() 返回 true"、"npm test 通过"）
+verify:       验证命令（如 `npm test -- src/foo.test.ts`；无测试时填 `无`）
+agent:        explore（只读调研）| general（执行改动/多步）— 选择规则见下
+writable:     可写文件白名单（为空 ⇒ 该任务只读；路径相对 root_dir；须与 files 的 Create/Modify 一致）
+forbidden:    禁改文件清单（至少含 constraints 全部内容）
+depends:      依赖任务：T1, T3（必须先完成）| 无
+budget:       预计 ≤10 分钟
+```
+
+## 1.2 agent 类型选择（提取自 L84-100）
+
+| agent 类型 | 适用场景 | 工具权限 |
+|-----------|---------|---------|
+| `explore` | 只读调研：搜索代码、读取文件、理解结构、验证假设 | read/grep/glob（只读） |
+| `general` | 可写改动：编辑代码、执行命令、多步实现、写测试 | 全部工具 |
+
+**选择规则**：
+- 任务涉及任何文件创建/修改/删除 → `general`
+- 任务只读不改（调研、审查、验证） → `explore`
+- 不确定时按 `general`（权限更大不会卡住）
+
+**注意**：审查类 subagent 取 `general`（需写审查文件），以 prompt 强约束「只读源码 + 写白名单仅审查文件」；审查处于任务串行链上，天然满足串行。
+
+## 2.4 并发硬性规则（提取自 L193-200）
+
+- **并发分型（Git 隔离的核心约束）**：
+  - `explore`（只读）**绝不提交、绝不改写工作树/index/HEAD**，只做搜索/读取/理解；可并行，**≤ 5 个/轮**。
+  - `general`（可写）**必须串行**，同一轮最多 1 个在跑，且须在上一任务的 review close 后才派发下一个；下一个 general 的 `BASE` 自动等于上一任务的 `HEAD`，保证 `BASE..HEAD` 恰好是本任务自己的改动。
+- 凡任务可能产生任何文件或 git 变更，一律 `general`（从而落入串行）。
+- 串行还是并行由 `depends` 字段 + agent 类型共同决定：有依赖必须串行；无依赖但写操作同样串行；仅只读任务可并行。
+- 一个 subagent 对应一个可独立验收的任务，不把多个不相关目标塞给一个 subagent。
+- 状态如需跨轮保留，把状态写进 Ledger/文件，不要依赖子代理记忆。

package/skills/work-recovery/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: work-recovery
+description: |
+  [work 专属 runbook] 仅供 work agent 通过 skill 工具显式调用（name=work-recovery），其他 agent / 普通对话禁止触发
+  恢复与护栏技能：覆盖重规划（触发条件 3 种、规则=复用 session_id/增量调整/不重做已完成、上限 3 轮超限升级用户）+ 退出条件（target 验收/重规划≤3/阻塞/预算超限/ESCALATE）+ 预算与超时（单任务超时=平台 timeout 优先/否则 prompt 软上限+maxSteps 硬兜底、等待纪律有界等待不静默阻塞、总预算护栏 4 项≤20 任务/≤30 分钟/并行≤5）+ 中断与回滚（用户中断保留现场、回滚限本任务 BASE..HEAD/工作树脏禁--hard/forbidden 文件强制 checkout/绝不 reset 早于 initial_base）+ 防失控护栏 5 条。
+  适用：work agent 运行期遇到计划级失败 / 超时 / 中断 / 需回滚 / 防失控检查时加载。
+  不适用：单任务 review fix（用 work-review）；最终交付（用 work-finalize）；非 work 流程的普通恢复。
+license: MIT
+metadata:
+  workflow: on-demand
+---
+
+# work-recovery 技能
+
+## 触发时机
+
+work agent 运行期遇到以下任一情况时加载本技能对应阶段：
+
+- 计划级失败（多任务失败 / 某任务反复失败且换模型拆任务均无效 / 计划自审结构性冲突在实现后成真）→ 加载 `references/replan.md`
+- 判定退出（target 验收 / 重规划超限 / 阻塞 / 预算超限 / ESCALATE）→ 加载 `references/budget.md` 退出条件段
+- 单任务超时 / 等待 child / 总预算护栏检查 → 加载 `references/budget.md` 预算段
+- 用户中断 / implementer 提交有误需回滚 / forbidden 文件被改 → 加载 `references/rollback.md`
+- 防失控周期自检 → 加载 `references/rollback.md` 护栏段
+
+## 输入
+
+从 work.md 流程传入：
+
+| 字段 | 说明 | 默认 |
+|------|------|------|
+| `target` | 要达成的目标（退出条件按其验收标准判定） | 必填 |
+| `root_dir` | 工程根目录 | 当前工作目录 |
+| `doc_dir` | 本次 session 产物目录（Ledger / plan.md 所在） | 必填 |
+| `session_id` | 本次 session id（重规划复用，不新开） | 必填 |
+| `initial_base` | 本次运行最初的 base（回滚绝不 reset 早于它） | 必填 |
+| `constraints` | 全局禁改/禁操作清单（forbidden 文件判定基准） | 无 |
+
+## 工作流程
+
+### 阶段 1：加载 references
+
+用 `read` 工具按触发原因加载本技能 `references/` 下对应文件（相对路径基于本 skill 目录）：
+
+- `references/replan.md` → 重规划（触发条件 3 种、规则=复用 session_id/增量调整/不重做已完成、上限 3 轮超限升级用户）
+- `references/budget.md` → 退出条件（5 种）+ 预算与超时（单任务超时 / 等待纪律 / 总预算护栏 4 项）
+- `references/rollback.md` → 中断与回滚（用户中断 / 回滚规则 / forbidden 强制 checkout）+ 防失控护栏 5 条
+
+### 阶段 2：按触发分支执行
+
+- **重规划**：按 `references/replan.md` 复用同一 `session_id`/`doc_dir`/Ledger，只重走第二步对未完成目标重新拆分并更新 `plan.md`，已完成任务保留标记 done 不重派发；Ledger 记 `replan round <R>/3`；最多 3 轮，超限升级用户。
+- **退出判定**：按 `references/budget.md` 退出条件 5 种逐项检查，命中即停止派发并如实报告。
+- **预算与超时**：派发 subagent 时优先用平台 `timeout`/`cancel`/后台执行；不支持则用 prompt 软上限（implementer ≤50 / fix ≤20 / reviewer ≤15）+ `maxSteps` 硬兜底；等待期有界等待不静默阻塞；总预算护栏 4 项超限即停派发记 Ledger 报告用户。
+- **中断与回滚**：用户中断立即停派发 + cancel 在途 + 记 Ledger + 保留现场；回滚限本任务 `BASE..HEAD`（BASE 从 Ledger `T<N>: base=` 读取），工作树脏禁 `--hard` 改用 `git revert` 或 `git reset --soft` + 手动 checkout，forbidden 文件强制 `git checkout -- <file>`，绝不 reset 早于 `initial_base`。
+- **防失控自检**：按 `references/rollback.md` 护栏 5 条周期自检（并发分型 / task 预算 / scoped re-review / Round 5 后裁决 / 外部信息用 general+webfetch）。
+
+## 输出
+
+- Ledger 条目（`replan round <R>/3` / `T<N>: timeout` / `T<N>: interrupted by user ...` / `T<N>: reverted to <sha>` / `T<N>: reverted forbidden <file>` / 总预算超限记录）
+- 更新后的 `plan.md`（重规划时）
+- 本技能**不派发新 subagent**（重规划后的派发由 work agent 主流程按新 plan.md 进行）；**不 push / 不 merge / 不 reset 早于 initial_base**
+
+## 约束
+
+- 重规划复用同一 `session_id`/`doc_dir`/Ledger，是针对失败与未完成部分的增量调整，不重做已完成任务；最多 3 轮，超限升级用户不再自动继续。
+- 退出条件 5 种：target 验收通过 / 重规划 ≤3 轮 / 阻塞无法解除（含与 `constraints` 不可调和）/ 总预算超限 / subagent ESCALATE 且无法通过拆分任务/换模型解决。
+- 单任务超时：平台 `timeout`/`cancel` 优先（硬兜底），否则 prompt 软上限 + `maxSteps` 硬兜底叠加；超时立即记 Ledger `T<N>: timeout` 标 BLOCKED/ESCALATE，不无限同步等待。
+- 等待纪律：有界等待，不轮询短超时也不长时间静默；间隔（如 5 分钟）列一次在途 subagent 追查「已结束但仍未上报」的 child。
+- 总预算护栏 4 项：总任务数 ≤20 / 总运行时长 ≤30 分钟 / 总工具调用或 token 平台可观测时设上限 / 最大并行 explore ≤5；每项超限如实写进 Ledger 并报告，不静默续跑。
+- 用户中断保留现场，不删除产物目录。
+- 回滚仅限本任务 `BASE..HEAD`；工作树脏禁 `--hard`；forbidden 文件强制 `git checkout -- <file>` 恢复；**绝不 `reset` 到早于 `initial_base`**。
+- 防失控护栏 5 条：只读 explore 可并行 ≤5 / 可写 general 必须串行；每个 task ≤10 分钟，失败先换模型/拆任务再重规划；每轮 fix 后必须 scoped re-review；Round 5 后才裁决，每条裁决都是 Ledger 条目禁止静默丢弃；需要外部信息用 `general` + `webfetch` 调研不嵌套再派发。
+
+## 资源目录
+
+```
+references/
+├── replan.md     # 重规划（触发 3 种/规则/上限 3 轮）
+├── budget.md     # 退出条件 5 种 + 预算与超时（单任务超时/等待纪律/总预算护栏 4 项）
+└── rollback.md   # 中断与回滚（用户中断/回滚规则/forbidden 强制 checkout）+ 防失控护栏 5 条
+```

package/skills/work-recovery/references/budget.md

@@ -0,0 +1,40 @@
+# 退出条件
+
+- 对照 `target` 验收标准，所有任务 `done`、review 通过 **且整体验收通过**
+- 重规划 ≤3 轮（整体步骤用平台最大步数配置兜底，如 `maxSteps`）
+- 阻塞无法解除（含与 `constraints` 不可调和）
+- 总预算超限（见「预算与超时」）
+- subagent 返回 ESCALATE 且无法通过拆分任务/换模型解决 → 如实向用户报告
+
+# 预算与超时（总预算 + 单任务超时）
+
+## 单任务超时（技术强制优先）
+
+- 派发 subagent 时，若 `task` 工具支持 `timeout` / `cancel` / 后台执行，必须显式带超时；超时后主 agent 立即记 Ledger `T<N>: timeout` 并标记 `BLOCKED`/`ESCALATE`，**不无限同步等待**（避免主 agent TUI 卡死）。
+- 若平台不支持超时/取消，仍以 prompt 级硬约束（implementer ≤50 / fix ≤20 / reviewer ≤15 次工具调用）为软上限，并在派发后主动推进，不静默阻塞。
+- 二者关系：prompt 中的工具调用上限是**软约束**，平台能力（timeout / maxSteps）是**硬兜底**，叠加使用。
+
+## subagent 强制退出配置（实施细节）
+
+1. **`steps` 配置位置**：应配在 **subagent 定义**上（`agent.general.steps=50` / `agent.explore.steps=30`），不是 work agent 上——"卡住"的是 subagent（foreground 下 work 被 block），steps 达限强制结束的是被配置方。work 自身可加 `steps`（如 200）防 runaway，但次要。
+2. **background 模式启用**：在 opencode 配置中设 `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true`，task 工具的 `background=true` 参数才生效——subagent 异步运行，主 agent 不 block，完成时自动通知注入结果。
+3. **escape 中断语义**：TUI `session_interrupt`（escape）中断的是**整个 session**（含所有子 session），不是只中断子 session。中断后可通过 `git log` + Ledger 恢复续跑。
+
+## 等待纪律（不静默阻塞）
+
+- 派发后不停摆：等待期间继续做本地工作（写 Ledger、准备下一个 review package、读已返回的报告）。
+- 空闲等待用**有界等待**：不轮询短超时，也不长时间静默；间隔一段（如 5 分钟，若平台允许）列一次在途 subagent，追查「已结束但仍未上报」的——child 的结果可能丢失，而 timeout 抓不到这种「结果丢了」的失败。
+- 发现 child 卡死/丢失：按单任务超时处理，记 Ledger `T<N>: timeout` 并标 BLOCKED/ESCALATE。
+
+## 总预算护栏（防失控）
+
+主 agent 侧维护一份总预算，超限即停止派发、记 Ledger、报告用户：
+
+| 预算项 | 建议值 | 超限动作 |
+|--------|--------|---------|
+| 总任务数 | ≤ 20 | 规划期由 2.3 范围闸门拦截；运行时超限停止拆分，评估重规划或升级用户 |
+| 总运行时长 | ≤ 30 分钟 | 停止派发，记 Ledger，报告用户 |
+| 总工具调用 / token | 平台可观测时设上限 | 同上 |
+| 最大并行 explore | ≤ 5（见 2.4） | 等待，不超额派发 |
+
+每项超限都**如实写进 Ledger** 并报告，不静默续跑。

package/skills/work-recovery/references/replan.md

@@ -0,0 +1,21 @@
+# 重规划（计划级失败恢复）
+
+计划级失败时主 agent **自主重新规划**，只针对失败/未完成的目标，不打断用户、不重做已完成任务。
+
+## 触发
+
+单任务失败先走第四步的「换模型 / 拆任务」；当以下任一成立，进入重规划：
+
+- 一轮计划中多个任务失败，暴露计划本身的问题（任务边界 / 依赖 / 验收标准定义错误）；
+- 某任务反复失败，且「换模型 / 拆任务」均无效；
+- 计划自审（2.3）发现的结构性冲突在实现后成真。
+
+## 规则
+
+- 复用同一 `session_id` / `doc_dir` / Ledger：历史与已完成提交不丢；重规划是**针对失败与未完成部分的增量调整**。
+- 只重走第二步：重读 `target`，对未完成目标重新拆分，更新 `plan.md`；已完成任务条目保留并标记 done，不重新派发。
+- Ledger 记 `replan round <R>/3`（`<R>` = 第几轮）；重规划后照常走派发 → review → fix 循环。
+
+## 上限
+
+- 最多 3 轮重规划；超限 → 升级用户，如实报告，不再自动继续（见「退出条件」）。

package/skills/work-recovery/references/rollback.md

@@ -0,0 +1,20 @@
+# 中断与回滚
+
+## 用户中断
+
+- 收到用户中断后：立即停止派发新 subagent；对在途 subagent 发送 cancel（若平台支持 `cancel`）；记 Ledger `T<N>: interrupted by user (commits <base7>..<head7>, uncommitted: <files>)`。
+- **保留现场**：不删除产物目录，便于续跑或复盘。
+
+## 回滚
+
+- implementer 提交有误：回滚限定在本任务 `BASE..HEAD`（BASE 从 Ledger `T<N>: base=` 读取）。**若工作树干净**可用 `git reset --hard <BASE>`；**若工作树脏**（含起始检查中用户选择保留的脏文件），禁止 `--hard`（会连同脏文件一起丢弃），改用 `git revert <task commits>` 或 `git reset --soft <BASE>` + 手动 checkout 目标文件。回滚后在 Ledger 记 `T<N>: reverted to <sha>`。
+- **forbidden 文件被改**：reviewer 检测到 `writable` 白名单外的变更（含 `constraints` 禁改文件）→ 记 Critical finding，强制 `git checkout -- <file>` 恢复，并在 Ledger 记 `T<N>: reverted forbidden <file>`。
+- 回滚仅限本运行产生的提交，**绝不 `reset` 到早于 `initial_base`**。
+
+# 防失控护栏
+
+1. 并发分型：只读 `explore` 可并行 ≤5；可写 `general` 必须串行（同一轮最多 1 个），杜绝并发写冲突与 review diff 污染。
+2. 每个 task 预算 ≤10 分钟；worker 失败先换模型/拆任务重试，仍失败则重规划失败部分（见「重规划」）。
+3. 每轮 fix 后必须 scoped re-review，未审查的 fix 是回归的来源。
+4. Round 5 后才裁决，每条裁决都是 Ledger 条目，禁止静默丢弃。
+5. 需要外部信息时用 `general` + `webfetch` 调研，不在子代理里嵌套再派发。

package/skills/work-review/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: work-review
+description: |
+  [work 专属 runbook] 仅供 work agent 通过 skill 工具显式调用（name=work-review），其他 agent / 普通对话禁止触发
+  审查与修复阶段技能：5.1 生成 review package（Commits/Files changed/Diff 上下文 10 行 + 7 位短 SHA）；
+  5.2 派发 reviewer（两阶段 Spec Compliance+Code Quality、≤15 次、写白名单仅 REVIEW_FILE、不重跑测试）；
+  5.3 结论处理（✅+Approved→complete / ❌或有 Critical/Important→fix loop / ⚠️→主 agent 核查；Minor→deferred；Plan-mandated→主 agent 裁决 ruled 不打断）；
+  6.2 fix 轮次策略（1-3 复用 session，4-5 新 implementer，能力假设退化）；
+  6.3 scoped re-review（FIX_BASE=最后 reviewed_head、re-reviewer ≤10 次、写 rereview-<R>.md）；
+  6.4 Ledger 记录两条；6.5 异常分支状态机；6.6 Breaker（round 5 才裁决 park/STOP，绝不 round 5 前裁决）。
+  适用：work agent 第五步「Task Review」与第六步「Fix Loop」。
+  不适用：派发 implementer（用 work-dispatch）；规划（用 work-plan）；非 work 流程的普通审查。
+license: MIT
+metadata:
+  workflow: sequential
+---
+
+# work-review 技能
+
+## 触发时机
+
+work agent 完成第四步派发、implementer 返回 `DONE` 或 `DONE_WITH_CONCERNS` 后，进入第五步「Task Review」时加载本技能；review 报告 Spec ❌ 或有 Critical/Important finding 时进入第六步「Fix Loop」，沿用本技能至 review close 或 Breaker 裁决。
+
+## 输入
+
+从 work.md 流程传入：
+
+| 输入 | 说明 |
+|------|------|
+| `doc_dir` | 产物目录绝对路径（来自 work-ledger），review/diff/rereview 文件均写其下 |
+| `task_id` (`T<N>`) | 当前任务编号 |
+| `BASE` / `HEAD` | review package 的 diff 起止；`BASE` 取 Ledger 中该任务的 `base=` 值，`HEAD` = 当前 HEAD |
+| `BRIEF_FILE` | `<doc_dir>/task-<N>-brief.md`，reviewer/re-reviewer 读取验收标准 |
+| `REPORT_FILE` | `<doc_dir>/task-<N>-report.md`，reviewer 读取实现者声称 |
+| Ledger 句柄 | review/re-review 后写 `T<N>: reviewed_head=`/fix round 条目 |
+
+## 工作流程
+
+### 阶段 1：加载 references
+
+用 `read` 工具加载本技能 `references/` 下的全部流程文件（相对路径基于本 skill 目录）：
+
+- `references/review-package.md` → 5.1 生成 review package（三段结构 + 7 位短 SHA）
+- `references/reviewer-prompt.md` → 5.2 派发 reviewer（两阶段 prompt + 执行边界 ≤15 次 + 写白名单仅 REVIEW_FILE + 不重跑测试 + 报告格式）
+- `references/verdict-handling.md` → 5.3 Review 结论处理（✅/❌/⚠️ + Minor deferred + Plan-mandated ruled）
+- `references/fix-loop.md` → 6.2 fix 轮次策略 + 6.3 scoped re-review + 6.4 Ledger 记录 + 6.5 异常分支状态机
+- `references/breaker.md` → 6.6 Breaker（Round 5 仍有 open findings 时裁决 park/STOP）
+
+### 阶段 2：生成 review package
+
+按 `references/review-package.md`：取 Ledger 中该任务 `base=` 作为 `BASE`，`HEAD` = 当前 HEAD，写入 `<doc_dir>/task-<N>-review-<base7>..<head7>.diff`，内容含三段（Commits / Files changed / Diff 上下文 10 行）。
+
+### 阶段 3：派发 reviewer
+
+按 `references/reviewer-prompt.md` 渲染两阶段审查 prompt（Spec Compliance + Code Quality），用 `task` 工具派发，`subagent_type` 取 `general`（需写入 REVIEW_FILE）。reviewer 写入 `<doc_dir>/task-<N>-review.md`。
+
+### 阶段 4：处理结论
+
+按 `references/verdict-handling.md` 读取 `task-<N>-review.md` 分派：✅+Approved→complete；❌或有 Critical/Important→fix loop；⚠️→主 agent 核查；Minor→deferred；Plan-mandated→主 agent 裁决 ruled 不打断。
+
+### 阶段 5：Fix Loop（如触发）
+
+按 `references/fix-loop.md` 执行最多 5 轮 fix：每轮按轮次策略派发 fix implementer（1-3 复用 session，4-5 新 implementer），fix 后做 scoped re-review（`FIX_BASE` = 最后一条 `reviewed_head=`），写 Ledger 两条；异常分支按 6.5 状态机处理。
+
+### 阶段 6：Breaker（如 Round 5 仍有 open findings）
+
+按 `references/breaker.md`：停止派发，读 `task-<N>-rereview-5.md`，主 agent 裁决每条 open finding（park with ruling / STOP）。**绝不**在 Round 5 前提前裁决。
+
+## 输出
+
+- `<doc_dir>/task-<N>-review-<base7>..<head7>.diff`（review package）
+- `<doc_dir>/task-<N>-review.md`（reviewer 报告）
+- fix loop 期间：`<doc_dir>/task-<N>-review-<fix_base7>..<head7>.diff`（scoped package）、`<doc_dir>/task-<N>-rereview-<R>.md`（re-reviewer 报告）
+- Ledger 条目：`T<N>: reviewed_head=`、`T<N>: complete`、`T<N>: fix round <R>/5`、`T<N>: minor (deferred)`、`T<N>: ruled`、`T<N>: parked`、`T<N>: BLOCKED`
+- 本技能**不派发 implementer 初次执行**（属 work-dispatch），只派发 reviewer / fix implementer / re-reviewer
+
+## 约束
+
+- reviewer/re-reviewer 只读约束写在 prompt 里，不体现在工具权限：唯一允许的写操作是写入对应 REVIEW_FILE/REREVIEW_FILE，不得改源码、不得 add/commit、不得改工作树/index/HEAD/分支。
+- reviewer 不重跑测试：信任 Ledger 记录的测试结果。
+- fix prompt 引用 review 文件路径，不内联 findings——compaction 后 findings 可能丢失，文件不会。
+- fix 轮次硬上限 5 轮；Breaker 绝不在 Round 5 前提前裁决（6.5 即时 ESCALATE/BLOCKED 是技术与边界问题，不属「提前裁决 finding 正确性」）。
+- 能力假设退化：若平台不支持 session 续接，每轮新 implementer；若不支持模型切换，退化为「新 implementer + 更详细 brief」，不许静默失效。
+- 本技能只审查与 fix，不规划、不派发初次 implementer、不改源码。
+
+## 资源目录
+
+```
+references/
+├── review-package.md  # 5.1 review package 三段结构
+├── reviewer-prompt.md # 5.2 reviewer prompt 模板 + 执行边界 + 报告格式
+├── verdict-handling.md # 5.3 结论处理（✅/❌/⚠️/Minor/Plan-mandated）
+├── fix-loop.md        # 6.2 轮次策略 + 6.3 scoped re-review + 6.4 Ledger + 6.5 异常状态机
+└── breaker.md         # 6.6 Breaker（Round 5 裁决 park/STOP）
+```

package/skills/work-review/references/breaker.md

@@ -0,0 +1,26 @@
+# 6.6 Breaker（Round 5 仍有 open findings）
+
+## 触发条件
+
+Fix loop 跑完 Round 5 仍有 open findings 时触发。**绝不**在 Round 5 前提前裁决——那是 pre-judging。6.5 中的即时 ESCALATE/BLOCKED 是技术与边界问题，不属于「提前裁决 finding 正确性」。
+
+## 步骤
+
+1. 停止派发。
+2. 读取 `task-<N>-rereview-5.md`。
+3. 自己裁决每条 open finding，按下表分派：
+
+## 裁决表
+
+| 情况 | 动作 |
+|------|------|
+| reviewer 错误/可争议 | park with ruling: `T<N>: parked — <finding> — ruling: <why>` |
+| 真问题但不 load-bearing | park with ruling（同上） |
+| 真问题且 load-bearing | STOP: `T<N>: BLOCKED — <reason>`，报告用户 |
+
+## 约束
+
+- 仅 Round 5 后触发，Round 1-4 不裁决 finding 正确性。
+- park 不打断用户；STOP 才报告用户。
+- load-bearing 判定：该 finding 不修复会导致 `target` 未达成或后续任务无法进行。
+- 6.5 即时 ESCALATE/BLOCKED（fix implementer 返回 BLOCKED/ESCALATE、finding retry 2 次未解决等）是技术与边界问题，与本 Breaker 的 finding 正确性裁决不同，不视为「提前裁决」。

package/skills/work-review/references/fix-loop.md

@@ -0,0 +1,118 @@
+# 6.2-6.5 Fix Loop
+
+## 6.1 触发条件
+
+Review 报告 Spec ❌、任何 Critical/Important finding、或你确认的 ⚠️ 项。
+
+## 6.2 Fix 轮次策略
+
+| 轮次 | 策略 | 理由 |
+|------|------|------|
+| Round 1-3 | 恢复原 implementer（传 session_ref） | context 完整，知道自己的代码和选择 |
+| Round 4-5 | 新 implementer + 更强模型 | fresh eyes + capability bump |
+
+**能力假设**（不符则退化，不许静默失效）：
+- 「传 `session_ref` 续接同一 subagent 会话」依赖平台 `task` 工具支持会话续接；若不支持，改为每轮**新 implementer**（附完整 brief + report + review 文件路径，prompt 自包含）。
+- 「更强模型」为可选项：若 `task` 调用支持指定模型则用之；否则退化为「新 implementer + 更详细 brief」，**不假定模型可切换**。
+
+### 每轮 fix 的 prompt
+
+```
+你之前实现了 T<N>，review 发现了以下问题需要修复。
+
+## 任务详情
+
+读取你的任务 brief：<BRIEF_FILE>
+
+## 审查发现
+
+读取审查报告：<REVIEW_FILE>
+其中的 Critical 和 Important findings 是你需要修复的。
+
+## 执行边界（硬约束）
+
+- **最多 20 次工具调用**：到 20 次仍未完成必须停止并报告 ESCALATE。
+- **只修 open findings**：不要重构未涉及的代码，不要"顺手改进"。
+- **每条 finding 最多重试 2 次**：如果同一 finding 修了 2 次仍未解决，停止并报告该 finding 为 ESCALATE。
+
+## 修复要求
+
+1. 逐条修复 review 中的 Critical/Important findings
+2. 运行 brief 中的 verify 命令验证修复
+3. 将 fix report 追加到 <REPORT_FILE>（不要覆盖之前的报告）
+4. 返回 ≤10 行状态：fix 了哪些 finding、verify 结果、commits、工具调用次数
+```
+
+**关键**：fix prompt 引用 review 文件路径，不内联 findings——compaction 后 findings 可能丢失，文件不会。
+
+## 6.3 Scoped Re-review
+
+每轮 fix 后，取 Ledger 中该任务**最后一条** `reviewed_head=` 的值作为 `FIX_BASE`，`HEAD` = 当前 HEAD，生成 scoped review package 到 `<doc_dir>/task-<N>-review-<fix_base7>..<head7>.diff`（结构同 5.1）。
+
+派发 re-reviewer（`subagent_type` 取 `general`；唯一写操作是 `<REREVIEW_FILE>`，不得改源码/add/commit）：
+
+```
+你是一个 scoped re-reviewer。验证上一轮 review 的 findings 是否被解决，检查 fix diff 是否引入新问题。
+
+## Task
+读取 brief：<BRIEF_FILE>
+
+## 审查发现
+读取审查报告：<REVIEW_FILE>
+其中的 Critical/Important findings 是你需要验证的。
+
+## Fix
+读取实现者报告（fix report 在末尾）：<REPORT_FILE>
+Fix base: <FIX_BASE_SHA>  Head: <HEAD_SHA>
+Diff 文件：<DIFF_FILE>
+
+## 执行边界（硬约束）
+
+- **最多 10 次工具调用**：到 10 次仍未完成必须停止并报告未完成。
+- **只验证 findings + fix diff**：不重新审查未改动代码。
+- **写操作白名单 = 仅 `<REREVIEW_FILE>`**：不修改源码、不 add、不 commit、不改工作树/index/HEAD/分支；唯一允许的写是写入 `<REREVIEW_FILE>`。
+
+## 范围
+- 只验证 findings 是否解决 + 检查 fix diff 新问题
+- 范围外的观察记为 out-of-scope，不阻塞
+
+## 报告格式
+
+将完整 re-review 报告写入 <REREVIEW_FILE>，然后用 ≤10 行回报：
+- 逐条 finding: ADDRESSED / NOT ADDRESSED
+- New breakage: None / <描述>
+- Verdict: All findings addressed | Findings remain open
+- 工具调用次数（如 "used 6/10"）
+```
+
+re-reviewer 写入文件：`<doc_dir>/task-<N>-rereview-<R>.md`（R = 轮次编号）
+
+## 6.4 Ledger 记录
+
+每轮 fix 后、re-review 结束后立即追加两条：
+
+```
+T<N>: fix round <R>/5 (<X> addressed, <Y> open — <finding one-liners>; commits <a7>..<b7>)
+T<N>: reviewed_head=<re-review 时的 HEAD>
+```
+
+## 6.5 Fix loop 异常分支状态机
+
+fix 过程中出现的非正常返回按以下状态表处理（不分轮次，即时触发）：
+
+| 事件 | 处理 |
+|------|------|
+| fix implementer 返回 `BLOCKED`/`ESCALATE` | 停止本任务 fix，写 Ledger `T<N>: fix blocked/escale (<reason>)`，按 6.6 Breaker 裁决或升级用户 |
+| re-review 报 **New breakage**（Critical/Important） | 作为新 finding 并入下一 fix round（不单独重启流程）；Minor → park |
+| fix 后 `verify` 失败 | 视为该 finding 未解决；该 finding 计 retry+1，累计 >2 次 → 该 finding 单独 `ESCALATE` |
+| 部分 `ADDRESSED` / 部分 `NOT ADDRESSED` | 仅未解决项进入下一轮；已解决项在 Ledger 标注 `fixed` |
+| 某 finding retry 2 次仍未解决 | 该 finding 单独 `ESCALATE`，不阻塞其他 finding 继续 |
+| re-reviewer 返回空 / 无 verdict | 记 Ledger `T<N>: rereview missing`，从 rereview 文件读取；文件亦无 → 按该轮 findings 未解决处理 |
+
+## 约束
+
+- fix 轮次硬上限 5 轮。
+- `FIX_BASE` 语义：取 Ledger 中该任务**最后一条** `reviewed_head=` 的值（不是初始 `base=`），保证 scoped re-review 只看 fix diff。
+- re-reviewer 工具调用上限 10 次；写白名单仅 `<REREVIEW_FILE>`。
+- fix prompt 引用 review 文件路径，不内联 findings。
+- 能力假设退化不许静默失效：不支持 session 续接 → 每轮新 implementer；不支持模型切换 → 退化「新 implementer + 更详细 brief」。

package/skills/work-review/references/review-package.md

@@ -0,0 +1,24 @@
+# 5.1 生成 review package
+
+## 步骤
+
+1. 取 Ledger 中该任务的 `base=` 值作为 `BASE`；`HEAD` = 当前 HEAD。
+2. 写入 `<doc_dir>/task-<N>-review-<base7>..<head7>.diff`（`<base7>`/`<head7>` 为 7 位短 SHA），内容必须含三段：
+
+## 三段结构
+
+1. `## Commits`：`BASE..HEAD` 的 commit 列表
+2. `## Files changed`：`BASE..HEAD` 的变更文件统计
+3. `## Diff`：`BASE..HEAD` 的完整 diff（上下文取 10 行）
+
+## 产物
+
+| 产物 | 位置 | 用途 |
+|------|------|------|
+| review package diff | `<doc_dir>/task-<N>-review-<base7>..<head7>.diff` | reviewer 读取审查 |
+
+## 约束
+
+- 短 SHA 一律取 7 位（`${sha:0:7}`）。
+- diff 上下文固定 10 行（`git diff -U10` 或等价）。
+- `BASE` 必须来自 Ledger `base=` 条目，不取记忆值（compaction 恢复安全）。