[skarim]

Updates the "unstack on GitHub and keep local" choices in gh stack sync and gh stack checkout to handle merged PRs remaining in the old remote stack. Both paths preserve the local branch layout and only detach the remote association when recreation is safe.

Functionality and user impact

• Use the same unstack-and-keep-local handling in both commands. Accept merged-only remnants and report retained history rather than claiming the remote stack was deleted.
• Keep the local association when unmerged PRs still prevent recreation or the API fails. A failed stack lookup no longer masquerades as an already-deleted stack.
• Preserve local branches and stack order. Sync stops before pushing or recreating anything and directs users to submit; prompts now describe unstacking rather than guaranteed deletion.

Key areas to review

• cmd/utils.go:2160-2188: unstackAndKeepLocal centralizes the outcome handling. Check the merged-only versus blocked-remnant distinction, the 404/API-error paths, and that remote ID/number clearing and the catalog save happen only after a safe outcome.
• cmd/utils.go:2141-2158: resolveDivergenceDeleteRemote distinguishes lookup failure from a missing stack and delegates to the shared helper. It keeps sync stopped and only offers recreation guidance after the local association is safely cleared.
• cmd/checkout.go:627-631: handleCompositionConflict uses the same helper for its keep-local choice, returning the existing local stack rather than importing or replacing its branches.

Related issues

• https://github.com/github/pull-requests/issues/26707

---

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

[Copilot]

🟢 Approval recommended

Static review identified no blocking issues in the shared handling, command integration, or regression coverage; tests were not executed.

No open issues 🎉

What changed in this PR

Updates sync and checkout to handle partial unstacking safely while preserving local branch layout.

Changes:

• Shares keep-local handling across both commands, accepting merged-only remnants and retaining associations on blocked outcomes.
• Adds regression coverage for successful, partial, and failed unstacking.
• Updates prompts and documentation to avoid promising remote stack deletion.

File	Description
README.md	Explains partial unstacking and recreation.
docs/​src/​content/​docs/​reference/​cli.md	Updates sync conflict-resolution guidance.
docs/​src/​content/​docs/​guides/​workflows.md	Documents keep-local behavior.
cmd/​utils.go	Centralizes safe unstacking and lookup-error handling.
cmd/​sync_test.go	Covers sync outcomes and verifies no pushing or recreation.
cmd/​checkout.go	Uses shared handling and injectable selection.
cmd/​checkout_test.go	Covers checkout outcomes and local-stack preservation.

_{Review effort: Balanced}