AI PR Governor

ai-pr-governor is a local pre-tool gate for solo developers using AI coding agents at very high velocity.

Status: public alpha. The tool is usable, conservative, and non-mutating. Expect the command surface to evolve as more high-volume agent workflows are tested.

It answers one narrow question before an agent opens, pushes, rebases, merges, or deletes a branch:

Does the current Git/GitHub evidence warrant this action?

It does not replace GitHub, CI, stacked PR tools, merge queues, Graphite, or jj. It sits in front of those tools so an agent cannot casually claim "ready to merge" when the branch is stale, CI is failing, conflict markers are present, the worktree is dirty, or the PR state is unknown.

AI coding agents can produce changes faster than the traditional PR queue can absorb them. A solo developer can end up with many small PRs blocked by:

• stale base branches;
• hidden merge conflicts;
• failing or pending CI;
• dirty local state;
• large diffs that should be stacked or batched;
• PR claims that are not supported by current evidence.

This tool turns those operational claims into an explicit gate.

From GitHub:

python3 -m pip install git+https://github.com/AdemVessell/ai-pr-governor.git

For local development:

git clone https://github.com/AdemVessell/ai-pr-governor.git
cd ai-pr-governor
python3 -m pip install -e .

No runtime dependencies are required. If the GitHub CLI (gh) is installed and authenticated, merge gates can also inspect PR state and checks.

If the pr-gov script is not on your shell PATH, use:

python3 -m ai_pr_governor --help

Run inside a Git repository:

pr-gov open-pr
pr-gov push
pr-gov rebase
pr-gov merge-pr
pr-gov delete-branch
pr-gov queue-status
pr-gov next
pr-gov land-plan

Machine-readable output:

pr-gov merge-pr --json --strict-exit
pr-gov land-plan --json

Exit codes with --strict-exit:

• 0: allow_tool
• 2: hold_for_reaudit
• 3: block_tool

The governor returns:

• allow_tool: current evidence supports the requested action;
• hold_for_reaudit: more current evidence is needed;
• block_tool: current evidence contradicts or does not warrant the action.

Example:

Decision: hold_for_reaudit
Action:   open-pr
Summary:  open-pr needs fresher or more complete evidence before proceeding.

Findings:
- [warning] dirty_worktree: Worktree has uncommitted changes; current action evidence is not stable.
- [warning] branch_behind_main: Branch is behind the main ref; stale-base actions are not warranted.

Required next steps:
- Commit, stash, or intentionally include dirty worktree changes before continuing.
- Rebase or merge the current main ref, then rerun tests/checks.

Put this before destructive or queue-amplifying agent actions:

pr-gov open-pr --json --strict-exit

Only let the agent run gh pr create, git push, git rebase, or gh pr merge when the decision is allow_tool.

For high-throughput solo work, the recommended workflow is:

agent worktree -> pr-gov gate -> local tests -> stack/batch/integration branch -> CI -> merge queue/automerge

Local Git evidence:

• inside a Git repository;
• current branch;
• default/base ref;
• commits ahead/behind base;
• changed files;
• dirty worktree;
• conflict markers in changed files;
• suspiciously large diffs for tiny PR flow.

Optional GitHub evidence through gh pr view:

• PR draft state;
• mergeability status;
• failing checks;
• pending checks;
• local HEAD vs PR HEAD.

Queue evidence through gh pr list:

• open PR ordering;
• draft state;
• mergeability state;
• failing and pending checks;
• changed file counts;
• changed-file overlap with earlier open PRs;
• next safest PR to merge.
• bounded ready merge waves;
• offline queue snapshots with --from-file.

For the quoted pain case, queue mode is the important one:

pr-gov queue-status
pr-gov next
pr-gov land-plan --wave-size 20

queue-status classifies every open PR:

• ready;
• held for CI/draft/overlap/large diff;
• blocked by failing checks or mergeability.

next prints the best next action. It is intentionally non-mutating. It tells the agent what is warranted; it does not run the merge.

land-plan prints an ordered non-mutating landing plan for the whole queue. Ready independent PRs are grouped into bounded merge waves. The default wave size is 20 PRs; use --wave-size 0 if you intentionally want an uncapped wave.

Example shape:

Decision: allow_tool
Summary:  PR #42 is the next safest merge candidate.
Counts:   3 ready, 4 held, 1 blocked, 8 total

Recommended next: PR #42 fix typo in parser

Example land-plan shape:

Land plan:
1. Wave 1: merge or enable auto-merge for PRs #1-#20 (20 PRs).
2. Wave 2: merge or enable auto-merge for PRs #21-#40 (20 PRs).
3. Hold PR #43: stack or rebase after overlapping PR(s) #42.
4. Block PR #44: fix failing CI before merge.

For high-throughput work, you often want repeatable queue analysis without creating more GitHub traffic. Save a PR-list snapshot, then analyze it locally:

gh pr list --state open --limit 200 \
  --json number,title,createdAt,updatedAt,isDraft,mergeStateStatus,changedFiles,files,statusCheckRollup \
  > queue-snapshot.json

pr-gov land-plan --from-file queue-snapshot.json --json

--from-file also accepts a prior pr-gov queue-status --json payload. Old governor findings are ignored and recomputed from the current snapshot fields.

Try the included example:

pr-gov land-plan --from-file examples/queue-snapshot.json

For a solo developer producing dozens of AI changes per hour, the practical fix is not "open every PR instantly and hope the queue keeps up." Use three lanes:

• Intake lane: agents write to separate branches/worktrees and run local tests before opening a PR.
• Stack/batch lane: overlapping file sets become stacked PRs or an integration branch instead of competing independent PRs.
• Landing lane: pr-gov land-plan classifies the whole queue, then enables auto-merge in bounded ready waves.

At extreme rates, call the governor before both queue-amplifying actions:

pr-gov open-pr --strict-exit
pr-gov land-plan --wave-size 20

• It does not resolve conflicts.
• It does not run your test suite.
• It does not prove code correctness.
• It does not replace merge queues or stacked PR tools.
• It does not perform repository mutations.

For a solo developer with 10-20 AI-generated PRs per hour:

• remove human review requirements;
• keep CI fast;
• use auto-merge or a merge queue;
• stack dependent changes;
• batch noisy agent work into an integration branch;
• use this governor before agents open or merge PRs.
• use pr-gov queue-status before deciding whether to merge, rebase, stack, or batch.

For 20+ PRs per minute, do not depend on GitHub PRs as the first coordination surface. Use an intake queue or integration branch first, then open PRs only for changes that have passed the local gate and are not fighting the same file set.

This is a practical application of evidence-to-action entitlement:

Do not let an agent perform a consequential tool action unless its operational claim is warranted by current evidence.

In this package, the operational claims are Git/PR claims: ready to open, ready to push, ready to rebase, ready to merge, or safe to delete.