[brettheap]

Part of #1110: its twelfth site, scripts/shape_advisory.py _leg_by_agents_md.

Was stacked on #1144, which squash-landed on main as b1f45fa7 on 2026-11-08. GitHub retargeted this PR to main, and the branch is restacked on main by three merges (see ## Restacked after #1144 landed).

Outside v1.2.0. Brett Heap ruled at 2026-10-21T10:32:04Z: "leave the follow-ups out of v1.2.0". This PR lands after the v1.2.0 tag, on a later word.

66e68f94 changes one docstring in tests/test_doctor_unsearchable_links.py and nothing else (r1159b's NIT-B); every figure measured at 0ca33611 carries.

Restacked after #1144 landed

#1144 squash-landed on main as b1f45fa7. This branch is restacked on it by three merges, with no rebase and no force-push:

merge	commit	parents	tree
1. #1144's final head 5b38c3a3, update-branch's merge of main bd3e9c14 into 89486f69	9d93487d	66e68f94, 5b38c3a3	c5d0bc70
2. #1144's squash b1f45fa7, ours for its four files	ab31e2e5	9d93487d, b1f45fa7	c5d0bc70, merge 1's
3. main 0d5704b3 (#1169, #1223, #1166, #1133, #1104)	5370b018	ab31e2e5, 0d5704b3	fd53e4c0

• Merge 2 changes nothing. b1f45fa7's own files are scripts/shape_advisory.py, shape-doctor.py, tests/test_doctor_unsearchable_links.py and tests/test_path_guard_hygiene.py, and its tree is 5b38c3a3's, which merge 1 brought in. They take the branch's side, and the merged tree is 9d93487d's.
• Merge 3 is clean. Of this PR's files, main changed only scripts/shape_advisory.py: validate-manifest.py, validate-family.py, family.py and update-shape.py: an id:, a date or a repository: ending in a line feed is refused by name, and a pin's source_repository: that is no path or owner/repo name is named as the pin's (#1139) #1166 ends its DATE_RE in \Z, away from this PR's lines.
• This PR's own change is unchanged. The + and - lines of git diff -U0 89486f69 66e68f94 (the reviewed delta) and of git diff -U0 0d5704b3 5370b018 are the same 707 lines, in the same order and the same three files (674 added, 33 removed). Both have sha256 0a7cfc864f721b1f862b807e59cdde700b14e257c5e782c5f0aca5707036fcdf.

The gate at 5370b018 (3.12, the probe environment, one basetemp per call):

call	result
tests/test_doctor_unsearchable_links.py, tests/test_shape_advisory.py	96 passed (49 and 47)
tests/test_path_guard_hygiene.py, tests/test_no_auto_maintenance.py, tests/test_scaffold_leg_path_collisions.py	283 passed, 2 skipped (121, 60 and 104 collected)
tests/test_agents_md_codes.py, tests/test_cli_reference.py, tests/test_repo_hygiene.py	171 passed (47, 23 and 101)

The 2 skips are tests/test_no_auto_maintenance.py's, at line 222: "the session began with GIT_CONFIG_GLOBAL set, and its file includes that one". The probe environment sets GIT_CONFIG_GLOBAL=/dev/null.

What

On #1144's head, _leg_by_agents_md read any exception as "no leg's file" (except Exception: return None). The fixtures are clones of acme/Orbit whose AGENTS.md is the spec leg's or the code leg's file, rendered from its template, in two forms:

• link: the working-tree file is a link into a folder at mode 000;
• mode: the file itself is at mode 000.

Over either form, the doctor offered adopt-project.py plan ... --project Orbit in the way in and setup.sh in the other way in, and its Triad advisory said "This is a single repository". This held on 3.12 and on a 3.14-like shim, where Path.is_file, exists and the rest answer False to any OSError.

Base 89486f69 against head 0ca33611: shape-doctor.py --root <fixture>/Atlas, 32 runs, made at 0f9aff05. Re-run at 0ca33611, the 16 head reports are byte-identical to 0f9aff05's, paths normalised. In --json, the locked fixtures' the way in row now keeps origin_org: "acme" where 0f9aff05 gave null (4 of 4: spec and code, link and mode), and nothing else differs.

fixture (spec and code leg alike)	base	head
link, locked	what is here names AGENTS.md: cannot be read (Permission denied). the way in gives NEXT adopt-project.py plan, the other way in gives NEXT setup.sh, and an advisory Triad row says "This is a single repository". Exit 2.	what is here names it, with the cure. the way in gives the reason below and no NEXT. There is no the other way in row and no Triad row. Exit 2.
mode, locked	what is here says a git repository, an AGENTS.md. The adopt, scaffold and Triad rows are as above. Exit 2.	The same as link, locked.
readable (link and mode)	NAMED OR WRITTEN AS A LEG. The Triad row says "this is a clone of the R leg".	Byte-identical to base, paths normalised (8 of 8).

The new the way in reason: its AGENTS.md cannot be read, so it is not known whether this is a clone of a Triad's leg, which is not adopted or scaffolded on its own, and neither way in is offered until it can be: what is here says how.

At 0f9aff05, every report on 3.12 is byte-identical to its report under the shim (32 of 32). With paths normalised, the code leg's locked reports equal the spec leg's (16 of 16). The readable ones differ only in the leg's name.

In process (leg_clone and shape_advisory.read(), 3.12 and shim):

AGENTS.md	base	head
locked	read() is advise and leg_clone is False	read() is not-answered, with why AGENTS.md: cannot be read (Permission denied), so whether this is a leg clone is not known here, and the advisory says nothing, and leg_clone raises PermissionError
readable	leg-clone, True	leg-clone, True

adopt-project.py plan and check: 64 runs at 0f9aff05, equal on base and head, 3.12 and shim. Where git cannot give a commit's AGENTS.md, a folder named as a leg still gets the leg's note, as on base; with no such name, plan and check print no advisory, where base printed the advice. No fixture meets this. Adopt reads the commit's AGENTS.md, never the disk's, so a locked working-tree file changes nothing there. adopt-project.py is not changed.

The whole doctor report: spec leg, link, locked, 3.12

<standard> is the checkout and <fixture> the fixture's folder.

Base 89486f69:

root        <fixture>/Atlas
kind        not a shape root
standard    <standard>

  ok        naming            Atlas, Orbit: classifies under the naming policy
  n/a       what is here      AGENTS.md: cannot be read (Permission denied); a git repository
            NEXT              python3 <standard>/shape-doctor.py --root <fixture>/Atlas
            WHY               Make what this user may not open readable by this user: `chmod u+r` on a file, `chmod u+rx` on a directory (and on every directory above it inside the root), or fix who owns it. Then run this doctor again
  n/a       the way in        this is a git repository with no shape manifest: it is ADOPTED in place, keeping its name, identity and history
            NEXT              python3 <standard>/adopt-project.py plan --source <fixture>/Atlas --project Orbit
  n/a       the other way in  a NEW project is SCAFFOLDED instead of adopting this repository: it creates three repositories and asks first
            NEXT              <standard>/setup.sh --org <your-org> --project Orbit
            WHY               replace <your-org> with the GitHub organisation to create it in; without --yes, it asks
  advisory  Triad             This is a single repository. The Triad -- an assembly root with a spec leg and a code leg -- is the preferred project shape; preferred, not required: it confers nothing, and a single repository is reviewed identically. openRepoShape's adopt-project.py converts a repository in place when a person deciding for this project runs it, and a project that stays single can say so in single-repository.yaml. Nothing here changes; work continues.
  n/a       machine           this machine is missing something the fixes above may need (setup-project.py --preflight, exit 1): gh is not authenticated
            NEXT              python3 <standard>/setup-project.py --preflight
            WHY               it names each missing prerequisite and offers to install it, on a typed yes

NOT A SHAPE ROOT   (exit 2)
the machine check is `openRepoShape --preflight` now; `--doctor` is this report
exit 2

Head 0ca33611 (and 0f9aff05, byte for byte):

root        <fixture>/Atlas
kind        not a shape root
standard    <standard>

  ok   naming        Atlas, Orbit: classifies under the naming policy
  n/a  what is here  AGENTS.md: cannot be read (Permission denied); a git repository
       NEXT          python3 <standard>/shape-doctor.py --root <fixture>/Atlas
       WHY           Make what this user may not open readable by this user: `chmod u+r` on a file, `chmod u+rx` on a directory (and on every directory above it inside the root), or fix who owns it. Then run this doctor again
  n/a  the way in    its AGENTS.md cannot be read, so it is not known whether this is a clone of a Triad's leg, which is not adopted or scaffolded on its own, and neither way in is offered until it can be: `what is here` says how
  n/a  machine       this machine is missing something the fixes above may need (setup-project.py --preflight, exit 1): gh is not authenticated
       NEXT          python3 <standard>/setup-project.py --preflight
       WHY           it names each missing prerequisite and offers to install it, on a typed yes

NOT A SHAPE ROOT   (exit 2)
the machine check is `openRepoShape --preflight` now; `--doctor` is this report
exit 2

For mode, locked, base differs only in what is here, which says a git repository, an AGENTS.md with no NEXT or WHY. Head's report is the same as for link.

Why

• Only "nothing there" is no leg's file. _leg_by_agents_md follows 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's rule: an OSError whose errno says nothing is there answers None, as before. Those errnos are ENOENT, ENOTDIR, EBADF and ELOOP, and Windows' 21, 123 and 1921. Any other OSError is raised.
• Bytes that are not UTF-8 still declare no leg. This follows scripts/shape_advisory.py repository_names and shape-doctor.py origin_url and origin_name read git remote get-url origin through git_out and catch Refusal and OSError only, so an origin URL that is not UTF-8 makes read answer not-answered (a single repository loses the Triad advisory, a leg clone its pointer to the assembly root) and ends shape-doctor.py --root in a UnicodeDecodeError traceback, exit 1, where an ASCII origin gives NOT A SHAPE ROOT, exit 2 #385's rule against salvaging text that is not UTF-8; see Known limits.
• Anything else (a Refusal) ends in read()'s net, not-answered.
• A leg's name still answers. On a refused AGENTS.md, _read turns to _leg_by_name first, so a folder named as a leg is still leg-clone. Without a name, the answer is not-answered, and the refused OSError is kept in the new Reading.refused.
• So it does where git cannot give a commit's AGENTS.md. _read catches the Refusal of cat-file blob (in adopt-project.py's reading of a commit) as it catches a refused OSError. A folder named as a leg is leg-clone, as on base, so plan and check print the leg's note. With no such name, the Refusal goes on to read()'s net, not-answered. refused stays None, since no OSError was refused.
  • The .git not-answered carries refused too.
  • refused is not in as_dict, so as_dict keeps its keys.
• The doctor raises what the advisory could not read:
  • leg_clone raises reading.refused.
  • check_the_way_in asks leg_clone right after carries_git. On an OSError it gives way_in_unread_row("AGENTS.md", ...), a helper shared with the .git row, whose words are unchanged.
  • In --json, the AGENTS.md row keeps origin_org, as the leg's own row and the policy row keep it with no command. The .git row's stays None, since its origin is not read. suggested_project is None in both, since no --project is offered.
  • check_the_other_way_in is silent.
  • The reason for offering neither command: a leg is not adopted or scaffolded on its own, and whether this folder is a leg is not known.
• what is here reads the file through. The new read_through reads a regular AGENTS.md, so a file at mode 000, whose stat succeeds, is named there with the cure. It does not raise a read that finds nothing.
  • It reads a REGULAR file only. A directory or a named pipe called AGENTS.md is listed and not read. A read of the directory is refused (Is a directory), and the open of a pipe nobody writes to blocks the doctor for ever.
  • It reads AGENTS.md alone. Every other name is asked, as before.
• Helpers:
  • _nothing_there(exc) is now shared with _is_a;
  • _cannot_be_read(name, exc) spells both why lines from the strerror, or the exception's type name where there is none.

Tests

tests/test_doctor_unsearchable_links.py gains 24 rows, for 49 in all:

• 3 mode rows: 2 over a link into a folder at mode 000, 1 over a file at mode 000;
• 2 whole runs of the doctor, given 120 seconds each (doctor_within), over an AGENTS.md that is a directory and one that is a named pipe. A run that opens the pipe fails the row instead of hanging the suite. The pipe row skips where os.mkfifo is absent, and nothing opens the pipe in the test's own process;
• 19 in process.

Two of #1144's rows change:

• test_the_doctor_reads_the_advisory_as_silent now expects PermissionError from leg_clone over a refused .git, where it said False;
• test_the_advisory_names_a_git_it_cannot_reach_and_says_nothing also checks type(reading.refused) is type(error).

run	base 89486f69 (new file laid over)	head 0ca33611
3.12	17 failed, 32 passed	49 passed
3.14-like shim	17 failed, 32 passed (the same 17 tests)	49 passed

Every base failure is on the row's own assertion:

• an extra way-in-scaffold or triad-advisory row (7);
• DID NOT RAISE (4);
• 'Reading' object has no attribute 'refused' (3);
• 'advise' == 'not-answered' (2);
• what is here saying an AGENTS.md for a file at mode 000 where there is no repository, 'an AGENTS.md' == 'AGENTS.md: cannot be read (Permission denied)' (1).

The new controls pass on base:

• the leg by its name, where the disk's AGENTS.md is refused and where git cannot give the commit's;
• an AGENTS.md that is not there (dangling, gone before it is read, loop);
• an AGENTS.md that is a directory or a named pipe: listed, not read;
• a Makefile whose read is refused: listed like any other name;
• the not-UTF-8 decision rows.

Two of this round's changes are pinned by rows that fail without them:

• the row for a leg by its name where git cannot give its AGENTS.md fails on 0f9aff05 (not-answered);
• with origin_org back to None, the 7 rows that use no_leg_way_in fail (7 failed, 42 passed).

Mutants: 31, 28 killed. The 3 survivors are those the review accepted as equivalent. Each ran alone, in a clone, over tests/test_doctor_unsearchable_links.py on 3.12, and the file's bytes matched its HEAD blob after each one. N2, and M3 over its named-pipe row, ran at 0ca33611. The rest ran at e356013b, which differs from 0ca33611 only by one assertion in N2's row, a row no other mutant fails.

id	file	mutant	rows failed
A1	scripts/shape_advisory.py	refused read answers None	12
A2	scripts/shape_advisory.py	an absent errno raises too	1
A3	scripts/shape_advisory.py	the broad except put back	13
A4	scripts/shape_advisory.py	bytes that are not UTF-8 go to read()'s net	2
A5	scripts/shape_advisory.py	anything else is no leg's file	1
A6	scripts/shape_advisory.py	no turn to the name	1
A7	scripts/shape_advisory.py	a refused AGENTS.md falls through to the advice	12
A8	scripts/shape_advisory.py	refused not set for AGENTS.md	11
A9	scripts/shape_advisory.py	refused not set for .git	3
A10	scripts/shape_advisory.py	the exception's name for the system's reason	7
D1	shape-doctor.py	leg_clone does not raise	8
D2	shape-doctor.py	the way in falls through to the adoption	7
D3	shape-doctor.py	the AGENTS.md row said as the .git one	7
D4	shape-doctor.py	the other way in offers the scaffold over it	7
D5	shape-doctor.py	what is here does not read through	4
D6	shape-doctor.py	read_through raises a read that finds nothing	1
D7	shape-doctor.py	read_through only asks the stat	4
D8	shape-doctor.py	what is here reads through only in a repository	1
M3	shape-doctor.py	read_through reads any kind of file	2
M8	shape-doctor.py	the AGENTS.md row gives git_repository None	7
M9	scripts/shape_advisory.py	_cannot_be_read uses str(exc)	7
M10	shape-doctor.py	read_through only opens the file	3
M14	shape-doctor.py	what is here reads through every name	1
M16	scripts/shape_advisory.py	_leg_by_agents_md also catches ValueError	survived: equivalent, since UnicodeDecodeError is the only ValueError text() can raise
M18	shape-doctor.py	the other way in asks leg_clone first	survived: equivalent, since leg_clone raises a .git it cannot read as carries_git does, and is False where there is none
M18b	shape-doctor.py	the way in asks leg_clone first	3
M19	scripts/shape_advisory.py	_nothing_there drops the Windows arm	survived: Windows only, and CI is Linux only
N2	scripts/shape_advisory.py	a Refusal skips the name again (0f9aff05's _read)	1
N2b	scripts/shape_advisory.py	a Refusal with no leg's name falls through to the advice	1
N5	shape-doctor.py	the AGENTS.md row drops origin_org again	7
N5b	shape-doctor.py	way_in_unread_row ignores org	7

A1-A10 and D1-D8 are the writer's first 18. M3-M19 are the review's (r1), and N2-N5b are this round's. M3 fails both of its rows: the directory row on its assertion, and the named-pipe row on its timeout, Failed: the doctor did not end within 120 seconds over .../Atlas: something opened its AGENTS.md, after 126 s. The blocked doctor is killed, and no doctor process is left. A9 is caught only by #1144's two rows, which this change extends: no brand-new row catches it.

The gate, call by call (3.12 unless named, the probe environment, one basetemp per call, at 0ca33611):

call	result
tests/test_doctor_unsearchable_links.py	49 passed
tests/test_doctor_unsearchable_links.py, shim	49 passed
tests/test_shape_advisory.py, tests/test_path_guard_hygiene.py	96 passed (47 and 49)
tests/test_shape_doctor.py, shard 1 of 4	112 passed
tests/test_shape_doctor.py, shard 2 of 4	112 passed
tests/test_shape_doctor.py, shard 3 of 4	112 passed (215.6 s)
tests/test_shape_doctor.py, shard 4 of 4	109 passed, 3 skipped (82.0 s)
tests/test_doctor_next_is_a_command.py (names check_the_way_in)	61 passed (79.5 s)
tests/test_adopt_single_repository_record.py, test_bom_reads.py, test_bootstrap_non_utf8_branch.py, test_doctor_gitmodules_not_utf8.py, test_doctor_unreadable_paths.py, test_doctor_validator_verdicts.py, test_repo_hygiene.py (the rest of the files that name shape_advisory)	290 passed (162.4 s)

Known limits

• A leg's file that is not UTF-8 is still "no leg's file". This follows scripts/shape_advisory.py repository_names and shape-doctor.py origin_url and origin_name read git remote get-url origin through git_out and catch Refusal and OSError only, so an origin URL that is not UTF-8 makes read answer not-answered (a single repository loses the Triad advisory, a leg clone its pointer to the assembly root) and ends shape-doctor.py --root in a UnicodeDecodeError traceback, exit 1, where an ASCII origin gives NOT A SHAPE ROOT, exit 2 #385's rule. One example is a leg's AGENTS.md whose opening is intact ahead of a byte in a legacy code page; another is UTF-16. Over such a file the doctor still offers adoption and the Triad advisory, on base and head alike. Decoding the opening leniently was rejected, because scripts/shape_advisory.py repository_names and shape-doctor.py origin_url and origin_name read git remote get-url origin through git_out and catch Refusal and OSError only, so an origin URL that is not UTF-8 makes read answer not-answered (a single repository loses the Triad advisory, a leg clone its pointer to the assembly root) and ends shape-doctor.py --root in a UnicodeDecodeError traceback, exit 1, where an ASCII origin gives NOT A SHAPE ROOT, exit 2 #385 forbids salvaging text that is not UTF-8. The rows test_a_leg_agents_md_that_is_not_utf8_declares_no_leg[a-legacy-byte-after-the-opening] and [utf-16] hold this behaviour, and mutant A4 shows they catch a change to it.
• leg_clone now raises over a refused .git, where shape-doctor.py and shape_advisory.py: a .git or an agent file linked into a folder this user cannot search is said once in what is here or agent files, <name>: cannot be read (<reason>), never absent; a .git offers no way in (#1110) #1144's row said False. Both callers ask carries_git first, so no report changes.

Not in this PR

• A committed symlink AGENTS.md. adopt-project.py's commit reader reads it as its target's path, so plan and check say "This is a single repository" over a link to a leg's file, readable or not. Meanwhile the doctor, which reads the disk, calls the same checkout a leg. This is the same on base and head. Filed as shape_advisory.py: a committed AGENTS.md that is a symlink is read, in adopt-project.py's commit reading, as the text of its target's path, so a leg cloned with its AGENTS.md as a link is told it is a single repository #1163.

Lane: openreposhape-1 (openRepoShape-1)

🤖 Generated with Claude Code

Summary by Sourcery

Prevent the doctor from offering adoption or scaffolding when an unreadable AGENTS.md leaves a repository's Triad-leg status unknown.

Bug Fixes:

• Treat unreadable leg AGENTS.md files as unknown rather than as evidence that a repository is not a Triad leg, preventing inappropriate adoption and scaffolding suggestions.
• Report unreadable AGENTS.md files in what is here with actionable permission details while preserving leg detection by directory name.
• Keep unreadable repository and leg metadata reads silent in unrelated advisory rows and propagate the underlying refusal when callers need to explain it.

Enhancements:

• Refine advisory read outcomes to distinguish absent files, invalid UTF-8, and access refusals, including carrying refused operating-system errors through the reading model.
• Add regular-file-only read-through behavior for AGENTS.md and preserve existing behavior for directories, named pipes, missing files, and non-UTF-8 content.

Tests:

• Add coverage for unreadable leg files through inaccessible links, file permissions, mocked I/O failures, and commit-read refusals.
• Add controls for named legs, absent or non-regular AGENTS.md files, non-UTF-8 content, and ensuring adoption reads committed rather than working-tree metadata.

[sourcery-ai]

Reviewer's Guide

Data structures

Add Reading.refused to carry an operating-system refusal for callers that need to name it, without changing the serialized advisory interface.

• scripts/shape_advisory.py L319-329, L336

Implementation

Centralize the distinction between an absent path and a refused read, and apply it consistently to path checks and leg AGENTS.md reads.

• scripts/shape_advisory.py L363-377, L417-420, L592-623 (+1 small edits)

Carry refused .git and leg-file reads through _read, while preserving name-based leg identification and returning silence when the leg remains unknown.

• scripts/shape_advisory.py L140-149, L855-858, L866-889

UI

Read a regular AGENTS.md through in “what is here” so a refused file is named, and make leg_clone propagate the advisory's refusal.

• shape-doctor.py L11366-11383, L11403-11410, L11761-11777 (+1 small edits)

Make “the way in” offer neither command when a leg's identity is unknown because its AGENTS.md cannot be read, and keep the other-way-in row silent.

• shape-doctor.py L11845-11854, L11860-11870, L11910-11931 (+1 small edits)

Tests

Add regression and control coverage for refused leg files, absent or non-regular files, UTF-8 handling, name-based identification, doctor output, and commit-based reads.

• tests/test_doctor_unsearchable_links.py L275-378, L479-526, L812-1090 (+7 small edits)

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[brettheap]

(lane openRepoShape-1, 2026-10-22T15:30:29Z) Independent review r1159 of #1159 at 0f9aff05: NOT READY, two SHOULDs and five NITs; no MUST. The code measured correct. SHOULD-2 is a missing control row: without it, a mutant of read_through makes the doctor hang on a FIFO named AGENTS.md. Lane 1 runs the fix round in the next window. It was started by r1159 and finished by r1159-c across an account swap.

Review of PR #1159 (head 0f9aff0, base #1144's head 89486f6)

Verdict: NOT READY. The code is correct as I measured it, and nothing is a MUST. Two SHOULDs are left: one PR-body edit and one missing control row in the tests. There are also five NITs.

I stopped at your LAST STEP word. The mutant that was already running (M18b) finished and restored itself, and I started nothing after it. mut0, mut1 and the review checkout are all at 0f9aff0 with status --short empty. After every mutant, the file matched its HEAD blob again. None of my runs is still live; the pytest processes left on the box belong to w1136 and w1138. The live PR still matches the copy we saved: same head and base, still a draft, closingIssuesReferences is [], and the body is byte-equal to body.md.

Findings

SHOULD-1: PR body, "Not in this PR", lines 181-183

• Evidence: it still says "Lane 1 files it as a follow-up, under the title: > ...", but the committed-symlink case is now filed as shape_advisory.py: a committed AGENTS.md that is a symlink is read, in adopt-project.py's commit reading, as the text of its target's path, so a leg cloned with its AGENTS.md as a link is told it is a single repository #1163.
• Fix: replace that sentence and its quote with "Filed as shape_advisory.py: a committed AGENTS.md that is a symlink is read, in adopt-project.py's commit reading, as the text of its target's path, so a leg cloned with its AGENTS.md as a link is told it is a single repository #1163." Do not use "closes" or "fixes".

SHOULD-2: shape-doctor.py line 11168. No test row protects the regular-file check in read_through, and without it the doctor can hang.

• Evidence: mutant M3 changes that check to is_a(path, lambda _m: True), and all 45 rows still pass. I ran the doctor with M3 applied over a repository whose AGENTS.md is:
  • a FIFO: the doctor never returns (timeout 30 ended it with exit 124);
  • a directory: what is here wrongly says AGENTS.md: cannot be read (Is a directory); a git repository.
• Head and base both give a git repository, an AGENTS.md for these two cases, exit 2. read_through is new in this PR, so this one check is all that stops a hang.
• Fix: add a control row to tests/test_doctor_unsearchable_links.py, next to test_an_agents_md_that_is_not_there_is_no_legs_file (line 874). Use a repository whose AGENTS.md is a directory (all platforms) and a FIFO (os.mkfifo, skipped where it does not exist). Assert:
  • contents.reason == "a git repository, an AGENTS.md";
  • no row says cannot be read;
  • offered_both_ways_in.
• Run the FIFO case through the subprocess doctor() with a timeout, so a regression fails instead of hanging the suite.

NIT-1: PR body, Tests, line 110

• Evidence: "3 over a file at mode 000" is wrong. Two of the three mode rows are a link into a folder at 000 ([spec|code]), and only one is a file at 000. The total of 3 + 17 = 20 is right.
• Fix: "3 mode rows (2 over a link into a folder at mode 000, 1 over a file at mode 000) and 17 in process".

NIT-2: scripts/shape_advisory.py _read, lines 861-876. A Refusal no longer falls back to the leg's name, which base did.

• Evidence: I measured this with probes/nit2_probe.py on fx/named-spec/Orbit-spec, with Tree.text("AGENTS.md") raising Refusal:
  • base: leg-clone, found by its name;
  • head: not-answered, "the advisory could not be read here (Refusal)".
• Effect: when cat-file blob fails while reading a commit, adopt-project.py no longer prints the leg's note for a folder named <P>-spec.
• Fix: add except Refusal: leg = _leg_by_name(names, policy); if leg is None: raise ahead of except OSError. This is mutant M17, and it keeps all 45 rows green. Or name the case in Known limits instead.

NIT-3: PR body, Tests, lines 118 and 120-125. Base figures are stale and incomplete.

• Evidence:
  • The shim row says "16 failed, 28 passed (44 rows, before the 45th was added)". On 45 rows it is now 17 failed, 28 passed: the same 17 tests that fail on 3.12.
  • The list of failure kinds leaves out 'an AGENTS.md' == 'AGENTS.md: cannot be read (Permission denied)', from test_an_agents_md_nobody_may_open_is_named_where_there_is_no_git.
• Fix: change the shim row to "17 failed, 28 passed", and add a bullet for what is here saying an AGENTS.md where there is no repository.

NIT-4: shape-doctor.py line 11225. Nothing pins that only AGENTS.md is read through.

• Evidence: mutant M14 reads through every listed name (if there:), and all 45 rows pass.
• Fix: add an in-process control row in a leg clone that refuses the read of Makefile (refusing(monkeypatch, "read_bytes", "Makefile", PermissionError(...))). Assert that contents lists a Makefile like any other name and that no row says cannot be read.

NIT-5: shape-doctor.py lines 11658 and 11703 (way_in_unread_row). The AGENTS.md row drops origin_org even though it is known.

• Evidence: in head's --json for link-spec, locked, the way-in detail has origin_org: null, while the naming row in the same run reads origin Orbit. The leg's own row (11663-11677) keeps origin_org: org even though it offers no command either. So the docstring's reason, "None because no command is offered with them", does not hold.
• Fix (optional): pass origin_org(root) into the AGENTS.md row, or say in the docstring that the row keeps the .git row's values. The no_leg_way_in assertion (about line 320) pins the current value, so change both together.

Observations, not findings

• In a repository, a person's own non-leg AGENTS.md that cannot be read now withholds both ways in (fixture person-x). This is by design.
• In named-spec, locked, the name says the spec leg while the unreadable file is the code leg's. The sentence is hedged ("if it is one"), and the report is the same on base and head.

Mutants

Each ran alone in a clone, on 3.12, over tests/test_doctor_unsearchable_links.py:

id	mutant	result
M3	read_through reads any kind of file	survived: SHOULD-2
M8	AGENTS.md row gives git_repository None	killed, 7 rows
M9	_cannot_be_read uses str(exc)	killed, 7 rows
M10	open('rb').close() instead of read_bytes()	killed, 3 rows
M14	what is here reads through every name	survived: NIT-4
M16	_leg_by_agents_md also catches ValueError	survived, accepted as equivalent: UnicodeDecodeError is the only ValueError that text() can raise
M17	NIT-2's fix	stays green, 45 passed
M18	check_the_other_way_in asks leg_clone first	survived, accepted as equivalent
M18b	check_the_way_in asks leg_clone first	killed, 3 .git rows, so the order the body relies on is pinned
M19	_nothing_there drops the Windows arm	survived, accepted: Windows only, and CI is Linux only

Test counts

run	result
links tests, head, 3.12	45 passed
links tests, head, shim	45 passed
links tests, base with the new file, 3.12	17 failed, 28 passed
links tests, base with the new file, shim	17 failed, 28 passed (the same 17 tests)
tests/test_shape_advisory.py, head	47 passed
tests/test_path_guard_hygiene.py, head	49 passed, as the body says

Every base failure is on the row's own assertion. The control rows (leg by name, AGENTS.md not there, not UTF-8) pass on base.

Doctor-report comparison

256 report files, paths normalised.

• Errors: no Traceback, and every .err file is empty.
• 3.12 against the shim: identical in all 32 pairs (text, --json and exit code).
• Base against head:
  • The readable reports are equal for all 8 fixtures.
  • Locked, named-spec and gitlink-spec are equal. For gitlink-spec, carries_git is asked first, so the .git change alters no report.
  • Locked, link-*, mode-* and person-x change exactly as the body's table says: no NEXT in the way in, and no the other way in row or Triad row. Exit 2 on both sides.
  • Locked, plain-x: head now names AGENTS.md: cannot be read (Permission denied) with the cure, and still offers the scaffold.
• Spec against code, and link against mode (locked, head): byte-equal. On base, mode differs from link only in what is here, as the body's line 88 says.
• The body's two whole-report blocks match the measured reports line for line, except the machine row. That difference comes from this bench, where git-filter-repo is not on PATH.

Greps and static checks

• Nothing uses vars( or __dict__ on a Reading, and .refused is read only at shape-doctor.py lines 11568-11569.
• leg_clone has two callers, and both catch OSError.
• I found no version-dependent assertion.
• The body has no closing keyword before an issue number and no HTML tag outside code. Its only non-ASCII character is the emoji in the attribution line.

Not done (outside this review's list): a re-run of the writer's 18 mutants, and the test_shape_doctor shards and the other gate files.

Files

• /workspace/projects/openRepoShape-worktrees/_lane1-scratch/r1159/review-r1-partial2.md — this review
• /workspace/projects/openRepoShape-worktrees/_lane1-scratch/r1159/probes/mutants.py
• /workspace/projects/openRepoShape-worktrees/_lane1-scratch/r1159/probes/mut.sh
• /workspace/projects/openRepoShape-worktrees/_lane1-scratch/r1159/probes/m3_probe.sh
• /workspace/projects/openRepoShape-worktrees/_lane1-scratch/r1159/probes/nit2_probe.py
• /workspace/projects/openRepoShape-worktrees/_lane1-scratch/r1159/logs/ — mut-*.log and mut-*.diff
• /workspace/projects/openRepoShape-worktrees/_lane1-scratch/r1159/fx2/ — fifo-x holds a FIFO named AGENTS.md, so anything that reads it will block
• /workspace/projects/openRepoShape-worktrees/_lane1-scratch/r1159/runs2/

Lane: openreposhape-1 (openRepoShape-1)

[brettheap]

(lane openRepoShape-1, 2026-10-22T20:18:30Z) Independent re-check r1159b of #1159 at 0ca33611, after f1159's fix round: READY. Every r1159 finding is answered, and there is no new MUST or SHOULD. Two NITs are optional. Landing still needs GitHub's Linux tests job green on this head, and #1159 lands only after #1144, after the v1.2.0 tag, on a later word.

Verdict: READY. f1159's round answers every finding from r1159 (SHOULD-1, SHOULD-2 and NITs 1 to 5). My measurements show no new MUST or SHOULD. Two optional NITs are below.

One thing outside the PR: GitHub's Linux tests job for head 0ca33611 was still "pending" at 20:17Z. SonarCloud, package and tests-git-bash pass. Landing still needs that job green.

The live PR still matches what we expected: head 0ca336110b67…, base fix/1110-doctor-advisory-unsearchable-git, still a draft, closingIssuesReferences: [], last updated 19:50:38Z.

The r1 findings

• SHOULD-1: answered. Body line 210 now reads "Filed as shape_advisory.py: a committed AGENTS.md that is a symlink is read, in adopt-project.py's commit reading, as the text of its target's path, so a leg cloned with its AGENTS.md as a link is told it is a single repository #1163." gh issue view 1163 gives OPEN, titled "shape_advisory.py: a committed AGENTS.md that is a symlink is read, … as the text of its target's path …". No close or fix form is used.

• SHOULD-2: answered. test_an_agents_md_that_is_no_regular_file_is_listed_and_not_read[directory|named-pipe] runs the doctor through doctor_within with a 120 s limit. I re-ran M3 (read_through reads any kind of file) in clone h, restoring the file in a finally. Result: 2 failed, 47 passed in 146.97 s, and the restored blob equals HEAD's.

  • The directory row fails on its own assertion: 'AGENTS.md: cannot be read (Is a directory); a git repository' against 'a git repository, an AGENTS.md'.
  • The pipe row fails with Failed: the doctor did not end within 120 seconds over …/bt-mut-M3/…/Atlas: something opened its AGENTS.md, raised from subprocess.TimeoutExpired.
  • The blocked doctor was killed. Its command line holds the basetemp path, and pgrep -af r1159b/bt-mut found nothing left afterwards.
  • The row cannot hang the run on head: the whole file takes 27 s. Nothing in the test's own process opens the pipe, and the advisory's Tree.text returns None for anything that is not S_ISREG.
  • Both rows pass on base 89486f69, so they are true controls.

• NIT-1: answered. Body line 116: "3 mode rows: 2 over a link into a folder at mode 000, 1 over a file at mode 000".

• NIT-2: answered. _read now has except Refusal: leg = _leg_by_name(...); if leg is None: raise ahead of except OSError. Refusal subclasses Exception, not OSError, so the bare raise reaches read()'s net. I probed it with r1159b/probes/nit2.py, making cat-file blob …:AGENTS.md raise Refusal:

  folder	head 0ca33611	base 89486f69
  Orbit-spec (a leg's name)	leg-clone, by name	leg-clone, by name
  Atlas (no leg's name)	not-answered, "the advisory could not be read here (Refusal), so it says nothing"	advise

  The only source of a Refusal there is Tree.text's cat-file blob, because kind() catches its own. Two mutants confirm the rows hold it:

  • N2 (except Refusal disabled) kills only the new row test_a_leg_by_its_name_is_one_while_git_cannot_give_its_agents_md (1 failed, 48 passed).
  • N2c (no re-raise) kills only test_a_failure_the_leg_reader_does_not_expect_is_silence_not_advice (1 failed, 48 passed).

• NIT-3: answered. Body line 128 now says "17 failed, 32 passed (the same 17 tests)", and line 136 adds the 'an AGENTS.md' == … bullet. I sorted my 17 base failures by their assertion and got the body's split exactly: 7 extra-row, 4 DID NOT RAISE, 3 no refused, 2 advise/not-answered, 1 an AGENTS.md.

• NIT-4: answered. I re-ran M14 (what is here reads through every name) in clone h2, restoring in a finally: 1 failed (test_what_is_here_reads_through_agents_md_alone), 48 passed, and the blob was restored.

• NIT-5: answered. way_in_unread_row takes org. The AGENTS.md call passes origin_org(root), and the .git call passes None. The new docstring is now correct: the leg's own row (line 11699) and the policy row (11677) both keep origin_org with no command.

  • origin_org is only reached after carries_git succeeds, so it brings no new raise path.
  • Mutants N5 (pass None again), N5b ("origin_org": None inside the helper) and M8 each give 7 failed, 42 passed.
  • No .md file in the repo names origin_org, so no doc goes stale.

New problems

None at MUST or SHOULD.

• Behaviour: except Refusal changes the answer only in adopt-project.py's commit reading, and only where a leg's name answers. That case goes back to base's answer.
• Rows passing for the wrong reason: none. Each new row is killed by the mutant aimed at it: M3 by the directory and pipe rows, M14 by the Makefile row, N2 by the leg-by-name row. All four new rows pass on base.
• Version-dependent asserts: none. The new asserts compare row reasons and detail keys only, and "Is a directory" appears only in docstrings. Head under the 3.14-like shim gives 49 passed; I confirmed the shim loads (pathlib._w1110c_shim True).
• NIT-A, PR body line 35, optional. The sentence "This round changes adopt-project.py's reading only where git cannot give a commit's AGENTS.md" talks about the review round, and the base-to-head change it hides is never stated. That change: with no leg's name, plan and check go from the advice on base to silence on head. Fix: replace it with "Where git cannot give a commit's AGENTS.md, a folder named as a leg still gets the leg's note, as on base. With no such name, plan and check print no advisory, where base printed the advice. No fixture meets this."
• NIT-B, tests/test_doctor_unsearchable_links.py lines 1045-1046, optional. The backticked row name is broken across the line as …_cannot_ / be_read, so a grep for test_a_leg_by_its_name_is_one_while_its_agents_md_cannot_be_read (line 885) does not find this reference. Fix: break the line before the backticks.

Measurements

Everything ran on 3.12 in the probe environment, one basetemp per call, at most 2 calls at once.

run	result
links file, head 0ca33611	49 passed (27 s)
links file, head, shim	49 passed
links file, base 89486f69 + head's test file	17 failed, 32 passed
links file, base + head's test file, shim	17 failed, 32 passed, the same 17 (diff empty)
links file, 0f9aff05 + head's test file	8 failed (the leg-by-name row and the 7 origin_org rows), 41 passed. This bears out body lines 148-149.
tests/test_shape_advisory.py + tests/test_path_guard_hygiene.py, head	96 passed; collected 47 and 49, as body line 195 says

Mutants I re-ran at 0ca33611. After every one, the file's blob equalled HEAD's.

mutant	result
M3	2 failed
M14	1 failed
N2	1 failed
N2c	1 failed
N5	7 failed
N5b	7 failed
M8	7 failed

These all match the body's table.

The body's gate rows I did not re-run: the test_shape_doctor shards, test_doctor_next_is_a_command and the 7-file list. f1159's logs for them in w1110c/logs agree with the body (112, 112, 112, 109+3 skipped, 61, 290). All are timed 19:40-19:50Z, after 0ca33611's commit at 19:34:02Z, and l1-1110c is at 0ca33611 with a clean tree. I also did not re-run the whole-report blocks; the rows hold their structure.

PR body: title 245 characters; no close, fix or resolve form before an issue number; no @; the only non-ASCII character is the emoji.

State: my checkout l1-r1159 is clean at 0ca33611. Mutant clones h and h2 are clean. Clones b and p carry the overlaid test file, as intended. No process of mine is running.

Files

All in /workspace/projects/openRepoShape-worktrees/_lane1-scratch/r1159b:

• body.md: the live PR body, as read
• pr-meta.json
• probes/mut.py: the mutant runner, which restores in a finally and checks the blob
• probes/nit2.py
• logs/:
  • links-head-312.log, links-head-shim.log
  • links-base-312.log, links-base-shim.log, links-0f9-newfile.log
  • mut-M3.log, mut-M14.log, mut-N2.log, mut-N2c.log, mut-N5.log, mut-N5b.log, mut-M8.log
  • gate-adv-hyg.log
• penv.sh, run.sh, and the clones h, h2, b, p

Lane: openreposhape-1 (openRepoShape-1)

[brettheap]

(lane openRepoShape-1, 2026-10-24T14:43:48Z) d1159, lane 1's independent delta checker (not the writer): READY carries from 0ca33611 to 66e68f94, with no MUST, no SHOULD and three NITs.

• 66e68f94 is one commit. It rewraps one docstring in tests/test_doctor_unsearchable_links.py (r1159b's NIT-B).
  • Every other file is byte-identical, and the test file's AST is equal with docstrings blanked.
  • At 66e68f94: the links file gives 49 passed on 3.12 and under the 3.14-like shim. Base gives 17 failed and 32 passed, the same set as r1159b's.
  • The advisory file and the two scans give 154 passed and 2 skipped. 4 spot-check mutants were all killed.
• NITs, none blocking:
  • NIT-1: the body does not name 66e68f94. Lane 1 adds one sentence before landing.
  • NIT-2: the commit message says a grep finds the row, but only the suffix is greppable.
  • NIT-3: one curly quote, in the Sourcery block.
• 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: READY (issuecomment-6371395973) names its current head 74096eb4, with no commit since. The landing checks its merge with 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 new head 569ea056.
• shape_advisory.py and shape-doctor.py: a leg's AGENTS.md this user cannot read leaves whether it is a leg unknown, so the way in offers neither command and points at what is here, and the other way in and the Triad row are silent (#1110) #1159 still lands after shape-doctor.py and shape_advisory.py: a .git or an agent file linked into a folder this user cannot search is said once in what is here or agent files, <name>: cannot be read (<reason>), never absent; a .git offers no way in (#1110) #1144, with the three-merge restack after shape-doctor.py and shape_advisory.py: a .git or an agent file linked into a folder this user cannot search is said once in what is here or agent files, <name>: cannot be read (<reason>), never absent; a .git offers no way in (#1110) #1144's squash.

The full delta check

d1159 report

Part 1 is complete: READY carries from 0ca33611 to 66e68f94, with three NITs and no MUST or SHOULD.

Part 2 is partial. #1164's head has not moved since the review that names it, and I re-measured nothing on it. I stopped at lane 1's LAST STEP. No runs of mine are live.

Part 1: #1159 (0ca33611..66e68f94)

Commit table

commit	parents	what it changes	only what its message says?
66e68f948 "tests/test_doctor_unsearchable_links.py: the docstring of the control row names its sibling row on one line, so a grep for the row's name finds the reference (#1110)"	0ca336110 (one parent, not a merge)	One file, +4/-3. It rewraps the docstring of test_a_leg_by_its_name_is_one_while_git_cannot_give_its_agents_md, so the backticked row name sits on one line. This is r1159b's NIT-B.	Yes for the change. See NIT-2 for the grep wording in the message.

Commands and output:

• git log --format='%h %p %s' 0ca33611..66e68f94 prints that one commit. git rev-list --count gives 1 and --merges gives 0.
• git diff --name-only 0ca33611 66e68f94 prints tests/test_doctor_unsearchable_links.py alone.
• Every other file is byte-identical. A hash of git ls-tree -r, with that file excluded, is f8d8b6d9858e3836c015e86ffb7d380cc6fc6290 at both commits. So shape-doctor.py and scripts/shape_advisory.py did not change.
• The AST of the old and new test file, with docstrings blanked, is equal: AST equal with docstrings blanked: True. Exactly one docstring differs, and the old and new texts are equal after whitespace normalisation and healing the _ be_ break. Only one string constant differs, and the file is one line longer (1089 to 1090).
• Nothing in the repo cites a line number of the file (grep for test_doctor_unsearchable_links.py:[0-9] finds nothing).
• No added line is non-ASCII or over 80 characters.

The delta is not a behaviour change, so the brief's "at least 3 mutants of the changed lines" does not strictly apply. I ran 4 spot-check mutants anyway, to show the rows still bite at 66e68f94.

Test runs

Run in the probe environment: stub gh, bogus token, empty GH_CONFIG_DIR, GIT_CONFIG_GLOBAL=/dev/null, GIT_SSH_COMMAND=false, env -u LANES_LANE, one basetemp per call, at most 2 calls at once. I ran df -h /workspace and df -i / and counted pytest processes before each call; the minimum free was 16G.

call	result
links file at 66e68f94, 3.12	49 passed (149.8 s)
links file at 66e68f94, 3.14-like shim	49 passed (147.6 s)
tests/test_shape_advisory.py, tests/test_path_guard_hygiene.py, tests/test_no_auto_maintenance.py at 66e68f94	154 passed, 2 skipped (280 s). The collect counts are 47 + 49 + 60 = 156.
base 89486f69 plus head's test file, 3.12	17 failed, 32 passed
base 89486f69 plus head's test file, shim	17 failed, 32 passed

Base comparison:

• The failing set on 3.12 equals r1159b's set at 0ca33611 (diff empty), and the shim's set equals the 3.12 set.
• The base file has 25 rows and head has 49, so "gains 24 rows" is right.
• The shim was loaded: shim loaded: True. On a file inside a mode-000 folder, plain 3.12 is_file raises PermissionError and the shim answers False.

GitHub checks on 66e68f94: tests, tests-git-bash, package and SonarCloud all completed with success.

Mutants

Spot-check, not required by the delta. Run on 3.12 in a clone at 66e68f94. Each file was restored in a finally, and the blob matched HEAD's afterwards.

mutant	file	rows failed	blob restored
M3: read_through reads any kind of file	shape-doctor.py	2 failed, 47 passed (directory row and named-pipe row)	True
N2: except Refusal disabled	scripts/shape_advisory.py	1 failed (..._by_its_name_is_one_while_git_cannot_give_its_agents_md), 48 passed	True
N5: the AGENTS.md way-in row drops origin_org	shape-doctor.py	7 failed, 42 passed	True
M14: what is here reads through every name	shape-doctor.py	1 failed (test_what_is_here_reads_through_agents_md_alone), 48 passed	True

All 4 were killed, with the same counts as the body's table. After M3 no stray doctor process was left over the FIFO.

The body

• Closing form. Exactly one: line 1, Part of #1110. closingIssuesReferences is []. A regex for close, fix or resolve before an issue number finds nothing. The only other #N forms are "Filed as shape_advisory.py: a committed AGENTS.md that is a symlink is read, in adopt-project.py's commit reading, as the text of its target's path, so a leg cloned with its AGENTS.md as a link is told it is a single repository #1163" (line 210) and mentions of scripts/shape_advisory.py repository_names and shape-doctor.py origin_url and origin_name read git remote get-url origin through git_out and catch Refusal and OSError only, so an origin URL that is not UTF-8 makes read answer not-answered (a single repository loses the Triad advisory, a leg clone its pointer to the assembly root) and ends shape-doctor.py --root in a UnicodeDecodeError traceback, exit 1, where an ASCII origin gives NOT A SHAPE ROOT, exit 2 #385, 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 and shape-doctor.py and shape_advisory.py: a .git or an agent file linked into a folder this user cannot search is said once in what is here or agent files, <name>: cannot be read (<reason>), never absent; a .git offers no way in (#1110) #1144. There is no @.
• Stacking. Right. The base is fix/1110-doctor-advisory-unsearchable-git, shape-doctor.py and shape_advisory.py: a .git or an agent file linked into a folder this user cannot search is said once in what is here or agent files, <name>: cannot be read (<reason>), never absent; a .git offers no way in (#1110) #1144's head is still 89486f69, and shape-doctor.py and shape_advisory.py: a .git or an agent file linked into a folder this user cannot search is said once in what is here or agent files, <name>: cannot be read (<reason>), never absent; a .git offers no way in (#1110) #1144 is open.
• Live PR. Head is 66e68f94, still a draft, 6 commits, title 245 characters. The body is byte-equal to the copy I read at the start.
• Claims about the new commit. There are none. See NIT-1.

Findings

No MUST and no SHOULD.

NIT-1: the PR body does not name the delta.

• PR body lines 16, 67, 125, 151 and 189 label head, "Head 0ca33611" and the measurements "at 0ca33611". The body names neither 66e68f94 nor a docstring-only commit ('66e68f94' in body is False, and so is "docstring").
• All of those measurements still hold. I re-measured the counts that matter at 66e68f94 (49/49, 17/32, 47 + 49).
• Fix: add one sentence, for example "66e68f94 changes one docstring in tests/test_doctor_unsearchable_links.py and nothing else (r1159b's NIT-B); every figure above carries from 0ca33611."

NIT-2: the commit message overstates the grep claim.

• tests/test_doctor_unsearchable_links.py:1046 now reads `..._by_its_name_is_one_while_its_agents_md_cannot_be_read`). It stays abbreviated with ..._.
• grep -n "test_a_leg_by_its_name_is_one_while_its_agents_md_cannot_be_read" finds only the def at line 885. That is r1159b's own example string. A grep for the suffix by_its_name_is_one_while_its_agents_md_cannot_be_read finds both lines 885 and 1046.
• r1159b's fix, "break the line before the backticks", was applied as asked, so the NIT is answered as asked.
• Optional fix: spell the full test_a_leg_by_... name in the docstring.

NIT-3 (observation): non-ASCII in the body.

• The body holds one ' (U+2019) besides the emoji. It is in the Sourcery-generated block ("doctor's"), not in lane text.
• r1159b said the emoji was the only non-ASCII character. If the squash message is cut from that block, replace it.

Not covered in Part 1

• I did not re-run the test_shape_doctor shards, test_doctor_next_is_a_command, the 7-file list, the doc trio, or the doctor-report comparison. Their inputs are unchanged: all non-test files are byte-identical, and the test file is AST-equal apart from one docstring. They carry from 0ca33611.
• I did not check landing mechanics. shape_advisory.py and shape-doctor.py: a leg's AGENTS.md this user cannot read leaves whether it is a leg unknown, so the way in offers neither command and points at what is here, and the other way in and the Triad row are silent (#1110) #1159 still lands after shape-doctor.py and shape_advisory.py: a .git or an agent file linked into a folder this user cannot search is said once in what is here or agent files, <name>: cannot be read (<reason>), never absent; a .git offers no way in (#1110) #1144, after the v1.2.0 tag, on a later word. A stacked PR after its parent's squash needs the three-merge procedure.

Part 2: #1164 (read-only checks, no test or mutant run)

• The review names the current head. issuecomment-6371395973 (brettheap, 2026-10-23T17:59:47Z) says "READY at 74096eb4". The PR head is 74096eb4783384ec46b366f9d6098426a5aa9f28, the full sha the brief gives.
• No commits after the named head. gh pr view lists 7 commits, from 4352ac2fd to 74096eb47. The last was committed 2026-10-23T07:41:46Z, before the review at 17:59Z. There are no GitHub reviews and no review comments. So there is no delta to check, and the READY carries by identity.
• GitHub checks on 74096eb4: SonarCloud, package, tests and tests-git-bash all completed with success.
• The body took r1164c's two NITs.
  • Line 113 now says "PR 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 for bootstrap.py, and the family root's validate-family.py, bootstrap.py and siblings.py: a root whose own .git this user cannot read is a PermissionError traceback on 3.12, or not-a-git-repo where exists() answers False, not refused by name #1148, now at 5aa0f116", with the merge-tree quoted at 74096eb47. 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 current head is 5aa0f116d, so that matches.
  • Lines 84 and 90 now say "(4 at 74096eb47, with the family.yaml rows)".
• Closing form. Line 1 is Part of #1110, and closingIssuesReferences is []. I read the body for other close, fix or resolve forms and saw none, but I did not run a regex on it. The title is 249 characters.

Flags, not findings

• Body line 113 says "this head merges with b75babee3 cleanly". 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 head is now 569ea0565. It was b75babee when r1164c measured, and I did not check when it moved. I did not run git merge-tree against 569ea0565.
• 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 base 038dafba9 is 20 commits behind main (compare says diverged, ahead 7, behind 20), and mergeable_state reads unknown. I did not test a merge with the current main.
• Suggested check for lane 1: git merge-tree --write-tree --name-only 74096eb47 569ea0565, and the same against main.

Not covered in Part 2: I re-ran no tests, mutants, gate rows or pin measurements. I did not diff #1164 against anything, because there is no later commit.

State

• Review checkout /workspace/projects/openRepoShape-worktrees/l1-d1159: detached at 66e68f94, status --short empty.
• Scratch clones m and m2 are at 66e68f94 and clean. Clone b is at base 89486f69 and carries the head test file overlaid, plus an untracked tests/test_zzbase_links.py (I run no rm). Both are intentional.
• No process of mine is running.

Files

All in /workspace/projects/openRepoShape-worktrees/_lane1-scratch/d1159/:

• checkpoint.md
• logs/ (the run logs: links-head-312.log, links-head-shim.log, links-base-312.log, links-base-shim.log, gate-adv-hyg-nam.log, mut-M3.log, mut-N2.log, mut-N5.log, mut-M14.log)
• probes/mut.py
• shim/sitecustomize.py
• penv.sh, run.sh
• body.md, body1164.md, pr-meta.json, pr-view.json, pr1164.json

Lane: openreposhape-1 (openRepoShape-1)

Lane: openreposhape-1 (openRepoShape-1)

[brettheap]

(lane openRepoShape-1, 2026-11-08T15:21:59Z) Lane 1's delta check of #1159 after #1144 landed: the restack to 5370b018 leaves this PR's own change byte for byte as reviewed, so READY carries to 5370b018.

• Three merges, with no rebase and no force-push:
  1. 9d93487d merges shape-doctor.py and shape_advisory.py: a .git or an agent file linked into a folder this user cannot search is said once in what is here or agent files, <name>: cannot be read (<reason>), never absent; a .git offers no way in (#1110) #1144's final head 5b38c3a3.
  2. ab31e2e5 merges shape-doctor.py and shape_advisory.py: a .git or an agent file linked into a folder this user cannot search is said once in what is here or agent files, <name>: cannot be read (<reason>), never absent; a .git offers no way in (#1110) #1144's squash b1f45fa7, taking this branch's side for its four files. Its tree is merge 1's, c5d0bc70.
  3. 5370b018 merges main 0d5704b3 cleanly.
• The delta: the +/- lines of 89486f69..66e68f94 (the reviewed delta) and of 0d5704b3..5370b018 are the same 707 lines (sha256 0a7cfc86), in the same order and the same three files.
• Main's lines in this PR's files: only validate-manifest.py, validate-family.py, family.py and update-shape.py: an id:, a date or a repository: ending in a line feed is refused by name, and a pin's source_repository: that is no path or owner/repo name is named as the pin's (#1139) #1166's DATE_RE change in scripts/shape_advisory.py, away from this PR's lines.
• Tests at 5370b018: 550 passed and 2 skipped over 3 calls: the PR's two files, the two scans with tests/test_scaffold_leg_path_collisions.py, and the doc trio. The 2 skips are the probe environment's, at tests/test_no_auto_maintenance.py:222.
• Next: once CI's tests is green on 5370b018, lane 1 lands shape_advisory.py and shape-doctor.py: a leg's AGENTS.md this user cannot read leaves whether it is a leg unknown, so the way in offers neither command and points at what is here, and the other way in and the Triad row are silent (#1110) #1159 in its slot after shape-doctor.py and shape_advisory.py: a .git or an agent file linked into a folder this user cannot search is said once in what is here or agent files, <name>: cannot be read (<reason>), never absent; a .git offers no way in (#1110) #1144 (step 18b of lane 3's order), by fast refresh.

Lane: openreposhape-1 (openRepoShape-1)

[sonarqubecloud]

Quality Gate passed

Issues
4 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

[sourcery-ai]

Sorry @brettheap, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 6 days and 20 hours by commenting @sourcery-ai review. Upgrade to get a review now.