close-github-pr

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.