v0.2.0 to v0.2.1

---

name: ready-to-merge

description: Pre-merge gate — verify a PR is green, approved, in sync, and free of obvious risk, then (on explicit approval) squash-merge it. Composes /pr-status, /contract-check, and /review-pr rather than reimplementing them.

allowed-tools: "Read,Grep,Glob,Bash(git:*),Bash(gh pr list:*),Bash(gh pr view:*),Bash(gh pr merge:*),Bash(gh repo view:*),Bash(~/.agents/skills/ready-to-merge/scripts/gh-branch-view.py:*),Bash(~/.agents/skills/ready-to-merge/scripts/gh-branch-delete.py:*),Bash(~/.agents/skills/pr-status/scripts/gh-pr-list-open.sh:*),Bash(~/.agents/skills/pr-status/scripts/gh-pr-details.sh:*),Bash(~/.agents/skills/pr-status/scripts/gh-pr-checks.sh:*),Bash(~/.agents/skills/pr-status/scripts/gh-pr-reviews.sh:*),Bash(~/.agents/skills/pr-status/scripts/gh-pr-threads.sh:*),Bash(~/.agents/skills/pr-status/scripts/gh-pr-merge-state.sh:*),Bash(~/.agents/skills/review-pr/scripts/gh-pr-view.sh:*),Bash(~/.agents/skills/review-pr/scripts/gh-pr-diff.sh:*),Bash(~/.agents/skills/review-pr/scripts/gh-pr-current-number.sh:*),Bash(~/.agents/skills/ready-to-merge/scripts/git-unpushed.sh:*),Bash(~/.agents/skills/ready-to-merge/scripts/merge-timing.py:*),Bash(./scripts/contract-check:*),Bash(./scripts/trello-api:*),Bash(bd close:*),Bash(bd list:*),Bash(bd show:*),Bash(date:*),Bash(wc:*),Skill,AskUserQuestion,mcp__jira__jira_get"

model-tier: standard

model: sonnet

effort: high

author: "flurdy"

---

# Ready to Merge — Pre-Merge Gate

Verify a PR is safe to merge, present a terse readout, and — only after explicit user approval — squash-merge it.

This skill is a **synthesis layer**: it calls into `/pr-status`'s scripts, optionally `/contract-check`, and reuses `/review-pr`'s view/diff scripts. It does NOT reimplement those skills.

## Relationship to other skills

- **`/pr-status`** — passive multi-PR dashboard. This skill is single-PR, decision-oriented, and ends with an action.

- **`/review-pr`** — deep AC-vs-diff review. Linked but not auto-invoked. Suggest it if the diff is large or AC fit is unclear.

- **`/contract-check`** — read-only contract health audit. Auto-invoked only when pacts are present in the repo, and scoped to `status` (summary only).

- **`/contract-test`** — contract test *runner* (generate → sync → verify). Never auto-invoked here — CI already ran the tests on push. Surfaced as a remediation pointer when `/contract-check` flags stale or uncommitted pacts.

- **`tracking-auditor`** (agent) — branch-vs-ticket scope check. Suggest it if the diff looks broader than the ticket.

## Usage

```

/ready-to-merge # PR for current branch

/ready-to-merge 5753 # explicit PR number

/ready-to-merge --no-merge # report only, never offer to merge

```

## Merge timing policy

Optional and opt-in: without a policy, timing is never checked or rendered. A policy is the

nearest `merge-timing.toml` in a directory **above** the repository's top level, for example

`~/Code/{client}/merge-timing.toml`. A file inside the repository is ignored and reported, so a

PR cannot relax its own restriction. A candidate inside another checkout of the same repository is

unknown, not trusted. The nearest trusted file wins; there are no built-in defaults.

```toml

timezone = "Europe/London" # IANA name; never the machine's timezone

[[rule]]

name = "business-hours"

enforcement = "required" # blocks the merge offer; only for explicit client policy

days = ["mon", "tue", "wed", "thu", "fri"] # allowed days; omit for every day

start = "09:00" # earliest merge time; omit for 00:00

end = "17:30" # merge before this time; omit for 24:00

[[rule]]

name = "late-afternoon"

enforcement = "advisory" # caution only; normal confirmation still applies

end = "16:00"

end_by_day = { fri = "12:00" } # day-specific cutoffs replace end

```

Every rule must allow the current policy-local time. Any required violation is `required`;

otherwise any advisory one is `advisory`. Unknown keys, missing `enforcement`, invalid times or

timezones, empty or contradictory day settings, and unreadable files are `unknown`, never clear.

