[brettheap]

Lane: openreposhape-3 (openRepoShape-3)
Claim: #475 (comment)

What

templates/assembly-root/scripts/bootstrap.py, step (a). Before it refuses a tracking branch whose tip is not the pin, checkout_tracking_branch now runs git merge-base --is-ancestor <tip> <pin>. A branch that is behind goes to the new fast_forward_to_pin:

• HEAD detached at the pin, as bump-leg.py and git submodule update leave it: git branch -f <branch> <pin>, then git checkout <branch>. The leg ends on its tracking branch AT the new pin, and bootstrap prints branch main fast-forwarded <old> -> <new>, the pin.

• HEAD on the tracking branch, behind the pin: git -c merge.autostash=false merge --ff-only <pin>. The working tree moves with it. merge.autostash is off for this one merge (fix round, review finding 1 and codex's P1). With merge.autostash=true in a person's config, git stashed a local edit to a file the move changes, fast-forwarded, applied the stash back into conflicts and exited 0. Bootstrap then printed fast-forwarded over an unmerged leg holding an autostash entry. Now that edit is refused the same way it is without the setting. -c, not --no-autostash: a git before 2.27 rejects that as an unknown option, and has no autostash to turn off.

• Not checkout -B. Measured on git 2.43: git checkout -B main <pin> resets main even while another worktree of the leg has it checked out. That leaves the other worktree's files behind its own HEAD. git branch -f refuses in that case.

• Any other checkout stays where it is. A commit made on the detached leg after the bump is exactly the commit the issue says gets lost, and checking the branch out would leave it only in the reflog. A leg on another branch is somebody's work. Bootstrap prints ... and the checkout is at <sha> (detached), which is neither and says what to do.

• When git refuses a move (an untracked file or a changed tracked file in the way, or the branch held by another worktree), bootstrap prints git's own lines under ... and git refused to move it: and tries nothing else. The exit code stays 0, as for every step (a) line. Fix round, review finding 2: when branch -f worked and the checkout was refused (a stale index.lock), the line now says branch main moved <old> -> <new>, the pin, and git refused to check it out:. Blank lines in git's message are no longer printed as a line of spaces.

• A fresh clone whose leg's remote has moved past the pin (fix round, the coordinator extended this PR to the review's "out of scope" gap). git clone --recurse-submodules makes each leg's main at the remote's tip and leaves the leg detached at the pin. Bootstrap then met a main ahead of the pin and left the leg detached under not moving an existing branch. That is bump-leg.py, then make bootstrap, leaves the leg detached: bootstrap never fast-forwards a local tracking branch that is behind the new pin, though AGENTS.md, README and bump-leg.py say it re-places it #475's harm on the onboarding flow AGENTS.md section 3 describes. Bootstrap now moves the branch back to the pin, with branch -f then checkout, only when all three hold:

  • the branch has no commit of its own: its tip IS its upstream's remote-tracking ref (refs/remotes/origin/main), compared by object id;
  • the pin is an ancestor of it;
  • HEAD is detached AT the pin, so no file changes; a local edit stays.

  It prints one line: branch main moved back <tip> -> <pin>, the pin; nothing is lost, origin/main still holds those commits, and `git -C spec merge --ff-only origin/main` brings the branch forward. Second fix round, verification finding 5: the leg path and the upstream in that command are shell-quoted with shlex.quote, then spelled, as scripts/family.py quotes the commands it prints. An ordinary path prints as before; my spec prints as 'my spec'. The older NOT INITIALIZED line is a different line and is unchanged.

• Every checkout of an existing branch is judged by where HEAD is afterwards, not by git's exit code (second fix round, verification finding 1 = codex's P2, and finding 3). The new _check_out runs git checkout <branch> through _git_says, then reads _head_of.

  • A branch whose tip IS the pin used to be checked out with the result ignored, and on main at <pin> was printed anyway. With a stale index.lock the leg stayed detached; with a local edit in the way it stayed on another branch. That is on main too, and this PR opened a new way into it: a branch branch -f moved to the pin, whose checkout git refused, is at the pin on the next run. The new place_at_pin now prints branch main is at the pin <pin>, and git refused to check it out: with git's lines, and the leg stays where it is.
  • A branch that moved is never put back. Putting it back is a second ref write, which a stale lock refuses as well. The next run says again whether git can check it out.
  • A post-checkout hook that fails after HEAD moved makes git exit non-zero, because the hook's exit status is the checkout's own. That is not a refusal. The move's line is printed, and git's words follow it under checked out, and then git said:.

