[brettheap]

What

The four other pinned callers of find_repo_root, which #1146 left as they were (its Known limits): the assembly root's scripts/bootstrap.py, and the family holder's validate-family.py, bootstrap.py and siblings.py. Also the doctor's members row over a holder whose own .git cannot be read.

Was stacked on #1147 (base fix/1146-root-git-unreadable-not-drift, whose head was b75babee when this was measured and reviewed). #1147 has landed, as its squash 51a9c5f1 on main, and this branch was restacked onto main by real merges, with its own change unchanged (see "Restacked after #1147 landed"). This PR is outside v1.2.0 by Brett Heap's ruling of 2026-10-21T10:32:04Z ("leave the follow-ups out of v1.2.0"). It lands after the tag, on a later word.

Measured in a scaffold's recursive clone and a family holder, with base b75babee (#1147's head then) and this head, on Python 3.12.3. It was also measured under a 3.14-like sitecustomize, in which Path.is_file, is_dir, exists and is_symlink answer False to any OSError. Each tool ran from the root, as make runs it.

Tool	.git a link into a folder at 000	.git a directory at 000	readable
assembly bootstrap.py, base	3.12: PermissionError traceback, exit 1. Shim: REFUSED not-a-git-repo: no .git found at or above <root>, exit 2	step (a) says no gitlink recorded; leaving as is of each leg. Then pins refuses git-repo-unreadable and bootstrap REFUSED, exit 2	bootstrap ok
assembly bootstrap.py, head	REFUSED git-repo-unreadable: .git: cannot be read (Permission denied) and the chmod cure, exit 2, no traceback, nothing on stdout, both Pythons	the same refusal, before anything is placed	bootstrap ok
validate-family.py (and --no-members), base	3.12: traceback, exit 1. Shim: not-a-git-repo, exit 2	REFUSED gitlinks-unreadable over git's not a git repository, with the remedy to ask git status, exit 2	family ok
validate-family.py (and --no-members), head	REFUSED git-repo-unreadable: .git: cannot be read (Permission denied), exit 2, both Pythons	the same	family ok
family bootstrap.py, base	3.12: traceback, exit 1. Shim: not-a-git-repo, exit 2, with or without --no-fetch --skip-members	plain: FETCH INCOMPLETE (git exit 128) with the advice to set SHAPE_LEGS_TOKEN, each member fails its pins, family bootstrap FAILED, exit 1. With --no-fetch --skip-members: family bootstrap ok, exit 0, over a run that read nothing	family bootstrap ok
family bootstrap.py, head	REFUSED git-repo-unreadable: .git: cannot be read (Permission denied), exit 2, both Pythons, with or without the flags	the same, with or without the flags	family bootstrap ok
siblings.py (plain and --dry-run), base	3.12: traceback, exit 1. Shim: not-a-git-repo, exit 2	places every member, siblings ok, exit 0; the holder's branch shown ?	siblings ok
siblings.py (plain and --dry-run), head	REFUSED git-repo-unreadable: .git: cannot be read (Permission denied), exit 2, both Pythons	unchanged, by design: places every member, exit 0	siblings ok
the doctor over the holder, base	3.12: INVALID (family). The family row says crashed ... PermissionError, and members says .git: cannot be read through run_checks' generic handler. Shim: DRIFTED (a member is not at its pin), members says checked out at ?	DRIFTED (a member is not at its pin) on both Pythons; family refuses gitlinks-unreadable	COMPLIANT
the doctor over the holder, head	INVALID (family), both Pythons. members: FINDING .git: cannot be read (Permission denied), so no gitlink is read and no member is compared with its pin, NEXT this doctor again, WHY the chmod cure. family: the project's own scripts/validate-family.py refuses (exit 2): REFUSED git-repo-unreadable: .git: cannot be read (Permission denied)	the same	COMPLIANT

The doctor's other family rows (manifest-kinds, shape-currency, agent-files) were ok in every state, on both sides. placement is unchanged (placement is n/a for a holder).

Lane 1's ruling. The family bootstrap's new refusal under --no-fetch --skip-members over a .git directory at 000 is ACCEPTED. Base said family bootstrap ok there, over a run that read nothing. Head refuses git-repo-unreadable, exit 2, as the other tools that read the holder's repository through git do.

The gate's regression, fixed in the test's fixture. Lane 1's gate found tests/test_validate_family_unreadable.py failing 6 of 53 at 05e6ab0f, where base passes all 53.

• What failed. Each row expects REFUSED member-unreadable: members/IRRS/.git: cannot be read (Permission denied), and got REFUSED git-repo-unreadable: .git: cannot be read (Permission denied).
• The tool was right and the fixture was stale.
  • Those rows run validate-family.py's main in process after refused_stat(monkeypatch, ".git"). That call refuses the stat of every path named .git: the holder's own as well as the member's.
  • On base, only find_repo_root asked the holder's .git, and the file's gate() stubs it to answer the holder.
  • This PR's _run_checks asks _refuse_an_unreadable_root(start) first. The stub did not cover it, so it met the holder's refused .git and refused it by its own name, .git.
• The fix. gate() now gives the holder as the whole root: find_repo_root answers it, and _refuse_an_unreadable_root asks nothing. No assertion changed.
• A real run never reaches a member. The walk asks only the start and the folders above it. The file's mode rows (member-000, members-000, variant-000, staged-removal-000) run the whole gate in a subprocess, the new check included. They passed at 05e6ab0f too.
• The other three tools. Each carries its own copy of the walk, from the same start upward. None of their tests runs main in process after refusing .git by name. Their .git rows call one function alone (checkout_tracking_branch, unfetchable, run_member_target, fetch_members, _print_pinned_row), and the gate passed them.

Why

