@wwkit/harness 1.0.15 → 1.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wwkit/harness",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "author": "bluesliu <langcai163@163.com>",
   "description": "WebWork abilities for opencode",
   "type": "module",

package/skills/work-dispatch/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: work-dispatch
+description: |
+  [work 专属 runbook] 仅供 work agent 通过 skill 工具显式调用（name=work-dispatch），其他 agent / 普通对话禁止触发
+  派发阶段技能：4.1 准备（记录 BASE、Ledger 写 base+session、渲染 task brief、指定 report 路径）；
+  4.2 渲染自包含派发 prompt（任务详情/上下文/约束/执行边界 50 次+防循环/自审/报告格式）；
+  4.3 处理 implementer 返回（status 表 DONE/DONE_WITH_CONCERNS/NEEDS_CONTEXT/BLOCKED/ESCALATE + 异常表 + 重试上限 1 次 + background 派发与串行衔接）。
+  适用：work agent 第四步「派发 implementer」。
+  不适用：规划（用 work-plan）；产物目录与 Ledger 维护（用 work-ledger）；审查与 fix loop（用 work-review）；非 work 流程的普通派发。
+license: MIT
+metadata:
+  workflow: sequential
+---
+
+# work-dispatch 技能
+
+## 触发时机
+
+work agent 完成第三步「产物目录与 Ledger」、并已通过 work-plan 落单任务后，进入第四步「派发 implementer」时加载本技能。每派发一个任务加载一次；恢复场景下按 Ledger `T<N>: base=`/`T<N>: session=` 条目恢复派发上下文。
+
+## 输入
+
+从 work.md 流程传入：
+
+| 输入 | 说明 |
+|------|------|
+| `doc_dir` | 产物目录绝对路径（来自 work-ledger），brief/report/diff 文件均写其下 |
+| `plan.md` | 任务计划文件（位于 `<doc_dir>/plan.md`），派发以其中该任务条目为准 |
+| `task_id` (`T<N>`) | 当前任务编号 |
+| `root_dir` | 工程根目录，prompt 内路径与 bash 命令的基准 |
+| `constraints` | 全局约束，展开为每个任务 `forbidden` 的至少内容 |
+| Ledger 句柄 | 派发前后需写 `T<N>: base=`/`T<N>: session=`/状态行 |
+
+## 工作流程
+
+### 阶段 1：加载 references
+
+用 `read` 工具加载本技能 `references/` 下的全部流程文件（相对路径基于本 skill 目录）：
+
+- `references/prepare.md` → 4.1 准备（BASE 记录、Ledger 写 base+session、brief 渲染、report 路径指定）
+- `references/dispatch-prompt.md` → 4.2 派发 prompt 模板（自包含结构 + 执行边界 50 次 + 防循环 + 自审 + 报告格式）与「禁止」清单
+- `references/report-handling.md` → 4.3 status 处理表 + 异常返回表 + 重试上限 1 次 + background 派发与串行衔接
+
+### 阶段 2：派发前准备
+
+按 `references/prepare.md`：记录 `BASE = $(git rev-parse HEAD)`；写 Ledger `T<N>: base=<BASE>`；以 `plan.md` 中该任务条目渲染 `<doc_dir>/task-<N>-brief.md`；在 prompt 中告知 implementer report 路径 `<doc_dir>/task-<N>-report.md`。
+
+### 阶段 3：派发 implementer
+
+按 `references/dispatch-prompt.md` 渲染自包含 prompt（所有占位符展开为绝对路径），用 `task` 工具派发，`subagent_type` 取 `explore`（只读）或 `general`（可写）。写 Ledger `T<N>: session=<session_ref>`。
+
+### 阶段 4：处理返回
+
+implementer 返回后立即按 `references/report-handling.md` 写 Ledger 状态行，再按 status 表分派动作；异常返回按异常表处理，空输出/无 status 最多重试 1 次。background 派发时遵循串行衔接规则：派发后记 Ledger → 做本地工作 → 收到通知 → 处理 → review close 后才派下一个 general；等待期间不派下一个。
+
+## 输出
+
+- `<doc_dir>/task-<N>-brief.md`（派发前渲染）
+- Ledger 中 `T<N>: base=`/`T<N>: session=`/状态行条目
+- 触发下一步：status=DONE/DONE_WITH_CONCERNS → 生成 review package 并交 work-review；其他 status 按表分派
+- 本技能**不审查、不 fix**（审查与 fix loop 属 work-review）
+
+## 约束
+
+- 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 个/轮。
+- 本技能只派发与处理返回，不审查、不 fix、不改源码。
+
+## 资源目录
+
+```
+references/
+├── prepare.md          # 4.1 准备（BASE/Ledger/brief/report 路径）
+├── dispatch-prompt.md  # 4.2 派发 prompt 模板 + 禁止清单
+└── report-handling.md  # 4.3 status 表 + 异常表 + 重试上限 + 串行衔接
+```

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

