fix(sc-gh-stack): unblock adopted-layer reconcile, bound rebases at fork points

Iteration-3 review pass (1 blocker, 2 majors, 8 minors):

- convert: adopted-layer freshness also accepts a local tip that already
  contains every remote commit, so the documented reconcile recipe, re-runs
  after gh stack submit pushed the branches, and ff-then-rebase sequences all
  pass while post-adoption remote pushes are still refused (was an
  unrecoverable GIT.BRANCH_DIVERGED loop / false positive)
- convert: when a layer descends from neither the below layer's recorded tip
  nor its current tip (cut from an older tip of the layer below), the rebase
  upstream falls back to the merge-base fork point instead of trunk, so the
  below layer's conflict-resolved commits are never re-replayed as spurious
  conflicts or duplicates
- convert: failed fast-forwards report CONVERT.FF_FAILED with git stderr
  (worktree-checkout cause visible) instead of CONVERT.REBASE_FAILED
- tests: 49 cases — new mutation-verified coverage for adopted-layer divergence
  + reconcile, post-submit idempotent re-run, fork-point bounding, and
  rerere-staged zero-unmerged conflicts
- docs: empty conflict.files guidance (rerere), CONVERT.FF_FAILED, sanctioned
  scope of the keep-local troubleshooting path, submit-recovery conflict loop,
  STACK.INIT_FAILED split onto the failure path, test counts

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: randlee

packages/sc-gh-stack/CHANGELOG.md

@@ -17,9 +17,11 @@ Initial package (skill-only, no agents).
   a different conversion starts, so dependent branches never replay a lower
   layer's commits and stale bookkeeping never leaks between conversions);
   stdlib-only, fenced JSON envelopes
-- `tests/`: 45 pytest cases — mocked unit tests plus real-git integration tests
-  (conflict → resume, abort → re-run, dependent layers, trunk-merge
-  linearisation, stale and diverged remotes, stale-bookkeeping clearing)
+- `tests/`: 49 pytest cases — mocked unit tests plus real-git integration tests
+  (conflict → resume, abort → re-run, dependent layers, fork-point bounds,
+  trunk-merge linearisation, stale and diverged remotes, adopted-layer
+  divergence and reconcile, post-submit idempotency, rerere-staged conflict
+  resumability, stale-bookkeeping clearing)
 - upstream `github/gh-stack` references (`commands.md`, `troubleshooting.md`,
   `stack-design.md`) carried verbatim for on-demand loading
 - `references/installation-and-troubleshooting.md` per guidelines v0.7

packages/sc-gh-stack/README.md

