[brettheap]

Part of #1110. This is slice A: the eight sites in shape-doctor.py and scripts/shape_advisory.py. It 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"), and it lands after the tag, on a later word.

What

Eight sites asked exists() or is_file() of a name directly in the root. Both calls follow a link. Each site now asks the file's own stat helper, which applies #430's rule: stat the path; ENOENT, ENOTDIR, EBADF and ELOOP (and Windows' 21, 123 and 1921) mean nothing is there; any other OSError is raised so the caller can name it. The helper is is_a in shape-doctor.py and _is_a in scripts/shape_advisory.py. In shape-doctor.py the four .git sites share a new carries_git(root), which is is_a(root / ".git", <any mode>).

Measured over a folder Atlas whose .git links to the git directory of a checkout of acme/Orbit in a folder at mode 000, and over an AGENTS.md linked the same way. "Shim" means a 3.14-like sitecustomize in which is_file, is_dir, exists and is_symlink answer False to any OSError.

Site	Base, Python 3.12.3	Base, shim	Head, 3.12 and shim
check_agent_files	raises; run_checks makes it FINDING agent files AGENTS.md: cannot be read (Permission denied), and the verdict gains agent-files	note absent: AGENTS.md, NEXT scaffold-project.py --help	note AGENTS.md: cannot be read (Permission denied), NEXT this doctor again, WHY the chmod advice; the verdict is the project's own. The pinned AGENTS-shape.md is a FINDING
check_what_is_here	raises; FINDING what is here <name>: cannot be read (...)	no git repository, no manifest, no contracts/ -- an ordinary directory	n/a <name>: cannot be read (Permission denied), then what it did find; NEXT this doctor again, WHY the chmod advice
check_the_way_in	raises; FINDING the way in .git: cannot be read (...)	there is no repository here to adopt: a new project is SCAFFOLDED, NEXT setup.sh --org <your-org> --project Atlas	n/a its .git cannot be read, so it is not known whether this is a git repository to adopt, and neither way in is offered until it can be: `what is here` says how; no NEXT; git_repository: null
check_the_other_way_in	raises; FINDING the other way in .git: cannot be read (...)	row left out, as for a folder with no repository	no row: no way in is offered
origin_org	raises PermissionError	None, the answer for a folder with no repository (acme readable)	raises the refused stat; the way in asks .git first, so the doctor never reaches it
repo_local_origin_name	raises; FINDING naming .git: cannot be read (...)	None, so naming classifies Atlas and drops Orbit	raises; naming catches it: Atlas: classifies under the naming policy; origin's name is not read while .git cannot be read (see `what is here`)
shape_advisory._read	raises into read()'s net: not-answered, why ... (PermissionError) ...	not-a-repository	not-answered, why .git: cannot be read (Permission denied), so whether this is a repository is not known here, and the advisory says nothing
shape_advisory.repository_names	raises	['Atlas'] (['Atlas', 'Orbit'] readable)	raises the refused stat

The whole doctor over the .git fixture (--root Atlas; text report; the machine row omitted):

• Base, 3.12. naming, what is here, the way in and the other way in are each FINDING .git: cannot be read (Permission denied), with the same NEXT and the same chmod WHY, four times. There is no Triad row. NOT A SHAPE ROOT, exit 2.
• Base, shim. naming reads ok Atlas. what is here reads n/a ... an ordinary directory. the way in reads n/a there is no repository here to adopt, with NEXT setup.sh --org <your-org> --project Atlas. Exit 2.
• Head, 3.12 and shim. The two reports are byte-identical (cmp):

  ok   naming        Atlas: classifies under the naming policy; origin's name is not read while .git cannot be read (see `what is here`)
  n/a  what is here  .git: cannot be read (Permission denied)
       NEXT          python3 <standard>/shape-doctor.py --root <root>
       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 .git cannot be read, so it is not known whether this is a git repository to adopt, and neither way in is offered until it can be: `what is here` says how
NOT A SHAPE ROOT   (exit 2)

The eight entries leave KNOWN_OPEN in tests/test_path_guard_hygiene.py; its stale-entry check fails until they do. Measured: putting the check_the_way_in entry back fails it with 0 found, 1 listed.

Why: the design choices

1. One row carries the line and the cure: what is here. It is the one row that reads every name in a directory that is no shape root, so a .git and an agent file follow one rule there, and the cure is said once whatever combination is unreadable. In a project the agent files row says the same line for the three agent files (2). The rows that depend on .git do not repeat it:

   • the way in points at what is here;
   • naming adds one clause;
   • the other way in and the Triad row are silent.

   What that covers for an agent file, and what it does not. An agent file the doctor cannot read is said once, <name>: cannot be read (<reason>), and never read as absent, in what is here and in agent files. It is not the only reader of an AGENTS.md, and over an unreadable one a way in is offered as on main. _leg_by_agents_md in scripts/shape_advisory.py (except Exception: return None, "an unreadable file says nothing") is called by shape_advisory.read, whose readers are leg_clone (which the way in and the other way in ask), the Triad row and adopt-project.py's triad lines. An AGENTS.md it cannot read is still read as absent there, so those rows still offer adoption, the scaffold and the Triad advice over it, as on main (Known limits). It is not one of 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's eleven sites, and it is listed there now as a twelfth. It is not fixed here: _leg_by_agents_md is unchanged. For a .git no way in is offered (3).

   This is the doctor's own precedent for a mount (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 slice C). There the legs row names the mount, with the NEXT and the advice, and leg shape files and placement say the line without them. Rejected: making the way in the owner. It asks about the .git, and reads an AGENTS.md only through the advisory (above), so it has no line of its own for an agent file, and with two owners the cure would be said twice when both a .git and an agent file are unreadable.

2. Status follows the README's rule that a FINDING means something else asserts it.

   • In a directory with no manifest, the rows stay n/a. Nothing asserts a name there, and that verdict reads no row (NOT A SHAPE ROOT, exit 2, as before).
   • In agent files, an unreadable file is a note when it is rendered and nothing pins it (AGENTS.md, CLAUDE.md). It is a FINDING when it is the pinned AGENTS-shape.md, which the project's own validate-pins.py refuses by name. This is the rule the row already applied to an absent file.
   • So base 3.12's INVALID (..., agent-files) for an unreadable AGENTS.md is gone.

3. the way in offers neither command over a .git it cannot read. Whether the folder is a repository is not known. The scaffold is the defect, and an adoption over a .git git cannot read would fail at plan. The row has no NEXT, and detail.git_repository is null (unknown) in this one case.

4. origin_org, repo_local_origin_name and repository_names raise the refused stat instead of answering None or dropping a name. This is is_a's contract ("for the caller to name"). Each caller handles it:

   • the way in and the other way in ask .git first;
   • naming catches it;
   • _read asks .git first.

5. shape_advisory.read() gets no new state. NOT_ANSWERED is by its own definition "the advisory could not be read here, and says nothing", and every reader already keeps it silent:

   • the doctor's Triad row and leg_clone;
   • adopt-project.py's triad lines.

   A new state would be a second name for the same answer, which every reader would have to treat identically. What changes is its why, which now names .git: cannot be read (<reason>) in validate-pins.py's words. adopt-project.py is not touched. The constant's comment says so.

6. carries_git accepts any mode. A gitdir file (--separate-git-dir, a linked worktree, a submodule's checkout), a directory, or a link to either is a repository, as exists() said wherever the stat succeeds. mount_read asks a mount's .git the same way.

7. detail keeps true for a name that is there and adds cannot_be_read. That is a list in what is here and agent files, and a string in the way in and naming. A --json reader keeps its booleans, and no false says "absent" for a path that IS there.

8. Beside an absent agent file, that file's command stays the NEXT and the advice is added to its why. This is how the legs row keeps its checkout line beside a pin it cannot read.

9. naming keeps the policy's own status while origin's name is not read. It classified the folder's own name, so a name that classifies stays ok, with the clause saying origin's was not read; a name the policy does not classify, or a naming script that refuses, is the policy's FINDING with the same clause. That is a half-asked question, said as one, and it is pinned for each exit (0, 1 and 2) in a row of its own.

The change stays inside the eight sites, carries_git, and the callers that must handle the raise (check_not_a_root_naming). Other lanes' DRAFTs change shape-doctor.py too, #1109 among them; this keeps a later merge small.

Tests

New rows: tests/test_doctor_unsearchable_links.py, 25 rows. 17 came with the first two commits, and 8 were added in the fix round after the review (the third commit). The fourth commit splits two composite asserts, one per condition (SonarCloud's python:S9073), and changes no result.

• Mode cases (a real link into a real folder at 000, the doctor run as a person runs it; skipped on Windows and as root):
  • a .git, with a readable control first;
  • an AGENTS.md in a plain directory;
  • a project's AGENTS.md and its CLAUDE.md.
• Stand-in cases (in process, refused_stat and refusing; on every platform and as root):
  • the three .git questions, with controls for a gitdir file, no .git, and a name under a file;
  • the rows of a directory with no manifest, for a permission and for an I/O error;
  • what is here beside a readable Makefile;
  • the advisory, for a permission and for an I/O error, with a --separate-git-dir control (a gitdir file is a repository to _read and to repository_names);
  • the doctor's two readers of the advisory;
  • agent files: rendered, I/O error, pinned, and beside an absent file.
• Added after the review (in process, on every platform and as root; the four link rows skip where no symlink can be made):
  • test_a_git_link_that_leads_nowhere_is_still_no_repository[loop, dangling]: controls, .git -> .git (ELOOP) and .git -> ../nowhere/.git (ENOENT). the way in is the scaffold, what is here an ordinary directory, no cure and no cannot be read anywhere, no origin asked, the advisory not-a-repository;
  • test_carries_git_says_no_to_a_link_that_leads_nowhere[loop, dangling]: carries_git is False for the same two links;
  • test_an_unreadable_pinned_agent_file_beside_an_absent_one_is_a_finding: refused_stat on AGENTS-shape.md with CLAUDE.md unlinked is a FINDING, the absent file's command still the NEXT, and verdict_for says INVALID (agent-files);
  • test_naming_says_origin_was_not_read_whatever_the_name_comes_to[classifies, does-not-classify, script-refuses]: the naming row with the .git refused, for exit 0 (Atlas, status ok), exit 1 (my-service, FINDING) and exit 2 (a stand-in naming script that refuses, FINDING): the clause that origin's name was not read is on every branch.

New rows	Python 3.12.3	3.14-like shim
base 038dafba (a --shared scratch clone, with the new file laid over it)	2 passed, 23 failed	2 passed, 23 failed
head 89486f69	25 passed	25 passed

The two that pass on base are the two controls. Every other base failure is on the row's own assertion: a status, a reason, the naming clause, DID NOT RAISE, or a why. Two groups of rows fail differently:

• test_a_git_this_user_cannot_reach_is_named_once_on_every_python[io-error] and test_an_agent_file_this_user_cannot_reach_is_named_on_every_python[io-error] fail on base 3.12 (and only there) with OSError: [Errno 5] Input/output error escaping exists() (in repo_local_origin_name, called by naming) and is_file() (in check_agent_files). Under the shim the same two fail on a reason (an ordinary directory, absent: AGENTS.md).
• [carries_git] and the two test_carries_git_says_no_to_a_link_that_leads_nowhere rows fail on base as missing, AttributeError: the helper is new. Their siblings [origin_org] and [repo_local_origin_name] carry the proof (DID NOT RAISE).

Each added row, on base and on head:

Row	Base	Head	Kills
..._is_still_no_repository[loop], [dangling]	passes: a control	passes	R01, R29 (and R19)
test_carries_git_says_no_to_a_link_that_leads_nowhere[loop], [dangling]	fails: AttributeError, a new helper	passes	R01, R29
..._pinned_agent_file_beside_an_absent_one_is_a_finding	fails on the reason: absent: AGENTS-shape.md, CLAUDE.md (the FINDING already holds there, so it pins this change's words)	passes	R07
test_naming_says_origin_was_not_read...[classifies]	fails on the clause (status ok, exit and names hold)	passes	R13
...[does-not-classify]	fails on the clause	passes	R15
...[script-refuses]	fails on the clause	passes	R14
the --separate-git-dir lines of test_the_advisory_names_a_git_it_cannot_reach_and_says_nothing	the control lines pass on base; the rows still fail after them (DID NOT RAISE for a permission, a why for an I/O error)	pass	R27, R28

Mutants: 47 of 47 killed. The writer's 18 (D1 to D14 and A1 to A4) and the review's 29 (R01 to R29), each applied alone to one of four --shared scratch clones of the head (run again after the fourth commit, with the same result), with the 25 rows run and the file put back from its bytes. After each one its sha256 matched its HEAD blob: shape-doctor.py 4841bc5b... (39 mutants) and scripts/shape_advisory.py d48d565d... (8). The worktree was never changed.

• The review's 29, against the first 17 rows and a broad set of 298 tests: 22 killed. R01, R07, R13, R14, R15, R27 and R28 survived them, and R29 was killed only by the hygiene scan's ban on a bare os.path.islink. With the 8 added rows all 29 are killed by the rows alone:
  • R01, carries_git reads an ELOOP .git as a repository: [loop] of both link rows;
  • R29, a dangling .git read as a repository: [dangling] of both, so the hygiene scan no longer stands alone;
  • R07, an unreadable PINNED copy beside an absent file is only a note: the pinned-beside-absent row;
  • R13, naming a FINDING while .git cannot be read: [classifies];
  • R14, the clause dropped where the script refuses (exit 2): [script-refuses];
  • R15, the clause dropped where the name does not classify (exit 1): [does-not-classify];
  • R27, _read takes a gitdir file for no repository, and R28, repository_names drops its origin: both rows of the advisory test.
• The writer's 18: round 1, 16 killed. Two survived:
  • D8: carries_git asking for a directory only, so a gitdir file is no repository;
  • A2: _read catching only PermissionError.
    The second commit adds the gitdir-file control and the advisory's I/O-error case.
• The writer's 18: round 2, 18 killed.
  • In agent files: D1 a refused file counted absent; D2 a pinned one a note; D3 no NEXT; D4 the advice dropped beside an absent file.
  • In what is here: D5 false in detail; D6 no advice; D7 3.14's absent answer.
  • D8 is above. D9: the way in falls through to the scaffold. D10: the other way in offers it.
  • D11: naming drops origin silently. D14: naming raises to run_checks, a second telling.
  • D12 and D13: origin_org and repo_local_origin_name swallow the refusal as None.
  • In the advisory: A1 not-a-repository; A2 is above; A3 repository_names swallows it; A4 the exception's name in place of the system's reason.

Gate on head 89486f69. Python 3.12.3 and git 2.43.0, with a stub gh first on PATH, GH_TOKEN bogus, an empty GH_CONFIG_DIR, GIT_CONFIG_GLOBAL=/dev/null and GIT_SSH_COMMAND=false. At most 4 calls in parallel, each under 9 minutes (the longest took 3 min 24 s). origin/main is still 038dafba, the branch's base, so no merge was made.

Call	Result
tests/test_doctor_unsearchable_links.py	25 passed
the same, under the shim	25 passed
tests/test_path_guard_hygiene.py	49 passed
tests/test_shape_doctor.py, 448 tests in 4 shards by node id	111 passed and 1 skipped; 112 passed; 111 passed and 1 skipped; 111 passed and 1 skipped. Total 445 passed, 3 skipped
tests/test_scaffold_leg_path_collisions.py	104 passed
tests/test_doctor_unreadable_paths.py and tests/test_doctor_unreadable_pin.py	86 passed
every other file that imports or runs shape_advisory: test_shape_advisory, test_bom_reads, test_adopt_single_repository_record, test_doctor_gitmodules_not_utf8, test_doctor_validator_verdicts, test_bootstrap_non_utf8_branch	203 passed
the doc-pinning trio: test_agents_md_codes, test_cli_reference, test_repo_hygiene	170 passed
tests/test_doctor_unreadable_paths.py, under the shim	34 passed

Known limits

• Python 3.14 itself was not run. Every 3.14 statement here comes from the shim and from refused_stat.
• Windows was not measured. The mode rows skip there and as root; the stand-in rows run everywhere.
• An unreadable leg AGENTS.md is still read as absent where _leg_by_agents_md reads it (scripts/shape_advisory.py, except Exception: return None), so a way in is still offered over it. Its readers are leg_clone (which the way in and the other way in ask), the Triad row and adopt-project.py's triad lines. Measured over a clone with origin acme/Orbit whose AGENTS.md is a spec leg's, linked into a folder at mode 000: main and this head both say the way in ... it is ADOPTED in place with adopt-project.py plan ... --project Orbit, the other way in ... a NEW project is SCAFFOLDED with setup.sh --org <your-org> --project Orbit, and the advisory Triad row. Readable, the same folder is NAMED OR WRITTEN AS A LEG with no NEXT, and the Triad row says it is a clone of the spec leg. This head adds what is here AGENTS.md: cannot be read (Permission denied); a git repository, with the cure. The site is not one of 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's eleven, and it is listed there now as a twelfth. It is not fixed here: _leg_by_agents_md is unchanged.
• A .git that is a gitdir file pointing into a folder this user cannot search is a name the doctor can read, so carries_git says True. git then fails to read origin, and the adoption line ends --org <your-org>, as before. Nothing in this slice's guards touches that case.
• The same class: a root .git that is a DIRECTORY at mode 000. carries_git asks the .git itself, which this user can stat, so it is still called a repository. Main and this head both offer adoption, adopt-project.py plan --source <root> --project Atlas --org <your-org>, and the scaffold, and print the Triad advice. Measured over a real repository with origin acme/Orbit, its .git at 000.
• shape_advisory.NOT_ANSWERED's new why, .git: cannot be read (<reason>), so whether this is a repository is not known here, and the advisory says nothing, is printed by nothing. _triad_advisory_row returns no row for that state and adopt-project.py prints nothing for it, so the text is true but reachable only in process, where the rows hold it. The constant's comment says --json, and no --json report carries it.
• the way in's detail.git_repository is null in this one case, where it was always a boolean.
• AGENTS.md's "Report the verdict and both commands" (the NOT A SHAPE ROOT step) is not amended for the case in which the way in offers none. The row's own words say why. A one-clause amendment would close it; AGENTS.md is not changed in this PR.
• No docs changed. There is no new doctor code and no --help change (so docs/cli.md is unchanged), and the README lists the rows, not their texts. The doc-pinning trio passes.

Not in this PR

Slice B's three sites stay on KNOWN_OPEN under #1110:

• scripts/family.py _gitmodules_names;
• scripts/family.py _sections_giving;
• templates/family-root/scripts/siblings.py submodule_urls.

They wait for other lanes' open DRAFTs on family.py's remove (#1117 and #1098). #1110 stays open for them.

A shape root whose own .git is a link into a folder this user cannot search still reads DRIFTED, and both of its pinned validators crash. That was r1144's observation outside this PR. Base and head behave alike, and it is filed as #1146.

Lane: openreposhape-1 (openRepoShape-1)

🤖 Generated with Claude Code

Summary by Sourcery

Make shape discovery and advisory checks distinguish unreadable linked .git and agent files from absent paths, report the access problem with appropriate guidance, and avoid unsafe repository recommendations.

New Features:

• Report unreadable .git and agent-file links explicitly instead of treating them as absent, including actionable recovery guidance.
• Preserve repository uncertainty across doctor and advisory results when .git cannot be read, avoiding adoption or scaffolding recommendations.

Bug Fixes:

• Prevent unreadable linked paths from being misclassified as missing repositories, missing agent files, or missing origin names across the affected doctor and advisory checks.

Enhancements:

• Centralize repository detection through stat-based checks that distinguish absent paths from paths whose access is refused.
• Ensure unreadable paths are reported once in the appropriate doctor row while retaining accurate status, details, and follow-up commands.

Tests:

• Add comprehensive coverage for inaccessible, dangling, looping, and gitdir-file links, including permission and I/O errors across doctor and advisory behavior.
• Update path-guard hygiene expectations as the affected direct existence checks are replaced.

[sourcery-ai]

Reviewer's Guide

Implementation

Make unreadable .git entries distinguishable from absent repositories in the advisory, naming, and way-in checks, while keeping the other-way-in row silent.

• scripts/shape_advisory.py L140-146, L499-508, L792-803
• shape-doctor.py L11212-11229, L11304-11316, L11795-11818 (+5 small edits)

Report unreadable agent files as present, preserving pinned-file findings and the appropriate repair command and advice.

• shape-doctor.py L10102-10134, L10139-10147, L10185-10191

Have “what is here” name unreadable root entries once, with the doctor command and the cause-specific advice.

• shape-doctor.py L11367-11389, L11404-11410, L11423-11428

Tests

Add regression coverage for unreadable links, absent-path controls, naming and advisory behavior, and pinned versus rendered agent files.

• tests/test_doctor_unsearchable_links.py L1-600

Remove obsolete open-path exceptions now covered by the new guarded reads.

• tests/test_path_guard_hygiene.py L658 (removed lines)

---

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-21T22:41:03Z) r1144, lane 1's independent review of #1144 at eb3f098c: READY on condition, with no MUST, two SHOULDs and six NITs. It is not the writer w1110a.

• The .git case does what the body says. Every caller of the three helpers that now raise handles the raise, no traceback escaped in any probe, and every gate count reproduces.
• S1: the title and design point 1 claim too much for agent files. shape_advisory._leg_by_agents_md (except Exception: return None) still reads an unreadable leg AGENTS.md as absent, so the way in offers adoption over it. Base does the same. Lane 1 takes the review's option (a): narrow the title and the design point here, and add the site to 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.
• S2: seven of the reviewer's mutants survive (R01, R07, R13, R14, R15, R27 and R28), and R07 changes the verdict. The fix round adds the rows.
• Outside this PR: a shape root whose own .git is a link into an unsearchable folder reads DRIFTED. Lane 1 files it.
• Next: a fix round after the 02:00Z reset. This window is spent (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-6327775505).

The full review

r1144: independent review of #1144 at eb3f098c

Verdict: READY on condition

No MUST findings. The code does what the body says for the .git case, and every caller of the three helpers that now raise handles the raise. No traceback escaped in any probe. Every gate count in the body is reproduced.

The two conditions:

• S1: the title and one design claim say more than the code does for agent files. Correct the wording and record the follow-up.
• S2: seven of my mutants survive every test, one of them on a branch that moves the verdict. Add the rows.

Findings

MUST

None.

SHOULD

S1. The title and design point 1 overclaim for agent files. An unreadable leg AGENTS.md is still read as absent, and a way in is offered over it.

• Where:

  • scripts/shape_advisory.py:563-566: _leg_by_agents_md has except Exception: return None, commented "an unreadable file says nothing".
  • Its readers: shape-doctor.py:11519 (leg_clone), :11614 (the way in), :11744 (the other way in) and :11828 (the Triad row).

• What the PR claims:

  • The title: "a .git or an agent file … never absent, and no way in is offered over it".
  • Design point 1: "An AGENTS.md it cannot read has no other reader there".

• Measured (probes/fx/sc/nLegAgents): a repository with origin acme/Orbit whose AGENTS.md is a real spec-leg AGENTS.md, linked into a folder at mode 000.

  • Readable, head says the way in … NAMED OR WRITTEN AS A LEG … see the Triad row, with no NEXT, and the Triad row says this is a clone of the spec leg.
  • Locked, on base 3.12, head 3.12 and head under the shim, the doctor says:
    • the way in … ADOPTED in place, NEXT adopt-project.py plan … --project Orbit;
    • the other way in, NEXT setup.sh --org <your-org> --project Orbit;
    • advisory Triad This is a single repository….
  • Head adds what is here AGENTS.md: cannot be read (Permission denied); a git repository, with the cure.

• Why it is not a MUST: it is not a regression (base behaves the same), and the site is not one of 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's eleven.

• Fix: do either of these.

  • (a) Narrow the title, for example "…a .git … offers no way in; an agent file is said once, never absent". Correct design point 1. Add _leg_by_agents_md to 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 as a further site, or open a new follow-up issue.
  • (b) Fix it here: a refused AGENTS.md read gives NOT_ANSWERED, and the way in offers neither command while it cannot be read. This mirrors the .git rule.

  I recommend (a), for scope.

S2. Seven mutants of the new code survive every test I ran. Each survived the 17 new rows and a broad set of 298 tests: the new rows, test_shape_advisory, the unreadable pair, the hygiene test, and the 99 test_shape_doctor tests matching naming, way-in, agent and .git terms.

• R07, shape-doctor.py:9978. The status line becomes FINDING if detail["pinned"] else NOTE. A pinned AGENTS-shape.md that cannot be read, beside an absent CLAUDE.md, then drops from FINDING to note, and the verdict changes. No row covers this branch.
  • Add a stand-in row: refused_stat on AGENTS-shape.md, unlink CLAUDE.md, and assert FINDING.
• R01, carries_git (:11005-11020). An ELOOP .git is read as a repository. No row has a looping .git.
  • My R29 (a dangling .git link read as a repository) is killed only by the hygiene scan, which bans its bare os.path.islink. No behaviour row kills it.
  • Add controls for .git -> .git and .git -> ../nowhere/.git. Expect carries_git False and the way in the scaffold. I measured both as absent on base and head (sc/nLoop, sc/nDangle).
• R13, :11155. naming goes FINDING while .git cannot be read. No test asserts the naming status in this case.
• R14 and R15, :11148-11154. The "origin's name is not read" clause is dropped from the exit-2 and exit-1 FINDING branches. Every row uses Atlas, which classifies.
  • Add a name that fails the policy, beside an unreadable .git.
• R27 and R28, scripts/shape_advisory.py:793 and :508. Asked with S_ISDIR, a gitdir-file .git becomes not-a-repository and drops origin's name. The gitdir control exists only for the doctor's three questions.
  • Add the --separate-git-dir control to test_the_advisory_names_a_git_it_cannot_reach_and_says_nothing.

NIT

• N1. The body says "every base failure is the intended one: a status, a reason, DID NOT RAISE, or a why". On 3.12 that is not quite true of two rows:

  • test_a_git_this_user_cannot_reach_is_named_once_on_every_python[io-error];
  • test_an_agent_file_this_user_cannot_reach_is_named_on_every_python[io-error].

  Both fail with OSError: [Errno 5] Input/output error escaping base's exists() or is_file() in process.

• N2. NOT_ANSWERED's new why is printed nowhere.

  • _triad_advisory_row returns no row for that state.
  • adopt-project.py:5955-5967 prints nothing for it.
  • The constant's comment (shape_advisory.py:134-146, "for --json") implies a reader. The text is true but reachable only in process.

• N3. The known limits omit a root .git that is a directory at mode 000 (sc/nGit000). Base and head both call it a repository and offer adoption with --project Atlas --org <your-org>, the scaffold, and the Triad advice. It is the same class as the gitdir-file limit the body does list.

• N4. naming stays ok while origin's name is unread. That is defensible, but it is a half-asked question; whichever status you keep, pin it in a test (see R13).

• N5. tests/test_doctor_unsearchable_links.py:98 is 80 characters long.

• N6. AGENTS.md's "Report the verdict and both commands" is not amended for the case where no command is offered. The body discloses this; a one-clause amendment would close it.

Observation, outside this PR

A shape root whose own .git is a link into an unsearchable folder (sc/pG) reads DRIFTED (2 leg(s) not at the pin). The legs row says "no gitlink recorded", and both validators crash with PermissionError.

• This is identical on base and head and on both Pythons.
• It contradicts the rule written in drifted_reasons' docstring: a path in the root this user cannot reach is INVALID, never DRIFTED.
• It is a candidate follow-up issue.

Body claims

Claim	Result
Eight sites (six doctor, two advisory); carries_git is is_a(root/.git, any mode)	true (diff)
Change limited to the eight sites, carries_git and check_not_a_root_naming	true
check_agent_files: base 3.12 FINDING plus agent-files in the verdict; base shim note absent; head note … cannot be read, NEXT the doctor, chmod WHY, the verdict the project's own; pinned file a FINDING	true (sc/pA: base INVALID (agent-files), head COMPLIANT; sc/pS FINDING)
check_what_is_here, the way in, the other way in: base 3.12, base shim and head columns	true
origin_org and repo_local_origin_name: 3.12 raise, shim None, head raises	true (in process)
_read: base 3.12 not-answered (PermissionError), base shim not-a-repository, head not-answered with the .git line	true
repository_names: 3.12 raises, shim ['Atlas'], head raises	true
Whole-doctor reports: base 3.12 (four FINDINGs, no Triad row, exit 2) and base shim	true
Head 3.12 and shim byte-identical, and equal to the quoted block	true (cmp; the block matches byte for byte)
Stale-entry check: 0 found, 1 listed	true
The cure said once in what is here	true where nothing has a manifest (sc/nBoth: .git and AGENTS.md both locked, advice once)
"An AGENTS.md … has no other reader there"; title "no way in is offered over it"	false for agent files (S1)
INVALID (agent-files) gone; a note under README's rule	true, and sound: README makes FINDING "something else asserts this", and leg shape files already makes a leg file it cannot read a note (#430)
git_repository: null only in this case; nothing reads it as a boolean	true (only readable-case tests assert is False)
Helpers raise; every caller handles it	true (grep: the only callers are naming (catches it), way_in_project and origin_org (after carries_git), and _read; no template or pinned copy calls them)
Gitdir file into a locked folder behaves as before	true (sc/nGitdir, base equals head)
17 rows; base 0/17 on 3.12 and the shim; head 17/17	true
Every base failure is the intended one	mostly; two exceptions (N1)
Mutants 18 of 18 killed	true (I re-ran the writer's 18 with my own driver; all killed)
Shas 4841bc5b… and d48d565d…	true
Gate counts: 445 passed / 3 skipped, 66, 104, 86, 203, 170, 51 under the shim	true (my shards are 112, 112, 112, and 109 + 3 skipped)
No docs changed; docs/cli.md unchanged; nothing in the docs now false	true (README and the handbook list rows, not their texts)
Slice B's three sites stay on KNOWN_OPEN	true
"Part of #1110", no closing keyword	true (closingIssuesReferences: []; no keyword in either commit message)

Base against head, measured

In the tables, "the probes" means the doctor run over the fixture with .git linked into a folder at mode 000.

	3.12	my shim
Base doctor, the probes	4 × FINDING .git: cannot be read, exit 2	ordinary directory, NEXT setup.sh … --project Atlas, exit 2
Head doctor, the probes	the quoted block, exit 2	byte-identical to 3.12 (text and --json)
Base, new rows	0 passed, 17 failed	0 passed, 17 failed
Head, new rows	17 passed	17 passed

• Dangling .git link and .git loop: base and head identical, both absent.
• Shape root with an unreadable .git: base and head JSON identical.

My mutants

• 29 written: R01-R29 in mutants.py.
• Against the 17 new rows (R01-R28): 21 of 28 killed.
• Survivors: R01, R07, R13, R14, R15, R27 and R28; they survive the 298-test broad set as well (S2).
• R29 ran only against the broad set, where only the hygiene scan killed it.
• Total: 22 of 29 killed.
• Restores: after every mutant the file went back to the HEAD blob, proved by sha256 (4841bc5b… and d48d565d…). The final git status of all four mutant clones is empty.

Merge with main

• origin/main is still 038dafba, fetched at the start and again at the end. The head is therefore the merge result, and I tested the head.
• Counts on the head, in the probe environment:

Run	Result
test_path_guard_hygiene + the new rows	66 passed
test_shape_doctor, 4 shards	445 passed, 3 skipped (PowerShell, Windows only)
test_scaffold_leg_path_collisions	104 passed
The unreadable pair	86 passed
The six shape_advisory importers	203 passed
test_doctor_next_is_a_command	61 passed
test_doctor_validator_rows + test_release_install_check_children	101 passed
The doc trio	170 passed
New rows + test_doctor_unreadable_paths, under the shim	51 passed

A process slip on my side

My first shard launch used mapfile in zsh, which does not have it. The id lists came out empty, so four pytest runs started the whole suite in parallel.

• timeout stopped each one at 535 s, about 2% in.
• No process of mine was left, my worktree is clean at eb3f098c, and no folder in scratch is left at mode 000.

I made no GitHub write, commit or push.

Files

Everything is under /workspace/projects/openRepoShape-worktrees/_lane1-scratch/r1144/:

• mutants.py (my 29, plus the writer's 18 parsed into wmutants.py with ast.literal_eval, never executed) and the driver mutate.py;
• the shim, shim/sitecustomize.py;
• the probe scripts and outputs: probes/scen.sh, probes/show.py, probes/helpers.py, probes/p1/, probes/fx/sc/*/;
• the logs, in logs/.

Lane: openreposhape-1 (openRepoShape-1)

[brettheap]

(lane openRepoShape-1, 2026-10-22T02:50:40Z) r1144b, lane 1's independent re-check of the fix round at 89486f69: READY, with no MUST or SHOULD. It is not the writer f1144.

• The round changes only the test file. The two tools' sha256 values equal the first review's.
• Mutants: each of r1144's seven survivors is killed by its named row. All 29 of r1144's and the writer's 18 are killed, 47 of 47.
• The new rows: base fails 23 and passes 2 (controls); head passes 25 on 3.12 and under the shim.
• S1: the narrowed title matches the code, and _leg_by_agents_md is stated as not fixed here and listed in 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 as the twelfth site, measured.
• The NITs: N1 to N6 are as stated, and N3 is measured.
• CI on 89486f69: at 02:49Z, tests was pending, while SonarCloud, package and tests-git-bash pass.
• Landing: 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 stays a DRAFT with no milestone, outside v1.2.0 by Brett Heap's ruling of 2026-10-21T10:32:04Z. It lands after the tag, on a later word, once tests passes.

The full re-check

Verdict: READY. No MUST and no SHOULD. One NIT, which needs no action.

Head is 89486f699f9a0b451ddbf1d4cfe41d5969391be3. It equals the PR's headRefOid, and origin/main was not moved by my reads.

Checks

1. The diff. git diff --name-only eb3f098c 89486f69 prints only tests/test_doctor_unsearchable_links.py (156 insertions, 8 deletions). shape-doctor.py and scripts/shape_advisory.py have the same sha256 as at the first review: 4841bc5b… and d48d565d….

2. S2, with the rows that kill each mutant. I ran each of the seven alone against the whole file on 3.12.

• R01 is killed by test_a_git_link_that_leads_nowhere_is_still_no_repository[loop] and test_carries_git_says_no_to_a_link_that_leads_nowhere[loop].
• R07 is killed by test_an_unreadable_pinned_agent_file_beside_an_absent_one_is_a_finding.
• R13 is killed by test_naming_says_origin_was_not_read_whatever_the_name_comes_to[classifies].
• R14 is killed by [script-refuses] of that test, and R15 by [does-not-classify].
• R27 and R28 are each killed by both rows of test_the_advisory_names_a_git_it_cannot_reach_and_says_nothing.
• R29 is killed by the [dangling] rows of both link tests, so the hygiene scan no longer stands alone.
• All 29 of R01–R29 are killed by the file alone. I also ran the writer's 18, so 47 of 47 are killed, each as a real test failure (between 1 and 13 failures per mutant).
• Restores: after every mutant the file matched its HEAD blob, 39 times shape-doctor.py 4841bc5b1ba95d63 and 8 times shape_advisory.py d48d565d6413f63f. All five clones show an empty git status afterwards.
• Round-1 claim: I ran D8 and A2 against the first-round test file (e21c8c05's). Both survive (16 passed), as the body says.

3. The new rows.

• Head: 25 passed on 3.12 and 25 passed under my copy of the shim.
• Base (038dafba's two tools in head's tree): 23 failed and 2 passed, on 3.12 and under the shim.
• The two that pass are test_a_git_link_that_leads_nowhere_is_still_no_repository[dangling] and [loop]. They are controls, as the report says.
• The failure kinds match the report's table.
  • AttributeError … no attribute 'carries_git' at lines 334 and 398.
  • DID NOT RAISE at 350 and 509.
  • A why or reason mismatch at 424, 513, 525, 554, 573 and 595.
  • The naming clause at line 462, three times.
• N1: on base 3.12 the two io-error rows fail with OSError: [Errno 5] escaping exists() (in repo_local_origin_name, from check_not_a_root_naming) and is_file() (in check_agent_files). Under the shim they fail on a reason, an ordinary directory and absent: AGENTS.md.

4. S1.

• Title: it now says "a .git or an agent file … said once in what is here or agent files … never absent; a .git offers no way in". That matches the code.
• Design point 1 and Known limits: both state that _leg_by_agents_md is not fixed here. They also list its readers: leg_clone, the Triad row and adopt-project.py's triad lines. I checked scripts/shape_advisory.py:810, shape-doctor.py:11614 and :11744, and adopt-project.py:5956.
• 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 (read-only gh): its title says "twelve sites". It has an entry "One more, found by r1144 … scripts/shape_advisory.py _leg_by_agents_md", and that entry says the fix round narrows 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 title.
• Measured on head, with a leg AGENTS.md linked into a folder at mode 000:
  • what is here AGENTS.md: cannot be read (Permission denied); a git repository, with the cure.
  • the way in … it is ADOPTED in place, NEXT adopt-project.py plan … --project Orbit.
  • the other way in … SCAFFOLDED.
  • advisory Triad This is a single repository….
  • Readable, the same folder says NAMED OR WRITTEN AS A LEG, with no NEXT.
  • The folder is back at 755.

5. N1–N6.

• N1 and N2: the body wording is as the report says.
• N3: I made a root .git directory at mode 000 with origin acme/Orbit. Head and base both print the way in … ADOPTED in place with adopt-project.py plan --source <root> --project Atlas --org <your-org>, the scaffold, and the Triad advice. That matches the Known limits entry. The folder is back at 755.
• N4: [classifies] covers it, and design point 9 states it.
• N5: the file has 0 lines over 79. At eb3f098c line 98 was 80.
• N6: it is in Known limits.

6. The body.

• It opens "Part of 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."
• The keyword scan finds no close, fix or resolve form followed by an issue number. The hits are "fix who owns it", "not fixed here" and "would close it", none followed by #.
• closingIssuesReferences is []. The four commit messages have no closing keyword.
• 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 is OPEN and named as "filed 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".
• The counts match the report: 25 rows, 47 mutants, shas, and the gate table. Seven of the report's gate rows (3.12 and shim runs, hygiene, the unreadable pair) I reproduced or saw. The other five I did not run, because no tool code changed.
• The operator's address does not appear, 🤖 is the only non-ASCII character, and the title is 243 characters with one #1110.
• The GitHub title and body are already the new ones, although f1144's report says they still needed updating.

7. Runs on head.

• tests/test_path_guard_hygiene.py: 49 passed.
• tests/test_doctor_unreadable_paths.py plus tests/test_doctor_unreadable_pin.py: 86 passed.

8. CI at 02:49:52Z.

• tests: pending.
• tests-git-bash: pass (3m46s).
• SonarCloud Code Analysis: pass.
• package: pass.

Findings

MUST: none.

SHOULD: none.

NIT

• f1144's report says the advisory test's control lines are at "498–500". In tests/test_doctor_unsearchable_links.py at 89486f69 they are lines 500–504, and the base failure follows at line 509. The PR body cites no line numbers, so nothing needs changing.

Not run: Python 3.14, Windows, and the test_shape_doctor.py shards. The shards are not needed because no tool code changed.

State left behind: I made no commit, push or GitHub write. My worktree is clean at 89486f69. No folder under my scratch is at mode 000, and none of my processes is running.

Paths

• Scratch: /workspace/projects/openRepoShape-worktrees/_lane1-scratch/r1144/r2/
• Mutant logs: logs/mut_c1.log to logs/mut_c5.log
• Head runs: logs/head312.log and logs/headshim.log
• Base runs: logs/base312.log, logs/baseshim.log, logs/base312v.log, logs/baseshimv.log and logs/base312s.log
• Hygiene and unreadable-pair runs: logs/hyg.log and logs/unr.log
• Fixtures: fx/leg and fx/g000
• PR and issue captures: pr-body.md and i1110.json

Lane: openreposhape-1 (openRepoShape-1)

[sonarqubecloud]

Quality Gate passed

Issues
3 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

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