对已验证的安全发现批量生成候选修复 diff（不自动应用…

当已有经 triage 排序验证的漏洞发现（TRIAGE.json / VULN-FINDINGS.json / INCIDENTS.json / vuln-pipeline 结果目录）需要生成修复补丁时，用本技能产出惰性 diff 与报告，交由人工审查后应用。

适用场景

解决思路

1. 开始运行前用 Bash 执行 python3 .claude/skills/_lib/checkpoint.py load ./.patch-state 检查状态：status 为 absent 或 complete，或 $ARGUMENTS 含 --fresh 时，执行 checkpoint.py reset ./.patch-state 全新开始并进入 Phase 0；status 为 running 且 phase_done==N 时按序读取 phase0.json..phaseN.json（以及 shards_done 中列出的 shard_*.json）合并进工作状态，打印 Resuming from checkpoint: Phase N complete，跳到 Phase N+1，不重新 spawn 已检查点子代理。
2. 每个阶段结束用 Write 工具把该阶段 JSON 写入 ./.patch-state/_chunk.tmp，再 Bash 执行 python3 .claude/skills/_lib/checkpoint.py save ./.patch-state <N> <name> --from ./.patch-state/_chunk.tmp；运行结束时执行 checkpoint.py done ./.patch-state 4。所有检查点 I/O 只走 checkpoint.py（原子、JSON 校验），用 Write→--from 模式避免仓库字节进入 Bash argv，绝不用 heredoc 或 stdin 传 payload。
3. Phase 0a：从 $ARGUMENTS 解析第一个位置参数 findings path、--repo（默认 .）、--top、--id、--model、--fresh；若没有 findings path 则停止并询问。
4. Phase 0b：检测模式——路径是目录且含 reports/manifest.jsonl 或 found_bugs.jsonl 或 run_*/result.json 时为 execution-verified 模式；但若目录中任何位置存在 INCIDENTS.json（D&R 运行目录也含 run_*/result.json，其 incidents 走静态）则改走 static 模式；否则（TRIAGE.json、VULN-FINDINGS.json、INCIDENTS.json、通用 finding JSON 或 markdown）为 static 模式。把 mode 记入工作状态。
5. Phase 1a：按优先级识别输入容器——① TRIAGE.json 读 .findings[] 并过滤 verdict == "true_positive"（规范输入，已验证、去重、已排序、带 owner）；② VULN-FINDINGS.json 读 .findings[]，先打印 Warning: VULN-FINDINGS.json is unverified scanner output. Consider /triage first. 再继续；③ INCIDENTS.json（/dnr-hunt 或 /dnr-respond 输出）把每条 .incidents[] 映射为一个 finding，嵌套 vuln.file/vuln.line/vuln.type → file/line/category，description ← vuln.mechanism 加 impact，保留 poc（confirmed_exploited incident 的 poc.command 就是其修复的回归检查），顶级 ruled_out 数组不算 finding，先打印未 triage 警告；④ pipeline 结果目录每个 reports/bug_NN/ 一条 finding，report.json → description、crash.crash_type → category、ASAN top-frame → file/line，记录 bug_id = NN 供 --bug N 使用；⑤ 含顶级 list 或 findings/results/issues/vulnerabilities 数组的通用 *.json。
6. Phase 1b：按字段别名表归一化——file ← path/location.file/filename；line ← line_number/location.line/lineno；category ← type/cwe/rule_id/crash_type；severity ← severity_rating/level/priority；title ← name/summary/message；description ← details/report/body/evidence/rationale；recommendation ← fix/remediation/mitigation；owner_hint ← owner/component。
7. Phase 1b 续：为每条 finding 附加 id（按摄取顺序 f001、f002…，TRIAGE.json 中已有的 id 保留）和 source（来源文件相对路径）。
8. Phase 1c：过滤与排序——若指定 --id fNNN 只保留该条；若指定 --top N（静态模式）按 severity HIGH > MEDIUM > LOW 再按 confidence 降序取前 N；丢弃没有 file 的 finding（无法定位就无法修补），记为 skipped、原因 "no source location"。
9. Phase 1d（静态模式）：解析 --repo，对前 5 条带 file 的 finding 检查路径能否在 repo 下解析（先按原样，再去掉常见前缀重试）；若全部无法解析则停止，告知用户引用的文件不可达并建议 --repo 取值。
10. Phase 2A（execution-verified 模式）：对每条 finding（若无 --id/--top 过滤则对整个目录执行一次）运行 vuln-pipeline patch <findings_path> --model <--model 参数> [--bug <bug_id>]，由流水线自行写 <findings_path>/reports/bug_NN/{patch.diff,patch_result.json}；不要重新实现 build → reproduce → regress → re-attack 阶梯。
11. Phase 2A 续：命令返回后读每个 patch_result.json，把 verdict 与 rationale 复制进工作状态；verdict.passed == true 时置 verified: "ladder_passed"，否则置 verified: "ladder_failed"。若 CLI 非零退出（无 build_command、缺 target 配置），把 stderr 记为该 finding 的 error 并继续处理其余 finding。
12. Phase 2A 续：跳过 Phase 3（阶梯本身就是验证器），直接进入 Phase 4；每条 finding 后用 checkpoint.py shard 保存，全部完成后用 checkpoint.py save 保存阶段 2 汇总。若 PATH 上没有 vuln-pipeline patch 就停止并告知用户，不要静默回退到静态模式。
13. Phase 2B（静态模式）：每条 finding 发一个 Task 子代理，全部放在单条 assistant 消息中以并行执行，subagent_type: "general-purpose"，绝不设 run_in_background（需要 diff 文本而非异步句柄）；子代理对 --repo 只读，不能改目标，只把 diff 作为文本返回，由 orchestrator 写入 PATCHES/bug_NN/patch.diff。
14. 静态模式子代理 prompt 要求：只能对 {REPO_PATH} 内路径使用 Read/Glob/Grep，不得构建、运行、安装、修改磁盘文件或访问网络；把修复以 unified diff 形式输出在最终响应中，不应用它；输出必须包含 <patch_diff>、<rationale>、<variants_checked>、<bypass_considered>、<test_note> 标签，diff 直接放在标记之间、不要用代码围栏包裹。
15. 静态模式子代理的 6 步过程：① 读代码——打开 {file} 第 {line} 行及所在函数，理解代码实际做什么，不把 finding 描述当唯一依据；② 根因优先——从被引用的 sink 反向追踪到坏值/缺失校验的源头，修复通常应在那里而非扫描器标记行，并指明根因位置 file:line；③ 变体搜索——Grep 同模式的兄弟调用点，修复应覆盖全部，或在 rationale 中说明为何不覆盖；④ 最小 diff——只做修复根因的最小改动，不重构、不顺带清理、不重排版、不加纯注释，风格与周边代码一致；⑤ 对抗性自检——以攻击者视角重读 diff，说出一个能绕过你改动到达同一坏状态的输入变体，若能说出就说明修复层次错了，回到第 2 步；⑥ 回归测试——在 diff 中加一个改前失败、改后通过的测试用例，放在项目测试目录（test_*/、*_test.*、tests/、spec/），若无测试目录则省略并在 <test_note> 说明。
16. 静态模式子代理若判定该 finding 无法按描述修复（文件错、代码已修、误报），输出 <patch_diff>NONE</patch_diff> 和 <rationale>why no patch is appropriate</rationale>。
17. 静态模式 spawn 时对 findings[] 每条构建 Task 调用并替换 {REPO_PATH}、{id}、{file}、{line}、{category}、{severity}、{title}、{description}、{recommendation}，description 设为 "patch {id}"；若 len(findings) > ~40 则切成约 40 条一批顺序执行（每批一条消息），每条结果解析后做 per-finding shard 检查点。
18. 若 Task 返回 status: "async_launched"（运行时把它放到后台）则整批统一用一种恢复策略：若会话中会到达完成通知，则在通知到达时从其 result 解析标签块，在所有 finding 结清前不要结束回合；若通知不到达，不要轮询 transcript 文件，而是用更小分片（如 10）在新 Task 批次中重新 spawn 缺失的子代理并使用同步结果；Phase 3 的 reviewer 子代理同理。
19. 静态模式解析：从每个 Task 结果提取五个标签块，容忍首尾空白、多余代码围栏、HTML 转义实体（&lt; &gt; &amp; ——某些运行时会在通知 payload 中转义尖括号，写 diff 前先反转义）；若 <patch_diff> 为 NONE 或空则标 status: "no_patch"，否则把 diff 文本写入 ./PATCHES/bug_NN/patch.diff（NN = 排序后的零填充索引）并记录 rationale、variants_checked、bypass_considered、test_note。
20. Phase 3（仅静态模式）：每个已生成 diff 发一个 reviewer 子代理，全部放在一条消息中，subagent_type: "general-purpose"；reviewer 绝不看 finding 的 description、recommendation 或补丁作者的 rationale，只拿 {file, line, category} 加原始 diff 字节，自行阅读源码判断是否最小、在范围内的修复（防止 finding 文本中嵌入的指令同时到达作者和门禁）。
21. reviewer prompt 要求：以维护者视角审查候选安全补丁，对未打补丁的源码 {REPO_PATH} 只读（Read/Glob/Grep），不得构建、运行或应用 diff；回答四问——① SCOPE：diff 是否只触及 {file}:{line} 与其调用者路径上的文件/函数，列出路径外的 hunk；② SUPPRESSION：是修根因还是在压制症状（try/except: pass、对魔法值提前返回、删掉触发的检查、降低日志级别）；③ NEW SURFACE：是否新增解析、信任新输入字段、削弱别处校验或移除安全相关检查；④ STYLE：0-10 分，愿不愿意原样合并（0-3 层次错/压制；4-6 正确但噪音；7-10 最小、定向、风格一致）。结尾精确输出 REVIEW: ACCEPT | REJECT、STYLE_SCORE: <0-10>、OUT_OF_SCOPE_HUNKS: <逗号分隔 file:line 或 none>、REASON: <2-4 句引用具体 diff hunk 与源码行>。ACCEPT 条件：in-scope、根因修复、无新攻击面、style >= 5，否则 REJECT。
22. Phase 3 解析：对每条 status != "no_patch" 的 finding 发一个 Task，解析结尾块，把 review、style_score、out_of_scope_hunks、review_reason 附加到该 finding；静态模式所有结果一律置 verified: "static_review_only"（该标签描述验证类别而非通过/失败）。检查点保存为 phase 3 review。
23. Phase 4a：为每条 finding（两种模式）写 ./PATCHES/bug_NN/patch_result.json，字段含 id、source、title、file、line、category、severity、owner_hint、mode、verified、review、style_score、out_of_scope_hunks、rationale、variants_checked、bypass_considered、test_note、review_reason，exec 模式再加从流水线取得的 verdict 对象。
24. Phase 4a 续：exec 模式还要读流水线的 <findings_path>/reports/bug_NN/patch.diff 并把字节写入 ./PATCHES/bug_NN/patch.diff，使两种模式产物落在同一位置。
25. Phase 4b：写 ./PATCHES.json，含 patch_completed、mode、repo、summary（input_count、patched、no_patch、accepted、rejected、ladder_passed）和 findings 数组（每条为 patch_result.json 形状）。
26. Phase 4c 第 1 步：用 Write 覆写 ./PATCHES.md 的头部——标题 # Candidate Patches；静态模式加粗提示「Static review only. 这些 diff 由独立 agent 阅读源码撰写和审查，未编译、运行或重新攻击，应用前请自行阅读每个 diff，参见 docs/patching.md#reviewing-generated-patches」；exec 模式加粗提示「Execution-verified. 每个 diff 通过（或未通过）流水线验证阶梯 build → reproduce → regress → re-attack，阶梯证明 crash 消失但不证明没引入新问题」；再写 **Input:** {findings_path} · **Repo:** {repo} · {N} findings → {M} diffs。
27. Phase 4c 第 2 步：按 ACCEPT/ladder_passed 优先、再按 severity 排序，逐条把 finding 块写入 ./.patch-state/_chunk.tmp（## bug_{NN}: [{severity}] {title} ({id})、位置与 owner、**Status:** {verified} · review {review or "n/a"} · style {style_score or "n/a"}/10、**Diff:** 路径与 hunk/行数、**Rationale:**、**Variants checked:**、**Bypass considered:**，若 review == "REJECT" 加被拒引用块，若有 out_of_scope_hunks 加超范围 hunk 引用块），然后执行 checkpoint.py append ./PATCHES.md --from ./.patch-state/_chunk.tmp。
28. Phase 4c 第 3 步：追加 ## Skipped 表格，列出无 file 或 status == "no_patch" 的 finding，每行一条并给出原因；最后执行 checkpoint.py done ./.patch-state 4。
29. Phase 4d：输出不超过约 10 行的终端摘要——Patches generated ({mode} mode): {N} findings → {M} diffs；Accepted: {n} 及最高优先被接受项的标题；Rejected: {n}；No patch: {n}；exec 模式加 Ladder passed: {n}/{M}；写明 Wrote ./PATCHES/bug_NN/、./PATCHES.md、./PATCHES.json；静态模式加 These are drafts. Review before applying — see docs/patching.md。
30. 遵守 guard rails：本技能绝不应用 diff——没有 git apply、没有 patch、不对 --repo 使用 Edit，若觉得需要这么做说明设计错了；只用 Write 工具写 ./PATCHES/ 与 ./.patch-state/ 下的路径；reviewer 隔离，只传 {file, line, category, diff} 给它，不传 description、recommendation、exploit_scenario 或补丁作者的 rationale；始终显式设置 subagent_type（用 fork 会把每条 finding 的文本泄漏给所有补丁子代理）；一个阶段的所有 Task 调用放在同一条消息里（串行 spawn 正确但慢 N 倍）；每次进入下一阶段前先做检查点。
31. 工具回退：优先 Read、Glob、Grep、Write、Task；有些会话不提供 Glob/Grep（allowed-tools 是权限过滤器而非加载器），此时用白名单内的只读 Bash 命令兜底——rg/grep 搜索、ls 枚举、head/file/wc 探测、jq 解析 JSON；其余 Bash 只允许 python3 .claude/skills/_lib/checkpoint.py 和 vuln-pipeline patch；不允许用 find。
32. 验证方式（可选自测）：静态模式对 canary fixture 依次执行 /vuln-scan targets/canary、/triage VULN-FINDINGS.json --repo targets/canary --auto、/patch TRIAGE.json --repo targets/canary --top 3，预期 PATCHES/bug_00..02/ 三个 diff，各自 verified: "static_review_only"、review: ACCEPT，植入的 overflow/UAF/format-string 漏洞 style ≥ 7；exec 模式先 vuln-pipeline run drlibs --runs 3 --parallel --stream --model <m>，再 /patch results/drlibs/<ts>/ --model <m>，预期委托给 vuln-pipeline patch，逐 bug 出现 verified: "ladder_passed" 并把 diff 复制进 ./PATCHES/。

适用边界 · 注意事项

• 输入是未验证的扫描器输出（如 VULN-FINDINGS.json）时，补丁质量差、浪费 token 在误报上——应先跑 /triage 得到 TRIAGE.json 再补丁。
• finding 没有可定位的 file/line 时无法生成补丁，只能记为 skipped。
• 需要自动把修复应用到目标仓库的场合不适用：本技能设计上从不应用 diff，产物是供人工审查后另行应用的惰性文本。