---
name: close-github-pr
description:
  "Merge and close GitHub pull requests with gh after provider-specific checks gating, draft readiness, merge, and local cleanup. Use with
  `kind=feature` or `kind=bug`."
---

# Close GitHub PR

## Contract

Prereqs:

- Run inside the target GitHub-backed git repo.
- `git`, `gh`, and `python3` available on `PATH`.
- Working tree clean (`git status --porcelain=v1` is empty).

Inputs:

- `kind=feature|bug`.
- PR number, or current-branch PR when `--pr` is omitted.
- Optional user-requested pre-close specialist review through
  `code-review-specialists`.
- Optional cleanup controls: `--keep-branch` and `--no-cleanup`.
- Optional no-CI acknowledgement: `--allow-no-checks`.

Outputs:

- Required PR checks verified as passing, or checks explicitly accepted as
  missing with `--allow-no-checks`. Optional skipped checks do not block merge.
- PRs that would close plan-tracking issues are checked before merge; incomplete issue-backed state blocks with an exact lifecycle next
  action.
- User-requested pre-close specialist review completed before merge, when
  requested, with no concrete findings waiting on user decision.
- Draft PRs marked ready with `gh pr ready <pr>` before merge.
- PR merged with a merge commit.
- Remote head branch deleted unless `--keep-branch` is supplied.
- Local checkout switched back to base branch and updated; local head branch deleted unless `--no-cleanup` is supplied.

Exit codes:

- `0`: success
- `1`: workflow blocked/failure (dirty tree, missing checks without explicit allow, failed checks, non-open PR, merge failure, command failure)
- `2`: usage error

Failure modes:

- PR checks are missing and `--allow-no-checks` was not supplied.
- Required PR checks are failing, canceled, timed out, skipped, blocked, or
  still pending.
- The PR would auto-close a plan-tracking issue whose latest `execute-from-tracking-issue:state:v1` comment is not complete.
- User-requested pre-close specialist review reports concrete findings that need
  user decision before merge.
- PR is draft and automatic `gh pr ready` fails.
- PR is not open, not mergeable, or `gh`/`git` permissions are insufficient.

## Scripts (only entrypoints)

- `$AGENT_HOME/skills/workflows/pr/github/close-github-pr/scripts/close-github-pr.sh`

## Optional User-Requested Review

- This gate is optional. Run it only when the user explicitly asks for review,
  specialist review, or review before close.
- End-to-end `deliver-github-pr` runs the mandatory shared delivery specialist
  review gate before invoking this close workflow. Keep this direct close gate
  optional so existing PR close/cleanup requests do not become implicit review
  orchestration.
- Run it before invoking `close-github-pr.sh` for final merge and cleanup; the
  close helper has no review flag.
- Resolve the PR number and base branch with `gh pr view`, then use the PR base
  branch as the `code-review-specialists` diff base.
- Keep `code-review-specialists` read-only: do not post PR comments, fix code,
  mark the PR ready, merge, or clean up from that workflow.
- Honor the `code-review-specialists` scope and skip rules unless the user
  forced a specialist or all specialists.
- If the specialist report contains concrete findings, stop before merge and
  report them for user decision. If there are no concrete findings, or the user
  explicitly accepts them, continue the normal close workflow.

Shared delivery gate reference:
`skills/workflows/_shared/references/DELIVERY_SPECIALIST_REVIEW_GATE.md`

## Workflow

1. Resolve PR metadata
   - Resolve PR URL, base branch, head branch, state, and draft state through `gh pr view`.

2. Run optional user-requested review
   - If the user requested pre-close review, complete the optional review gate
     before invoking the close helper.

3. Gate on required GitHub checks
   - Default behavior blocks missing checks:
     - `close-github-pr.sh --kind <feature|bug> --pr <number>`
   - Repositories with no checks require explicit acknowledgement:
     - `close-github-pr.sh --kind <feature|bug> --pr <number> --allow-no-checks`
   - Required checks are the hard merge gate. Optional skipped checks are
     non-blocking when required checks pass.
   - `--allow-no-checks` only accepts missing checks. It must not bypass failed, canceled, timed out, blocked, pending, skipped, or unknown
     required check states.

4. Gate plan-tracking issue auto-close
   - Inspect `closingIssuesReferences` through `gh pr view` before merge.
   - For issues with plan-tracking source/plan/state markers, require
     `execute-from-tracking-issue/scripts/tracking-issue-lifecycle.sh --dry-run --require-complete`.
   - If the gate fails, stop before `gh pr merge` and report the next action: post a complete
     `execute-from-tracking-issue:state:v1` comment, then merge and run `tracking-issue-closeout`.
   - Non-tracking closing issues keep the normal close behavior.

5. Mark ready and merge
   - If draft, run `gh pr ready <pr>` automatically.
   - Merge with `gh pr merge <pr> --merge` plus `--yes` when supported.

6. Cleanup
   - Delete the remote head branch unless `--keep-branch` is supplied.
   - Switch to the base branch, pull fast-forward, and delete the local head branch unless `--no-cleanup` is supplied.
   - If the base branch is locked by another worktree, fall back to detached `origin/<base>` for local branch deletion.

## Kind Policy

- `kind=feature`: use for feature PRs originally created by `create-github-pr`.
- `kind=bug`: use for bugfix PRs originally created by `create-github-pr`.
- The close mechanics are provider-specific and shared across both kinds; kind is retained for auditability and composition by
  `deliver-github-pr`.
