Merge Stacked PRs with merge command

[skarim]

This adds a new gh stack merge command built on GitHub's new async merge API, which can land multiple stacked PRs atomically. It merges some or all of a stack in one atomic operation: every PR up to and including the one you choose is merged into the base branch, and if any PR can't be merged, none are.

What's new

• Three ways to target a merge. No argument merges the current active local stack; a stack number merges a stack you don't have checked out (a purely remote operation); a PR number merges directly up to that PR.
• Interactive wizard. In a terminal, a three-step wizard lets you choose how far up the stack to merge (a bottom-anchored checkbox list, so everything below your selection is always included), pick the merge method (only the methods the repo allows, defaulting to your last-used one), and confirm — then a live view polls the merge to completion.
• Non-interactive / agent-friendly. With --yes or no TTY, the whole stack (or everything up to the given PR) merges without prompting, using your last-used merge method unless one is given via --merge / --squash / --rebase / --merge-method.
• Light pre-checks only. PRs are checked for being open and non-draft; GitHub evaluates branch protection and repository rules at merge time and reports the failure reason back. Because the merge is atomic, a failure lands nothing.
• Merge queues are handled automatically. The merge is submitted with merge_action: "default", so GitHub either merges the stack directly or, when the base branch uses a merge queue, adds it to the queue (reported back as an enqueued result). Bypassing merge requirements with admin privileges is not supported for stacks.

Changes

The command

• cmd/merge.go — the new gh stack merge command: resolves the target stack (current branch / stack number / PR number), computes the mergeable candidates (open, non-draft, contiguous from the bottom), and runs either the interactive wizard or the headless submit-and-poll path. Registered in cmd/root.go.

GitHub client

• internal/github/merge_async.go — an async stack-merge client over the REST API: MergeStackAsync (submit) and GetAsyncMergeResult (poll) on go-gh's REST client, returning a status enum (pending / merged / enqueued / failed); plus RepoMergeConfig (allowed methods and last-used default, via GraphQL) and PRTitles (batch PR titles for the picker). Added to ClientOps and MockClient.

Wizard TUI

• internal/tui/mergeview/ (new package) — the Bubble Tea wizard: a stepper banner, the bottom-anchored PR picker with a scrolling viewport, the allowed-method picker, the confirm step, and the live progress view.

Docs

• README.md, docs/ CLI reference and workflows guide, skills/gh-stack/SKILL.md, and AGENTS.md — document the command, its targeting and merge-method behavior, and how merges route to a direct merge or the merge queue.

Testing

• Unit tests for the command paths (cmd/merge_test.go), the async-merge client including status decoding and error mapping (internal/github/merge_async_test.go), and the wizard model (internal/tui/mergeview/model_test.go).
• go test -race -count=1 ./... and go vet ./... are clean, and the changed files pass gofmt.

---

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}

[Copilot]

Pull request overview

Adds gh stack merge for atomic stacked-PR merges through GitHub’s async merge API.

Changes:

• Adds local, stack-number, and PR-number merge targeting.
• Adds interactive and headless merge workflows.
• Extends GitHub clients, tests, and documentation.

Show a summary per file

File	Description
cmd/merge.go	Implements merge command behavior.
cmd/merge_test.go	Tests merge command paths.
cmd/root.go	Registers the command.
cmd/root_test.go	Tests command registration.
internal/github/merge_async.go	Adds async merge API support.
internal/github/merge_async_test.go	Tests async merge handling.
internal/github/client_interface.go	Extends the client interface.
internal/github/mock_client.go	Extends the mock client.
internal/tui/mergeview/model.go	Implements wizard state and polling.
internal/tui/mergeview/model_test.go	Tests wizard behavior.
internal/tui/mergeview/types.go	Defines wizard types.
internal/tui/mergeview/view.go	Renders the wizard.
README.md	Documents the command.
docs/src/content/docs/reference/cli.md	Adds CLI reference material.
docs/src/content/docs/guides/workflows.md	Adds merge workflow guidance.
skills/gh-stack/SKILL.md	Adds agent-facing merge guidance.
AGENTS.md	Updates architecture documentation.
.github/copilot-instructions.md	Updates Copilot repository guidance.

Review details

Comments suppressed due to low confidence (1)

internal/tui/mergeview/model.go:292

• A polling transport/API error does not mean the server-side merge failed—the request may still complete—but this marks it failed and the command reports merge failed. That can make users retry an in-flight atomic merge or believe nothing landed. Preserve an unknown/watch-stopped outcome and report that only status polling stopped.

func (m Model) handlePollDone(msg pollDoneMsg) (tea.Model, tea.Cmd) {
	if msg.err != nil {
		m.err = msg.err
		m.failed = true
		m.message = msg.err.Error()
		return m.finish()

• Files reviewed: 18/18 changed files
• Comments generated: 13
• Review effort level: Medium