• Every other branch holding a commit the pin lacks is never moved. Its two lines, PIN ... != branch ... tip ... and not moving an existing branch. ..., are byte-identical to main's. That covers: ahead with a commit of its own, diverged, no upstream, an upstream that is a local branch, an upstream whose remote-tracking ref is missing, HEAD on the branch, and a main that does not contain the pin.

• Every new line spells the branch names, the upstream, the leg path and git's lines with spelled, as templates/assembly-root/scripts/bootstrap.py and templates/family-root/scripts/bootstrap.py: main prints the manifest's name with a plain print before any step runs, so name: "a\ud83db" (a lone surrogate) ends make bootstrap in a UnicodeEncodeError traceback, exit 1 (make: 2), and the validator that names the problem is never reached; a valid name the stdout cannot encode ends the same way #391 (landed in Both roots' scripts/bootstrap.py: main escapes what stdout cannot encode and spells each value it prints, so name: "a\ud83db" or 日本 under PYTHONIOENCODING=ascii no longer ends make bootstrap in a traceback (#391) #456) requires for every value bootstrap prints.

• Unchanged: a leg with no local branch (created at the pin), a branch whose tip is the pin and which git checks out, the pin itself, and steps (b) to (d).

• The digest moves. scripts/bootstrap.py is a pinned shape copy. Its sha256 moves from 3c18fa84… (main) to c5a45458… (head 757a440; e5d7a3a had de536646…, b247dec 03db7ca7…). update-shape.py check will report the file as upstream-changed in every project. No test pins that digest (no 64-hex string anywhere in tests/), so no test expectation moved.

• Families: nothing to change. templates/family-root/scripts/bootstrap.py has no branch logic. It runs git submodule update --init --recursive, then each member's own make bootstrap, which is this file in that member. So a member gets this fix once its own copy is updated.

The issue was right on every point. Re-measured, it holds on current main, and with --tracking-branch trunk too. The review found the same harm on a fresh clone, which this PR now covers as well.

Why

First round. Measured with a Python driver (no bash). It scaffolds Atlas into local bare remotes, clones recursively, bootstraps, pushes a new spec-leg commit, runs bump-leg.py from a bump/spec branch of the root, then bootstraps again. A refusing gh stub is first on PATH, with GH_TOKEN=bogus and an empty GH_CONFIG_DIR. Main was measured at 8782333, just before #456 landed; #456 changed only how step (a) spells its values, not what it moves. Head was e5d7a3a, on ec4a7a0.

In every case, bump-leg exits 0 and both bootstraps exit 0 on both sides. What differs is the [spec] line and where the leg ends:

case	main: [spec] line / where the leg ends	head: [spec] line / where the leg ends
behind, main (the issue)	PIN <new> != branch main tip <old> + not moving an existing branch. ... / DETACHED at <new>, main at <old>	branch main fast-forwarded <old> -> <new>, the pin / on main at <new>
behind, --tracking-branch trunk	the same, for trunk / DETACHED at <new>	branch trunk fast-forwarded <old> -> <new>, the pin / on trunk at <new>
behind, HEAD on main at the old pin	the same refusal / on main at <old> (the root records <new>)	branch main fast-forwarded ... / on main at <new>, worktree clean
ahead: a local commit on main, pin unchanged	PIN <pin> != branch main tip <local> + not moving ... / main at <local>	unchanged
diverged: a local commit on main, then bumped	PIN <new> != branch main tip <local> + not moving ... / main at <local>, leg detached at <new>	unchanged
a commit made on the detached leg after the bump	the refusal, which says The checkout stays at the pin / detached at <made>	branch main tip <old> is behind the PIN <new>, and the checkout is at <made> (detached), which is neither + not moving the checkout off it. ... / detached at <made>, main at <old>
HEAD on main, an untracked NEW-CONTRACT.md in the way	the refusal / main at <old>	... and git refused to move it:, git's four lines, then nothing else is tried; ... / main at <old>, the file kept

