Codex Merge PR

Merge a pull request

Work the steps in order. Codex doesn't provide skill-scoped command hooks, so the scripts enforce the terminal invariants while these instructions keep every mutating command on the sanctioned path. Never run gh pr merge directly.

Left alone, GitHub writes the squash message by concatenating every commit on the branch. That text has never passed a commit-msg hook, and it arrives on the default branch where the rest of the toolchain assumes those hooks ran. Nothing lints it afterwards. This workflow writes the message itself and puts it through what a commit answers to.

Preflight

Run bash .agents/skills/codex-merge-pr/scripts/preflight.sh [number], passing the pull request number when the request names one.

Step 0: open the task list

Create these with update_plan, keeping exactly one item in_progress at a time.

1. Confirm the pull request is mergeable
2. Settle the published description
3. Write the squash message in SQUASH_AGENTMSG
4. Review the message with codex-review-squash-message
5. Run the commit-msg gates
6. Confirm the message with the operator
7. Merge and clean up

Stop before any of it where preflight reports a missing precondition, a draft pull request, or a failing check. Say what's wrong and hand back.

Step 1: confirm the pull request is mergeable

Preflight printed the state, the check rollup, and the review decision. Merging needs an open pull request that nobody marked as a draft, with every check green.

A failing check goes to codex-fix-pr, and a running one goes to codex-watch-pr. Neither belongs here, and the merge script refuses both anyway.

A mergeStateStatus of BEHIND or DIRTY is the third case. The branch needs the base underneath it before anything merges, so run the codex-rebase skill and push the result. Don't reach for GitHub's own update button: it merges the base into the branch, which leaves a merge commit this workflow never wrote a message for.

Where the repository requires a review decision, respect it. CHANGES_REQUESTED means the merge waits, whatever the checks say.

Step 2: settle the description first

The description is on GitHub at this point, and often nothing sits on disk. Fetch it back before revising it:

bash .agents/skills/codex-merge-pr/scripts/populate-description.sh <number>

That rebuilds PR_AGENTDESC.md from what the pull request currently says, reassembling the frontmatter from the properties set on the pull request. It refuses to overwrite an existing draft without --force, because a pr workflow further up the stack may have one in flight.

Merging is the last moment the description can change, and the squash message gets written from it, so a wrong description propagates that error into history.

Read what preflight printed under == description as published == against the commits it collapses. Where it no longer describes the branch, delegate codex-write-pr-description and then codex-review-pr-description in fresh agents, following the codex-pr review loop, then republish with bash .agents/skills/codex-pr/scripts/create-pr.sh.

Most merges skip this. A description that still fits doesn't need a pass, and a pull request nobody here authored has none of this machinery behind it, so take its description as it stands.

Step 3: write the squash message

bash .agents/skills/codex-merge-pr/scripts/squash-message.sh <number>

That prints a briefing and writes a skeleton. Nothing in it converts the description into a message, because no rewriting rule produces one. The commit that merges here is the one a whole branch leaves behind, so writing it means reading everything that landed and deciding what a reader years from now still needs.

Your briefing carries the description as published, every commit message the squash collapses in full, the diffstat, and the trailers those commits carry. Read it before writing a word. Commit bodies matter most. Each one already argued for itself once, and this is the last place that argument survives. Run the command on its own and read the whole thing. Piping it through head or tail keeps the trailing skeleton and drops those bodies, which nothing else in this workflow prints, and the script caps nothing on purpose, so a cap you add is one nobody downstream can see you added.

SQUASH_AGENTMSG at the repository root holds the skeleton, which a gitignore entry keeps out of history. Subject and footer come filled in. The body stays empty until you write it.

Subject

The script sets <pull request title> (#<number>). Keep the reference, because squash-merge.sh reads it back to confirm the draft belongs to this pull request. Fix the rest where the title described one commit rather than the branch. A squash leaves one commit behind, so the subject names what the whole stack did.

Body

The description was Markdown, written for a reviewer with the diff open beside it. This is plain text, and whoever reads it three years from now has neither.

Take from the description:

• Summary and Why, which carry the reason the branch exists
• Risk, but only where it names a rollback the reader wouldn't guess

Leave behind:

• Verification, entirely. It reported what a reviewer needed at the time, and the moment the suite changes it describes a run nobody can repeat.
• Risk that only says the change could be wrong.

Then read the result back against the commits. The commits outrank it. Descriptions get published early while branches keep growing, so the commits record what landed rather than what someone expected to land. Where a commit body gives a reason the description never stated, that reason belongs in the message. Otherwise it goes at the merge, with the commit that held it.

Avoid:

• Restating the diff. A reader who wants the what reads the diff.
• Walking the stack. A branch of eight commits becomes one account rather than eight paragraphs.
• Counting. No file, line, test, or commit counts.
• Provenance filler. Nothing about requests, review rounds, sessions, prompts, models, or tools.
• Markdown. No fenced blocks, headings, emphasis, links, or tables. Backticks around a literal identifier are fine.

Hard wrap the body at 72 characters and the trailers at 100.

Footer

The script fills this in. Closes lines come from the description's Related section, and the trailers come from the commits themselves, ordered with attribution first and sign-off last.

Check the closing references before going on. Related lists whatever the author put there, so a number that names a pull request or a document rather than an issue this branch closes comes out of the footer.