---

name: pr-preflight description: Full pre-PR merge-readiness check. Run this before opening or merging a pull request — it validates local gates (lint, format, tests), CI status, screenshot evidence, and PR metadata in one pass. Also useful for reviewing an existing PR's readiness. user_invocable: true

PR Preflight

One-command merge-readiness check that combines local gates, CI status, and PR policy checks. Mirrors what reviewers look for so issues are caught before review, not during.

Check an existing PR

scripts/check_pr.sh <pr_number>

This runs:

1. PR metadata — fetches title, state, draft status, merge state, branch info
2. CI checks — counts pass/fail/pending GitHub Actions checks
3. Local gates — runs lint, format, and tests locally:
   • uv run ruff check .
   • uv run ruff format --check .
   • uv run pytest tests/ -x --timeout=60
4. PR body policy — validates required sections, evidence links, and blocked artifacts
5. Verdict — READY or NOT_READY with specific reasons

Options

Flag	Purpose
--repo OWNER/REPO	Override repository (default: auto-detect via gh)
--no-tests	Skip local test gates (useful when you just want CI + metadata check)

Exit codes

Code	Meaning
0	All checks passed — ready to merge
1	Script error (missing tool, network failure)
2	Not ready — at least one check failed

Run local gates only (no PR needed)

If you haven't opened a PR yet and just want to validate locally:

uv run ruff check . && uv run ruff format --check . && uv run pytest tests/ -x --timeout=60

Or use the pre-commit hook (auto-runs lint on commit):

git config core.hooksPath .githooks

What blocks merge

The script reports NOT_READY if any of these are true:

• PR is not in OPEN state
• PR is still a draft
• Merge state is not CLEAN or HAS_HOOKS
• Any CI check is failing
• Any CI check is still pending
• Local gates (lint/format/tests) fail
• PR body policy fails, such as missing evidence for runtime/viewer/client changes

Typical workflow

# 1. Make sure local gates pass
uv run ruff check . && uv run ruff format --check . && uv run pytest tests/ -x --timeout=60

# 2. Push and open PR
git push origin my-branch
gh pr create --title "feat: ..." --body "..."

# 3. Wait for CI, then run full preflight
scripts/check_pr.sh <pr_number>