@wwkit/harness 1.0.12 → 1.0.14

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/commands/fix.md

@@ -1,9 +1,9 @@
 ---
-description: 修复问题：问题定位→修复方案→修复测试→review→总结，并写入 {root_dir}/.webwork/harness/fix/yyyy-mm-dd/问题极简标题-hhmmss.md
+description: 修复问题：问题定位→修复方案→修复测试→review→总结，并写入 <root_dir>/.webwork/harness/fix/<yyyy-mm-dd>/<问题极简标题>-<hhmmss>.md
 agent: build
 ---
 
-你（build agent）根据用户问题描述 `$ARGUMENTS` 执行 5 阶段修复流程，产出文档写入 `{root_dir}/.webwork/harness/fix/<yyyy-mm-dd>/<问题极简标题>-<hhmmss>.md`。
+你（build agent）根据用户问题描述 `$ARGUMENTS` 执行 5 阶段修复流程，产出文档写入 `<root_dir>/.webwork/harness/fix/<yyyy-mm-dd>/<问题极简标题>-<hhmmss>.md`。
 
 ## 前置
 
@@ -17,11 +17,17 @@ agent: build
    - [ ] 4. review
    - [ ] 5. 总结
 
+**收尾约定（强制）**：本 command 只有两种收尾——**修复成功**（改动 + 验证结果）或**修复失败**（根因 + 已尝试方案 + 卡点 + 建议）。**绝不假装修复成功**：修不好就如实写「未能修复」，不硬编通过。判定失败的条件（满足任一）：
+
+- 阶段 1 定位失败：无法复现，且无法定位到可疑根因（非单纯环境缺失）；
+- 阶段 2/3/4 循环累计迭代 > 5 次仍未 review 通过（其中验证失败迭代 ≤3、review 返工迭代 ≤2）。
+
 ## 阶段 1：问题定位
 
 - 用 `grep`/`glob`/`read` 定位与问题相关的代码，梳理调用链，尽量复现问题。
-- 无法复现时如实记录"未能复现"及原因（环境/数据缺失等），不臆测。
+- 无法复现时如实记录「未能复现」及原因（环境/数据缺失等），不臆测。
 - 产出结论：**问题现象 → 定位位置（file:line）→ 根因**。
+- 定位失败则停止后续阶段，直接产出文档：在「问题定位」写「未能定位」+ 原因，「总结」写需要用户补充的信息，按「修复失败」收尾。
 
 ## 阶段 2：修复方案
 
@@ -33,45 +39,50 @@ agent: build
 
 - 实施修改：遵循仓库既有代码风格，不加多余注释，只改必须改的地方。
 - 验证修复：运行相关测试/构建命令，或重跑复现用例确认症状消失。
-- 验证失败则回到阶段 2/3 迭代（自限 ≤3 轮），记录每轮结果。
+- 验证失败则回到阶段 2/3 迭代（验证失败迭代 ≤3 次），记录每轮结果。
 
 ## 阶段 4：review
 
 - 自查 diff：边界情况、兼容性、遗漏改动、是否有其他调用方受影响。
-- 复查是否根治而非掩盖症状；发现问题回到阶段 2 修正，修正后重跑阶段 3 验证。
+- **切换独立视角**：假想这是别人的 diff，列出你会拒绝它的理由（边界遗漏、兼容性破坏、副作用），再用这些理由逐条复检自己的改动。
+- 复查是否根治而非掩盖症状；发现问题回到阶段 2 修正（review 返工迭代 ≤2 次），修正后重跑阶段 3 验证。
 - 全部通过后进入阶段 5。
 
 ## 阶段 5：总结
 
-1. 生成日期目录和时间戳：`date +%Y-%m-%d` 获取日期，`date +%H%M%S` 获取时间戳（如 `{root_dir}/.webwork/harness/fix/2026-09-15/`），`mkdir -p` 创建。
+1. 生成日期目录和时间戳：`date +%Y-%m-%d` 获取日期，`date +%H%M%S` 获取时间戳（如 `<root_dir>/.webwork/harness/fix/2026-09-15/`），`mkdir -p` 创建。
 2. 标题：从问题描述提炼 ≤6 字极简短语（去空格/标点/特殊字符），如"登录接口401"。
-3. 用 `write` 写入 `{root_dir}/.webwork/harness/fix/<yyyy-mm-dd>/<问题极简标题>-<hhmmss>.md`，结构：
+3. 用 `write` 写入 `<root_dir>/.webwork/harness/fix/<yyyy-mm-dd>/<问题极简标题>-<hhmmss>.md`，结构：
 
    ```
    # <问题极简标题>
 
    - 日期：<yyyy-mm-dd>
    - 问题描述：<用户描述摘要>
+   - 结论：已修复 | 未能修复   ← 二选一，必须显式写出
 
    ## 1. 问题定位
 
-   <现象 / 位置 / 根因>
+   <现象 / 位置 / 根因；未能定位时写原因>
 
    ## 2. 修复方案
 
-   <方案与取舍>
+   <方案与取舍；未能修复时逐条列出已尝试的方案>
 
    ## 3. 修复测试
 
-   <改动摘要 + 验证命令与结果>
+   <改动摘要 + 验证命令与结果；未能修复时写每轮验证失败的原因>
 
    ## 4. Review
 
-   <自查结论>
+   <自查结论 + 独立视角复检结果>
 
    ## 5. 总结
 
-   <影响面、后续建议>
+   <已修复：影响面、后续建议>
+   <未能修复：卡点、需要用户提供的信息、建议的下一步方向>
    ```
 
-4. `todowrite` 确认 5 项全部勾完，向用户输出：**文档路径** + 修复结论摘要（改动文件、验证结果）。
+4. `todowrite` 确认 5 项全部勾完，向用户输出：**文档路径** + 结论摘要。
+   - 修复成功：改动文件、验证结果。
+   - 修复失败：根因、已尝试方案、卡点、建议。

package/package.json

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