Holidays, overrides and automatic scheduling are out of scope.

The helper prints one JSON object: `status` (`none`, `clear`, `advisory`, `required` or

`unknown`), plus `policy`, `timezone`, `local_time`, `weekday`, `violations` (`rule`,

`enforcement`, `reason`), `next_allowed`, `ignored` or `error` when applicable. Treat exit 3,

any other non-zero exit, or unparseable output as `unknown`. `--now` exists for tests only;

never pass it here. Requires Python 3.11+ (standard library only) and Git 2.31+.

## Procedure

### Phase 1 — Resolve PR

```bash

# If no number given:

~/.agents/skills/review-pr/scripts/gh-pr-current-number.sh

# Fallback: gh pr view --json number --jq '.number'

```

Resolve owner/repo from `git remote get-url origin`.

### Phase 2 — Gather (run in parallel where possible)

Run these in parallel — they're independent fetches:

1. **PR details** (state, mergeState, reviewDecision, checksState, approvers, threads, isDraft, base, head):

```bash

~/.agents/skills/pr-status/scripts/gh-pr-details.sh {owner} {repo} {pr}

```

2. **PR view** (title, body, additions, deletions, changedFiles, files):

```bash

~/.agents/skills/review-pr/scripts/gh-pr-view.sh {pr}

```

3. **Diff**:

```bash

~/.agents/skills/review-pr/scripts/gh-pr-diff.sh {pr}

```

4. **Stacked children** — PRs that target THIS PR's head branch:

```bash

gh pr list --base {head-branch} --state open --json number,title,headRefName,url

```

5. **Local working copy** — if the resolved PR matches the current branch, also:

```bash

git status --porcelain

~/.agents/skills/ready-to-merge/scripts/git-unpushed.sh # unpushed commits

```

Uncommitted/unpushed work is a hard blocker.

Use the wrapper for the unpushed-commits check — never inline `git log @{u}..HEAD`.

The sandbox flags the bare `@{u}..HEAD` as brace expansion, so it can never be auto-approved.

6. **Merge timing** — from the PR's repository checkout:

```bash

~/.agents/skills/ready-to-merge/scripts/merge-timing.py

```

Keep the result as the timing snapshot shown to the user.

### Phase 3 — Ticket cross-reference

Extract the Jira key from branch name first, then PR title (`/[A-Z]+-\d+/`).

If found:

```

mcp__jira__jira_get

path: /rest/api/3/issue/{key}

jq: "{key: key, summary: fields.summary, status: fields.status.name, issuetype: fields.issuetype.name}"

```

Flag if Jira status is not one of: `Code Review`, `In Progress`, `Test/Review`, `Ready for Test`. Specifically:

- `Done` → ⚠️ already closed before merge — unusual, confirm with user.

- `Backlog` / `Ready to Work` → ⚠️ ticket never moved to In Progress — flow drift.

- `Blocked` → ❌ confirm before merging.

**Beads**: if `bd` is available, look for a bead referencing this Jira key:

```bash

bd list --status=in_progress

bd list --status=open

```

Match by Jira key in title or description. Note id + status. If a bead is `in_progress` for this work it will need closing after merge.

**Trello**: only if `./scripts/trello-api` exists in the repo. Look for a card matching the branch or ticket — best effort, skip silently if none found.

### Phase 4 — Diff risk scan

