@wwkit/harness 1.0.16 → 1.0.18

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/todo-dispatch/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: todo-dispatch
+description: 派发阶段：写 brief、记录 base、派发 implementer（explore 只读 / general 可写，background=true）、处理返回 status。主循环每派一个任务时加载。
+license: MIT
+metadata:
+  workflow: sequential
+---
+
+# todo-dispatch 技能
+
+## 输入
+
+| 输入 | 说明 |
+|------|------|
+| `doc_dir` | 产物目录绝对路径 |
+| `plan.md` | 任务计划文件（`<doc_dir>/plan.md`） |
+| `task_id` (`T<N>`) | 当前任务编号 |
+| `root_dir` | 工程根目录 |
+
+## 工作流程
+
+### 步骤 1：派发前准备
+
+```bash
+# 记录 base
+base=$(git rev-parse --short=7 HEAD)
+```
+
+写入 Ledger：`T<N>: base=<base>`
+
+从 plan.md 提取当前任务条目，写入 brief 文件 `<doc_dir>/task-<N>-brief.md`：
+
+```markdown
+# Task <N>: <goal>
+
+## Files
+<files>
+
+## Accept Criteria
+<accept>
+
+## Verify
+<verify>
+
+## Writable
+<writable>
+
+## Forbidden
+<forbidden>
+
+## Budget
+<budget> tool calls max
+```
+
+指定 report 路径：`<doc_dir>/task-<N>-report.md`
+
+**todowrite 全量替换**：派发当前任务前，用 `todowrite` 全量替换整个清单，把当前任务标 `in_progress`。
+
+### 步骤 2：派发 implementer
+
+用 `task` 工具派发，`background: true`。subagent 类型按任务 `readonly` 决定：`readonly=true` → `explore`（只读调研），`readonly=false` → `general`（可写实现）。
+
+#### 只读调研（explore）prompt 模板
+
+```
+你是 explore 只读 subagent，执行代码库调研/搜索/理解工作。
+
+## Task
+Read your task brief first: <brief_file>
+It contains the full task text.
+
+## Constraints
+1. **只读**：绝不提交、绝不改写工作树/index/HEAD，只做搜索/读取/理解。
+2. **工具调用上限**：最多 <budget> 次。到限必须停止。
+3. **证据要求**：返回结论时必须附 file:line 证据。
+4. **范围**：只调研 brief 指定的范围，不发散。
+5. **不派发 subagent**：你的工作不嵌套，不派发任何 subagent。
+
+## Report Format
+Write your full report to <report_file>:
+- 调研发现
+- 关键 file:line 证据
+- accept 逐条对照结果
+- 顾虑或问题
+
+Then report back with ONLY (≤10 lines):
+- Status: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT | ESCALATE
+- 一行结论摘要
+- 关键 file:line 证据（≤5 条）
+- 工具调用次数（如 "used 12/<budget>"）
+- 报告文件路径
+
+Work from: <root_dir>
+```
+
+#### 可写实现 subagent prompt 模板
+
+```
+你是 general 可写 subagent，执行具体实现工作。
+
+## Task
+Read your task brief first: <brief_file>
+It contains the full task text.
+
+## Context
+<一句话：此任务在项目中的位置>
+
+## Constraints
+1. **writable 白名单**：只 add/commit <writable> 中的文件。
+2. **forbidden 清单**：不触碰 <forbidden> 中的文件和操作。
+3. **工具调用上限**：最多 <budget> 次。到限必须停止并报告 ESCALATE。
+4. **重复读取**：同一文件不读超过 3 次。
+5. **重复测试**：同一测试不连续运行超过 3 次。
+6. **不派发 subagent**：你的工作不嵌套，不派发任何 subagent。
+7. **升级触发**：需要架构决策/无法理解代码/计划未预见的大量重构 → 停止报告 BLOCKED/ESCALATE。
+
+## Your Job
+1. Implement exactly what the task specifies
+2. Write tests (following existing patterns)
+3. Verify implementation works (run <verify>)
+4. **Commit ALL your changes**——任务结束时该任务所有修改必须已提交（`git status` 干净），不残留脏文件给下一个任务
+5. Self-review (read your own diff)
+6. Report back
+
+## Report Format
+Write your full report to <report_file>:
+- 实现了什么
+- 验证结果（verify 命令输出 + 测试结果）
+- accept 逐条对照结果
+- 变更文件
+- 自审发现
+- 顾虑或问题
+
+Then report back with ONLY (≤15 lines):
+- Status: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT | ESCALATE
+- Commits（短 SHA + subject）
+- 一行验证摘要（如 "14/14 passing"）
+- 工具调用次数（如 "used 18/<budget>"）
+- 顾虑（如有）
+- 报告文件路径
+
+Work from: <root_dir>
+```
+
+### 步骤 3：并行派发（只读调研用 `explore`，MUST 并行）
+
+**MUST**：plan.md 中存在多个可并行的只读任务（readonly=true，无依赖或依赖已满足）时，**不得逐个串行派发**——必须在同一条消息中一次性并行派发。
+
+**并行单位**：一个 subagent = 一个任务。**绝不**把多个可并行任务合并进一个 subagent 的 prompt。
+
+**分批规则**：可并行任务数 ≤5 → 一批并行派完；>5 → 分多批，每批 ≤5，同批一条消息并行发出，**前批全部返回后再派下一批**。
+
+1. 在同一条消息中发出多个 `task` 调用，每个 `background=true`
+2. 写 Ledger：每个任务各写 `T<N>: base=<base>`
+3. 等待全部返回后再逐个处理
+4. 不边收边派——全部返回后才进入下一步
+
+> 可写任务（readonly=false）保持串行：派发后等 review close 才派下一个。
+
+### 步骤 4：处理返回
+
+subagent 返回后，**可写任务先做工作区验证**（见下），再写 Ledger 状态行、按 status 分派。
+
+**工作区验证（仅可写任务，readonly=false，在判定 status 前执行）**：
+
+```bash
+git status --porcelain
+```
+
+- 干净 → 按 status 表处理
+- **脏 → 自动 commit 所有修改**：这些改动由本任务 subagent 产生，属 agent 自主提交，`git add -A && git commit -m "<T<N> auto-commit residual changes>"`，不残留给下一任务
+- 脏文件超出 writable 白名单 → `git checkout -- <file>` 恢复，并在 report 记录 Critical finding
+
+| Status | 动作 |
+|--------|------|
+| `DONE` | 生成 review package，进入 todo-review |
+| `DONE_WITH_CONCERNS` | 读 report 中的顾虑，自主裁决：correctness/scope 问题先处理再 review；observation 类记录后继续 review |
+| `NEEDS_CONTEXT` | 补充上下文，重新派发（同模型，最多 1 次） |
+| `BLOCKED` | 评估阻塞：context 问题→补上下文重派；能力问题→换更强模型重派；任务太大→拆分后重派；计划错误→裁决修正后重派 |
+| `ESCALATE` | 评估：换模型/拆任务/重规划（加载 todo-recovery） |
+
+**异常处理**：
+- 空输出/无 status → 重新派发（同模型，最多 1 次），再失败按 BLOCKED 处理
+- 绝不忽略升级或强制同一模型无变化重试
+
+### 步骤 5：有界等待（防超时卡死）
+
+派发后不静默无限等待，也不短轮询：
+
+```
+有本地工作（更新 Ledger、准备下一个 review package）→ 继续做
+真正空闲 → 等待 5-10 分钟
+超时 → 检查 subagent 状态
+  - 完成 → 处理返回
+  - 未完成 → 标记 BLOCKED，走重试/换模型/拆任务
+  - 丢失 → 标记 ESCALATE，重规划
+```
+
+## 输出
+
+- `<doc_dir>/task-<N>-brief.md`（派发前渲染）
+- `<doc_dir>/task-<N>-report.md`（subagent 写入）
+- Ledger 中 `T<N>: base=` / 状态行
+- 触发下一步：status=DONE/DONE_WITH_CONCERNS → 生成 review package → todo-review
+
+## 约束
+
+- prompt 必须自包含：所有占位符展开为绝对路径
+- 禁止：粘贴计划全文到 prompt、粘贴之前任务摘要到后续 prompt、让 subagent 读整个计划文件
+- 串行硬规则：下一个可写任务必须在上一任务 review close 后才派发，base = 上一任务 HEAD
+- 只派发与处理返回，不审查、不 fix、不改源码

package/skills/todo-finalize/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: todo-finalize
+description: 收尾阶段：全分支 Final Review + 最终验收 + 综合交付（整合产物 + 裁决清单 + 归档）。所有任务 review close 后加载。
+license: MIT
+metadata:
+  workflow: sequential
+---
+
+# todo-finalize 技能
+
+## 输入
+
+| 字段 | 说明 |
+|------|------|
+| `target` | 用户目标（验收标准） |
+| `root_dir` | 工程根目录 |
+| `doc_dir` | 本次 run 产物目录 |
+| `initial_base` | 本次运行最初的 base |
+| Ledger | `<doc_dir>/progress.md`，含全部进度 + rulings |
+
+## 工作流程
+
+### 步骤 1：Final Review
+
+#### 1a：生成全分支 review package
+
+```bash
+merge_base=<initial_base>  # 本次运行最初的 base
+final_diff="<doc_dir>/final-review-<merge_base7>..<head7>.diff"
+git log --oneline <merge_base>..HEAD > "$final_diff"
+echo "" >> "$final_diff"
+git diff --stat <merge_base>..HEAD >> "$final_diff"
+echo "" >> "$final_diff"
+git diff -U10 <merge_base>..HEAD >> "$final_diff"
+```
+
+#### 1b：派发 final reviewer（串行：全分支一个 reviewer）
+
+用 `task` 工具派发，`subagent_type: "general"`，`background: true`。
+
+#### Final reviewer prompt 模板
+
+```
+你是最终审查 subagent，审查整个分支的全部改动。这是全分支审查，不是单任务审查。
+
+## What Was Requested
+Target: <target>
+
+## Diff Under Review
+Base: <merge_base>
+Head: <HEAD>
+Diff file: <final_diff>
+
+Read the diff file once. Do not re-run git commands. Do not crawl the broader codebase.
+
+## Ledger
+Read the ledger for context on parked findings and rulings: <doc_dir>/progress.md
+
+## Your Job
+1. Review the full branch diff for correctness, completeness, and quality
+2. Triage parked findings and deferred minors: which must be fixed before delivery?
+3. Check cross-task interactions and integration issues
+
+## You Do Not Dispatch Subagents
+## Read-only review. Do not mutate the working tree, index, HEAD, or branch.
+
+## Output
+Write your review to <doc_dir>/final-review.md:
+
+### Branch Review
+- Overall assessment of the complete change
+
+### Parked/Deferred Triage
+For each parked/deferred item from the ledger: must fix before delivery | safe to defer
+
+### Issues
+#### Critical (Must Fix)
+#### Important (Should Fix)
+#### Minor (Nice to Have)
+
+### Assessment
+**Branch quality:** Approved | Needs fixes
+**Reasoning:** [1-2 sentences]
+
+Then report back with ONLY (≤15 lines):
+- Verdict: Approved | Needs fixes
+- Finding count (Critical/Important/Minor)
+- One-line summary
+- Review file path
+```
+
+#### 1c：处理 final review 结论
+
+| 结论 | 动作 |
+|------|------|
+| Approved | 进入步骤 2 |
+| Needs fixes | 一次 fix dispatch + 一次 scoped re-review |
+
+#### 1d：Final fix（如有 findings）
+
+只做**一次** fix dispatch（不是 per-finding）+ **一次** scoped re-review。
+
+```bash
+final_review_head=<HEAD at final review time>
+fix_base=$final_review_head
+# 派发 fix implementer（general, background=true）
+# 生成 scoped diff: <doc_dir>/final-fix-review-<fix_base7>..<head7>.diff
+# 派发 scoped re-reviewer（general, background=true）
+```
+
+残留 load-bearing findings → 报告用户（这是唯一需要用户参与的情况）。
+
+### 步骤 2：最终 target 验收（MUST 派 subagent 执行）
+
+**MUST**：验收运行（跑测试 / 构建 / 执行 verify 命令）一律由 subagent 执行——这属于「跑测试」，主 agent 不亲自跑。
+
+用 `task` 派发一个只读 verification subagent（`subagent_type: "general"`，`background=true`；单个，全 target 一个验证者，验收通常是整体命令，不并行）：
+
+```
+你是只读验证 subagent，执行最终 target 级整体验收。
+
+## Target
+<target>
+
+## Verify 命令
+- 优先执行单一可执行验收命令
+- 否则按 plan.md 汇总各任务 verify 命令，逐个执行
+
+## Constraints
+1. **只读**：不提交、不改写工作树/index/HEAD，只运行验证命令并记录结果
+2. **不派发 subagent**：你的工作不嵌套
+3. **工具调用上限**：最多 <N> 次，到限停止
+
+## Report
+把验收结果写入 <doc_dir>/final-verification.md：
+- 每个 verify 命令的输出摘要（pass/fail + 关键行）
+- 逐条对照 target 的验收结论
+- 阻塞或顾虑
+
+Then report back with ONLY (≤10 lines):
+- Verdict: PASS | FAIL | BLOCKED
+- 一行结论
+- 报告文件路径
+```
+
+主 agent 读 `<doc_dir>/final-verification.md`，把结论写入 `final-review.md` 的「整体验收结果」段。
+
+退出判据（三者缺一不可）：
+1. 所有任务 done + review 通过
+2. final review 通过（或残留已报告用户）
+3. 整体验收 PASS
+
+### 步骤 3：综合交付
+
+#### 3a：整合产物
+
+收集提交历史 + diff 路径 + final-review 摘要：
+
+```
+提交历史: <initial_base7>..<head7>
+全分支 diff: <doc_dir>/final-review-<merge_base7>..<head7>.diff
+Final review: <doc_dir>/final-review.md
+```
+
+#### 3b：裁决清单
+
+从 Ledger 收集全部 rulings，按发生顺序列出，每条附理由和代价：
+
+```
+## Rulings I made
+
+1. Ruling: <决定> — <原因> — <错了的代价>
+2. Ruling: <决定> — <原因> — <错了的代价>
+...
+```
+
+**这是用户审阅 agent 决策的唯一入口**——用户看到完整清单，可以逐条否决。
+
+#### 3c：向用户输出
+
+```
+全部 N 个任务完成，最终审查通过。
+
+提交历史: <initial_base7>..<head7>
+分支: <branch>
+diff: <doc_dir>/final-review-<merge_base7>..<head7>.diff
+
+## Rulings I made
+<裁决清单>
+
+## 残留问题（如有）
+<load-bearing findings that need user attention>
+```
+
+#### 3d：归档
+
+```bash
+# 保留关键产物到归档目录
+archive="<root_dir>/.webwork/todo/archive/<run_id>/"
+mkdir -p "$archive"
+cp <doc_dir>/plan.md "$archive/"
+cp <doc_dir>/progress.md "$archive/"
+cp <doc_dir>/task-*-report.md "$archive/" 2>/dev/null
+cp <doc_dir>/task-*-review.md "$archive/" 2>/dev/null
+cp <doc_dir>/final-review.md "$archive/" 2>/dev/null
+cp <doc_dir>/final-verification.md "$archive/" 2>/dev/null
+cp <doc_dir>/final-fix-report.md "$archive/" 2>/dev/null
+
+# 删除临时文件（brief、主 review diff、rereview、final diff）
+rm -f <doc_dir>/task-*-brief.md
+rm -f <doc_dir>/task-*-review-*.diff
+rm -f <doc_dir>/task-*-rereview-*.md
+rm -f <doc_dir>/task-*-rereview-*.diff
+rm -f <doc_dir>/final-review-*.diff
+rm -f <doc_dir>/final-fix-review-*.diff
+```
+
+默认保留归档；用户显式要求清理时才删除。
+
+## 输出
+
+- `<doc_dir>/final-review.md`（含整体验收结果段）
+- `<doc_dir>/final-verification.md`（最终验收报告）
+- `<doc_dir>/final-fix-report.md`（若有 findings）
+- `<doc_dir>/final-fix-review-*.diff`（若 scoped re-review）
+- 向用户输出的结果摘要 + 全部裁决清单
+- 归档目录 `<root_dir>/.webwork/todo/archive/<run_id>/`
+
+## 约束
+
+- final reviewer 最多 30 次工具调用，到限必须停止
+- final reviewer 写操作白名单 = 仅 `<doc_dir>/final-review.md`
+- final reviewer 不重跑测试
+- 有 findings 时只做一次 fix dispatch + 一次 scoped re-review，无第二次
+- 最终 target 验收运行强制，且**必须派只读 subagent 执行**（主 agent 不亲自跑测试），三者缺一不可
+- 不 push / 不 merge——交付即当前分支上的提交串，推送由用户决定
+- 裁决清单必须显式列出，不随归档消失
+- 归档即终止本 run