[brettheap]

Lane: openreposhape-2 (openRepoShape-2)
Claim: #430 (comment)

A v1.2.0 DRAFT, slice C of lane 1's plan for #430 (issuecomment-6251069236): shape-doctor.py and scripts/shape_advisory.py. Branch fix/430-c-doctor-unreadable, from main 50178305, two commits: 5e7a0440 (a WIP: usage-window checkpoint holding all the code) and 76ebca2e (one test's assertion; the code is 5e7a0440's). Nothing is merged into it. run_checks (decision 10) also names a refused read out of any other row in the gate's words, so the rule reaches a site this PR did not list. A leg file the row cannot read is cannot be read (<reason>) in leg shape files. Slice B (lane 2's other writer, update-shape.py) is a separate branch, and no test here depends on it.

Decisions

The plan's rule, held for every site: stat the path; ENOENT, ENOTDIR, EBADF and ELOOP (and Windows 21, 123 and 1921) are absent; any other OSError is named in validate-pins.py's words, <path relative to the root>: cannot be read (<reason>) (or cannot be listed for a folder, #434), with the gate's advice for the cause. The doctor asks with its own is_a (#847); scripts/shape_advisory.py gets a local _is_a with the same errno set (a parity test holds it to the gate's). scripts/repo_shape.py is untouched.

scripts/shape_advisory.py is not a shape copy. It is in none of shape_materialize.py's copy lists, and the pins of a scaffolded project (11 rows) and a holder (10 rows) name neither it nor shape-doctor.py. No project or holder gets an upstream-changed row from this PR.

Each site (lines at 50178305):

1. main (:11768, and one new check): REFUSES. A root whose stat is refused (a folder above it this user cannot search), or that this user cannot SEARCH (stat of <root>/.), is REFUSED shape-doctor-root-unreadable, exit 3, before any row. The code is the one main already gives a root resolve() refuses, so no new code. Exit 3, not the rule's 2: the doctor's exit 2 is NOT A SHAPE ROOT, a verdict about the tree, and 3 is its documented "usage or environment". Only search is asked: a root at mode 111 (searchable, not listable) is COMPLIANT on both Pythons, measured, and is not refused.
2. validator_for (:2000): REFUSES for its row. An own copy whose stat is refused raises; the manifest, pins and family rows name it (unreadable_gate_row) and run nothing, never the standard's template in its place. unloaded_manifest_row names it beside the manifest's refusal; gate_line gives no line, so lockstep_next and the agent-files confirm clause name no gate that cannot run.
3. check_legs (:7247/:7248): REFUSES for the leg. One helper, mount_read, asks the mount's stat, its listing and its .git's stat, for the four rows that read a mount. A refused one is the gate's line, kept in the leg's mount_cannot_be_read, routed to no checkout and no lockstep line; the NEXT is this doctor again where no other leg has a line, and the advice is the WHY, or follows the line's, as shape-doctor.py: for a pin or a contracts/ this user cannot read, the legs, manifest kinds and shape currency rows disagree with validate-pins.py's named refusal, and manifest kinds names a git checkout HEAD -- that discards work #847 does for a pin. Only a missing gitlink is said before it.
4. member_state (:9792/:9793): REFUSES for the member, through the same helper, key and words; members_verdict routes no such member and gives the advice.
5. leg_shape_comparison (:7514) and shape_file_state (:7486): the leg's state is the mount's line, and a leg file whose stat or read is refused is cannot be read (<reason>), never absent with a cp over it. The row is a note, never ok and never a FINDING (the legs row asserts the mount).
6. audit_leg (:8454): the leg's state is the mount's line, an unread leg, so placement is a note (n/a where no leg could be read), as for an unpopulated one; never git's it is not a git repository for a mount it could not enter.
7. own_bootstrap (:6277): BENIGN, by decision: a refused stat answers "cannot run" (False) on every Python. It chooses only which line a row prints, and the manifest and pins rows name an unreadable scripts/.
8. The low git-directory sites. kept_gitdir (:6715), keeps_modules (:6803) and checkout_reach's git_dir/modules (:6872) ask with is_a: a refused stat raises on every Python and its row names it (10), where 3.14 called a kept repository gone. BENIGN: checkout_reach :6859/:6870, detached :9368 and origin_url :9446 (reached only after the same mount's, or sibling's, listing and .git stat succeeded); root / ".git" at :10355, :10386, :10854, :10977, git_dir_holds :11135, Context :1327, check_agent_files :9306 and check_what_is_here :10473-:10478 (a name directly in the root, or in a git directory git has just read, is statable by anyone who can search the root, which main now requires).
9. BENIGN, the standard's own checkout: :404/:11759, :1492, :2199/:2370/:6301 (a copy validator_for just stated, or the template), :7490, :7516, :7657, :8533, :10600; :1591 (repo_shape.py beside a copy just stated); :6393 (os.path.lexists, root level), :9608 (a remote's path), :9715-:9752 (unclonable/sibling_slot, shape-doctor.py members row: its green note says make siblings places every member with no working clone, a directory make siblings refuses included, so one row says both that it places IRRS and that it leaves IRRS exactly as it is #669's unlistable).
10. run_checks: an OSError out of any check that is a refused read of a path inside the root (refused_in_root, shape-doctor.py: for a pin or a contracts/ this user cannot read, the legs, manifest kinds and shape currency rows disagree with validate-pins.py's named refusal, and manifest kinds names a git checkout HEAD -- that discards work #847) is that row's FINDING in the gate's words, NEXT this doctor again, WHY the advice, detail cannot_be_read and path. Any other OSError keeps could not be run: <exc>.
11. scripts/shape_advisory.py Tree.kind (:355/:357): asks _is_a, so a refused stat raises and each reader's net reads the file as there and unreadable (the record: it could not be read (PermissionError), which silences nothing) on every Python, where 3.14 called it absent.

Which verdict a "could not be run" row gives. INVALID, naming it; never DRIFTED and never CANNOT ANSWER. drifted_reasons counts drift only from a row's own readable entries: a legs row with none (an exception out of check_legs) and a leg whose mount or pin cannot be read are no leg off its pin, and a members row is drift only where a member this user CAN reach has a problem. Such a row falls through to invalid_verdict (a red gate) or the catch-all, which names it. Not CANNOT ANSWER: exit 3 says nothing is a statement about the tree, and an unreadable path in the root is one (#430's "What it should do" 2, and #847's ruling for an unreadable pin). The ladder's order is unchanged.

What changed

Measured by a probe on Python 3.12.3 and a 3.14-like sitecustomize shim (is_file, is_dir, exists, is_symlink answer False to any OSError), in a project and a holder scaffolded into local bare remotes from a committed copy of the branch, with a stub gh, GH_TOKEN=bogus and an empty GH_CONFIG_DIR. Controls (nothing chmod'd) are COMPLIANT before and after, on both.

cell	before, 3.12	before, 3.14-like	after, both
scripts/ 444	INVALID (manifest, pins), both rows could not be run: [Errno 13] ...	DRIFTED (5 copy-missing), ok manifest the standard's templates/assembly-root/scripts/validate-manifest.py passes	both rows name the own copy (below); 3.12 INVALID (manifest, pins); 3.14-like still DRIFTED (5 copy-missing), slice B's
.github/workflows/ 444	INVALID (pins)	DRIFTED (1 copy-missing)	unchanged: no doctor site reads there; slice B's
spec/ (a leg mount) 000	DRIFTED (1 leg(s) not at the pin); legs, leg shape files and placement could not be run	the same	INVALID (pins); legs names the mount, the other two notes name it
spec/ 444	DRIFTED (...); legs and leg shape files could not be run	DRIFTED (...); spec: populated, but with no .git of its own with a git submodule update NEXT, and every leg file absent with a cp NEXT	INVALID (pins); spec/.git: cannot be read in all three rows
holder members/ 000	DRIFTED (a member is not at its pin), members could not be run	the same verdict, members/IRRS: not populated -- the pinned copy is an unbootstrapped submodule	INVALID (family); members names the mount
holder members/IRRS 000	DRIFTED (...), could not be run	the same	INVALID (family); members/IRRS: cannot be listed
the root 000, the root 444	a traceback out of Context	NOT A SHAPE ROOT, exit 2	the refusal below, exit 3
the root's parent 000	a traceback at root.is_dir()	REFUSED shape-doctor-root-missing: ... is not a directory on this machine	the refusal below, exit 3
the root 111	COMPLIANT	COMPLIANT	COMPLIANT (not refused)

The new lines:

FINDING  manifest   scripts/validate-manifest.py: cannot be read (Permission denied), so the project's own gate was not run, and the standard's copy is not run in its place
         NEXT       python3 <shape>/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
FINDING  legs       spec: cannot be listed (Permission denied), so no HEAD in it is compared with the pin
FINDING  legs       spec/.git: cannot be read (Permission denied), so no HEAD in it is compared with the pin
note     leg shape files  spec: cannot be listed (Permission denied); code: AGENTS.md rendered, CLAUDE.md identical, .gitignore identical
note     placement  nothing is in the wrong leg in what could be read, and not everything could be: spec: cannot be listed (Permission denied); code: 1 path(s) over 1 of 5 tracked file(s)
FINDING  members    members/IRRS: cannot be read (Permission denied), so no HEAD in it is compared with the pin
FINDING  <row>      <path>: cannot be read (<reason>)

REFUSED shape-doctor-root-unreadable: --root <root>: cannot be read (Permission denied)
  Remediation: Make the root searchable by this user: `chmod u+rx` on it (and on every directory above it), or fix who owns it. Then run this doctor again

For a cause other than permission, each says the gate's other advice (OTHER_REASON, or OTHER_REASON_FOLDER for a mount it cannot list, and for the root). The --json entry of a leg or member carries mount_cannot_be_read. shape_advisory.py's record reader says it could not be read (PermissionError) for a record whose stat is refused, on every Python.

Tests

tests/test_doctor_unreadable_paths.py, 34 tests. MODE cases chmod a real path (skipped on Windows and as root, restored in a finally by mode_of) and run the doctor as a person does; STAND-IN cases use refused_stat (#383, which answers is_file() as 3.14 does) and #847's refusing, in process, on every platform. It imports its helpers from the files that own them (conftest, test_shape_doctor, test_doctor_unreadable_pin, test_doctor_legs_members_next, test_bump_leg_unopenable, and the two test_validate_pins_unreadable_* files): nothing is copied.

test	kind	what it pins	kills
test_an_own_gate_this_user_cannot_reach_is_named_never_the_template	mode, scripts/ 444	manifest and pins rows name the own copy, NEXT, WHY, own_copy, cannot_be_read; no passes; verdict not asserted (slice B)	the cell; on 3.12 M01's raise is caught, so the stand-in kills it
test_a_leg_mount_this_user_cannot_reach_is_named_and_no_drift [spec-000, spec-r--]	mode	legs names the mount and keeps mount_cannot_be_read; leg shape files and placement are notes naming it; verdict INVALID (pins)	the cell, on both Pythons
test_a_member_this_user_cannot_reach_is_named_and_no_drift [members-000, member-000, member-r--]	mode, holder	members names the mount, NEXT, WHY, never "unbootstrapped"; verdict INVALID (family)	M29
test_a_root_this_user_cannot_search_is_refused_by_name [root-000, root-r--, above-000]	mode	exit 3, empty stdout, no traceback, the refusal line and its chmod u+rx remediation	M02
test_a_root_this_user_can_search_and_not_list_is_not_refused	mode, root 111	control: only search is asked; exit 0
test_validator_for_raises_a_refused_stat_and_names_the_own_copy	stand-in	validator_for raises; the manifest row names the copy, runs nothing (exit None)	M01, M24
test_another_reason_for_the_own_copy_gets_the_other_advice	stand-in, EIO	the system's reason and OTHER_REASON
test_an_own_copy_that_is_not_there_still_falls_back_to_the_template	control	an absent own copy still gets the template
test_no_lockstep_line_is_named_for_a_gate_this_user_cannot_reach	stand-in	gate_line gives no command; confirm_digest says nothing	M23
test_an_unloaded_manifest_names_an_own_gate_it_cannot_reach	stand-in	the manifest's refusal, then the copy's line; NEXT, WHY	M25
test_a_leg_mount_refused_is_named_on_every_python [mount-stat, mount-listing, listing-io-error]	stand-in	each refusal's line, NEXT, the advice for the cause (OTHER_REASON_FOLDER for EIO), no drift	M04, M05, M07, M19, M26
test_a_mount_whose_git_cannot_be_reached_is_not_one_without_a_git	stand-in, .git refused	legs, leg shape files (note) and placement (n/a) all say <leg>/.git: cannot be read	M06, M09, M10
test_beside_a_checkout_line_the_unread_mount_gets_the_advice	stand-in	the other leg's checkout line stays the NEXT; its WHY ends on the advice
test_a_member_mount_refused_is_named_on_every_python	stand-in, holder	members names the mount, NEXT this doctor, WHY, no drift	M08, M21, M22
test_a_leg_file_this_user_cannot_read_is_said_not_called_absent	stand-in	a refused stat and a refused read are cannot be read; the row is a note with no copy	M11, M12
test_a_bootstrap_this_user_cannot_reach_cannot_run_on_every_python	stand-in	own_bootstrap is False for a refused stat, True otherwise	M13
test_a_git_directory_this_user_cannot_reach_is_raised [keeps_modules, kept_gitdir, checkout_reach]	stand-in	each raises the refused stat	M14, M15, M16
test_a_root_whose_stat_is_refused_is_refused_on_every_python	stand-in, main in process	the root's own refused stat is the same refusal, never root-missing	M03
test_a_refused_read_out_of_a_check_is_named_by_run_checks	stand-in	inside the root: the gate's line, NEXT, WHY, detail; elsewhere: could not be run	M17
test_a_row_that_could_not_be_run_is_invalid_never_drift	verdict	a legs or members row with no entry is INVALID (<row>); a leg off its pin is still DRIFTED	M18
test_a_member_this_user_cannot_reach_is_no_drift_beside_one_that_is	verdict	drift only from a member that can be read	M20
test_a_record_this_user_cannot_reach_silences_nothing_on_every_python	stand-in, advisory	Tree.kind raises; the record silences nothing, it could not be read (PermissionError)	M27
test_a_record_in_a_folder_this_user_cannot_search	mode, advisory	the same under a real r-- folder
test_a_record_that_is_not_there_is_still_absent	control, advisory	no file, a name under a file: None; a file, a folder: file, dir
test_the_advisory_calls_nothing_there_what_the_gate_calls_so	parity	_ABSENT_ERRNOS and _ABSENT_WINERRORS equal the gate's	M28

Runs (/usr/bin/python3 -m pytest, Python 3.12.3, one process at a time):

set	on main 50178305 (before)	on 76ebca2e (after)
tests/test_shape_doctor.py	445 passed, 3 skipped	445 passed, 3 skipped
tests/test_doctor_*.py, files 1-9 (gitlink_repairs .. partial_clone)	478 passed, 6 skipped	478 passed, 6 skipped
tests/test_doctor_*.py, files 10-18 (paste_through_git .. validator_verdicts)	304 passed	304 passed
the trio, test_stdout_encoding.py, test_scaffold_leg_path_collisions.py, and the 8 files naming a changed function (test_adopt_finding_spelling, test_adopt_single_repository_record, test_bom_reads, test_bootstrap_non_utf8_branch, test_refusal_default_remediation, test_shape_advisory, test_validate_family_duplicates, test_validate_family_unnamed_mounts)	648 passed, 1 skipped	648 passed, 1 skipped
tests/test_doctor_unreadable_paths.py	(new)	34 passed

render-cli-reference.py --check: [ok] (no help text changed). The before-runs of the doctor files ran from a clean clone of 50178305; the first test_shape_doctor.py run from the worktree before any edit.

Mutants (each one line, applied alone to the fixed file, only its killer run with -k, the fixed bytes restored and checked by sha256):

mutant	the change	killed by
M01	validator_for: is_a(own_path, S_ISREG) -> own_path.is_file()	test_validator_for_raises_a_refused_stat_and_names_the_own_copy
M02	main: the search os.stat(<root>/.) -> pass	test_a_root_this_user_cannot_search_is_refused_by_name [root-000, root-r--]
M03	main: is_a(root, S_ISDIR) -> root.is_dir()	test_a_root_whose_stat_is_refused_is_refused_on_every_python
M04	mount_read: is_a(mount, S_ISDIR) -> mount.is_dir()	test_a_leg_mount_refused_is_named_on_every_python [mount-stat]
M05	mount_read: a refused listing read as empty	test_a_leg_mount_refused_is_named_on_every_python [mount-listing, listing-io-error]
M06	mount_read: .git asked with .exists()	test_a_mount_whose_git_cannot_be_reached_is_not_one_without_a_git
M07	check_legs: mount_read -> the two bare guards of 50178305	test_a_leg_mount_refused_is_named_on_every_python (all three)
M08	member_state: the same	test_a_member_mount_refused_is_named_on_every_python
M09	leg_shape_comparison: the bare guard back	test_a_mount_whose_git_cannot_be_reached_is_not_one_without_a_git
M10	audit_leg: the bare guard back	the same
M11	shape_file_state: here.is_file()	test_a_leg_file_this_user_cannot_read_is_said_not_called_absent
M12	check_leg_shape_files: ok for an unread leg or file	the same
M13	own_bootstrap: the refused stat raised	test_a_bootstrap_this_user_cannot_reach_cannot_run_on_every_python
M14	kept_gitdir: path.is_dir()	test_a_git_directory_this_user_cannot_reach_is_raised [kept_gitdir]
M15	keeps_modules: .is_dir()	the same [keeps_modules]
M16	checkout_reach: (git_dir / "modules").is_dir()	the same [checkout_reach]
M17	run_checks: named = None	test_a_refused_read_out_of_a_check_is_named_by_run_checks
M18	drifted_reasons: drift from a legs row with no entry	test_a_row_that_could_not_be_run_is_invalid_never_drift
M19	drifted_reasons: a leg whose mount cannot be read counted	test_a_leg_mount_refused_is_named_on_every_python (all three)
M20	drifted_reasons: a member that cannot be read counted	test_a_member_this_user_cannot_reach_is_no_drift_beside_one_that_is
M21	members_verdict: an unread member routed to a line	test_a_member_mount_refused_is_named_on_every_python
M22	member_problem: the unread mount not said first	the same
M23	gate_line: the refused stat raised	test_no_lockstep_line_is_named_for_a_gate_this_user_cannot_reach
M24	validator_row: the refused stat raised	test_validator_for_raises_a_refused_stat_and_names_the_own_copy
M25	unloaded_manifest_row: the refused stat raised	test_an_unloaded_manifest_names_an_own_gate_it_cannot_reach
M26	check_legs: the unread-mount branch dropped	test_a_leg_mount_refused_is_named_on_every_python [mount-listing, listing-io-error]
M27	Tree.kind: path.exists()	test_a_record_this_user_cannot_reach_silences_nothing_on_every_python
M28	shape_advisory._ABSENT_ERRNOS + EACCES	test_the_advisory_calls_nothing_there_what_the_gate_calls_so
M29	member_state: detached() asked of an unread mount	test_a_member_this_user_cannot_reach_is_named_and_no_drift [member-r--] (a real mode: 3.12)

All 29 KILLED (S/w430c/mutants.log); the fixed bytes restored after each and checked by sha256.

Not changed

• The shape currency row's copy-missing under 3.14 for a scripts/ or a .github/workflows/ this user cannot search, and so the verdicts DRIFTED (5 copy-missing) and DRIFTED (1 copy-missing): those rows come from update-shape.py's prepare, which the doctor imports. Slice B (lane 2's w430b) fixes them in update-shape.py; the doctor already renders a raised OSError by name (unreadable_copy_row, shape-doctor.py: for a pin or a contracts/ this user cannot read, the legs, manifest kinds and shape currency rows disagree with validate-pins.py's named refusal, and manifest kinds names a git checkout HEAD -- that discards work #847). This PR does not touch update-shape.py, and its tests assert no verdict of those two cells.
• The family row's crash under a holder members/ this user cannot search (validate-family.py raises PermissionError): slice E's templates/family-root/scripts/validate-family.py. It keeps the verdict INVALID (family) either way.
• main's other shape-doctor-root-unreadable (resolve() raising) keeps its words, --root <arg>: <exc>.
• scripts/shape_advisory.py:438 and :714 ((root / ".git").exists()): names directly in the root, which the doctor now refuses up front; adopt-project's source is slice H's.
• README.md's exit-3 sentence ("no such path, a refused --placement-plan, ...") does not name a root this user cannot search; the module docstring's EXIT CODES does. README is outside this slice's files.
• adopt-project.py and shape-doctor.py: a .gitmodules of whitespace is asked on every run, a dropped file whose blob the root also holds counts as root, _answered_legs is quadratic, and two validator code families have no placeholder row #914's shape-doctor.py half is left alone. No branch on origin names adopt-project.py and shape-doctor.py: a .gitmodules of whitespace is asked on every run, a dropped file whose blob the root also holds counts as root, _answered_legs is quadratic, and two validator code families have no placeholder row #914, and main 01a2b016 has not touched shape-doctor.py or shape_advisory.py since 50178305, so its lines could not be compared here; a reviewer holding adopt-project.py and shape-doctor.py: a .gitmodules of whitespace is asked on every run, a dropped file whose blob the root also holds counts as root, _answered_legs is quadratic, and two validator code families have no placeholder row #914 should check them against this diff.
• Main has moved to 01a2b016 (4 commits, none in these files); not merged, as asked.

Part of #430

🤖 Generated with Claude Code

Summary by Sourcery

Make unreadable paths explicit and consistent across shape validation, refusing inaccessible roots early and preventing inaccessible data from being mistaken for absence or drift.

New Features:

• Report unreadable paths consistently across the shape doctor and advisory tooling, including clear remediation guidance and JSON details.
• Refuse roots that the current user cannot search before evaluating any repository rows.

Bug Fixes:

• Prevent unreadable gates from falling back to standard templates, unreadable mounts and files from being treated as absent, and failed checks from being reported as DRIFTED.
• Preserve refused-stat errors across Python versions and ensure advisory records distinguish unreadable files from missing files.

Enhancements:

• Route unreadable leg and member mounts to INVALID findings with no misleading checkout or lockstep commands, while retaining applicable advice and rerun guidance.
• Update CLI documentation to describe unreadable roots as an exit-3 environment condition.

Documentation:

• Document the doctor's handling of roots that the current user cannot search in the README, CLI reference, and generated handbook.

Tests:

• Add comprehensive cross-platform and permission-mode coverage for unreadable roots, gates, mounts, files, git directories, members, advisory records, and verdict classification.

[sourcery-ai]

Reviewer's Guide

The PR introduces consistent, errno-aware unreadable-path semantics across shape-doctor.py and shape_advisory.py: roots that cannot be searched are refused up front, paths inside reachable roots are named with gate-aligned diagnostics, templates are never substituted for inaccessible project gates, and unreadable rows are INVALID or notes rather than false DRIFTED/absent results. A broad regression suite validates behavior across Python versions and both real permission modes and simulated OS refusals.

Sequence diagram for unreadable root handling

sequenceDiagram
    participant User
    participant Doctor as shape-doctor.py
    participant OS
    User->>Doctor: main(--root)
    Doctor->>OS: is_a(root, S_ISDIR)
    OS-->>Doctor: directory or refused OSError
    alt root stat refused
        Doctor-->>User: REFUSED shape-doctor-root-unreadable
    else root is searchable but not listable
        Doctor->>OS: stat(root/.)
        OS-->>Doctor: success
        Doctor-->>User: run checks
    else root search refused
        Doctor->>OS: stat(root/.)
        OS-->>Doctor: refused OSError
        Doctor-->>User: REFUSED shape-doctor-root-unreadable
    end

Loading

Sequence diagram for unreadable project gates

sequenceDiagram
    participant Doctor as shape-doctor.py
    participant Validator
    participant OS
    Doctor->>Validator: validator_for(ctx, own, template)
    Validator->>OS: is_a(own_path, S_ISREG)
    alt own gate readable
        OS-->>Validator: true
        Validator-->>Doctor: project gate
        Doctor->>Validator: run gate
    else own gate absent
        OS-->>Validator: false
        Validator-->>Doctor: standard template
        Doctor->>Validator: run template
    else own gate stat refused
        OS-->>Validator: refused OSError
        Validator-->>Doctor: raise OSError
        Doctor-->>Doctor: unreadable_gate_row()
        Doctor-->>Doctor: no template substitution
    end

Loading

Entity relationship diagram for unreadable check details

erDiagram
    CHECK_ROW ||--o{ LEG_ENTRY : contains
    CHECK_ROW ||--o{ MEMBER_ENTRY : contains
    LEG_ENTRY }o--|| MOUNT_READ_RESULT : records
    MEMBER_ENTRY }o--|| MOUNT_READ_RESULT : records
    CHECK_ROW {
        string status
        string next_command
        string why
    }
    LEG_ENTRY {
        string cannot_be_read
        string mount_cannot_be_read
        string head
        string pin
    }
    MEMBER_ENTRY {
        string mount_cannot_be_read
        string head
        string pin
    }
    MOUNT_READ_RESULT {
        string gate_line
        string reason
        boolean listing_refused
    }

Loading

Flow diagram for unreadable mount verdicts

flowchart TD
    A[Read leg or member mount] --> B{mount_read succeeds?}
    B -->|No| C[Record mount_cannot_be_read]
    C --> D[Name gate-aligned cannot-be-read line]
    D --> E[No checkout or lockstep command]
    E --> F[Run doctor again]
    B -->|Yes| G[Read mount listing and .git]
    G --> H{Readable mount data has a problem?}
    H -->|Yes| I[Evaluate pin or member drift]
    H -->|No| J[Continue normal checks]
    F --> K[INVALID, never DRIFTED]
    I --> L[DRIFTED only for readable entries]

Loading

File-Level Changes

Change	Details	Files
Normalize unreadable-path handling across the doctor so refused reads are explicitly reported, never confused with absence, and do not produce false drift or fallback behavior.	Added explicit root readability/searchability checks with exit-3 refusal diagnostics. Replaced path predicates at key doctor sites with errno-aware stat handling that propagates unexpected read failures. Named unreadable validator copies and prevented template substitution or gate execution. Added shared mount-read classification for legs and members, including unreadable listings and .git directories. Propagated mount/file refusal details into leg shape, placement, member, bootstrap, and low-level git-directory rows. Updated check exception handling to name refused paths inside the root while preserving generic failures elsewhere. Excluded unreadable or unevaluated entries from drift calculations so affected rows become INVALID rather than DRIFTED. Preserved the existing absent-path behavior for ENOENT, ENOTDIR, EBADF, ELOOP, and specified Windows errors.	shape-doctor.py
Make advisory record classification consistent with the gate across Python versions by distinguishing absent paths from paths whose stat operation was refused.	Added a local errno-aware _is_a helper with parity to the gate's absent-error sets. Changed Tree.kind to raise non-absent stat errors so unreadable records are reported as unreadable instead of absent. Added parity coverage for errno and Windows-error classifications.	scripts/shape_advisory.py
Add comprehensive regression coverage for unreadable roots, gates, mounts, files, members, git directories, advisory records, and verdict behavior.	Added real-mode and platform-independent stand-in tests for refused stat, listing, and file reads. Verified diagnostics, remediation, NEXT/WHY routing, JSON detail, template non-fallback, and no-drift semantics. Covered controls for truly absent paths, missing own copies, searchable-but-unlistable roots, and readable drift. Added mutation coverage expectations for the principal refusal and verdict branches.	tests/test_doctor_unreadable_paths.py

Possibly linked issues

• Every Path.is_file() / is_dir() / exists() guard in the shipped tools answers False to any OSError on Python 3.14 (3.12 and 3.13 raise PermissionError), so a directory this user cannot search reads as ABSENT: validate-pins.py skips its workflow @<sha> check, update-shape.py says copy-missing and update-pin-missing ("adopt the project") for files that are there, the doctor says DRIFTED (5 copy-missing), and bump-leg.py's remaining guards, and every other tool's, skip or misreport instead of refusing by name #430: The PR implements the issue’s unreadable-path handling for shape-doctor.py and shape_advisory.py, an explicitly scoped part of the broader fix.

---

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-2, 2026-10-19T21:58:40Z) Independent review of #975 (#430 slice C) at 3fd80cbe, for lane openRepoShape-2: READY

Fixed since 76ebca2e, none open:

• SHOULD (fixed): S3776 on shape-doctor.py:9966 member_state. It went from 13 to 16 at 76ebca2e; refused is now required, which brings it to 14.
• NIT (fixed): the new exit-3 cause, a root this user cannot search, is now in README.md, the handbook, the openRepoShape and src/openreposhape/cli.py --doctor help, and docs/cli.md.

Checked and true

• Merges cleanly with main 3864b18cc and with update-shape.py: a path in the root or the upstream this user cannot read is update-unreadable on every Python, so a scripts/ it can list but not search is no longer five copy-missing and a validator it cannot stat is never SKIPPED #976's branch (head 59b12500).
• render-cli-reference.py --check is [ok].
• The docs set (4 files) passed 320.
• The doctor tests on the merge:
  • files 10 to 18 plus the new file: 338 passed;
  • files 1 to 9: 482 passed, 6 skipped, 1 failed.
• The one failure is test_doctor_gitlink_repairs.py::test_a_hand_committed_gitlink_names_both_bump_leg_commands. It fails the same way on main 3864b18cc without this PR whenever test_doctor_partial_clone.py is collected with it, and passes when run alone. It was there before this PR.
• On the earlier merge with main 2a78ae1a, test_shape_doctor.py passed 445, with 3 skipped.
• The trio set (13 files) passed 670, with 1 skipped.
• The new file fails 30 of 34 against the base's code, and all 4 that pass are expected to pass there.
• No composite asserts and no real duplication. Every Tree.kind and Tree.text caller catches the exception it can now raise.

Could not verify

• tests/test_openreposhape_command.py.
• The 17 extra mutants. The writer reports its own 29 as all killed.
• The probes. On reading only:
  • A leg file at mode 000 gives a note under COMPLIANT. I accept that: that row is advisory, and an absent or differing leg file is also a note.
  • .git/modules/spec at mode 000 is a read git makes, not a stat site in the doctor, so it is outside this slice.
• The tests on the merge with update-shape.py: a path in the root or the upstream this user cannot read is update-unreadable on every Python, so a scripts/ it can list but not search is no longer five copy-missing and a validator it cannot stat is never SKIPPED #976.
• A real Python 3.14: this host has only 3.12.

Lane 2's note: #975 is green at 3fd80cbe (tests and SonarCloud), and CI's full tests job covers tests/test_openreposhape_command.py. It lands after #976 and #986, one at a time, each gated again on the main of its turn. The order-dependent failure on main (test_a_hand_committed_gitlink_names_both_bump_leg_commands with test_doctor_partial_clone.py collected) is not this PR's.

Lane: openreposhape-2 (openRepoShape-2)

[brettheap]

(lane openRepoShape-2, 2026-10-19T22:39:47Z) Addendum to the independent review of #975 (#430 slice C) at 3fd80cbe, for lane openRepoShape-2: READY stands

This closes the items my READY left under "Could not verify". It was run on the merge of 3fd80cbe with main 46cf9240b. #976 has not landed: ls-remote shows main at 46cf9240b and #976's branch at 59b12500. Nothing new is a MUST, so #975 can land as it is. The three items below are for follow-ups.

Findings

1. SHOULD, as a follow-up issue (not a MUST, does not hold the landing): a leg whose git directory this user cannot read still gives DRIFTED. This is the .git/modules/spec at mode 000 cell.
   • The pins row names the path correctly: REFUSED pin-submodule-unreadable: .git/modules/spec: cannot be read (Permission denied).
   • The legs row says spec: populated, but git cannot read a HEAD in it (shape-doctor.py:7444). drifted_reasons counts that leg as off its pin, and drift outranks INVALID.
   • So the verdict is DRIFTED (1 leg(s) not at the pin) for a leg that is at its pin, and placement says spec: it is not a git repository.
   • It is the same before and after this PR, on 3.12 and under a 3.14-like shim. It is git's own read, not a stat site, and not in slice C's site list, so it is not a regression.
   • Fix: where own_git holds and head is None, read the gitdir: line of the mount's .git file and ask that path with is_a. A refusal becomes the leg's mount_cannot_be_read line, so the leg is not counted as drift and the row gives the cure.
2. NIT (not a MUST): 5 of my 17 mutants survive. All five sit in branches the tests never build, and the code is right by reading:
   • MI, :7428: a leg with no gitlink and a mount this user cannot reach loses the mount's line.
   • MJ, :10315: the .gitmodules guard for a member this user cannot reach. Without it, 3.12 raises out of the members row when another member needs make bootstrap.
   • MK1, :10324, and MK2, :10344: the cure beside another member's bootstrap or checkout line.
   • ML, :10285: rerun. This one is close to equivalent, because the advice already ends with "Then run this doctor again".
   • Fix: add a holder with two members, one this user cannot reach and one off its pin, as test_beside_a_checkout_line_the_unread_mount_gets_the_advice already does for legs. Add a leg with no gitlink over a mount this user cannot reach.
3. NIT (not a MUST): a leg file at mode 000 is COMPLIANT with a note but no cure. I accept the COMPLIANT.
   • The cell is spec/CLAUDE.md at 000. Before this PR it was INVALID (leg-shape-files) on both Pythons; now it is COMPLIANT, exit 0, on both, with the note CLAUDE.md cannot be read (Permission denied).
   • Why I accept it:
     • The leg shape files row gates nothing: an absent or differing leg file is also only a note under COMPLIANT.
     • So no content of that file could change the verdict.
     • The old INVALID came from the row crashing ("could not be run"), not from a judgment.
   • The PR's stated reason ("the legs row asserts the mount") covers a whole mount, not one file.
   • Fix: every other path in this PR that cannot be read carries the gate's advice as its WHY (cannot_read_why). Give this note the same WHY (shape-doctor.py:7832).

Checked and true

• tests/test_openreposhape_command.py: 461 passed.
• 12 of my 17 mutants are killed:
  • MA: the advisory's _is_a errno filter dropped;
  • MB: the doctor's is_a errno filter dropped;
  • MC: os.stat(root) asked in place of root/.;
  • MD: the root refusal always given the folder advice;
  • ME and MF: mount_read swallowing the .git refusal, then the mount's own;
  • MG: the NEXT dropped for a member this user cannot reach;
  • MH: a refused listing counted as a refused file;
  • MM: the file half of the leg shape files note check dropped;
  • MO: an empty legs row counted as drift;
  • MP: no NEXT on the run_checks row;
  • MR: validator_for falling back to the template on a refused stat.
• Probes: verdicts with the base's doctor (50178305) and with the head's, each on 3.12 and under a 3.14-like sitecustomize shim:

cell	base	head
spec/ at 000	DRIFTED (1 leg(s) not at the pin), both	INVALID (pins), both
spec/ at 444	DRIFTED, both	INVALID (pins), both
spec/ at 111	DRIFTED, both	INVALID (legs), both, with spec: cannot be listed
holder's members/ at 000	DRIFTED (a member is not at its pin), both	INVALID (family), both
holder's members/IRRS at 000	DRIFTED, both	INVALID (family), both
scripts/validate-manifest.py file at 000	INVALID (manifest, pins), both	the same
scripts/repo_shape.py file at 000	INVALID (manifest, pins), both	the same
.git/modules/spec at 000	DRIFTED, both	the same (finding 1)
spec/CLAUDE.md file at 000	INVALID (leg-shape-files), both	COMPLIANT, both (finding 3)
controls (project and holder)	COMPLIANT	COMPLIANT

• scripts/ and .github/workflows/ at 444 still give DRIFTED (5 copy-missing) and DRIFTED (1 copy-missing) under the shim at this head. Those rows come from update-shape.py: a path in the root or the upstream this user cannot read is update-unreadable on every Python, so a scripts/ it can list but not search is no longer five copy-missing and a validator it cannot stat is never SKIPPED #976's update-shape.py.
• No cell gives CANNOT ANSWER, and no cell prints a traceback.
• The merge with update-shape.py: a path in the root or the upstream this user cannot read is update-unreadable on every Python, so a scripts/ it can list but not search is no longer five copy-missing and a validator it cannot stat is never SKIPPED #976 (59b12500) is clean.
  • The new test file, test_doctor_unreadable_pin.py and test_update_shape_unreadable.py: 134 passed.
  • With update-shape.py: a path in the root or the upstream this user cannot read is update-unreadable on every Python, so a scripts/ it can list but not search is no longer five copy-missing and a validator it cannot stat is never SKIPPED #976 in, scripts/ at 444 is INVALID (manifest, pins) and .github/workflows/ at 444 is INVALID (pins), on both 3.12 and the shim. The two DRIFTED cells left to slice B are closed there.

Could not verify

• A real Python 3.14. Only 3.12 is on this host, so 3.14 is covered by the shim and the in-process refused_stat only.

Lane 2's decision: #975 lands as it is, after #976 and #986, gated again over the main of its turn. The SHOULD and the two NITs go to follow-ups, which lane 2 proposes to Brett Heap before filing.

Lane: openreposhape-2 (openRepoShape-2)

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
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 3 days and 20 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[brettheap]

(lane openRepoShape-2, 2026-10-20T09:52:10Z) A correction to lane 2's notes on #975 (6278304447 and 6278933012), and to its landing text, d7ee65a. test_a_hand_committed_gitlink_names_both_bump_leg_commands is not order-dependent. It fails whenever LANES_LANE is exported, which is #1042, filed by lane 1.

• Lane 2's gate ran from a lane shell that exports LANES_LANE. With it unset, test_doctor_gitlink_repairs.py and test_doctor_partial_clone.py together pass 53 of 53 at dc7cd49b7.
• The landing's statement still holds: the failure was red on main without shape-doctor.py and shape_advisory.py: a path in the root this user cannot reach is named on every Python, never read as absent or stood in for by the template, a root it cannot search is refused first, and a row that could not ask is never DRIFTED #975, and it is not shape-doctor.py and shape_advisory.py: a path in the root this user cannot reach is named on every Python, never read as absent or stood in for by the template, a root it cannot search is refused first, and a row that could not ask is never DRIFTED #975's.
• Lane 2's gate script now unsets LANES_LANE, as CI's environment has none.

Lane: openreposhape-2 (openRepoShape-2)