Walk the changed files list (don't re-read the whole diff). Flag only what's present — quiet success, loud risk:

| Risk | Detection (heuristic) |

|------|-----------------------|

| Migration / schema change | path matches `migrations/`, `migrate/`, `*.sql`, `schema.prisma`, `alembic/` |

| Dependency change | `package.json`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `requirements.txt`, `Cargo.lock`, `go.mod`, `Gemfile.lock`, `build.sbt` |

| Secrets / sensitive | `.env*`, `*.pem`, `*.key`, files matching `credential` / `secret` |

| CI / infra changes | `.github/workflows/*`, `Dockerfile*`, `terraform/`, `helm/` |

| Public-API delete | grep diff for removed `export `, `pub fn`, `public def` |

| Feature flag absent | new behaviour added but no flag toggle — flag only if PR description claims to be gated |

| Leftover debug | `console.log`, `dbg!`, `println!`, `pp `, `binding.pry`, `debugger` added in diff |

| Lingering TODOs | new `TODO`/`FIXME`/`XXX` lines added |

| Test/code ratio | non-trivial code change (≥50 LOC added in non-test files) with **zero** new/modified test files → flag low coverage |

Skip rows that have nothing to report — only show risks that fired.

### Phase 5 — Gate evaluation

Compute three buckets:

- **Blockers (❌)** — anything in this list and the PR cannot merge:

- `isDraft: true`

- `reviewDecision != APPROVED`

- CI checks not `SUCCESS`

- unresolved threads > 0

- `mergeState` is `DIRTY` (conflict), `BLOCKED`, or `BEHIND`

- base is not `main`/`master` (PR is stacked — should be merged via parent, not directly)

- uncommitted or unpushed local changes (if PR matches current branch)

- Jira status `Blocked`

- **Warnings (⚠️)** — proceed-with-caution, don't auto-block:

- any risk fired in Phase 4

- `mergeState: UNKNOWN` — GitHub hasn't computed mergeability yet; usually transient. Suggest a retry before merging.

- stacked children exist (they'll need rebasing post-merge)

- Jira status drift (`Backlog`, `Done`, missing)

- bead still `in_progress` (will need closing post-merge)

- large diff (≥500 LOC or ≥20 files changed) — recommend `/review-pr` for depth

- **Notes (ℹ️)** — informational only:

- post-merge follow-ups (close bead, transition Jira, rebase children)

- `ignored` in-repository `merge-timing.toml` (untrusted; move it above the repository)

Merge timing is evaluated **separately** from technical readiness; it never changes the three

buckets or the technical verdict:

- `none` / `clear` — render nothing (quiet success).

- `advisory` — 🕒 caution; the merge may still be offered with normal confirmation.

- `required` — ⛔ no merge offer, while still reporting technical readiness.

- `unknown` — ⛔ no merge offer: mandatory applicability cannot be established.

### Phase 6 — Optional contract check

Only if pacts are present in the repo (`./scripts/contract-check` exists, or `**/pacts/` directory present, or `*Consumer*.scala`/`*.consumer.test.*` files exist):

```

Skill /contract-check status

```

Add a row to the gate table for **Contracts**. If WARN or FAIL, move to Warnings (don't auto-block — contract drift rarely blocks a single PR merge but should be visible).

Do NOT auto-run `/contract-test` — it's the *runner* (generate → sync → verify) and is redundant with CI, which already ran on push. If `/contract-check` surfaces stale, uncommitted, or sync-gap pacts, recommend `/contract-test` (or `/contract-test sync` / `full`) as the **remediation** under Risks, and let the user run it before re-invoking `/ready-to-merge`.

### Phase 7 — Draft squash commit

The user squash-merges by default. Pre-draft the squash commit so they can approve or tweak:

- **Subject**: the PR title, verbatim (already conventional-commit style at PR creation time).

- **Body**: 2–5 bullets summarising the change, derived from the PR description and diff. Strip boilerplate (template sections that weren't filled in). Always include a trailing `Jira: {KEY}` line if a ticket is linked.

Keep the body under ~10 lines. The user can edit if they want more.

### Phase 8 — Render the readout

Render compactly. Skip empty sections.

```markdown

## PR #{number} — Ready-to-Merge Check

**{title}**

[#{number}]({url}) · `{head}` → `{base}` · +{additions} / -{deletions} across {changedFiles} files

| Gate | Status |

|--------------|-------------------------------------|

| CI | ✅ / ❌ / ⏳ |

| Approvals | ✅✅ alice, bob (or 🔔 awaiting) |

| Threads | ✅ 0 / 💬 N unresolved |

| Sync w/ base | ✅ clean / ❌ behind / 💥 conflict |

| Mergeable | ✅ / ❌ {reason} |

| Contracts | ✅ / ⚠️ / — |

| Tests | ✅ N test files touched / ⚠️ none |

**Linked work**

- Jira: [{KEY}]({url}) — {summary} _(status: {status})_

- Bead: `{bead-id}` — {status}

- Trello: {card-name} (or `—`)

**Stacked children** _(omit section if none)_

- ⚠️ #{n} {title} — will need `/rebase merged {this-branch}` after this merges.

**Diff summary**

- 3–5 bullets, each one short, derived from the diff. No file lists.

**Risks** _(omit section if empty — do not pad with "no secrets" etc.)_

- ⚠️ Migration added `db/migrate/20260511_xxx.sql` — verify backwards compatible.

- ⚠️ 87 LOC added without new tests in `src/foo.ts`.

**Drafted squash commit**

```

{subject}

- bullet 1

- bullet 2

Jira: {KEY}

```

**Merge timing** _(omit for `none` / `clear`)_

- 🕒 / ⛔ {Ddd HH:MM} {timezone} — {reason} _({rule}, {enforcement})_

- Next allowed: {next_allowed in policy-local time}, or `not computable within a week`

- ⛔ Policy unknown: {error} — merge not offered

### Verdict

❌ Blocked — {reason}

or

⚠️ Mergeable with warnings — review risks above.

or

🚀 Ready to squash-merge.

Then, only when timing fired, one timing line:

🕒 Timing caution — {reason}.

or

⛔ Technically ready, but merge timing does not allow merging now — {reason or error}.

```

### Phase 9 — Ask for go/no-go

If verdict is ❌ blocked, stop here. Print the blockers and suggest next steps (often `/rebase main`, `/review-comments`, `/clean-code`).

If `--no-merge` was passed, stop here regardless. The readout still reports applicable timing.

If timing is `required` or `unknown`, stop here: do not offer the merge. Report `next_allowed`

when present. Do not wait, sleep, schedule or retry until then; the user re-invokes later.

If timing is `advisory`, keep the caution visible in the question; it does not change the options.

Otherwise ask the user via `AskUserQuestion`:

> Question: `Squash-merge PR #{n} now?`

> Options:

> - **Yes — merge with drafted commit** (recommended when verdict is 🚀)

> - **Edit commit message first** — user supplies new subject/body, then re-prompt

> - **Wait** — print no further action, end the skill

### Phase 10 — Merge

Only on explicit "Yes". Use the GitHub CLI's squash mode with the drafted (or edited) commit.

**Recheck timing immediately before merging.** As the tool call directly before `gh pr merge`, run

`merge-timing.py` again. Proceed only if its `status` and violated rule names match the timing

snapshot shown when the user approved, and the status is not `required` or `unknown`. Otherwise do

not merge: render the new timing. If it is now `required` or `unknown`, stop. If it is now `clear`

or `advisory` but differs, ask again with fresh confirmation. Approval never carries across a

timing change, and a recheck never merges, waits or schedules anything by itself.

**Do NOT pass `--delete-branch`.** It makes `gh` run *local* git operations (switch to the default branch, pull, delete the local branch) as a side effect of the merge. In a worktree checkout — where `main`/`master` is checked out in a *different* worktree — that local step fails with `fatal: '{branch}' is already used by worktree at ...` **even though the remote merge succeeded**. The merge is done; only the local cleanup errored, which reads as a scary failure for a no-op. Branch deletion is handled separately below, against the remote only.

```bash

gh pr merge {number} --squash \

--subject "{subject}" \

--body "$(cat <<'EOF'

{body}

EOF

)"

```

**Idempotency:** if the command prints `Pull request ... was already merged` (e.g. a prior attempt merged remotely before erroring on local cleanup), treat that as **success** — do not retry or alarm. Confirm with `gh pr view {number} --json state --jq .state` (expect `MERGED`) if unsure.

After merging, remote-branch cleanup is a **separately confirmed** action, not part of merge approval.

Never infer deletion permission from merge approval. First re-read the selected PR, repository default

branch, and dependent PRs read-only:

```bash

~/.agents/skills/review-pr/scripts/gh-pr-view.sh "{owner}" "{repo}" "{number}"

gh repo view "{owner}/{repo}" --json nameWithOwner,url,defaultBranchRef

gh pr list --repo "{owner}/{repo}" --base "{head-branch}" --state open --json number,title

```

Require PR state `MERGED`, the same selected PR identity, `headRefName`, `headRefOid` and

`headRepository` as the reviewed snapshot, and repository identity matching `{owner}/{repo}`.

Skip cleanup for a fork or unknown head repository; never redirect deletion into a fork.

The helpers support github.com only: skip non-public-GitHub targets or a host mismatch rather

than changing hosts. Require a known `defaultBranchRef.name`; never delete the default branch,

the PR's base branch, `main` or `master`. If dependent PRs remain, skip cleanup and report them.

Missing or changed metadata is not deletion evidence.

Then read the branch through the fixed GET helper:

```bash

~/.agents/skills/ready-to-merge/scripts/gh-branch-view.py "{owner}" "{repo}" "{head-branch}"

```

Require successful JSON with `name` equal to `headRefName` and `sha` equal to the reviewed

`headRefOid`. On any error or mismatch, skip deletion. A 404 does not prove auto-deletion: the

branch may be missing or inaccessible. Report cleanup unavailable, not successful or auto-deleted.

Only after those checks, show the exact command below and ask for **fresh confirmation** to delete

that specific remote branch. Declining, abandoning or denying permission means skip cleanup.

On approval, execute it as the next standalone tool call, never chained with the reads:

```bash

~/.agents/skills/ready-to-merge/scripts/gh-branch-delete.py "{owner}" "{repo}" "{head-branch}"

```

Both helpers require Python 3.10+, Git and authenticated `gh`; they share

[`scripts/github_branch.py`](scripts/github_branch.py) for target validation. Each accepts exactly

three positional arguments, validates repository/ref syntax and encodes URL-sensitive branch

characters while retaining ref separators. Methods and endpoint namespaces are fixed in separate

entry points; no arbitrary method, endpoint, host or flags are accepted. The read helper never

mutates. The delete helper rejects `main`/`master`, but cannot itself prove merge state or a custom

default branch: caller checks and confirmation remain mandatory. Keep the delete path separately

prompted in user permission policy; do not edit settings automatically. Skill grants are

Claude-style metadata, not a portable enforcement guarantee.

This REST flow does not provide atomic compare-and-delete: the branch can change after the GET.

Do not claim race-free deletion or retry an ambiguous result. Both helpers pass through `gh`

stdout, stderr and exit status without retries; malformed arguments return 2 and missing tools 127.

The DELETE is **best-effort**: on API/SSO failure or local permission denial, note that cleanup

was not confirmed and move on. Never delete the *local* branch or switch worktrees yourself.

After merge succeeds, print:

```

✅ Merged #{number}.{branch-note}

```

where `{branch-note}` is ` Remote branch deleted.` only on confirmed DELETE success, or

` (remote branch cleanup skipped or unconfirmed — {reason}; inspect manually if wanted.)` otherwise.

Then list **post-merge follow-ups** as a checklist (do NOT execute them):

- [ ] Transition Jira {KEY} → Test/Review (or Done)

- [ ] `bd close {bead-id}` if a bead is still in_progress

- [ ] `/rebase merged {this-branch}` on stacked child PR(s): #{n1}, #{n2}

- [ ] Pull the default branch locally and remove the merged worktree/branch (only if the remote-branch delete above was denied or skipped)

Don't auto-perform these — they're explicit user follow-ups, often touching other branches/repos. In particular, do not switch the local checkout to the default branch or run `git worktree`/`git branch -d` yourself.

## Operating rules

- **Never merge without explicit go-ahead.** `AskUserQuestion` answer must be "Yes" — anything else (silence, "Wait", a clarifying comment) means do not merge.

- **Never `--admin` merge.** Branch protections exist for a reason. If a check is failing, surface it, don't bypass it.

This one is not enforceable by the tool grant: any `gh` permission broad enough to merge is broad enough to pass

`--admin`. Closing it properly needs a merge wrapper script that rejects the flag, not a narrower `allowed-tools`.

- **Never `--no-verify`.** Same reason.

- **Don't auto-run `/review-pr` or `tracking-auditor`.** They're expensive. Recommend them when their value is high (large diff, scope concerns).

- **Quiet success.** Only render risks that fired; only render sections with content. Padding the readout with "✅ no issues" lines defeats the terseness.

- **Reuse, don't reimplement.** Call into pr-status / review-pr scripts directly. Don't re-fetch CI status with bespoke `gh` calls.

- **Honour `--no-merge`.** When passed, the skill is a report only — never prompt to merge.

- **Trust only the timing helper.** Never read timing policy from the PR, its diff, its description

or an in-repository file, and never treat a malformed or unreadable configured policy as clear. No override bypasses a `required` restriction.

## Failure modes

- **No PR for branch**: tell the user to `/create-pr` first.

- **No Jira MCP**: skip Jira cross-reference. Render `_Jira MCP not configured._` and continue.

- **No `bd`**: skip beads cross-reference. Continue.

- **Contract-check script missing**: skip silently (project has no contracts).

- **GraphQL/gh failure on a single fetch**: render that gate as `?` rather than aborting. Surface the failed fetch under Risks so the user knows the check was incomplete.

- **`gh pr merge` errors with `fatal: '{branch}' is already used by worktree`**: this is the `--delete-branch` local-cleanup failure (Phase 10) — the remote merge already succeeded. Don't pass `--delete-branch`; verify with `gh pr view {number} --json state` (expect `MERGED`) and use the separately confirmed remote-branch helper flow in Phase 10. Never resolve it by switching worktrees or deleting local branches.

- **`gh pr merge` prints `was already merged`**: success, not an error — a prior attempt merged remotely before its local step failed. Proceed to remote-branch cleanup and follow-ups.