[PR Flow] 为低风险小 diff 提供轻量化 security fragment 证据路径

[liuli195]

Parent

#89

相关边界

• [PR Flow] security fragment 轻量记录本地安全 review fallback 原因 #109 已解决 Security fragment 需要记录 tool / fallback_reason 的契约问题；本 issue 不重复该字段修复。
• [PR Flow] pr-submit 增加阶段化进度和耗时遥测 #111 覆盖 pr-submit 阶段化进度和耗时遥测；本 issue 解决的是 security evidence 生成成本过高，不只是展示进度。
• [Governance] 为本地 verify full 增加 fingerprint 缓存 #98 覆盖本地 verify full fingerprint cache；本 issue 不缓存测试结果，只约束 security review evidence 的深度和产物。

详细背景

PR #119 的实际代码变更集中在 PR Flow / governance 契约和测试，但为了生成本地 Security review fragment 的 no-findings evidence，仍执行了完整 Codex Security diff scan 工作流。

本次 scan 产出完整报告与 artifacts，并消耗约 36,932 tokens / 158 秒。对涉及凭据、网络、认证、CI secrets、依赖或交易执行路径的改动，这种深度是合理的；但对小范围治理契约和测试改动，完整报告、ledger、HTML artifact 的成本明显偏高。

#109 已经要求 Security fragment 记录 security_review.tool 和 fallback metadata，这保证了证据来源可追溯；但它没有解决“低风险小 diff 是否必须走完整重扫描和重报告”的效率问题。

产品解决方案

为本地 Security review fragment 增加风险分级证据路径：

• 低风险小 diff 使用轻量化 security receipt：记录 diff 范围、风险分类、执行的基础检查、tool、结论和 evidence ref。
• 高风险 diff 仍强制走完整 Codex Security scan：例如 secrets、auth、webhook、网络 IO、依赖、GitHub Actions、权限、外部上传、交易执行关键路径等。
• 轻量路径不能绕过 P0/P1 发现；一旦分类命中高风险或基础检查发现问题，自动升级到 full scan 或停在 DISPATCH_REQUIRED。

用户视角：小范围治理改动不再为生成 no-findings security fragment 付出完整深扫成本；高风险改动仍保持严格审查。

详细技术实现方案

1. 在 Security fragment contract 中增加可选 metadata：mode（lightweight / full）、risk_level、risk_reasons、evidence_refs、scan_receipt。
2. 增加 diff risk classifier：根据 changed files、diff content、dependency/workflow changes、secret-like patterns、network/auth/webhook/API usage、trading critical paths 选择 lightweight 或 full。
3. lightweight path 生成结构化 receipt，至少包含：current head、diff_files_hash、changed files、classifier version、检查项、结果、tool 名称、no-findings verdict。
4. high-risk path 继续要求完整 Codex Security scan，并把 report / artifact 路径写入 fragment evidence。
5. 如果 classifier 不确定，默认升级 full scan，不允许默认放行。
6. pr-submit 校验 Security fragment 时同时验证 mode 与 risk reasons；低风险 receipt 缺少必要字段时拒绝。
7. 增加测试：低风险治理测试 diff 走 lightweight；workflow/secrets/auth/dependency/trading critical path 走 full；不确定分类升级 full；lightweight receipt stale head/diff 时失败。

Acceptance criteria

• 低风险小 diff 可以生成 schema-valid lightweight Security fragment。
• 高风险 diff 仍必须走 full Codex Security scan。
• lightweight receipt 记录 tool、risk classification、current head 和 diff fingerprint。
• 分类不确定时默认升级 full scan。
• open P0/P1 security findings 仍会阻断 pr-submit。
• PR 修复 PR Flow 本地 review fragment 契约 #119 这类治理契约/测试小 diff 有回归测试或文档示例。

Blocked by

None - can start immediately

[liuli195]

本次会话复现场景补充：实现 #97/#114/#120 后，需要为最终 HEAD 4914ff0 生成 Security fragment。当前会话只读取到 Codex Security diff-scan workflow 文档，没有可直接调用的 scanner 工具；最终对低风险治理契约/测试 diff 采用 manual security review，并在 fragment 中写入 security_review.tool=manual-security-review 和 fallback_reason。

[liuli195]

PR #124 复现场景补充

本次实现 #123 / PR #124 时，变更主要集中在 governance / PR Flow hook、branch protection、文档和测试。当前会话没有可调用的 codex-security 工具，最终 Security fragment 采用 security_review.tool=manual-security-review，并记录 fallback_reason：codex-security tool unavailable；同时本地 verify fast --files ... 中 scoped bandit.governance 已通过。

该场景再次体现：低风险治理 diff 仍需要生成 schema-valid Security fragment，但完整 security scan 工具在会话中不一定可直接调用。

[liuli195]

本次 PR #128 复现了 security evidence 路径的低风险治理 diff 场景：

• 改动集中在 PR Flow / governance wrapper、review fragment contract 和测试。
• 当前会话中没有暴露可直接调用的 codex-security 扫描工具，最终 security fragment 使用 manual-diff-security-review fallback，并记录了 fallback_reason。
• 这次没有阻断合并，但仍需要主会话额外判断 diff 风险、确认 bandit.governance 证据，并手动生成 security fragment。

这不是新的独立问题；它补充了本 issue 中“低风险小 diff 的 security evidence 生成成本/路径需要更轻量、更清晰”的复现场景。

[liuli195]

本次 PR #131 复现了低风险策略 diff 的 security evidence 成本/路径问题：

• 改动范围仅为 strategies/etf_factor_rotation/etf_factor_rotation.py 和对应测试，核心是运行时默认参数回填，未新增外部输入、权限、网络、文件写入、命令执行或密钥处理路径。
• 为生成 current Security fragment，主会话仍需要读取 codex-security diff-scan workflow、建立安全 review 目标、判断 diff 风险，并手动生成 builder payload。
• 该步骤未阻断合并，但对低风险策略兼容性修复来说成本偏高，且依赖主会话临场判断。

这不是新的独立问题；它补充本 issue 中低风险小 diff security evidence 路径的复现场景。

[liuli195]

复现补充：PR #133 低风险治理 diff 的 Security fragment 证据边界不清

本次会话中，PR #133 的 diff 主要是治理契约、PR Flow 状态机和测试：

• docs/rules/pr-flow-interface-contract.yaml
• docs/rules/pr-workflow.md
• docs/rules/review-guidelines.md
• docs/adr/0007-pr-flow-closed-loop-review-evidence.md
• docs/adr/0009-subagent-delegation-continuous-authorization.md
• scripts/research/governance/pr_flow.py
• scripts/research/governance/pr_flow_contract.py
• scripts/research/governance/tests/test_pr_flow_contract.py

主 agent 读取了 Codex Security diff-scan 技能入口，并做了 diff-scoped 安全判断：本次新增内容是字符串状态判断、YAML contract 字段读取和测试，未新增 shell 拼接、外部输入执行、凭据处理、网络入口或交易执行路径。

但这里暴露了一个边界问题：当前 Security fragment 只能记录：

{"security_review": {"tool": "codex-security"}}

它无法表达本次采用的是轻量 diff-scoped security judgment，还是完整 Codex Security scan artifacts。PR Flow 需要 security fragment，但对低风险治理小 diff 来说，完整 deep scan 成本高；如果主 agent只做轻量判断，又容易让 fragment 看起来像完整 codex-security scan。

相关 PR：#133
head：c87d1e4360e14f433c9fca6a430169dc82648df2