Pull request quality contract

You do not need permission to fix something

An unplanned pull request for a bug you actually hit is welcome. Several of this project’s better fixes arrived exactly that way — a routed model stalling after tool calls, a provider sending the wrong model parameters, images being flattened out of tool results. None of those started from a planning discussion, and a gate that required one would have lost all of them.

Opening an issue first genuinely helps for larger or design-shaped work, where agreeing on the approach saves you from building the wrong thing. That is advice, not an admission requirement.

What a ready pull request claims

Marking a PR ready for review is a claim that the change is complete, understood, and tested. Opening it does not transfer responsibility for the branch to the maintainers.

Authors are expected to understand every changed line, name the exact commands and results behind any validation claim, add focused regression coverage for behavior changes, and stay available to resolve CI and review feedback. Maintainers identify problems; they are not expected to repair contributor branches, write the missing tests, or translate automated findings into patches on your behalf.

“Tested” or “CI passes” without named commands and results is not evidence.

Automated gates

Three deterministic checks run before human review, and each failure message tells you exactly what to change:

• PR quality (enforce-target). Pull requests must target dev and carry a real description: a Summary of what changed and why, plus a Test plan (or equivalent substance). When the title or description mentions gui, the description must include a screenshot of the UI change; the check keeps the PR a draft and comments until the screenshot is present. A maintainer (OWNER / COLLABORATOR / MEMBER — repository owners, collaborators, and members) can waive the screenshot requirement with an issue comment saying the change does not touch the GUI (for example “no gui changes”); a contributor PR author cannot self-waive (a maintainer who authors the PR can waive, but they already hold push permission and are not gated by the contributor checklist). Contributor PRs (authors without repository push permission) open in draft and stay there until a four-box review-readiness checklist in the description is complete: local CI green, the branch on the latest dev commit, all correct Codex and CodeRabbit findings fixed, and the ready-for-review confirmation. Once every box is ticked the check marks the PR ready for review and notifies the maintainers listed in MAINTAINERS.md (excluding the author). The gate’s status and “what to do” live in a single consolidated bot comment that is rewritten on every run, so there is exactly one place to look. Completion is bound to the exact commit the PR head pointed at: if new commits are pushed afterward, the gate moves the PR back to draft, resets the checklist and the maintainer notification, and asks you to test and tick the boxes again against the latest code. A retarget to dev clears the wrong-branch message automatically and is remembered by the gate; the draft stays until the checklist is complete. Before a completion is accepted, the gate verifies the checklist claims it can check itself: the head’s ci check must be green, the branch must be on the latest dev commit or at most 10 commits behind it, and every Codex and CodeRabbit review thread authored by a review bot on the current head must be resolved (unresolved threads from other authors do not block). CodeRabbit findings that fall outside the diff range and are reported only in a review body on the current head add to the unresolved count while a bot review thread is open; resolving every bot thread clears the box. A disproved claim unticks the matching box and keeps the PR a draft. When the checklist is complete and every gate is green, the gate adds a review-ready label as a visible status marker at the ready moment.

• Hygiene. Behavior changes need a test; new lint or type suppressions, focused or skipped tests, empty catch blocks, edited generated output, and a lockfile changed without its manifest each need an explicit approval label. A comment-only change to a source file is not a behavior change and owes no test.

• Cross-platform CI. The suite runs sharded on Linux and in full on macOS for every pull request. Windows runs at the shipping boundary — on promotion to main or preview — so a slow or flaky Windows runner cannot decide when your pull request turns green. This runs for every pull request, whatever its base branch — including a stacked child whose base is another open PR’s head. The paths: filter, not the base branch, decides whether the jobs run at all: a PR touching only docs or devlog/ queues nothing.

• Type label. The label check derives bug / enhancement / documentation / chore from your PR title. A title without a recognisable prefix (stack 3/5: …) falls back to the PR’s commits, which usually stay conventional; chore-family commits (test:, ci:, refactor:) do not outvote a fix: or feat:. A PR that genuinely mixes types is left unlabeled rather than guessed, and a label a human sets is never overwritten.

CodeRabbit reviews every PR and its findings are advisory. Address what it gets right; say why when it is wrong. It does not block a merge.

When a workflow change takes effect

enforce-target and label run on pull_request_target, which GitHub always loads from the repository default branch. A change to either takes effect only after it is promoted to main — merging it to dev does not change live behavior. The cross-platform CI workflow runs on pull_request and takes effect as soon as it is on the branch being targeted.

Sponsored surfaces

Authentication, credential handling, GitHub Actions workflows, release automation, and dependency installation need a maintainer to sponsor the change (maintainer-sponsored) before it merges. A bad merge on those surfaces is expensive and hard to unwind, which is why they are the only surfaces gated this way. Everything else is open.

When a pull request is closed

A PR that stalls with unresolved review feedback may be closed, with the reason stated plainly. Closure is not a verdict on the contributor: reopen it once the stated reason is resolved, or replace it with a clean one. Ask if the reason is not clear.