[PR Flow] 优化 stale local review fragments 的 agent 接手体验

[liuli195]

详细背景

PR #131 的流程中，第一次运行：

make pr-submit TITLE="策略：兼容模拟盘缺失参数"

流程正确停在 stale local review fragments：

DISPATCH_REQUIRED: local-review: standards fragment head is stale; local-review: standards fragment diff is stale; local-review: spec fragment head is stale; local-review: spec fragment diff is stale
reason_code: FRAGMENT_MISSING
phase: submit_fragments
retryable: true
next_actions:
- dispatch review agents to regenerate fragments

需要先澄清：#120 已经解决了底层安全能力问题。当前仓库已有：

• .local/pr-flow/review-fragments-handoff.json，能给出 current head、current diff、目标 fragment 和 builder 输入模板。
• build-review-fragment，能把结构化 reviewer verdict 安全落成 current-head fragment。
• head/diff 校验、P0/P1 lifecycle、Security metadata 校验等约束。

本 issue 不认为 #120 失败，也不要求用脚本替代 agent review 能力。脚本不能替代 Standards / Spec / Security 的判断，也不能自动从旧 fragment、聊天总结或空 completion 推断 pass。

本 issue 记录的是 #120 之后仍存在的体验/编排问题：当 stale fragments 发生时，主 agent 仍需要执行较多机械步骤：

• 读取 handoff。
• 派发 Standards / Spec 子 agent。
• 等待并判断 reviewer 结论。
• 单独完成 Security review 判断。
• 把 reviewer verdict 整理为 payload。
• 调用 builder 写入 fragments。
• 再次运行 pr-submit。

这些步骤本身合理，但手工衔接成本较高，容易消耗时间和 token，也容易在 payload 字段、reviewer 标识、security metadata 等地方出现机械错误。

产品解决方案

优化 stale local review fragments 的 agent 接手体验：让 pr-submit 输出更清晰、更可执行的 agent handoff，而不是试图自动替代 agent review。

目标是让 agent 更少做机械拼装，更多做必须由 agent 完成的判断：

• Standards / Spec 是否无发现或有什么 finding。
• Security diff 风险和 verdict。
• P0/P1 finding 是否 fixed / false_positive / open。

不改变的边界：

• 不跳过 review。
• 不自动生成 pass verdict。
• 不从旧 fragment 推断 current verdict。
• 不让脚本调用或替代 reviewer。
• 不降低 [PR Flow] 为本地 review fragments 增加 current-head 映射和预检入口 #120 的 head/diff 和 schema 校验。

详细技术实现方案

1. 改进 review-fragments-handoff.json 的可读性和可执行性：
   • 每个 role 给出明确的 agent task prompt。
   • 明确 fixed point、diff command、changed files、目标 fragment path。
   • 明确 payload 必填字段和允许值。
2. 增加 agent-only payload skeleton 生成能力，但只生成待填模板：
   • 自动填 current head / diff / source / target path。
   • reviewer、verdict、findings、security_review 仍必须由 agent 填写。
   • skeleton 明确标记 TODO，不能直接通过 builder。
3. 改进 pr-submit 的 next_actions：
   • 区分“必须重新 review”的 diff stale 和“可 refresh”的 same-diff head stale。
   • 输出下一步建议命令和 handoff 路径。
4. builder 错误信息更贴近 agent 操作：
   • 缺 reviewer、缺 security tool、head/diff mismatch 时给出具体修复字段。
5. 增加回归测试：
   • stale diff handoff 包含 role-level task prompt。
   • payload skeleton 不能直接写 fragment。
   • skeleton 自动填 head/diff，但 verdict 必须由 agent 提供。
   • Security skeleton 缺 verdict/tool 时 builder 拒绝。
   • same-diff head stale 路径仍不强迫重新 review。

Acceptance criteria

• stale fragments handoff 能直接指导 agent 派发 review 和填写 payload。
• agent 不需要手工复制 current head / diff 到每个 payload。
• payload skeleton 不能被当作 pass verdict 使用。
• reviewer verdict、findings 和 security judgment 仍必须由 agent 提供。
• pr-submit 输出能区分 diff stale 与 same-diff head stale 的下一步。
• 不改变 [PR Flow] 为本地 review fragments 增加 current-head 映射和预检入口 #120 已有 builder / handoff 的安全边界。
• PR 策略：兼容模拟盘缺失参数 #131 的复现场景有测试或文档示例。

Blocked by

#120 已完成。本 issue 是 #120 后续体验优化，不是底层能力缺失修复。

[liuli195]

Duplicate of #120. 本 issue 描述的 stale local review fragments handoff / builder 接手刷新流程，已由 #120 覆盖；PR #131 复现场景已补充到 #120。

[liuli195]

复现补充：PR #133 review fragment 接手仍有较高手工拼装成本

本次会话中，PR #133 需要为 current head 生成 Standards / Spec / Security fragments。实际步骤包括：

1. 派发 Standards 子 agent。
2. 派发 Spec 子 agent。
3. 等待并核对两个 agent 的 completed 结论。
4. 单独做 security diff 判断。
5. 手工计算 current diff hash。
6. 手工准备 3 个 builder payload。
7. 调用 build-review-fragment 写入 fragments。
8. 清理临时 payload。
9. 重新运行 pr-submit。

本次还出现一个可观测性问题：用户侧只看到一个子 agent completed 通知，因此要求主 agent 重新确认两个子 agent 是否都返回。主 agent 通过再次 wait_agent 才确认 Standards 和 Spec 两个 agent 都是 completed/pass。

这个场景没有破坏 fragment 安全边界，最终 fragments 也绑定了 current head/diff。但机械步骤仍然多，且 agent receipt 对用户不够直观，导致需要额外确认和 token 消耗。

相关 PR：#133
head：c87d1e4360e14f433c9fca6a430169dc82648df2

[liuli195]

This was generated by AI during triage.

复现补充：PR #135 本地 review / fragment 接手耗费大量机械步骤

本次 PR #135 中，当前 head 多次因为修复 review findings 而变化，每次都需要重新完成 Standards / Spec review，并重新映射 current head / diff 的 fragments。实际机械步骤包括：派发两个 reviewer、等待子 agent、核对结论、计算当前 diff hash、准备 builder payload、调用 build-review-fragment、确认 fragment freshness，再继续 Guard 状态推进和 pr-submit。

其中还出现过子 agent 线程数占满，需要关闭旧 agent 后再派发最终 Spec reviewer。流程最终正确合并，但本地 review evidence 准备阶段消耗了大量时间和 token。

这个场景与本 issue 的范围一致：#120 后仍存在的 stale local review fragments 接手体验和机械拼装成本。相关 PR：#135。