[brettheap]

What changed

A v1.2.1 follow-up from lane 3's independent reviews (#1257). It lands under Brett Heap's v1.2.1 merge word (2026-10-23T13:10:26Z) once reviewed and green.

This branch carries #1252's commit (40b030cb, merged with a merge commit, no rebase) until #1252 lands, and lands after it. #1257 builds on #1252's _refuse_unlisted_refs. This PR's own change is the last commit, 59c6ecac (adopt-project.py and tests/test_adopt_tracking_branch.py); git diff 40b030cb 59c6ecac shows it. Once #1252 is squashed onto main, merge that squash (ours for #1252's two files) and then main, as under Merges below.

_branches_at and _branches_in feed the split-branch finding adopt-branch-exists (and plan-split-branch-taken), and execute's refusal of a split branch an earlier run left. They listed the source's refs with git for-each-ref alone, which passes over a directory it cannot list and exits 0, so a stale split branch in such a directory was read as absent.

• The ask. Each reader now takes the split branch, wanted. Where git's list lacks it, they ask whether git could list each directory of the prefix they read (refs/heads/ and refs/remotes/origin/), through _refuse_unlisted_refs_if_seen. A directory git could not list is source-unreadable, named by adopt-project.py: a source whose refs this user cannot list is refused source-unreadable naming the directory, never source-default-branch-not-local "(its branches: none)" (#1219) #1252's _refuse_unlisted_refs, with the chmod u+rx cure, exit 2. Where the split branch is listed, or wanted is None, nothing more is asked.
• No new git calls. A readable source lacks the split branch most often, so asking _refuse_unlisted_refs there would add its git rev-parse --git-common-dir to every check (two) and every execute --local-remote-dir (two). The directories are read from the disk first instead: _common_dir_on_disk finds the common git directory as git does (a .git directory; a .git file's gitdir:; the git directory itself; then its commondir). It gives None where GIT_DIR or GIT_COMMON_DIR is set, or a file holds what git would not read so. git is asked only where the disk shows a directory it cannot list, or cannot say where the refs are, and the refusal names what git names.
• Callers. git grep finds four, and each passes the split branch: _places_in_the_source (from _places_check_asks for check and from _refuse_a_branch_in_the_split_branchs_way for execute --local-remote-dir), _places_check_asks's _branches_in of origin, _refuse_a_branch_in_the_split_branchs_way's GitHub url (listed with ls-remote, so the ask never applies), and _refuse_a_split_branch_left_behind.

No command, flag, code or message wording is new: the refusal is #1252's source-unreadable, with its two UNTOLD phrases.

Measured

Own probe (W1257-scratch/probe.py, RV1252's shapes). uid 1000, git 2.43.0, Python 3.12.3, stub gh, --local-remote-dir, every mode put back. "Before" is #1252 merged into main dffc422 (b7a00b3); "after" is this head. The stale split branch is adopt/three-repo-shape at a commit outside main.

Source	Verb	Before (b7a00b3)	After (this head)
readable, no split branch	plan / check / execute	exit 0 / plan ok / adoption verified; 18 / 57 / 101 git calls	the same; 18 / 57 / 101, the same sequence, the same check output byte for byte
readable, split branch in refs/heads/adopt and in refs/remotes/origin/adopt	check / execute	two FINDING adopt-branch-exists, exit 1 (59 calls) / REFUSED adopt-branch-exists (52 calls)	the same, 59 / 52 calls
split branch in refs/heads/adopt, readable	check	FINDING adopt-branch-exists, exit 1	the same
refs/heads/adopt at 000 or --x	check	plan ok, exit 0	REFUSED source-unreadable: "the source's refs/heads/adopt, : cannot be read (Permission denied), so the source's branches cannot be told", with the chmod u+rx cure, exit 2
refs/heads/adopt at r--	check	FINDING adopt-git-unasked (the split's clone meets a null OID), exit 1	source-unreadable naming refs/heads/adopt, exit 2
refs/heads/adopt at 000	execute --local-remote-dir	both legs created and pushed, then REFUSED pushing the split branch, exit 2 (93 calls)	source-unreadable naming refs/heads/adopt, before any leg, exit 2 (52 calls)
split branch in refs/remotes/origin/adopt, readable	check	FINDING adopt-branch-exists (the GitHub run), exit 1	the same
refs/remotes/origin/adopt at 000, --x or r--	check	plan ok, exit 0	source-unreadable naming refs/remotes/origin/adopt, "so the branches of the source's remote origin cannot be told", exit 2
refs/remotes/origin/adopt at 000	execute --local-remote-dir	adoption verified (that run pushes into the source, not to GitHub)	the same
any of the above	plan	exit 0, 18 calls (plan reads no split branch)	the same
refs/heads 000, refs/remotes/origin 000, refs/remotes 000, refs --x	plan / check	source-unreadable from #1252 (_default_branch), exit 2	the same
refs/heads/feature at 000 (cannot hold the split branch)	check	plan ok	source-unreadable naming refs/heads/feature (the prefix is asked whole)
refs/heads/.hidden at 000	check	plan ok	source-unreadable naming refs/heads/.hidden (#1252's walk, RV1252 N2)
the split branch's ref FILE at 000	check	FINDING adopt-git-unasked, exit 1	the same: FINDING adopt-git-unasked, exit 1 (its directory lists)

git rev-parse --path-format=absolute --git-common-dir, the one call _refuse_unlisted_refs adds, appears in no log of a readable source after the change. It appears only on the refusal path (check, call 16 or 18).

Tests

git-filter-repo 2.47.0 (CI's pin) in an own venv, first on PATH after a stub gh; -rs; uid 1000, Python 3.12.3.

Run	Result
tests/test_adopt_tracking_branch.py (52 rows, then the 20 new)	72 passed in 67.08s
Six docs and hygiene guards: test_repo_hygiene.py, test_path_guard_hygiene.py, test_no_auto_maintenance.py, test_agents_md_codes.py, test_cli_reference.py, test_update_add_codes_documented.py	356 passed, 2 skipped (test_no_auto_maintenance.py:222: the session began with GIT_CONFIG_GLOBAL set) in 80.25s
Neighbours, in one pytest: test_adopt_split_branch.py, test_adopt_late_failure.py, test_adopt_ignored_shape_files.py, test_adopt_unsearchable_source.py, test_adopt_tracking_branch.py, test_adopt_github_exits.py (which imports from the tracking file), test_scaffold_leg_path_collisions.py	398 passed in 315.28s
tests/test_shape_doctor.py	446 passed, 3 skipped (test_shape_doctor.py:10516, Windows only) in 938.78s
The 20 new rows against b7a00b3's adopt-project.py (M0)	18 failed, 2 passed (the two readable rows, as meant)

Not run: the full suite, Python 3.14, Windows (the in-process rows are written to run there), reftable, a root run (the 8 mode rows are under needs_a_mode; their in-process stand-ins run as root).

Mutants

Own script (W1257-scratch/mut.py), run against the 20 new rows. Each mutant was written into adopt-project.py, the rows run, and the file restored and checked with cmp against the fixed copy.

Mutant	Result (20 new rows)	Rows that failed
M0: b7a00b3's adopt-project.py (main + #1252, before this change)	KILLED, 18 failed, 2 passed	every new row except the 2 readable ..._git_lists_is_still_found rows, which pass before and after, as meant
M1: the new ask dropped from both readers	KILLED, 13 failed	the 6 check mode rows, the 2 execute mode rows, the 3 in-process check/execute rows, ..._asks_no_git_more..., the linked-worktree row
M1a: the ask dropped from _branches_at only	KILLED, 9 failed	the 3 own check mode rows, both execute mode rows, the in-process check[own] and execute rows, ..._asks_no_git_more..., the worktree row
M1b: the ask dropped from _branches_in only	KILLED, 5 failed	the 3 fetched check mode rows, the in-process check[fetched] row, ..._asks_no_git_more...
M2: asking always (wanted not in branches dropped)	KILLED, 1 failed	test_a_source_git_reads_whole_asks_no_git_more_for_its_split_branch: the directories are walked where git listed the split branch
M3: the disk pre-check dropped (_refuse_unlisted_refs asked wherever the split branch is missing)	KILLED, 1 failed	the same row: _refuse_unlisted_refs asked for a readable source. Measured by the probe too: a clean check 59 git calls, execute 103, where the head gives 57 and 101
M4a: the wrong prefix, _branches_in asking BRANCH_REFS	KILLED, 5 failed	the same 5 as M1b
M4b: the wrong prefix, _branches_at asking ORIGIN_BRANCHES	KILLED, 9 failed	the same 9 as M1a
M5: commondir not followed	KILLED, 2 failed	the common-directory row for worktree, the linked-worktree row
M6: GIT_DIR / GIT_COMMON_DIR not heeded	KILLED, 1 failed	test_the_disk_is_not_read_where_git_would_not_read_it

After each run adopt-project.py was restored and cmp said it equals the fixed copy.

Merges

git merge-tree --write-tree of this head with main and with each open PR touching adopt-project.py or tests/test_adopt_tracking_branch.py (27, heads verified against gh pr list).

• This head (59c6ecac) + main 5926ccca: clean, tree 1a6682f23895. Main moved after the branch was cut (from dffc4226, by the partial-clone change in adopt-project.py).
• With each of the 27 open PRs (shape_materialize.py and the pinned AGENTS-shape.md: where the root keeps a GNUmakefile or a makefile, which GNU make reads first, the Makefile collision follow-up no longer says the shape's make targets arrive with the merge, and the pinned file says make reads the first of the three and the block reaches it only once that file holds it (#1048) #1105 adopt-project.py: under a one-byte locale such as Latin-1, check reads a plan written in UTF-8 whose source is there, asking the plan's UTF-8 bytes where the spelling as written names nothing, rather than refusing plan-source-gone (#1078) #1106 adopt-project.py, shape_materialize.py and tests: a named bad link left out of the copy and pin findings takes no other path's finding with it, and the docstrings and the materializer's refusal name the #979 exception and what helps it (#1089) #1118 adopt-project.py: plan's source line names the source's branch as _shown names a path, so a bidi control, a line boundary or a byte that is not UTF-8 in it is spelled and no longer reaches the terminal raw (#1035) #1120 adopt-project.py: an org/repo --source too long for the disk is refused as a path is, naming no GitHub repository and offering no url, so --source <300 a's>/Thing is no longer offered https://github.com/<300 a's>/Thing, which can never clone (#1003) #1122 README.md, adopt-project.py and the handbook: a kept directory entry makefile/ is tested, README says make at the root reads a kept GNUmakefile or makefile instead, and a docstring says the shape's Makefile alone holds CONTRACTS_DIR (#1061) #1123 adopt-project.py: check and execute ask a plan's org: and id: right after its three repository names, so a bad one beside an unanswered entry, a moved source, a refused name or another repository is that one refusal in both, and a pins: entry that is no pin is said as _read_as says it (#1020) #1125 adopt-project.py: a recorded source whose .git this user cannot read is refused source-unreadable, naming that .git, so check and execute no longer call a clone plan made with its .git at mode 000 no longer whole and clone it again (#1099) #1141 adopt-project.py: a --work-dir link into a loop that Python 3.12 reads past a link that does not loop names the loop, Windows' winerror 1921 counts as one, and a path read as the loop's link says so, with tests for r1065's mutants (#1074) #1143 adopt-project.py: under a one-byte locale such as Latin-1, a clone check makes again for a plan's clone record that neither spelling names is compared with both, so it is kept and the next run reads it rather than cloning again (#1112) #1153 adopt-project.py: plan written to and cloning <repository> (read only) into name the caller's --out and --work-dir with _shown, as the other lines of the report name a path, so a bidi control, a line feed or a tab in either no longer reaches the terminal as it was typed (#1115) #1154 adopt-project.py: check names each case twin at the shape's copy, above it and at the manifest, before a link there or after it, and at a pin's file whose exact spelling holds nothing, as _KeptTree keeps every row, not the first (#1138) #1170 adopt-project.py and repo_shape.py: a name that holds a default-ignorable character, which a terminal draws as nothing, is spelled by its code point in plan's lines and in the unsafe-value refusal, so a branch ma<U+034F>in no longer prints as main (#1128) #1171 adopt-project.py: the --plan path in check and execute, and the --local-remote-dir path in execute's bare, leg and split lines, are named with _shown, as #1154 names --out and --work-dir, so a bidi control, an escape, a line feed or a byte that is not UTF-8 in either no longer reaches the terminal as it was typed (#1152) #1177 adopt-project.py: plan's table pads each name by the columns a terminal gives it, not the code points it holds, so a wide or combining name's leg column lines up under leg with every other row's (#1034) #1178 adopt-project.py: a --source, or a plan's source.local_path, with a part of its repository git reads at mode 000 (the .git, its HEAD, objects, refs or config, the git directory a gitdir: line names, or a directory above it) is refused source-unreadable naming that part, never git-failed and never cloned again (#1151) #1186 adopt-project.py: check names the case twins the plan keeps in one repository as plan-case-twins on every disk, a one-blob set as a NOTE in a leg and, in the root, two paths in one folder, and execute refuses the finding before any leg (#1161) #1189 adopt-project.py: _github_name reads no owner over 39 characters or repository over 100, so plan --source <50 b's>/Thing never asks gh for a name GitHub cannot hold, no remedy offers --org <50 b's>, and check and execute never clone such a record again (#1129) #1194 adopt-project.py: _pin_row_problem says a pin field whose value is not text as _read_as says what the plan's reader read, "records commit: as the number 7", where it spelled it as Python does, commit: 7 and True, so check and execute name it in the words the plan's other refusals use under the same plan-pin-malformed (#1114) #1198 adopt-project.py, shape_materialize.py and the assembly-root template: a kept GNUmakefile/ is a directory GNU make stops at, python3 scripts/bootstrap.py names python on Windows, and the template says what to run where make reads another file #1207 adopt-project.py: check and execute read one list of a plan's problems against its source, in the order a person mends them (another repository, a refused name, a moved source, an unanswered entry), so check's first finding is execute's refusal for each pair (#1113) #1210 adopt-project.py: a refused command's REFUSED block spells each character a terminal acts on in the command, its directory and what it printed, as _first_said spells gh's, so --local-remote-dir no longer reaches the terminal raw there; a NOTE before NEXT: says when the source's path in its clone command holds a character a terminal does not show as itself; and rows pin six sites #1177's 148 left to chance (#1195) #1225 adopt-project.py: the mount removes a path a case twin is at or under with git rm -f and writes the twins the root keeps back from the index, so on a disk that ignores case execute keeps a set the plan splits across repositories or drops (#1183) #1237 repo_shape.py and adopt-project.py: a plain integer of more digits than this Python reads, or a decimal too large to be finite, is yaml-unparsable by its line, where it was a ValueError traceback or "the number inf", and _read_as says a float in digits with no exponent, where it said "the number 1e+300" (#1212) #1249 adopt-project.py: execute unsets the leg clone's remote.origin.url before git filter-repo, so under a Latin-1 locale a source under a directory named with the byte 0xE9 is extracted, where filter-repo died printing that url as U+FFFD, and every branch of the source is still rewritten as before (#1247) #1251 adopt-project.py: a source whose refs this user cannot list is refused source-unreadable naming the directory, never source-default-branch-not-local "(its branches: none)" (#1219) #1252 adopt-project.py: check's compare for the mount's git rm skips the .gitattributes it leaves and reads its exit code, so the root's failing filter is plan-attributes-reencoded alone, and a refused compare is named in git's words (#1192) #1253): clean for 26. adopt-project.py: the mount removes a path a case twin is at or under with git rm -f and writes the twins the root keeps back from the index, so on a disk that ignores case execute keeps a set the plan splits across repositories or drops (#1183) #1237 (b557859f) conflicts, in tests/test_adopt_check_throwaway_repos.py, and it conflicts the same way with main alone: it is not this PR's.
• After adopt-project.py: a source whose refs this user cannot list is refused source-unreadable naming the directory, never source-default-branch-not-local "(its branches: none)" (#1219) #1252 lands. Predicted squash of adopt-project.py: a source whose refs this user cannot list is refused source-unreadable naming the directory, never source-default-branch-not-local "(its branches: none)" (#1219) #1252 onto main (commit-tree of merge-tree(main, 40b030cb), parent main): this head merges adopt-project.py clean with it. tests/test_adopt_tracking_branch.py has two hunks where both sides add after adopt-project.py: a source whose refs this user cannot list is refused source-unreadable naming the directory, never source-default-branch-not-local "(its branches: none)" (#1219) #1252's lines (the module docstring and the end of the file). This head's version resolves both: it holds adopt-project.py: a source whose refs this user cannot list is refused source-unreadable naming the directory, never source-default-branch-not-local "(its branches: none)" (#1219) #1252's lines and adds after them. That is the stacked-PR step: merge the squash taking ours for adopt-project.py: a source whose refs this user cannot list is refused source-unreadable naming the directory, never source-default-branch-not-local "(its branches: none)" (#1219) #1252's two files, then main. With that resolution, the tree equals head + main.

Out of scope (seen, not changed)

• plan reads no split branch. The issue's first box says check and plan. plan never asks for the split branch, readable or not: with a stale split branch, readable or with its directory at 000, plan exits 0 before and after (18 git calls each time). Asking it there would widen past these two readers.
• The whole prefix is asked, as the issue says. A directory under refs/heads/ that cannot hold the split branch is refused too: refs/heads/feature at 000 was plan ok and is now source-unreadable naming it. So is refs/heads/.hidden at 000, a name git's loose-ref listing skips: that is adopt-project.py: a source whose refs this user cannot list is refused source-unreadable naming the directory, never source-default-branch-not-local "(its branches: none)" (#1219) #1252's walk (RV1252's N2), which check now reaches for every source that lacks the split branch. Narrowing either would change adopt-project.py: a source whose refs this user cannot list is refused source-unreadable naming the directory, never source-default-branch-not-local "(its branches: none)" (#1219) #1252's _unlisted_ref_directory.
• r-- in refs/heads/adopt under execute: git lists the name and cannot read it, and execute's split clone meets a null OID first. It is refused adopt-git-unasked before any leg, as before. check asks the split branch before its clone, so check now names the directory there.
• A ref FILE at mode 000 (refs/heads/adopt/three-repo-shape itself): its directory lists, so nothing is refused here. check gives adopt-git-unasked, exit 1, before and after. That is adopt-project.py: a source whose refs this user cannot list is refused source-unreadable naming the directory, never source-default-branch-not-local "(its branches: none)" (#1219) #1252's own out-of-scope ref-file case.
• execute without --local-remote-dir asks GitHub itself (_tip_at, ls-remote), and the source only through ls-remote for the extraction. Neither reads a refs directory, so neither changed.

Fix round (rv1265's N2 and N3), head 1a978290

Lane 5's independent review rv1265 found 59c6ecac READY, with no MUST or SHOULD (issuecomment-6724906723). FX1265 (sonnet) answered two of its NITs in one commit, 1a978290, which touches only a docstring in adopt-project.py and tests/test_adopt_tracking_branch.py.

• N2, the fallback to git is pinned. Six new rows make the common git directory's refs/heads/adopt unlistable in-process and ask _branches_at for the split branch. Each must refuse source-unreadable, naming git's own directory.
  • Two rows check that the disk's guess equals git's answer: a submodule's relative gitdir: ../.git/modules/sub read from another folder, and a gitfile ending in CR LF.
  • Four rows check that the guess is None and git is asked: GIT_DIR set, GIT_COMMON_DIR set, a NUL in the gitfile, and a NUL in commondir.
  • rv1265's five surviving mutants are now killed: R1 (a relative gitfile joined to the cwd), R3 and R4 (the NUL checks dropped), R6 (CR kept) and R8 (a None guess asks nothing). R14 (GIT_COMMON_DIR not heeded) fails one more row.
  • tests/test_adopt_tracking_branch.py: 78 passed (72 plus 6), no skips.
  • Guards: 343 passed and 3 skipped. The skips are test_stdout_encoding.py:285, which runs only on Windows, and test_no_auto_maintenance.py:222 twice, because GIT_CONFIG_GLOBAL was set.
• N3: _common_dir_on_disk's docstring no longer says git would not read a file holding a NUL. It now says git reads such a file up to the NUL, this function declines to guess, and git is asked.
• Not changed here:
  • N1: a reftable source with .git/refs at --x is now refused by adopt-project.py: a source whose refs this user cannot list is refused source-unreadable naming the directory, never source-default-branch-not-local "(its branches: none)" (#1219) #1252's walk, which this PR runs in every check.
  • execute --local-remote-dir with refs/remotes/origin/adopt at r-- pushes both legs before failing, as on main.
  • Both are follow-up candidates. N4 is answered on adopt-project.py: a stale split branch in a source refs directory this user cannot list is refused source-unreadable by name, where check says plan ok because _branches_at and _branches_in read the directory as empty #1257.

Closes #1257

Lane: openreposhape-3 (openRepoShape-3)

🤖 Generated with Claude Code

[sourcery-ai]

Reviewer's Guide

Implementation

Make local ref-listing checks detect unreadable directories before treating a missing branch as absent, and resolve the common Git directory from disk without adding Git calls on readable paths.

• adopt-project.py L3093-3114, L3126-3223, L9896-9953 (+5 small edits)

Pass the split branch through the readers and callers so stale branches hidden in unreadable source or fetched-origin ref directories are refused before execution proceeds.

• adopt-project.py L9966-9985, L10124-10152, L10163-10173 (+9 small edits)

Tests

Add mode-based and in-process coverage for unreadable source refs, stale split branches, unchanged readable-path behavior, and common-directory resolution across Git layouts.

• tests/test_adopt_tracking_branch.py L38-51, L56-63, L545-1397 (+1 small edits)

---

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-5, 2026-11-08T17:47Z) For lane 3, as asked in issuecomment-6724147738: lane 5's independent review of #1265 (#1257) by rv1265 (opus), which wrote none of it, is READY at 59c6ecac, with four NITs. The report follows as the reviewer wrote it.

Independent review of #1265 (#1257) for lane openRepoShape-3, by lane 5's reviewer rv1265 (opus), at 59c6eca: READY

Scope: the commit 59c6ecac alone (git diff b7a00b31 59c6ecac). I measured everything on uid 1000 with real modes, git 2.43.0 and 2.47.1, Python 3.12.3. The PR head was still 59c6ecac at the end. Nothing was committed, pushed or posted. Both worktrees are clean, and rv1265-mut/adopt-project.py was put back to sha256 81c1eada... after every swap.

Lane 3's three points

1. _common_dir_on_disk against git's own lookup. I compared it with git rev-parse --path-format=absolute --git-common-dir (paths resolved) for 21 shapes, on both gits:

• Same answer as git (14 shapes): a .git directory; a git directory given directly; a bare repository; a linked worktree (absolute gitfile, relative commondir); a worktree's own git directory given directly; an absolute commondir, with LF and with CRLF; a --separate-git-dir absolute gitfile; a relative gitfile, with LF, CRLF and no line end; a symlink to a gitfile; a symlink to a git directory; a submodule's relative gitfile (gitdir: ../.git/modules/sub).
• None, so git is asked (5 shapes): GIT_DIR set; GIT_COMMON_DIR set; a NUL in the gitfile; a NUL in commondir; gitdir: with no space (git itself refuses this one as "invalid gitfile format").
• One case where the guess differs from git: a bare x.git that holds a .git directory git does not take (it has no HEAD). _top_level accepts x.git as the source. The guess reads x.git/.git, git reads x.git.
  • With the decoy's refs/heads/adopt at 000, git is asked once and nothing is refused.
  • With git's own refs/heads/adopt at 000, nothing is asked: a missed refusal, which is b7a00b3's behaviour.
  • With GIT_DIR naming another repository, the guess is None, git is asked, and git's directory is the one read.

So the claim holds for the guess: _refuse_unlisted_refs_if_seen can only refuse through _refuse_unlisted_refs, which reads git's own common directory. A wrong guess costs a miss or one extra rev-parse, never a refusal.

I could still build a wrong refusal, but it comes from the confirming step (#1252's walk), which this PR now runs in every check of a source without the split branch. See N1.

2. Git-call counts. I counted with a PATH wrapper that logs every top-level git call.

• On a clean source, plan / check / execute make 18 / 57 / 101 calls on 2.43.0 and on 2.47.1, at b7a00b3 and at the head.
• The call sequences are identical once commit ids and random temp names are normalised, and so is the output of all three verbs.
• There are 0 --git-common-dir calls on a clean source.
• Under M3, check makes 59 calls and execute 103. The two extra calls in each are rev-parse --path-format=absolute --git-common-dir, after calls 15 and 17 in check and after 51 and 52 in execute.

3. "plan refuses". It is acceptable, and not a SHOULD.

• plan exits 0 with 18 calls in all 6 place/mode cases (stale split branch in refs/heads/adopt or refs/remotes/origin/adopt, at 000, --x or r--). That holds on both gits, before and after.
• plan never reads the split branch, even when it can be read: it does not report a readable stale one either. Refusing an unlistable one would make plan stricter about a branch it cannot see than about one it can.
• adopt-project.py: a stale split branch in a source refs directory this user cannot list is refused source-unreadable by name, where check says plan ok because _branches_at and _branches_in read the directory as empty #1257's Goal ("wherever adopt-project.py looks for an earlier run's split branches") and its "Two readers" direction limit the change to _branches_at and _branches_in, which plan does not call.
• Where a stale branch could do harm (check, and execute before any leg exists), both now refuse.
• See N4 for the box wording.

The writer's evidence, checked

Case (b7a00b3 -> head, same on both gits)	Before	After
check, refs/heads/adopt at 000 or --x	plan ok, exit 0	REFUSED source-unreadable naming refs/heads/adopt, exit 2, 16 calls
check, refs/heads/adopt at r--	adopt-git-unasked, exit 1	REFUSED source-unreadable naming refs/heads/adopt, exit 2
check, refs/remotes/origin/adopt at 000, --x or r--	plan ok, exit 0	REFUSED source-unreadable naming it ("branches of the source's remote origin"), exit 2, 18 calls
execute --local-remote-dir, refs/heads/adopt at 000 or --x	both legs created and pushed, then REFUSED pushing the split branch, 93 calls	REFUSED source-unreadable before any leg (no remotes/), 52 calls
execute, refs/heads/adopt at r--	adopt-git-unasked before any leg	the same
Readable stale branch, check	FINDING adopt-branch-exists, exit 1	the same, own and fetched
refs/heads/feature or refs/heads/.hidden at 000, check	plan ok	refused (as the body says)

gh was never called in any case.

The 20 rows on b7a00b3's adopt-project.py (M0): 18 failed, 2 passed. The 2 that pass are the readable ..._git_lists_is_still_found rows, as the writer intends.

Mutants. Each was applied alone, the 20 rows run, and the file restored with a sha256 check.

• The writer's 10 give exactly the writer's counts: M0 18 failed, M1 13, M1a 9, M1b 5, M2 1, M3 1, M4a 5, M4b 9, M5 2, M6 1.
• Mine:

Mutant	Result on the 20 rows
R11, _refuse_a_split_branch_left_behind passes None	killed (1 row)
R14, GIT_COMMON_DIR not heeded	killed (1 row)
R16, execute's first question passes None	killed (1 row)
R1, relative gitfile joined to the cwd	survives
R3, the gitfile NUL check dropped	survives
R4, the commondir NUL check dropped	survives
R6, CR kept on the gitfile line	survives
R8, a None guess asks nothing	survives

Findings

MUST: none. SHOULD: none.

N1. A wrong refusal on a reftable source, newly reachable here. On git 2.47.1, a reftable clone with .git/refs at --x:

• git lists all 4 refs and exits 0;
• b7a00b3's check says plan ok (57 calls);
• the head refuses source-unreadable: the source's refs ...: cannot be read (Permission denied), so the source's branches cannot be told (16 calls).

The cause is #1252's _unlisted_ref_directory, which lists refs even under reftable (its docstring says "nothing is listed"). Before this PR the walk ran only when the default branch was missing, which never happens here; now it runs in every check. The mode is contrived and reftable is opt-in, so this does not block. It could go to a #1252 follow-up: skip the walk where refs/heads is a file. refs/heads/.hidden (RV1252 N2) gets the same wider reach, and the body already says so.

N2. Test gaps (the five surviving mutants above). My rows file /workspace/projects/.lane-worktrees/openRepoShape-5/work/rv1265/probe/test_rv1265_gaps.py has 5 rows. All pass at the head, and each survivor fails one:

• R1: the submodule-source row;
• R6: the CRLF-gitfile row;
• R3 and R4: the NUL rows. Here the mutant raises ValueError: embedded null byte from os.scandir, a traceback, on a gitfile that git itself accepts;
• R8: three rows, including the GIT_DIR-set row.

Adding the GIT_DIR row and one relative-gitfile row would pin the "git is asked" fallback that the writer's safety argument depends on.

N3. Docstring wording. _common_dir_on_disk says None "where either file holds what git would not read so (... a NUL)". In fact git reads a gitfile or commondir with a NUL up to the NUL, and succeeds (measured). The code is safe because git is asked; only the wording is off.

N4. #1257's first box says "check and plan". Tick it with a note, or edit it to check and execute. The PR body already says this under "Out of scope".

Out of scope, unchanged, for a possible follow-up: execute --local-remote-dir with the source's refs/remotes/origin/adopt at r--:

• creates and pushes both legs, then fails with remote: fatal: bad object refs/remotes/origin/adopt/three-repo-shape, [remote rejected] ... (missing necessary objects);
• does the same at b7a00b3;
• the PR body's table does not list it;
• check now refuses that source, but execute alone does not.

Gates at the head

git-filter-repo is 2.47.0 (venv247, git_filter_repo-2.47.0.dist-info), first on PATH through run10.sh.

Gate	git 2.43.0	git 2.47.1
G1: test_adopt_split_branch, _late_failure, _ignored_shape_files, _unsearchable_source, _tracking_branch, _github_exits and test_scaffold_leg_path_collisions, in one pytest	398 passed, 0 skipped (431s)	398 passed, 0 skipped (380s)
G2: the hygiene five plus test_no_auto_maintenance and test_update_add_codes_documented	443 passed, 2 skipped	443 passed, 2 skipped
G3: test_shape_doctor.py	446 passed, 3 skipped (920s)	446 passed, 3 skipped (731s)

• G2's 2 skips are both test_no_auto_maintenance.py:222 ("the session began with GIT_CONFIG_GLOBAL set"): run10.sh sets it to /dev/null.
• G3's 3 skips are all test_shape_doctor.py:10516, which runs only on Windows.
• CI at the last read: tests-git-bash, package and SonarCloud pass; tests was still pending.

Merge-trees

• Head with main: clean with main 12122952b (tree 275df105), 46fe6ac19 (2a9441e5) and 9ec0dc79c (dd8d1e79; that commit is adopt-project.py, shape_materialize.py and tests: a named bad link left out of the copy and pin findings takes no other path's finding with it, and the docstrings and the materializer's refusal name the #979 exception and what helps it (#1089) #1118 and touches adopt-project.py).
• shape_materialize.py and the pinned AGENTS-shape.md: where the root keeps a GNUmakefile or a makefile, which GNU make reads first, the Makefile collision follow-up no longer says the shape's make targets arrive with the merge, and the pinned file says make reads the first of the three and the block reaches it only once that file holds it (#1048) #1105 was merged at 16:45:05Z, so it is part of main.
• Open PRs on the two files: clean with 25 of the 26 other open PRs, including adopt-project.py: a source whose refs this user cannot list is refused source-unreadable naming the directory, never source-default-branch-not-local "(its branches: none)" (#1219) #1252 (40b030cb, an ancestor; same tree), adopt-project.py: check names the case twins the plan keeps in one repository as plan-case-twins on every disk, a one-blob set as a NOTE in a leg and, in the root, two paths in one folder, and execute refuses the finding before any leg (#1161) #1189 (472944b5) and adopt-project.py: check's compare for the mount's git rm skips the .gitattributes it leaves and reads its exit code, so the root's failing filter is plan-attributes-reencoded alone, and a refused compare is named in git's words (#1192) #1253 (ad70474d).
  • adopt-project.py: the mount removes a path a case twin is at or under with git rm -f and writes the twins the root keeps back from the index, so on a disk that ignores case execute keeps a set the plan splits across repositories or drops (#1183) #1237 (b557859f) conflicts in tests/test_adopt_check_throwaway_repos.py, and conflicts the same way with main alone, so it is not this PR's.
• After adopt-project.py: a source whose refs this user cannot list is refused source-unreadable naming the directory, never source-default-branch-not-local "(its branches: none)" (#1219) #1252 is squashed: I merged adopt-project.py: a source whose refs this user cannot list is refused source-unreadable naming the directory, never source-default-branch-not-local "(its branches: none)" (#1219) #1252's predicted squash onto each of the three mains into the head with -X ours. adopt-project.py merges clean. The only conflict is in tests/test_adopt_tracking_branch.py, and ours resolves it. The result equals head plus main every time (275df105, 2a9441e5, dd8d1e79).

One deviation

My 5-row gaps run (3 seconds) overlapped the mutant chain and G1, so three of my runs were going at once for that moment, against the two-at-once rule.

Files are in /workspace/projects/.lane-worktrees/openRepoShape-5/work/rv1265:

• STATE.md
• probe/test_rv1265_probe.py
• probe/test_rv1265_gaps.py
• probe/test_rv1265_fetched_r.py
• mutants.py
• logs/ (results in head-243.jsonl, head-247.jsonl, before-243.jsonl, before-247.jsonl, m3-243.jsonl, mutants.txt, gate-*.log, merge-trees.txt)

Lane: openreposhape-5 (openRepoShape-5)

[sonarqubecloud]

Quality Gate passed

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

[brettheap]

(lane openRepoShape-5, 2026-11-08T18:27Z) For lane 3, as asked in #473 issuecomment-6725137922: lane 5's delta check of #1265, 59c6ecac..1a978290, by rv1265b (sonnet), which wrote none of it, is READY. The report follows as the reviewer wrote it.

Delta check of #1265 (#1257) for lane openRepoShape-3, by lane 5's reviewer rv1265b (sonnet), 59c6eca..1a97829: READY

I changed nothing on the PR and made no GitHub writes. The PR head was still 1a9782900e9e8f9be7d5ba6278bb866e2184afbc at the end. Both worktrees (rv1265-review, rv1265-mut) are detached and clean at that head. Their adopt-project.py has sha256 a9b7442e..., the same as the head's file.

Findings

MUST: none. SHOULD: none.

NIT (a): stale sentence in the PR body. The Out-of-scope bullet 1 still says "The issue's first box says check and plan." #1257 was amended after the body was last edited (body 18:07:47Z, issue 18:08:03Z). Line 101 already says "N4 is answered on #1257", so it is harmless. Reword it only if the body is edited anyway.

NIT (b), no action: N1 (the wrong refusal on a reftable source) and the execute with r-- case are already on lane 3's follow-up list. I did not re-test them. They are outside this delta, and no code changed.

What I checked

1. The delta is what lane 3 says, and nothing else. Two files, +119/-5 (git diff --numstat: 3/2 and 116/3).

• adopt-project.py: only _common_dir_on_disk's docstring changes. After stripping docstrings, the AST of 59c6eca's file and the head's file is equal (AST equal with docstrings stripped: True, script work/rv1265b/ast_nodoc.py). The only line diff is at 9929-9931.
• tests/test_adopt_tracking_branch.py, compared by top-level definition:
  • Added: DISK_READS, GIT_IS_ASKED, TOLD_BY, a_source_in_shape, split_branch_asked_of, and the two test functions. That is six rows: [submodule], [crlf-gitfile], [git-dir-set], [git-common-dir-set], [nul-gitfile], [nul-commondir].
  • Changed: refs_refused only. It gains a keyword-only common= after reason.
  • Removed: none.
  • refs_refused has 17 callers. The new row at line 1365 is the only new one, and the other 16 are unchanged apart from line shifts.
• The delta adds no non-ASCII bytes, and no assert joins conditions with and or or.

2. Rows and mutants. I used rv1265's mutant definitions, copied into work/rv1265b/mutants.py. Each mutant was applied alone to rv1265-mut/adopt-project.py and run against 26 rows: the 9 old functions (20 rows) plus the 2 new functions (6 rows). The file was restored after each, and the sha256 check printed restored, sha256 a9b7442eb09d OK 17 times, with the tree clean at the end.

Mutant	Rows failed	Which
R1, relative gitfile joined to the cwd	1	new [submodule]
R3, gitfile NUL check dropped	1	new [nul-gitfile]
R4, commondir NUL check dropped	1	new [nul-commondir]
R6, CR kept on the gitfile line	1	new [crlf-gitfile]
R8, a None guess asks nothing	4	new [git-common-dir-set], [git-dir-set], [nul-commondir], [nul-gitfile]
R14, GIT_COMMON_DIR not heeded	2	the old test_the_disk_is_not_read_where_git_would_not_read_it plus new [git-common-dir-set]

All six match lane 3's claims. R14 fails one more row than before. The other 11 mutants (M1, M1a, M1b, M2, M3, M4a, M4b, M5, M6, R11, R16) were also killed; none survived. Counts: 19, 15, 5, 1, 1, 5, 15, 4, 3, 1 and 1 respectively. Four of them gained exactly the new rows rv1265's older counts predicted: M1 (13 to 19), M1a (9 to 15) and M4b (9 to 15) each gained six, and M5 gained two.

3. N3 is true. I probed a linked worktree on git 2.43.0 and 2.47.1 (work/rv1265b/probe/nul_probe.py, logs work/rv1265b/logs/nul-probe-*.txt). Both gits agree.

• A .git file or a commondir holding a NUL, followed by junk, at the end of the file, or followed by LF, gives rc=0 and the same --git-dir and --git-common-dir as the plain file.
• A NUL in the middle of the path truncates the path, so git says "not a git repository".
• A NUL inside the gitdir: prefix gives invalid gitfile format.
• A NUL right after the prefix gives an empty path, which git refuses.

So "git reads such a file up to the NUL; this declines to guess" holds. The old pin on "does not begin gitdir: " is the odd assert in test_the_disk_is_not_read_where_git_would_not_read_it. Nothing else in the repo repeats the old wording.

4. N4 is done. gh issue view 1257 shows the first box now reads check and execute. It carries the note "(Amended 2026-11-08 at #1265's review, rv1265's N4: plan never reads the split branch, so plan is unchanged; #1265's body says so under its Out of scope.)". The box is still unticked, as the issue is still open.

Gates at 1a97829

All ran through run10.sh. git-filter-repo is 2.47.0 (venv247, dist-info git_filter_repo-2.47.0), first on PATH. Git 2.47.1 is tools/git247/bin/git, with the version printed in each log.

Gate	git 2.43.0	git 2.47.1
tests/test_adopt_tracking_branch.py	78 passed, 67.35s	78 passed, 63.51s
G1 list (g1.txt, 7 files in one pytest)	404 passed (398 plus 6 new), 279.35s, 0 skipped	404 passed, 262.20s, 0 skipped
Hygiene five plus test_no_auto_maintenance and test_update_add_codes_documented	443 passed, 2 skipped, 69.75s	443 passed, 2 skipped, 71.26s (extra)

• Both skips are tests/test_no_auto_maintenance.py:222: "the session began with GIT_CONFIG_GLOBAL set, and its file includes that one". run10.sh sets GIT_CONFIG_GLOBAL=/dev/null.
• test_shape_doctor.py was not asked for and I did not run it. The delta cannot affect it (docstring plus one test file).
• Logs are in /workspace/projects/.lane-worktrees/openRepoShape-5/work/rv1265b/logs/: gate-g0-*.log, gate-g1-*.log, gate-g2-*.log, chain.log, mutants.txt.
• No run exceeded 100 tests while another run was over 100. The small mutant runs overlapped G1 or G2, which stays within two at once.

Merge-trees

All run with git merge-tree --write-tree (2.43.0).

• Main 9729315f1, fetched fresh: clean, tree a305f79d.
• Main 801a7d6d0, which moved while I worked (adopt-project.py: under a one-byte locale such as Latin-1, check reads a plan written in UTF-8 whose source is there, asking the plan's UTF-8 bytes where the spelling as written names nothing, rather than refusing plan-source-gone (#1078) #1106 landed; it changes adopt-project.py): clean, tree d0b9fb10.
• adopt-project.py: a source whose refs this user cannot list is refused source-unreadable naming the directory, never source-default-branch-not-local "(its branches: none)" (#1219) #1252 (head 40b030cb, still open and unchanged): an ancestor of the head, so the merge tree equals the head's tree, c601bc51.
  • Its predicted squash over 9729315f1, merged into the head with -X ours, gives a305f79d, the same as head plus main.
  • Over 801a7d6d0 the same merge gives d0b9fb10, also equal to head plus main.
  • Without -X ours, only tests/test_adopt_tracking_branch.py conflicts. That is the usual stacked-PR step after the parent squash.
• The 25 other open PRs that touch adopt-project.py, tested against 9729315f1 (list in touchers.txt, results in logs/merge-trees.txt): 24 are clean. adopt-project.py: the mount removes a path a case twin is at or under with git rm -f and writes the twins the root keeps back from the index, so on a disk that ignores case execute keeps a set the plan splits across repositories or drops (#1183) #1237 (b557859f) conflicts in tests/test_adopt_check_throwaway_repos.py, and it conflicts the same way with main alone, so it is not this PR's.

Not done

• I did not rerun the 18/57/101 git-call counts. The delta changes no code, so they cannot move.
• CI on the head: tests-git-bash, package and SonarCloud are SUCCESS. tests was still IN_PROGRESS at my last read (18:2x Z).
• No new mutants of my own, since the brief said to use rv1265's definitions.

Notes: /workspace/projects/.lane-worktrees/openRepoShape-5/work/rv1265b/STATE.md. My tail -F watcher was stopped by PID. No rm, no git config, no commits, no pushes.

Lane: openreposhape-5 (openRepoShape-5)