• Each pinned copy carries its own _refuse_an_unreadable_root(start), not a newer find_repo_root.

  • scripts/repo_shape.py is a shape copy too, and a pinned copy may not rely on a newer one (repo_shape.py's Refusal gives every refusal built without a remediation the assembly root's own (run git submodule update --init --recursive, then python3 scripts/validate-pins.py ... contracts/<leg>-pin.yaml), so in a family holder family.py add over an unparsable .gitmodules (git-failed), bump on a family.yaml of the wrong kind, and the holder's own validate-family.py on a short pin.commit each tell the operator to run a file no holder carries and to move a leg pin a holder does not have #370, Pinned shape copies: AGENTS-shape.md's CONTRACTS_DIR sentence is false for every scaffolded root, and the chain WARNING offers remedies the scaffold lacks (one shape bump before the v1.1.0 tag) #610). That is why shape-doctor.py: a shape root whose own .git is a link into a folder this user cannot search reads DRIFTED, its legs as having no gitlink, and both of its validators crash with PermissionError #1146 put the walk in each validator.
  • Each tool's loader calls it right before find_repo_root(start), with start = args.root or parents[1].
  • It asks each .git that find_repo_root would ask, in the same order, with the file's own _is_a.
  • A .git that answers absent (nothing there, a link to nothing or to itself) is passed over, as exists() passes it.
  • It starts where the start resolves, so --root . from a folder inside the root walks up from there.
  • It stops at the first .git that is there, a directory or a gitfile, so a .git above the root is never asked.
  • The path is named relative to the resolved start, or whole where it is not under it, and spelled (spelled, templates/assembly-root/scripts/bootstrap.py and templates/family-root/scripts/bootstrap.py: main prints the manifest's name with a plain print before any step runs, so name: "a\ud83db" (a lone surrogate) ends make bootstrap in a UnicodeEncodeError traceback, exit 1 (make: 2), and the validator that names the problem is never reached; a valid name the stdout cannot encode ends the same way #391).

• One code, git-repo-unreadable, exit 2. It is the code validate-pins.py and validate-manifest.py refuse the same root by (shape-doctor.py: a shape root whose own .git is a link into a folder this user cannot search reads DRIFTED, its legs as having no gitlink, and both of its validators crash with PermissionError #1146), and the sibling of not-a-git-repo. Each remedy is in the tool's own words:

  • the assembly bootstrap: _unreadable(..., ROOT_READ);
  • validate-family.py: _unreadable gains reads=PATHS_READ;
  • the family bootstrap: unreadable(..., ROOT_UNDONE);
  • siblings.py: member_unreadable gains code="member-unreadable" and is passed code=ROOT_UNREADABLE. Its advice keeps its own "(and on every directory above it)", without "inside the root", since its clones sit outside the holder (Every Path.is_file() / is_dir() / exists() guard in the shipped tools answers False to any OSError on Python 3.14 (3.12 and 3.13 raise PermissionError), so a directory this user cannot search reads as ABSENT: validate-pins.py skips its workflow @<sha> check, update-shape.py says copy-missing and update-pin-missing ("adopt the project") for files that are there, the doctor says DRIFTED (5 copy-missing), and bump-leg.py's remaining guards, and every other tool's, skip or misreport instead of refusing by name #430).

• The three that read the root's repository through git also ask what validate-pins.py asks. Those are both bootstraps and validate-family.py. Each asks of the first .git that is there:

  • a gitfile it cannot open;
  • a git directory whose HEAD it cannot reach.

  The gitfile's line has CR LF stripped, and the name is normpath'd. On base, git's answers there were no gitlink recorded, gitlinks-unreadable over not a git repository, and FETCH INCOMPLETE with the advice to set a credential: each a claim about something else.

• siblings.py asks the stat alone, as validate-manifest.py does. It reads the holder's files, and .gitmodules as a file, and runs git in the holder only for the branch its layout table shows. With a .git directory at 000 it still places every member, measured on both sides.

• The doctor: one finding, in the members row, and no member is drift.

  • check_members calls root_git_read(ctx.root) (shape-doctor.py: a shape root whose own .git is a link into a folder this user cannot search reads DRIFTED, its legs as having no gitlink, and both of its validators crash with PermissionError #1146's) after the empty-members return, and returns members_git_unread_row.
  • The row is a FINDING with the gate's line once. Its NEXT is this doctor again, and its WHY is the advice for the cause.
  • Each member's entry carries every key a member's entry has, each null, plus gitlink_cannot_be_read, so a reader of --json gets no KeyError.
  • drifted_reasons counts no entry that carries it, and still counts a member beside it that it could read and is off its pin.

• Not touched: scripts/repo_shape.py (find_repo_root stays on the hygiene test's BENIGN list as PINNED); KNOWN_OPEN (no entry for these sites); siblings' submodule_urls, which is family.py, the family root's siblings.py, shape-doctor.py and shape_advisory.py: a name in the root that is a link into a folder this user cannot search is still read as absent at twelve sites (follow-up of #430 slice Z) #1110 slice B's.

Tests

tests/test_pinned_root_git_unreadable.py, new, has 76 rows.

• Mode cases. A real mode, each tool run as a person runs it. They skip on Windows and as root (CANNOT_RUN_AS_ROOT), and restore the mode after:
  • the issue's case, a .git linked into a folder at 000, for each tool;
  • .git at 000 and at 444, for each git reader;
  • a gitfile into a locked folder, named by its git directory, whole;
  • the doctor over the holder, link and directory: INVALID (family), members held whole, never checked out at ?.
• Stand-in cases. In process, on every platform and as root (refused_stat, refusing, as_python_314):
  • each tool, both causes (permission and I/O error);
  • the walk, per tool: a .git above the --root given, named whole; the same under a folder whose name holds an ESC, the whole path spelled; a relative --root . run from contracts/; a .git above the root never asked; a stop at a readable gitfile, and at a gitfile that names no directory (added after review r1: test_the_walk_stops_at_a_gitfile_that_names_no_directory, one id per git reader);
  • per git reader, what .git is or names: a git directory's HEAD, a gitfile that cannot be opened, a git directory outside the root and inside it, a gitfile ending in CR LF, an unprintable folder (POSIX only);
  • siblings.py asks only the stat;
  • the members row in process, both causes, and drifted_reasons with a readable member beside an unread one.
• Controls. A readable root and holder: COMPLIANT, each tool goes on past the question. Five roots that answer absent or that git answers for: no tool refuses. siblings.py over a .git directory at 000 still places the members.

Base vs head. Base is b75babee with the new file laid over it.

	3.12.3	3.14-like shim
base b75babee	74 failed, 2 passed	74 failed, 2 passed
head 5aa0f116	76 passed	76 passed

The 2 rows that pass on base are controls: test_siblings_still_places_the_members_of_a_holder_whose_git_is_at_000 and test_roots_whose_git_can_be_read_are_unchanged.

The other rows fail on base for two reasons:

• 38 on base's own answers (unchanged by the review round): the 3.12 traceback and the shim's not-a-git-repo (link at 000, every tool, in process, --root contracts, --root ., and the ESC folder); no gitlink recorded, gitlinks-unreadable, gitmodules-unreadable and FETCH INCOMPLETE (the git readers at 000, 444 and through a gitfile); DRIFTED (a member is not at its pin) and a members row that is ok, not FINDING; drifted_reasons counting the unread entries;
• 36 only on a name base does not have (_refuse_an_unreadable_root, AttributeError): the 33 before review r1, and the 3 ids of test_the_walk_stops_at_a_gitfile_that_names_no_directory.

Mutants: 58 of 58 killed (the 55 below, and the 3 review r1 added). Each was applied once to a scratch clone of the head (never the worktree), the new file was run there with -x on 3.12, and the file was put back in a finally. The clones were checked clean after.

• Per git reader (A, V, F), the mutants were: the call removed; continue made return on absent; no .resolve(); the final return removed; CR not stripped; no normpath; the git directory named as .git; the HEAD step removed; relative naming removed or named against the candidate; the ValueError fallback removed; spelled removed (F); the code changed; the reads or what text dropped.
• siblings.py (S): the call removed; the return removed; an absent .git stopping the walk; no resolve; the relative naming and its fallback; spelled removed; the code dropped or ignored; the what text dropped.
• The doctor (D): no root_git_read in check_members; the drift filter removed; the null keys dropped; why or next None; status ok; the reason changed; the line not carried.
• Review r1's three (issuecomment-6351621763). It ran 42 of its own 85 mutants: 39 killed and 3 survived. The 3 were A-, V- and F-gitfile-naming-nothing-continues: in each git reader, the return made continue where .git is a gitfile that does not start with gitdir: . The 73 rows had no row that held that line. test_the_walk_stops_at_a_gitfile_that_names_no_directory was added for them: the root's .git is a gitfile reading no gitdir, the parent's .git is refused with as_python_314, and _refuse_an_unreadable_root(root) answers None. Run in a scratch clone of this tree, the file with -x on 3.12.3, each mutant is KILLED by its own tool's id: [assembly-bootstrap], [validate-family], [family-bootstrap] (1 failed, 45 passed, 1 failed, 47 passed, 1 failed, 46 passed), restored in a finally. The review's other 43 mutants were not run by it and were not run again here.
• 54 were killed by the file's first 69 rows. S-spelled-removed survived those (69 passed), because the only unprintable row was the git readers'. The row test_a_root_git_named_whole_is_spelled was added for it, over all four tools, and its [siblings] id kills it.

The regression in tests/test_validate_family_unreadable.py, on 3.12.3:

b75babee (base)	05e6ab0f (before the fix)	3a389565 (the fix; 53 passed again at the head 5aa0f116, measured by r1172b)
53 passed	6 failed, 47 passed	53 passed

• The six rows: test_a_path_whose_stat_is_refused_is_refused_by_name at [member-checkout], [member-checkout-pins], [unregistered-member-checkout], [staged-removal-checkout] and [variant-checkout], and test_a_stray_whose_rm_takes_no_f_asks_nothing_of_its_git.
• Two mutants of the fix, each in a scratch clone of the head, with the files put back in a finally:
  • The new stub removed. Killed by test_a_path_whose_stat_is_refused_is_refused_by_name[member-checkout], and by the other five, as before the fix.
  • validate-family.py's check walking from members/IRRS instead of the start. Killed by the mode row test_a_folder_this_user_cannot_search_is_refused_by_name[member-000]. A root check that reached a member's .git is still seen with the stub in place.
• The new file, again at 3a389565: 73 passed on 3.12.3, and 73 passed under the shim. At 5aa0f116, with review r1's 3 rows: 76 passed on 3.12.3, and 76 passed under the shim; tests/test_validate_family_unreadable.py, 53 passed.

The gate, all five calls, on 3.12.3.

• How it ran. Each call was collected to node ids first (--collect-only; the count of ids equals pytest's own "collected" line). The ids were then run in shards of at most 300 ids, each under 9 minutes, as a person runs them: no gh, a stub gh first on PATH, GIT_SSH_COMMAND=false.
• Which head. The calls ran at 05e6ab0f. The fix that followed, 3a389565, touches only tests/test_validate_family_unreadable.py. After review r1 the new call ran again at 5aa0f116 (the head, which adds 3 rows to the new file and nothing else).
  • Only the big-22 shard holds that file, and no other test imports it.
  • So new and big-22 ran again at 3a389565, and the other shards stand.
  • tests/test_family_hand_mount_git_rm_lines.py, which names the file in its docstring, also ran again at 3a389565: 29 passed.

Call	Files	Ids	Result
new	test_path_guard_hygiene, test_root_git_unreadable, test_pinned_root_git_unreadable, test_doctor_unreadable_pin, test_doctor_unreadable_paths	255	255 passed at 05e6ab0f, 255 again at 3a389565, and 258 passed at 5aa0f116 (3 rows added)
docs	test_scaffold_leg_path_collisions and the doc trio (test_agents_md_codes, test_cli_reference, test_repo_hygiene)	274	274 passed
pin	test_pinned_copy_text, test_shape_pin_*, test_update_shape* (22 files)	945 in 4 shards	945 run: 237 passed, 234 passed with 3 skipped (junctions are NTFS's, test_update_shape_add_symlink.py:832), 237 passed, 234 passed; 0 failed
sd	test_shape_doctor.py, in 4 shards	448	445 passed, 3 skipped (the PowerShell line, printed only on a Windows host), 0 failed
big	the 116 other files naming validate-family.py, siblings.py or bootstrap.py, and 6 that read the members row or its keys	8076 in 27 shards	8037 passed, 39 skipped, 0 failed, with big-22 at 3a389565 (300 passed). At 05e6ab0f, big-22 failed 6 of 300: the regression above. The other 26 shards passed

The 39 skips in big are this bench's:

• git 2.43 here, where CI runs 2.55 (and the reftable backend needs 2.45);
• rows for Windows or macOS only;
• GNU make's jobserver form;
• rows whose template already quotes the value, so the rule has nothing to refuse.

The new file was also run in full under the 3.14-like shim: 73 passed, at 05e6ab0f and again at 3a389565, and 76 passed at 5aa0f116. tests/test_path_guard_hygiene.py with tests/test_repo_hygiene.py: 149 passed at 5aa0f116. The pin, docs, sd and big calls were not run again after review r1, since the only file it changes is the new test file, which no other test imports.

Pinned copy

The four files are in scripts/shape_materialize.py's COPIED_VERBATIM (the assembly bootstrap) and FAMILY_COPIED_VERBATIM (the three holder files). No file is added to or taken from a list, and no digest of them is recorded in the tree, so there is no pin-record edit, as in #1147. Measured against a standard one commit past the pin of a project and a holder scaffolded from base:

• update-shape.py check, project: upstream-changed scripts/bootstrap.py, unchanged for the other 10;
• update-shape.py check, holder: upstream-changed for scripts/validate-family.py, scripts/bootstrap.py and scripts/siblings.py, unchanged for the other 7;
• the new doctor, readable: COMPLIANT, SHAPE BEHIND (1 upstream-changed, 0 upstream-added) for the project and (3 upstream-changed, 0 upstream-added) for the holder;
• the new doctor over a holder that still holds the old copies, link or directory at 000, on both Pythons: INVALID (family). The members row names .git: cannot be read (Permission denied) once, with the cure. Until the holder runs update-shape.py apply, the family row is the old copy's answer: crashed before reaching a verdict (exit 1): PermissionError for the link, REFUSED gitlinks-unreadable for the directory. The doctor takes PYTHONPATH out of the validator's child (shape-doctor.py: after #238 the doctor runs a root's OWN validator with the operator's PYTHONPATH still in the child's environment, so for an operator who exports one that reaches a repo_shape.py the manifest row of a root that lost its own scripts/repo_shape.py says ok ... passes again, the false pass #238 removed, where the project's own gate in CI fails on ModuleNotFoundError: No module named 'repo_shape' #306), so the shim does not reach it, and the row is the same on both.

Merge with #1147's new head

#1147's head was then a2fc1da8: main with #1200 merged in (569ea056), then placement giving the root's line ahead of #1200's refusal of a leg's git directory. It is merged here as 2eabec8e ("Merge #1146's branch into #1148's branch"), parents 5aa0f116 and a2fc1da8, with no conflict. git merge-tree gave tree c473b237, and the merge commit has that tree. Four files changed on both sides since the merge base b75babee (shape-doctor.py, both bootstrap.py files and validate-family.py), and git merged each with no conflict. Compared line by line, per file, the merge adds to this PR's 7 files exactly the lines a2fc1da8 brings, and keeps exactly the lines this PR added: 902 added and 26 removed, as before.

The members row and #1200 agree. #1200 names a member whose own git directory cannot be read, through mount_read in member_state. This PR's check comes first in check_members: with the holder's own .git unreadable, root_git_read answers and the row returns before any member is read. So the two never meet, and the order is the one a2fc1da8 gives placement: the root's line first. On the merge:

• with the holder's .git linked into a locked folder, or a directory at 000, the row is a FINDING: .git: cannot be read (Permission denied), so no gitlink is read and no member is compared with its pin, said once. The member's entry has every key null, plus gitlink_cannot_be_read, and the verdict is INVALID (family). shape-doctor.py: a leg or member whose git directory this user cannot read is named in the gate's words, spec: .git/modules/spec: cannot be read (<reason>), so the legs and members rows never count it as drift, placement never calls it "not a git repository", and no HEAD is read for it (#1174) #1200's line for .git/modules/members/IRRS, unreadable under that .git too, is not said;
• with a readable holder and the member's git directory at 000 or r--, the row is shape-doctor.py: a leg or member whose git directory this user cannot read is named in the gate's words, spec: .git/modules/spec: cannot be read (<reason>), so the legs and members rows never count it as drift, placement never calls it "not a git repository", and no HEAD is read for it (#1174) #1200's: members/IRRS: .git/modules/members/IRRS: cannot be read (Permission denied), so no HEAD in it is compared with the pin. The entry has mount_cannot_be_read and head null, and the verdict is INVALID (family);
• in process, drifted_reasons is [] for both rows, and each row's why is the advice for its cause.

Tests on 2eabec8e, in the probe environment, on Python 3.12.3 and git 2.43.0:

Call	Files	Result
own	tests/test_pinned_root_git_unreadable.py, tests/test_validate_family_unreadable.py	129 passed
unread	tests/test_root_git_unreadable.py, tests/test_doctor_unreadable_paths.py	118 passed
scans	test_path_guard_hygiene, test_no_auto_maintenance, test_scaffold_leg_path_collisions	283 passed, 2 skipped (test_no_auto_maintenance.py:222: the session began with GIT_CONFIG_GLOBAL set)
members	8 of the ids above: the members rows of both PRs and the readable control, with each row logged	8 passed

That is 532 ids: 530 passed and 2 skipped. Lane 1's gate on a2fc1da8 covers #1147's side: 1,018 passed and 5 skipped. The pin, docs, sd and big calls above were not run again on the merge.

Restacked after #1147 landed

#1147 landed as 51a9c5f1 on main, the squash of its final head 95ea5646. That head is update-branch's merge of main 801a7d6d into 4d299dd3, #1147's last fix: placement gives the root's line only to a leg whose mount mount_read got into, so a mount this user can search and not list keeps spec: cannot be listed. The squash's tree, 2d6db67c, equals 95ea5646's. The branch was restacked from 2eabec8e by real merges, with no rebase, squash, amend or force-push:

1. 81bc91f8 merges 95ea5646. No conflict. Its tree, f48d7e9e, is the one git merge-tree --write-tree gave beforehand. It brings 4d299dd3 (shape-doctor.py, and a row in tests/test_root_git_unreadable.py) and main's 18 commits after a2fc1da8.
2. ba81fd7d merges the squash 51a9c5f1, with this branch's side kept for shape-doctor.py, validate-pins.py and validate-manifest.py: a root whose own .git this user cannot read is named .git: cannot be read (<reason>), so the doctor never reads it as DRIFTED, and both pinned validators refuse it, exit 2 (#1146) #1147's files. Those are the five files of git diff --name-only 51a9c5f1^ 51a9c5f1: shape-doctor.py, validate-pins.py, validate-manifest.py, tests/test_doctor_unreadable_paths.py and tests/test_root_git_unreadable.py. git ls-files -u was empty, and git write-tree gave f48d7e9e, the tree of 81bc91f8: the merge changes no file.
3. No merge of main was needed. Fetched again before this step, at 18:34Z, origin/main was still 51a9c5f1.

The PR's own change is unchanged. The + and - lines of git diff -U0 b75babee 5aa0f116 (the delta r1172b found READY) and of git diff -U0 51a9c5f1 ba81fd7d are the same 928 lines, in the same 7 files and the same order: 902 added and 26 removed. Both have sha256 9eef7395.

Tests on ba81fd7d, in the probe environment, on Python 3.12.3 and git 2.43.0:

Call	Files	Result
own	tests/test_pinned_root_git_unreadable.py, tests/test_validate_family_unreadable.py	129 passed
unread	tests/test_root_git_unreadable.py, tests/test_doctor_unreadable_paths.py, tests/test_doctor_unreadable_pin.py	171 passed
scans	test_scaffold_leg_path_collisions, test_path_guard_hygiene, test_no_auto_maintenance	283 passed, 2 skipped (test_no_auto_maintenance.py:222: the session began with GIT_CONFIG_GLOBAL set)
docs	test_agents_md_codes, test_cli_reference, test_repo_hygiene	171 passed
sd	tests/test_shape_doctor.py, 449 ids in 4 shards	446 passed, 3 skipped (test_shape_doctor.py:10516: the PowerShell line, printed only on a Windows host), 0 failed

That is 1,205 ids: 1,200 passed and 5 skipped, none failed. The pin and big calls above were not run again on the restack.

Known limits

• family.py and the family root's siblings.py: a holder's .gitmodules this user cannot read, as through a link into a folder it cannot search, is gitmodules-unreadable, never no section for remove's rollback or no url for make siblings (#1110) #1164 (the sibling branch fix/1110-family-unsearchable-gitmodules) also changes templates/family-root/scripts/siblings.py. Lane 1's merge-tree shows a content conflict in the docstring's exit-2 paragraph and in member_unreadable. Whichever lands second keeps one form of each.
• The chmod cure says "every directory above it". In the issue's case the line names .git, which is a link, and the folder to mend is the one it leads into. chmod u+rx .git follows the link and is refused. These are each tool's existing words, as shape-doctor.py: a shape root whose own .git is a link into a folder this user cannot search reads DRIFTED, its legs as having no gitlink, and both of its validators crash with PermissionError #1146 left the gates'.
• siblings.py over a .git directory at 000 still places every member, by design: it asks only the stat. validate-family.py and make bootstrap refuse that holder.
• A .git this user can search whose HEAD is at mode 000 is not asked by this PR's four tools. The question is the stat of HEAD, and a searchable directory answers it. Review r1 measured the same answers on base and head, on both Pythons, each a claim about something else: the assembly bootstrap says REFUSED pin-gitlink-absent: no gitlink (mode 160000) recorded at 'spec'; the holder's bootstrap says FETCH INCOMPLETE (git exit 128) using credential source 'none' with the advice to set SHAPE_LEGS_TOKEN, and exits 0 with --no-fetch --skip-members; validate-family.py refuses gitlinks-unreadable over git's not a git repository. This PR leaves that case as it was.
  • Lane 3's validate-pins.py: a leg git directory's HEAD this user cannot open, under .git/modules/<leg> or in a .git directory, is refused pin-submodule-unreadable by name, where it ended pin-commit-unresolvable (#1222) #1239 (for validate-pins.py and shape-doctor.py: a leg's git-directory HEAD file at mode 000 passes the gate's stat of HEAD and ends pin-commit-unresolvable, and the doctor reads the leg DRIFTED, where both should name the file this user cannot open #1222) changes the assembly root's answer there; this PR does not. It is not on main at 51a9c5f1. It makes validate-pins.py's _refuse_an_unreadable_git_dir open a git directory's HEAD, and shape-doctor.py, validate-pins.py and validate-manifest.py: a root whose own .git this user cannot read is named .git: cannot be read (<reason>), so the doctor never reads it as DRIFTED, and both pinned validators refuse it, exit 2 (#1146) #1147's _refuse_an_unreadable_root in that file calls it for the root's own .git. Once validate-pins.py: a leg git directory's HEAD this user cannot open, under .git/modules/<leg> or in a .git directory, is refused pin-submodule-unreadable by name, where it ended pin-commit-unresolvable (#1222) #1239 lands, the pins validator, whose pin-gitlink-absent is the assembly bootstrap's answer above, opens the root's HEAD first, so that answer becomes a git-repo-unreadable refusal by name (lane 5's note, docs/release-notes/v1.0.0.md: the v1.0.0 release notes, a draft for Brett to amend before he tags, saying what 1.0 contains and promises, how to pin it by commit, what changed on the way grouped by the five tracking areas, and every known limit as the input that triggers it and what the person sees (#472) #473 issuecomment-6724142443, read from the code, not run). validate-pins.py: a leg git directory's HEAD this user cannot open, under .git/modules/<leg> or in a .git directory, is refused pin-submodule-unreadable by name, where it ended pin-commit-unresolvable (#1222) #1239 changes only validate-pins.py and its tests. The family gate, validate-family.py, and the holder's bootstrap.py and siblings.py carry their own walk, so for the family holder the sentence above holds either way.
• Only what validate-pins.py and repo_shape.py after #919: gh's stderr that is not UTF-8 ends in a traceback, a leg's git directory this user cannot read is called an unresolvable pin with no reason, and two gh details still name the repository raw #968 asks of a leg is asked: the stat of .git, the open of a gitfile, the stat of the git directory's HEAD. A git directory this user can search but whose index it cannot read is still git's answer.

Not in this PR

• scripts/repo_shape.py's find_repo_root.
• family.py, the family root's siblings.py, shape-doctor.py and shape_advisory.py: a name in the root that is a link into a folder this user cannot search is still read as absent at twelve sites (follow-up of #430 slice Z) #1110 slice B (siblings' submodule_urls).
• The doctor's members row for an unread holder .git has without_working_clone: [] beside entries whose working_clone is null (shape-doctor.py:11241 at ba81fd7d). A --json reader is told no member lacks a working clone, about a question the row did not ask. Review r1's NIT 3. The follow-up is None there, or computing it: a working clone sits beside the holder, outside its .git.
• Making the controls that name _refuse_an_unreadable_root pass on base, by driving them through main and asserting the code is not in stderr (review r1's NIT 1). 36 of the 74 rows that fail on base fail on that name alone.

Closes #1148

Lane: openreposhape-1 (openRepoShape-1)

🤖 Generated with Claude Code

Summary by Sourcery

Refuse unreadable repository roots consistently across pinned family tools and report them accurately in the shape doctor's members check.

New Features:

• Refuse unreadable repository roots consistently across the remaining pinned bootstrap, family validation, and sibling tools with the git-repo-unreadable error and exit code 2.
• Report an unreadable family holder in the doctor's members row once without treating its members as drift.

Bug Fixes:

• Prevent permission errors in repository-root discovery from becoming tracebacks, misleading missing-repository errors, or misleading fetch and gitlink failures.
• Ensure unreadable holder repositories are detected before any family members are fetched, validated, cloned, or compared.

Enhancements:

• Align root readability checks across pinned copies while preserving siblings' ability to place members when only repository contents are inaccessible.
• Keep unreadable-member details structurally complete and exclude them from drift-reason aggregation.

Tests:

• Add comprehensive mode-based and in-process coverage for unreadable root git links, directories, gitfiles, path traversal, error causes, doctor output, and unchanged readable-root behavior.
• Update validate-family unreadable-path fixtures to account for the new root check.

[sourcery-ai]

Reviewer's Guide

Implementation

Add root .git readability checks to the pinned bootstrap, family validator, and siblings callers so an unreadable repository is refused by name before those tools proceed.

• templates/assembly-root/scripts/bootstrap.py L117-120, L468-523, L2094-2101
• templates/family-root/scripts/bootstrap.py L184-187, L399-462, L2411-2414
• templates/family-root/scripts/siblings.py L367-415, L1608-1611 (+4 small edits)
• templates/family-root/scripts/validate-family.py L522-527, L532-590, L4330-4333 (+2 small edits)

Make the doctor report an unreadable holder .git once in the members finding and exclude those entries from drift reasons.

• shape-doctor.py L11214-11245, L11260-11268, L12696-12702 (+2 small edits)

Tests

Add coverage for unreadable root repositories across the pinned callers and doctor, and adapt the gate fixture to distinguish holder-level from member-level .git refusals.

• tests/test_pinned_root_git_unreadable.py L1-562
• tests/test_validate_family_unreadable.py L51-56, L100-104, L109-110

---

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-1, 2026-10-22T21:23:31Z) Independent review r1172 of #1172 at 3a389565, partial, cut short when the shared window reached STOP: NOT READY as far as it got. It found no MUST and one SHOULD.

• SHOULD: in all three git readers, no row holds the line that stops the walk at a .git gitfile naming nothing. Three mutants survive; one cheap row fixes it.
• NITs: 4.
• f1148's fixture stub: sound.
• The four tools: they match the body's table on 3.12 and under the 3.14 shim.

Lane 1 runs the fix round in a later window.

Review of #1172 (r1172, lane openRepoShape-1): partial, cut short by STOP

Verdict: NOT READY, as far as I got. I found no MUST. There is one SHOULD: a key line in all three git readers has no test that catches a change to it. It needs one cheap test row. Coverage is incomplete; see the last section.

State at stop: no runs are live. Each mutant was restored and its blob checked against HEAD. git status --untracked-files=no shows nothing in clone, clone2 or the review checkout l1-r1172, all at 3a389565a.

Your three points

1. f1148's stub (commit 3a389565): sound

• Before the stub: at 05e6ab0f, tests/test_validate_family_unreadable.py gave 6 failed, 47 passed. They are the six rows the body names, each failing with REFUSED git-repo-unreadable: .git: cannot be read (Permission denied).
• Base: b75babee gave 53 passed.
• Head: 3a389565 gave 53 passed on 3.12 and 53 passed under my 3.14-like shim ($S/shim314/sitecustomize.py).
• The 05e6ab0f run is the "stub removed" mutant. That commit is head without the stub.
• The stub cannot hide a member's .git. The real walk asks only [path, *path.parents] of the resolved start, never anything below it. So the stub takes away only the holder's own .git, which refused_stat(".git") refuses as a side effect.
• The subprocess mode rows still hold a member's .git to member-unreadable. They run the gate with no stub, the new check included, and passed in both head runs above: member-000, member-444, members-000, unregistered-member-000, staged-removal-000, other-checkout-000, variant-000 and hand-mount-committed-444.
• Not re-run: the body's second fixture mutant (the walk started from members/IRRS).

2. The four tools: no wrong refusal, missed refusal or wrong wording found

I probed each tool as make runs it, from the root, on base and head, on 3.12 and under the shim, in seven states: readable, link into a folder at 000, .git at 000, .git at 444, gitfile into a locked folder, gitfile at 000, and HEAD at 000.

• The body's What table: every cell matches, both Pythons.
  • Base 3.12, link: traceback, exit 1. Base shim, link: not-a-git-repo, exit 2.
  • Base, .git at 000:
    • the assembly bootstrap said no gitlink recorded, then bootstrap REFUSED: pins (exit 2);
    • validate-family.py refused gitlinks-unreadable;
    • the family bootstrap said FETCH INCOMPLETE, exit 1, and family bootstrap ok, exit 0, with --no-fetch --skip-members.
  • Head: REFUSED git-repo-unreadable, exit 2, nothing on stdout, for every refusal on both Pythons.
  • siblings.py over a .git at 000 places IRRS and says siblings ok, exit 0, on both sides.
• States the body did not list, all as designed:
  • gitfile at 000: the three git readers refuse .git and siblings.py is unchanged;
  • .git at 444: refused;
  • gitfile into a locked folder: the git directory is named whole.
• The doctor at head: INVALID (family) in the link, 000, 444, gitfile-locked and gitfile-000 states, on both Pythons.
  • members is a FINDING with the gate's line once, NEXT is this doctor again, and WHY is the chmod advice.
  • family is the holder's validate-family.py refusing git-repo-unreadable.
  • The readable holder is COMPLIANT. The base doctor matches the body.
• Wording: each tool's stderr matches the test's BEFORE and its advice word for word. siblings.py alone leaves out "inside the root".
• Bench note, not a PR fault: the plain (fetching) runs of the family bootstrap and siblings.py need protocol.file.allow=always here. git 2.43 refuses the file transport for submodules. With it set, the readable cells say family bootstrap ok and siblings ok.

3. The body's numbers

• New file: head 73 passed on 3.12 and 73 passed under the shim. Base with the file laid over gave 71 failed, 2 passed on both. The two passing rows are the controls the body names. 33 of the 71 call the new function directly (4+4+18+2+5), which matches the body's 33. Confirmed.
• Mutants: I ran 42 of my 85 and 39 were killed. The body's 55 of 55 is not confirmed, because my set includes one mutant family the body's set did not have, and it survives (SHOULD 1).

Findings

SHOULD 1: a gitfile that names no directory must stop the walk, and no row holds that

• Where:
  • templates/assembly-root/scripts/bootstrap.py:511
  • templates/family-root/scripts/validate-family.py:569
  • templates/family-root/scripts/bootstrap.py:448
• What it guards: each of these lines returns when .git is a gitfile that does not start with gitdir: . find_repo_root stops at that .git, so the check must stop there too.
• Evidence: I changed each return to continue (r1172/mut/mutants.py, run by run.py with -x on the new file, 3.12). All three survived:

  A-gitfile-naming-nothing-continues  SURVIVED 27s restored=True
  V-gitfile-naming-nothing-continues  SURVIVED 27s restored=True
  F-gitfile-naming-nothing-continues  SURVIVED 26s restored=True
  

  With the mutant, a holder whose .git names nothing would be refused over a .git above it that find_repo_root never asks.
• Fix: add one row over GIT_READERS, beside test_the_walk_stops_at_a_git_that_is_a_gitfile (line 424):
  • the root's .git is b"no gitdir\n" (the ABSENT arrangement);
  • the parent's .git is refused with as_python_314;
  • assert _refuse_an_unreadable_root(root) is None.

NIT 1: 15 control rows cannot pass on base

• Where: tests/test_pinned_root_git_unreadable.py, lines 411, 424, 479 and 491. Those are test_a_git_above_the_root_is_never_asked, test_the_walk_stops_at_a_git_that_is_a_gitfile, test_siblings_asks_only_the_stat and test_what_answers_absent_is_left_to_find_repo_root.
• Evidence: base 3.12 lists all 15 as FAILED with AttributeError: ... has no attribute '_refuse_an_unreadable_root'. The review rule is that a control row passes on both sides. The body is open about these rows (its 33).
• Fix: drive the controls through main (or run_tool) and assert CODE not in stderr, so base passes them too.

NIT 2: the body says placement was ok in every state

• Evidence: in my doctor runs, placement is n/a in every state, the readable holder included, on base and head alike.
• Fix: say "unchanged (placement is n/a for a holder)".

NIT 3: without_working_clone: [] beside entries whose working_clone is null

• Where: shape-doctor.py:10949.
• Problem: a --json reader is told that no member lacks a working clone, about a question the row did not ask.
• Fix: None, or compute it. A working clone sits beside the holder, outside its .git.

NIT 4: Known limits could name HEAD at 000

• Evidence: with a searchable .git whose HEAD is at 000, the same on base and head and on both Pythons:

  • the assembly bootstrap says REFUSED pin-gitlink-absent: no gitlink (mode 160000) recorded at 'spec';
  • the family bootstrap says FETCH INCOMPLETE, or ok with --no-fetch --skip-members;
  • validate-family.py refuses gitlinks-unreadable.

  These are the kind of misleading answers this PR removes, left out by the limit's "stat of HEAD only".

• Fix: add a sentence to Known limits naming this case.

Parts not covered

• 43 mutants not run (all defined in /workspace/projects/openRepoShape-worktrees/_lane1-scratch/r1172/mut/mutants.py):
  • A: absent-kind-dir, relative-naming-removed, named-against-candidate, reads-dropped;
  • V and F: relative-naming-removed, named-against-candidate, valueerror-fallback-removed;
  • V: reads-dropped, reads-ignored;
  • F: spelled-removed, what-dropped;
  • all 17 siblings.py mutants;
  • all 10 doctor mutants, including D-before-empty-return (the order after the empty-members return);
  • X-walk-from-member. X-stub-removed is covered by the 05e6ab0f run.
• The gate calls (docs, pin, sd, big; about 9,000 ids) were not re-run. Only test_pinned_root_git_unreadable.py and test_validate_family_unreadable.py were.
• The Pinned copy section was not measured: the update-shape.py check results and the doctor over a holder that still holds the old copies.
• Closing form and stacking:
  • Read but not grepped: the body holds one closing line, Closes #1148, and I saw no other close, fix or resolve form before an issue number.
  • Merge-base of head and b75babee is b75babee.
  • Not checked: whether origin's fix/1146-root-git-unreadable-not-drift is still at b75babee (no ls-remote).

Files

• Scratch: /workspace/projects/openRepoShape-worktrees/_lane1-scratch/r1172/
  • mutant results: mut/res1.jsonl, mut/res2.jsonl
  • probe output: probe-{base,head}-{312,314}.jsonl, probe2-{base,head}.jsonl
• Base worktree: /workspace/projects/openRepoShape-worktrees/l1-r1172-base at b75babee. It holds two untracked test files I copied in; it is not to be committed.

Lane: openreposhape-1 (openRepoShape-1)

[brettheap]

(lane openRepoShape-1, 2026-10-23T08:09:41Z) Independent re-review r1172b of #1172 at 5aa0f116: READY. No MUST and no SHOULD; two NITs, neither blocking.

Review r1172b of #1172 at 5aa0f116: READY

I found no MUST and no SHOULD. r1172's SHOULD is fixed, NIT-2 and NIT-4 are done, and every claim in the body that I checked matches what I measured. There are two new NITs, and neither blocks the PR.

1. The SHOULD is fixed

• The diff since 3a389565 is one file, tests/test_pinned_root_git_unreadable.py, with 18 lines added (437-453). It adds test_the_walk_stops_at_a_gitfile_that_names_no_directory over GIT_READERS. Nothing imports that file; test_validate_family_unreadable.py:55 names it only in a docstring.
• Base vs head. I ran the whole file in scratch clones, with base at b75babee plus the head's file laid over it:

	3.12.3	3.14-like shim (mine, r1172b/shim314)
base	74 failed, 2 passed	74 failed, 2 passed
head	76 passed	76 passed

• The new row's 3 ids fail on base and pass at head, on both Pythons. On base each fails with test_pinned_root_git_unreadable.py:452: AttributeError: module 'pinned_root_git_bootstrap' has no attribute '_refuse_an_unreadable_root', and the same for the other two tools.
• The three mutants that survived r1172, run in r1172b/clone-head with -x on the whole file. Each file was restored in a finally, and its blob matched HEAD's after:

  A-gitfile-naming-nothing-continues KILLED [assembly-bootstrap] 1 failed, 45 passed restored=True
  V-gitfile-naming-nothing-continues KILLED [validate-family]    1 failed, 47 passed restored=True
  F-gitfile-naming-nothing-continues KILLED [family-bootstrap]   1 failed, 46 passed restored=True
  

  Each one fails with REFUSED git-repo-unreadable: <parent>/.git: cannot be read (Permission denied). That is the wrong refusal the row exists to catch, and the counts match the body's word for word. 3/3 killed.

2. NIT-2 and NIT-4

• NIT-2 is done. The body now says the other family rows were ok and that "placement is n/a for a holder". r1172's probe files (r1172/probe-{base,head}-{312,314}.jsonl) agree: in all 6 states, on both sides and both Pythons, manifest-kinds, shape-currency and agent-files are ok and placement is n/a.
• NIT-4 is done. I checked the new Known-limits sentence myself on 3.12, with a searchable .git whose HEAD is at 000. Each tool ran from the root, and base and head gave the same answers:
  • the assembly bootstrap: REFUSED pin-gitlink-absent: no gitlink (mode 160000) recorded at 'spec', then bootstrap REFUSED: pins (exit 2);
  • validate-family.py: REFUSED gitlinks-unreadable, exit 2;
  • the family bootstrap: FETCH INCOMPLETE (git exit 128) using credential source 'none': and fatal: not a git repository, with the SHAPE_LEGS_TOKEN advice, exit 1;
  • with --no-fetch --skip-members: family bootstrap ok, exit 0.

3. Reading the diff adversarially

The row is sound. _is_a uses path.stat(), which as_python_314 patches, so a continue really does reach the parent's refused .git. Nothing in it depends on the Python version, and it runs as root and on Windows. Leaving out siblings is right: siblings' stop at any .git that is there is held by test_the_walk_stops_at_a_git_that_is_a_gitfile[siblings].

4. The body's claims

• Rows and counts: 76 rows; base 74 failed and 2 passed, head 76 passed, both Pythons. Confirmed.
• The 2 base passes are the two named controls. Confirmed.
• Why base fails: 36 rows on the AttributeError and 38 on base's own answers. Confirmed: 74 tb lines, 36 of them AttributeError.
• Hygiene: test_path_guard_hygiene.py with test_repo_hygiene.py gave 149 passed at head. Confirmed.
• The regression file: test_validate_family_unreadable.py gave 53 passed at 5aa0f116. Confirmed.
• Gate arithmetic: the counts add up. pin is 237 + (234+3) + 237 + 234 = 945; sd is 445+3 = 448; big is 8037+39 = 8076; new is 255+3 = 258.
• Closing form: exactly one, Closes #1148. A regex finds no other close, fix or resolve form before any #N.
  • Title: 246 characters.
  • The outside-v1.2.0 ruling is named.
  • The body ends with the lane line and the generated footer.
  • closingIssuesReferences is [] while the base is not main, which is expected for a stacked PR.
• Stacking is right:
  • shape-doctor.py, validate-pins.py and validate-manifest.py: a root whose own .git this user cannot read is named .git: cannot be read (<reason>), so the doctor never reads it as DRIFTED, and both pinned validators refuse it, exit 2 (#1146) #1147 is OPEN, its head fix/1146-root-git-unreadable-not-drift is at b75babee…889, and its base is main;
  • the remote ref fix/1146-… is at b75babee…889, and the remote ref fix/1148-… is at 5aa0f116…5;
  • merge-base 5aa0f116 b75babee is b75babee, with 4 commits on top.

NIT findings

NIT-A: the row holds return against continue, but not against a fall-through

• Where: tests/test_pinned_root_git_unreadable.py:449-451, against bootstrap.py:510-511, validate-family.py:568-569 and family/bootstrap.py:447-448.
• Evidence: return made pass survives the whole file in all three readers (76 passed, restored=True ×3).
  • With that mutant, the code parses b"no gitdir\n"[8:], which is b'r', as a git directory. Where <root>/r/HEAD is refused, it gives the wrong refusal REFUSED git-repo-unreadable: r: cannot be read (Permission denied).
  • The case is contrived, so this is only a NIT.
• Fix: add root.resolve() / "r" / "HEAD": denied to that row's as_python_314 dict.
  • Measured in a scratch copy of the row (r1172b/clone-head/tests/test_r1172b_probe_strong_row.py), it gives 3 passed at head.
  • It kills all three pass mutants (1 failed …) and still kills the three continue mutants.

NIT-B: two stale phrases in the body's Tests section

• The regression table's header labels `3a389565` (head), but the head is 5aa0f116. Fix: say "3a389565 (the fix)", or add a 5aa0f116 column with 53 passed, which I measured.
• The "Which head" bullet puts "The fix that followed touches only tests/test_validate_family_unreadable.py" after the 5aa0f116 sentence, so it reads as if 3a389565 came after 5aa0f116. Fix: move it before that sentence.

What I did not cover, and two slips

• Not re-run: the pin, docs, sd and big gate calls, the new call as a whole, and r1172's other 43 mutants. The diff is a single test file that nothing imports, so those results stand as the body states them.

• Load rule slips:

  • two of my pytest calls started while the container held 4 pytest processes: the first mutant run (about 07:57Z), and the strengthened-row run (about 08:07Z, after my wait loop timed out);
  • /workspace stood at 12G free during the last runs.

  All of my runs have ended.

State

• l1-r1172 is clean at 5aa0f116.
• l1-r1172-base is untouched: b75babee, with r1172's two untracked files.
• My scratch is /workspace/projects/openRepoShape-worktrees/_lane1-scratch/r1172b/:
  • logs: logs/, mutant results: mut/res-*.jsonl;
  • clones clone-head and clone-base, each with untracked probe files only and no tracked diff.

Lane: openreposhape-1 (openRepoShape-1)

[brettheap]

(lane openRepoShape-1, 2026-11-08T13:46:07Z) #1172's head is now 2eabec8e: it merges #1147's head a2fc1da8, and lane 1's check finds nothing else in it.

• The merge. Parents are 5aa0f116 and a2fc1da8. There was no conflict, and the tree c473b237 is the one git merge-tree predicted.
  • A line check of the 7 files bootstrap.py, validate-family.py and siblings.py: a root or holder whose .git this user cannot read is refused git-repo-unreadable, exit 2, not a traceback or not-a-git-repo, and the doctor's members row names it once, never drift (#1148) #1172 changes finds that the merge adds to each exactly what a2fc1da8 brings, and keeps exactly what bootstrap.py, validate-family.py and siblings.py: a root or holder whose .git this user cannot read is refused git-repo-unreadable, exit 2, not a traceback or not-a-git-repo, and the doctor's members row names it once, never drift (#1148) #1172 added: +902/−26, unchanged against a2fc1da8.
• The members rows agree with shape-doctor.py: a leg or member whose git directory this user cannot read is named in the gate's words, spec: .git/modules/spec: cannot be read (<reason>), so the legs and members rows never count it as drift, placement never calls it "not a git repository", and no HEAD is read for it (#1174) #1200's change. With the holder's own .git unreadable, the row says the root's line once, and shape-doctor.py: a leg or member whose git directory this user cannot read is named in the gate's words, spec: .git/modules/spec: cannot be read (<reason>), so the legs and members rows never count it as drift, placement never calls it "not a git repository", and no HEAD is read for it (#1174) #1200's per-member git-directory line is never said, because root_git_read returns first. With the holder readable and the member's git directory locked, shape-doctor.py: a leg or member whose git directory this user cannot read is named in the gate's words, spec: .git/modules/spec: cannot be read (<reason>), so the legs and members rows never count it as drift, placement never calls it "not a git repository", and no HEAD is read for it (#1174) #1200's row stands. The readable control is COMPLIANT.
• At 2eabec8e, in the probe environment:
  • bootstrap.py, validate-family.py and siblings.py: a root or holder whose .git this user cannot read is refused git-repo-unreadable, exit 2, not a traceback or not-a-git-repo, and the doctor's members row names it once, never drift (#1148) #1172's two files: 129 passed;
  • the root-git and doctor-unreadable files: 118 passed;
  • the three scans: 283 passed, 2 skipped.
• READY (r1172b, issuecomment-6360478153, at 5aa0f116) is about bootstrap.py, validate-family.py and siblings.py: a root or holder whose .git this user cannot read is refused git-repo-unreadable, exit 2, not a traceback or not-a-git-repo, and the doctor's members row names it once, never drift (#1148) #1172's own lines, which this merge leaves unchanged.
• Next: after shape-doctor.py, validate-pins.py and validate-manifest.py: a root whose own .git this user cannot read is named .git: cannot be read (<reason>), so the doctor never reads it as DRIFTED, and both pinned validators refuse it, exit 2 (#1146) #1147 squash-lands, bootstrap.py, validate-family.py and siblings.py: a root or holder whose .git this user cannot read is refused git-repo-unreadable, exit 2, not a traceback or not-a-git-repo, and the doctor's members row names it once, never drift (#1148) #1172 takes the three-merge restack onto the squash and main, then CI and its gate, in step 20.

Lane: openreposhape-1 (openRepoShape-1)

[brettheap]

(lane openRepoShape-1, 2026-11-08T18:47:46Z) #1172 is restacked onto #1147's squash 51a9c5f1, with its own change unchanged, at head ba81fd7d. It stays READY (r1172b, issuecomment-6360478153). It lands by fast refresh once CI's tests passes at ba81fd7d.

• The merges are real merges, with no rebase:
  1. 81bc91f8 merges shape-doctor.py, validate-pins.py and validate-manifest.py: a root whose own .git this user cannot read is named .git: cannot be read (<reason>), so the doctor never reads it as DRIFTED, and both pinned validators refuse it, exit 2 (#1146) #1147's final head 95ea5646 (update-branch's merge of 801a7d6d into 4d299dd3), with no conflict. Its tree, f48d7e9e, is the one merge-tree predicted.
  2. ba81fd7d merges shape-doctor.py, validate-pins.py and validate-manifest.py: a root whose own .git this user cannot read is named .git: cannot be read (<reason>), so the doctor never reads it as DRIFTED, and both pinned validators refuse it, exit 2 (#1146) #1147's squash 51a9c5f1, taking this branch's side for shape-doctor.py, validate-pins.py and validate-manifest.py: a root whose own .git this user cannot read is named .git: cannot be read (<reason>), so the doctor never reads it as DRIFTED, and both pinned validators refuse it, exit 2 (#1146) #1147's 5 files.
     • git ls-files -u is empty.
     • write-tree gives f48d7e9e, which is merge 1's tree, as it must be: the squash's tree 2d6db67c equals the tree of shape-doctor.py, validate-pins.py and validate-manifest.py: a root whose own .git this user cannot read is named .git: cannot be read (<reason>), so the doctor never reads it as DRIFTED, and both pinned validators refuse it, exit 2 (#1146) #1147's final head.
  3. There is no third merge, because main was still 51a9c5f1 at 18:34:29Z.
     • 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 landed after that, as 81eaf757. It touches only adopt-project.py and tests/test_adopt_work_dir_refusal.py.
     • merge-tree of it with ba81fd7d is clean, and update-branch brings it in at landing.
• The delta: git diff -U0 b75babee 5aa0f116 (the reviewed delta) and git diff -U0 51a9c5f1 ba81fd7d hold the same +/- lines: 928 (902 added, 26 removed), in the same 7 files. Both hash to sha256 9eef7395.
• Gates at ba81fd7d, in the probe environment, with Python 3.12.3 and git 2.43.0:
  • the PR's own files (tests/test_pinned_root_git_unreadable.py tests/test_validate_family_unreadable.py): 129 passed;
  • tests/test_root_git_unreadable.py tests/test_doctor_unreadable_paths.py tests/test_doctor_unreadable_pin.py: 171 passed;
  • tests/test_scaffold_leg_path_collisions.py with the two scans: 283 passed, 2 skipped;
  • the doc trio: 171 passed;
  • tests/test_shape_doctor.py in 4 shards: 446 passed, 3 skipped (the PowerShell line that only a Windows host prints).
• The body:
  • It now says "Was stacked on shape-doctor.py, validate-pins.py and validate-manifest.py: a root whose own .git this user cannot read is named .git: cannot be read (<reason>), so the doctor never reads it as DRIFTED, and both pinned validators refuse it, exit 2 (#1146) #1147" and names the squash.
  • A new section, "Restacked after shape-doctor.py, validate-pins.py and validate-manifest.py: a root whose own .git this user cannot read is named .git: cannot be read (<reason>), so the doctor never reads it as DRIFTED, and both pinned validators refuse it, exit 2 (#1146) #1147 landed", holds the facts above.
  • It takes lane 5's note (issuecomment-6724142443). validate-pins.py: a leg git directory's HEAD this user cannot open, under .git/modules/<leg> or in a .git directory, is refused pin-submodule-unreadable by name, where it ended pin-commit-unresolvable (#1222) #1239 is not on main; once it lands, the assembly gate opens the root's HEAD. So the limit on a HEAD at mode 000 now says it holds for this PR's four tools, and a sub-bullet gives validate-pins.py: a leg git directory's HEAD this user cannot open, under .git/modules/<leg> or in a .git directory, is refused pin-submodule-unreadable by name, where it ended pin-commit-unresolvable (#1222) #1239's effect.
  • The family.py and the family root's siblings.py: a holder's .gitmodules this user cannot read, as through a link into a folder it cannot search, is gitmodules-unreadable, never no section for remove's rollback or no url for make siblings (#1110) #1164 sentence stays. merge-tree of ba81fd7d with family.py and the family root's siblings.py: a holder's .gitmodules this user cannot read, as through a link into a folder it cannot search, is gitmodules-unreadable, never no section for remove's rollback or no url for make siblings (#1110) #1164's 74096eb4 still conflicts in templates/family-root/scripts/siblings.py, and whichever PR lands second keeps one form of each.

Lane: openreposhape-1 (openRepoShape-1)

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

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
1.7% Duplication on New Code

See analysis details on SonarQube Cloud