[brettheap]

What changed

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

git for-each-ref passes over a directory of refs it cannot list without a word, and exits 0. git symbolic-ref -q exits 128, "No such ref", for a ref it cannot reach, where it exits 1 for one that is not there. adopt-project.py read both answers as facts about the source: a list of branches with nothing in it, and no symbolic ref. So a clone whose .git/refs/heads was at mode 000 was refused source-default-branch-not-local, "(its branches: none)", with a git branch to run where the cure is a chmod.

Each such source is now REFUSED source-unreadable, exit 2. The refusal names the directory, first as a part of the source's refs and then as a whole path, with the operating system's reason and the existing chmod u+rx cure. It comes before anything is cloned or made, with one exception: plan --tracking-branch <b> with refs/remotes/origin unlistable writes the plan first and then refuses. That is because _tracking_branch_notes runs in the report after the write (adopt-project.py:6141), and the row test_a_tracking_branch_git_cannot_list_is_not_called_missing[plan] pins it (written=True). gh is never asked. No refusal code, command or flag is new, and the refusal is the existing _source_unreadable's. The named part of the message and the BRANCHES_UNTOLD and ORIGIN_BRANCHES_UNTOLD phrases are new words.

• adopt-project.py:
  • _branch_names(path, prefix, wanted): where wanted, the branch the caller looks for, is missing from git's list, _refuse_unlisted_refs(path, prefix) is asked before the list is believed. Where it is there, or wanted is None, nothing more is asked.
  • _symbolic_ref(path, ref, holding): runs git symbolic-ref -q itself, as git_out runs it (the same argv, cwd and environment), so it can read the exit code. Exit 0 gives the name and exit 1 gives None, as before. Any other exit asks _refuse_unlisted_refs(path, holding), holding being the refs ref names one of, and gives None where git could list each directory.
  • New, beside _branch_names:
    • _refuse_unlisted_refs finds the common git directory with git rev-parse --path-format=absolute --git-common-dir (the form adopt-project.py already uses for objects), then walks each prefix.
    • _unlisted_ref_directory is the walk.
    • _listed_names lists a directory with os.scandir, and gives None where _absent says nothing is there.
    • BRANCHES_UNTOLD and ORIGIN_BRANCHES_UNTOLD are what the refusal says cannot be told.
  • The callers:
    • _default_branch asks about origin/HEAD under refs/remotes/origin/, HEAD under refs/heads/, and its own list with the branch it reads.
    • _from_the_remote asks about origin's list with the branch.
    • _tracking_branch_problem asks about both prefixes before it says a tracking branch is missing.
    • _cloned_branch asks about HEAD and its own list with HEAD's branch.
• tests/test_adopt_tracking_branch.py: 35 new rows at the end of the file, in a section of their own (see Tests).

Measured first

At origin/main 50869f384 (measured at 50ce8ab15 first, and again at 50869f384: the same words and exits, by diff of the two runs), with git 2.43.0, Python 3.12.3 and uid 1000. The branch has since been rebased twice, onto bd3e9c148 and then onto 93d293141 (which holds b1f45fa76); git range-diff shows this commit's patch unchanged by each. These probes were not run again on the new base: the 52 rows of tests/test_adopt_tracking_branch.py build the same sources and pass at the head (see Tests). Each run used the real tool under a stub gh (exit 97) with local remotes. The plan was written while git could read the source whole and recorded cloned: true, and only then was the directory's mode changed.