@@ -48,8 +48,9 @@ Stdlib-only Python 3; every run emits one fenced JSON envelope (`success`/`data`
 python3 -m pytest packages/sc-gh-stack/tests
 ```
 
-Unit tests mock `git`/`gh`; one integration test drives real `git` in a temp repo
-(conflict → resume → linear chain) with a stubbed `gh` on PATH.
+Unit tests mock `git`/`gh`; the integration tests drive real `git` in temp repos
+(conflict → resume, abort → re-run, dependent layers, divergence guards) with a
+stubbed `gh` on PATH.
 
 ## Why stacks
 

packages/sc-gh-stack/scripts/gh_stack_convert.py

@@ -103,10 +103,11 @@ def _has_merges(upstream: str, layer_ref: str, cwd: Optional[Path] = None) -> bo
     return gs.git_out(["rev-list", "--merges", f"{upstream}..{layer_ref}"], cwd=cwd) != ""
 
 
-def _fast_forward(branch: str, target: str, cwd: Optional[Path] = None) -> bool:
+def _fast_forward(branch: str, target: str, cwd: Optional[Path] = None):
+    """Returns the CompletedProcess of the attempted update (caller checks rc/stderr)."""
     if gs.git_out(["rev-parse", "--abbrev-ref", "HEAD"], cwd=cwd) == branch:
-        return gs.git(["merge", "--ff-only", target], cwd=cwd).returncode == 0
-    return gs.git(["branch", "-f", branch, target], cwd=cwd).returncode == 0
+        return gs.git(["merge", "--ff-only", target], cwd=cwd)
+    return gs.git(["branch", "-f", branch, target], cwd=cwd)
 
 
 def begin_conversion(trunk: str, layers: List[str], cwd: Optional[Path] = None) -> None:
@@ -140,16 +141,22 @@ def _check_remote_freshness(layer: str, remote: str, cwd: Optional[Path]) -> Opt
     orig = _orig_tip(layer, cwd=cwd)
     adopted = orig is not None and orig != _rev(_head(layer), cwd=cwd)
     if adopted:
-        if gs.is_ancestor(remote_ref, orig, cwd=cwd):
+        # Safe when the remote gained nothing since adoption (ancestor of the
+        # recorded tip) OR the local tip already contains every remote commit —
+        # the post-submit state, and the state after the documented reconcile
+        # (`git rebase <remote>/<layer>`), both of which must pass.
+        if gs.is_ancestor(remote_ref, orig, cwd=cwd) \
+                or gs.is_ancestor(remote_ref, _head(layer), cwd=cwd):
             return None
     elif gs.is_ancestor(remote_ref, _head(layer), cwd=cwd):
         return None
     elif gs.is_ancestor(_head(layer), remote_ref, cwd=cwd):
-        if _fast_forward(layer, remote_ref, cwd=cwd):
+        ff = _fast_forward(layer, remote_ref, cwd=cwd)
+        if ff.returncode == 0:
             return None
-        return {"code": "CONVERT.REBASE_FAILED", "exit": EXIT_ERR, "layer": layer,
-                "message": f"could not fast-forward {layer} to {remote_ref}",
-                "action": "inspect the branch state and re-run"}
+        return {"code": "CONVERT.FF_FAILED", "exit": EXIT_ERR, "layer": layer,
+                "message": f"could not fast-forward {layer} to {remote_ref}: {ff.stderr.strip()}",
+                "action": "inspect the branch state (is it checked out in another worktree?) and re-run"}
     return {"code": "GIT.BRANCH_DIVERGED", "exit": EXIT_INPUT, "layer": layer,
             "message": f"{layer} and {remote_ref} have diverged; converting the "
                        f"local branch would drop the remote's commits on submit",
@@ -193,6 +200,14 @@ def chain(layers: List[str], trunk_ref: str, remote: str, cwd: Optional[Path] =
                 upstream = orig_below
             elif gs.is_ancestor(below, layer_ref, cwd=cwd):
                 upstream = below
+            else:
+                # Layer cut from an OLDER tip of the layer below: bound the
+                # rebase at the fork point so the below layer's shared commits
+                # are never re-replayed. Degenerates to the trunk fork point
+                # (same replay set as trunk_ref) for layers cut from trunk.
+                fork = gs.git_out(["merge-base", orig_below or below, layer_ref], cwd=cwd)
+                if fork:
+                    upstream = fork
         if _orig_tip(layer, cwd=cwd) is None:
             gs.git(["update-ref", _orig_ref(layer), layer_ref], cwd=cwd)
 

packages/sc-gh-stack/skills/managing-gh-stacks/references/playbook-convert.md

@@ -39,9 +39,10 @@ merge commits — verify no conflict-resolution content from an "evil merge" was
 continuing). It stops at the **first** conflict. Every run emits one fenced JSON envelope;
 read `success`, `error.code`, and `data`. The sample payloads below show the fields to act
 on; `data` also always carries `trunk`, `remote`, and `layers`. Exit 1 with
-`CONVERT.REBASE_FAILED` means a rebase or fast-forward failed without leaving a resumable
-rebase — read `error.message`, fix that (never re-chain by hand), and re-run; finished layers
-are skipped.
+`CONVERT.REBASE_FAILED` (a rebase failed without leaving a resumable rebase) or
+`CONVERT.FF_FAILED` (a fast-forward failed — often the branch is checked out in another
+worktree) — read `error.message`, fix that (never re-chain by hand), and re-run; finished
+layers are skipped.
 
 ### On exit 3 — `error.code: "CONVERT.CONFLICT"`
 
@@ -65,7 +66,9 @@ git rebase --continue
 python3 .claude/scripts/gh_stack_convert.py main 101 102 103 104   # re-run: finished layers report "skip"
 ```
 
-Every conflict is attributed to a specific layer. If `git rebase --continue` conflicts again
+Every conflict is attributed to a specific layer. If `conflict.files` is empty, rerere has
+already staged every resolution — run `git rebase --continue` directly, then re-run the
+script. If `git rebase --continue` conflicts again
 (a layer with several conflicting commits), repeat resolve + `git add` + `--continue` until
 the rebase itself finishes; only then re-run the script — run mid-rebase it refuses with
 `GIT.REBASE_IN_PROGRESS`. Loop until `success: true`. rerere records each resolution, so the
@@ -75,9 +78,13 @@ same conflict never needs a second manual resolution when the stack is rebased a
 
 `data.stack_init.action` is `"initialised"` (or `"existing_stack_kept"` if a local stack was
 already present — if the reported branches differ from your list, run `gh stack unstack --local`
-and re-run the script). On exit 1 with `error.code: "STACK.INIT_FAILED"`, read
-`data.stack_init.stderr`, fix the reported problem, and re-run — chained layers are skipped.
-Nothing has been pushed yet. Now inspect the stack:
+and re-run the script).
+
+On exit 1 with `error.code: "STACK.INIT_FAILED"`, read `data.stack_init.stderr`, fix the
+reported problem, and re-run — chained layers are skipped; do not run `view` or `submit`
+until the re-run succeeds.
+
+On success: nothing has been pushed yet. Now inspect the stack:
 
 ```bash
 gh stack view --json
@@ -117,8 +124,15 @@ gh stack rebase --upstack               # propagate through the layers above
 gh stack submit --auto
 ```
 
