fix(pr-review): gate disproportionate changes

[huangruiteng]

Summary

• require typed change_proportionality evidence for every code-changing PR;
• make disproportionate and not_yet_proven verdicts block approval even when implementation checks are green or earlier review findings were resolved;
• reset proportionality from the original problem whenever a re-review has materially expanded in scope;
• record the reusable self-repair pattern and keep the host skill thin.

Root Cause

The existing review contract separated active-call-site scope fit from code-volume description, but neither provided a blocking benefit-to-complexity verdict. A re-review could therefore optimize closure of the latest implementation finding and inherit an approval trajectory while the proposed mechanism kept growing beyond the evidenced user value.

Validation

• pytest tests/capabilities/test_pr_review_contract.py tests/capabilities/test_pr_review_queue.py -q — 26 passed
• examples/pr-review-command-smoke.py — passed
• examples/bootstrap-command-pack-smoke.py — passed
• changed Python Ruff checks — passed (the smoke's pre-existing import bootstrap uses the existing E402 exclusion)
• public/private boundary scan — clean for all six changed files
• loopx canary premerge --from-git-diff --tier standard — passed: 9 catalog checks, 8 risk-profile checks, no manual holds; self-merge allowed

Scope and Safety

This is an additive review-contract repair. It does not add a second reviewer engine, inspect private evidence, change GitHub write authority, or alter runtime product behavior. Code and docs PR applicability remains typed: code changes require proportionality evidence; docs-only changes do not.

Future-facing scope pass: the repair stays in the existing PR review execution contract and its durable smoke. A separate result validator was intentionally not added because there is no shipped review-result ingestion call site; the current capability contract remains the authoritative model-facing enforcement boundary.

[huangruiteng]

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

Exact head: 3731@83fa40c26a6346c8fa59bbe8c0bf44fca823bf01

动机

这次修复针对一个已复现的 review 控制面缺口：现有 scope_fit 只证明代码有生产 caller，code_volume 只要求描述规模，但 verdict policy 没有把原始收益与机制/维护成本的比例作为阻塞条件。因此复审可能逐条关闭实现 blocker、继承“越来越接近批准”的轨迹，却不重新判断完整 exact head 是否仍值得合入。

改动思路

修复留在既有 pull_request_review_execution_contract_v1：所有 code-changing PR 新增 typed change_proportionality evidence，要求从原始问题核对频率/严重度、用户与恢复成本、最小修复、production/state/schema/CLI/caller/migration/maintenance surface 和 scope growth。completion_gate.blocking_evidence_verdicts 把 disproportionate 与 not_yet_proven 映射成 blocker；verdict_policy 明确 correctness、绿色 CI 和已关闭的旧 finding 不能覆盖该门禁。materially expanded re-review 必须从原问题重置，不继承 approval trajectory。

正向路径：code PR 的 build_review_plan 投影必选 evidence → reviewer 验证收益与成本 → proportionate 后才可进入无 blocker verdict。负向路径：证据不足或范围失衡 → typed verdict 为 not_yet_proven/disproportionate → 必须 REQUEST_CHANGES，建议最小修复、删除、拆分或 hold。docs-only PR 不触发此 code gate。

具体改动

• build_review_execution_contract 新增比例 evidence、字段、typed verdict 与复审重置规则；completion/verdict policy 将两个未通过值设为阻塞。
• build_review_plan 仅对 code change 添加 change_proportionality_required 和 result skeleton；build_review_template 要求风险与整体评价消费该 evidence。
• contract 单测和 public command smoke 证明 code/docs applicability、阻塞映射、live packet 投影和 thin-skill ownership；README/catalog 更新公开协议说明。
• self-repair pattern 记录 pr_review_proportionality_goal_drift，把这次事件抽象成可复用诊断，而不写 PR 编号、作者或私有上下文。

关键符号复核：build_review_execution_contract 是 evidence/verdict authority；build_review_plan 在 loopx/pr_review.py:1044 的 active packet path 为每个 PR 绑定 applicability；build_agent_response_contract 在 loopx/pr_review.py:1252 把共享 gate 放进 live CLI packet。没有增加第二 reviewer engine 或无 caller 的 result validator。

对主干的风险

未发现阻塞项。最强残余风险是该能力的执行边界仍是 model-facing structured contract，而不是一个独立结果提交 API；当前产品没有 shipped review-result ingestion call site，新增 validator 会成为未使用框架，因此本 PR 没有扩张到那一步。回归通过 live packet、unit test 和 command smoke 保证门禁不会从正常 review 上下文中丢失；如果未来出现机器结果写入 surface，应在那个真实 caller 上增加结果级 validator。

比例判断为 proportionate：6 文件 +132/-3，生产 contract 仅 +56/-2，其余主要是 63 行测试/smoke、12 行协议文档和一条修复模式；没有新状态、CLI 参数、迁移、外部写权限或 runtime behavior。最小修复就是扩展现有 contract，未引入新的抽象层。typed-state、domain-neutrality、behavior disclosure 和 guidance-vs-obligation 均无新增风险。

验证：26 个 focused tests 通过；PR review command smoke、bootstrap command-pack smoke、Ruff、public/private boundary 均通过；标准 premerge 执行 9 个 catalog + 8 个 risk-profile checks，无 failure/manual hold；exact-head GitHub 的 Linux pytest、Windows、DCO、Dependency Review、Pages/Release build 与 Sonar checks 全部成功或预期 skipped。

我的整体评价

无 blocking finding，批准 exact head。该修复直接改变 reviewer 的判决目标，而不是为 #3558 写 denylist：每个 code PR 都必须证明收益—复杂度比例，物化扩张后的复审必须重新从原始问题开始。未来-facing pass 已做且无需额外重构；合并后应继续保留 #3558 的 REQUEST_CHANGES，直到其范围被缩小或必要性被重新证明。

English verdict: APPROVE on exact head 83fa40c26a6346c8fa59bbe8c0bf44fca823bf01. The PR adds a typed, verdict-blocking proportionality gate to the existing review contract, requires full-scope re-evaluation after material growth, and keeps docs-only reviews exempt. Focused tests, command/bootstrap smokes, Ruff, public boundary, standard premerge (9 catalog + 8 risk-profile checks), and all applicable GitHub checks passed. No blocking findings; formal self-approval is unavailable for this author-owned PR.