@@ -0,0 +1,87 @@
+# 4.2 派发 prompt 模板
+
+使用 `task` 工具，`subagent_type` 取 `explore`（只读）或 `general`（可写）。
+
+## 自包含原则
+
+> 派发前，prompt 中所有占位符（`<BRIEF_FILE>`、`<REPORT_FILE>`、`<doc_dir>/...` 等）一律展开为绝对路径，subagent 直接可读，不再含任何待解引用符号。
+
+subagent 看不到主 agent 历史，prompt 必须自包含。
+
+## prompt 结构
+
+```
+你是一个被派发的执行者。你的任务是实现 T<N>: <task name>
+
+## 任务详情
+
+读取你的任务 brief：<BRIEF_FILE>
+它包含完整任务文本：goal、files、interfaces、accept（验收标准）、verify（验证命令）、约束。
+brief 是你的唯一需求来源——不要假设 brief 之外的任何上下文。
+
+## 上下文
+
+<场景设置：任务在项目中的位置、依赖、架构上下文>
+<接口信息：前序任务产出的接口、类型、签名——从 plan.md 的 interfaces 字段提取>
+
+## 约束
+
+- 可写文件白名单：<writable>
+- 禁改文件：<forbidden>（含 constraints）
+- 工作目录：<root_dir>
+
+## 执行边界（硬约束）
+
+- **最多 50 次工具调用**：每调用一次工具（read/write/edit/bash/grep/glob 等）计一次。到 50 次仍未完成必须停止并报告 ESCALATE。
+- **禁止无限循环**：同一个文件不要读超过 3 次；同一个测试不要连续运行超过 3 次；同一个错误不要重试超过 2 次。
+- **进度自检**：每 10 次工具调用后，评估剩余工作是否还能在剩余调用次数内完成。不能则立即停止并报告 ESCALATE。
+- **遇到以下情况立即停止并报告**：
+  - 任务需要架构决策（多种有效方案）→ BLOCKED
+  - 你无法理解代码且无法找到清晰说明 → BLOCKED
+  - 任务涉及计划未预见的大量重构 → ESCALATE
+  - 你不确定你的方法是否正确 → ESCALATE
+  - 工具调用次数即将耗尽且未完成 → ESCALATE
+
+## 你的工作
+
+1. 按 brief 实现指定内容
+2. 写测试（如 brief 要求 TDD）
+3. 运行 brief 中的 verify 命令验证实现可用
+4. 对照 brief 中的 accept 验收标准逐条自检
+5. 提交你的工作
+6. 自审（见下方）
+7. 报告
+
+## 自审
+
+报告前检查：
+- 完整性：brief 中的 accept 每条是否满足？
+- 质量：命名是否清晰？代码是否可维护？
+- 纪律：是否避免了过度构建（YAGNI）？
+- 测试：测试是否验证真实行为（不是 Mock 行为）？
+
+## 报告格式
+
+将完整报告写入 <REPORT_FILE>：
+- 实现了什么
+- 验证结果（verify 命令输出 + 测试结果）
+- accept 逐条对照结果
+- 变更文件
+- 自审发现
+- 顾虑或问题
+
+然后用 ≤15 行回报（详情在报告文件中）：
+- Status: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT | ESCALATE
+- Commits（短 SHA + subject）
+- 一行验证摘要（如 "14/14 passing"）
+- 工具调用次数（如 "used 18/50"）
+- 顾虑（如有）
+- 报告文件路径
+```
+
+## 禁止
+
+- 粘贴计划全文到 prompt（brief 文件是单一来源）
+- 粘贴之前任务的摘要到后续任务的 prompt
+- 让 subagent 读整个计划文件
+- 在 prompt 中重复 brief 的 accept/verify（implementer 自己读 brief）

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