+If that `git rebase <remote>/<rejected-layer>` itself conflicts, resolve + `git add` +
+`git rebase --continue` exactly as in the conversion loop (rerere replays earlier
+resolutions); never `--abort` into a force-push. Duplicated lower-layer commits are dropped
+by the following `gh stack rebase --upstack`.
+
 Never resolve a rejected push with `git push --force`, and never pick "keep the local
-version" from a divergence prompt — the remote-only commits are someone's work.
+version" when branch **content** has diverged (a rejected push) — the remote-only commits
+are someone's work. The keep-local path in `troubleshooting.md` applies only to
+stack-**grouping** divergence, where no commits differ.
 Exit **9** means stacked PRs are not enabled on the repository — stop and tell the user,
 reporting which layers (if any) were already pushed per the submit output; the local branches
 remain chained and the stack tracked — do not attempt to undo that without the user.

packages/sc-gh-stack/tests/test_convert.py

@@ -115,6 +115,33 @@ def fake_git(args, cwd=None):
         assert env["data"]["failure"]["layer"] == "a"
         assert "boom" in env["data"]["failure"]["message"]
 
+    def test_rerere_staged_conflict_still_resumable(self, monkeypatch):
+        """rebase stops nonzero, rebase-in-progress, but rerere.autoUpdate staged
+        every resolution (zero unmerged paths): must classify as a resumable
+        conflict, never CONVERT.REBASE_FAILED."""
+        state = {"rebasing": False}
+
+        def fake_git(args, cwd=None):
+            if args[0] == "rebase":
+                state["rebasing"] = True
+                return cp(1, "", "stopped; resolutions staged by rerere")
+            return cp(0)
+
+        monkeypatch.setattr(gs, "rebase_in_progress", lambda cwd=None: state["rebasing"])
+        monkeypatch.setattr(gs, "working_tree_clean", lambda cwd=None: True)
+        monkeypatch.setattr(gs, "remotes", lambda cwd=None: ["origin"])
+        monkeypatch.setattr(gs, "git", fake_git)
+        monkeypatch.setattr(gs, "git_out", lambda args, cwd=None: "")
+        monkeypatch.setattr(gs, "local_branch_exists", lambda b, cwd=None: True)
+        monkeypatch.setattr(gs, "remote_branch_exists",
+                            lambda remote, branch, cwd=None: branch == "main")
+        monkeypatch.setattr(gs, "is_ancestor", lambda a, b, cwd=None: False)
+        monkeypatch.setattr(gs, "conflicted_files", lambda cwd=None: [])
+        code, env = cv.convert("main", ["a", "b"])
+        assert code == cv.EXIT_CONFLICT
+        assert env["error"]["code"] == "CONVERT.CONFLICT"
+        assert env["data"]["conflict"] == {"layer": "a", "onto": "origin/main", "files": []}
+
     def test_init_stack_keeps_existing_stack(self):
         with patch.object(gs, "git", return_value=cp(0)), patch.object(gs, "gh", return_value=cp(0, "{}")):
             assert cv.init_stack("main", ["a", "b"])["action"] == "existing_stack_kept"
@@ -362,6 +389,72 @@ def test_abort_then_rerun_converges(self, repo):
         code, env = cv.convert("main", ["pr1", "pr2", "pr3"], cwd=repo)
         assert code == cv.EXIT_OK, env
 
