atomic-issues-prs

Atomic issues and PRs

Contract

Inputs

Required: a working tree containing the change-set to publish and a gh-authenticated GitHub account. Optional: per-unit routing overrides (issue+PR vs PR-only) stated by the user; dependency order among units.

Procedure

1. Run gh auth status. If unauthenticated, stop and ask the user to run gh auth login.
2. Resolve the canonical (upstream) slug before any permission check. Read remotes with git remote -v; pick the contribution target as upstream if present, else origin. Detect a fork relationship with gh repo view <slug> --json nameWithOwner,parent,defaultBranchRef; a non-null parent means the canonical slug is parent.nameWithOwner. If there is no clear single upstream (no upstream remote and ≥2 plausible non-origin candidates, or gh's detected parent disagrees with the upstream remote) or origin has genuinely diverged from upstream (no common merge-base, or origin was re-created/renamed/renewed), prompt the user for the target repo. Plain fork-behind, where origin is merely behind upstream with a shared merge-base, is not ambiguity and must never prompt.
3. Query permission on the canonical slug: gh repo view <canonical-slug> --json viewerPermission. viewerPermission ∈ {ADMIN, MAINTAIN, WRITE} ⇒ direct mode; otherwise ⇒ fork mode. Record the canonical default base branch from defaultBranchRef.
4. Group working-tree changes into atomic units by mechanism/file boundary: one concern per unit. Never bundle unrelated changes. Commit the whole set into N atomic commits first, running the repo-native type-checker and linter before each commit. Each unit becomes one self-contained commit, which allows per-unit branches to be created by cherry-picking. Never re-stage a dirty tree, which would let later units swallow earlier diffs. Present the unit→commit list to the user, then proceed.
5. Route each unit by whether it changes observable behavior: behavior-affecting → Issue + linked PR, because a tracking issue gives the change a changelog/discussion anchor; mechanical → PR-only, because a self-explanatory change needs no separate tracking. Honor an explicit per-unit override if the user states one; otherwise route silently.
6. Resolve the push URL once, by URL not remote name, to avoid undefined targets and remote-name collisions. Direct mode: push URL = https://github.com/<canonical-slug>. Fork mode: fork owner = gh api user --jq .login; fork slug = <login>/<repo>. If origin already points to a prior personal fork whose owner ≠ canonical owner and ≠ the authenticated login, print a non-blocking warning noting the account mismatch; do not stop the run. If the fork does not exist, create it with gh repo fork <canonical-slug> --clone=false and note the fork slug in the output. Push URL = https://github.com/<fork-slug>.
7. For each unit, in dependency order:
   1. Create the branch and cherry-pick the unit commit. Independent unit: git branch <branch> <canonical-default-base> then git cherry-pick <unit-commit>; PR bases on <default>. Dependent unit in direct mode: parent-ref = the prerequisite unit's already-pushed branch; PR bases on that branch (a stacked PR); cherry-pick only this unit's commit so no prerequisite is lost. Dependent unit in fork mode: cross-fork stacking cannot be expressed (a fork PR's base must be a branch in the canonical repo), so flatten onto <canonical-default-base> and prefix the PR body with a warning line naming the prerequisite unit and noting the dependency was flattened; the compromise is never silent.
   2. git push <push-url> <branch>:refs/heads/<branch> (same form both modes; only the URL differs).
   3. gh pr create --repo <canonical-slug> --body-file <tmp>. Direct mode: --base <parent-ref> --head <branch>; fork mode: --base <default> --head <fork-owner>:<branch>; capture PR #M.
   4. If the unit routed to Issue + linked PR: gh issue create --repo <canonical-slug> --title "<summary>" --body-file <tmp> with a body that references PR #M; capture #N.
   5. Amend the PR body by appending Closes #N to the PR's existing body. Reuse the body-file from step 3 (append the line and rewrite the file) or fetch the current body first with gh pr view <M> --json body; then write it with gh pr edit <M> --repo <canonical-slug> --body-file <amended-tmp>. gh pr edit --body-file replaces the whole body, so never write a bare Closes #N as the entirety of it.
   6. Emit the issue/PR URLs; move to the next unit.
8. For PR-only routed units (no issue filed in step 4), skip the issue-create and body-amend steps entirely; no dangling Closes. Done when: every logical unit has the correct issue/PR routing, base and head, links, and reported URLs.