First fix round. Measured with the review's probe, extended: the same leg state is run through main 7a8b981's bootstrap.py, the first commit e5d7a3a's, and head b247dec's, with --skip-validators, under the same gh stub. Every run exits 0. The fresh-clone rows use a second scaffold whose spec remote's main is one commit (<tip>) past the pin.

case	main 7a8b981 / e5d7a3a	head b247dec
HEAD on main behind the pin, a local edit to README.md, which the pin also changes, with merge.autostash=true	main: the refusal, nothing moves. e5d7a3a: branch main fast-forwarded <old> -> <new>, the pin; ..., and the leg is left UU README.md, unmerged: README.md, stash@{0}: autostash	... and git refused to move it:, git's four lines (Your local changes ... would be overwritten by merge) / main at <old>, M README.md, no stash, nothing unmerged
the same, without merge.autostash	e5d7a3a: the refusal above	byte-identical to e5d7a3a
detached at the pin over main at <old>, a stale index.lock in the leg	e5d7a3a: branch main tip <old> is behind the PIN <new>, and git refused to move it:, git's lines with a line of ten spaces among them / main at <new>, detached	branch main moved <old> -> <new>, the pin, and git refused to check it out:, git's lines, no blank one / main at <new>, detached. Once the lock is gone, the next run checks main out; while it stays, the next run says so again (second fix round, below)
fresh clone, the leg's remote main past the pin	both: PIN <pin> != branch main tip <tip> + not moving an existing branch. ... / DETACHED at <pin>, main at <tip>	branch main moved back <tip> -> <pin>, the pin; nothing is lost, origin/main still holds those commits, and `git -C spec merge --ff-only origin/main` brings the branch forward / on main at <pin>, origin/main at <tip>, upstream still origin/main, root clean
fresh clone, a local edit to README.md	both: the refusal / detached	the moved-back line / on main at <pin>, the edit kept ( M README.md)
fresh clone, main with a commit of its own; no upstream; an upstream that is a local branch; the remote-tracking ref deleted; HEAD on main	both: the refusal	byte-identical to both
fresh clone, main checked out in another worktree of the leg	both: the refusal	branch main tip <tip> is ahead of the PIN <pin> with no commit origin/main lacks, and git refused to move it back: + fatal: cannot force update the branch 'main' used by worktree at '<path>' / nothing moves
fresh clone, a stale index.lock	both: the refusal	branch main moved back <tip> -> <pin>, the pin (origin/main still holds <tip>), and git refused to check it out: + git's lines / main at <pin>, detached. Once the lock is gone, the next run checks it out; while it stays, the next run says so again (second fix round, below)

The review's 18 first-round scenarios were re-run through e5d7a3a and b247dec. Output and the state left are byte-identical in 16 of them. The other two are the autostash and index.lock rows above.

Second fix round. Measured with the verification's probe: 30 scenarios, each on its own fresh recursive clone of one scaffold whose spec remote's main is one commit (<tip>) past the pin, with fixed commit dates so every variant sees the same object ids. Each scenario runs main 03dc729's bootstrap.py (byte-identical to 7a8b981's), b247dec's and head 757a440's, with --skip-validators, under the same gh stub. Every run exits 0.

case	main 03dc729	b247dec	head 757a440
fresh clone, a stale index.lock kept over two runs	the refusal, twice / detached	run 1: branch main moved back <tip> -> <pin>, ... and git refused to check it out:. Run 2: on main at <pin> (branch tip == pin), over a leg still detached	run 1 unchanged. Run 2: branch main is at the pin <pin>, and git refused to check it out: + git's lines / detached, main at <pin>
the same with a stale HEAD.lock	the refusal, twice	run 2: on main at <pin>, leg detached	run 2: branch main is at the pin <pin>, and git refused to check it out: + unable to update HEAD
main == pin, detached at the pin, a stale index.lock	on main at <pin> (branch tip == pin), leg detached	the same false line	branch main is at the pin <pin>, and git refused to check it out: + git's lines / detached
main == pin, HEAD on feat at <tip>, a local edit to README.md, which <tip> also changes	on main at <pin>, HEAD still on feat	the same false line	branch main is at the pin <pin>, and git refused to check it out: + Your local changes ... would be overwritten by checkout / on feat, the edit kept
fresh clone, a post-checkout hook that prints post-checkout hook failed and exits 1	the refusal	branch main moved back ..., and git refused to check it out: + the hook's line, over a leg on main	the moved-back line, then checked out, and then git said: + the hook's line / on main at <pin>
fresh clone, the leg at my spec (hand-written manifest)	the refusal	... `git -C my spec merge --ff-only origin/main` ..., which a shell splits into -C my	... `git -C 'my spec' merge --ff-only origin/main` ... / on main at <pin>

