oversized-pr-close-policy.md

Oversized PR close policy

• Status: active
• Owner: ClawSweeper maintainers
• Source of truth: src/clawsweeper-oversized-pr-policy.ts, the review admission hook, the guarded apply writer, and .github/workflows/sweep.yml
• Verified scope: shared review admission, exact-event handoff, and synthetic GitHub apply on the policy branch; production closing is not exercised
• Update when: admission order, metadata fields, exemptions, close gates, repository apply rules, or record publication changes

An open pull request whose GitHub-reported additions plus deletions exceeds CLAWSWEEPER_MAX_PR_CHANGED_LINES receives the deterministic oversized_pull_request close proposal before structural-cache inspection, review-start comments, list/blob hydration, scanning, or model review. The threshold defaults to 50,000. It must be a positive integer; invalid values fall back to the default. Exactly 50,000 lines is admitted; 50,001 is oversized. Missing or invalid size/head metadata admits the PR normally.

Drafts and owner/member-authored PRs are subject to the policy. The existing PR_AUTO_CLOSE_EXEMPT_LABEL_NAMES labels (clawsweeper:human-review, clawsweeper:manual-only, clawsweeper:autofix, clawsweeper:automerge) and size: accepted-large exempt a deliberately large change. PR status label synchronization creates the maintainer-owned size label but never applies it on a maintainer's behalf. Existing security/protected-label and repository apply restrictions remain in force; the maintainer label alone does not exempt an oversized PR.

Exact events, scheduled work admitted through the exact queue, and shard review share the predicate. The exact-event live-state check saves its raw PR payload and invokes the built predicate. Oversized items skip target checkout, review-tool setup and reactions, but reserve the same durable review lease as ordinary admitted items. Held or throttled reservations defer; superseded queue authority blocks publication. After reservation/status writes, the workflow waits through the timestamp margin and refreshes PR metadata, rechecking the admitted head and size policy. Changed eligibility or head defers to fresh admission instead of publishing a stale snapshot. The review CLI carries the supplied lease owner and comment ID into the metadata-only report without Git, GitHub, or model calls. Direct exact publication uses the shared fenced apply path to update the durable comment with the proposal and, when all close gates pass, the close notice. First reviews create the durable proposal through that writer; existing reviews update the canonical comment. Both carry the reserved lease identity. Ordinary admitted PRs reuse the payload during hydration. Each head or label change is evaluated again. This policy never reopens a PR.

Known gap: when direct publication is not accepted and the proposal falls back to the durable queue, the queued lease-expiry write advances PR activity after the report's observation. The unchanged source-freshness guard keeps the PR open with skipped_changed_since_review; it can be re-evaluated at the next event or head. Deferred publication is not fixed by carrying the lease tuple. The follow-up is to create the final metadata proposal under publication ownership, after the publisher acquires its current lease and fence.

CLAWSWEEPER_OVERSIZED_PR_CLOSE_ENABLED gates apply; it defaults off in a standalone CLI and defaults to true in the sweep workflow. The normal close-reason filter includes this reason when CLAWSWEEPER_AUTO_CLOSE_REASONS=all. Dry-run, comment-only publication, or a closed policy/reason gate leaves the proposal in records/<slug>/items/<n>.md with decision: close and its additions, deletions, changedFiles, threshold, and head evidence. Exact publication records this intentional policy refusal as policy_noop after the retained proposal reaches the canonical store. It does not claim a GitHub comment or close occurred, dispatch a follow-up router, or charge another retry for the same immutable review. Dry-run and unverified kept_open results do not supply this proof. A later authorized apply can still use the retained proposal after the normal live checks. The report also records a metadata source fingerprint and comment counts. No scanner or model provenance is asserted.

Apply requires complete recorded metadata and repeats the live PR size, head, open-state, lock, and exemption checks immediately before closing. Changed metadata or unreadable live state blocks the close. The source record also carries the observation time taken before the PR metadata read; initial activity at that second or within the one-second clock margin is ambiguous and keeps the proposal open. Missing handoff observation times fall back conservatively to the PR update timestamp. Submitted reviews expose no edit timestamp, so a PR update timestamp in that observation window also blocks initial receipt creation when reviews exist. Before comment publication, apply captures bounded issue-comment, timeline, inline-comment, and review metadata, with a maximum of three 100-entry pages per stream. Incomplete reads keep the proposal open. The receipt excludes only the exact owned review-comment ID and verifies that comment against its write response; all other activity remains fingerprinted. The baseline is persisted before publication, and the exact owned write identity is persisted before any post-publication read, including when subsequent validation fails. Forced checks before closing catch body edits and same-second human comments after publication, and persisted receipts preserve that protection across retries. PR files, commits, blobs, scanner work, and model review are not hydrated by this guard.

Changed metadata or unreadable live state blocks the close. The public notice uses proposal wording until GitHub confirms the close, so an aborted close never claims success. After closing, apply updates that same comment to the template below without replacing a newer canonical review. Normal freshness and durable-comment guards still apply. The existing writer posts the one policy comment and closes the PR; archiveClosed moves the report to closed/ only after success. The observer projection treats the pending proposal and actual close exactly as other reasons; it gains no action controls.

The public comment is:

ClawSweeper closed this pull request because it changes {total} lines ({additions} added, {deletions} removed) across {files} files, above this repository's {threshold}-line limit for review. Changes this large cannot be reviewed safely or scanned within limits and usually indicate a stale branch merged against an old base. Please open a fresh pull request from current main containing only the intended change, or split it into focused pull requests. A maintainer can apply size: accepted-large to exempt a deliberately large change.

Reproducible proof

node scripts/proof-oversized-pr-close.mjs exercises metadata admission and dry-run retention, with a 49,999-line control. The retained oversized-admission and sweep workflow tests cover the guarded metadata-only path. One-off publication and close-effect proof drivers have been retired; their original evidence remains in repository history.