[brettheap]

Lane: openreposhape-1 (openRepoShape-1)
Claim: #520 (comment)
Claim: #420 (comment)

What

adopt-project.py check now finds the branch names execute used to fail on after both legs existed, and execute refuses each one before it creates a leg:

• A4 (adopt-project.py check: refuse the branch names execute fails on after both legs exist (case, hideRefs, git's own rules) #520). A branch that is in git's way of the split branch only once case is ignored is plan-split-branch-taken. Examples are Adopt, ADOPT/THREE-REPO-SHAPE and Adopt/Three-Repo-Shape/old beside adopt/three-repo-shape. This holds in the source and on GitHub, on every system, as ruled on 2026-10-12, and the finding says that it holds once case is ignored.
• hideRefs (adopt-project.py check: refuse the branch names execute fails on after both legs exist (case, hideRefs, git's own rules) #520). A local repository's branches are read from its own refs with git for-each-ref, so a branch the source hides with uploadpack.hideRefs or transfer.hideRefs is seen. A clone of the source never gets such a branch, so the finding about it is about the push into the source (execute --local-remote-dir) alone.
• adopt-project.py: --tracking-branch and the plan's tracking_branch: and adopt_branch: are held only to checked_value's alphabet and never asked of git, so a name git refuses (~, a..b, x.lock, a trailing /) passes plan and check and execute dies at the first git command that takes it, after a leg repository exists (git init --bare -b, git checkout -B, or a push to GitHub after both gh repo create calls), and the corrected plan is then refused leg-remote-exists #420. check asks git (git check-ref-format --branch, through scaffold-project.py holds --tracking-branch only to checked_value's alphabet, so a name git refuses as a branch (~, a..b, x.lock, a trailing /) passes --dry-run and, against GitHub, dies at the first git init -b after gh repo create has made all three repositories #283's refuse_bad_branch) about the plan's adopt_branch: and tracking_branch:. The findings are plan-bad-adopt-branch and plan-bad-tracking-branch. plan --tracking-branch refuses a name git will not create as adopt-bad-tracking-branch, and writes no plan.
• L2-1 (Tracking: adopt-project.py, converting an existing repository in place #457, rides along). check holds both names to checked_value's alphabet, as execute does. The finding is unsafe-value, in execute's own words.

Why (repro on main)

Measured on main at bfed143 with git 2.43.0, git-filter-repo a40bce548d2c and Python 3.12.3. Every remote is local, and gh is a stub that refuses every call. The source is three files (src/app.py, docs/spec.md, README.md) in one commit, and <D> is the scratch directory.

python3 adopt-project.py plan --source <D>/Northwind --project Northwind --org testorg \
    --elected-by 'T H' --elected-on 2026-09-02 --out <D>/plan.yaml          # exit 0
sed -i 's|^adopt_branch:.*|adopt_branch: "a..b"|' <D>/plan.yaml
python3 adopt-project.py check --plan <D>/plan.yaml                           # exit 0, `plan ok`
python3 adopt-project.py execute --plan <D>/plan.yaml --yes --local-remote-dir <D>/remotes --work-dir <D>/work
#   exit 2
#   REFUSED extracting the spec leg. THE EXACT COMMAND WAS:
#       git checkout -q -B a..b 0e6cbe2c62e9...
#   fatal: 'a..b' is not a valid branch name
#   NOTHING has been rolled back: `<D>/remotes/Northwind-spec.git` and `<D>/remotes/Northwind-code.git` exist

A source branch adopt hidden by the source's own uploadpack.hideRefs = refs/heads/adopt went the same way. check said plan ok, and execute --local-remote-dir made and pushed both legs before the push of the split failed:

REFUSED pushing the split branch. THE EXACT COMMAND WAS:
    git push -q <D>/Northwind HEAD:refs/heads/adopt/three-repo-shape
remote: error: cannot lock ref 'refs/heads/adopt/three-repo-shape': 'refs/heads/adopt' exists; cannot create 'refs/heads/adopt/three-repo-shape'

transfer.hideRefs failed at the same push, after both legs were made and pushed, but not on the ref lock: the pattern hides refs/heads/adopt/three-repo-shape from the push as well, and git refused it with ! [remote rejected] HEAD -> adopt/three-repo-shape (deny updating a hidden ref).

case, on bfed143	plan	check	execute --local-remote-dir	left behind
adopt_branch: edited to a..b, x.lock, ~ or a/	n/a	exit 0, plan ok	exit 2 at the extraction's git checkout -B	both leg repositories; the corrected plan into the same directory: REFUSED leg-remote-exists
adopt_branch: or tracking_branch: edited to a=b, or adopt_branch: to a,b (L2-1; the source holds a branch a=b)	n/a	exit 0, plan ok	exit 2, REFUSED unsafe-value	nothing
a source branch adopt hidden by uploadpack.hideRefs or transfer.hideRefs	exit 0	exit 0, plan ok	exit 2 at the push of the split	both legs, pushed
a source branch Adopt, ADOPT/THREE-REPO-SHAPE or Adopt/Three-Repo-Shape/old (A4)	exit 0	exit 0, plan ok	exit 0 on Linux, adoption verified. #457 reports macOS and Windows making both legs before git refused	n/a

#420's table, measured again row by row on bfed143. #283, #479 and #181 changed this area after #420 was filed.

#420 row	on bfed143	already fixed?
--tracking-branch a..b, ~, x.lock, a/, a//b, .a	plan exit 0 with a NOTE that the source has no such branch. check exit 1, plan-tracking-branch-missing. execute refused before any leg, nothing left	The refusal before any leg came with #479 (56713e2, PR #493), as plan-tracking-branch-missing. plan still wrote the plan, and nothing named git's rule: fixed here.
plan's tracking_branch: edited to "a..b", "x.lock", "~" or "a/"	check exit 1, plan-tracking-branch-missing. execute refused before any leg, nothing left	Yes, by #479 (56713e2), under that code. Here it is plan-bad-tracking-branch, in git's words, and not also plan-tracking-branch-missing.
plan's adopt_branch: edited to "a..b", "x.lock", "~" or "a/"	check plan ok. execute exit 2 at git checkout -B, both leg repositories left. Since #420 was filed the refusal names the failed command, where #420 saw nothing on stderr	No: fixed here.
main and adopt/ok (controls)	adopt	n/a
the plan corrected, the same --local-remote-dir	REFUSED leg-remote-exists after an adopt_branch: row. After a tracking_branch: row there is nothing to meet	Fixed here for adopt_branch:, by #479 for tracking_branch:.
--tracking-branch a..b, GitHub mode, stub gh	plan exit 0. execute refused plan-tracking-branch-missing before any gh call (0 calls)	Yes, by #479 (56713e2). plan now refuses it.

#283 (6c2a371, PR #355) put branch_problem and refuse_bad_branch into scripts/shape_materialize.py, and asked them from the scaffold and the family holder only. #181's commits (3ef059c, PR #314, and b8b7062, PR #518) ask git about a tracking branch only when the project's loader misreads it (_a_branch_git_creates), and none of these rows is misread.

How

• The two names (adopt-project.py: --tracking-branch and the plan's tracking_branch: and adopt_branch: are held only to checked_value's alphabet and never asked of git, so a name git refuses (~, a..b, x.lock, a trailing /) passes plan and check and execute dies at the first git command that takes it, after a leg repository exists (git init --bare -b, git checkout -B, or a push to GitHub after both gh repo create calls), and the corrected plan is then refused leg-remote-exists #420, L2-1). _branch_name_refusal(plan, key, default, code) reads each name as execute reads it in _checked_plan_values: the constant ADOPT_BRANCH or main where the key is absent, and str of what the file holds otherwise. It holds the name to checked_value first, which gives unsafe-value in execute's own words, and otherwise asks git with refuse_bad_branch under the key's own code. _branch_name_findings asks the split branch first, then the tracking branch, the order _checked_plan_values asks them. Their remediation is said once. It is checked_value's for the alphabet; for git's verdict it is a sentence about the plan's key, in place of the helper's "pass a branch name", which is worded for a flag.
• Where in _entry_findings. The two name findings come after the project's validator (adopt-project.py and scaffold-project.py accept values the new project's own validate-manifest.py refuses (a blank --elected-by or --reference, --elected-on 2026-W41-6 or 20261011 on Python 3.11+, --org test+org, a plan's visibility: secret), so adoption verified or a scaffold exit 0 is followed by a failed first bootstrap; and plan admits a 251-255-character --project that check refuses #261) and right before plan-tracking-branch-missing (adopt-project.py: a source whose default branch is not main is adopted with both legs pushed, then its pull request is refused (--base main), and the printed way out repeats --base main #479). So a value's name is judged before its existence, in the order execute asks the two names.
• One finding per cause. A name outside the alphabet is not asked of git. A tracking branch with a name finding is not also plan-tracking-branch-missing. _check_split_branch asks nothing about a split branch with a name finding, so adopt_branch: "a/" beside a source branch a is one finding, not two.
• execute still refuses unsafe-value first, in _checked_plan_values, now in the same words as check's finding. It refuses git's verdict among check's other findings, in _refuse_what_check_finds. Both happen before any leg exists.
• plan asks refuse_bad_branch("adopt-bad-tracking-branch", ...) right after checked_value on --tracking-branch, or on the source's default branch when the flag is not given. Its --help says so, and docs/cli.md is regenerated.
• A4. _in_the_way compares through path_overlap, as a leg's mount path is compared. It returns (name, commit, aside), with CASE_ASIDE for a name that is in the way only once case is ignored. Such a finding does not quote git's ref-lock words, which are not measured on a disk that ignores case. It says instead that git keeps each branch as a file named after it, that such a disk keeps two paths that differ only by case as one, and that check and execute refuse the pair on every system. SPLIT_BRANCH_TAKEN_REMEDIATION names the case rule too.
• hideRefs.
  • _branches_at reads a local path's refs with git for-each-ref (what a push into it meets), and any url with git ls-remote --heads, unchanged.
  • _branches_a_clone_gets is the ls-remote listing, which is what _extract_leg's git clone gets.
  • _places_in_the_source is the source as check and execute --local-remote-dir ask it. Branches a clone gets are about either run; branches the source hides are a second place, about the push alone.
  • Without --local-remote-dir, execute asks the extraction about the branches a clone gets. On main it read the source's own refs there, and refused a hidden branch in words about a git filter-repo that never meets it.
  • _refuse_a_split_branch_left_behind reads the source's own refs under --local-remote-dir, so that an earlier split branch the source hides, which check now finds, is refused too. _tip_at keeps the old git ls-remote <url> <ref> for any other url.
  • _pushed_in_every_mode keeps asking git ls-remote, as execute --local-remote-dir asks the tracking branch (unchanged behaviour).

After this change, on the same rows: plan --tracking-branch a..b (and ~, x.lock, a/, a//b, .a) exits 2 with adopt-bad-tracking-branch and writes nothing. A hand-edited name is one check finding, and execute exits 2 with that finding and makes no leg. The corrected adopt_branch: plan adopts into the same --local-remote-dir. Adopt, a hidden adopt (either knob) and a=b are each found by check and refused by execute before any leg. The controls still adopt.

Tests

All new tests live in tests/test_adopt_branch_names.py (new, 22 tests) and tests/test_adopt_split_branch.py (43 to 53 tests together with tests/test_adopt_tracking_branch.py). That is 32 new test ids. Two existing tests gained a parameter and are renamed: test_a_branch_in_gits_way_on_github_is_refused_in_the_pushs_words[in-the-way] and test_a_source_branch_in_the_way_is_refused_and_runs_once_it_is_gone[seen].

• test_adopt_branch_names.py: plan refuses each of adopt-project.py: --tracking-branch and the plan's tracking_branch: and adopt_branch: are held only to checked_value's alphabet and never asked of git, so a name git refuses (~, a..b, x.lock, a trailing /) passes plan and check and execute dies at the first git command that takes it, after a leg repository exists (git init --bare -b, git checkout -B, or a push to GitHub after both gh repo create calls), and the corrected plan is then refused leg-remote-exists #420's six names. check finds each hand-edited name once, for both keys. check holds both keys to the alphabet, with a name git creates and a deleted key as controls. Two bad names are found in one run, with the remediation said once. execute refuses before any leg, word for word. End to end, adopt_branch: "a..b" makes no leg and the corrected plan adopts into the same --local-remote-dir.
• test_adopt_split_branch.py: the three A4 names in the source, and Adopt on GitHub. A branch hidden by uploadpack.hideRefs or transfer.hideRefs is found and refused under --local-remote-dir, and does not stop a GitHub run. An earlier split branch the source hides is adopt-branch-exists in check and in execute. End to end, a hidden adopt is refused and the run adopts once the branch is deleted.

Two existing tests pinned the behaviour this changes, and now pin the new one:

• tests/test_adopt_plan_yaml_quoting.py: test_plan_records_a_branch_git_will_not_create_as_on_main is now test_plan_refuses_a_branch_git_will_not_create_in_gits_words. plan --tracking-branch ~ exits 2 with adopt-bad-tracking-branch and writes no plan. It is still never refused as adopt-manifest-misread, which was that test's point (rv181f's H1).
• tests/test_adopt_template_values.py: in PRINTED, the row adopt_branch-surrogate (adopt_branch: "adopt/x\ud800") now expects check to exit 1 with FINDING unsafe-value: adopt_branch is where it expected plan ok. That row was L2-1 itself. execute still refuses it as unsafe-value, and check still prints the value spelled under WHAT WILL HAPPEN.

Revert table. Each part was reverted alone in a scratch clone, and the three branch files were run there. Unreverted, 75 of 75 pass. The two updated tests were run under the first two reverts as well, and pass unreverted.

reverted	tests that fail
plan's refuse_bad_branch	7: test_plan_refuses_a_tracking_branch_git_will_not_create[*] (6), and the updated test_plan_refuses_a_branch_git_will_not_create_in_gits_words
the name findings in _entry_findings	17: every test_adopt_branch_names.py test but the six plan ones (16), and the updated test_check_prints_a_hand_edited_value_spelled[adopt_branch-surrogate]
no plan-tracking-branch-missing beside a name finding	5: test_check_finds_a_name_git_will_not_create_once[*-tracking-branch] (4), test_check_holds_both_names_to_the_alphabet_execute_holds_them_to[tracking_branch]
_check_split_branch skipping a bad name	1: test_check_finds_a_name_git_will_not_create_once[a/-adopt-branch]
case-folded _in_the_way	4: test_a_branch_in_gits_way_of_the_split_branch_is_taken[Adopt], [ADOPT/THREE-REPO-SHAPE], [Adopt/Three-Repo-Shape/old], test_a_branch_in_gits_way_on_github_is_refused_in_the_pushs_words[once-case-is-ignored]
the case wording	the same 4
for-each-ref for a local path	4: test_a_branch_the_source_hides_is_taken_where_the_split_is_pushed[uploadpack], [transfer], test_an_earlier_split_branch_the_source_hides_is_found_and_refused, test_a_source_branch_in_the_way_is_refused_and_runs_once_it_is_gone[hidden]
a hidden branch as the push's alone	2: test_a_branch_the_source_hides_is_taken_where_the_split_is_pushed[*]
GitHub run: the extraction asks what a clone gets	2: test_a_github_run_is_not_refused_for_a_branch_the_source_hides[*]
_refuse_a_split_branch_left_behind reading the source's own refs	1: test_an_earlier_split_branch_the_source_hides_is_found_and_refused

Every new test fails under at least one revert. Before the change, all 32 new ids failed on bfed143.

Both modes, on head aee12f2, dirty 0. The set is 71 test files: the 70 that run adopt-project.py (the brief's grep -l -E 'adopt-project|adopt_project' tests/*.py, plus the 18 files that run it through conftest's ADOPT; tests/test_shape_doctor.py and tests/test_scaffold_leg_path_collisions.py are among them), and tests/test_cli_reference.py, added because docs/cli.md changed.

• with git-filter-repo on PATH: 5744 passed, 13 skipped, in three chunks, each EXIT=0
• with it hidden (PATH=<stub gh>:/usr/local/bin:/usr/bin:/bin): 5429 passed, 328 skipped, in three chunks, each EXIT=0

A first run on the commit before aee12f2 failed only the two existing tests above, which pinned the old behaviour; they are updated in this commit.

Main has moved since: v1.0.0 is tagged, and main was 2247dbf when this was measured, which also changes tests/conftest.py and tests/test_adopt_plan_yaml_quoting.py. git merge-tree of this head with 2247dbf is clean, tree 45b18ba3. On that merge, the four test files this PR changes and tests/test_adopt_tracking_branch.py, plus tests/test_agents_md_codes.py, tests/test_repo_hygiene.py, tests/test_readme_sections.py, tests/test_cli_reference.py and tests/test_clone_just_pushed.py, with git-filter-repo on PATH: 882 passed, EXIT=0. Main is now bbcfd34. git merge-tree of this head with it is clean too; the only file both sides change is docs/cli.md, in different hunks, and CI's test_cli_reference.py checks the merged file.

Windows

• Newline emulation. The new tests ran under a pytest plugin kept outside the repository, which makes text-mode Path.write_text and text-mode subprocess stdin write \r\n. Its header shows Path.write_text('a\nb\n') wrote b'a\r\nb\r\n' and stdin 'x\ny\n' arrived as b'x\r\ny\r\n'. tests/test_adopt_branch_names.py and tests/test_adopt_split_branch.py gave 69 passed, the end-to-end tests included.
• Plan edits and config. Every plan edit in the new tests is bytes in and bytes out, so the plan stays LF as plan wrote it. The hideRefs lines are appended to the source's .git/config with newline="\n".
• Names on disk. The branches the tests create are Adopt, ADOPT/THREE-REPO-SHAPE, Adopt/Three-Repo-Shape/old, adopt, adopt/three-repo-shape/old, lane-3/shape+fix@eagle, a=b and a, and all are legal on NTFS. Each is created in a source that holds no case twin of it. The names git refuses (a..b, ~, x.lock, a/, a//b, .a, a:b) are only ever plan values.
• Case-insensitive disks. This is reasoned, not measured: a disk that keeps case and ignores it (APFS, NTFS) keeps a branch's file under the case it was created with, so for-each-ref and ls-remote list a case twin under that name. _refuse_a_split_branch_left_behind asks the exact name, so a twin is refused as plan-split-branch-taken there, as on Linux. Nothing was run on macOS or Windows here; tests-macos and tests-windows run these tests.

Not in this PR

• A tracking branch the source hides. _refuse_a_tracking_branch_the_remote_lacks still asks git ls-remote under --local-remote-dir. So execute refuses, before any leg, a tracking branch the source hides with uploadpack.hideRefs, which check passes. This was measured after the change, with --tracking-branch develop and develop hidden. It is a refusal in the safe direction, and it is listed for Tracking: adopt-project.py, converting an existing repository in place #457.
• A split branch name the source hides. A source whose transfer.hideRefs or receive.hideRefs hides the split branch's own name (refs/heads/adopt, with no branch in the way) passes check. execute --local-remote-dir then makes both legs, and the push of the split is denied as a hidden ref. This was measured after the change, and it is listed for Tracking: adopt-project.py, converting an existing repository in place #457. A pattern that hides a branch in the way hides the split branch with it (transfer.hideRefs = refs/heads/adopt beside a branch adopt): check now names adopt in the words of git's ref lock, where git's push would say deny updating a hidden ref, and once adopt is deleted the run meets the case above.
• A bare YAML value for the split branch. A hand-edited bare adopt_branch: true or adopt_branch: 007 checks ok and adopts onto a split branch True or 7 without a word (measured; ~ and null fall back to the default). This is the YAML-scalar question scaffold-project.py writes --id and --tracking-branch into project.yaml unquoted, so --id null or --id true scaffolds a project whose first bootstrap fails manifest-id, and --tracking-branch true, 007 or null puts the clone's legs on True, 7 or main with no upstream: #181's defect on the scaffold side, beside #225 #258 asks of the manifest's values, and it is listed for Tracking: adopt-project.py, converting an existing repository in place #457.
• Other tools. scaffold-project.py and family.py are scaffold-project.py holds --tracking-branch only to checked_value's alphabet, so a name git refuses as a branch (~, a..b, x.lock, a trailing /) passes --dry-run and, against GitHub, dies at the first git init -b after gh repo create has made all three repositories #283's (PR scaffold-project.py and family.py: --tracking-branch is asked of git check-ref-format --branch before anything exists, so ~, a..b, x.lock and a/ are refused under --dry-run and no longer die at the first git init -b after gh repo create has made the repositories (#283) #355) and are untouched.
• GitHub and case. How GitHub's own storage treats two branch names that differ only by case was not measured. The ruling refuses the pair there as everywhere.

Known limits

• The case rule refuses on Linux a pair git holds there. That is the 2026-10-12 ruling: one plan is not good on one machine and refused after both legs exist on another.
• For a plan whose two names git accepts, check now runs git check-ref-format --branch three more times (twice in _entry_findings, once in _check_split_branch), and execute runs it twice more. Each run is asked of no repository, from an empty temporary directory, as scaffold-project.py holds --tracking-branch only to checked_value's alphabet, so a name git refuses as a branch (~, a..b, x.lock, a trailing /) passes --dry-run and, against GitHub, dies at the first git init -b after gh repo create has made all three repositories #283's helper does.
• A hidden branch is told from a visible one by comparing two listings of the source, for-each-ref and ls-remote. A local path is told from a url by remote_is_a_path, as elsewhere in this file.

Closes #520
Closes #420

🤖 Generated with Claude Code

Summary by Sourcery

Prevent adoption runs from partially progressing by validating branch names and detecting hidden or case-insensitive branch conflicts before any leg is created.

New Features:

• Validate adoption and tracking branch names against Git's branch naming rules during planning, checking, and execution.
• Detect case-insensitive branch conflicts and branches hidden by repository ref settings before adoption creates or pushes leg repositories.

Bug Fixes:

• Prevent invalid or conflicting branch configurations from creating partial adoption results before execution fails.
• Ensure locally hidden branches and previously left-behind split branches are detected when validating local-remote runs.

Enhancements:

• Align check findings and execute refusals for unsafe and invalid branch names, while avoiding duplicate or secondary findings.
• Preserve the distinction between branches visible to clones and branches encountered by pushes into local repositories.

Documentation:

• Update CLI documentation to describe validation of tracking branch names during planning.

Tests:

• Add coverage for invalid branch names, unsafe values, case-insensitive conflicts, hidden refs, and pre-leg execution refusals.
• Update existing tests for the new planning and validation behavior.

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

[sourcery-ai]

Reviewer's Guide

The PR makes branch-name and split-branch conflict validation match the failures execute can encounter, ensuring check reports them and execute refuses them before creating legs, while correctly handling case collisions and refs hidden from clone listings.

Sequence diagram for preflight branch validation before execution

sequenceDiagram
    participant User
    participant Check as check
    participant Execute as execute
    participant Git
    participant Source
    participant Legs as Leg repositories

    User->>Check: check(plan)
    Check->>Git: refuse_bad_branch(adopt_branch)
    Check->>Git: refuse_bad_branch(tracking_branch)
    Check->>Source: Inspect split-branch conflicts
    Check-->>User: Findings or plan ok

    User->>Execute: execute(plan)
    Execute->>Execute: _checked_plan_values()
    Execute->>Git: refuse_bad_branch(...)
    alt Any preflight finding
        Execute-->>User: Refuse before creating legs
    else Plan passes
        Execute->>Legs: Create and push both legs
        Execute->>Source: Push split branch
    end

Loading

File-Level Changes

Change	Details	Files
Validate both plan branch names before execution and align check, execute, and plan refusal behavior.	Added shared branch-name validation using the existing safe-value alphabet and Git's check-ref-format rules. Added distinct findings for invalid split and tracking branch names, with duplicate remediation suppression and precedence over missing-branch checks. Made execute refuse the same invalid names before creating any leg, and made plan --tracking-branch reject invalid names without writing a plan. Expanded tests for invalid names, unsafe values, finding order, and no-side-effect execution; updated CLI documentation and existing expectations.	adopt-project.py docs/cli.md tests/test_adopt_branch_names.py tests/test_adopt_plan_yaml_quoting.py tests/test_adopt_template_values.py
Detect split-branch conflicts using case-insensitive path overlap and distinguish local repository refs from refs visible to clones.	Detect branches conflicting only by case and report them consistently on all systems with dedicated remediation wording. Read local destination refs via git for-each-ref so hideRefs branches are found before a push, while retaining git ls-remote for clone-visible refs and remote URLs. Model extraction and push destinations separately, preventing hidden source branches from incorrectly blocking GitHub-mode extraction. Check hidden existing split branches against the source's own refs before reruns. Added coverage for case clashes, uploadpack.hideRefs and transfer.hideRefs, GitHub/local mode differences, and hidden leftover split branches.	adopt-project.py tests/test_adopt_split_branch.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#420	Have plan ask git whether --tracking-branch is a valid branch name and refuse invalid names before writing a plan.	✅
#420	Have check report invalid tracking_branch: and adopt_branch: plan values—including their execution defaults—and ensure invalid names are not reported as valid plans.	✅
#420	Have execute reject invalid tracking and adopt branch names before creating leg repositories, using the shared git branch-name validation helper.	✅
#520	Have check detect split-branch conflicts that differ only by case, so check and execute refuse the conflicting branch pair on every system before creating legs.	✅
#520	Read a local repository’s own refs when checking branches that a push will encounter, so branches hidden by hideRefs are detected and refused before any legs are created.	✅
#520	Validate adopt_branch and tracking_branch against both execute’s checked_value alphabet and Git’s branch-name rules, and refuse invalid tracking-branch options during plan creation.	✅

Possibly linked issues

• adopt-project.py: --tracking-branch and the plan's tracking_branch: and adopt_branch: are held only to checked_value's alphabet and never asked of git, so a name git refuses (~, a..b, x.lock, a trailing /) passes plan and check and execute dies at the first git command that takes it, after a leg repository exists (git init --bare -b, git checkout -B, or a push to GitHub after both gh repo create calls), and the corrected plan is then refused leg-remote-exists #420: PR implements issue adopt-project.py: --tracking-branch and the plan's tracking_branch: and adopt_branch: are held only to checked_value's alphabet and never asked of git, so a name git refuses (~, a..b, x.lock, a trailing /) passes plan and check and execute dies at the first git command that takes it, after a leg repository exists (git init --bare -b, git checkout -B, or a push to GitHub after both gh repo create calls), and the corrected plan is then refused leg-remote-exists #420’s branch-name checks: plan rejects invalid tracking names, while check and execute reject invalid plan branch names before creating legs.
• adopt-project.py check: refuse the branch names execute fails on after both legs exist (case, hideRefs, git's own rules) #520: The PR implements adopt-project.py check: refuse the branch names execute fails on after both legs exist (case, hideRefs, git's own rules) #520’s fixes: case-folded branch-conflict checks and local-ref inspection that detects hideRefs branches before leg creation.

---

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]

@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-15T11:23:03.595697Z	aee12f2	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. You're on a roll.

Reviewed commit: aee12f2980

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