Of the 30 scenarios, 21 are byte-identical in output and state between b247dec and 757a440. In three more (another worktree, a rebase stopped at break, a bisect), only the scratch path inside git's own message differs. The other six are the rows above. The local-branch upstream (branch.main.remote of .) is refused, byte-identical to main, on all three.

Tests

tests/test_bootstrap_after_bump.py, 23 tests. The module scaffolds into its own bare repositories on disk, because each test pushes a commit to the spec remote, to a branch of its own. The fresh-clone tests have a second scaffold of their own, whose spec remote's main has moved past the pin. Each of those tests makes its own git clone --recurse-submodules of it. Everything is git and Python, with no bash and no gh. merge.autostash=true and the post-checkout hook's core.hooksPath go in through GIT_CONFIG_COUNT/GIT_CONFIG_KEY_<n>/GIT_CONFIG_VALUE_<n>, APPENDED to what the environment holds, because the Windows job already sets two entries. Never git config. The hook is a shebang script, which Git for Windows runs through its own sh, as tests/test_bump_leg_rollback.py's hook already does on all three OSes. Nothing is skipped on any OS.

First round (8):

• the issue's reproduction: scaffold, clone, bootstrap, a new leg commit, bump-leg.py, bootstrap. The leg ends on main at the new pin, the pin is unmoved and the root is clean;
• HEAD on main behind the pin is fast-forwarded, with its files;
• a branch ahead of the pin is not moved and keeps its message;
• a diverged branch is not moved and keeps its message;
• a commit made on the detached leg is not left behind;
• with an untracked file in the way, git's words are printed and nothing moves;
• main checked out in another worktree of the leg is not reset;
• the branch name is spelled in the new lines (U+2028).

First fix round (11):

• a local edit to a tracked file the pin also changes, HEAD on main, run plain and with merge.autostash=true: refused, main unmoved, git stash list empty, nothing unmerged, the edit as it was (2);
• a checkout refused after branch -f moved the branch says the branch moved, prints no line of spaces, and the next run checks it out;
• the move-back line spells the branch, its upstream and the command (U+2028);
• the fresh-clone flow end to end: clone, bootstrap. The leg ends ON main AT the pin, the pin is unmoved, the root and the leg are clean, origin/main and the upstream are kept, and the printed git -C spec merge --ff-only origin/main brings main to the remote's tip;
• a fresh leg with a local edit: main moves back and the edit is kept;
• a fresh leg whose main has a commit of its own: refused, byte-identical to main, nothing moved;
• refused, byte-identical to main, nothing moved: no upstream, the upstream's ref missing, HEAD on main, and a main that does not contain the pin (4).

Second fix round (4 new tests, 1 new case, 2 extended):

• the refused-checkout test keeps the index.lock for a second run, which says branch main is at the pin <new>, and git refused to check it out: and never [spec] spec: on main at; once the lock is gone, the next run checks main out;
• new: main == pin, the leg detached there, a stale index.lock: git's refusal, no on main at, nothing moves; once the lock is gone, the next run checks main out;
• new: a post-checkout hook that exits 1, on a fresh leg: the moved-back line, then checked out, and then git said: and the hook's line, no refused, the leg on main at the pin;
• new: a leg at my spec: the printed command is git -C 'my spec' merge --ff-only origin/main, and split as a POSIX shell splits it, it runs and brings main to the remote's tip;
• new case: a local branch as the upstream is refused, byte-identical to main;
• the move-back spelling test now expects the quoted upstream, 'origin/tb\u2028x'.

