[skarim]

Fixes #512: prevent rebase and sync from replaying merged commits when local refs or recorded bases are stale.

Functionality and impact

• Cache merged PR heads separately from local refs, with backfill for existing stacks.
• Choose ancestry-validated cutoffs while preserving rollback snapshots and worktree recovery.

Key areas to review

• Cutoff selection and frozen recovery evidence in cmd/utils.go.
• PR-head persistence/backfill and distinguishing missing Git objects from lookup errors.
• Default GitHub mocking in test configs to keep backfill tests offline.

Testing and verification

• go vet ./...
• go run ./scripts/test -workers 4 (full race-enabled suite)
• go build -o gh-stack .
• Real-Git regressions cover stale heads/bases, pruning, ranges, and cross-worktree recovery.

[Copilot]

🔵 Needs a closer look

Core history-rewrite and recovery changes have unresolved correctness concerns and need maintainer validation.

2 open issues

• Preserve named trunk ref during legacy rebase continuation · New
• Prefer recorded base after regular merge · New

What changed in this PR

This PR addresses #512 by separating GitHub’s merged PR heads from local refs, improving how gh-stack chooses rebase and sync boundaries when local state is stale.

Changes:

• Persist merged PR heads and backfill metadata for existing stacks.
• Validate rebase cutoffs while preserving rollback snapshots and recovery evidence.
• Add regression coverage, offline test defaults, and user documentation.

File	Description
internal/​stack/​stack.go	Stores merged PR heads separately.
internal/​stack/​stack_test.go	Tests persistence and legacy compatibility.
internal/​stack/​schema.json	Adds the merged-head schema field.
internal/​github/​github.go	Retrieves PR head commit IDs.
internal/​github/​github_test.go	Tests PR-head queries and decoding.
internal/​git/​mock_ops.go	Adds commit-availability mocking.
internal/​git/​gitops.go	Checks commits and handles unavailable fork points.
internal/​git/​gitops_test.go	Tests boundary lookups and worktree failures.
internal/​git/​git.go	Exposes commit checks and documents fork-point behavior.
internal/​config/​testing.go	Stubs GitHub clients by default.
docs/​src/​content/​docs/​reference/​cli.md	Explains cutoff validation and manual recovery.
cmd/​utils.go	Backfills PR heads and selects validated cutoffs.
cmd/​utils_test.go	Tests metadata preservation and backfill.
cmd/​sync_test.go	Adds stale-state and worktree regressions.
cmd/​rebase.go	Enables boundary resolution without a local merged-parent ref.
cmd/​rebase_test.go	Adds cutoff, range, and recovery regressions.
cmd/​checkout.go	Preserves merged heads during import and refresh.
cmd/​checkout_test.go	Tests imported and refreshed PR-head metadata.

_{Review effort: Max}