Create/update stack on remote during sync

[skarim]

Make gh stack sync reconcile the stack object on GitHub when the branches already have open PRs, and report an accurate final status.

gh stack sync could finish with ✓ Stack synced even though it never created a stack on GitHub. After adopting existing branches with gh stack init, opening PRs outside the CLI, and then running gh stack sync:

Syncing PRs ...
✓ PR #124 (branch2) — Open
✓ PR #123 (branch1) — Open

✓ Stack synced        ← but no stack was ever created on GitHub

Two separate bugs addressed:

1. Sync never reconciled the remote stack object. runSync only refreshed local PR associations (syncStackPRs); it never created or updated the stack on GitHub. The branches were rebased and pushed and the PRs were detected, but the stack object never existed on the server.

2. The final message was unconditional. Stack synced was printed regardless. That message should mean "the stack object on GitHub now reflects the local stack" — which can only be true when two or more open PRs exist and the remote stack was actually created or updated.

This reuses the create/adopt/update logic that already powers submit (added in #83298f1, "Adopt an existing remote stack on submit"), now handling the case where the remote stack doesn't exist yet.

Behavior

After syncing PR state, sync reconciles the stack on GitHub:

1. Links existing PRs into a stack when the stack has two or more open PRs — creating the stack if none exists, adopting an untracked one, or updating a partially-formed one. Sync never opens PRs; that is still gh stack submit's job.
2. Reports what actually happened. The closing message is Stack synced only when the remote stack object reflects the local stack, and Branches synced otherwise — fewer than two PRs, stacked PRs unavailable, a cross-stack divergence, or no GitHub client.

Changes

cmd/sync.go:

• After the PR-state step, reconcile the remote stack by calling the shared syncStack helper (when a GitHub client is available) and record whether the stack object was synced.
• Replace the unconditional Stack synced with Stack synced / Branches synced, driven by that result.
• Document the stack-object step and the two closing messages in the command's long help.

cmd/submit.go:

• syncStack (and updateStack / createNewStack / handleCreate422) now return a synced bool so sync can tell whether the remote stack object reflects local. adoptRemoteStack becomes reconcileUntrackedStack, which folds in the create path and returns a single bool. Submit's call site ignores the return, so submit's behavior is unchanged.
• Make the divergence / dropped-PR guidance command-neutral ("reconcile them first", and drop the trailing gh stack submit), since it is now reachable from sync as well as submit.

cmd/sync_test.go — six new tests:

• TestSync_CreatesRemoteStackWhenPRsExist: open PRs, no remote stack → CreateStack is called once and the new ID is persisted; output has "Stack created on GitHub" and "Stack synced".
• TestSync_AdoptsExistingEqualRemoteStack: a matching remote stack → adopted, no create/update, "Stack synced".
• TestSync_UpdatesPartialRemoteStack: a subset stack → UpdateStack with the full PR list, "Stack synced".
• TestSync_FewerThanTwoPRs_BranchesSynced: one PR → no stack API calls, "Branches synced".
• TestSync_StacksUnavailable_BranchesSynced: 404 on create → warns, "Branches synced".
• TestSync_PRsSpanMultipleStacks_BranchesSynced: PRs across two stacks → divergence warning, no create/update, "Branches synced".

Docs — document the stack-object step and the Stack synced vs Branches synced distinction:

• README.md
• docs/src/content/docs/reference/cli.md
• skills/gh-stack/SKILL.md
• docs/src/content/docs/introduction/overview.md
• docs/src/content/docs/guides/stacked-prs.md
• docs/src/content/docs/guides/workflows.md

---

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

[Copilot]

Pull request overview

This PR fixes gh stack sync so that it actually reconciles the stack object on GitHub, rather than only refreshing local PR metadata and unconditionally reporting ✓ Stack synced. After syncing PR state, sync now links the open PRs into a remote stack (creating, adopting, or updating it) whenever two or more PRs exist, and reports Stack synced only when the remote stack object truly reflects the local stack — otherwise Branches synced. It reuses the already-tested stack helpers from submit by threading a synced bool return through them, and never opens PRs (still submit's job).

Changes:

• Add syncRemoteStack to cmd/sync.go (short-circuits when the remote already matches, else delegates to the shared syncStack) and make the closing message conditional on whether the remote stack was reconciled.
• Thread a synced bool return through syncStack/createNewStack/updateStack/handleCreate422 and (handled, synced) through adoptRemoteStack; extract the shared stackPRNumbers helper. Submit's call site ignores the new return, so submit behavior is unchanged.
• Add six sync tests covering create/adopt/update/fewer-than-two-PRs/unavailable/divergence, and update README, CLI reference, overview, guides, and SKILL docs.

Show a summary per file

File	Description
cmd/sync.go	Adds syncRemoteStack reconciliation step and Stack synced/Branches synced conditional message; new imports strconv/github.
cmd/submit.go	Extracts stackPRNumbers; threads bool/(handled, synced) returns through the stack helpers (additive, submit behavior preserved).
cmd/sync_test.go	Six new tests plus newSyncMockNoRebase/openPRFinder/runSyncWithGitHub helpers for remote stack reconciliation.
README.md	Documents the new "Sync the stack" step and renumbers prune.
docs/src/content/docs/reference/cli.md	Mirrors the CLI reference flow change.
docs/src/content/docs/introduction/overview.md	Notes sync now links open PRs into a Stack.
docs/src/content/docs/guides/workflows.md	Adds stack-linking as step 6.
docs/src/content/docs/guides/stacked-prs.md	Adds "link open PRs into a Stack on GitHub" to the sync summary.
skills/gh-stack/SKILL.md	Documents the sync stack-object step, new output lines, and Stack synced vs Branches synced.

Review details

• Files reviewed: 9/9 changed files
• Comments generated: 2
• Review effort level: Medium

[Lukeghenco]

is bool like this an expected pattern in Go for the mutative actions? I guess I assumed it should return a tuple response that I see elsewhere in Go.

func updateStack(cfg *config.Config, client github.ClientOps, s *stack.Stack, prNumbers []int) (someVal: SomeObj, err error)
_, err := updateStack(args*)

[skarim]

The tuple pattern is good when we need to bubble up an error message. In the case of updateStack, it doesn't make sense to do that vs. just printing the messages directly inside the func (none of which is an error/blocking). So the bool is just easier so we know if we're working with a stack and can proceed accordingly.

[Lukeghenco]

Code seems solid. A general Go coding style question, but nothing blocking here.