fix(workflow): classify oversized PR diffs safely (#7695)

[ll7]

Summary

Make the base-sensitive gate recover complete changed-file inventories from GitHub's paginated pull-request files API when gh pr diff --name-only is rejected for an oversized diff, while preserving fail-closed behavior for incomplete or malformed data.

Linked Issues

• Closes friction: classify base-sensitive gates for oversized PR diffs #7695

Stack / Dependency

• Base dependency: origin/main 2d221f7c3af34e9ae9db4a563c576fb6e919771e
• Required prior PRs: none
• Stack follow-up issues: none
• Safe to review independently: yes
• Review dependency reason, if any: none

What Changed

• Keep the successful gh pr diff --name-only path for ordinary small diffs.
• Add strict, bounded pagination over pulls/<number>/files as the fallback source.
• Emit structured JSON for unknown changed-file classification instead of returning an empty error path.
• Add fast-path, oversized-diff, multi-page, malformed-response, and JSON fail-closed tests.
• Document changed-file provenance in docs/dev_guide.md.

Why It Matters

• Added value: large research/documentation PRs no longer lose base-sensitive admission diagnostics solely because GitHub cannot render their unified diff.
• Expected impact: complete inventories remain classifiable; partial or unavailable inventories still block safely.
• Why this is worth merging now: PR feat(research): wire answerability into campaign admission #7469 reproduced HTTP 406 PullRequest.diff_too_large and currently prevents the gate from producing a useful JSON result.

Research Result Guidance

• Target claim / hypothesis / blocker this should affect: unblock reliable workflow classification for oversized research PRs; no scientific claim.
• Comparator or baseline, if applicable: existing gh pr diff --name-only fast path.
• Evidence tier: NA
• Evidence applicability: NA - support tooling only; no benchmark or research result is produced.
• Result classification: NA
• Decision or stop rule, if applicable: merge only with focused tests, lint, exact-head review, and final readiness proof; unknown inventories remain fail-closed.
• Parent issue, claim map, registry, context note, or synthesis surface to update: friction: classify base-sensitive gates for oversized PR diffs #7695.
• New research/benchmark/metric/paper-facing analysis tool, if any: NA - support helper; it does not interpret evidence.

Domain-Aware Approval

• Required for this PR: no - support tooling only; no evidence or scientific claim changes.
• Domains reviewed: NA
• Status: not required
• Approver/review source or waiver: not applicable.
• Validity checklist. Keep these machine-detected labels unchanged:
  • Target claim/hypothesis: NA - support tooling only.
  • Comparator or split/evidence validity: NA - support tooling only.
  • Fallback/degraded exclusions: NA - no benchmark execution.
  • Claim boundary: no benchmark, metric, planner, publication, or scientific claim.
  • Implementation integrity vs experimental validity: implementation integrity is covered by focused tests and readiness; experimental validity is not in scope.

Falsification / Non-Transfer Check

• Did the mechanism activate? NA - support tooling only.
• Did the intervention change command source, selected command, trajectory, or route progress? NA.
• Did the scenario actually contain the targeted failure mode? NA - this is a GitHub API boundary.
• Result route: NA
• Follow-up question or issue for weak, negative, or non-transfer results: NA.

Next Empirical Action

• Rerun needed: NA - support tooling only.
• Extractor or analysis tool needed: NA.
• Artifact missing or unavailable: none for this support change.
• Stop / revise / continue decision: continue using the gate; refresh any stale PR before merge.
• Proposed child issue or existing follow-up: none.

Validation / Proof

• Commands run:
  • uv run ruff format --check scripts/dev/check_base_sensitive_gates.py tests/dev/test_base_sensitive_gate_contract.py — pass
  • uv run ruff check scripts/dev/check_base_sensitive_gates.py tests/dev/test_base_sensitive_gate_contract.py — pass
  • focused changed-file tests — 5 passed
  • related base-sensitive selector/worktree/CAS tests — 16 passed
  • gh pr diff 7469 --repo ll7/robot_sf_ll7 --name-only — expected HTTP 406 reproduced
  • python scripts/dev/check_base_sensitive_gates.py --pr 7469 --repo ll7/robot_sf_ll7 --json — structured ordinary classification from REST fallback
• Evidence that the change works here: mocked oversized-diff and multi-page REST fixtures prove complete enumeration; malformed data and unknown JSON paths remain fail-closed.
• Benchmarks or smoke tests, if applicable: NA - support tooling only.

Risks / Rollout

• Compatibility risks: the fallback adds bounded GitHub API reads only after the existing diff path fails; callers without a complete API response remain blocked.
• Failure modes: API transport errors, malformed pages, empty inventories, and pagination exhaustion return unknown rather than admitting a PR.
• Rollback or fallback plan: revert this commit; the original diff-only path remains available, and no merge-policy relaxation is introduced.

Docs / Provenance

• Updated docs: docs/dev_guide.md merge-race prevention section.
• Relevant design or provenance notes: issue friction: classify base-sensitive gates for oversized PR diffs #7695 and the existing strict REST pagination contract in scripts/dev/merge_queue_gate.py.
• Any assumptions that need to be preserved: only a complete, filename-validated inventory may reach the existing selector.

Downstream Propagation

• Parent issue updated (yes/no/NA): yes — friction: classify base-sensitive gates for oversized PR diffs #7695 contract and evidence updated.
• Claim map / benchmark report updated (yes/no/NA): NA.
• Leaderboard / artifact catalog updated (yes/no/NA): NA.
• Registry or config index updated (yes/no/NA): NA.
• Context index / memory note updated (yes/no/NA): NA.
• Follow-up issue opened for deferred propagation (yes/no/NA): NA.
• Not applicable because: support-only workflow diagnostics produce no research artifact.

Follow-Up Issues

• Deferred work: none.
• Issues opened for follow-up: none.

Reviewer Notes

• Verify the fallback is only used after the diff fast path fails and that a full terminal page is required before classification.
• Known limitations: the fallback is bounded at 100 API pages and deliberately reports unknown beyond that bound.
• Shared-helper migration: inapplicable; this patch extends one existing gate owner and does not migrate a process-boundary helper or create a second merge authority.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 0f1963e1-6c6f-45ea-b21e-dc8789516650

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[ll7]

Exact-head review

• Head reviewed: 9bbf1024fad60f9c66371ec59adb36f442f13313
• Base reviewed: 2d221f7c3af34e9ae9db4a563c576fb6e919771e
• Decision: acceptable for merge after all hosted checks pass and the guarded merge-ready label is admitted.

Scope and correctness

The change preserves the fast gh pr diff --name-only path and adds a strict, bounded GitHub REST pagination fallback for oversized diffs. It validates response shape, requires a terminal short/empty page, and fails closed on malformed or exhausted enumeration. The CLI now emits structured JSON for unknown/error outcomes instead of silently omitting a result. The focused contract tests cover the fast path, 406 fallback, multi-page terminal behavior, malformed responses, and structured error output.

Evidence

• Focused new contract tests: 5 passed.
• Related base-sensitive gate tests: 16 passed.
• Selected contract tests: 6 passed.
• Final readiness on the exact base/head: passed, including the full core lane, CUDA preflight, docstring/broad-exception ratchets, and clean-tree stamp.
• Live diagnostic reproduced GitHub HTTP 406 for PR #7469 and verified the REST fallback returned a complete non-success classification without claiming base-sensitive files.

This is support tooling only; it makes no benchmark, planner, or paper-facing claim. Merge remains contingent on hosted checks and the repository's guarded merge procedure.

[github-actions]

🔍 PR Contract Check Summary

Overall Status: 🟢 PASSED

Check	Status	Description
1. Closes-discipline	✅ PASSED	Demand Refs #N for epic issues
2. Closure declaration	⚠️ WARNING	Require Closes/Refs for title issues
3. State-refresh-only	✅ PASSED	Reject docs/context state updates
4. Evidence hygiene	✅ PASSED	Checks markers and provenance fields
5. Evidence writer usage	✅ PASSED	Require the shared marked writer path
6. Successor discipline	⚠️ WARNING	Require successor statement on multi-PR issues
7. Worker-lane label	⚪ None	Label PRs from cheap worker lane
8. Placeholder docstring ratchet	✅ PASSED	Reject NEW TODO/empty docstrings in added diff lines

⚠️ Warnings

• WARN: Issue friction: classify base-sensitive gates for oversized PR diffs #7695 has already been referenced in 2 merged PR(s), but the PR body does not contain a successor statement ('successor slice' or 'does not duplicate').

ℹ️ Info

• No worker-lane provenance detected.

---

This check is mechanized. Please resolve any blockers to pass CI.

[ll7]

Exact-head self-review

• Reviewed head: 9bbf1024fad60f9c66371ec59adb36f442f13313
• Reviewed base: 2d221f7c3af34e9ae9db4a563c576fb6e919771e
• Intended design: #7695 preserves the fast gh pr diff --name-only path and adds a strict, bounded GitHub REST pagination fallback for oversized diffs. Malformed or incomplete enumeration remains unknown/fail-closed, and the CLI emits structured JSON for unknown/error outcomes.
• Findings: none within the issue scope.
• Focused proof: 5 passed for the new changed-file enumeration contract tests; 16 passed for related base-sensitive gate tests; 6 passed for selected contract tests.
• Additional proof: exact pr_ready_check.sh passed at the reviewed head, including the full core lane, CUDA preflight, docstring/broad-exception ratchets, and clean-tree stamp. A live diagnostic reproduced GitHub HTTP 406 for PR #7469 and verified the REST fallback returned a complete non-success classification without claiming base-sensitive files.
• This is support/tooling work with no research, benchmark, planner, or paper-facing claim and no domain review required.

single-account internal review waiver: no distinct implementation-review identity is available; exact-head self-review, independent hosted checks, and the guarded merge receipt are required instead.

base-policy: ordinary-cas @ 9bbf1024fad60f9c66371ec59adb36f442f13313

pr-metadata: reconciled @ 6b769a84825ca85fe87ae840ca701591eb7834a7783de61903f93ca2ad1d35ff

gate-verdict: accepted @ 9bbf1024fad60f9c66371ec59adb36f442f13313