@@ -0,0 +1,25 @@
+# 4.1 派发前准备
+
+按以下顺序执行，每步产物供后续阶段与 work-review 使用。
+
+## 步骤
+
+1. **记录 BASE**：`BASE = $(git rev-parse HEAD)`（当前 HEAD，作为本任务的 diff 起点与下一任务 `BASE` 的来源）。
+2. **写 Ledger**：`T<N>: base=<BASE>`（compaction 后恢复用；恢复时以此条目为准，不以记忆为准）。
+3. **渲染 task brief**：以 `<doc_dir>/plan.md` 中该任务条目为准，渲染为 `<doc_dir>/task-<N>-brief.md`，包含完整任务文本：`goal`/`files`/`interfaces`/`accept`（验收标准）/`verify`（验证命令）/`约束`。
+4. **指定 report 路径**：`<doc_dir>/task-<N>-report.md`，在 prompt 中告知 implementer（implementer 把完整报告写入此文件）。
+
+## 产物
+
+| 产物 | 位置 | 用途 |
+|------|------|------|
+| `BASE` 值 | 内存 + Ledger | review package 的 diff 起点；下一任务 `BASE` |
+| `T<N>: base=` | Ledger | compaction 恢复入口 |
+| `task-<N>-brief.md` | `<doc_dir>/` | implementer 的唯一需求来源 |
+| `task-<N>-report.md` 路径 | prompt 中告知 | implementer 写报告的目标文件 |
+
+## 约束
+
+- brief 文件是单一来源：不要在 prompt 中重复 brief 的 `accept`/`verify`，implementer 自己读 brief。
+- `BASE` 取 7 位短 SHA 用于 Ledger 显示，但 diff 计算用完整 SHA。
+- 恢复场景：若 Ledger 已有 `T<N>: base=`，跳过步骤 1-2，直接以该值作为 `BASE`。

package/skills/work-dispatch/references/report-handling.md

@@ -0,0 +1,38 @@
+# 4.3 处理 implementer 返回
+
+implementer 返回后，**立即写入 Ledger** 状态行，然后按 status 处理。
+
+## status 处理表
+
+| Status | Ledger 记录 | 动作 |
+|--------|------------|------|
+| `DONE` | `T<N>: implementer done (commits <base7>..<head7>)` | 生成 review package，派发 task reviewer |
+| `DONE_WITH_CONCERNS` | `T<N>: implementer done_with_concerns (<concern one-liner>)` | 读**回报文本中的顾虑段（≤15 行，不读完整 report 文件）**，正确性/范围问题先处理，观察类问题记录后进入 review |
+| `NEEDS_CONTEXT` | `T<N>: needs_context` | 补充上下文，重新派发（复用 session_ref 或新开会话；task_id 不变） |
+| `BLOCKED` | `T<N>: blocked (<reason>)` | 评估：上下文问题→补充重派；推理不足→换更强模型；任务过大→拆分；计划错误→重规划（见「重规划」节） |
+| `ESCALATE` | `T<N>: escalate (<reason>)` | 停止该分支。如实向用户说明为何超出边界/需人工介入，不再重试。如果是工具调用耗尽，考虑拆分任务后重新派发 |
+
+## 异常返回处理
+
+subagent 返回不符合预期时按以下表处理：
+
+| 异常情况 | 检测方式 | 处理 |
+|---------|---------|------|
+| 空输出 | 返回文本为空或仅空白 | 记 Ledger `T<N>: empty output`，新开会话重新派发（task_id 不变），最多重试 1 次 |
+| 无 status 行 | 返回文本不含 Status 关键字 | 计 Ledger `T<N>: no status`，从 report 文件读取实际状态；report 文件也无 → 按 BLOCKED 处理 |
+| 报告文件未写入 | report 文件不存在或为空 | 记 Ledger `T<N>: report missing`，按 BLOCKED 处理 |
+| task 工具返回错误 | task 工具返回 state="error" | 记 Ledger `T<N>: task error (<error>)`，评估错误类型后决定重派或升级 |
+
+## 重试上限
+
+**绝不**忽略升级或强制同一模型无变化重试。空输出/无 status 最多重试 1 次，再失败则按 BLOCKED 处理。
+
+## background 派发与串行衔接
+
+派发后记 Ledger → 做本地工作 → 收到通知 → 处理 → review close 后才派下一个 general；等待期间不派下一个。
+
+- 派发后：立即写 Ledger `T<N>: session=` 与状态行，不要等返回。
+- 等待期间：可做不依赖该任务产物的本地工作（如准备下一任务 brief、整理 Ledger），但**不派发下一个 `general`**。
+- 收到通知：按上方 status 处理表分派动作。
+- review close 后：下一任务的 `BASE` 自动等于本任务 `HEAD`，才派发下一个 `general`。
+- `explore`（只读）可并行且 ≤5 个/轮，不受串行约束限制。

package/skills/work-finalize/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: work-finalize
+description: |
+  [work 专属 runbook] 仅供 work agent 通过 skill 工具显式调用（name=work-finalize），其他 agent / 普通对话禁止触发
+  收尾阶段技能：执行第七步 Final Review（全分支 review package、final reviewer ≤30 次工具调用/写白名单仅 final-review.md/不重跑测试、parked/minor triage、一次 fix + 一次 scoped re-review、final_review_head 记录、残留 load-bearing 报告用户）与第八步 综合交付（最终 target 验收运行强制、三者缺一不可、整合产物=提交历史+diff 路径、不 push/merge、裁决清单显式列出、产物目录清理/归档规则）。
+  适用：work agent 所有任务 review close 后的「最终审查 → 整体验收 → 交付」环节。
+  不适用：单任务 review（用 work-review）；重规划/预算/回滚（用 work-recovery）；非 work 流程的普通收尾。
+license: MIT
+metadata:
+  workflow: sequential
+---
+
+# work-finalize 技能
+
+## 触发时机
+
+work agent 所有任务 review close 后、向用户交付前加载本技能，执行「全分支 Final Review → 最终 target 验收 → 综合交付」。
+
+## 输入
+
+从 work.md 流程传入：
+
+| 字段 | 说明 | 默认 |
+|------|------|------|
+| `target` | 要达成的目标（第五步按它判定成败；第八步按其验收标准做整体验收） | 必填 |
+| `root_dir` | 工程根目录（产物目录、diff 路径、归档目录的基准） | 当前工作目录 |
+| `doc_dir` | 本次 session 的产物目录（plan.md / progress.md(Ledger) / 各 task report 所在） | 必填 |
+| `session_id` | 本次 session id（归档目录命名用） | 必填 |
+| `merge_base` | Ledger 首行元数据中的 `merge_base`（起始检查时记录） | 必填 |
+| `initial_base` | 本次运行最初的 base（整合产物 commit 列表范围 `initial_base..HEAD`） | 必填 |
+
+## 工作流程
+
+### 阶段 1：加载 references
+
+用 `read` 工具加载本技能 `references/` 下的全部流程文件（相对路径基于本 skill 目录）：
+
+- `references/final-review.md` → 第七步 Final Review（MERGE_BASE 取值、review package 生成、final reviewer prompt 与硬约束、一次 fix + 一次 scoped re-review、final_review_head 记录、残留 load-bearing 处理）
+- `references/acceptance.md` → 第八步 综合交付 第 1-2 点（最终 target 验收运行强制、三者缺一不可退出判据）
+- `references/handover.md` → 第八步 综合交付 第 3-5 点（整合产物=提交历史+diff 路径、不 push/merge、裁决清单显式列出、产物目录清理/归档规则）
+
+### 阶段 2：Final Review
+
+按 `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 → 报告用户。
+
+### 阶段 3：最终 target 验收
+
+按 `references/acceptance.md` 在 final review 通过后由主 agent 执行一次 target 级整体验收命令（单一可执行命令优先，否则汇总各任务 `verify`），结果写入 `final-review.md` 的「整体验收结果」段；对照 `target` 验收标准确认「所有任务 done + review 通过 + 整体验收通过」三者缺一不可。
+
+### 阶段 4：综合交付
+
+按 `references/handover.md` 整合产物（提交历史 `initial_base..HEAD` + `final-review-<merge_base7>..<head7>.diff` 路径 + final-review 摘要）写入最终交付文件；向用户输出结果摘要 + 本运行全部裁决清单（parked/ruled/blocked/escalate/reverted/interrupted/replan，按发生顺序，每条附理由）；按归档规则保留 `plan.md`/`progress.md`/各 `task-<N>-report.md`/`final-fix-report.md`/各 review/`final-review.md` 到 `<root_dir>/.webwork/harness/archive/<session_id>/`，删除临时 task brief 与 diff 包；默认保留归档，仅当用户显式要求清理时才删除。
+
+## 输出
+
+- `<doc_dir>/final-review.md`（含整体验收结果段）
+- `<doc_dir>/final-fix-report.md`（若有 findings）
+- `<doc_dir>/final-fix-review-<final_review_head7>..<head7>.diff`（若 scoped re-review）
+- 最终交付文件（提交历史 + diff 路径 + final-review 摘要）
+- 向用户输出的结果摘要 + 全部裁决清单
+- 归档目录 `<root_dir>/.webwork/harness/archive/<session_id>/`（默认保留）
+- 本技能**不 push / 不 merge**（那是 worktree 外的副作用，由用户自行决定）
+
+## 约束
+
+- final reviewer 最多 30 次工具调用，到 30 次仍未完成必须停止并报告未完成。
+- final reviewer 写操作白名单 = 仅 `<doc_dir>/final-review.md`：不修改源码、不 add、不 commit、不改工作树/index/HEAD/分支。
+- final reviewer 不重跑测试：信任 Ledger 记录的测试结果；整体验收由主 agent 在第八步执行。
+- 有 findings 时只做**一次** fix dispatch（不是 per-finding）+ **一次** scoped re-review；final fix 一律派新 `general`（findings 可能跨多任务，无原 session 可复用）。
+- 派发 final fix 前必须写 Ledger 首段 `final_review_head=<sha>`；scoped re-review 的 `FIX_BASE` 取该值。
+- 最终 target 验收运行**强制**：任务级 accept 通过并不代表 target 整体可用；退出判据三者缺一不可（所有任务 done + review 通过 + 整体验收通过）。
+- 本 agent 不 push / merge；交付即当前分支上的提交串，是否推送到远端由用户决定。
+- 裁决清单必须显式列出（parked/ruled/blocked/escalate/reverted/interrupted/replan，按发生顺序，每条附理由），不随产物目录归档而消失。
+- 归档即终止本 session，不再支持 compaction 续跑。
+
+## 资源目录
+
+```
+references/
+├── final-review.md   # 第七步 Final Review（MERGE_BASE/review package/final reviewer prompt/一次 fix+一次 re-review/final_review_head）
+├── acceptance.md     # 第八步 第 1-2 点（最终 target 验收运行强制/三者缺一不可）
+└── handover.md       # 第八步 第 3-5 点（整合产物/不 push merge/裁决清单/产物目录清理归档）
+```

package/skills/work-finalize/references/acceptance.md

@@ -0,0 +1,19 @@
+# 最终 target 验收（第八步 第 1-2 点）
+
+## 1. 最终 target 验收运行（强制）
+
+final review 通过后，由你（主 agent）执行一次 **target 级整体验收命令**，任务级 accept 通过并不代表 target 整体可用：
+
+- 若 target 有单一可执行验收命令（如 `npm test` / `make check`）→ 运行它；
+- 否则汇总所有任务的 `verify` 结果，逐一确认通过；
+- 将验收命令与结果写入 `final-review.md` 的「整体验收结果」段，作为退出判据。
+
+## 2. 退出判据（三者缺一不可）
+
+对照 `target` 验收标准：
+
+- 所有任务 `done`
+- review 通过
+- **整体验收通过**
+
+三者缺一不可。

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

@@ -0,0 +1,53 @@
+# Final Review（第七步）
+
+所有任务完成后，进行全分支审查。
+
+## 流程
+
+1. 定义 `MERGE_BASE`：取 Ledger 首行元数据中的 `merge_base`（取值规则见「起始检查」）。生成全分支 review package（`${MERGE_BASE}..HEAD`）到 `<doc_dir>/final-review-<merge_base7>..<head7>.diff`
+2. 派发 final reviewer（`subagent_type` 取 `general`；唯一写操作是 `<doc_dir>/final-review.md`，不得改源码/add/commit），指向 Ledger 的 parked/minor 项让它 triage
+3. final reviewer 写入 `<doc_dir>/final-review.md`
+4. 有 findings → **一次** fix dispatch（不是 per-finding）+ **一次** scoped re-review：
+   - **final fix 一律派新 `general`**（findings 可能跨多任务，无原 session 可复用）。
+   - 派发前写 Ledger 首段 `final_review_head=<sha>`（= 上次 final review 时的 HEAD）。
+   - fix report 写入 `<doc_dir>/final-fix-report.md`（不覆盖 final-review.md）。
+   - fix 后 scoped re-review 的 `FIX_BASE` 取该 `final_review_head` 值，HEAD = 当前 HEAD，diff 写入 `<doc_dir>/final-fix-review-<final_review_head7>..<head7>.diff`。
+5. 招留 load-bearing findings → 报告用户
+
+## final reviewer prompt
+
+```
+你是全分支审查者。审查整个开发分支的最终质量。
+
+## 计划与进度
+
+读取计划：<doc_dir>/plan.md
+读取进度：<doc_dir>/progress.md
+Ledger 中的 parked/minor 项需要你 triage：哪些必须在合并前修复，哪些可延期。
+
+## Diff
+
+全分支 diff 文件：<doc_dir>/final-review-<merge_base7>..<head7>.diff
+
+## 执行边界（硬约束）
+
+- **最多 30 次工具调用**：到 30 次仍未完成必须停止并报告未完成。
+- **写操作白名单 = 仅 `<doc_dir>/final-review.md`**：不修改源码、不 add、不 commit、不改工作树/index/HEAD/分支；唯一允许的写是写入 final-review 报告。
+- **不重跑测试**：信任 Ledger 记录的测试结果；整体验收由主 agent 在第八步执行。
+
+## 审查范围
+
+- 全分支的 spec 覆盖完整性
+- 跨任务接口一致性
+- parked findings 的 triage
+- 整体代码质量
+
+## 报告格式
+
+将完整审查报告写入 <doc_dir>/final-review.md，然后用 ≤15 行回报：
+- 总体评估: Approved | Needs fixes
+- Critical/Important 数量
+- parked triage 结果
+- 工具调用次数（如 "used 22/30"）
+- Final review 文件路径
+```

package/skills/work-finalize/references/handover.md

@@ -0,0 +1,28 @@
+# 综合交付（第八步 第 3-5 点）
+
+## 3. 整合产物
+
+交付物 = 提交历史（`initial_base..HEAD` 的 commit 列表）+ `final-review-<merge_base7>..<head7>.diff` 文件路径，连同 final-review 摘要一并写入最终交付文件，报告用户。
+
+**交付即当前分支上的这串提交；本 agent 不 push / merge（那是 worktree 外的副作用），是否推送到远端由用户自行决定。**
+
+## 4. 裁决清单（显式列出）
+
+向用户输出结果摘要：交付物 + **本运行全部裁决**（parked / ruled / blocked / escalate / reverted / interrupted / replan，按发生顺序，每条附理由）。
+
+这些是主 agent 替你拍板的决定，必须显式列出，不随产物目录归档而消失。
+
+## 5. 产物目录清理（可恢复）
+
+删除临时产物（task brief、diff 包）；**归档保留** 以下文件到 `<root_dir>/.webwork/harness/archive/<session_id>/`：
+
+- `plan.md`
+- `progress.md`（Ledger）
+- 各 `task-<N>-report.md`（含 fix 追加记录，是 reviewer 判断依据、复盘核对的关键）
+- `final-fix-report.md`
+- 各 review
+- `final-review.md`
+
+`diff` 包可重新生成、brief 可从 `plan.md` 重建，故只删它们。
+
+**默认保留归档；仅当用户显式要求清理时才删除。归档即终止本 session，不再支持 compaction 续跑。**

package/skills/work-ledger/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: work-ledger
+description: |
+  [work 专属 runbook] 仅供 work agent 通过 skill 工具显式调用（name=work-ledger），其他 agent / 普通对话禁止触发
+  运行会话管理技能：创建产物目录（doc_dir 树 + .gitignore）、生成/恢复 session_id、起始检查（git 仓库 / 工作树 stash / 运行元数据 branch+initial_base+merge_base）、
+  以及 Ledger（progress.md）的格式与读写恢复规则（短 SHA 7 位 + 大小写映射约定）。
+  适用：work agent 第三步「产物目录与 Ledger」及 compaction 后恢复进度。
+  不适用：规划阶段（用 work-plan）；任务派发/审查正文；非 work 流程的普通文档管理。
+license: MIT
+metadata:
+  workflow: sequential
+---
+
+# work-ledger 技能
+
+## 触发时机
+
+work agent 进入第三步「产物目录与 Ledger」时（创建运行时）、以及 compaction 后需要恢复进度时加载本技能。
+
+## 输入
+
+从 work.md 流程传入：
+
+| 输入 | 说明 |
+|------|------|
+| `root_dir` | 工程根目录，产物目录位于 `<root_dir>/.webwork/harness/work/<session_id>/` |
+| `target` | 目标摘要，写入 Ledger 首行命名、plan.md 标题 |
+| `constraints` | 约束（每个任务 brief 的 `forbidden` 至少包含其全部内容） |
+| git 状态 | 起始检查时读取的分支名、HEAD、工作树状态 |
+
+## 工作流程
+
+### 阶段 1：加载 references
+
+用 `read` 工具加载本技能 `references/` 下的全部流程文件（相对路径基于本 skill 目录）：
+
+- `references/layout.md` → 产物目录结构（doc_dir 树 + `.gitignore` + archive 约定）
+- `references/bootstrap.md` → session_id 生成与恢复、产物目录创建、起始检查、后续约束
+- `references/ledger-format.md` → Ledger（progress.md）格式、条目规则、恢复逻辑、短 SHA/大小写约定
+
+### 阶段 2：创建产物目录
+
+按 `references/layout.md` 与 `references/bootstrap.md`：生成 `session_id`，创建 `<root_dir>/.webwork/harness/work/<session_id>/`，写入 `<root_dir>/.webwork/harness/work/.gitignore`（内容 `*` + `!.gitignore`）。
+
+### 阶段 3：起始检查（仅此一次）
+
+按 `references/bootstrap.md`：确认在 Git 仓库内；检查工作树干净（非空则 `git stash push -u` 并把脏文件清单记入 Ledger，此为人工确认点之一）；记录运行元数据 `branch`/`initial_base`/`merge_base` 并写入 Ledger 首行。
+
+### 阶段 4：Ledger 读写维护
+
+按 `references/ledger-format.md`：每次派发前写 `T<N>: base=` 与 `T<N>: session=`，review/re-review 后写 `T<N>: reviewed_head=`，implementer 返回后写状态行；恢复时按该文件的恢复逻辑执行（先读 `plan.md` 恢复计划，再读 `progress.md` 恢复进度）。
+
+## 输出
+
+- `<root_dir>/.webwork/harness/work/` 目录树（`.gitignore` + `<session_id>/` 下的 plan.md/progress.md 等文件）
+- Ledger 首行元数据块（`doc_dir`/`branch`/`initial_base`/`merge_base`），作为恢复入口
+- 按阶段 4 维护的 `T<N>: key=value` 进度条目
+
+## 约束
+
+- 唯一约束：Ledger 字段名与产物文件格式固定（对照 `references/ledger-format.md`），不得改动。
+- 短 SHA 一律取 7 位（`${sha:0:7}`）；大小写映射约定（见 ledger-format）：Ledger 元数据字段小写、任务条目 `T<N>: key=value`、内存/命令变量大写。
+- 产物目录绝对路径是恢复入口，compaction 后以 Ledger 首行 `doc_dir=` 为准，不以记忆为准。
+- 本技能只维护产物目录与 Ledger，不派发/审查任务、不写任务 brief。
+
+## 资源目录
+
+```
+references/
+├── layout.md        # 产物目录结构（doc_dir 树 + .gitignore + archive）
+├── bootstrap.md     # session_id 生成与恢复、创建产物目录、起始检查、后续约束
+└── ledger-format.md # Ledger 格式、条目规则、恢复逻辑、短 SHA/大小写约定
+```

package/skills/work-ledger/references/bootstrap.md

@@ -0,0 +1,28 @@
+# session_id 生成与恢复 + 起始检查（提取自 docs/plans/work-copy.md L225-249）
+
+## session_id 生成与恢复（L225-234）
+
+`session_id` 唯一标识一次编排运行的产物目录，由创建时生成（要求：唯一、可排序、含时间戳）并**写入 Ledger 首行**作为恢复入口。
+
+**恢复规则**：
+- compaction 后从 Ledger 头部元数据块的 `doc_dir=` 读取绝对路径恢复；无法读取时退化为：定位 `<root_dir>/.webwork/harness/work/` 中时间戳最新的 `<session_id>` 目录。
+- **产物目录绝对路径是 Ledger 首条元数据**（见 Ledger 格式），恢复时以它为准，不以记忆为准。
+- 并发隔离：不同运行用不同 `session_id` 目录，天然隔离，无额外机制。
+
+**创建产物目录**：创建 `<root_dir>/.webwork/harness/work/<session_id>/` 目录，并写入 `<root_dir>/.webwork/harness/work/.gitignore`（内容为 `*` + `!.gitignore`：忽略所有中间产物，但保留 `.gitignore` 自身）。归档目录 `<root_dir>/.webwork/harness/archive/` **不写** `.gitignore`——保留审计产物，可纳入版本控制。
+
+## 起始检查（仅一次，创建产物目录时执行，L236-245）
+
+派发任何 subagent 前，先确认工作树安全并记录运行元数据：
+
+1. **在 Git 仓库内**：非 Git 仓 → 报告用户并停止。
+2. **工作树是否干净**（`git status --porcelain`）：非空 → 默认 `git stash push -u` 后继续，并把 existing 文件清单记录到 Ledger。**这是人工确认点之一（另一处在范围闸门）**：若用户在场可询问 stash/保留，但全自动运行不因询问卡住。
+3. **记录运行元数据**（写入 Ledger 首行，字段语义如下）：
+   - `branch` = 当前分支名
+   - `initial_base` = 当前 HEAD
+   - `merge_base` = `initial_base`（本次启动时的 HEAD；使 `MERGE_BASE..HEAD` 恰好覆盖**本次编排产出的提交**，不混入运行前已有提交）。仅当用户**显式要求审查整个分支**时才取 `git merge-base HEAD <main_branch>`。
+
+## 后续约束（L247-249）
+
+- **脏文件不得被 implementer 一起提交**：每个任务 brief 的 `forbidden` 中追加「不得 add/commit 任何未在 `writable` 白名单中的文件」。
+- 回滚锚点：`initial_base` 是本运行所有提交的回滚参照（见「中断与回滚」）。

package/skills/work-ledger/references/layout.md

@@ -0,0 +1,25 @@
+# 产物目录（提取自 docs/plans/work-copy.md L204-223、L234）
+
+所有中间产物统一存放在 `doc_dir`（`<root_dir>/.webwork/harness/work/<session_id>/`）目录：
+
+```
+<root_dir>/.webwork/harness/work/
+  .gitignore                    # 内容: * + !.gitignore（忽略所有产物，保留 .gitignore 自身）
+  <session_id>/
+    plan.md                     # 完整计划（第二步产出，compaction 后恢复用）
+    progress.md                 # Ledger（进度持久化）
+    task-<N>-brief.md           # 任务 N 的完整文本（implementer 读取）
+    task-<N>-report.md          # 任务 N implementer 的报告（fix 追加到同一文件）
+    task-<N>-review.md          # 任务 N reviewer 的审查结果
+    task-<N>-rereview-<R>.md    # 任务 N 第 R 轮 re-review 结果
+    task-<N>-review-<base7>..<head7>.diff   # 任务 N 的 review package（diff 包）
+    final-review.md                     # 全分支 final review 结果
+    final-fix-report.md                 # final 阶段一次 fix 的 report（第七步）
+    final-review-<merge_base7>..<head7>.diff  # final review package
+    final-fix-review-<final_review_head7>..<head7>.diff  # 该 fix 的 scoped re-review diff
+```
+
+## .gitignore 约定
+
+- `<root_dir>/.webwork/harness/work/.gitignore`：内容为 `*` + `!.gitignore` —— 忽略所有中间产物，但保留 `.gitignore` 自身。
+- 归档目录 `<root_dir>/.webwork/harness/archive/` **不写** `.gitignore`——保留审计产物，可纳入版本控制。

package/skills/work-ledger/references/ledger-format.md

@@ -0,0 +1,57 @@
+# Ledger 格式（提取自 docs/plans/work-copy.md L251-294；全局约束 L27）
+
+Ledger 是你的恢复地图——compaction 后你的 context 会丢失，但文件不会。Ledger 即 `<doc_dir>/progress.md`。
+
+## 全局约束（L27）
+
+- 短 SHA 一律取 7 位（`${sha:0:7}`）。
+- **大小写映射约定**：
+  - Ledger **元数据字段**小写（`doc_dir`/`branch`/`initial_base`/`merge_base`）；
+  - **任务条目**用 `T<N>: key=value` 形式（如 `T1: base=...`）；
+  - 内存/命令变量同名大写（`BASE`/`HEAD`/`FIX_BASE`/`MERGE_BASE`/`INITIAL_BASE`）。
+- 唯一约束：Ledger 字段名与产物文件格式固定，不得改动。
+
+## 模板
+
+```markdown
+# Work ledger — target: <target 摘要>
+doc_dir: <root_dir>/.webwork/harness/work/<session_id>
+branch: <branch name>
+initial_base: <sha — 启动时 HEAD>
+merge_base: <sha — 本次运行起点，= initial_base>
+
+T1: base=a1b2c3d
+T1: session=abc123
+T1: complete (commits a1b2c3d..d4e5f6a, review clean)
+T1: reviewed_head=d4e5f6a
+T2: base=d4e5f6a
+T2: session=def456
+T2: fix round 1/5 (2 addressed, 0 open; commits d4e5f6a..b7c8d9e)
+T2: reviewed_head=b7c8d9e
+T2: complete (commits d4e5f6a..b7c8d9e, review clean)
+T3: base=b7c8d9e
+T3: session=ghi789
+T3: reviewed_head=e8f9a0b
+T3: parked — <finding> — ruling: <why the code stands>
+T3: complete (commits b7c8d9e..e8f9a0b, 1 parked)
+```
+
+## 每条规则
+
+- 创建 `doc_dir` 时：写首行元数据块（`doc_dir`/`branch`/`initial_base`/`merge_base`），这是恢复入口。
+- 派发 implementer 前：写 `T<N>: base=<BASE_SHA>`（review 和 fix 依赖此 SHA）与 `T<N>: session=<session_ref>`（fix 复用 / 重派时更新）。
+- 每次 review / re-review 结束后：写 `T<N>: reviewed_head=<REVIEW_HEAD_SHA>`（供 FIX_BASE 取用）。
+- final review 结束后、final fix 派发前：写 `final_review_head=<sha>`（= final review 时的 HEAD，供 final fix 的 scoped re-review 作 `FIX_BASE`）。
+- implementer 返回后：立即写状态行（complete/fix round/blocked）。
+- compaction 后恢复：先读 `plan.md` 恢复计划，再读 `progress.md` 恢复进度，信任 Ledger 和 `git log` 胜过你的记忆。
+
+## 恢复逻辑
+
+- 首行元数据 `doc_dir=` → 定位会话产物目录绝对路径（恢复入口）。
+- 首行命名 target → 确认归属。
+- `initial_base` → 启动时的 HEAD；`merge_base` → diff 的起点（默认 = `initial_base`）。
+- `T<N>: base=<sha>` → 该任务的 BASE SHA（用于生成 review package）。
+- `T<N>: reviewed_head=<sha>` → 该任务上次 review 看到的 HEAD（用于 fix 的 scoped re-review）。
+- `final_review_head=<sha>` → final review 时的 HEAD（final fix 的 `FIX_BASE`）。
+- `T<N>: complete` → 已完成，不重新派发。
+- 最后一行是 fix round → 中断在 loop 中，从下一轮恢复。