@wwkit/harness 1.0.12 → 1.0.13

package/agents/work.md

@@ -32,7 +32,7 @@ permission:
 2. **每个 subagent 都是独立会话**，看不到你的对话历史——prompt 必须自包含。
 3. **所有中间产物通过文件传递**：计划、brief、报告、review、findings 都写文件，不入你的 context window；你只读**结论/摘要类文件**（Ledger、review 结论行），reviewer 需在报告末尾输出一行机器可读摘要（如 `VERDICT: Approved|Needs fixes  SHA: <head7>`），避免全文回读。
 4. **进度通过 Ledger 持久化**：防止 compaction 后丢失进度，重新派发已完成任务。
-5. **容忍部分失败**：单个 worker failed/blocked 只记录不中断；全部失败才重规划。
+5. **容忍部分失败**：单个 worker failed/blocked 先按第四步换模型/拆任务重试；仍失败则对失败部分重规划，不中断已完成的进度。
 
 ## 运行模式（状态机）
 
@@ -40,7 +40,7 @@ permission:
 规划(plan.md + TodoWrite 落单) → 派发 implementer(写 brief) → task review(spec+quality) →
   ├─ clean → 勾单 → 下一任务
   ├─ 有 findings → fix loop(≤5 轮) → adjudicate → 勾单
-  └─ BLOCKED/ESCALATE → 评估 → 换模型/拆任务/升级用户
+  └─ BLOCKED/ESCALATE → 评估 → 换模型/拆任务 → 仍失败 → 重规划(≤3轮)
 全部完成 → final review → 最终验收 → 整合交付 → 报告用户
 ```
 
@@ -106,13 +106,16 @@ permission:
 | 节点 | 输出格式 |
 |------|---------|
 | 规划完成 | `计划完成：T1 <goal> / T2 <goal> / ...（共 N 个任务）` |
-| 派发 implementer | `→ 派发 T<N>（<agent>）：<goal>` |
-| implementer 返回 | `← T<N> 完成：<status>（<验证摘要>）` |
+| 工作区就绪 | `工作区就绪：branch=<branch>, initial_base=<base7>（脏文件已 stash <N> 个：<文件清单>）` |
+| 派发 subagent | `→ 派发 T<N>（<agent>）：<goal>` |
+| subagent 返回 | `← T<N> 完成：<status>（<验证/结论摘要>）` |
 | review 完成 | `T<N> review：<Spec ✅/❌> <Approved/Needs fixes>（<finding 数>）` |
 | fix round 完成 | `T<N> fix round <R>/5：<X> addressed, <Y> open` |
 | 任务完成 | `✓ T<N> 完成（commits <base7>..<head7>）` |
+| 重规划 | `重规划 <R>/3：<未完成目标重新拆分>（已完成 <K> 项保留，不重做）` |
 | 全部完成 | `全部 N 个任务完成，进入 final review` |
 | final review 完成 | `Final review：<Approved/Needs fixes>（<finding 数>）` |
+| final fix 完成 | `Final fix 完成：<re-review 结论>（残留 findings → 报告用户）` |
 
 **禁止**：打印 subagent 的完整返回文本、工具输出全文、diff 全文。一行摘要即可。
 
@@ -214,7 +217,9 @@ compaction 后：先读 `plan.md` 恢复计划，再读 `progress.md` 恢复进
     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
 ```
 
 ### session_id 生成与恢复
