[brettheap]

Lane: openreposhape-4 (openRepoShape-4)
Claim: #603 (comment)

What changed and why

fast_forward_to_pin moved a tracking branch BEHIND the pin, and put the leg on it, from two checkouts: HEAD on the branch itself, and HEAD detached at the pin. HEAD on ANOTHER branch (T7) fell to _say_neither ("which is neither") and nothing moved, while place_at_pin checked the same checkout out for a tracking branch AT the pin (P9). R556 probed both at 26c1600, and the P9 test left the difference "#458's to rule on". The family holder's AGENTS-shape.md and bump-leg.py's leg_placement docstring still promised placement unconditionally, which #556 had already taken out of the assembly root's copy.

D1, option A of the checklist triage (Brett Heap, 2026-10-15T16:49:38Z): the code follows the sentence. T7 is placed as P9 is.

• The new path. HEAD on a refs/heads/ ref that is not the tracking branch takes the path HEAD detached at the pin takes: _move_and_check_out (branch -f <branch> <pin>, then _check_out, judged by where HEAD is afterwards). That loses no commit: the tracking branch's tip is an ancestor of the pin, and the other branch is not touched and keeps its commits.
• The leg is told it left the branch. On success it prints the fast-forwarded line the other two starts print, byte for byte, and, only when HEAD started on another branch, one more indented line before git's own: the leg was on <other>, which keeps its commits; it is on <tracking> now, or the leg was on <other>, a branch with no commit yet; it is on <tracking> now for an orphan HEAD. P9's lines are not touched (P9 says nothing of the branch it left; that goes to Tracking: update-shape.py and bump-leg.py, keeping a project's shape copies and leg pins current #458). The refused paths print no extra line: HEAD stays on the other branch, and git's lines already say why. The name is spelled (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).
• The checkout refused after branch -f worked. From another branch the checkout changes files, so git can refuse it over a local edit or an untracked file, where one from the pin cannot. The existing moved-and-refused lines are printed, the branch stays at the pin and is never put back, HEAD stays on the other branch, and the next run meets P9.
• branch -f refused (another worktree holds the tracking branch): the existing not-moved refusal.
• HEAD detached at a commit that is not the pin still gets "which is neither": a commit made there is on no branch.
• HEAD on a branch with no commit yet (an orphan): placed as P9 places it. Free, it prints the fast-forward line and the orphan line above, HEAD on main at the pin; with an untracked file in the way, T7 prints the moved-and-refused lines and P9 its own is at the pin, and git refused to check it out lines, and HEAD stays on the unborn branch in both.
• "Loses no commit", not "loses nothing". A checkout git makes from another branch overwrites an IGNORED file at a path the pin tracks, and moving off a branch with a merge in progress ends that merge: MERGE_HEAD goes and the staged result is carried onto the tracking branch. Neither is new: both are already true of P9 and of the missing-branch path, and the ignored file of the on-branch merge --ff-only too. The docstrings say so; they are Tracking: update-shape.py and bump-leg.py, keeping a project's shape copies and leg pins current #458's to rule on, and the coordinator posts them there. No behaviour changed for them.
• The line is its own helper. Round 1's if other_branch: block took fast_forward_to_pin's cognitive complexity to 16 (SonarCloud S3776, limit 15); the print, ternary included, is now _say_left(head, current, named) next to _place_of, with a docstring that says why, and the caller is 14. The printed bytes did not change.
• Docstrings of fast_forward_to_pin (two checkouts become three, and why a leg on another branch can be moved), _move_and_check_out (it no longer starts only from the pin) and _say_neither (the "somebody's work" clause is gone) say why and name bootstrap.py and AGENTS-shape.md: a leg on another branch is placed when its tracking branch is at the pin and left when it is behind, and the family holder's copy still promises placement unconditionally #603 and D1.
• Docs.
  • "Where that loses no commit", in the three places this PR says what placement loses: templates/family-root/AGENTS-shape.md (the three lines round 0 added: each member's legs go on their tracking branch AT their pinned commits where that loses no commit, bootstrap says why where it does not, by running the member's own bootstrap), templates/assembly-root/AGENTS-shape.md:95-96 (bootstrap.py: a leg detached off the pin is left where it is and said, so a commit made there is no longer stranded when its branch is already at the pin, the not moving an existing branch line names where the checkout is, and bump-leg.py and AGENTS-shape.md say "or says why not" (#533) #556's sentence, one word changed, same line count) and leg_placement's docstring in bump-leg.py (re-wrapped in the same three lines; no printed line of bump-leg.py changes). Round 1 had left "loses nothing" in all three, which the ignored-file and merge-in-progress states make false. Left alone: the docstrings in bootstrap.py that are about moving the branch REF, which does lose nothing, the move-back line's nothing is lost, <upstream> still holds those commits, which its own clause scopes to commits, and shape-doctor.py.
  • Round 1 folded in the three other unconditional promises, saying "where that loses no commit" and why not where it does not: templates/assembly-root/Makefile's make help (pinned; one more help line than before, aligned as its others are), and templates/family-root/README.md and templates/assembly-root/README.md (rendered at scaffold time, same line counts). Round 2 puts "(so you are not staring at a detached HEAD)" in the assembly README straight after "at its pinned commit" again.
  • templates/family-root/scripts/bootstrap.py:31-32 is left for Tracking: update-shape.py and bump-leg.py, keeping a project's shape copies and leg pins current #458: changing it would add a file to the family holder's re-pin.

The case table

Tracking branch (rows) by where HEAD is (columns), measured on a bumped scaffold (leg detached at the new pin P over main at the old pin O) before and after this change, with the real bootstrap.py. "no commit yet" is git switch --orphan; git checkout --orphan, which leaves the files staged, gave the same result in every row. Bold cells changed (and now also print the one line above); every other cell is byte-identical before and after.

main is	HEAD on it	detached at the pin	detached elsewhere	on another branch	on a branch with no commit yet
at the pin	placed	placed	left, which is neither	placed (P9)	placed
behind the pin	fast-forwarded	fast-forwarded	left, which is neither	fast-forwarded (was left)	fast-forwarded (was left)
ahead, no commit of its own	left, not moving	moved back	left, not moving	left, not moving	left, not moving
ahead, one of its own	left, not moving	left, not moving	left, not moving	left, not moving	left, not moving
missing	created, on it	created, on it	left, does not exist	created, on it	created, on it

The assembly copy's sentence, now "places each leg on its tracking branch AT the pin where that loses no commit, and leaves one detached at any other commit, saying why", is true of all three changed cells (it was false of them before), and of the ignored-file and merge-in-progress states, where "loses nothing" was not. It still disagrees with the code in three states, left for #458 with no code changed: ahead with no commit of its own (its tip IS its upstream's remote-tracking ref), with HEAD on the branch, on another branch, or on a branch with no commit yet. The commits are held by the remote-tracking ref, as for the "moved back" cell, but move_back_to_pin starts only from HEAD detached at the pin, so these keep not moving an existing branch.

Tests

tests/test_bootstrap_after_bump.py, on its own harness, lines asserted byte for byte (49 tests, 11 of them new, and three existing ones touched):

• T7: elsewhere with a commit of its own (its file is taken out, the pin's files put in, elsewhere untouched and holding its commit, main and HEAD at the pin, the pin not moved), with the fast-forwarded line followed by the new line;
• T7 with elsewhere exactly at the pin: the same, and no file in the leg is rewritten (bytes and mtimes compared);
• T7 from a branch that is itself behind the pin: the tracking branch moves, elsewhere stays at the old pin;
• T7 refused: a local edit on elsewhere to a file the pin changes. Moved-and-refused lines and no new line, HEAD on elsewhere with the edit intact, main at the pin; the second run is P9's refusal; with the edit gone it places;
• T7 with branch -f refused (another worktree holds main): the not-moved refusal, no new line, nothing moves;
• a branch with no commit yet, behind or at the pin, free or with an untracked file in the way (four cases): the orphan wording on the free T7 case, no line on the rest;
• new in round 1: a T7 move with a failing post-checkout hook: the fast-forward line, the new line, then checked out, and then git said: and the hook's words, HEAD on main at the pin, no refused;
• new in round 1: a branch named with U+2028 is spelled in the new line;
• the detached-at-the-pin and HEAD-on-the-branch starts assert the new line is absent;
• the P9 test's docstring no longer leaves the difference "Tracking: update-shape.py and bump-leg.py, keeping a project's shape copies and leg pins current #458's to rule on" (its asserts stay);
• the control, a leg detached off the pin still saying "which is neither", is the existing test_a_commit_made_on_the_detached_leg_is_not_left_behind.

Runs, from a standalone clone, /usr/bin/python3 -m pytest -rs over test_bootstrap_after_bump, test_bootstrap_spelling, test_scaffold_e2e, test_bump_leg, test_bump_leg_dry_run_tracking, test_family, test_family_siblings_placement, test_family_tracking_branch, test_doctor_legs_members_next, test_template_text_placeholders, test_repo_hygiene, test_cli_reference, test_agents_md_codes, test_doctor_next_is_a_command, test_scaffold_mount_ignored, test_adopt_gitmodules_values and test_shape_doctor (the files git grep finds the changed phrases in):

• round 1's commit f8989b56: 1589 passed, 4 skipped, exit 0;
• the head 088c7728 (the merge of main below), with test_bump_leg_paste_lines and test_bump_leg_rollback added: 1646 passed, 4 skipped, exit 0 (17 min 28 s); the skips of those two runs: test_bump_leg.py:693 (needs a disk that ignores case) and three at test_shape_doctor.py:9878 (the PowerShell line, a Windows host only);
• round 2's commit 6ad23038, over test_bootstrap_after_bump, test_bootstrap_spelling, test_template_text_placeholders, test_template_values_single_pass, test_free_plan_hint, test_family_tracking_branch, test_family, test_bump_leg, test_bump_leg_paste_lines, test_repo_hygiene, test_cli_reference and test_doctor_legs_members_next: 992 passed, 1 skipped, exit 0 (7 min 24 s), the skip being test_bump_leg.py:693.

The full suite was not run here.

Mutants, each in a scratch clone with this change's files copied in, against all 49 tests of the module:

• M1, remove the new path: 9 fail, all this PR's.
• M2, merge --ff-only on the branch HEAD is on: 9 fail, including "elsewhere is not moved".
• M5, drop _say_after in fast_forward_to_pin: it survived round 0; the hook test now fails (1 fail).
• M8, drop the new line: 6 fail.
• M9, print the new line for every start: 2 fail (the detached-at-the-pin and HEAD-on-the-branch starts).
• M10, the orphan wording is the other branch's: 1 fails.
• M11, the new line printed before the fast-forwarded line: 6 fail; M13, the new line naming the tracking branch instead of the branch left: 6 fail (both over round 2's bytes).
• R603 killed M3 (check out before moving the branch), M4 (an orphan HEAD treated as detached), M6 (also move from a leg detached elsewhere) and M7 (branch -f on the wrong branch) against round 0's tests.

Shared files

#588 has landed (709eec16), and it changed scripts/bump-leg.py, which this PR changes too: the one docstring hunk in leg_placement, and none of #588's. Under ruling 27 this branch merged that main in round 1: merge commit 088c7728, tree 8943978679611f825262b7d8bd85387eda9d96ac, a clean merge ("Auto-merging scripts/bump-leg.py", no conflict). Round 2 is one commit on top of it, with no merge of main: 6ad23038. git merge-tree --write-tree of the head with main 66267f0a (current when this was written) is clean, tree 165f2711867f0ab2a4797ef202383dcc01a7c3e0, and main has touched none of the PR's files since 709eec16.

The re-pin, measured

Measured at round 2's commit with this PR's own changes only: update-shape.py check --upstream <a clone of base 3f768a6 plus this PR's diff>, on an assembly root and a family holder scaffolded from base 3f768a66. (scripts/bump-leg.py in that clone carries only this PR's docstring hunk; #588's lines are main's.) At the branch tip, which has main's #575 validators merged in through 709eec16, the same roots also show scripts/validate-pins.py (assembly: upstream-changed 4 unchanged 7) and scripts/validate-family.py (family: upstream-changed 2 unchanged 8); those rows are main's, not this PR's.

• assembly root: upstream-changed scripts/bootstrap.py, upstream-changed Makefile, upstream-changed AGENTS-shape.md; upstream-changed 3 unchanged 8;
• family holder: upstream-changed AGENTS-shape.md only; upstream-changed 1 unchanged 9.

A pinned-copy change: an assembly root takes it as one upstream-changed re-pin of scripts/bootstrap.py, Makefile and AGENTS-shape.md, a family holder as one of AGENTS-shape.md; the two README templates are rendered at scaffold time, not pinned, so they reach new projects only.

Closes #603

🤖 Generated with Claude Code

[sourcery-ai]

Reviewer's Guide

Bootstrap now places a bumped leg onto its tracking branch when HEAD is on another local or unborn branch, using a force-and-checkout path that preserves the other branch, reports checkout failures consistently, and is backed by extensive behavioral tests and documentation updates.

State diagram for bumped leg placement outcomes

stateDiagram-v2
    [*] --> HeadLocation
    HeadLocation --> TrackingBranch: HEAD on tracking branch
    HeadLocation --> PinDetached: detached at pin
    HeadLocation --> OtherBranch: HEAD on another or unborn branch
    HeadLocation --> ElsewhereDetached: detached elsewhere
    TrackingBranch --> Placed: merge --ff-only succeeds
    PinDetached --> Placed: _move_and_check_out
    OtherBranch --> Placed: branch -f and _check_out succeed
    OtherBranch --> TrackingAtPin: checkout refused after branch -f
    OtherBranch --> NotMoved: branch -f refused
    ElsewhereDetached --> LeftDetached: _say_neither
    Placed --> [*]
    TrackingAtPin --> [*]
    NotMoved --> [*]
    LeftDetached --> [*]

Loading

Flow diagram for bootstrap leg placement after a bump

flowchart TD
    A["bootstrap fast_forward_to_pin"] --> B{"Where is HEAD?"}
    B -->|tracking branch| C["merge --ff-only pin"]
    B -->|detached at pin| D["_move_and_check_out"]
    B -->|another local or unborn branch| D
    B -->|detached elsewhere| E["_say_neither; leave leg"]
    D --> F["branch -f branch pin"]
    F -->|success| G["_check_out tracking branch"]
    F -->|refused| H["report not moved"]
    G -->|success| I["leg placed at pin"]
    G -->|refused| J["branch remains at pin; HEAD stays put"]

Loading

File-Level Changes

Change	Details	Files
Extend bootstrap placement to recover legs checked out on another local branch without moving that branch.	Detect non-tracking local branches and route them through branch-forcing plus checkout logic. Fast-forward the tracking branch to the pin while preserving the branch currently holding HEAD. Handle checkout conflicts and worktree-held branches with existing refusal behavior and leave recoverable state for the next run. Keep detached work at non-pin commits classified as neither.	templates/assembly-root/scripts/bootstrap.py
Align documentation with conditional leg placement semantics.	Document that placement occurs where it loses nothing and explain when bootstrap reports why it cannot place a leg. Update implementation docstrings for the added checkout path and preserved detached-commit behavior.	templates/family-root/AGENTS-shape.md scripts/bump-leg.py templates/assembly-root/scripts/bootstrap.py
Add end-to-end coverage for branch, orphan, refusal, and preservation cases.	Verify behind-tracking-branch legs on another branches are placed while the other branch remains unchanged. Cover already-at-pin branches, checkout conflicts, worktree refusal, unborn branches, and detached non-pin controls. Assert exact output, HEAD/branch positions, file preservation, and subsequent-run behavior.	tests/test_bootstrap_after_bump.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#603	When a leg's tracking branch is behind the pin and HEAD is on another branch, fast-forward the tracking branch to the pin and check it out without moving or losing commits on the other branch; preserve refusal behavior when Git cannot check out the tracking branch.	✅
#603	Correct the family holder's AGENTS-shape.md and bump-leg.py documentation so they promise placement only where it loses nothing and explain that bootstrap says why when it cannot place a leg.	✅

Possibly linked issues

• Tracking: update-shape.py and bump-leg.py, keeping a project's shape copies and leg pins current #458: The PR directly resolves both issue items: it places T7 like P9 and qualifies the family-root placement promise.

---

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.

[sonarqubecloud]

Quality Gate passed

Issues
12 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

[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 day and 2 hours by commenting @sourcery-ai review. Upgrade to get a review now.