plan-recovery

计划恢复

在 PlanWeave 执行状态异常时使用此技能。不要执行常规实现或审查工作。

快速开始

1. 停止分派依赖此状态的工作。
2. 确定 CLI 入口，并运行 <pw> help recovery 获取准确命令。
3. 检查包、状态、结果以及 current/status/explain 输出；只有在需要排查状态/结果一致性问题时才运行 doctor。
4. 区分计划缺陷与运行时状态/结果漂移。
5. 对于能表达所需修复的状态写入，使用准确的恢复命令；直接检查文件以获取证据。
6. 报告已修复的问题、仍不安全的部分，以及协调者接下来的操作。

Doctor 的适用范围

• doctor 用于检测范围有限的运行时状态/结果一致性问题，例如过时的 current 引用、孤立结果，以及状态/索引中的运行记录不一致。
• doctor --repair 不是通用的计划修复工具。
• 不要使用 doctor 修复错误的依赖关系、不安全的并行化、缺失的提示词、错误的审查门设计、不清晰的任务/区块粒度、无效的项目图，或不符合架构的包结构。
• 对于计划缺陷，报告 NEEDS_PLAN_UPDATE，并指导手动编辑 Plan Package、提示词、依赖关系或审查门。

先诊断

检查：

• 活跃的 current 引用和当前反馈。
• 区块/任务状态和认领提示。
• 最新运行索引与状态区块中的 lastRunId 是否一致。
• 孤立的结果工件。
• 过时的 current 引用。
• 已分歧或已阻塞的引用及其原因。
• 审查尝试、反馈状态和重新审查状态。
• 重试属于相同内容的幂等操作，还是新的工作修订。

恢复操作

• 在修复状态/结果之前使用 doctor；仅当报告的修复范围有限且有证据支持时才使用 repair。
• 如果 CLI 输出不完整、相互矛盾，或过于简略而无法诊断，请直接读取包/状态/结果。
• 如果 CLI 无法安全地认领/提交，请让协调者读取包/状态/结果，并手动分配准确的引用，直到可以安全回写。
• 对于外部前置条件或临时暂停，使用 blocked/unblocked 命令。
• 如果实现现状不再符合 Plan Package，使用 diverged/resolve-divergence。
• 对于提交部分成功的情况，在创建新运行或尝试前，先查找已持久化的报告/结果工件。
• 如果反馈已解决但仍为 current，在提交任何内容前重新检查 current/status。
• 对于并行不匹配，先比较顺序执行与并行执行时的可认领状态，再判定无事可做。
• 如果并行不匹配源于包设计，请手动调整依赖关系、并行安全设置或审查门位置，而不要运行 repair。

手动回退方案

直接检查文件是恢复工作的一部分：

• 如果存在 project-graph.json，请读取它；同时读取每个画布的 package/manifest.json、源提示词、state.json、results/，并在结构可疑时检查 planweave schema project/manifest/state/layout。
• 在信任索引前，验证元数据属于同一任务/区块/运行。
• 使用 CLI/运行时命令执行机械性的工作区操作、验证、恢复事务以及运行时状态/结果变更。
• 如果修复属于计划更新，请在 CLI 返回的工作区路径中直接编辑 Plan Package 语义文件：project-graph.json 中的依赖关系、画布 manifest.json 中的任务/区块/边/验收条件/提示词路径，以及源提示词 Markdown。
• 如果精确表达语义变更，请使用范围有限的 CLI 编辑命令；否则直接更新源包文件和提示词。
• 只有在没有恢复命令能表达修复、确切不变量已知且用户接受风险时，才直接编辑 state.json 或 results/。
• 直接编辑计划后，对已编辑的画布运行画布范围内的验证；如果修改了 project-graph.json、画布边或 crossTaskEdges，则运行项目验证。
• 保留证据路径，并说明任何直接写入状态/结果的操作。

停止条件

遇到以下情况时，停止并要求用户更新计划：

• 软件包依赖项或提示词有误。
• 无法在不猜测的情况下修复状态。
• 多个当前引用与实际工作归属相冲突。
• 结果元数据指向了错误的区块或任务。
• doctor 执行后，审核／反馈状态仍自相矛盾。
• 恢复命令会掩盖真实的产品或契约缺陷。

恢复报告

报告以下内容：

• 结论：RECOVERED、NEEDS_PLAN_UPDATE 或 BLOCKED。
• 症状和证据。
• 执行的命令。
• 检查的文件。
• 已进行或有意跳过的修复。
• plan-coordinator 接下来可以安全执行的命令。