Freeze a Bisect SHA and Public API Before an OSS Patch Review

Description and use

Freezing the bisect SHA and public API snapshot confines the model’s edits to the minimal failing change set, preventing scope creep and ensuring the patch addresses only the intended bug.

Problem

When a model generates a patch for an OSS bug, it often adds unrelated changes—extra files, new public APIs, or style tweaks—causing scope creep and downstream breakage.

Outcome

By freezing the bisect SHA and public API snapshot, the model’s edits are bounded to the minimal failing change set, eliminating scope creep and ensuring the patch addresses only the intended bug.

Workflow

• Clone the repository at the reporter’s tag and run the failing test to confirm the bug.
• Run git bisect to locate the first bad commit, outputting the SHA to FIRST_BAD and the list of allowed files to allowed_files.txt.
• Snapshot the public names on the bad tree with tools/api_snapshot.py, saving to api.snap.bad. Copy api.snap.bad beside FIRST_BAD. Create patch_contract.yaml with the SHA, allowed files, forbidden changes, required tests, and the snapshot file. Attach the contract to the review prompt and instruct the model to obey it. After the model generates a patch, verify the diff only touches allowed files and the snapshot byte‑for‑byte matches api.snap.bad.
• Review the patch, ensuring no new public names, modules, or dependency bumps were added.
• Merge the patch if all constraints are satisfied.

Evidence

The first artifact is a git bisect SHA. The second is a snapshot of public names.

Source

Allowed_files comes from the bisect file list. A model does not extend that list.

Source