+    def test_adopted_layer_remote_advance_refused(self, repo):
+        """After a layer was rebased by this conversion, a commit someone pushes
+        to its remote must still be detected (via the recorded pre-rebase tip),
+        even though plain ancestry against the rewritten branch means nothing."""
+        old_tip = _sh(repo, "git", "rev-parse", "pr3").strip()
+        code, env = cv.convert("main", ["pr1", "pr3"], cwd=repo)
+        assert code == cv.EXIT_OK, env
+        # Collaborator pushes to origin/pr3, building on the pre-conversion tip.
+        _sh(repo, "git", "checkout", "-qb", "collab", old_tip)
+        _commit(repo, "collab.txt", "c\n", "collab work")
+        _sh(repo, "git", "push", "-q", "origin", "collab:pr3")
+        _sh(repo, "git", "checkout", "-q", "main")
+        code, env = cv.convert("main", ["pr1", "pr3"], cwd=repo)
+        assert code == cv.EXIT_INPUT
+        assert env["error"]["code"] == "GIT.BRANCH_DIVERGED"
+        assert "pr3" in env["error"]["message"]
+
+        # The error's own reconcile recipe must clear the guard on re-run.
+        _sh(repo, "git", "checkout", "-q", "pr3")
+        _sh(repo, "git", "rebase", "-q", "origin/pr3")
+        _sh(repo, "git", "checkout", "-q", "main")
+        code, env = cv.convert("main", ["pr1", "pr3"], cwd=repo)
+        assert code == cv.EXIT_OK, env
+        assert "collab work" in _sh(repo, "git", "log", "--format=%s", "origin/main..pr3")
+
+    def test_rerun_after_submit_push_is_idempotent(self, repo):
+        code, env = cv.convert("main", ["pr1", "pr3"], cwd=repo)
+        assert code == cv.EXIT_OK, env
+        # Simulate `gh stack submit` pushing the rebased branches.
+        _sh(repo, "git", "push", "-q", "-f", "origin", "pr1", "pr3")
+        code, env = cv.convert("main", ["pr1", "pr3"], cwd=repo)
+        assert code == cv.EXIT_OK, env
+        assert all(c["action"] == "skip" for c in env["data"]["chained"])
+
+    def test_layer_cut_from_older_tip_of_below_not_duplicated(self, repo):
+        # dep is branched from pr1's current tip (contains the shared.txt
+        # commit), then pr1 gains one MORE commit — the everyday "lower layer
+        # kept moving after the upper layer was cut" shape.
+        _sh(repo, "git", "checkout", "-qb", "dep", "pr1")
+        _commit(repo, "dep.txt", "dep\n", "dep work")
+        _sh(repo, "git", "push", "-q", "origin", "dep")
+        _sh(repo, "git", "checkout", "-q", "pr1")
+        _commit(repo, "l1b.txt", "more\n", "pr1 more work")
+        _sh(repo, "git", "push", "-q", "-f", "origin", "pr1")
+        # Trunk moves, conflicting with pr1's shared-file edit.
+        _sh(repo, "git", "checkout", "-q", "main")
+        _commit(repo, "shared.txt", "trunk\n", "trunk shared")
+        _sh(repo, "git", "push", "-q", "origin", "main")
+
+        code, env = cv.convert("main", ["pr1", "dep"], cwd=repo)
+        assert code == cv.EXIT_CONFLICT
+        assert env["data"]["conflict"]["layer"] == "pr1"
+        (repo / "shared.txt").write_text("resolved\n")
+        _sh(repo, "git", "add", "shared.txt")
+        _sh(repo, "git", "rebase", "--continue")
+
+        # Re-run: dep descends from NEITHER pr1's recorded pre-rebase tip
+        # (which includes the later commit) NOR its current tip, so the
+        # upstream bound must fall back to the fork point. Only dep's own
+        # commit replays — pr1's conflict-resolved shared commit (whose patch
+        # changed) is never re-replayed, so no spurious conflict, no duplicate.
+        code, env = cv.convert("main", ["pr1", "dep"], cwd=repo)
+        assert code == cv.EXIT_OK, env
+        assert _sh(repo, "git", "rev-list", "--count", "pr1..dep").strip() == "1"
+        assert (repo / "shared.txt").read_text() == "resolved\n"
+
     def test_new_conversion_clears_stale_orig_refs(self, repo):
         code, env = cv.convert("main", ["pr1", "pr3"], cwd=repo)
         assert code == cv.EXIT_OK, env