Sync remote stack with local stack state

[skarim]

Mirrors the remote stack locally during sync

gh stack sync already reconciled the stack object on GitHub by pushing up your local stack (#156), but it never brought remote-ahead changes back down. If you push a stack and someone else adds more PRs to it on GitHub, a local sync left your local stack behind with the new PRs on remote silently ignored.

This makes sync mirror the remote stack locally: it pulls down branches for PRs added to the stack on GitHub, and prompts you to resolve the situation when the local and remote stacks have diverged.

Behavior

After fetching, sync reconciles the local stack against the remote stack:

• Remote-ahead (clean). When PRs have been appended to the stack on GitHub, their branches are fetched and appended to your local stack automatically — no prompt, so sync stays safe to run in automation.

• Diverged. When the two have genuinely diverged (for example, you added a branch locally while different PRs were added on GitHub), an interactive prompt offers three choices:

  • Use the remote stack as the source of truth — replace the local stack with the remote's, moving you off a dropped branch to the nearest surviving one (requires a clean working tree).
  • Delete the stack on GitHub — remove the remote stack and recreate it yourself with submit.
  • Cancel — abort without changes.

  In a non-interactive terminal, a divergence aborts the sync without touching anything.

• Submit "STACK N PRs". To support the "delete the stack on GitHub" path, the submit TUI now offers a (^b) STACK N PRs action (Ctrl+B) that links existing open PRs into a stack — shown when there's no remote stack yet, no new PRs are selected, and there are at least two open PRs.

Classification is based on the non-merged branch order, so merged/pruned branches don't cause false divergences.

Changes

• cmd/sync.go, cmd/utils.go — new early reconcile phase (reconcileRemoteStack): classifies the local↔remote relationship (in-sync / remote-ahead / local-ahead / divergent), pulls remote additions, and drives the three-option divergence resolution. Cancelled and non-interactive divergences abort the sync cleanly.
• cmd/checkout.go — factor out ensureLocalBranchFromRemote, shared with the new pull path.
• internal/stack/stack.go, internal/modify/apply.go — extract a shared NearestSurvivingBranch helper, now used by both sync's "use remote" branch-switch and modify's post-op checkout selection (removes duplicated logic).
• internal/tui/submitview/*, cmd/submit.go — the (^b) STACK N PRs button + Ctrl+B shortcut.
• Docs — README.md, docs/src/content/docs/reference/cli.md, guides/workflows.md, introduction/overview.md, guides/stacked-prs.md, and skills/gh-stack/SKILL.md.

The change is split into six focused commits (pull remote updates → cancel aborts → switch to nearest surviving branch + shared helper → simplify to the delete-remote option → submit STACK button → docs) for easier review.

Testing

• New tests: cmd/sync_test.go (classification, clean pull, each divergence choice, switch-off-dropped-branch, uncommitted-changes guard, non-interactive abort, and merged-branch no-false-divergence), internal/stack/stack_test.go (NearestSurvivingBranch), and internal/tui/submitview/stackbutton_test.go (button eligibility, rendering, Ctrl+B, and mouse click).
• go test -race -count=1 ./..., go vet ./..., and gofmt are all clean.

---

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

[Copilot]

Pull request overview

Adds bidirectional stack reconciliation to gh stack sync, pulling remote additions locally and resolving divergence.

Changes:

• Reconciles remote-ahead and divergent stacks.
• Adds shared branch-import and nearest-survivor helpers.
• Adds the submit TUI’s Ctrl+B stack action and documentation.

Show a summary per file

File	Description
cmd/sync.go	Runs early remote reconciliation.
cmd/sync_test.go	Tests reconciliation scenarios.
cmd/utils.go	Implements reconciliation and divergence handling.
cmd/checkout.go	Shares remote branch creation logic.
cmd/submit.go	Enables the TUI stack action.
cmd/submit_tui_test.go	Updates TUI helper invocation.
internal/stack/stack.go	Adds nearest-surviving-branch selection.
internal/stack/stack_test.go	Tests survivor selection.
internal/modify/apply.go	Reuses survivor selection.
internal/tui/submitview/model.go	Tracks stack-action eligibility.
internal/tui/submitview/data.go	Counts open PRs.
internal/tui/submitview/screen.go	Renders and handles Ctrl+B.
internal/tui/submitview/render.go	Updates header shortcuts.
internal/tui/submitview/mouse.go	Adds stack-button click handling.
internal/tui/submitview/help.go	Documents Ctrl+B.
internal/tui/submitview/stackbutton_test.go	Tests stack-button behavior.
README.md	Documents synchronization behavior.
docs/src/content/docs/reference/cli.md	Updates CLI reference.
docs/src/content/docs/introduction/overview.md	Updates feature overview.
docs/src/content/docs/guides/workflows.md	Documents reconciliation workflows.
docs/src/content/docs/guides/stacked-prs.md	Updates sync summary.
skills/gh-stack/SKILL.md	Updates agent guidance.
docs/package-lock.json	Regenerates lockfile platform metadata.

Review details

Files not reviewed (1)

• docs/package-lock.json: Generated file

• Files reviewed: 22/23 changed files
• Comments generated: 10
• Review effort level: Medium