fix: sort candidates by trunk distance and document --no-detect flags

- Sort `autoDetectAndAdopt` candidates by merge-base distance from trunk
  (ascending) so parents are processed before children in untracked
  chains, preventing mis-adoption when a child branch alphabetically
  sorts before its untracked parent
- Document `--no-detect` flag in README for `restack` and `sync`
  commands (was already implemented but undocumented)

Author: boneskull

README.md

@@ -302,11 +302,12 @@ If a rebase conflict occurs, resolve it and run `gh stack continue`.
 
 #### restack Flags
 
-| Flag          | Description                                              |
-| ------------- | -------------------------------------------------------- |
-| `--only`      | Only restack current branch, not descendants             |
-| `--dry-run`   | Show what would be done                                  |
-| `--worktrees` | Rebase branches checked out in linked worktrees in-place |
+| Flag            | Description                                              |
+| --------------- | -------------------------------------------------------- |
+| `--only`        | Only restack current branch, not descendants             |
+| `--dry-run`     | Show what would be done                                  |
+| `--worktrees`   | Rebase branches checked out in linked worktrees in-place |
+| `--no-detect`   | Skip auto-detection and adoption of untracked branches   |
 
 ### continue
 
@@ -333,6 +334,7 @@ This is the command to run when upstream changes have occurred (e.g., a PR in yo
 | `--no-restack` | Skip restacking branches                                 |
 | `--dry-run`    | Show what would be done                                  |
 | `--worktrees`  | Rebase branches checked out in linked worktrees in-place |
+| `--no-detect`  | Skip auto-detection and adoption of untracked branches   |
 
 ### undo
 

cmd/detect_helpers.go

@@ -1,7 +1,9 @@
 package cmd
 
 import (
+	"cmp"
 	"fmt"
+	"slices"
 
 	"github.com/boneskull/gh-stack/internal/config"
 	"github.com/boneskull/gh-stack/internal/detect"
@@ -33,6 +35,12 @@ func autoDetectAndAdopt(cfg *config.Config, g *git.Git, gh *github.Client, s *st
 		return nil
 	}
 
+	// Sort candidates by merge-base distance from trunk (ascending) so that
+	// branches closer to trunk (parents) are processed before their children.
+	// Without this, alphabetical ordering can cause a child to be adopted with
+	// the wrong parent when both it and its true parent are untracked.
+	sortCandidatesByTrunkDistance(candidates, trunk, g)
+
 	// Loop until no progress: untracked chains (e.g., C based on untracked B)
 	// may require multiple passes since a branch can only be detected once its
 	// parent has been adopted into the tracked set.
@@ -127,6 +135,34 @@ func autoDetectAndAdopt(cfg *config.Config, g *git.Git, gh *github.Client, s *st
 	return nil
 }
 
+// sortCandidatesByTrunkDistance sorts branches by their merge-base distance
+// from trunk (ascending). Branches closer to trunk are processed first, which
+// ensures parents are adopted before their children in untracked chains.
+// Branches whose distance can't be computed are sorted to the end.
+func sortCandidatesByTrunkDistance(candidates []string, trunk string, g *git.Git) {
+	const maxDist = 1<<31 - 1
+	dist := make(map[string]int, len(candidates))
+	for _, b := range candidates {
+		mb, err := g.GetMergeBase(b, trunk)
+		if err != nil {
+			dist[b] = maxDist
+			continue
+		}
+		n, err := g.RevListCount(mb, b)
+		if err != nil {
+			dist[b] = maxDist
+			continue
+		}
+		dist[b] = n
+	}
+	slices.SortFunc(candidates, func(a, b string) int {
+		if d := cmp.Compare(dist[a], dist[b]); d != 0 {
+			return d
+		}
+		return cmp.Compare(a, b)
+	})
+}
+
 // wouldCycle returns true if setting branch's parent to parent would create a
 // cycle in the config-based parent chain. It walks cfg.GetParent from parent
 // upward; if it ever reaches branch, adopting would create a loop.