Results:

head	result
main 03dc729	15 failed, 8 passed. The 8 check refusals main already prints: ahead, diverged, a commit of its own, and the five refusal cases
b247dec	5 failed, 18 passed. The 5: the lock kept over two runs, the lock at the pin, the hook, the space path, and the spelling test's quoted upstream
head 757a440	23 passed

(The 19-test module of the first fix round gave 12 failed and 7 passed on main 7a8b981, 5 failed and 14 passed on e5d7a3a, and 19 passed on b247dec.)

Each test bites. I ran the 19-test module against eleven deliberate breaks of b247dec; each break fails exactly the tests in its row:

break	tests that fail
every branch counts as behind	ahead, diverged, and all eight fresh-clone and move-back tests
any detached checkout is moved, not only one at the pin	detached commit, spelling
checkout -B instead of branch -f + checkout	another worktree, refused checkout
the tip is not compared with the upstream	a commit of its own
refs/remotes/origin/<branch> instead of the configured upstream	no upstream
no check that HEAD is detached at the pin	HEAD on main
no check that the pin is an ancestor of the tip	main does not contain the pin
merge.autostash left as configured	the autostash run
git's blank lines kept	refused checkout
the branch move not reported	refused checkout
the move-back as checkout -f -B	local edit kept

And the 23-test module against four deliberate breaks of head 757a440:

break	tests that fail
a branch at the pin: checkout result ignored, on line printed	the lock kept over two runs, the lock at the pin
a checkout judged by git's exit code, not by HEAD	the post-checkout hook
the printed command not shell-quoted	the space path, the spelling test
an upstream outside refs/remotes/ accepted (verification finding 6's mutant)	a local branch as the upstream

Targeted runs on head 757a440 (Linux, git 2.43, Python 3.12):

• test_bootstrap_after_bump.py test_bootstrap_spelling.py test_doctor_legs_members_next.py test_repo_hygiene.py test_cli_reference.py test_agents_md_codes.py test_git_output_decoding.py test_stdout_encoding.py: 523 passed, 1 skipped. The skip is test_stdout_encoding.py:286, "the default this is about is Windows' own".
• test_scaffold_e2e.py test_family.py test_tracking_branch_ref.py test_scaffold_mount_ignored.py test_bump_leg.py: 392 passed, 1 skipped. The skip is an existing disk-case skip in test_bump_leg.py.

Composes with

Trial merges (git merge-tree --write-tree) against head 757a440:

branch	result
origin/main 03dc729	CLEAN
#495, #494 (fix/refusal-default-remediation), #493, #491, #484, #474, #467, #466, #465, #384, #382, #376, #374, #373	CLEAN
#468 fix/doctor-mid-merge-not-compliant	conflict in docs/handbook.html, which it has with main alone. Nothing in this PR's files
fix/bootstrap-print-name-escaped (#456, already merged)	conflict in bootstrap.py, because this PR is built on its squash, ec4a7a0. Clean against main alone

No other origin/fix/* branch touches templates/assembly-root/scripts/bootstrap.py or tests/test_bootstrap_after_bump.py.

Left out

• shape-doctor.py's docstrings (submodule_update_next, check_legs) and the tests' still say bootstrap "never moves an existing branch whose tip is not the pin". Other open pull requests touch shape-doctor.py, so they are left for a checklist item. The doctor's NEXT still cures every case they describe, so no printed line is wrong.
• A branch whose tip IS the pin is still checked out over a commit made on a detached leg, as before. The same guard could apply there.
• If the leg has not fetched the new pin yet (a root pulled without git submodule update), bootstrap still prints the old refusal, including The checkout stays at the pin.
• A main with no commit of its own that does not contain the pin (the remote's main diverged from it) keeps the refusal. Moving it would lose nothing either, but this PR moves a branch back only along the pin's own line.
• "Nothing is lost" holds at the last fetch (verification finding 4). Suppose the person pushed a commit to the leg's main, the leg went back to the pin, and someone then force-pushed the remote's main to drop that commit. A move-back before the next fetch leaves the commit only in the reflog once that fetch runs. It needs a force-push that drops commits from the leg's shared branch, which a protected main refuses.

Closes #475

🤖 Generated with Claude Code

Summary by Sourcery

Keep assembly legs safely attached to their tracking branches at the authoritative pin without overwriting user work.

New Features:

• Keep assembly legs on their tracking branch at the recorded pin after fast-forward bumps and eligible fresh recursive clones.
• Safely move a fresh clone's remote-only branch back to the pin while preserving the remote-tracking commits and providing a recovery command.

Bug Fixes:

• Prevent bootstrap from leaving legs detached after branch bumps or fresh clones, while preserving branches with local or divergent commits.
• Report checkout and branch-move failures accurately, including git diagnostics, without falsely claiming a branch is checked out.

Enhancements:

• Handle branch placement based on the resulting HEAD state, disable autostash for pin fast-forwards, preserve local edits, and shell-quote printed recovery commands.
• Add comprehensive cross-platform integration coverage for bump, clone, refusal, worktree, locking, hook, spelling, and recovery scenarios.

Tests:

• Add end-to-end tests covering branch placement after bumps, fresh-clone remediation, safe refusal cases, git failures, and output handling.

[sourcery-ai]

Sorry @brettheap, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 1 hour by commenting @sourcery-ai review. Upgrade to get a review now.

[sourcery-ai]

Reviewer's Guide

Bootstrap now safely fast-forwards an existing tracking branch to an advanced pin when the branch is strictly behind, while preserving local work and Git safety refusals in all other checkout states. A new cross-platform end-to-end test module covers the bump-then-bootstrap workflow, refusal cases, worktree safety, and output spelling.

Sequence diagram for bootstrap fast-forwarding a tracking branch

sequenceDiagram
    participant Bootstrap
    participant Git
    participant Leg

    Bootstrap->>Git: merge-base --is-ancestor local pin
    alt branch tip is behind pin
        Bootstrap->>Leg: fast_forward_to_pin
        alt HEAD is on tracking branch
            Bootstrap->>Git: merge --ff-only pin
            alt Git accepts move
                Git-->>Bootstrap: success
                Bootstrap-->>Leg: branch now points at pin
            else Git refuses move
                Git-->>Bootstrap: refusal lines
                Bootstrap-->>Leg: keep checkout unchanged
            end
        else HEAD is detached at pin
            Bootstrap->>Git: branch -f branch pin
            alt branch move succeeds
                Bootstrap->>Git: checkout branch
                Git-->>Bootstrap: success
                Bootstrap-->>Leg: checkout tracking branch at pin
            else Git refuses branch move
                Git-->>Bootstrap: refusal lines
                Bootstrap-->>Leg: keep checkout unchanged
            end
        else checkout is elsewhere
            Bootstrap-->>Leg: do not move checkout
        end
    else branch tip is ahead or diverged
        Bootstrap-->>Leg: print PIN mismatch and do not move branch
    end

Loading

Flow diagram for tracking branch fast-forward during bootstrap

flowchart TD
    A[checkout_tracking_branch] --> B[_is_ancestor local pin]
    B -->|no| C[Print PIN != branch tip]
    C --> D[Do not move existing branch]
    B -->|yes| E[fast_forward_to_pin]
    E --> F{Checkout state}
    F -->|HEAD on tracking branch| G[git merge --ff-only pin]
    F -->|HEAD detached at pin| H[git branch -f branch pin]
    H --> I[git checkout branch]
    F -->|Other branch or detached commit| J[Print checkout location and do not move it]
    G --> K{Git accepts move}
    I --> K
    K -->|yes| L[Print branch fast-forwarded to pin]
    K -->|no| M[Print git refusal and stop]

Loading

File-Level Changes

Change	Details	Files
Fast-forward existing tracking branches to a newer pin when doing so cannot discard commits.	Use merge-base ancestry checks to distinguish behind branches from ahead or diverged branches. Add separate handling for branch-attached and detached-at-pin checkouts. Move attached branches with fast-forward-only merge; move detached branches with branch force-update followed by checkout. Preserve existing refusal behavior for branches containing commits absent from the pin.	templates/assembly-root/scripts/bootstrap.py
Protect user work and report failed moves without changing the recorded pin.	Leave detached checkouts with post-bump commits and checkouts on other branches untouched. Print actionable messages for unsupported checkout states. Surface Git’s refusal output for untracked-file conflicts and branches used by another worktree. Spell branch names and Git output before printing them.	templates/assembly-root/scripts/bootstrap.py
Add end-to-end coverage for bootstrap behavior after bumping a leg.	Exercise detached-at-pin and branch-attached fast-forward paths, including working-tree updates. Verify ahead and diverged branches remain unchanged. Verify detached local commits, untracked files, and alternate worktrees are preserved. Validate escaped branch-name output and expected status, pin, and exit-code behavior.	tests/test_bootstrap_after_bump.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#475	When a local tracking branch is behind the pin (its tip is an ancestor of the pin), fast-forward it to the pin and, for the bumped leg detached at that pin, check out the tracking branch.	✅
#475	Preserve branches that are ahead of or diverged from the pin, and avoid moving a checkout that is neither safely on the tracking branch nor detached at the pin.	✅
#475	Add regression coverage that reproduces the scaffold, bootstrap, bump, bootstrap flow and verifies both the fast-forward behavior and refusal to move branches containing commits absent from the pin.	✅

Possibly linked issues

• bump-leg.py, then make bootstrap, leaves the leg detached: bootstrap never fast-forwards a local tracking branch that is behind the new pin, though AGENTS.md, README and bump-leg.py say it re-places it #475: The PR fixes the reported behavior by fast-forwarding a behind tracking branch to the pin and checking out the branch when safe.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[brettheap]

(lane openRepoShape-3, 2026-10-12T22:30Z) @codex review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-13T00:00:26.775285Z	b247dec	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e5d7a3a81d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Disable autostash for the bootstrap fast-forward

When the user has merge.autostash=true and local edits conflict with changes between the branch tip and the pin, this git merge fast-forwards the branch, reapplies the automatic stash with conflicts, and still exits 0. _git_says consequently discards Git's conflict warning and bootstrap reports a successful fast-forward while leaving unmerged files and an autostash entry; this reproduces on Git 2.43. Git's documentation explicitly warns that applying the stash after a successful merge may cause conflicts, so pass --no-autostash here to preserve the intended all-or-nothing handling of dirty worktrees. Git merge documentation

Useful? React with 👍 / 👎.

[brettheap]

(lane openRepoShape-3, 2026-10-12T23:56Z) Fixed in b247dec: the on-branch fast-forward is now git -c merge.autostash=false merge --ff-only -q <pin> (-c rather than --no-autostash, which a git before 2.27 rejects), so a conflicting tracked edit is refused with git's own lines and nothing moves, with or without merge.autostash=true. tests/test_bootstrap_after_bump.py covers both runs and asserts the branch unmoved, git stash list empty and nothing unmerged.

[brettheap]

(lane openRepoShape-3, 2026-10-12T23:56Z) @codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b247dec0f9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Preserve checkout failures on subsequent bootstrap runs

When branch -f succeeds but checkout continues to fail—for example, with the index.lock condition exercised by the new test—this leaves the branch at the pin while HEAD remains detached. A subsequent bootstrap then enters the existing local == pin path, ignores another failed checkout, and prints on main at ... even though the leg is still detached, so the next commit can be created off-branch. Roll back the branch after a failed checkout, or make the local == pin path verify and report checkout failure.

AGENTS.md reference: AGENTS.md:L101-L104

Useful? React with 👍 / 👎.

[brettheap]

(lane openRepoShape-3, 2026-10-13T00:25Z) Fixed in 757a440 by verifying, not rolling back: the branch-at-the-pin path (new place_at_pin) and _move_and_check_out now run the checkout through _git_says and read where HEAD ended up, so a second run with the lock still there prints branch main is at the pin <pin>, and git refused to check it out: with git's lines instead of on main at; this also fixes main's own false line for a branch already at the pin. tests/test_bootstrap_after_bump.py keeps the index.lock across two runs and adds the branch-at-the-pin case.

[brettheap]

(lane openRepoShape-3, 2026-10-13T00:26Z) @codex review

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[brettheap]

Lane: openreposhape-5 (openRepoShape-5)

(lane openRepoShape-5, v1.0.0 accuracy pass, #483; read at fix/bootstrap-fast-forwards-tracking-branch 757a440 against main 5a25387, where #394 and #484 have landed) Two doc findings are false today and become true only in part with this pull request. No doc edit is asked of you; they are listed so the wording is read against your behaviour. Lane 5's docs pull request (#505, branch docs/v1-accuracy, head f35e59fa, part of #483) leaves both sentences alone and merges clean with yours (git merge-tree --write-tree against 757a4402: clean everywhere, README.md 1422 and AGENTS.md 490 lines).

AGENTS.md:345 (D1-F9) and README.md:995 (D3-F7): "The leg is left DETACHED at the new commit. make bootstrap in the root re-places it on its tracking branch AT the new pin." (Line numbers at your head; #484 has landed with both sentences unchanged, at AGENTS.md:355-356 and README.md:994-995 on main.)

• True on main: bootstrap checks the branch out only when its tip already IS the pin; otherwise it prints [spec] spec: PIN 1bfb3c456c9e != branch main tip c5e75731d678 and not moving an existing branch. The checkout stays at the pin ... and leaves the leg detached (templates/assembly-root/scripts/bootstrap.py:151). A leg's local tracking branch sits at the OLD pin whenever the new commit came from someone else's push, which is the state the scaffold's own bootstrap leaves ("on main at c5e75731d678 (branch tip == pin)"). Run: scaffold, bootstrap, push a new commit to the spec remote from another clone, bump-leg.py --leg spec --to <it> (exit 0), then python3 scripts/bootstrap.py: the leg HEAD was still detached at the pin. The sentence held only when the commit was made and pushed from that mount's own branch. scripts/bump-leg.py prints the same unconditional sentence after every bump (:1506-1507 on main).
• With your change, at 757a440 (templates/assembly-root/scripts/bootstrap.py), bootstrap puts the branch on the pin in three cases: a branch AT or BEHIND the pin (fast_forward_to_pin, :275-341, _is_ancestor at :150, called at :435; prints branch main fast-forwarded <a> -> <b>, the pin, :338); a branch AHEAD of the pin with no commit of its own, its tip being its upstream's remote-tracking ref, from a leg detached at the pin (move_back_to_pin, :343-391, _held_upstream_past_the_pin at :177, called at :439; prints branch main moved back <a> -> <b>, the pin; nothing is lost, <upstream> still holds those commits, :385); and place_at_pin (:255, called at :432) for a branch already on the pin.
• It still leaves the leg detached, and says why, in four cases: a branch holding a commit of its own past the pin, ahead or diverged (PIN <a> != branch main tip <b> and not moving an existing branch, :446); a leg checked out anywhere but the tracking branch or the pin (not moving the checkout off it, :319); a move git refuses, a local change blocking it (git refused to move it, :324-331, and, moving back, git refused to move it back, :382-383); and a branch ahead of the pin with no commit of its own when the leg is not detached AT the pin (_held_upstream_past_the_pin requires it, :183-187), which falls to not moving an existing branch.
• So the sentence is incomplete without its limits. Suggested text, for whichever lands first: "The leg is left DETACHED at the new commit. make bootstrap in the root puts it back on its tracking branch when that branch is at or behind the new commit, or ahead of it with no commit of its own; a branch with commits of its own past the pin is not moved (bootstrap says not moving an existing branch), and the leg stays detached at the pin. Say which when you relay the result." It is a docs and tool-text change (bump-leg.py's print) for whoever takes it.
• Every project's AGENTS-shape.md (a pinned template copy) and docs/handbook.html carry the same promise; only AGENTS.md and README.md were audited.

[brettheap]

(lane openRepoShape-3, 2026-10-13T01:47:08Z) Thanks. #490 keeps its scope. Three places still promise more than bootstrap does: the AGENTS.md and README.md sentence ("make bootstrap in the root re-places it on its tracking branch AT the new pin"), the same promise in AGENTS-shape.md and the handbook, and bump-leg.py's unconditional print after a bump. All three go on #458's checklist with your suggested text, to be made true against #490's behaviour once #490 lands. Whichever pull request takes them, #505 included, closes that line.

[sonarqubecloud]

Quality Gate passed

Issues
16 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud