@wwkit/harness 1.0.15 → 1.0.17

package/skills/revise/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: revise
 description: |
-  基于原始素材进行二次创作，输出符合特定格式的结果（始终为 JSON 数组）。
-  通过 count 参数控制生成条目数量（默认 1），通过 schema 校验确保输出格式正确，校验失败自动重试（最多 3 次）。
-  支持 language 参数指定输出语言（默认中文）。不写入任何文件。
+  自包含内容创作 skill：解析入参（JSON/key=value/prose）→ 按 format 加载 prompt 生成 → schema 校验 → 写 output 文件或 stdout。
+  format=question/status/gallery/article。count 控制条目数（默认1），language 控制输出语言（默认中文）。
+  调用方直接传原始任务消息，skill 自解析自包含。内部用 todowrite 管理 6 步。禁止 WebFetch/网络请求。
   适用：内容创作（question/status/gallery/article 等）。
 license: MIT
 metadata:
@@ -12,28 +12,71 @@ metadata:
 
 # revise 技能
 
+## 核心约束（最高优先级）
+
+- **MUST**：收到任务消息后，先 todowrite 落单 6 步，再逐步执行。
+- **MUST**：每步完成立即 todowrite 勾单。
+- **禁止**：使用 WebFetch 或任何网络请求获取内容。
+- **禁止**：写入 output 以外的任何文件；中间产物用临时文件，完成后清理。
+- **禁止**：以任何形式使用未声明字段（url 等不属于 revise 的字段）。
+
+## 第一步硬指令（自检）
+
+解析入参前，强制自检：
+> 我是否已用 todowrite 落单 6 步？
+> - 未落单 → 立即 todowrite 创建清单。
+> - 已落单 → 继续。
+
 ## 输入参数
 
-入参来自调用方（agent）已规整后的字段，字段清单（字段/类型/必填/默认值）见 `references/input.schema.json5`。
+入参为调用方传入的**原始任务消息**，可能是以下任一形态：
+- **JSON 对象**：如 `{format, source, count, language, output}`，直接取字段值；
+- **key=value**：如 `format=question, source=xxx`，按 `,` 和 `=` 拆分为字段；
+- **纯文本 prose**：不做格式推断（同一 source 可有多种 format）。仅当文本命中 `references/format-aliases.json5` 中某 format 的 `terms`（如"问题/文章/图集/动态"）时才翻译为该 format 标准值，`source` 取文本本身。
+
+字段清单（字段/类型/必填）见 `references/input.schema.json5`。本技能仅使用 `source`、`format`、`count`、`language`、`output` 五个字段，忽略所有其他字段（如 `url`），不得读取、写入或据此推断任何行为。
 
 ## 输出
 
-返回符合指定格式的 JSON **数组**，包含 `{{ count }}` 个 item（即使 count=1 也输出数组）。**不写入任何文件**。
+- 提供 `output` 参数：将 JSON 数组用 `write` 工具写入该文件，stdout 输出文件路径。
+- 未提供 `output` 参数：将 JSON 数组直接输出到 stdout，**不写任何文件**。
+- 校验失败未能产出数组：不写文件、不输出数组，将错误信息输出到 stderr 并结束。
 
 ## 工作流程
 
-### 阶段 1：输入处理
+### 阶段 0：todowrite 落单
+
+收到任务消息后，**先**用 `todowrite` 创建 6 步清单（status=pending）：
+
+1. 解析入参（JSON/key=value/prose → format/source/count/language/output）
+2. 加载 references（format prompt 文件 + schema 文件）
+3. 内容生成（LLM 创作）
+4. Schema 校验
+5. 校验失败修复重试（≤3 次）
+6. 输出（写 output 文件或 stdout）
+
+每步完成立即 todowrite 勾单（status=completed）。
+
+### 阶段 1：解析入参
+
+将第 1 步标记为 in_progress，解析原始任务消息：
 
-- `{{ source }}`：原始素材。若值是现有文件路径，读取文件内容；否则直接以值作为内容。
-- `{{ format }}`：创作格式，用于定位 `references/` 下的 prompt 和 schema 文件。
-- `{{ count }}`：生成的 item 数量，解析为整数，默认 1。为空、非整数或小于 1 时按 1 处理。
-- `{{ language }}`：输出内容语言，默认 `中文`。为空或仅含空白时按 `中文` 处理。
+- **JSON 对象**：直接取 `format`/`source`/`count`/`language`/`output` 字段值。
+- **key=value**：按 `,` 分割、按 `=` 拆分为键值对，取上述五字段。
+- **纯文本 prose**：用 `read` 读取 `references/format-aliases.json5`，仅当文本命中某 format 的 `terms` 时翻译为该 format 标准值，`source` 取文本本身；未命中则 `format` 视为未提供。
 
-本技能仅使用 `source`、`format`、`count`、`language` 四个字段。忽略传入的所有其他字段（如 `output` 等），不得读取、写入或据此推断任何行为。
+解析后得到：
+- `format`（必填，经别名表翻译为标准值）
+- `source`（必填，素材文本或文件路径，原样透传由后续阶段解析）
+- `count`（可选，数值，缺省透传空由阶段 3 按默认 1 处理）
+- `language`（可选，缺省透传空由阶段 3 按默认 中文 处理）
+- `output`（可选，输出文件路径）
 
-若 `{{ source }}` 为空、null 或仅含空白：直接输出 `[]` 并结束，**禁止**继续执行。
+**必填校验**：若无法解析出 `format` 或 `source`，将错误信息输出到 stderr 并结束，**禁止**继续执行。
 
-若 `{{ format }}` 为空或对应 prompt 文件不存在：直接输出 `[]` 并结束。
+**空 source 短路**：若 `source` 为空、null 或仅含空白：直接输出 `[]` 并结束，**禁止**继续执行。
+
+完成后 todowrite 勾单第 1 步。
 
 ### 阶段 2：加载 Prompt 和 Schema
 
@@ -42,14 +85,18 @@ metadata:
 - Prompt 文件：`references/{{ format }}.md` — LLM 创作指令
 - Schema 文件：`references/{{ format }}.schema.json5` — 输出校验规则（JSON Schema）
 
-用 `read` 工具读取两个文件内容，并**记录 schema 文件的绝对路径**（阶段 4 校验时需要）。若任一文件不存在，则输出 `[]` 并结束。
+用 `read` 工具读取两个文件内容，并**记录 schema 文件的绝对路径**（阶段 4 校验时需要）。若 `format` 为空或对应 references 文件不存在：直接输出 `[]` 并结束。
+
+完成后 todowrite 勾单第 2 步。
 
 ### 阶段 3：内容生成
 
-先判断 `{{ source }}` 是否为 JSON 字符串：若是则解析为结构化对象作为素材；否则直接作为文本素材。**禁止用 bash 解析 JSON**，直接依据内容理解处理。
+先判断 `source` 是否为现有文件路径：若是则读取文件内容作为素材；否则直接以值作为素材。再判断素材是否为 JSON 字符串：若是则解析为结构化对象作为素材；否则直接作为文本素材。**禁止用 bash 解析 JSON**，直接依据内容理解处理。
 
 将素材结合 Prompt 文件内容调用 LLM 生成符合格式的结果。**必须生成 `{{ count }}` 个 item，整体输出为 JSON 数组（即使 count=1）。** 内容语言使用 `{{ language }}`（默认中文）。
 
+`count` 解析为整数，默认 1；为空、非整数或小于 1 时按 1 处理。`language` 为空或仅含空白时按 `中文` 处理。
+
 生成时向 LLM 传入：
 - 原始素材（完整 source，已解析为可读格式）
 - Prompt 文件内容（创作指令）
@@ -57,6 +104,8 @@ metadata:
 - `{{ language }}`（输出语言）
 - 输出格式说明和示例
 
+完成后 todowrite 勾单第 3 步。
+
 ### 阶段 4：Schema 校验
 
 用 `write` 工具将待校验的 JSON 数组写入临时文件，再用 `write` 工具将 `{"data": <JSON 数组>, "schema_path": "<schema 绝对路径>"}` 写入 JSON 输入文件，stdin 重定向交给 Node.js 校验：
@@ -65,8 +114,8 @@ metadata:
 node '<技能目录>/references/validate-schema.js' < <临时 JSON 输入文件>
 ```
 
-- 若校验通过，进入阶段 6
-- 若校验失败，进入阶段 5 进行修复重试（最多 3 次）
+- 若校验通过，todowrite 勾单第 4 步，跳过阶段 5，进入阶段 6
+- 若校验失败，todowrite 勾单第 4 步，进入阶段 5 进行修复重试（最多 3 次）
 
 ### 阶段 5：校验失败时修复重试
 
@@ -80,19 +129,31 @@ node '<技能目录>/references/validate-schema.js' < <临时 JSON 输入文件>
 
 重新生成后，再次执行阶段 4 校验。**最多重试 3 次**，超过则将最后一次重试的 schema 校验错误信息及「重试 {N} 次后 schema 校验仍然失败」输出到 stderr 并结束。
 
+重试成功后 todowrite 勾单第 5 步，进入阶段 6。
+
 ### 阶段 6：输出
 
-**若校验未通过（重试耗尽）：** 将最后一次重试的 schema 校验错误信息及「重试 {N} 次后 schema 校验仍然失败」输出到 stderr 并结束。
+**若校验未通过（重试耗尽）：** 将最后一次重试的 schema 校验错误信息及「重试 {N} 次后 schema 校验仍然失败」输出到 stderr 并结束，**不写任何文件**。
 
-**若校验通过：** 将最终 JSON **数组**作为结果返回。**禁止写入任何文件**；文件写入由调用方（agent）负责。
+**若校验通过：**
+- 提供 `output` 参数：用 `write` 工具将最终 JSON 数组写入 `output` 指定文件（**禁止创建其他文件**），stdout 输出该文件路径。
+- 未提供 `output` 参数：将最终 JSON 数组直接输出到 stdout，**不写任何文件**。
+
+完成后 todowrite 勾单第 6 步。
+
+## 工具使用约束
+
+- 写文件一律用 `write` 工具；读文件用 `read` 工具。
+- 需要中间数据时，用 `write` 工具写入临时文件，再以 stdin 重定向传给 node。
+- 禁止使用未授权的 `cp`/`rm`/`mv` 等命令；需要复制、移动或删除临时文件时，一律用允许的 `node -e` 的 fs 模块完成。
+- 除技能校验所需 node 外，禁止执行其他 shell。
 
 ## 约束
 
-- 只处理已声明字段（source/format/count/language），忽略所有其他传入参数（如 `output`），**禁止**以任何形式使用它们。
-- 本技能不读取、不写入任何输出文件；仅返回 JSON 数组。
-- `{{ source }}` 为空时必须输出 `[]`，**禁止**使用 WebFetch 或其他方式获取外部内容。
-- 忽略参数中除已声明字段之外的所有字段。
-- 内部重试步骤的中间产物禁止写入任何文件。
+- 只处理已声明字段（source/format/count/language/output），忽略所有其他传入参数（如 `url`），**禁止**以任何形式使用它们。
+- **禁止使用 WebFetch 或任何网络请求获取内容**；`source` 为空时必须输出 `[]`，绝不自行获取内容。
+- 内部重试步骤的中间产物用临时文件，完成后清理，禁止写入 output 以外的任何持久文件。
+- 禁止访问外部网络。
 
 ## references/ 目录结构
 
@@ -110,4 +171,4 @@ references/
 ├── article.md               # 社交媒体图文文章 prompt
 ├── article.schema.json5
 └── ...
-```
+```

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 续跑。**