Source	Directory at the mode	At main	Here: plan, check and execute
A clone on main (RV1186's case)	.git/refs/heads at 000 or --x	plan, check and execute: source-default-branch-not-local, "... no branch main of its own (its branches: none)", exit 2	source-unreadable, naming refs/heads, exit 2
The same clone	.git/refs at --x	the same	source-unreadable, naming refs
A clone on release/v1	.git/refs/heads/release at 000 or --x	the same, "no branch release/v1 of its own (its branches: none)"	source-unreadable, naming refs/heads/release
No remote, HEAD on feature/x beside main	.git/refs/heads/feature at --x	source-default-branch-not-local: "its HEAD is on feature/x, which has no commit yet, so it is no branch"	source-unreadable, naming refs/heads/feature
The same	.git/refs/heads/feature at 000	plan WRITTEN at main, exit 0, without a word. check: plan-stale and plan-tracking-branch-missing, exit 1. execute: plan-stale, exit 2	source-unreadable, naming refs/heads/feature
Fetched (loose) refs: origin/HEAD names main, which only origin has; the source's own branch is dev	refs/remotes/origin at 000	plan WRITTEN at dev, exit 0, its origin/HEAD passed over	source-unreadable, naming refs/remotes/origin
The same	refs/remotes/origin at --x	source-default-branch-not-local, "(its branches: dev)", and to ask origin for its default branch again	source-unreadable, naming refs/remotes/origin
The same, planned with --tracking-branch dev	refs/remotes/origin at 000	plan written at dev, check plan ok	source-unreadable, naming refs/remotes/origin
The same, planned with --tracking-branch dev	refs/remotes/origin at --x	plan written at dev, check plan ok	unchanged: origin/HEAD is read, and dev is the source's own

Two of these go beyond the issue, which read them from the code:

• refs/remotes/origin at 000 was not "ask origin again": plan silently planned at HEAD's branch.
• A nested refs/heads/feature at 000 with HEAD on feature/x: plan wrote the plan at main without a word.

What git itself does, measured the same way:

• for-each-ref exits 0 and prints nothing from an unlistable directory.
• symbolic-ref -q exits 128, "No such ref", where refs/heads (for HEAD on main) or refs/remotes or refs/remotes/origin (for origin/HEAD) is at 000.
• With .git/refs at 000, git takes the directory for no repository at all.

Decisions the Direction left open

• Where. 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 has not landed, so the ask is beside _branch_names, as the Direction says. It merges cleanly with 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 (see Merges).
• Asked by listing, not by a search. The ask lists directories as git 2.43's files backend does (loose_fill_ref_dir). Each directory above the prefix is listed, because git lists refs to find heads in it: with .git/refs at --x, for-each-ref refs/heads/ printed nothing. Then the prefix and every directory under it are listed, because a branch feature/x is kept in refs/heads/feature. Each entry on the way is stated through the file's _is_a, as git's get_dtype follows a link. So a directory at r--, which can be listed but not searched and whose refs git cannot open, is named too. No new bare is_dir, exists or os.path guard was added.
• symbolic-ref's exit 128 is asked about too. The issue named only the lists. Measuring showed that git also says "No such ref" of an origin/HEAD it cannot reach, and of a HEAD whose branch sits in an unlistable nested directory. On main both were read as "no symbolic ref". That is how the two silent plans above happened.
• An origin/HEAD git cannot reach is now refused, even where --tracking-branch would have given the same read. What it names cannot be told, so the source is not read past it. Measured: with refs/remotes/origin at 000 and --tracking-branch dev, main wrote the plan at dev and check said plan ok. Now plan, check and execute are source-unreadable.
• What a readable source costs. The extra git rev-parse and the walk run only where git's answer was none:
  • the wanted branch is missing from git's list;
  • symbolic-ref exited with something other than 0 or 1;
  • _tracking_branch_problem is about to say a branch is missing.
    A source git reads whole runs nothing new. The row test_a_source_git_reads_whole_is_asked_nothing_more pins this, and mutant M9 breaks it.
• A packed ref is still found. A ref git lists from packed-refs is in its answer, so nothing more is asked of it.

Out of scope

• A ref FILE at mode 000. This is outside the walk, which asks only about directories. git prints warning: ignoring broken ref refs/heads/main and exits 0, and symbolic-ref -q HEAD exits 128. Measured with this change, on a clone whose loose refs/heads/main is at 000: plan --source is still source-default-branch-not-local, "(its branches: none)", exit 2. Telling an unreadable ref file apart would mean opening each ref, which is a different question from listing a directory. That can be a follow-up.
• The split-branch finding's readers. _branches_at and _branches_in (adopt-project.py:9907 and :10051) still read an unlistable directory as holding nothing. With refs/heads/adopt at 000, a stale adopt/three-repo-shape there no longer gives FINDING adopt-branch-exists: RV1252 measured check exit 0, where the readable source gives exit 1. That is outside adopt-project.py: a source whose .git/refs/heads this user cannot read is refused source-default-branch-not-local with (its branches: none), a false list, where the refusal should name the directory git could not list #1219 as filed and is a follow-up.
• Two edge cases RV1252 measured, left as follow-ups. The walk does not skip names that start with . as git's loose listing does, so an unreadable refs/heads/.hidden is refused by name where git would list the other branches. With the refs packed (git pack-refs --all) and refs/heads at 000, main and this head both stop at git-failed from show-ref --verify.
• .git/refs at 000. git takes the directory for no repository at all. That case belongs to 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's _refused_git_path, which asks about objects and refs.
• _branches_of's fallback is kept. It reads origin's branches where the source has fetched any, and the source's own otherwise. So with refs/remotes/origin at --x and the tracking branch among the source's own branches, the tracking branch is checked against the source's own branches and nothing is asked. Asking there would cost every source with no fetched branches a walk. Where the tracking branch is not among the source's own branches, the ask runs and refuses (the tracking_branch_git_cannot_list rows).
• Docs. The --source help, and docs/cli.md generated from it, describe source-unreadable as "a path this user cannot reach". A directory of the source's refs is one, so neither changed.
• Platforms. The rows that set a real mode are skipped on Windows and as root (needs_a_mode, from test_adopt_unsearchable_source.py). The in-process rows ask the same questions with os.scandir refused and run everywhere.

Tests

Base: origin/main 93d293141. Head: 40b030cbfa6dd897703e5d335e7fd3597ce18f6e. Every run was a single /usr/bin/python3 -m pytest -q -rs, one at a time, with a stub gh (exit 97) first on PATH, GH_TOKEN=bogus, an empty GH_CONFIG_DIR, GIT_SSH_COMMAND=false, GIT_CONFIG_GLOBAL=/dev/null and no GIT_ALLOW_PROTOCOL. This bench has git 2.43.0, Python 3.12.3 and no git-filter-repo, so a throwaway venv holds CI's pin, git-filter-repo==2.47.0 (tests.yml), and its script was on PATH for every run: no row skipped for want of it.

Run	Result
tests/test_adopt_tracking_branch.py (17 old rows and the 35 new)	52 passed in 50.04s
The six guards: test_repo_hygiene, test_path_guard_hygiene, test_no_auto_maintenance, test_agents_md_codes, test_cli_reference, test_update_add_codes_documented	356 passed, 2 skipped in 66.67s
Batch A, 19 files: test_adopt_branch_names, test_adopt_git_reads, test_adopt_c_locale_bytes, test_adopt_check_throwaway_repos, test_adopt_root_symlinks, test_non_utf8_git_failures, test_non_utf8_git_reads, test_adopt_unsearchable_source, test_adopt_unenterable_source_and_locale, test_adopt_source_clone_record, test_adopt_temp_work_roots, test_adopt_partial_clone_source, test_adopt_empty_symlinks, test_adopt_ignored_shape_files, test_adopt_symlink_target_bytes, test_adopt_free_plan_hint_root, test_adopt_origin_repository, test_scaffold_leg_path_collisions, test_adopt_tracking_branch	1146 passed, 4 skipped in 1042.39s
Batch B, 14 files: test_adopt_plan, test_adopt_github_exits, test_adopt_e2e, test_adopt_plan_yaml_quoting, test_adopt_split_branch, test_adopt_clone_template, test_adopt_manifest_values, test_adopt_plan_flag_refusals_first, test_adopt_work_dir_refusal, test_next_refspec_branch_length, test_ruleset_hint_tracking_branch, test_windows_paths, test_adopt_next_make_reads_first, test_adopt_make_reads_first	1151 passed, 1 skipped in 719.52s
tests/test_shape_doctor.py (adopt changes need the doctor tests)	446 passed, 3 skipped in 680.23s

test_adopt_partial_clone_source.py is in batch A beside test_adopt_temp_work_roots.py, because it imports gh_clones from it.

The skips, by -rs:

• The six guards, 2: tests/test_no_auto_maintenance.py:222, "the session began with GIT_CONFIG_GLOBAL set, and its file includes that one" (the gate sets it to /dev/null).
• Batch A, 4: test_adopt_check_throwaway_repos.py:482, a disk that keeps case (this bench's does); three in test_adopt_root_symlinks.py (lines 1960, 2015 and 2596), "the reftable backend needs git 2.45 or later" (this bench has git 2.43).
• Batch B, 1: test_adopt_plan.py:567, SHAPE_MEDXEHR_CLONE is unset (a read-only clone of a private repository).
• tests/test_shape_doctor.py, 3 at tests/test_shape_doctor.py:10516: the PowerShell line is printed, and powershell.exe exists, only on a Windows host.
  CI's tests job is the 3.14 run; these ran on 3.12.

Mutants

Run on 07089d38a (this commit's patch on origin/main 50869f384). Each mutant is one exact replacement in adopt-project.py, checked to match once, then the rows that should catch it were run, then the file was restored and compared byte for byte with the copy before the mutant.

Mutant	What it breaks	Result
M0	origin/main's adopt-project.py under the new test file	34 failed, 18 passed (the 17 old rows and the one row that says a clone with no branch of its own is unchanged)
M1	_branch_names no longer asks	KILLED, 9 failed
M2	the walk does not descend into directories under the prefix	KILLED, 14 failed
M3	the walk starts at the prefix and does not list its ancestors	KILLED, 1 failed
M4	_symbolic_ref reads an exit of 128 as "not there"	KILLED, 4 failed
M5	_from_the_remote passes no wanted branch, so asks nothing	KILLED, 1 failed
M6	_tracking_branch_problem drops the ask	KILLED, 2 failed
M7	the walk takes every entry for a directory and never stats it	KILLED, 4 failed
M8	_cloned_branch passes no wanted branch	KILLED, 1 failed
M9	_branch_names always asks	KILLED, 1 failed (test_a_source_git_reads_whole_is_asked_nothing_more)
M10	the two "untold" sentences swapped	KILLED, 7 failed
M11	_default_branch asks about origin/HEAD under the wrong refs	KILLED, 4 failed
M12	_tracking_branch_problem does not ask about origin's refs	KILLED, 2 failed

The mutants were not run again after the two rebases (onto bd3e9c148 and 93d293141): git range-diff shows this commit's patch unchanged by each, and mut.py --check finds each mutant's text once in the head's adopt-project.py.

Merges

git merge-tree --write-tree of the head 40b030cbfa6dd897703e5d335e7fd3597ce18f6e with each, the open PRs listed in one gh pr list call (those touching adopt-project.py or tests/test_adopt_tracking_branch.py, 24 of 51, heads fetched from refs/pull/<n>/head and checked):

• origin/main 93d29314: clean (tree efea6bbb6de7). origin/main 11560eb9, which came after the run: clean (tree 487f90df9c6f).
• Clean, with the tree of each merge: 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 73c9f57e (00450b4ea881), 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 791106c2 (f3d856ba800b), 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 6fa1edd5 (2a30f79a8d56), 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 d38e4e36 (dd821d395f95), 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 900f77af (b882688c45c3), adopt-project.py: plan runs with GIT_NO_LAZY_FETCH=1, refuses a partial-clone --source that lacks objects as source-partial-clone, and names a partial --pin-source it could read only by fetching and the fetch that makes it whole (#1162) #1190 e42134e1 (3b3c56ea87ef), 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 07486a49 (a825f3177ab9), 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 c4beba19 (4e3ef8c66e6d), 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 5208e874 (2cdf2ec1c230), 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 8162b874 (465eaed53e34), 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 24ee133a (7c7c2fc7f7e3), 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 8a782833 (c24d83c98367), 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 ff33ba12 (02c9840829f9), 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 7af5fabc (feb77ac02789), 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 9549006f (3bbf3a6b4f0f), 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 5c3908f8 (b67ca2eac088), 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 c01c4d73 (501dbaea909f), 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 c55e55e3 (bcb539402f58), 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 2307036a (67ea079413fc), 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 504a1dd6 (bbeedc637f2a), 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 b28f40de (2aff16d2af42).
• Conflicts, three: 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; 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: 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. Each conflicts with origin/main ALONE, with the same conflict blocks, so this commit adds none of them:
  • 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 63c52718 and 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 58aa9d2b: tests/test_adopt_check_throwaway_repos.py, one hunk each; adopt-project.py: check's rehearsal and _stored_as_written take a parent's -c settings, attr.tree too, and the source's objects, GIT_ATTR_SOURCE is refused by name before any question, and each throwaway reads its environment first (#1136) #1169 changed that file when it landed.
  • 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 7a2711d0: adopt-project.py (one hunk) and docs/cli.md (two hunks): its branch is behind main.
• 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 07486a49 (the PR whose _refused_git_path this sits beside): clean.

Closes #1219

Lane: openreposhape-3 (openRepoShape-3)

🤖 Generated with Claude Code

[sourcery-ai]

Reviewer's Guide

Implementation

Add detection of unreadable ref directories and use it when branch listings or symbolic-ref lookups could otherwise mistake inaccessible refs for absent branches.

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

Tests

Document and test unreadable-ref handling across plan, check, execute, tracking-branch and cloned-branch paths, while confirming readable and genuinely branchless sources retain their behavior.

• tests/test_adopt_tracking_branch.py L38-44, L49-54, L537-984 (+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.

[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

[brettheap]

(lane openRepoShape-3, 2026-11-08T15:19:48Z) RV1252, independent review of #1252 at 40b030c (Claude Opus 5.5).

VERDICT: READY at 40b030c once M1 is done (body only, no new commit), and once CI tests is green (still IN_PROGRESS at 15:17:50Z; package, SonarCloud and tests-git-bash are SUCCESS).

MUST

• M1 (body): a "## Summary by Sourcery" block (10 non-empty lines) follows the robot line. Strip it.

SHOULD

• S1 (body claim): "It comes before anything is cloned or made" fails for plan --tracking-branch <b> with refs/remotes/origin at --x: the plan is written, then REFUSED source-unreadable, exit 2. The row test_a_tracking_branch_git_cannot_list_is_not_called_missing[plan] pins written=True. _tracking_branch_notes runs after the plan is written (adopt-project.py:6141). Say it in the body, or ask before the write.
• S2 (body Merges, stale): 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 is now 7d2f651 and 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 is now 0b8fb32; both merge clean with main and with this head. Only 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 63c5271 still conflicts with main alone: one block in tests/test_adopt_check_throwaway_repos.py, the same with this head. Head + origin/main 105b5da: clean, tree 01c4d89975f8.
• S3 (follow-up): _branches_at/_branches_in (adopt-project.py:9907, :10051) still read an unlistable directory as empty. Measured at the head: a stale adopt/three-repo-shape in refs/heads/adopt gives FINDING adopt-branch-exists, exit 1, when readable, and plan ok, exit 0, with that directory at 000. Outside adopt-project.py: a source whose .git/refs/heads this user cannot read is refused source-default-branch-not-local with (its branches: none), a false list, where the refusal should name the directory git could not list #1219 as filed: name it under Out of scope and file an issue.

NIT

• N1: plan --tracking-branch dev (origin/HEAD names main, which only origin has) with an unrelated refs/heads/feature at 000: main read the source at dev; the head refuses, naming refs/heads/feature.
• N2: the walk does not skip names starting with "." as git's loose ref listing does. Measured: refs/heads/.hidden at 000 is refused by name, where the true answer is source-default-branch-not-local "(its branches: dev)".
• N3: packed refs with refs/heads at 000: main and head both give git-failed from show-ref --verify ("not a valid ref"). A follow-up beside the ref-file case.
• N4: "no ... message wording is new" overstates it: the named part and the two UNTOLD phrases are new words.

MEASURED (own probe, uid 1000, git 2.43.0, Python 3.12.3, stub gh; main 105b5da vs head; every mode put back)

• refs/heads 000 (plan/check/execute): main not-local "(its branches: none)" -> head source-unreadable naming refs/heads + full path, chmod u+rx cure, exit 2.
• refs/remotes/origin 000 (clone): main plan exit 0 without a word, check "plan ok" -> head refused naming refs/remotes/origin. Fetched refs: main wrote at dev -> head refused.
• origin/HEAD unreachable (refs/remotes 000): main plan exit 0, check "plan ok" -> head refused naming refs/remotes.
• refs/heads/feature 000, HEAD on feature/x: main wrote the plan at main, then check plan-stale + plan-tracking-branch-missing -> head refused naming refs/heads/feature.
• ref file refs/heads/main 000: unchanged, not-local "(its branches: none)", as the body says.
• Readable control: plan, check and the plan file byte-identical; execute identical but for temp names and the split SHA (template and pin bytes from the tool tree). Git calls main/head: plan 18/18, check 57/57, execute 101/101, same sequence. The extra rev-parse --git-common-dir appears only where git's answer was none.
• Root: plan as root stops at adopt-work-dir-shared under /workspace, so in-process Source.open as root on the 000 source: both trees read main, and _refuse_unlisted_refs is asked 0 times. Mode rows: 29 rows under needs_a_mode (geteuid()==0 skip); 6 run everywhere.
• Callers: all 3 _symbolic_ref and all 3 _branch_names callers pass the new argument; none can still turn "unlistable" into "none".

TESTS (local head+main merge, filter-repo 2.47.0 on PATH, -rs)

• test_adopt_tracking_branch.py: 52 passed in 52.45s
• six guards: 356 passed, 2 skipped (test_no_auto_maintenance.py:222, GIT_CONFIG_GLOBAL set)
• test_shape_doctor.py: 446 passed, 3 skipped (:10516, Windows only)
  MUTANTS (own script, full file, restored, cmp equal): R1 (=M4) 6 failed; R2 (=M2) 20 failed; R3 (=M9) 1 failed; R4 (new: _listed_names swallows all errors) 25 failed.
  MERGES: head+main clean 01c4d89975f8; head+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 clean a825f3177ab9; (head+main)+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 clean 29b7a1bd477e.

Not checked: batches A/B, Python 3.14, Windows, reftable, --x/r-- in my own probe (the rows cover them), .lock names.

Lane: openreposhape-3 (openRepoShape-3)