[brettheap]

Lane: openreposhape-5 (openRepoShape-5)
Claim: #647 (comment)

What changed and why

#607 (#637) gave family.py and the holder's validate-family.py one sentence for a switch -c that fails fatal: a branch named '<branch>' already exists (exit 128):

If git switch -c says that branch already exists, an earlier act left it: give the branch another name, which starts it where the holder stands, or, only if that branch holds work not merged yet, the same command with switch in place of switch -c goes back to it and keeps every commit on it.

Two tools still printed a switch -c and said nothing more. Both now say the same sentence under that line, each as its own constant, BRANCH_LEFT, as #637 does:

• scripts/bump-leg.py, with "the project" where the others say "the holder". It follows the command in all three places _switch_command is named:
  • the bump-leg-on-tracking-branch remedy: after and re-run.;
  • the bump-leg-root-detached remedy: on the line under it;
  • the dry run's closing hint (bump-leg.py --dry-run, step 1 of advancing a leg, is refused bump-leg-on-tracking-branch on every fresh project, before the old -> new line the human is to read #477): the new last line, under the hint.
• setup-project.py: the same sentence, word for word (the holder), as one more comment line under the family block's switch -c line. The family block's two comment lines stay, and the line comes after them.

No command line changes, and none is quoted differently. The sentence is words, not a second command, so no PowerShell quoting is added (#532) and no README sentence about quoting becomes false.

Pinned files: none. This changes no file under templates/.

Decisions and evidence

1. Where the sentence goes in bump-leg's tracking-branch remedy: after and re-run., not between the command and and re-run. The remedy reads Run:, the command on its own line, and re-run. With the sentence between, and re-run. would hang under a full sentence. After it, the text before the sentence is byte for byte what it was, so the command line and and re-run. keep their places. The sentence is still under the switch -c line.
2. setup's sentence is one comment line, unbroken (about 300 columns). The brief asked for one comment line, word for word. family.py's dry run prints it unbroken too. The block's other comments are hand-wrapped at 78 columns. A wrapped block would be a small change if the coordinator prefers it; the test would then join the comment lines.
3. Every printed command line is unchanged, and the tests prove it: bump-leg's line is read back by shlex.split and compared to the argv it always meant (switch_argv); setup's by host_words, on a folder with a space and one with a space beside an apostrophe. The block still has exactly two command lines.
4. One rule, four copies. family.py and validate-family.py: where an earlier act left the branch, the switch -c remedy says to give it another name, or go back only if it holds work not merged yet, and the docs say family/add-<Project> (#607) #637's equality test, now test_the_tools_say_the_same_words, also asserts that setup-project.py's constant equals family.py's and the validator's, and that bump-leg's equals it with "the project" for "the holder". It was renamed from test_the_two_tools_say_the_same_words, because "two" is no longer true. The project's wording is pinned as text once, as BRANCH_LEFT_PROJECT in tests/test_bump_leg_paste_lines.py, beside the lines it follows; the holder's is family.py and validate-family.py: where an earlier act left the branch, the switch -c remedy says to give it another name, or go back only if it holds work not merged yet, and the docs say family/add-<Project> (#607) #637's pinned copy in tests/test_validate_family_branch_step.py. test_the_two_pinned_texts_differ_in_the_one_word_only ties the two pinned copies together.
5. Existing tests that pinned the old last lines take the sentence. Seven tests in three files (listed under Tests). Each read the last line of an output, or the exact end of a remedy; none changes what it checks.
6. The new module imports family.py and validate-family.py: where an earlier act left the branch, the switch -c remedy says to give it another name, or go back only if it holds work not merged yet, and the docs say family/add-<Project> (#607) #637's typing helpers (leave_branch, refused_as_left, type_other_name, typed, without_c, head, on_branch) instead of copying them, so the duplication gate sees one body.

Tests

New module tests/test_branch_left_bump_leg_setup.py, 19 tests:

• bump-leg, each of three places (tracking, detached, dry-run): the command is the one it always was and what stands under it is the sentence (3); the printed line makes the branch where none is left (3); where an earlier bump left bump/spec-<id> holding a commit of its own, the printed line fails already exists (exit 128) and changes nothing, then another name works (the new branch starts where the root stands, the bump goes through on it, its commit sits on the commit the root stood on, and HEAD:spec is the new commit) (3), and going back with switch for switch -c works (back on the branch at its own commit, the bump goes through there on top of it) (3).
• setup, the family block: the line, the two comments, the sentence, the add line, two command lines (2, one per folder name); a real setup-project.py run prints the sentence once, under the right comment (1); in a real local holder (the family fixture's, on its tracking branch), with a real member: the printed line makes the branch where none is left, and where an earlier try left family/add-<project> with a commit of its own, another name works and family.py add goes through on it, and going back works and add goes through on top of the earlier commit (3).
• test_the_two_pinned_texts_differ_in_the_one_word_only (1).

Edited tests: seven cases in six test functions of the three bump-leg files, test_bump_leg_dry_run_tracking.py (4: the dry run's report, the difference from a dry run on a branch, the hint pasted for a root with a space, the real refusal byte for byte), test_bump_leg_paste_lines.py (1: the exact remedies) and test_bump_leg_dry_run_truth.py (2: the hint's branch name, [local-remote-dir] and [origin]); and, beside them, the extended test_the_tools_say_the_same_words in test_family_switch_branch_exists.py.

Runs, on be1bff9 (BASE a524542 plus main 95780dd), through run9.sh, gh stub first on PATH:

• New module with family.py and validate-family.py: where an earlier act left the branch, the switch -c remedy says to give it another name, or go back only if it holds work not merged yet, and the docs say family/add-<Project> (#607) #637's module: 44 passed in 61.90s.
• Set 1, 21 files: every tests/test_bump_leg*.py (7), the new module, test_bootstrap_after_bump, test_stdout_encoding, test_non_utf8_git_reads, test_agents_md_codes, test_commit_trailers, test_update_shape_paste_lines, test_validate_pins_lockstep_lines, test_pin_rewrite_layout, test_validator_child_encoding, test_validate_pins_unreadable_workflows_dir, test_template_text_placeholders, test_repo_hygiene, test_cli_reference: 1040 passed, 2 skipped in 459.92s. Both skips were there before: a case-ignoring disk (test_bump_leg.py:693) and a Windows default (test_stdout_encoding.py:286).
• Set 2, 10 files: every file git grep -l 'switch -c' tests/ names outside set 1 (test_dry_run_asks_remotes, test_family_printed_quoting, test_family_refuse_up_front, test_family_switch_branch_exists, test_family_tracking_branch, test_validate_family_branch_step, test_validate_family_unnamed_mounts), plus test_setup_by_hand_commands, test_setup_project_py, test_setup_sh: 592 passed in 506.74s.
• Before family.py and validate-family.py: where an earlier act left the branch, the switch -c remedy says to give it another name, or go back only if it holds work not merged yet, and the docs say family/add-<Project> (#607) #637 landed, on 6ac545f: set 1 1042 passed, 2 skipped, set 2 (9 files) 441 passed.

Fails on BASE. The same five test files from the head, run on main 95780dd (no source change): 26 failed, 80 passed in 168.33s. 18 of the 19 new tests fail, test_the_tools_say_the_same_words fails (no BRANCH_LEFT in either new place), and the seven edited tests fail. The one new test that passes on BASE is test_the_two_pinned_texts_differ_in_the_one_word_only: it reads text only. On the first commit alone, against a524542, the old module copy gave 20 failed, 1 passed.

Reproductions (local bare remotes, the gh stub first on PATH)

A real project (scaffold-project.py into local remotes, a recursive clone, the spec leg advanced on a branch of its remote) and a real holder (family.py init, then a real setup-project.py Sample --yes --family Orbit run). An earlier act left the branch with a commit of its own.

• On BASE a524542: bump-leg.py on the tracking branch ends Run: / the switch -c line / and re-run. and nothing more. The line typed as printed gives fatal: a branch named 'bump/spec-712e4ce5d766' already exists, exit 128. The detached refusal and the dry run's hint end on the command the same way. setup's block is the switch -c, # a branch first: add refuses the and # holder's tracking branch, then the add. Typed, fatal: a branch named 'family/add-sample' already exists, exit 128.
• On the head: each of the four prints the sentence under the line, and the same line gives the same 128. Then:
  • another name (<line>-2): exit 0; bump-leg.py goes through on it, on top of the commit the root stood on; family.py add goes through on it;
  • going back (switch for switch -c): exit 0, at the earlier commit; bump-leg.py and family.py add go through, their commit on top of it.
• Both choices already worked on BASE: the sentence tells a person so. No row needs real GitHub.
• A real earlier bump, not a made-up branch. I ran a real bump on bump/spec-<id>, then went back to main. There the root shows M spec (the leg is still at the bump's commit), and the next bump-leg.py is refused bump-leg-root-dirty before it reaches the switch -c line. After git submodule update puts the leg back, the line appears, fails already exists, and the other name works. See the checklist candidates.

Mutation probes

Each hunk was reverted or broken alone in a scratch clone of the head, and the new module plus test_the_tools_say_the_same_words was run. Every mutation makes new tests fail:

Mutation	Result
bump-leg BRANCH_LEFT says "the holder"	13 failed: the equality test, and the three places in each of four tests
bump-leg BRANCH_LEFT drops only if	13 failed, the same
bump-leg-root-detached remedy without the sentence	4 failed (the detached case of each of four tests)
bump-leg-on-tracking-branch remedy without the sentence	4 failed (the tracking case of each)
the same remedy with the sentence above and re-run.	4 failed, the same
dry run's hint without the sentence	4 failed (the dry-run case of each)
_switch_command prints switch -C	9 failed (the "another name" and "going back" cases, and the three "command is the one it was" cases); the control, where no branch is left, still passes, as -C makes a new branch too
setup BRANCH_LEFT says "the project"	7 failed (the equality test and six)
setup block without the sentence	6 failed
setup sentence above the block's two comments	6 failed
setup BRANCH_LEFT drops only if	7 failed

The other hunks change only docstrings and comments (_switch_command, _branch_to_bump_from, family_next_command, the comment above the dry run's hint). They change no behaviour.

Merge checks (git merge-tree --write-tree be1bff90 <ref>)

Ref	Result
origin/main d4a7fab (one commit past my merge of 95780dd; touches scripts/family.py, scaffold-project.py, docs/cli.md)	clean
#637 (landed as 95780dd)	merged into this branch once, clean
#623 (lane 2, setup-project.py steps (3) and (4); landed as abb956e)	merged in with #637, clean: its hunks are far from family_next_command
#639 08b6245 (lane 5, #611)	clean
#641 e87fcb0 (touches bump-leg.py and family.py)	conflicts in scripts/family.py, and the same conflict arises against main alone: not from this branch. bump-leg.py merges clean.
#615 6ad2303 (touches bump-leg.py)	clean
#631, #636 (lane 4)	clean
#642, #643, #644	clean
lane-5 siblings fix/645 e2110f8, fix/646 2216e1c, fix/648 852c5c4, fix/649 d91b314	clean
#561 (lane 4's fix/bump-leg-tag-dry-run)	its work is on main already (7d9bec9, asked = commit); its stale pull head conflicts with main alone, so it is not an open PR to check

Left out, and why

• No README, AGENTS.md or handbook edit. I checked every sentence about these lines: AGENTS.md:337-351 and 374 (the dry run "prints the git switch -c"), README.md:157 and 1011, docs/cli.md (generated; no --help text changes) and the handbook. None becomes false.
• Windows and macOS are not checked here, and no CI job checks them since ci: run the test suite on Linux only #597. The tests type argvs, run no shell, compare no file that write_text wrote, and read setup's lines with host_words.
• A branch checked out in another worktree makes git switch <branch> fail (family.py and validate-family.py: where an earlier act left the branch, the switch -c remedy says to give it another name, or go back only if it holds work not merged yet, and the docs say family/add-<Project> (#607) #637's "Left out", N1); the sentence is not made longer for it.
• I did not tick or mark the lines on Tracking: update-shape.py and bump-leg.py, keeping a project's shape copies and leg pins current #458 and Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459.
• Review rv647 (APPROVE WITH NITS, 0 blockers, 0 should-fix, 5 nits), and what is left of it:
  • Commit 6ac545f's message says "Four existing tests … take the sentence". It is six test functions (seven cases) in three files, as the Tests section says. The squash message is this body.
  • scripts/bump-leg.py's comment near :1164 still says "the three tools follow one rule"; there are four copies of the sentence now, and setup-project.py's comment names two. Left for the bump-leg.py issue filed from Tracking: update-shape.py and bump-leg.py, keeping a project's shape copies and leg pins current #458's lines, which lands after this and edits that file.
  • No AST guard holds a fourth _switch_command caller to the sentence, as family.py and validate-family.py: where an earlier act left the branch, the switch -c remedy says to give it another name, or go back only if it holds work not merged yet, and the docs say family/add-<Project> (#607) #637's test_every_remedy_that_names_a_switch_line_ends_with_the_sentence holds the validator's.
  • Setup's sentence prints as one comment line of about 317 columns in a block wrapped at 78. It is unbroken as family.py's _branch_said prints it, which is what lets the byte-for-byte equality tests hold (decision 1).

Checklist candidates (not fixed here)

• bump-leg.py: after a real bump on a branch and a switch back to an older branch, the root is dirty ( M spec) and bump-leg-root-dirty's remedy, "commit or stash them first", is wrong advice. The leg is left at the bump's commit and git switch does not move it (README says the leg is left detached at the new commit). git submodule update (or make bootstrap) puts it back and clears the refusal. The remedy could say so where the one dirty path is a leg's mount. It also means the switch -c sentence is reached only after that step in this flow.
• The same flow's "go back" choice meets that refusal too (rv647): git switch to the branch that holds the earlier bump leaves the leg behind, so the re-run is refused bump-leg-root-dirty; after git submodule update it says nothing to do, and only the push is left.
• update-shape.py:5279 prints NEXT git -C <root> checkout -b shape/update-<12> && git … commit (rv647, read only): it fails already exists the same way, and the && chain then commits nothing. It is checkout -b, outside bump-leg.py and setup-project.py: the git switch -c line fails "already exists" when an earlier act left that branch, and nothing says what to do (#607's sentence, in the two tools #607 left) #647.
• family.py, after a real earlier add and a switch back: another name works for the switch, but family.py add is then refused member-path-taken, because git left the populated members/<Project> checkout behind (rv647; identical on the base). It bears on family.py and validate-family.py: where an earlier act left the branch, the switch -c remedy says to give it another name, or go back only if it holds work not merged yet, and the docs say family/add-<Project> (#607) #637's "another name works".

Closes #647

🤖 Generated with Claude Code

Summary by Sourcery

Make all relevant branch-creation guidance explain how to recover when the target branch already exists.

New Features:

• Add consistent guidance beneath every relevant git switch -c instruction in bump-leg.py and setup-project.py for handling branches that already exist.

Bug Fixes:

• Prevent printed branch-creation instructions from leaving users without actionable next steps when an earlier operation created the branch.

Enhancements:

• Keep branch guidance wording synchronized across the project and holder tools while preserving all existing command lines.
• Expand coverage to validate printed commands, branch-recovery choices, and real bump/setup workflows.

Tests:

• Add comprehensive tests for existing-branch guidance in bump-leg and setup-project output, including alternate branch names and switching back to retained work.
• Update affected output and wording assertions to account for the new guidance.

[brettheap]

(lane openRepoShape-5, 2026-10-16T12:22Z) @codex review

[sourcery-ai]

Reviewer's Guide

The PR adds a standardized explanation and tested recovery options wherever bump-leg.py and setup-project.py print git switch -c, while preserving every command line and validating behavior against existing-branch scenarios.

Flow diagram for existing-branch recovery guidance

flowchart TD
    A[Tool prints git switch -c] --> B{Branch already exists?}
    B -->|No| C[Create branch and continue]
    B -->|Yes| D[Use another branch name]
    B -->|Branch contains unmerged work| E[Use git switch instead of git switch -c]
    D --> F[New branch starts where the project or holder stands]
    E --> G[Return to existing branch and keep its commits]

Loading

File-Level Changes

Change	Details	Files
Add consistent guidance for handling an already-existing branch beneath every affected git switch -c instruction.	Define a project-worded BRANCH_LEFT sentence in bump-leg.py. Append the guidance to tracking, detached-root, and dry-run bump-leg outputs without changing command lines. Define the holder-worded sentence in setup-project.py and add it to the family command block. Keep the four tool copies synchronized through cross-tool text assertions.	scripts/bump-leg.py setup-project.py tests/test_family_switch_branch_exists.py
Add end-to-end coverage proving the printed commands remain executable and both recovery paths work when a branch was left behind.	Test branch creation when no branch exists, alternate-name creation, and switching back to an existing branch for bump-leg and setup flows. Validate command parsing, output placement, quoting, commit ancestry, and unchanged behavior. Reuse existing fixtures and typing helpers rather than duplicating test infrastructure.	tests/test_branch_left_bump_leg_setup.py
Update output and exact-text regression tests for the newly appended guidance.	Pin the project-worded sentence and update exact remedy and dry-run expectations. Adjust tests that identify the dry-run hint or compare its output tail. Extend the shared wording consistency test to include both new tools.	tests/test_bump_leg_dry_run_tracking.py tests/test_bump_leg_dry_run_truth.py tests/test_bump_leg_paste_lines.py tests/test_family_switch_branch_exists.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#647	Add the agreed branch-already-exists guidance beneath every git switch -c instruction printed by bump-leg.py, using “the project” in place of “the holder.”	✅
#647	Add the same branch-already-exists guidance beneath the family git switch -c instruction printed by setup-project.py, using the agreed “the holder” wording.	✅

Possibly linked issues

• bump-leg.py and setup-project.py: the git switch -c line fails "already exists" when an earlier act left that branch, and nothing says what to do (#607's sentence, in the two tools #607 left) #647: The PR adds the requested BRANCH_LEFT guidance beneath bump-leg.py’s three switch commands and setup-project.py’s family command, with tests.

---

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.

[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-16T12:28:13.794588Z	be1bff9	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: Didn't find any major issues. Bravo.

Reviewed commit: be1bff901b

ℹ️ 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".

[sonarqubecloud]

Quality Gate passed

Issues
0 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 8 hours and 5 minutes by commenting @sourcery-ai review. Upgrade to get a review now.