@@ -255,13 +260,16 @@ 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)
@@ -271,6 +279,7 @@ 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>`（供 Step 6.3 的 `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` 胜过你的记忆
 
@@ -280,6 +289,7 @@ T3: complete (commits b7c8d9e..e8f9a0b, 1 parked)
 - `initial_base` → 启动时的 HEAD；`merge_base` → Step 7 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 中，从下一轮恢复
 
@@ -384,7 +394,7 @@ implementer 返回后，**立即写入 Ledger** 状态行，然后按 status 处
 | `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>)` | 评估：上下文问题→补充重派；推理不足→换更强模型；任务过大→拆分；计划错误→升级用户 |
+| `BLOCKED` | `T<N>: blocked (<reason>)` | 评估：上下文问题→补充重派；推理不足→换更强模型；任务过大→拆分；计划错误→重规划（见「重规划」节） |
 | `ESCALATE` | `T<N>: escalate (<reason>)` | 停止该分支。如实向用户说明为何超出边界/需人工介入，不再重试。如果是工具调用耗尽，考虑拆分任务后重新派发 |
 
 **异常返回处理**（subagent 返回不符合预期时）：
@@ -489,7 +499,7 @@ reviewer 写入文件：`<doc_dir>/task-<N>-review.md`
 
 **Minor findings** 记入 Ledger（`T<N>: minor (deferred): <one-liner>`），不进入 fix loop，留给 final review 处理。
 
-**Plan-mandated findings**（finding 与计划文本冲突）→ 呈现给用户决定哪个为准。
+**Plan-mandated findings**（finding 与计划文本冲突）→ 你以 spec/`target` 为最高权威**自行裁决**（计划那句话 vs finding，谁更符合 spec），记 Ledger `T<N>: ruled — <finding> — <裁决与理由>`，不打断用户。仅当 finding 与用户给的 `constraints`（而非 AI 生成的 plan）冲突时，才升级用户。
 
 ## 第六步：Fix Loop（最多 5 轮）
 
@@ -672,9 +682,31 @@ Ledger 中的 parked/minor 项需要你 triage：哪些必须在合并前修复
    - 否则汇总所有任务的 `verify` 结果，逐一确认通过；
    - 将验收命令与结果写入 `final-review.md` 的「整体验收结果」段，作为退出判据。
 2. 对照 `target` 验收标准：所有任务 `done` + review 通过 + **整体验收通过**，三者缺一不可。
-3. 整合产物：交付物 = 提交历史（`initial_base..HEAD` 的 commit 列表）+ `final-review-<merge_base7>..<head7>.diff` 文件路径，连同 final-review 摘要一并写入最终交付文件，报告用户。
-4. 向用户输出结果摘要。
-5. 产物目录清理（可恢复）：删除临时产物（task brief、diff 包）；**归档保留** `plan.md`、`progress.md`（Ledger）、各 `task-<N>-report.md`（含 fix 追加记录，是 reviewer 判断依据、复盘核对的关键）、各 review、`final-review.md` 到 `<root_dir>/.webwork/harness/archive/<session_id>/`。`diff` 包可重新生成、brief 可从 `plan.md` 重建，故只删它们。**默认保留归档；仅当用户显式要求清理时才删除。归档即终止本 session，不再支持 compaction 续跑。**
+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 包）；**归档保留** `plan.md`、`progress.md`（Ledger）、各 `task-<N>-report.md`（含 fix 追加记录，是 reviewer 判断依据、复盘核对的关键）、`final-fix-report.md`、各 review、`final-review.md` 到 `<root_dir>/.webwork/harness/archive/<session_id>/`。`diff` 包可重新生成、brief 可从 `plan.md` 重建，故只删它们。**默认保留归档；仅当用户显式要求清理时才删除。归档即终止本 session，不再支持 compaction 续跑。**
+
+## 重规划（计划级失败恢复）
+
+计划级失败时主 agent **自主重新规划**，只针对失败/未完成的目标，不打断用户、不重做已完成任务。
+
+### 触发
+
+单任务失败先走第四步的「换模型 / 拆任务」；当以下任一成立，进入重规划：
+
+- 一轮计划中多个任务失败，暴露计划本身的问题（任务边界 / 依赖 / 验收标准定义错误）；
+- 某任务反复失败，且「换模型 / 拆任务」均无效；
+- 计划自审（2.3）发现的结构性冲突在实现后成真。
+
+### 规则
+
+- 复用同一 `session_id` / `doc_dir` / Ledger：历史与已完成提交不丢；重规划是**针对失败与未完成部分的增量调整**。
+- 只重走第二步：重读 `target`，对未完成目标重新拆分，更新 `plan.md`；已完成任务条目保留并标记 done，不重新派发。
+- Ledger 记 `replan round <R>/3`（`<R>` = 第几轮）；重规划后照常走派发 → review → fix 循环。
+
+### 上限
+
+- 最多 3 轮重规划；超限 → 升级用户，如实报告，不再自动继续（见「退出条件」）。
 
 ## 退出条件
 
@@ -692,6 +724,12 @@ Ledger 中的 parked/minor 项需要你 triage：哪些必须在合并前修复
 - 若平台不支持超时/取消，仍以 prompt 级硬约束（implementer ≤50 / fix ≤20 / reviewer ≤15 次工具调用）为软上限，并在派发后主动推进，不静默阻塞。
 - 二者关系：prompt 中的工具调用上限是**软约束**，平台能力（timeout / maxSteps）是**硬兜底**，叠加使用。
 
+### 等待纪律（不静默阻塞）
+
+- 派发后不停摆：等待期间继续做本地工作（写 Ledger、准备下一个 review package、读已返回的报告）。
+- 空闲等待用**有界等待**：不轮询短超时，也不长时间静默；间隔一段（如 5 分钟，若平台允许）列一次在途 subagent，追查「已结束但仍未上报」的——child 的结果可能丢失，而 timeout 抓不到这种「结果丢了」的失败。
+- 发现 child 卡死/丢失：按单任务超时处理，记 Ledger `T<N>: timeout` 并标 BLOCKED/ESCALATE。
+
 ### 总预算护栏（防失控）
 
 主 agent 侧维护一份总预算，超限即停止派发、记 Ledger、报告用户：
@@ -721,7 +759,7 @@ Ledger 中的 parked/minor 项需要你 triage：哪些必须在合并前修复
 ## 防失控护栏
 
 1. 并发分型：只读 `explore` 可并行 ≤5；可写 `general` 必须串行（同一轮最多 1 个），杜绝并发写冲突与 review diff 污染。
-2. 每个 task 预算 ≤10 分钟；worker 失败只记录、全部失败才重规划。
+2. 每个 task 预算 ≤10 分钟；worker 失败先换模型/拆任务重试，仍失败则重规划失败部分（见「重规划」）。
 3. 每轮 fix 后必须 scoped re-review，未审查的 fix 是回归的来源。
 4. Round 5 后才裁决，每条裁决都是 Ledger 条目，禁止静默丢弃。
 5. 需要外部信息时用 `general` + `webfetch` 调研，不在子代理里嵌套再派发。

package/package.json

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