ship-pr

Commit every change, push, open a pull request, and merge it once CI is green. Never commit onto the default branch. The arguments, if any, are a hint at what the change is about, not the message itself.

Keep a shipping record outside the worktree with the original and repair PRs, branches, checked commits, run IDs and attempts, logs, QA/review reports, and recovery counters. The original shipping operation and all its repair PRs share one set of recovery counters: initialize them only for a new shipping operation, and restore them from the record on continuation. Preserve the record across restarts and follow-up PRs.

Start from the session's working directory. When this session's work sits in another worktree (git worktree list), use that worktree as the execution cwd for every command and subprocess throughout shipping, CI recovery through recover-ci, and the post-merge repair, including gh, validation and hooks; leave the original working directory's changes untouched. git -C <path> scopes only that Git command, not subsequent commands. If the host cannot run hooks in the selected worktree, stop rather than run them from the original directory.

1. Run git status --short --branch, git diff HEAD --stat, git log --oneline origin/HEAD..HEAD (the branch commits), git log --oneline -10, and gh api 'repos/{owner}/{repo}/actions/permissions' --jq .enabled (whether Actions is enabled). Read the full diff (git diff HEAD), every untracked file git status lists, and, when there are branch commits, their diff (git diff origin/HEAD...HEAD) before writing anything. Read each issue the branch commits reference (#N) with the Read an issue operation in docs/agents/issue-tracker.md, since its comments hold the triage brief, or with gh issue view N --json title,body,comments when that file is missing.
2. Scan the working changes, untracked files, and every outgoing commit's content for credentials, tokens, private keys, and any value that does not belong in this repository. Inspect each commit relative to its parents, including root commits, merge resolutions, and values introduced then removed by a later commit; the net branch diff alone is insufficient because the push publishes intermediate history. Determine the outgoing commits against the destination remote's current refs. If you find a secret anywhere in that content, stop, commit and push nothing, and report it without exposing the value. Do not rewrite history automatically.
3. If the current branch is the repository's default branch, create and switch to a new one first: type/kebab-description, where type matches the Conventional Commit type you are about to use and the description comes from the change itself. Any branch commits move to the new branch with it: then run git branch -f <default> origin/<default> so the default branch matches its remote and the merge can fast-forward it.
4. Stage the changes. Prefer explicit paths over git add -A. An untracked directory that holds a local tool's state (an index, cache, or database, such as .codegraph/) belongs in the root .gitignore, even when it ships its own .gitignore: add its path there, stage that line with the rest, and say so in the report.
5. If staged changes exist (git diff --cached --quiet exits 1), write a Conventional Commit type(scope): description, matching the subject style already in git log, and commit them. When the oss-writing skill is installed, load and follow it through the host's skill mechanism for the wording. With no staged changes, keep the existing commits and continue without an empty commit. Any other exit status is an error to resolve, not an empty index.
6. Run git push -u origin HEAD with a 10-minute timeout: a pre-push hook can run the whole test suite. The outgoing-history screening in step 2 applies even when no new commit was needed. If the hooks must run against a scratch copy, complete the scratch dependency preflight in that exact copy before pushing. Use the normal unchanged hooks, launched from the selected shipping worktree.
7. Create the PR with gh pr create, or update the existing PR for this branch after a repair. The squash merge makes the title the one commit on the default branch, so the title and body cover the whole branch: your commit's subject when it is the branch's only commit, otherwise one Conventional Commit subject spanning every commit. Use the repository's pull request template when it has one. Otherwise, load and follow the pr skill through the host's skill mechanism for the body, and load and follow oss-writing for the wording when that skill is installed, even when no commit was written in step 5.
8. Inspect applicable PR checks and commit statuses at the exact head, including external CI, and use gh pr checks --watch until they settle. It exits non-zero on failure, so allow that and read the result. Actions enabled false means only that GitHub Actions is disabled; external checks and statuses may still apply. If no checks appear, wait 20 seconds and query again. Percent-encode the base branch as one URL path parameter (/ becomes %2F) and use that encoded value for <base> in both lookups: read branch protection's required checks with gh api 'repos/{owner}/{repo}/branches/<base>' --jq .protection.required_status_checks (available on every plan), and rulesets with gh api --paginate 'repos/{owner}/{repo}/rules/branches/<base>', inspecting every page it returns: the endpoint pages its results, and several repository and organization rulesets can apply to one branch. A rulesets 403 whose message says to upgrade to GitHub Pro or make the repository public establishes that rulesets do not apply on this plan, not unavailable configuration; do not retry it with the /protection or /rulesets endpoints. Report no CI only when repository configuration and required-check settings establish that none applies. A missing expected check or genuinely unavailable configuration (any other failure) is blocked, not green.
9. Green: gh pr merge <PR URL> --squash --match-head-commit <checked-head>, where <checked-head> is the head SHA step 8 checked, then confirm gh pr view <PR URL> --json state,mergedAt reports MERGED. Keep the branch and worktree while this worker is alive: shell cd does not move the harness or its hooks out of their working directory. The orchestrator removes its clean worktree after the worker exits; a standalone run leaves local cleanup to its caller. On a failed check, load and follow the recover-ci skill through the host's skill mechanism, passing the PR URL, the checked head SHA, and the recovery counters from the shipping record, with the record as the place each spend is written. Record its outcome and evidence, then return to the CI gate for the repaired head. Merge only with all required checks green on that exact head, and preserve branch protections. A stopped or budget-exhausted outcome leaves the PR unmerged with its evidence and remaining blocker.
10. Merged: close each issue the branch commits reference (#N, or a local issue path) that is still open, since the merge is what finishes it and a closed issue unblocks the tickets that wait on it. Use the Close operation in docs/agents/issue-tracker.md with the comment Merged in <PR URL>., or gh issue close N --comment when that file is missing.
11. Verify the CI and deployment workflows triggered by this merge before reporting completion. Resolve the merge SHA and identify applicable workflows from repository configuration, including chained workflows; use gh to inspect runs for that exact commit. Wait for them to settle. If an expected run has not registered, wait 20 seconds and query again; a still-missing expected run is blocked, not success. Record intentionally filtered/skipped workflows or no configured post-merge workflow separately. A failed run follows the post-merge repair, which recovers it through recover-ci. A pending approval or unavailable external service stays blocked without bypass. Keep the caller's ship slot through this step and report a failed or blocked default-branch run immediately so it can hold further merges.
12. Report every original and repair PR URL and merge SHA, issues closed, CI outcomes and remaining coverage gaps, recovery counters, retained branches, and the shipping record path. Distinguish a successful original merge from blocked post-merge verification. Report the .gitignore line from step 4 if one was added.