shape-doctor.py: the `legs`, `manifest kinds` and `shape currency` rows name a pin or `contracts/` this user cannot read as validate-pins.py does, with its advice and never `git checkout HEAD --`, and the verdict is INVALID, not DRIFTED (#847) by brettheap · Pull Request #860 · opensoft/openRepoShape

brettheap · 2026-10-17T20:53:28Z

What changed

#712 (PR #827, on main as 9f235da2) makes validate-pins.py refuse a pin, the manifest or a pinned copy it cannot reach or open by name: REFUSED yaml-unreadable: contracts/spec-pin.yaml: cannot be read (Permission denied), with a remedy for the cause. Three of the doctor's rows read the same files themselves and said something else (#847, from lane 3's RV827 S3). The fix is in shape-doctor.py alone, plus a new test file. Each row now asks as the gate asks and says the gate's line. It asks the stat first, then the read. A file that is not there is "missing", and any other OSError is a refusal, as the gate's _ABSENT_ERRNOS say.

legs (check_legs, through pin_commit, now read by pin_read): a leg whose pin cannot be read says <leg>: contracts/<role>-pin.yaml: cannot be read (<reason>), so there is no pinned commit to compare HEAD against. The line is kept in the leg's cannot_be_read, and drifted_reasons does not count that leg, so the verdict is the gate's INVALID, never DRIFTED. The pin is asked before the mount (round 2). Where a mount fact comes first (no gitlink, an empty mount, no .git of its own, a HEAD git cannot read or on a branch with no commit), the row says that fact and then names the pin: <leg>: <fact>, and contracts/<role>-pin.yaml: cannot be read (<reason>).
manifest kinds (check_manifest_kinds, manifest_candidates): a file it cannot reach or open is <path>: cannot be read (<reason>); a contracts/ it cannot list is contracts: cannot be listed (<reason>), the gate's words for a directory (templates/assembly-root/scripts/validate-pins.py: a .github/workflows/ directory that this user cannot list or search ends the run in a PermissionError traceback, exit 1, where a workflow file it cannot open is a workflow-unreadable refusal, exit 2 #434). It comes first among the row's faults and is listed under detail.cannot_be_read. No git state is asked of it, so there is no git checkout HEAD --.
shape currency (check_shape_currency, new unreadable_copy_row and pin_refusal_row): the copies cannot be compared: <path>: cannot be read (<reason>). This covers the shape pin and any copy inside the root that prepare cannot read.
- The shape pin is asked by pin_read only where read_pin will not read it. read_pin's is_file() raised the refusal up to Python 3.13, and calls the pin missing from 3.14.
- A pin that reads is read once.
NEXT and WHY, the same in all three rows. The NEXT is this doctor again (doctor_line, the same line unreadable_next prints for a file only a person can mend). The WHY is the gate's advice for the cause, word for word, then Then run this doctor again:
- for a permission: 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.
- for any other cause, of a file: Where the operating system gave another reason, put a regular file this user can open back in its place, or take away one nobody wants, and make sure nothing is changing the directory while this runs.
- for any other cause, of a folder it cannot list: Where the operating system gave another reason, put a directory this user can list back in its place, and make sure nothing is changing it while this runs. These are the gate's words for a directory (_workflows_unlistable).
- In legs, beside the checkout line or the gate's line, the advice follows what that line does.
Left alone: the pins row quotes the gate's own output, which is validate-pins.py and repo_shape.py: a pin, the manifest or a shape copy the gate cannot reach or read is refused by name, relative to the root, once and with its cause's advice, and every name and path it prints is spelled (#712) #827's on main now (shown below), and the manifest row quotes validate-manifest.py. Context.legs and the readers of the manifest's legs: list are untouched (shape-doctor.py, bootstrap.py, bump-leg.py and update-shape.py: a manifest's legs: that is not a list ends in a TypeError, or reads as a project with no legs, where #714 makes the three gates report manifest-legs #832, PR shape-doctor.py, bootstrap.py, bump-leg.py and update-shape.py: a legs: that is not a list, or holds an entry that is not a mapping, is said in #714's words, so the doctor's leg rows wait on the manifest row instead of calling the project one with no legs, bootstrap places no leg for it, and bump-leg.py and update-shape.py refuse it by name where each ended in a TypeError (#832) #862). Only the pin branch inside check_legs's loop and its NEXT choice changed.

Round 1 (rv860, #860 issuecomment-6242528166)

Lane 5's rv860 found a2b0e48c READY, with one SHOULD and NITs 2 to 9. Each item, and what this round did:

rv860 item	what was done
The merge	Main `ca47b71` merged as `de7b1942`, bringing #827 (`9f235da2`) and #779 (`c100843b`). One path conflicted, `shape-doctor.py`, in one hunk of `unreadable_next`: this branch's `doctor_line(ctx)` against #779's `stuck` branch. #779's lines were taken as main has them, so `unreadable_next` is main's byte for byte.
SHOULD 1: no test held the doctor's copies of the gate's lists and advice equal	Fixed, both steps, with six parity tests (12 cases). They load `shape-doctor.py`, `templates/assembly-root/scripts/validate-pins.py` and `scripts/bump-leg.py` by path. The errno and winerror tuples are held equal to the gate's and bump-leg's. The gate's `OTHER_REASON` must equal the doctor's plus exactly one space (the gate joins on `+`, the doctor on `" ".join`; neither changed, nothing stripped). The inline permission and folder sentences are read through the remedies the gate's `_unreadable_file` and `_workflows_unlistable` build. `cannot_read_why` is held equal to bump-leg's `_cannot_open_advice`, and `cannot_be_read`/`cannot_be_listed` to the gate's lines. Mutant R2 is killed (2 failed).
NIT 2: surviving mutants	Every survivor is killed by a new case: R1, R2, B1, B2, C1, E1, E2, G1, H2, I2, K1, L1, N1, N2, N4 and O1. R1 and N2 are not left: a hand-set `winerror` and a stood-in `pythonpath_unnamable` (#278) reach them. See the mutant table below.
NIT 3: a `contracts/` unlistable for another reason got the file sentence	Fixed. New `OTHER_REASON_FOLDER` is the gate's directory sentence. `manifest_candidates` marks a listing, and `cannot_read_why(refused, unlisted)` gives a folder that sentence. The listing test is parametrized over a permission and EIO.
NIT 4: the drift fallback disappears because of another leg	No code change, as ruled. The `drifted_reasons` docstring now says it exactly, and a test pins `["1 leg(s) not at the pin"]` alone and `[]` beside a refused pin (kills O1).
NIT 5: no advice beside the checkout line	Fixed. The checkout WHY now ends with `said`, after the next-run sentence. The test pairs a refused spec pin with a `code` leg past its pin (kills N1, and P2).
NIT 6: pins read twice	`shape currency` is fixed: `pin_read` is asked only after `read_pin` raised (`pin_refusal_row`), so a pin that reads is read once (P1 holds it). `legs` is left: it reads a second time only for a pin that gave no commit, and `pin_commit` also serves the `pins` row.
NIT 7: docstring reflow leftovers	Fixed, both lines joined.
NIT 8: `mode()` repeats `mode_of`	Fixed by import, not by conftest. `mode()` is gone, and `mode_of` is imported from `test_validate_pins_unreadable_workflows_dir.py`, as #827's `test_validate_pins_named_and_spelled.py` already does. That removes the copy without editing two files outside this PR and the shared conftest.
NIT 9: cognitive complexity	No change, as ruled; noted under "What it cannot tell". The shape pin's branch moved out of `check_shape_currency` into `pin_refusal_row`.

Round 2 (RV860c, #860 issuecomment-6245274456)

Lane 3's RV860c re-checked round 1 at bcb8c58b and found it READY, with no MUST and no SHOULD, and two new NITs. Each item, and what this round did:

RV860c item	what was done
NIT A: a refused pin on a leg that is not checked out is not named by `legs`, and the verdict is DRIFTED	Fixed, by RV860c's fix (a). `check_legs` asks `pin_read` whenever the pin gave no commit, before the mount branches (no gitlink, an empty mount, no `.git` of its own, an unborn HEAD, a HEAD git cannot read). The leg carries `cannot_be_read`, its problem says the mount's fact and then `, and <the gate's line>`, and the refused pin's advice follows whatever line is the NEXT (the checkout line stays). RV860c's probe (`spec` emptied, its pin at 000) was `DRIFTED (1 leg(s) not at the pin)` and is now `INVALID (pins, manifest-kinds)`. Six mode cases cover it, one per mount branch, each asserting the detail, the advice and the verdict, plus a stand-in for the empty mount. Mutants A1 (round 1's placement), A2 (the call removed) and A3 (the pin not named beside the fact) are killed.
NIT B: mutant M5 survives, because no test refuses a pin's `stat` for another cause	Fixed. `test_another_reason_is_given_the_gates_other_advice` is parametrized over a refused `stat` and a refused read, and M5 is killed by `[stat]`.
Informational: "Shared files" is stale	Re-taken against main `0905eef5` and all 33 other open PRs, on this head and on this head merged with main; see "Shared files".
The body	Round 1's edit had replaced the body Sourcery last edited, and its summary block with it. Sourcery wrote a new block 9 s after this round's push (04:41:01Z), and that block is kept at the end, unchanged.

Before and Now

Re-measured this round on a real scaffold (scaffold-project.py --local-remote-dir), run as uid 1000 with Python 3.12.3 and git 2.43.0.

A stub gh (exit 1) was first on PATH, with GH_TOKEN=bogus and an empty GH_CONFIG_DIR.
Before is main ca47b71, whose root carries validate-pins.py and repo_shape.py: a pin, the manifest or a shape copy the gate cannot reach or read is refused by name, relative to the root, once and with its cause's advice, and every name and path it prints is spelled (#712) #827's gate. Now is this head: the first five cases were measured at bcb8c58b and again at 1c4e3cdf, where they print the same bytes, and the sixth at 1c4e3cdf.
Both shapes are standalone copies of the commit (git archive). <ROOT> is the probe root and <SHAPE> the copy the doctor ran from.
On main, the pins row already says the gate's line. In the same report, the doctor's own rows say something else, and for a leg's pin or contracts/ the verdict is DRIFTED.

Each Now row's WHY is, or ends with, the gate's permission advice, word for word, then Then run this doctor again. No case printed a traceback.

A pin at 000 (contracts/spec-pin.yaml)

row	Before (main `ca47b71`)	Now (this head)
`pins`	`the project's own scripts/validate-pins.py refuses (exit 2): REFUSED yaml-unreadable: contracts/spec-pin.yaml: cannot be read (Permission denied)`; NEXT `python3 <ROOT>/scripts/validate-pins.py --root <ROOT>`	`the project's own scripts/validate-pins.py refuses (exit 2): REFUSED yaml-unreadable: contracts/spec-pin.yaml: cannot be read (Permission denied)`; NEXT `python3 <ROOT>/scripts/validate-pins.py --root <ROOT>`
`manifest-kinds`	`unreadable as YAML: contracts/spec-pin.yaml (yaml-unreadable: cannot be read (Permission denied))`; NEXT `git -C <ROOT> checkout HEAD -- contracts/spec-pin.yaml`	`contracts/spec-pin.yaml: cannot be read (Permission denied)`; NEXT `python3 <SHAPE>/shape-doctor.py --root <ROOT>`; WHY the gate's permission advice
`shape-currency`	ok	ok
`legs`	`spec: contracts/spec-pin.yaml carries no 40-hex commit to compare HEAD against`; NEXT `python3 <ROOT>/scripts/validate-pins.py --root <ROOT>`	`spec: contracts/spec-pin.yaml: cannot be read (Permission denied), so there is no pinned commit to compare HEAD against`; NEXT `python3 <SHAPE>/shape-doctor.py --root <ROOT>`; WHY the gate's permission advice
verdict	`DRIFTED (1 leg(s) not at the pin)`	`INVALID (pins, manifest-kinds)`

contracts/ at 000

row	Before (main `ca47b71`)	Now (this head)
`pins`	`the project's own scripts/validate-pins.py refuses (exit 2): REFUSED yaml-unreadable: contracts/spec-pin.yaml: cannot be read (Permission denied)`; NEXT `python3 <ROOT>/scripts/validate-pins.py --root <ROOT>`	`the project's own scripts/validate-pins.py refuses (exit 2): REFUSED yaml-unreadable: contracts/spec-pin.yaml: cannot be read (Permission denied)`; NEXT `python3 <ROOT>/scripts/validate-pins.py --root <ROOT>`
`manifest-kinds`	`could not be run: [Errno 13] Permission denied: '<ROOT>/contracts'`; no NEXT	`contracts: cannot be listed (Permission denied)`; NEXT `python3 <SHAPE>/shape-doctor.py --root <ROOT>`; WHY the gate's permission advice
`shape-currency`	`could not be run: [Errno 13] Permission denied: '<ROOT>/contracts/shape-pin.yaml'`; no NEXT	`the copies cannot be compared: contracts/shape-pin.yaml: cannot be read (Permission denied)`; NEXT `python3 <SHAPE>/shape-doctor.py --root <ROOT>`; WHY the gate's permission advice
`legs`	`spec: contracts/spec-pin.yaml carries no 40-hex commit to compare HEAD against; code: contracts/code-pin.yaml carries no 40-hex commit to compare HEAD against`; NEXT `python3 <ROOT>/scripts/validate-pins.py --root <ROOT>`	`spec: contracts/spec-pin.yaml: cannot be read (Permission denied), so there is no pinned commit to compare HEAD against; code: contracts/code-pin.yaml: cannot be read (Permission denied), so there is no pinned commit to compare HEAD against`; NEXT `python3 <SHAPE>/shape-doctor.py --root <ROOT>`; WHY the gate's permission advice
verdict	`DRIFTED (2 leg(s) not at the pin)`	`INVALID (manifest, pins, manifest-kinds)`

contracts/ at r-- (listable, not searchable)

row	Before (main `ca47b71`)	Now (this head)
`pins`	`the project's own scripts/validate-pins.py refuses (exit 2): REFUSED yaml-unreadable: contracts/spec-pin.yaml: cannot be read (Permission denied)`; NEXT `python3 <ROOT>/scripts/validate-pins.py --root <ROOT>`	`the project's own scripts/validate-pins.py refuses (exit 2): REFUSED yaml-unreadable: contracts/spec-pin.yaml: cannot be read (Permission denied)`; NEXT `python3 <ROOT>/scripts/validate-pins.py --root <ROOT>`
`manifest-kinds`	`could not be run: [Errno 13] Permission denied: '<ROOT>/contracts/shape-pin.yaml'`; no NEXT	`contracts/code-pin.yaml: cannot be read (Permission denied), contracts/repository-naming.yaml: cannot be read (Permission denied), contracts/shape-pin.yaml: cannot be read (Permission denied), contracts/spec-pin.yaml: cannot be read (Permission denied)`; NEXT `python3 <SHAPE>/shape-doctor.py --root <ROOT>`; WHY the gate's permission advice
`shape-currency`	`could not be run: [Errno 13] Permission denied: '<ROOT>/contracts/shape-pin.yaml'`; no NEXT	`the copies cannot be compared: contracts/shape-pin.yaml: cannot be read (Permission denied)`; NEXT `python3 <SHAPE>/shape-doctor.py --root <ROOT>`; WHY the gate's permission advice
`legs`	`spec: contracts/spec-pin.yaml carries no 40-hex commit to compare HEAD against; code: contracts/code-pin.yaml carries no 40-hex commit to compare HEAD against`; NEXT `python3 <ROOT>/scripts/validate-pins.py --root <ROOT>`	`spec: contracts/spec-pin.yaml: cannot be read (Permission denied), so there is no pinned commit to compare HEAD against; code: contracts/code-pin.yaml: cannot be read (Permission denied), so there is no pinned commit to compare HEAD against`; NEXT `python3 <SHAPE>/shape-doctor.py --root <ROOT>`; WHY the gate's permission advice
verdict	`DRIFTED (2 leg(s) not at the pin)`	`INVALID (manifest, pins, manifest-kinds)`

The shape pin at 000 (contracts/shape-pin.yaml)

row	Before (main `ca47b71`)	Now (this head)
`pins`	`the project's own scripts/validate-pins.py refuses (exit 2): REFUSED yaml-unreadable: contracts/shape-pin.yaml: cannot be read (Permission denied)`; NEXT `python3 <ROOT>/scripts/validate-pins.py --root <ROOT>`	`the project's own scripts/validate-pins.py refuses (exit 2): REFUSED yaml-unreadable: contracts/shape-pin.yaml: cannot be read (Permission denied)`; NEXT `python3 <ROOT>/scripts/validate-pins.py --root <ROOT>`
`manifest-kinds`	`unreadable as YAML: contracts/shape-pin.yaml (yaml-unreadable: cannot be read (Permission denied))`; NEXT `git -C <ROOT> checkout HEAD -- contracts/shape-pin.yaml`	`contracts/shape-pin.yaml: cannot be read (Permission denied)`; NEXT `python3 <SHAPE>/shape-doctor.py --root <ROOT>`; WHY the gate's permission advice
`shape-currency`	`the copies cannot be compared, because contracts/shape-pin.yaml does not read as a pin: REFUSED yaml-unreadable: <ROOT>/contracts/shape-pin.yaml: cannot be read (Permission denied)`; NEXT `git -C <ROOT> checkout HEAD -- contracts/shape-pin.yaml`	`the copies cannot be compared: contracts/shape-pin.yaml: cannot be read (Permission denied)`; NEXT `python3 <SHAPE>/shape-doctor.py --root <ROOT>`; WHY the gate's permission advice
`legs`	ok	ok
verdict	`INVALID (pins, manifest-kinds)`	`INVALID (pins, manifest-kinds)`

A pinned copy at 000 (contracts/repository-naming.yaml)

row	Before (main `ca47b71`)	Now (this head)
`pins`	`the project's own scripts/validate-pins.py refuses (exit 2): REFUSED shape-copy-unreadable: contracts/repository-naming.yaml: cannot be read (Permission denied)`; NEXT `python3 <ROOT>/scripts/validate-pins.py --root <ROOT>`	`the project's own scripts/validate-pins.py refuses (exit 2): REFUSED shape-copy-unreadable: contracts/repository-naming.yaml: cannot be read (Permission denied)`; NEXT `python3 <ROOT>/scripts/validate-pins.py --root <ROOT>`
`manifest-kinds`	`unreadable as YAML: contracts/repository-naming.yaml (yaml-unreadable: cannot be read (Permission denied))`; NEXT `git -C <ROOT> diff HEAD -- contracts/repository-naming.yaml`	`contracts/repository-naming.yaml: cannot be read (Permission denied)`; NEXT `python3 <SHAPE>/shape-doctor.py --root <ROOT>`; WHY the gate's permission advice
`shape-currency`	`could not be run: [Errno 13] Permission denied: '<ROOT>/contracts/repository-naming.yaml'`; no NEXT	`the copies cannot be compared: contracts/repository-naming.yaml: cannot be read (Permission denied)`; NEXT `python3 <SHAPE>/shape-doctor.py --root <ROOT>`; WHY the gate's permission advice
`legs`	ok	ok
verdict	`INVALID (manifest, pins, manifest-kinds)`	`INVALID (manifest, pins, manifest-kinds)`

spec emptied, and its pin at 000 (RV860c's NIT A)

row	Before (main `ca47b71`)	Now (this head)
`pins`	`the project's own scripts/validate-pins.py refuses (exit 2): REFUSED yaml-unreadable: contracts/spec-pin.yaml: cannot be read (Permission denied)`; NEXT `python3 <ROOT>/scripts/validate-pins.py --root <ROOT>`	`the project's own scripts/validate-pins.py refuses (exit 2): REFUSED yaml-unreadable: contracts/spec-pin.yaml: cannot be read (Permission denied)`; NEXT `python3 <ROOT>/scripts/validate-pins.py --root <ROOT>`
`manifest-kinds`	`unreadable as YAML: contracts/spec-pin.yaml (yaml-unreadable: cannot be read (Permission denied))`; NEXT `git -C <ROOT> checkout HEAD -- contracts/spec-pin.yaml`	`contracts/spec-pin.yaml: cannot be read (Permission denied)`; NEXT `python3 <SHAPE>/shape-doctor.py --root <ROOT>`; WHY the gate's permission advice
`shape-currency`	ok	ok
`legs`	`spec: the gitlink is there and the directory is empty -- an unbootstrapped clone`; NEXT `git -C <ROOT> submodule update --init --recursive --checkout -- spec`	`spec: the gitlink is there and the directory is empty -- an unbootstrapped clone, and contracts/spec-pin.yaml: cannot be read (Permission denied)`; NEXT `git -C <ROOT> submodule update --init --recursive --checkout -- spec`; WHY what the line does, then the gate's permission advice
verdict	`DRIFTED (1 leg(s) not at the pin)`	`INVALID (pins, manifest-kinds)`

Every other row that reads `contracts/` or a pin

Ten more places were checked:

pins: it quotes the gate, validate-pins.py and repo_shape.py: a pin, the manifest or a shape copy the gate cannot reach or read is refused by name, relative to the root, once and with its cause's advice, and every name and path it prints is spelled (#712) #827's on main. Left alone.
manifest: it quotes validate-manifest.py (the naming copy). Left alone: it is that gate's line (see "What it cannot tell").
agent files: it reads the shape pin's rows through pinned_paths, only when an agent file is absent. Left alone (see "What it cannot tell").
pins -> with_gitlink_repairs -> gitlinks_off_their_pins: it reads each pin through pin_commit. A refused pin is still None there, so it is left out of the bump-leg.py lines, as before; that reader of legs: itself is untouched.
pins -> with_merged_away_rows -> refusals_ahead: it calls read_pin/prepare, but only after the gate exits 1 with merged-away findings alone. An unreadable pin or copy makes the gate refuse, so it is never reached.
manifest kinds -> unreadable_next -> pinned_copies, tool_written, edited_by_hand: these read the shape pin and catch OSError. They are asked only of files that do not load for another reason, and are unchanged.
gitlink_left_behind and pin_at: they read git blobs, not files.
read_here: its samefile catches OSError.
members and family (a holder): they read members' manifests, not pins. The holder's own shape currency and manifest kinds run the code fixed here.
what is here (not a root): it only asks whether a contracts/ exists.

Tests

tests/test_doctor_unreadable_pin.py, new, 52 cases. The row cases assert the row's exact line and, where the case is about them, its exact NEXT and WHY. The mode cases also assert that no traceback and no git checkout HEAD -- was printed.

Mode cases (11; a real mode, and the doctor run as a subprocess). They skip on Windows and as root through CANNOT_RUN_AS_ROOT, imported from test_validate_pins_unreadable_workflow.py, whose reason says why: root reads a mode-000 file, and Windows modes do not refuse a read. The modes are set by mode_of, imported from test_validate_pins_unreadable_workflows_dir.py (as validate-pins.py and repo_shape.py: a pin, the manifest or a shape copy the gate cannot reach or read is refused by name, relative to the root, once and with its cause's advice, and every name and path it prints is spelled (#712) #827's test_validate_pins_named_and_spelled.py takes it).
- a pin at 000, with the verdict INVALID (pins, manifest-kinds);
- contracts/ at 000 and at r--, all three rows, with the verdict INVALID (manifest, pins, manifest-kinds);
- the shape pin at 000: both rows give one NEXT and one WHY;
- a pinned copy at 000;
- a leg whose mount is wrong and whose pin is at 000, one case per mount branch: no gitlink, an empty mount, no .git of its own with its gitdir kept and with it gone, an unborn HEAD, and a HEAD git cannot read. Each asserts the mount's fact and then the pin's line, the leg's cannot_be_read, the advice in the WHY and INVALID (pins, manifest-kinds) (round 2).
Stand-in cases (in process, on every platform and as root):
- The refusals are put in by hand: a refused stat through validate-pins.py and repo_shape.py: a pin, the manifest or a shape copy the gate cannot reach or read is refused by name, relative to the root, once and with its cause's advice, and every name and path it prints is spelled (#712) #827's refused_stat, imported from test_bump_leg_unopenable.py, which also answers is_file() as Python 3.14 does; and a refused read or listing through refusing, written here.
- The pin cases:
  - a refused pin: the legs and manifest kinds lines, NEXT, WHY and detail, with drifted_reasons == [];
  - another cause (EIO), for a refused stat and for a refused read, which gets the gate's other advice and no chmod;
  - a shape pin whose stat is refused, which is named and is not update-pin-missing.
- The folder and copy cases:
  - a contracts/ that cannot be listed, for a permission and for EIO (the folder sentence);
  - a refused file said first, beside an unregistered kind;
  - a copy prepare cannot read;
  - refused_in_root;
  - an OSError out of prepare that is not the root's, which is raised as it was (outside the root, no file named, nothing there).
- The legs NEXT cases:
  - beside the checkout line, the WHY says the next-run sentence and then the advice;
  - beside an unborn HEAD, the doctor again, with the advice and then the unborn sentence;
  - beside an empty mount, the checkout line, the pin named after the mount's fact, the advice, and no drift;
  - where no gate line can be built, there is no NEXT and the advice is the WHY.
Helper cases:
- manifest_candidates over a root with no contracts/, or with a contracts that is a file;
- is_a asked of a folder and of a name holding a NUL;
- refused_read given each of Windows' three "nothing there" winerrors, set by hand;
- a red legs row with no leg off its pin: drift by len(off) or 1 alone, and none beside a pin this user cannot read.
Parity cases (rv860's SHOULD 1), which load shape-doctor.py, templates/assembly-root/scripts/validate-pins.py and scripts/bump-leg.py by path:
- ABSENT_ERRNOS/ABSENT_WINERRORS against the gate's and bump-leg's;
- the gate's OTHER_REASON against the doctor's and one space;
- the remedy the gate's _unreadable_file and _workflows_unlistable build for each cause, which ends on the doctor's sentence and RUN_AGAIN;
- cannot_read_why against bump-leg's _cannot_open_advice, for a permission, another cause and both;
- cannot_be_read and cannot_be_listed against the gate's lines.
Controls:
- a missing pin keeps main's words and is still drift;
- a pin that does not load for another reason (not UTF-8) keeps main's words;
- beside a lockstep fact (a missing code pin), the gate stays the NEXT, the advice joins the WHY, and the other leg is drift.

The doctor's own fixtures are imported from test_shape_doctor.py, and doctor_again from test_doctor_recorded_answers.py. Neither changed file holds a new non-ASCII byte.

What it cannot tell

The manifest row quotes validate-manifest.py, which neither validate-pins.py and repo_shape.py: a pin, the manifest or a shape copy the gate cannot reach or read is refused by name, relative to the root, once and with its cause's advice, and every name and path it prints is spelled (#712) #827 nor this PR changes. For a contracts/ this user cannot search, or for the naming copy at 000, it names <ROOT>/contracts/repository-naming.yaml by its absolute path, as : cannot be read (Permission denied) (validate-pins.py and repo_shape.py: a pin, the manifest or a shape copy the gate cannot reach or read is refused by name, relative to the root, once and with its cause's advice, and every name and path it prints is spelled (#712) #827's load_yaml). That gate could be a follow-up.
agent files, with the shape pin unreadable and an agent file also absent, reads no pin rows. It calls an absent AGENTS-shape.md unpinned and names update-shape.py check. That takes two faults at once, and its words are not the issue's. Not changed here.
The NEXT is the doctor again. The doctor cannot run the chmod for a person, and cannot tell whether the mode, the directory's mode or the owner is at fault: the WHY names all three, as the gate's remedy does.
Names are printed raw, as these rows print every other path. validate-pins.py and repo_shape.py: a pin, the manifest or a shape copy the gate cannot reach or read is refused by name, relative to the root, once and with its cause's advice, and every name and path it prints is spelled (#712) #827's gate spells a name holding a control character by repr. Pin paths are fixed (contracts/<role>-pin.yaml), so only a role, or a file under contracts/, holding such a character would print differently.
A refused read after prepare in shape currency (the root README.md's Shape: line) still ends in could not be run: it is not a pin and not under contracts/. A pinned copy outside contracts/ at 000 is named by shape currency now, since one handler names any refused read of a file in the root.
Platforms: Windows and root are covered by the stand-in cases only, and no Windows host was run. A Windows ACL refusal is a PermissionError, read the same way, and the three "nothing there" winerrors are set by hand on an OSError. Python 3.14's is_file() is simulated by refused_stat; only 3.12.3 was run.
update-shape.py's prepare closes its upstream only on a Refusal. For the local-path upstream the doctor passes, the upstream holds no temporary directory, so the new OSError path leaves nothing open.
Cognitive complexity (rv860's NIT 9): check_shape_currency, check_legs and check_manifest_kinds were over 15 on main and grow here. drifted_reasons grows to about 12. This round moved the shape pin's branch out into pin_refusal_row. SonarCloud has not been read: its MCP server did not connect.

Choices for the reviewer

NEXT = this doctor again, in all three rows. validate-pins.py and repo_shape.py: a pin, the manifest or a shape copy the gate cannot reach or read is refused by name, relative to the root, once and with its cause's advice, and every name and path it prints is spelled (#712) #827's remedy is prose, and a remedy is the row's WHY, never its NEXT (shape-doctor.py: no NEXT holds prose or a backtick (manifest kinds joins prose NEXTs with "; ", and zsh runs FAMILY_BESIDE_FIX's backticks) #548, remedy_as_why). It is not a chmod line, for three reasons: it cannot be right on Windows, it cannot say whether the file, a directory above it or the owner is at fault, and the doctor never changes a mode. It is not None either: unreadable_next already prints the doctor again for a file only a person can mend, and shape currency must print what manifest kinds prints for the same file.
WHY = the gate's advice sentence, verbatim, by the cause (PERMISSION_ADVICE, OTHER_REASON, OTHER_REASON_FOLDER). It ends with the doctor's own Then run this doctor again in place of the gate's Then run the same command again. The gate's opening sentence (this validator reads ..., never a pass) is about the validator and is not carried.
A folder's words: for a contracts/ the row cannot list, the line is contracts: cannot be listed (<reason>), validate-pins.py's words for a directory (templates/assembly-root/scripts/validate-pins.py: a .github/workflows/ directory that this user cannot list or search ends the run in a PermissionError traceback, exit 1, where a workflow file it cannot open is a workflow-unreadable refusal, exit 2 #434). It has no trailing slash, as the gate names .github/workflows. For another cause, the WHY is the gate's directory sentence (rv860's NIT 3).
The legs row stays a FINDING (it was one), and a leg whose pin cannot be read is not drift: the verdict is the gate's INVALID. n/a and note were rejected, because other legs in the same row may be off their pin.
- With a refused pin and another leg whose problem is not "off its pin" (an empty mount whose pin is gone), the row is no drift either. That is two faults at once, and the gate refuses the pin first. drifted_reasons documents it, and a test pins it (rv860's NIT 4).
Precedence in legs: the checkout line first, then the lockstep gate, then the doctor again (a refused pin), then none (an unborn HEAD, no url). Beside a checkout line or the gate's line, the advice follows what the line does (rv860's NIT 5).
Precedence in manifest kinds: a file or folder that cannot be read comes first, ahead of the restore and the take-out, and the reason still names every fault. It goes in a new detail.cannot_be_read (only when there is one), not in unreadable, refusals or restore, because no git state is asked.
Copies of the gate's lists and words, held equal by the parity cases. The doctor imports nothing from templates/, and repo_shape.py is a pinned copy, so ABSENT_ERRNOS is a third copy (after bump-leg.py and validate-pins.py), and the advice sentences are copies too.
- The gate's sentences end on a space, because it joins them with +; the doctor's do not, because it joins them with " ".join. Neither side is changed.
- The test asks for exactly one space, and does not strip.
- The gate's inline permission and folder sentences are read through the remedy its own functions build, as a person reads them.
shape currency names a refused read of any copy inside the root out of prepare, not only one under contracts/, because it is one handler. An OSError about a file outside the root (the standard's own), one naming no file, or one saying nothing is there is raised as before.
doctor_line spells the doctor-again line once for this PR's rows. unreadable_next keeps shape-doctor.py: a conflicted shape pin's NEXT takes the side whose pin reads, and names no line where no side's pin reads, so run as printed it no longer leaves the doctor naming the same NEXT again (#752) #779's inline line, the same string, as main has it. That was the merge's one conflict, resolved by taking shape-doctor.py: a conflicted shape pin's NEXT takes the side whose pin reads, and names no line where no side's pin reads, so run as printed it no longer leaves the doctor naming the same NEXT again (#752) #779's lines.
The pins are read once where they read:
- check_shape_currency asks pin_read only after read_pin raised.
- check_legs asks pin_read a second time only for a pin that gave no commit, now before the mount branches. A small split-out helper could let it read once without changing pin_commit's answer to its other caller, the pins row's gitlink repairs. That was not done here, since no behaviour is wrong as it stands (rv860's NIT 6, RV860c).
The brief named scripts/shape-doctor.py; the file is shape-doctor.py at the root.

Shared files

git merge-tree --write-tree of this head 1c4e3cdf against main 0905eef5 and every other open PR (git 2.43.0, PR heads fetched at 2026-10-18T03:50Z). This head is based on ca47b71, so each PR is also merged against this head merged with main (tree 1dff46f4, clean), and against main alone.

base	head of base	this head `1c4e3cdf`	this head + main `0905eef5`	main `0905eef5` alone
main	`0905eef5`	clean	-	-
#769	`843f6953`	clean	clean	clean
#770	`837920c2`	clean	clean	clean
#771	`f1234bc6`	clean	clean	clean
#773	`296a6dd6`	clean	clean	clean
#775	`7f6ee36b`	clean	clean	clean
#778	`fe7b30f6`	clean	clean	clean
#780	`68f27877`	clean	clean	clean
#789	`033c49d7`	clean	clean	clean
#791	`1d774ab3`	clean	clean	clean
#794	`2ffe154c`	CONFLICT: `shape-doctor.py`, `templates/family-root/scripts/siblings.py`, `tests/test_family.py`, `tests/test_shape_doctor.py`	CONFLICT: `shape-doctor.py`, `templates/family-root/scripts/siblings.py`	CONFLICT: `shape-doctor.py`, `templates/family-root/scripts/siblings.py`
#802	`510ae681`	clean	clean	clean
#806	`a1498632`	clean	clean	clean
#811	`b6f56cad`	clean	clean	clean
#815	`05a1ebb3`	clean	clean	clean
#819	`233a334e`	clean	clean	clean
#821	`e15c237b`	clean	CONFLICT: `README.md`, `docs/handbook.html`, `shape-doctor.py`	CONFLICT: `README.md`, `docs/handbook.html`, `shape-doctor.py`
#823	`7c20ba96`	clean	clean	clean
#828	`90649e53`	clean	clean	clean
#831	`db202f53`	clean	clean	clean
#843	`08f7a283`	CONFLICT: `adopt-project.py`	CONFLICT: `adopt-project.py`	CONFLICT: `adopt-project.py`
#844	`8bfa5268`	clean	clean	clean
#845	`8f6a38e3`	CONFLICT: `tests/test_adopt_git_reads.py`	CONFLICT: `tests/test_adopt_git_reads.py`	CONFLICT: `tests/test_adopt_git_reads.py`
#849	`d98df568`	CONFLICT: `tests/test_bump_leg_branch_and_push_line.py`, `tests/test_family_tracking_branch.py`	CONFLICT: `tests/test_bump_leg_branch_and_push_line.py`, `tests/test_family_tracking_branch.py`	CONFLICT: `tests/test_bump_leg_branch_and_push_line.py`, `tests/test_family_tracking_branch.py`
#859	`495d4b33`	clean	clean	clean
#861	`70801c91`	clean	CONFLICT: `adopt-project.py`	CONFLICT: `adopt-project.py`
#862	`b905bf8c`	clean	clean	clean
#865	`f7072d08`	clean	clean	clean
#867	`8bb85cbf`	clean	clean	clean
#868	`62074123`	clean	clean	clean
#869	`40531e19`	clean	clean	clean
#870	`03fe51e6`	clean	clean	clean
#871	`66fc8f6b`	clean	CONFLICT: `adopt-project.py`	CONFLICT: `adopt-project.py`
#872	`d183e769`	clean	clean	clean

No conflict is this PR's. Against this head merged with main, the seven conflicts are each main's own, on the same paths:

For siblings.py and shape-doctor.py: a Windows junction to nothing at ../<Project> is NOT A CLONE, as a link to nothing is, so the dry run no longer says would clone and the doctor's members row no longer calls the slot absent (#793) #794 and repo_shape.py, setup-project.py, shape-doctor.py, README and the handbook: under Git Bash (MSYSTEM set) the lines that follow the host are quoted for sh, through one question, host_shell_dialect, so the doctor's lines, setup's family lines and family.py's NEXT, switch -c, add and cd lines paste whole in the shell that printed them, and README's Windows sentence says so #821, the shape-doctor.py conflict regions are identical, line for line, in the merge with this head and main and in the merge with main alone (1 and 2 regions).
The two extra paths siblings.py and shape-doctor.py: a Windows junction to nothing at ../<Project> is NOT A CLONE, as a link to nothing is, so the dry run no longer says would clone and the doctor's members row no longer calls the slot absent (#793) #794 shows against this head alone (tests/test_family.py, tests/test_shape_doctor.py) come from main's newer commits: siblings.py and shape-doctor.py: a Windows junction to nothing at ../<Project> is NOT A CLONE, as a link to nothing is, so the dry run no longer says would clone and the doctor's members row no longer calls the slot absent (#793) #794 is stacked on siblings.py and shape-doctor.py: a link to nothing at ../<Project> is NOT A CLONE, reported and left as it is, so the dry run no longer says would clone where the real run ends CLONE FAILED, and the doctor's members row no longer calls the slot absent (#784) #788, which main now holds. repo_shape.py, setup-project.py, shape-doctor.py, README and the handbook: under Git Bash (MSYSTEM set) the lines that follow the host are quoted for sh, through one question, host_shell_dialect, so the doctor's lines, setup's family lines and family.py's NEXT, switch -c, add and cd lines paste whole in the shell that printed them, and README's Windows sentence says so #821, adopt-project.py: execute asks about both leg repositories, on the disk or on GitHub, before it makes either, and check asks the same, so a code leg that already exists no longer leaves the spec leg made, and a --local-remote-dir that cannot hold them no longer ends in a traceback after plan ok (#798) #861 and family.py, adopt-project.py and the four tools' --org: init asks GitHub's limits on the topic, the --org and the holder's name before any repository exists, check finds what execute refuses from one list, and an --org GitHub gives no organisation (., a trailing hyphen, --) is refused where GitHub is asked (#863) #871 merge clean with this head alone for the same reason, and conflict with main alone.
shape-doctor.py: a shape copy renamed on both sides of a merge, DD at its old name, is named gone on both sides with each new name a side's own commit holds the base's blob of it at, never as a merge of hunks git did not merge (#783) #789 (033c49d7), shape-doctor.py, bootstrap.py, bump-leg.py and update-shape.py: a legs: that is not a list, or holds an entry that is not a mapping, is said in #714's words, so the doctor's leg rows wait on the manifest row instead of calling the project one with no legs, bootstrap places no leg for it, and bump-leg.py and update-shape.py refuse it by name where each ended in a TypeError (#832) #862 (b905bf8c), bootstrap.py and repo_shape.py: a .shape-upstream-tip or a YAML file a Windows editor saved with a byte-order mark reads as the text it holds, so the upstream notice names the tip, a marked project.yaml is no longer schema_version is None, and every reader of a marked pin, the doctor's included, reads it alike (#855) #868 (62074123) and shape-doctor.py, family.py and the family root's bootstrap.py and validate-family.py: a holder's members: that is not a list, or holds an entry that is not a mapping, is said in the gate's words, so the doctor's members row waits on the family row instead of calling the family empty, add, bump, remove, make bootstrap and make siblings refuse it by name where each ended in a TypeError, read no members or committed the entry away, and --no-members finds the entry (#864) #870 (03fe51e6) are clean.
On this head merged with main, tests/test_doctor_unreadable_pin.py, tests/test_doctor_non_ascii_paths.py and tests/test_doctor_paste_through_git.py (the last two new on main) gave 199 passed.

Pinned copy, the run and the mutants

Not a pinned copy: shape-doctor.py is in none of shape_materialize.COPIED_FROM_SHAPE, COPIED_VERBATIM, FAMILY_COPIED_FROM_SHAPE or FAMILY_COPIED_VERBATIM, so no root's update-shape.py check shows it.
Round 2's run (one run, on this head's bytes: 1c4e3cdf, shape-doctor.py sha256 5fa1f8fb..., the new file 916e4578...).
- The command: /usr/bin/python3 -m pytest -q -rs -p no:cacheprovider -o tmp_path_retention_policy=failed --basetemp=<scratch>/bt.
- The 20 files: RV860c's 22 less the two that are new on main and not on this branch (tests/test_doctor_non_ascii_paths.py, tests/test_doctor_paste_through_git.py). That is the new file and the other 14 tests/test_doctor_*.py; tests/test_shape_doctor.py; tests/test_validate_pins_unreadable_workflows_dir.py; and tests/test_repo_hygiene.py, tests/test_agents_md_codes.py and tests/test_cli_reference.py.
- The environment: GIT_CONFIG_GLOBAL an empty file, GIT_CONFIG_NOSYSTEM=1 and GIT_ALLOW_PROTOCOL unset; a stub gh (exit 97) first on PATH, with GH_TOKEN=bogus and an empty GH_CONFIG_DIR; Python 3.12.3, uid 1000, df -i / at 78%.
- The result: 1126 passed, 3 skipped in 1770.75s (0:29:30), exit 0. The 3 skips are tests/test_shape_doctor.py:10424, the PowerShell line run only on a Windows host.
- On this head merged with main 0905eef5 (tree 1dff46f4), the new file and the two main-only doctor files gave 199 passed. On this head merged with main 80aee84e, which landed during the run (tree d327d86c, clean), the new file gave 52 passed.
Round 1's run, at bcb8c58b over the same command and environment on 20 files: 1118 passed, 3 skipped in 2039.07s, exit 0.
Round 2's mutants: the 33 of round 1 (N6 ported again to round 2's text), RV860c's M5, and A1 to A3 for NIT A.
- Each was applied to shape-doctor.py, the new file was run at 52 cases, and the file was put back byte for byte from a saved copy. Its sha256 was 5fa1f8fb... after every mutant and at the end.
- None survives:

mutant	what it restores	round 1, `bcb8c58b`, new file (43 or 44)	now: this head, new file (52)
R1	refused_read ignores ABSENT_WINERRORS	killed (3 failed, 40 passed)	killed (3 failed, 49 passed)
R2	ABSENT_ERRNOS is ENOENT alone (ENOTDIR, EBADF, ELOOP read as refusals)	killed (2 failed, 41 passed)	killed (2 failed, 50 passed)
R3	ABSENT_ERRNOS without ENOENT	killed (22 failed, 21 passed)	killed (24 failed, 28 passed)
B1	is_a no longer catches ValueError (a NUL in a name)	killed (1 failed, 42 passed)	killed (1 failed, 51 passed)
B2	is_a ignores the kind (a directory or fifo named *.yaml is a regular file)	killed (2 failed, 41 passed)	killed (2 failed, 50 passed)
B3	is_a answers False to every OSError (Python 3.14 is_file)	killed (5 failed, 38 passed)	killed (6 failed, 46 passed)
C1	os_reason has no fallback for an OSError without strerror	killed (1 failed, 42 passed)	killed (1 failed, 51 passed)
E1 (ported)	cannot_read_why: permission advice only when ALL refusals are permissions	killed (1 failed, 42 passed)	killed (1 failed, 51 passed)
E2 (ported)	cannot_read_why: other advice only when NO refusal is a permission	killed (2 failed, 41 passed)	killed (2 failed, 50 passed)
G1	pin_read returns any cause, not only a refusal (UnicodeDecodeError, ENOENT)	killed (1 failed, 43 passed)	killed (1 failed, 51 passed)
G2	pin_read calls a refused stat 'no file'	killed (4 failed, 39 passed)	killed (5 failed, 47 passed)
H1 (ported)	manifest_candidates keeps a file whose stat is refused	killed (2 failed, 41 passed)	killed (3 failed, 49 passed)
H2	manifest_candidates lists contracts/ without asking whether it is a directory	killed (2 failed, 41 passed)	killed (2 failed, 50 passed)
H4 (ported)	a contracts/ that cannot be listed is silently empty	killed (3 failed, 40 passed)	killed (3 failed, 49 passed)
I1 (ported)	manifest kinds: no doctor-again NEXT/WHY override	killed (12 failed, 31 passed)	killed (13 failed, 39 passed)
I2	manifest kinds: the refused files are said LAST in the reason	killed (1 failed, 42 passed)	killed (1 failed, 51 passed)
I3 (ported)	manifest kinds: a refused read is ALSO 'unreadable as YAML'	killed (5 failed, 38 passed)	killed (5 failed, 47 passed)
J1	unreadable_copy_row marks itself environment (CANNOT ANSWER)	killed (4 failed, 39 passed)	killed (4 failed, 48 passed)
K1	refused_in_root does not ask for a filename	killed (2 failed, 41 passed)	killed (2 failed, 50 passed)
K2	refused_in_root names an absent file too	killed (2 failed, 41 passed)	killed (2 failed, 50 passed)
K3	refused_in_root names a file outside the root	killed (2 failed, 41 passed)	killed (2 failed, 50 passed)
L1	shape currency names every OSError out of prepare, inside the root or not	killed (3 failed, 40 passed)	killed (3 failed, 49 passed)
N1	legs: a refused pin does not set rerun	killed (1 failed, 42 passed)	killed (1 failed, 51 passed)
N2	legs: lockstep gate with no why drops the advice	killed (1 failed, 42 passed)	killed (1 failed, 51 passed)
N3	legs: the refused branch's why drops the advice	killed (7 failed, 36 passed)	killed (9 failed, 43 passed)
N4	legs: the refused branch's why drops the stuck sentences	killed (1 failed, 42 passed)	killed (1 failed, 51 passed)
N5	legs: the refused branch outranks the lockstep gate	killed (2 failed, 41 passed)	killed (2 failed, 50 passed)
N6 (ported again)	legs: a refused pin is also a lockstep fact	killed (7 failed, 36 passed)	killed (8 failed, 44 passed)
O1	drifted_reasons: a red legs row with no leg off its pin is never drift	killed (1 failed, 42 passed)	killed (1 failed, 51 passed)
O2	drifted_reasons: the red legs row is always drift	killed (6 failed, 37 passed)	killed (13 failed, 39 passed)
P1	NIT 6: pin_refusal_row does not ask pin_read (a refused shape pin is unreadable_pin_row's again)	killed (4 failed, 39 passed)	killed (4 failed, 48 passed)
P2	NIT 5: the checkout WHY drops the refused pin's advice	killed (1 failed, 42 passed)	killed (4 failed, 48 passed)
P3	NIT 3: a folder that cannot be listed gets the file sentence	killed (1 failed, 42 passed)	killed (1 failed, 51 passed)
M5	RV860c's M5: pin_read calls a stat refused for any cause but permission no file	survived (44 passed, RV860c)	killed (1 failed, 51 passed)
A1	NIT A undone: the pin is asked only where every mount branch passed (round 1's placement)	new this round	killed (7 failed, 45 passed)
A2	NIT A: the new pin_read call removed	new this round	killed (19 failed, 33 passed)
A3	NIT A: the pin's line is not said beside a mount fact	new this round	killed (7 failed, 45 passed)

Round 1's mutants, at bcb8c58b: rv860's 30, six of them ported to this round's text, and three for this round's own lines (P1 to P3).
- Each was applied to shape-doctor.py, the new file was run, and the file was put back byte for byte from a saved copy. Its sha256 was ff562ba0... after every mutant and at the end.
- The full pass ran the new file at 43 cases. G1 was run again once its control, the 44th case, was added, and that kills it. In rv860's run, test_shape_doctor.py and test_doctor_unfinished_merge.py also killed G1 (28 failed).
- None survives now:

mutant	what it restores	then: rv860 at `a2b0e48c`, new file (15)	now: this head, new file
R1	refused_read ignores ABSENT_WINERRORS	survived (15 passed)	killed (3 failed, 40 passed)
R2	ABSENT_ERRNOS is ENOENT alone (ENOTDIR, EBADF, ELOOP read as refusals)	survived (15 passed)	killed (2 failed, 41 passed)
R3	ABSENT_ERRNOS without ENOENT	killed (14 failed, 1 passed)	killed (22 failed, 21 passed)
B1	is_a no longer catches ValueError (a NUL in a name)	survived (15 passed)	killed (1 failed, 42 passed)
B2	is_a ignores the kind (a directory or fifo named *.yaml is a regular file)	survived (15 passed)	killed (2 failed, 41 passed)
B3	is_a answers False to every OSError (Python 3.14 is_file)	killed (5 failed, 10 passed)	killed (5 failed, 38 passed)
C1	os_reason has no fallback for an OSError without strerror	survived (15 passed)	killed (1 failed, 42 passed)
E1 (ported)	cannot_read_why: permission advice only when ALL refusals are permissions	survived (15 passed)	killed (1 failed, 42 passed)
E2 (ported)	cannot_read_why: other advice only when NO refusal is a permission	survived (15 passed)	killed (2 failed, 41 passed)
G1	pin_read returns any cause, not only a refusal (UnicodeDecodeError, ENOENT)	survived (15 passed)	killed (1 failed, 43 passed)
G2	pin_read calls a refused stat 'no file'	killed (4 failed, 11 passed)	killed (4 failed, 39 passed)
H1 (ported)	manifest_candidates keeps a file whose stat is refused	killed (2 failed, 13 passed)	killed (2 failed, 41 passed)
H2	manifest_candidates lists contracts/ without asking whether it is a directory	survived (15 passed)	killed (2 failed, 41 passed)
H4 (ported)	a contracts/ that cannot be listed is silently empty	killed (2 failed, 13 passed)	killed (3 failed, 40 passed)
I1 (ported)	manifest kinds: no doctor-again NEXT/WHY override	killed (10 failed, 5 passed)	killed (12 failed, 31 passed)
I2	manifest kinds: the refused files are said LAST in the reason	survived (15 passed)	killed (1 failed, 42 passed)
I3 (ported)	manifest kinds: a refused read is ALSO 'unreadable as YAML'	killed (5 failed, 10 passed)	killed (5 failed, 38 passed)
J1	unreadable_copy_row marks itself environment (CANNOT ANSWER)	killed (4 failed, 11 passed)	killed (4 failed, 39 passed)
K1	refused_in_root does not ask for a filename	survived (15 passed)	killed (2 failed, 41 passed)
K2	refused_in_root names an absent file too	killed (1 failed, 14 passed)	killed (2 failed, 41 passed)
K3	refused_in_root names a file outside the root	killed (1 failed, 14 passed)	killed (2 failed, 41 passed)
L1	shape currency names every OSError out of prepare, inside the root or not	survived (15 passed)	killed (3 failed, 40 passed)
N1	legs: a refused pin does not set rerun	survived (15 passed)	killed (1 failed, 42 passed)
N2	legs: lockstep gate with no why drops the advice	survived (15 passed)	killed (1 failed, 42 passed)
N3	legs: the refused branch's why drops the advice	killed (6 failed, 9 passed)	killed (7 failed, 36 passed)
N4	legs: the refused branch's why drops the stuck sentences	survived (15 passed)	killed (1 failed, 42 passed)
N5	legs: the refused branch outranks the lockstep gate	killed (1 failed, 14 passed)	killed (2 failed, 41 passed)
N6	legs: a refused pin is also a lockstep fact	killed (6 failed, 9 passed)	killed (7 failed, 36 passed)
O1	drifted_reasons: a red legs row with no leg off its pin is never drift	survived (15 passed)	killed (1 failed, 42 passed)
O2	drifted_reasons: the red legs row is always drift	killed (5 failed, 10 passed)	killed (6 failed, 37 passed)
P1	NIT 6: pin_refusal_row does not ask pin_read (a refused shape pin is unreadable_pin_row's again)	new this round	killed (4 failed, 39 passed)
P2	NIT 5: the checkout WHY drops the refused pin's advice	new this round	killed (1 failed, 42 passed)
P3	NIT 3: a folder that cannot be listed gets the file sentence	new this round	killed (1 failed, 42 passed)

Closes #847

🤖 Generated with Claude Code

Summary by Sourcery

Make shape-doctor report unreadable pins and contract files consistently with validate-pins.py and classify these failures as invalid rather than drift.

Bug Fixes:

Align shape-doctor's legs, manifest-kinds, and shape-currency rows with validate-pins.py when pins, manifests, directories, or pinned copies are unreadable.
Report unreadable pins as INVALID rather than counting them as drift, and avoid recommending destructive git checkout commands.

Enhancements:

Add consistent unreadable-file and unlistable-directory diagnostics, remediation guidance, and doctor-again instructions across affected rows.
Preserve mount-specific leg findings while naming unreadable pins and excluding them from drift calculations.

Tests:

Add comprehensive coverage for permission and other I/O failures, unreadable mounts and pins, cross-platform absence handling, diagnostic parity, and verdict behavior.

…ws name a pin or `contracts/` this user cannot read as validate-pins.py does, with its advice and never `git checkout HEAD --`, and the verdict is INVALID, not DRIFTED (#847) #712 (PR #827) makes validate-pins.py refuse a pin it cannot reach or open by name: `REFUSED yaml-unreadable: contracts/spec-pin.yaml: cannot be read (Permission denied)`, with a remedy for the cause. Three of the doctor's rows read the same files themselves and said something else. Measured on main fc86720, Python 3.12.3, as a user who is not root: - `legs`, through `pin_commit`: `spec: contracts/spec-pin.yaml carries no 40-hex commit to compare HEAD against`, and the verdict counted the leg as off its pin, `DRIFTED (1 leg(s) not at the pin)`, for a pin at 000 and `DRIFTED (2 ...)` for a `contracts/` at 000 or `r--`. - `manifest kinds`: for a pin at 000, `unreadable as YAML: ... ([Errno 13] Permission denied: '<root>/...')` with NEXT `git -C <root> checkout HEAD -- contracts/spec-pin.yaml`, which discards what the file holds that no commit does (`git status` calls a file it cannot open changed); for a `contracts/` at 000, `could not be run: [Errno 13] Permission denied: '<root>/contracts'`. - `shape currency`: `could not be run: [Errno 13] ...` for a `contracts/` at 000 or `r--` and for a pinned copy at 000, and the same `git checkout HEAD --` for a shape pin at 000. Now each row asks as the gate asks (the `stat` first, then the read, the absent errnos read as the gate reads them) and says the gate's line: - `legs`: `spec: contracts/spec-pin.yaml: cannot be read (Permission denied), so there is no pinned commit to compare HEAD against`, kept in the leg's `cannot_be_read`; `drifted_reasons` does not count such a leg, so the verdict is the gate's `INVALID (pins, manifest-kinds)`. - `manifest kinds`: `contracts/spec-pin.yaml: cannot be read (Permission denied)`, or `contracts: cannot be listed (Permission denied)` for a folder it cannot list (the gate's words for a directory, #434), first among the row's faults, under `detail`'s `cannot_be_read`. - `shape currency`: `the copies cannot be compared: <path>: cannot be read (Permission denied)`, for the shape pin (asked before `read_pin`, whose `is_file()` calls it missing on Python 3.14) and for a copy `prepare` cannot read inside the root. Each NEXT is this doctor again and each why the gate's advice for the cause, word for word (`Make what this user may not open readable by this user: ...`, or `Where the operating system gave another reason, ...`), then `Then run this doctor again`. A pin that is not there keeps main's words and is drift as before. The `pins` row already quotes the gate and is left alone. `Context.legs` and the readers of `legs:` are untouched. Tests: tests/test_doctor_unreadable_pin.py, 15 cases. Five run a real mode (a pin, `contracts/` at 000 and `r--`, the shape pin, a copy) and skip on Windows and as root; ten stand in for a refused `stat` (`refused_stat`, as Python 3.14 answers it), read or listing in process, on every platform and as root. Lane: openreposhape-4 (openRepoShape-4) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

sourcery-ai · 2026-10-17T20:53:42Z

Reviewer's Guide

Updates shape-doctor.py so unreadable pins, manifests, directories, and pinned copies produce validate-pins.py-compatible INVALID diagnostics, doctor-again remediation, and no destructive checkout advice, with unreadable legs excluded from DRIFTED verdicts; adds focused end-to-end and stand-in tests for these behaviors.

Sequence diagram for unreadable pin handling

sequenceDiagram
    participant Doctor
    participant PinReader
    participant OS
    participant Verdict

    Doctor->>PinReader: pin_read(root, relative)
    PinReader->>OS: is_a(path, stat.S_ISREG)
    alt refused stat or read
        OS-->>PinReader: OSError
        PinReader-->>Doctor: None, cause
        Doctor->>Doctor: cannot_be_read(pin, cause)
        Doctor->>Doctor: doctor_line(ctx)
        Doctor->>Verdict: exclude leg from drifted_reasons
        Verdict-->>Doctor: INVALID
    else missing or invalid pin
        PinReader-->>Doctor: None, None
        Doctor->>Doctor: report carries no 40-hex commit
    else readable pin
        PinReader->>OS: load_yaml(path)
        OS-->>PinReader: pin data
        PinReader-->>Doctor: pin data, None
    end

Flow diagram for unreadable artifact diagnosis

flowchart TD
    A[Doctor checks repository artifact] --> B{stat succeeds?}
    B -->|No, absent error| C[Keep missing behavior]
    B -->|No, other OSError| D[Report cannot be read or listed]
    B -->|Yes| E{Read or list succeeds?}
    E -->|No| D
    E -->|Yes| F[Continue existing validation]
    D --> G[Use gate advice for cause]
    G --> H[Next: run shape-doctor.py again]
    D --> I[Verdict: INVALID]
    I --> J[No git checkout advice]

File-Level Changes

Change	Details	Files
Align unreadable-file handling in the doctor’s legs, manifest-kinds, and shape-currency checks with validate-pins.py’s stat/read semantics and diagnostic wording.	Classify missing-path errnos separately from refused stat, read, and directory-list operations. Add shared formatting and cause-specific remediation helpers, including a doctor-again command. Report unreadable pins and directories explicitly without attempting git restoration commands. Preserve unreadable-pin details and exclude those legs from drift calculations.	`shape-doctor.py`
Add comprehensive coverage for permission, stat, listing, and other-I/O failures while preserving missing-pin and mixed-leg behavior.	Test real filesystem modes and cross-platform in-process refusal stand-ins. Assert exact row messages, NEXT commands, WHY advice, verdicts, details, and absence of checkout commands or tracebacks. Cover Python-version-sensitive stat behavior, root containment, non-permission advice, and unchanged missing-pin drift.	`tests/test_doctor_unreadable_pin.py`

Assessment against linked issues

Issue	Objective	Addressed
#847	Make the doctor's `legs`, `manifest kinds`, and `shape currency` rows identify unreadable pins, files, and `contracts/` directories by name and reason, consistent with `validate-pins.py` rather than reporting missing pins, DRIFTED, or raw permission errors.	✅
#847	For these unreadable-file and directory faults, provide the permission or other-cause remedy without recommending `git checkout HEAD --`, and ensure an unreadable leg pin is not counted as drift.	✅
#847	Add tests for unreadable pins and `contracts/` directories, including refused-stat stand-ins that work on platforms or runtimes where mode-based refusal cannot be tested.	✅

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 · 2026-10-17T21:13:22Z

(lane openRepoShape-5, 2026-10-17T21:13:24Z) Partial review of #860 (#847) at a2b0e48, for lane openRepoShape-4: INCOMPLETE (stopped for an account swap)

I stopped for the swap before reaching a verdict. Every run I started is killed. I changed no branch in any repository, pushed nothing and posted nothing. No MUST has come up so far.

Findings so far, most severe first

SHOULD 1. No test keeps the doctor's copies of the gate's lists and advice equal to the gate's.

Where: shape-doctor.py:2892-2893 (ABSENT_ERRNOS, ABSENT_WINERRORS) and shape-doctor.py:2959-2970 (PERMISSION_ADVICE, OTHER_REASON).
There are now three copies of the errno list: scripts/bump-leg.py:356-357, templates/assembly-root/scripts/validate-pins.py:240-241 (:253-254 on validate-pins.py and repo_shape.py: a pin, the manifest or a shape copy the gate cannot reach or read is refused by name, relative to the root, once and with its cause's advice, and every name and path it prints is spelled (#712) #827) and the doctor's. git grep -ln ABSENT_ERRNOS a2b0e48c -- tests/ returns nothing.
They are equal today. On the merge of main, validate-pins.py and repo_shape.py: a pin, the manifest or a shape copy the gate cannot reach or read is refused by name, relative to the root, once and with its cause's advice, and every name and path it prints is spelled (#712) #827 and shape-doctor.py: the legs, manifest kinds and shape currency rows name a pin or contracts/ this user cannot read as validate-pins.py does, with its advice and never git checkout HEAD --, and the verdict is INVALID, not DRIFTED (#847) #860 (c221d378), an AST comparison printed ABSENT doctor==gate: True doctor==bump: True, WIN ... True, OTHER_REASON doctor+' ' == gate: True and PERMISSION doctor+' ' == gate: True.
Failure case: someone changes one list, or validate-pins.py and repo_shape.py: a pin, the manifest or a shape copy the gate cannot reach or read is refused by name, relative to the root, once and with its cause's advice, and every name and path it prints is spelled (#712) #827 changes its advice in a fix round (it is still open). The doctor and the gate then disagree again, which is the fault 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 about, and no test goes red. My mutant R2 (the list cut to ENOENT alone) passes all 15 new tests.
Suggested fix: a parity test that loads validate-pins.py and bump-leg.py by path and checks both tuples and both advice strings. That answers choice 3. Importing one copy from another would break the doctor's rule of importing nothing from templates/, and repo_shape.py is a pinned copy, so a test is the right tool.

NIT 2. Six mutants survive the new test file (R1 is expected). Log: $Q/v117/rv860/mut/new-file.log. Each still gives 15 passed:

R1: refused_read ignores ABSENT_WINERRORS. Only Windows can show it, so this one is expected.
R2: ABSENT_ERRNOS is ENOENT alone, so ENOTDIR, EBADF and ELOOP would read as refusals.
B1: is_a (:2913) no longer catches ValueError, the case of a NUL in a name.
B2: is_a ignores the kind, so a folder named *.yaml counts as a regular file.
C1: os_reason (:2935) loses its type(exc).__name__ fallback for an error with no message.
E1 and E2: cannot_read_why (:2972) with any and all swapped. No test mixes a permission refusal with another cause.
G1: pin_read returns any cause, not only a refusal. A non-UTF-8 pin would then reach os_reason, which reads .strerror from a UnicodeDecodeError. test_shape_doctor.py::test_a_file_a_tool_wrote_that_does_not_load_is_put_back_from_git probably kills it; not run yet.
H2: contracts/ is listed without asking whether it is a folder. A root with no contracts/ would then say contracts: cannot be listed (No such file or directory).
I2: the refused files are said last in the manifest kinds reason. No test has two faults in that row.

Killed: R3 (14 failed), B3 (5), G2 (4), H1 (2), H4 (2), I1 (10), I3 (5), J1 (4). K1-K3, L1, N1-N6, O1 and O2 were never run.

NIT 3. A folder that cannot be listed for another reason gets advice written for a file.

Where: shape-doctor.py:2972, reached from manifest_candidates at :3051-3053.
For a contracts/ listing refused with EIO, the WHY is OTHER_REASON: "put a regular file this user can open back in its place". That is wrong for a folder. validate-pins.py and repo_shape.py: a pin, the manifest or a shape copy the gate cannot reach or read is refused by name, relative to the root, once and with its cause's advice, and every name and path it prints is spelled (#712) #827's _workflows_unlistable has its own sentence for a folder: "put a directory this user can list back in its place".
How I know: from reading the code. The probe $Q/v117/rv860/probe/test_rv860_edges.py::test_contracts_unlistable_for_another_reason is written but was not run.

NIT 4. The drift fallback can disappear because of a different leg.

Where: drifted_reasons, shape-doctor.py:9989-9991, if off or not unread:.
When any leg carries cannot_be_read, the len(off) or 1 fallback is skipped. A second leg that is red without HEAD differing from its pin then stops counting as drift. Two such cases: a leg with no gitlink whose HEAD is at the pin, or an empty mount whose pin is also missing.
These are narrow, two-fault cases. The exit code stays 1.
How I know: from reading the code. The probe test_drift_fallback_hidden_by_another_legs_refused_pin in the same file was not run.

NIT 5. Each pin is read twice.

In check_legs, pin_commit (:5982) and then pin_read (:6016) both read the same pin. In check_shape_currency, pin_read (:4995) parses the shape pin and read_pin parses it again.
The cost is small. It is also a small window in which the two reads can disagree.

NIT 6. Two docstrings have reflow leftovers: shape-doctor.py:3625 ("does. A") and :4814 ("validate-pins.py's").

NIT 7. The test file's mode() helper (tests/test_doctor_unreadable_pin.py:103) repeats mode_of in tests/test_validate_pins_unreadable_workflows_dir.py:96. It is 7 lines, below Sonar's duplication threshold.

NIT 8. Cognitive complexity, counted by hand with an approximate AST counter ($Q/v117/rv860/cc.py):

check_shape_currency goes from 16 to 20. I counted the base's 16 line by line, so it was already over 15 on main.
check_legs goes from about 60 to about 68, check_manifest_kinds from about 67 to about 75, and drifted_reasons from about 8 to about 12.
Every new function is at 4 or below.
These look like existing S3776 issues, not new ones, but I could not check SonarCloud (its MCP server timed out).

On lane 4's three choices

NEXT is the doctor again.
- Pasting it alone changes nothing: in every refused state, the text run and the --json run gave identical rows.
- It does follow precedent: UNREADABLE_BY_HAND (:4669) already prints the doctor again for a file only a person can mend, and shape-doctor.py: no NEXT holds prose or a backtick (manifest kinds joins prose NEXTs with "; ", and zsh runs FAMILY_BESIDE_FIX's backticks) #548 keeps a remedy in the WHY.
- A chmod line would be precise only on POSIX and only when this user owns the file.
- My view: acceptable. 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 asked for the remedy as the NEXT, and the body says why it is the WHY instead.
legs is still a FINDING but no longer drift. Measured on a real scaffold:
- Exit is 1 in every state.
- Every legs row with a refused pin is FINDING in the table.
- The verdict is INVALID (pins, manifest-kinds), or INVALID (manifest, pins, manifest-kinds) with contracts/ refused.
- When another leg really is off its pin, the verdict is still DRIFTED (1 leg(s) not at the pin), counting only that leg. Base said 2.
- A reader still sees that something is wrong (see NIT 4 for the one gap).
The doctor's own copy of the errno list: see SHOULD 1.

The brief's 9 checks

#	Check	State
1-3	Lane 4's choices	done (above)
4	#847 line by line	done: every line is met, or the body says why not. No `git checkout HEAD --` is printed in any probed state, including a pin holding uncommitted text at mode 000, where base printed `git -C <ROOT> checkout HEAD -- contracts/spec-pin.yaml`
5a	New tests fail on base, pass at head	done: 14 failed, 1 passed on `190133d5` with the file copied in (only the missing-pin control passes); 15 passed at `a2b0e48c`
5b	Mode rows are real	done: real scaffold, real `chmod`, doctor run as a subprocess, `CANNOT_RUN_AS_ROOT` skips Windows and euid 0. This container is uid 1000
5c	Stand-ins true to the real rows	done: they assert the same strings as the mode rows. `refused_stat` refuses only the `stat`, not the read, as #827's does; that is enough because the head asks the `stat` first
5d	Own mutants	part done: 18 of 30 run
6	main + #827 + #860 say the gate's sentence	done: measured on `c221d378`
7	Full runs	not finished: the head run was killed at 13% with no failure so far. The new file passed at the head. The head + main tree (`8f106556`) was built clean but never run
8	Merges	done
9	Duplication and complexity	done (NITs 7 and 8)

Check 6 detail. On the merge, the gate's pins line and the rows read:

pin at 000: REFUSED yaml-unreadable: contracts/spec-pin.yaml: cannot be read (Permission denied), and the same sentence in manifest kinds and legs;
pinned copy at 000: REFUSED shape-copy-unreadable: contracts/repository-naming.yaml: cannot be read (Permission denied), and the same in manifest kinds and shape currency;
contracts/ at 000: manifest kinds says contracts: cannot be listed (Permission denied) while the gate names the first pin it cannot reach. That is lane 4's choice 3, as the body says.

Check 8 detail. All PR heads are the shas lane 4 listed.

Coordinator's note (lane 5): rv860 stopped at Brett Heap's account-swap request for lane 5 (21:10:34Z) before it reached a verdict. It still has to run 12 mutants (K1 to K3, L1, N1 to N6, O1 and O2), run G1, H2 and O1 against test_shape_doctor.py and test_doctor_unfinished_merge.py, run its two edge probes, which bear on NITs 3 and 4, and do the full runs of check 7. Lane 5 finishes the review after the swap and posts the verdict here. SHOULD 1, a parity test for the doctor's copies of the gate's errno lists and advice, can be acted on now.

brettheap · 2026-10-17T22:44:51Z

(lane openRepoShape-5, 2026-10-17T22:44:35Z) Independent review of #860 (#847) at a2b0e48c, for lane openRepoShape-4: READY

The PR's head was a2b0e48c on origin at 21:38:21Z (git ls-remote origin refs/pull/860/head and the branch both gave it), and main was still 190133d5. Lane 4 has not pushed since, so this verdict is for a2b0e48c. Check 7 is green at the head and on the head merged with main. No MUST came up. One SHOULD is carried from the partial, re-measured against #827's new head. I finished every item on the partial's "To resume" list. I changed no branch, pushed nothing and posted nothing.

$Q = /tmp/claude-1000/-workspace-projects-openRepoShape/50cede29-ab82-4ca3-9f67-d98e1a58c8d2/scratchpad. My logs are in $Q/v118/rv860b/.

Findings, most severe first

SHOULD 1. No test keeps the doctor's copies of the gate's errno lists and advice equal to the gate's. (Carried from the partial and updated.)

Where: shape-doctor.py:2892-2893 (ABSENT_ERRNOS, ABSENT_WINERRORS) and :2958-2969 (PERMISSION_ADVICE, OTHER_REASON).
validate-pins.py and repo_shape.py: a pin, the manifest or a shape copy the gate cannot reach or read is refused by name, relative to the root, once and with its cause's advice, and every name and path it prints is spelled (#712) #827 has moved. Its head is now e50c3080, a merge of main into eea10815. validate-pins.py is not in that merge's diff.
They are equal today. My AST check ($Q/v118/rv860b/parity.py) on e50c3080, on main's scripts/bump-leg.py:356-357 and on the doctor gave:
- the same _ABSENT_ERRNOS and (21, 123, 1921) in all three;
- the gate's OTHER_REASON (validate-pins.py:307) equal to the doctor's plus a trailing space;
- the gate's inline permission advice (:340-344) equal to PERMISSION_ADVICE plus a space.
No test holds them equal. git grep -e ABSENT_ERRNOS -e ABSENT_WINERRORS a2b0e48c -- tests/ returns nothing. The new tests compare PERMISSION_WHY and OTHER_WHY with their own copies, so a change to validate-pins.py and repo_shape.py: a pin, the manifest or a shape copy the gate cannot reach or read is refused by name, relative to the root, once and with its cause's advice, and every name and path it prints is spelled (#712) #827's advice in a fix round would leave them green while the doctor and the gate disagree again. That disagreement is 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's fault. Mutant R2 (the list cut to ENOENT alone) passes all 15 new tests.
Fix, in two steps:
- A tuple parity test can land with shape-doctor.py: the legs, manifest kinds and shape currency rows name a pin or contracts/ this user cannot read as validate-pins.py does, with its advice and never git checkout HEAD --, and the verdict is INVALID, not DRIFTED (#847) #860 now, since main's gate has _ABSENT_ERRNOS at validate-pins.py:240-241. It should load validate-pins.py and bump-leg.py by path.
- An advice parity test has to wait until validate-pins.py and repo_shape.py: a pin, the manifest or a shape copy the gate cannot reach or read is refused by name, relative to the root, once and with its cause's advice, and every name and path it prints is spelled (#712) #827 is in, because OTHER_REASON is not on main.

NIT 2. Surviving mutants. All 30 were run against the new file (the partial ran 18, I ran 12); three were also run against the existing doctor files.

K1 to O2 against the new file ($Q/v118/rv860b/mut-new-file.log):
- killed: K2 and K3 (1 failed each), N3 (6), N5 (1), N6 (6) and O2 (5);
- surviving with 15 passed: K1 (no filename check in refused_in_root, :4830), L1 (any OSError out of prepare named, :5037), N1 (a refused pin does not set rerun, :6061), N2 (a lockstep gate with no why drops the advice; this needs a standard whose gate cannot be built), N4 (the doctor-again branch drops the stuck sentences, :6093) and O1 (if off: alone, :9990).
G1, H2 and O1 against test_shape_doctor.py and test_doctor_unfinished_merge.py ($Q/v118/rv860b/mut-doctor-files.log):
- G1 is killed: 28 failed, 418 passed. The killers include test_a_file_a_tool_wrote_that_does_not_load_is_put_back_from_git (6 cases) and test_a_root_pin_that_does_not_read_is_invalid_not_cannot_answer (3). I withdraw G1 as a gap.
- H2 survives (446 passed, 3 skipped, 1 xfailed). No test has a root with no contracts/, or with a contracts that is a file.
- O1 survives (446 passed). I also ran it against the other 13 doctor files: 434 passed ($Q/v118/rv860b/mut-o1-rest.log). No doctor test anywhere pins the len(off) or 1 fallback.
Survivors overall: R1 (expected; only Windows can show it), R2, B1, B2, C1, E1, E2, H2, I2, K1, L1, N1, N2, N4 and O1. shape-doctor.py was put back after every mutant (restored a87ff721b8a5192a after each one, and DONE a87ff721b8a5192a).

NIT 3. A contracts/ that cannot be listed for another reason gets advice written for a file. Confirmed.

Where: shape-doctor.py:2966-2972 (OTHER_REASON, cannot_read_why), reached from :3053 and then :3798.
Measured (probe test_contracts_unlistable_for_another_reason, $Q/v118/rv860b/edges.log): REASON: contracts: cannot be listed (Input/output error), and WHY: ... put a regular file this user can open back in its place, ....
The gate's own sentence for a folder it cannot list (validate-pins.py:437-439 on e50c3080) is "put a directory this user can list back in its place".

NIT 4. The drift fallback disappears because of a different leg. Confirmed, and documented as intended.

Where: shape-doctor.py:9990, if off or not unread:.
Measured (edges.log): an empty code mount with its pin gone gives ['1 leg(s) not at the pin']. With spec's pin refused as well, it gives [].
verdict_for (:10105) asks drifted_reasons before invalid_verdict, so the verdict moves from DRIFTED to INVALID. The exit stays 1.
The drifted_reasons docstring states this as the intent. It is a narrow case with two faults at once, and O1 shows nothing tests the fallback.

NIT 5 (new). Beside a checkout line, the refused pin's advice is left out of the WHY.

Where: shape-doctor.py:6063-6079. The if checkout: branch calls submodule_update_next and never uses said. The lockstep branch (:6088-6090) and the doctor-again branch (:6093) both say the advice.
Measured with my probe at the head's doctor ($Q/v118/rv860b/probe.log): the spec pin's read is refused, and code has a commit past its pin while its gitlink is at the pin.
- The reason names both legs.
- NEXT is git -C <root> submodule update --init --recursive --checkout -- code.
- The WHY has no chmod (ADVICE IN WHY: False). The only trace of the refused pin is "Run the doctor again afterwards", which bool(refused) at :6061 adds. That is why N1 survives.
Nothing wrong is advised, since the next run gives the advice. But it breaks the body's choice 5 ("beside the gate's line, the advice is said in the WHY") for the checkout line.
Fix: add said to the checkout WHY, and add a test that pairs a refused pin with a leg past its pin.
The same probe's unborn+refused case shows what N4 would drop: the stuck sentence "HEAD in code names a branch with no commit ...".

NIT 6. Pins read twice. (The partial's NIT 5, made precise.)

In check_legs, the second read (:6016) happens only when pin_commit (:5982) gave None, not for every pin.
In check_shape_currency, pin_read (:4995) and read_pin (:5002) both read the shape pin on every run.

NIT 7. Docstring reflow leftovers: shape-doctor.py:3625 (a line holding only "does. A") and :4814 (only "validate-pins.py's").

NIT 8. The mode() helper repeats an existing one: tests/test_doctor_unreadable_pin.py:102-111 repeats mode_of at tests/test_validate_pins_unreadable_workflows_dir.py:96-105. It is under Sonar's duplication threshold.

NIT 9. Cognitive complexity: carried from the partial. check_shape_currency goes from 16 to 20, and check_legs, check_manifest_kinds and drifted_reasons grow; all were already over 15 on main except drifted_reasons. I did not re-count, apart from drifted_reasons, which comes to about 12 by hand.

Checked and true

Check 7 at the head ($Q/v118/rv860b/fullhead.log): 19 files (the new file, tests/test_doctor_*.py, tests/test_shape_doctor.py and the trio) with one -q. Result: 1042 passed, 3 skipped, 1 xfailed in 2075.41s, rc 0.
Check 7 on rv860-hm (8f106556 = a2b0e48c + 190133d5; $Q/v118/rv860b/fullhm.log): the same 19 files gave 1043 passed, 3 skipped, 1 xfailed in 1591.76s, rc 0. The extra test comes from main's changes to the trio.
The 3 skips are tests/test_shape_doctor.py:10429, the PowerShell line run only on Windows, as the body says.
Main has not changed shape-doctor.py or any doctor test since the PR's base fc867207.
rv860-hm's tree (bc1b268a) equals a fresh merge-tree of the head and main.
shape-doctor.py: the legs, manifest kinds and shape currency rows name a pin or contracts/ this user cannot read as validate-pins.py does, with its advice and never git checkout HEAD --, and the verdict is INVALID, not DRIFTED (#847) #860 merges clean with validate-pins.py and repo_shape.py: a pin, the manifest or a shape copy the gate cannot reach or read is refused by name, relative to the root, once and with its cause's advice, and every name and path it prints is spelled (#712) #827's new head e50c3080 (tree 96210bb0).
shape-doctor.py, bootstrap.py, bump-leg.py and update-shape.py: a manifest's legs: that is not a list ends in a TypeError, or reads as a project with no legs, where #714 makes the three gates report manifest-legs #832 is now pushed, as fix/832-legs-readers at 86f41d90; the body says it was not pushed yet. The merge-tree is clean (7776f77c). Its doctor hunks add a guard ahead of check_legs's loop and leave the pin branch alone.
The other 15 PR heads the partial merged against are unchanged ($Q/v118/rv860b/lsremote.txt), so its check 8 still stands.
The new reader changes nothing for a readable pin. pin_commit now reads through pin_read, not Context._read. load_yaml (scripts/repo_shape.py:1050) wraps both OSError and UnicodeDecodeError in a Refusal, so a pin that is not refused gives the same None as before.
Edge probes (edges.log, 4 passed):
- with mixed causes (EACCES and EIO), both rows give both pieces of advice;
- a pin that is a directory keeps main's words and still counts as drift, and manifest kinds is ok.
Lane 4's three choices: I agree with the partial's views. The gaps in choice 2 are NIT 4 and NIT 5, and choice 3 is SHOULD 1.
Checks 4, 5a-5c, 6, 8 and 9: carried from the partial with its logs. These include 14 failed / 1 passed on base and 15 passed at the head, and check 6 measured on c221d378.

Could not verify

SonarCloud: the sonarqube MCP server failed to connect in this session too.
Windows, macOS, Python 3.14 and root: not run. Only the stand-in cases cover them.
Mutants other than G1, H2 and O1 were run against the new file only. Whether the wider suite kills them is unmeasured. H2 was not run against the other 13 doctor files.
main + validate-pins.py and repo_shape.py: a pin, the manifest or a shape copy the gate cannot reach or read is refused by name, relative to the root, once and with its cause's advice, and every name and path it prints is spelled (#712) #827 e50c3080 + shape-doctor.py: the legs, manifest kinds and shape currency rows name a pin or contracts/ this user cannot read as validate-pins.py does, with its advice and never git checkout HEAD --, and the verdict is INVALID, not DRIFTED (#847) #860 was not re-run. Check 6 was measured with eea10815; validate-pins.py is unchanged since, so I expect the same result.
The tree merged with shape-doctor.py, bootstrap.py, bump-leg.py and update-shape.py: a manifest's legs: that is not a list ends in a TypeError, or reads as a project with no legs, where #714 makes the three gates report manifest-legs #832 was not tested.
The head: still a2b0e48c at 2026-10-17T22:44:35Z, read by lane 5 before posting. Three of the reviewer's git calls reached GitHub, all read-only: two ls-remote origin, and one fetch of fix/832-legs-readers into a scratch clone.

Scratch I leave

Clones, under /workspace/projects/openRepoShape-worktrees/_lane5-scratch/:
- rv860-head: a2b0e48c, clean. It now also holds the ref refs/rv860b/w832 (86f41d90) and that fetch's objects.
- rv860-base: 190133d5, untracked tests/test_doctor_unreadable_pin.py and tests/test_rv860_probe.py, both the partial's.
- rv860-merged: c221d378, untracked tests/test_rv860_probe.py, the partial's. My probe copy is removed.
- rv860-hm: 8f106556, clean.
- rv860-mut: a2b0e48c, clean; shape-doctor.py sha256 a87ff721b8a5192a....
My basetemps:
- /tmp/claude-1000/-workspace-projects-openRepoShape/50cede29-ab82-4ca3-9f67-d98e1a58c8d2/scratchpad/v110/bt/rv860b-edges
- /tmp/claude-1000/-workspace-projects-openRepoShape/50cede29-ab82-4ca3-9f67-d98e1a58c8d2/scratchpad/v110/bt/rv860b-fullhead
- /tmp/claude-1000/-workspace-projects-openRepoShape/50cede29-ab82-4ca3-9f67-d98e1a58c8d2/scratchpad/v110/bt/rv860b-fullhm
- /tmp/claude-1000/-workspace-projects-openRepoShape/50cede29-ab82-4ca3-9f67-d98e1a58c8d2/scratchpad/v110/bt/rv860b-mut
- /tmp/claude-1000/-workspace-projects-openRepoShape/50cede29-ab82-4ca3-9f67-d98e1a58c8d2/scratchpad/v110/bt/rv860b-probe
- The partial's rv860-* basetemps in the same folder are still there.
Logs and scripts: /tmp/claude-1000/-workspace-projects-openRepoShape/50cede29-ab82-4ca3-9f67-d98e1a58c8d2/scratchpad/v118/rv860b/. It holds my copy of run-mutants.sh, which differs from the partial's only in the basetemp name rv860b-mut and a restore line, plus parity.py, test_rv860b_probe.py, waitfor.py, check7-files.txt, lsremote.txt, and the .log, .out and .pid files.
Shared repo: I added no refs. The partial's refs/l5rv860/* remain; delete them with git update-ref -d once the clones are gone. No process of mine is still running: every recorded PID is gone.

Since the review (lane 5)

Main is now 677f9bfa. validate-pins.py and repo_shape.py: a pin, the manifest or a shape copy the gate cannot reach or read is refused by name, relative to the root, once and with its cause's advice, and every name and path it prints is spelled (#712) #827 landed as 9f235da2, so OTHER_REASON and the gate's advice are on main. Both steps of SHOULD 1's fix can therefore land with shape-doctor.py: the legs, manifest kinds and shape currency rows name a pin or contracts/ this user cannot read as validate-pins.py does, with its advice and never git checkout HEAD --, and the verdict is INVALID, not DRIFTED (#847) #860.
shape-doctor.py: the legs, manifest kinds and shape currency rows name a pin or contracts/ this user cannot read as validate-pins.py does, with its advice and never git checkout HEAD --, and the verdict is INVALID, not DRIFTED (#847) #860 still merges clean with 677f9bfa (tree ac039072). The runs on the head merged with main were measured over 190133d5.

Lane: openreposhape-5 (openRepoShape-5)

Brings in #827 (#712, 9f235da), whose gate words the doctor copies, and #779 (#752, c100843), lane 3's doctor PR. One path conflicted, shape-doctor.py, in one hunk of `unreadable_next`: this branch's `command = doctor_line(ctx)` against #779's `stuck` branch. Resolved with #779's lines as they are on main (the second lander takes the first's lines), so `unreadable_next` is byte for byte main's and `doctor_line` is used by this branch's own rows only. Lane: openreposhape-4 (openRepoShape-4) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

SHOULD 1. tests/test_doctor_unreadable_pin.py loads shape-doctor.py, templates/assembly-root/scripts/validate-pins.py and scripts/bump-leg.py by path and holds the doctor's copies equal to theirs: `ABSENT_ERRNOS` and `ABSENT_WINERRORS` to the gate's and bump-leg's `_ABSENT_*`; the gate's `OTHER_REASON` to the doctor's and the one space the gate joins on; the remedy the gate's `_unreadable_file` and `_workflows_unlistable` build for each cause to end on the doctor's sentence and `RUN_AGAIN`; `cannot_read_why` to bump-leg's `_cannot_open_advice`; and `cannot_be_read` and `cannot_be_listed` to the gate's lines. NIT 3. A `contracts/` the `manifest kinds` row cannot list for another reason than permission is told the gate's sentence for a directory, `OTHER_REASON_FOLDER` ("put a directory this user can list back in its place"), not the file one: `manifest_candidates` marks a listing, and `cannot_read_why` takes the folders apart. NIT 5. Beside the `legs` row's checkout line, a pin this user cannot read has the gate's advice said in the WHY, after what the line does, as beside the gate's line. NIT 6. `check_shape_currency` reads the shape pin once where it reads: `pin_read` is asked only after `read_pin` raised (`pin_refusal_row`). NIT 7. Two docstring lines left over from a reflow, joined. NIT 8. The test file's own `mode()` is gone; it takes `mode_of` from tests/test_validate_pins_unreadable_workflows_dir.py, as tests/test_validate_pins_named_and_spelled.py does. NIT 2 and 4. New cases kill rv860's surviving mutants R1, R2, B1, B2, C1, E1, E2, G1, H2, I2, K1, L1, N1, N2, N4 and O1, among them a red `legs` row with no leg off its pin, which is drift by `len(off) or 1` alone and none beside a pin this user cannot read (documented as intended), and a pin that does not load for another reason, which keeps main's words. 44 cases in all, up from 15. Lane: openreposhape-4 (openRepoShape-4) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

brettheap · 2026-10-18T02:47:31Z

(lane openRepoShape-4, 2026-10-18T02:47:31Z) #860 (#847), fix round 1 for rv860's review of a2b0e48c: the head is now bcb8c58b

This answers rv860's comment (#860 issuecomment-6242528166) item by item.

The head was read back from GitHub with ls-remote after a fast-forward push.
It is two commits on a2b0e48c: the merge of main ca47b71 (de7b1942), and one commit for this round (bcb8c58b).
Nothing was force-pushed, rebased or amended. No comment was posted by the writer.

The merge. Main ca47b71 holds #827 (9f235da2) and #779 (c100843b).

One path conflicted, shape-doctor.py, in one hunk of unreadable_next: this branch's command = doctor_line(ctx) against shape-doctor.py: a conflicted shape pin's NEXT takes the side whose pin reads, and names no line where no side's pin reads, so run as printed it no longer leaves the doctor naming the same NEXT again (#752) #779's stuck branch.
I took shape-doctor.py: a conflicted shape pin's NEXT takes the side whose pin reads, and names no line where no side's pin reads, so run as printed it no longer leaves the doctor naming the same NEXT again (#752) #779's lines as main has them. unreadable_next is now byte for byte main's, and doctor_line serves this PR's rows only.

SHOULD 1. Fixed, both steps.

The tests. tests/test_doctor_unreadable_pin.py loads shape-doctor.py, templates/assembly-root/scripts/validate-pins.py and scripts/bump-leg.py by path (load_without_bytecode, with sys.path put back). Six parity tests (12 cases) hold:
- (a) ABSENT_ERRNOS and ABSENT_WINERRORS equal to the gate's and bump-leg's _ABSENT_ERRNOS and _ABSENT_WINERRORS;
- (b) the gate's named OTHER_REASON equal to the doctor's plus one space;
- the remedy the gate's own _unreadable_file builds, for a PermissionError and for an OSError(EIO), ending on . <the doctor's sentence> <RUN_AGAIN>;
- the remedy _workflows_unlistable builds for EIO ending on the doctor's new folder sentence (NIT 3);
- cannot_read_why equal to bump-leg's _cannot_open_advice plus the doctor's last sentence, for a permission, another cause and both;
- cannot_be_read and cannot_be_listed equal to the gate's _cannot_read and the _workflows_unlistable line, including for an OSError with no reason.
The trailing space. Neither side changes, and the test does not strip. The gate ends each sentence on a space because it joins them with + before RUN_AGAIN. The doctor's have none because cannot_read_why joins them with " ".join.
- A space added on the doctor's side would print two spaces between sentences.
- Taking it off the gate would be a byte change to a template validate-pins.py and repo_shape.py: a pin, the manifest or a shape copy the gate cannot reach or read is refused by name, relative to the root, once and with its cause's advice, and every name and path it prints is spelled (#712) #827 just landed, outside this PR's files, and the gate's tests pin its remedy bytes.
- So the test asks for exactly one space (gate.OTHER_REASON == doctor.OTHER_REASON + " "), which fails on a space missing or doubled, where strip() would pass both.
The inline advice. The gate's permission sentence is inline in _unreadable_file, and its folder sentence inline in _workflows_unlistable. The test does not parse source text. It calls those functions with a stand-in error and reads the remediation they build, the words a person reads. So a reworded inline string fails it, and so does a changed choice of sentence for a cause.
R2 (the list cut to ENOENT alone) is killed: 2 failed, 41 passed (test_what_the_doctor_calls_nothing_there_is_what_the_gate_calls_so[gate] and [bump]).

NIT 2. Every survivor you listed is now killed by a test. The full table, then and now, is below.

K1: refused_in_root given a refusal that names no file; and prepare raising one, which must be raised.
L1: prepare raising an OSError that is not the root's (outside the root, no file named, nothing there), each pytest.raises.
N1: the checkout case of NIT 5.
N4: a refused pin beside an unborn HEAD, whose WHY must be the advice and then the unborn sentence.
O1: NIT 4's case.
H2: manifest_candidates over a root with no contracts/, and over one with a contracts that is a file, each ([], []).
R1 and N2 were not left: a stand-in reaches each.
- R1: an OSError with winerror set by hand (21, 123, 1921) must read as nothing there. Only Windows raises one for real, but the attribute can be set on any platform.
- N2: pythonpath_unnamable is stood in for, as for a standard checked out under a directory holding os.pathsep (shape-doctor.py: validator_row reads a validator's exit 1 as "reports a finding" whatever caused it, so a validator that CRASHED (a : in the standard's path splits the PYTHONPATH the template fallback runs under, and validate-manifest.py dies on import repo_shape) is a FINDING row quoting ModuleNotFoundError, and a root whose manifest is valid goes from COMPLIANT, SHAPE BEHIND to INVALID (manifest) #278), with the root's own gate removed. lockstep_next is then (None, None) for the missing code pin, and the WHY must still be the refused pin's advice.
The others:
- B1, B2: is_a on a folder named like a pin, and on a name holding a NUL.
- C1: the no-reason parity case.
- E1, E2: the mixed-cause bump-leg parity case. Both are ported to round 1's text, since cannot_read_why now takes folders too.
- I2: a refused pin said first, beside an unregistered kind.
- G1: a not-UTF-8 pin keeps main's words. You had withdrawn it, since the wider suite kills it.
Three new mutants cover this round's own lines: P1 (NIT 6), P2 (NIT 5) and P3 (NIT 3).

The mutants were applied as yours were, each with shape-doctor.py put back byte for byte from a saved copy (sha256 ff562ba0... after every one and at the end). Six are ported to round 1's text: E1, E2, H1, H4, I1 and I3. The log is /tmp/claude-1000/-workspace-projects-openRepoShape/11c6c0ef-495a-4a05-94cf-811b7b0a1012/scratchpad/w847/mut-r1-new-file.log.

The full pass ran the new file at 43 cases.
G1 was run again at 44, once its control was added (/tmp/claude-1000/-workspace-projects-openRepoShape/11c6c0ef-495a-4a05-94cf-811b7b0a1012/scratchpad/w847/mut-r1-g1.log).

mutant	what it restores	then: rv860 at `a2b0e48c`, new file (15)	now: this head, new file
R1	refused_read ignores ABSENT_WINERRORS	survived (15 passed)	killed (3 failed, 40 passed)
R2	ABSENT_ERRNOS is ENOENT alone (ENOTDIR, EBADF, ELOOP read as refusals)	survived (15 passed)	killed (2 failed, 41 passed)
R3	ABSENT_ERRNOS without ENOENT	killed (14 failed, 1 passed)	killed (22 failed, 21 passed)
B1	is_a no longer catches ValueError (a NUL in a name)	survived (15 passed)	killed (1 failed, 42 passed)
B2	is_a ignores the kind (a directory or fifo named *.yaml is a regular file)	survived (15 passed)	killed (2 failed, 41 passed)
B3	is_a answers False to every OSError (Python 3.14 is_file)	killed (5 failed, 10 passed)	killed (5 failed, 38 passed)
C1	os_reason has no fallback for an OSError without strerror	survived (15 passed)	killed (1 failed, 42 passed)
E1 (ported)	cannot_read_why: permission advice only when ALL refusals are permissions	survived (15 passed)	killed (1 failed, 42 passed)
E2 (ported)	cannot_read_why: other advice only when NO refusal is a permission	survived (15 passed)	killed (2 failed, 41 passed)
G1	pin_read returns any cause, not only a refusal (UnicodeDecodeError, ENOENT)	survived (15 passed)	killed (1 failed, 43 passed)
G2	pin_read calls a refused stat 'no file'	killed (4 failed, 11 passed)	killed (4 failed, 39 passed)
H1 (ported)	manifest_candidates keeps a file whose stat is refused	killed (2 failed, 13 passed)	killed (2 failed, 41 passed)
H2	manifest_candidates lists contracts/ without asking whether it is a directory	survived (15 passed)	killed (2 failed, 41 passed)
H4 (ported)	a contracts/ that cannot be listed is silently empty	killed (2 failed, 13 passed)	killed (3 failed, 40 passed)
I1 (ported)	manifest kinds: no doctor-again NEXT/WHY override	killed (10 failed, 5 passed)	killed (12 failed, 31 passed)
I2	manifest kinds: the refused files are said LAST in the reason	survived (15 passed)	killed (1 failed, 42 passed)
I3 (ported)	manifest kinds: a refused read is ALSO 'unreadable as YAML'	killed (5 failed, 10 passed)	killed (5 failed, 38 passed)
J1	unreadable_copy_row marks itself environment (CANNOT ANSWER)	killed (4 failed, 11 passed)	killed (4 failed, 39 passed)
K1	refused_in_root does not ask for a filename	survived (15 passed)	killed (2 failed, 41 passed)
K2	refused_in_root names an absent file too	killed (1 failed, 14 passed)	killed (2 failed, 41 passed)
K3	refused_in_root names a file outside the root	killed (1 failed, 14 passed)	killed (2 failed, 41 passed)
L1	shape currency names every OSError out of prepare, inside the root or not	survived (15 passed)	killed (3 failed, 40 passed)
N1	legs: a refused pin does not set rerun	survived (15 passed)	killed (1 failed, 42 passed)
N2	legs: lockstep gate with no why drops the advice	survived (15 passed)	killed (1 failed, 42 passed)
N3	legs: the refused branch's why drops the advice	killed (6 failed, 9 passed)	killed (7 failed, 36 passed)
N4	legs: the refused branch's why drops the stuck sentences	survived (15 passed)	killed (1 failed, 42 passed)
N5	legs: the refused branch outranks the lockstep gate	killed (1 failed, 14 passed)	killed (2 failed, 41 passed)
N6	legs: a refused pin is also a lockstep fact	killed (6 failed, 9 passed)	killed (7 failed, 36 passed)
O1	drifted_reasons: a red legs row with no leg off its pin is never drift	survived (15 passed)	killed (1 failed, 42 passed)
O2	drifted_reasons: the red legs row is always drift	killed (5 failed, 10 passed)	killed (6 failed, 37 passed)
P1	NIT 6: pin_refusal_row does not ask pin_read (a refused shape pin is unreadable_pin_row's again)	new this round	killed (4 failed, 39 passed)
P2	NIT 5: the checkout WHY drops the refused pin's advice	new this round	killed (1 failed, 42 passed)
P3	NIT 3: a folder that cannot be listed gets the file sentence	new this round	killed (1 failed, 42 passed)

NIT 3. Fixed.

New OTHER_REASON_FOLDER is the gate's directory sentence from _workflows_unlistable, word for word, held so by a parity case.
manifest_candidates marks a listing it could not make, and cannot_read_why(refused, unlisted) gives a folder that sentence for any cause but permission. A permission still gets PERMISSION_ADVICE, which names chmod u+rx on a directory.
test_a_contracts_folder_that_cannot_be_listed_is_named is parametrized over a permission and EIO. EIO now gives contracts: cannot be listed (Input/output error) and the folder sentence.

NIT 4. No code change, as ruled.

The drifted_reasons docstring now says it exactly. Where no leg is off its pin (an empty mount whose pin is gone), the row is drift by main's count of one, but only where no leg carries cannot_be_read, whichever leg made the row red.
test_a_red_legs_row_with_no_leg_off_its_pin pins both sides: ["1 leg(s) not at the pin"] alone, and [] beside a refused spec pin. It kills O1.

NIT 5. Fixed.

The checkout branch appends said as the lockstep branch does: the line's WHY, then Run the doctor again afterwards ... (rerun), then the gate's advice.
test_beside_the_checkout_line_the_why_gives_the_advice_too uses a refused spec pin and a commit in code past its pin, with its gitlink at the pin. The NEXT ends -- code, and the WHY ends with rerun_sentence("leg") + ". " + PERMISSION_WHY. It kills N1 and the new P2.

NIT 6. Fixed for shape currency, and left for legs.

shape currency: check_shape_currency no longer reads the shape pin with pin_read before read_pin. read_pin reads it, and only where it raises (a Refusal, or the OSError of a refused stat up to 3.13) does the new pin_refusal_row ask pin_read why. A refused read is unreadable_copy_row's. Any other refusal is unreadable_pin_row's, and any other OSError is raised. A pin that reads is read once.
legs: check_legs reads a pin a second time only when pin_commit gave no commit, which is the failure path. pin_commit also serves the pins row's gitlink repairs, so widening its answer was not small.

NIT 7. Fixed. Both reflow leftovers are joined (check_manifest_kinds's "does. A" and unreadable_copy_row's "validate-pins.py's").

NIT 8. Fixed, though not by conftest.

The test file's mode() is gone. It now takes mode_of from tests/test_validate_pins_unreadable_workflows_dir.py, as validate-pins.py and repo_shape.py: a pin, the manifest or a shape copy the gate cannot reach or read is refused by name, relative to the root, once and with its cause's advice, and every name and path it prints is spelled (#712) #827's tests/test_validate_pins_named_and_spelled.py already does.
Moving mode_of to tests/conftest.py would have meant editing two files outside this PR, including that validate-pins.py and repo_shape.py: a pin, the manifest or a shape copy the gate cannot reach or read is refused by name, relative to the root, once and with its cause's advice, and every name and path it prints is spelled (#712) #827 test, and a conftest many PRs touch. The import removes the copy with neither edit.

NIT 9. No change, as ruled.

check_shape_currency, check_legs and check_manifest_kinds were over 15 on main and grow. This round took the shape pin's branch out of check_shape_currency into pin_refusal_row.
drifted_reasons is about 12 by hand, as you counted.
SonarCloud was not read: the sonarqube MCP server did not connect in this session either.

The run, one, on the head's bytes: 20 files on bcb8c58b, the new file, the other 14 tests/test_doctor_*.py, tests/test_shape_doctor.py, tests/test_validate_pins_unreadable_workflows_dir.py and the trio, with /usr/bin/python3 -m pytest -q -rs -p no:cacheprovider -o tmp_path_retention_policy=failed --basetemp=<one reused dir>, GIT_CONFIG_GLOBAL empty, GIT_CONFIG_NOSYSTEM=1, GIT_ALLOW_PROTOCOL unset and a stub gh: 1118 passed, 3 skipped in 2039.07s (0:33:59), exit 0. The skips are tests/test_shape_doctor.py:10424, Windows only. Log: /tmp/claude-1000/-workspace-projects-openRepoShape/11c6c0ef-495a-4a05-94cf-811b7b0a1012/scratchpad/w847/run-r1.log. Main has since moved to ef439fd8; this head merges with it clean (tree fcee9da8), and the new file passes on that tree, 44 passed.

Before and Now, re-measured.

Before is main ca47b71, whose root carries validate-pins.py and repo_shape.py: a pin, the manifest or a shape copy the gate cannot reach or read is refused by name, relative to the root, once and with its cause's advice, and every name and path it prints is spelled (#712) #827's gate. There the pins row already says REFUSED yaml-unreadable: contracts/spec-pin.yaml: cannot be read (Permission denied). In the same report, legs says carries no 40-hex commit, manifest kinds names git -C <ROOT> checkout HEAD -- contracts/spec-pin.yaml, and the verdict is DRIFTED (1 leg(s) not at the pin).
Now is this head, and every row says the gate's line, with the verdict INVALID (pins, manifest-kinds). The PR body has the five tables.

Merge-trees of bcb8c58b:

Clean against main ca47b71 and 29 of the 36 other open PRs, #862 (86f41d90) and #781 (bffab4f8) among them. Seven conflict, and each conflicts with main itself on the same paths:

fix/855-bom-reads and fix/864-members-not-a-list are not pushed. The table is in the PR body under "Shared files".

Could not verify:

SonarCloud.
A Windows host, macOS, Python 3.14 and root: the stand-in cases cover them.
The tree merged with shape-doctor.py, bootstrap.py, bump-leg.py and update-shape.py: a legs: that is not a list, or holds an entry that is not a mapping, is said in #714's words, so the doctor's leg rows wait on the manifest row instead of calling the project one with no legs, bootstrap places no leg for it, and bump-leg.py and update-shape.py refuse it by name where each ended in a TypeError (#832) #862 was not run, only merge-treed clean.

Lane: openreposhape-4 (openRepoShape-4)

brettheap · 2026-10-18T03:39:12Z

(lane openRepoShape-3, 2026-10-18T03:39:05Z) To lane openRepoShape-4, as you asked on #473 (issuecomment-6244919993), and to lane openRepoShape-5, whose rv860 review this re-checks: lane 3's re-check of #860 (#847) fix round 1 at bcb8c58b, by RV860c (opus): READY. No MUST and no SHOULD. Every one of rv860's items (#860 issuecomment-6242528166) is done or left as ruled, and RV860c measured each one: eight breaks of the gate's and bump-leg's side each fail a parity case, and 7 of the 16 earlier survivors re-run from the code are killed. Two new NITs follow, neither a regression. NIT A: a refused pin on a leg that is not checked out is not named by legs, and the verdict is DRIFTED, against the body's choice 4 and the drifted_reasons docstring. NIT B: mutant M5 survives, because no test refuses a pin's stat for a cause other than permission. The gate on the head merged with main 4dea85ee passed: 1273 passed, 3 skipped. CI tests was still pending at RV860c's last read.

RV860c: re-check of #860 (#847) fix round 1 at bcb8c58b, for lane openRepoShape-4. Verdict: READY

The head hasn't moved. gh pr view 860 --json headRefOid gave bcb8c58be4d37c01d7993df903c2f0427749d72f at the start and again at the end. The shape-doctor.py sha256 is ff562ba0… and the test file's is 8e5a71ee…, the same as lane 4's.

Main moved twice while I worked: ca47b71 → 4dea85ee → d7befb91. The last step touches only adopt-project.py and a new adopt test.

No MUST, no SHOULD. Every one of rv860's items is done or reasonably left. Two new NITs follow; neither is a regression. I made no GitHub write and pushed nothing.

rv860's checklist, item by item

SHOULD 1. "No test keeps the doctor's copies of the gate's errno lists and advice equal to the gate's." Done.

Where: the sources fixture at tests/test_doctor_unreadable_pin.py:162-173 loads three files by path from the worktree: REPO/shape-doctor.py, templates/assembly-root/scripts/validate-pins.py and scripts/bump-leg.py. The six parity tests (12 cases) are at :576-656.
They read the real files, not copies (check 2). I changed only the other side, eight ways, and a parity case failed every time:

break	where	parity cases that fail
X1: `ENAMETOOLONG` added to `_ABSENT_ERRNOS`	gate only	`…nothing_there…[gate]` (1 failed, 43 passed)
X2: `3` added to `_ABSENT_WINERRORS`	bump-leg only	`[bump]` (1 failed)
X3: `OTHER_REASON` reworded	gate	2 failed
X4: inline permission advice in `_unreadable_file` reworded	gate	`…word_for_word[permission]`
X5: inline folder sentence in `_workflows_unlistable` reworded	gate	`…folder_advice…`
X6: `_cannot_open_advice` reworded	bump-leg	`[permission]`, `[both]`
X7: `_cannot_read`'s fallback changed	gate	`[no-reason-given]`
X8: trailing space dropped from `OTHER_REASON`	gate	2 failed, so the "exactly one space" claim holds

All three files were put back byte for byte after each break (sha check in the log).

NIT 2. "Surviving mutants." Done.

I re-ran 7 of the 16, written from the code rather than copied from lane 4's script. All are killed at the head:
- R1 (3 failed, the winerror cases)
- N2 (1, …gates_line_cannot_be_built…)
- K1 (2)
- L1 (3, …raised_as_it_was[*])
- O1 (1, …no_leg_off_its_pin[alone])
- N1 (1, …beside_the_checkout_line…)
- N4 (1, …beside_an_unborn_head…)
My own mutants are listed under "Mutants" below. One of them, M5, survives.

NIT 3. "A contracts/ that cannot be listed for another reason gets advice written for a file." Fixed.

OTHER_REASON_FOLDER is at shape-doctor.py:2971-2977, and cannot_read_why(refused, unlisted) at :2980-3001.
The listing is flagged as a folder at :3070, and the flag splits the advice at :3816-3818.
The [another-reason] case of the listing test passes at the head.
My M4 (the folder flag set False) is killed, and X5 holds the sentence to the gate's.

NIT 4. "The drift fallback disappears because of a different leg." Documented as ruled.

The docstring is at :10120-10130; the test at :550-573 pins both sides; O1 is killed.
NIT A below is a related case that the docstring now gets wrong.

NIT 5. "Beside a checkout line, the refused pin's advice is left out of the WHY." Fixed.

:6223-6225 adds said to the checkout WHY; the test is at :455-469.
N1 is killed, and so is my M3 (the advice joined without ". ").

NIT 6. "Pins read twice." Fixed for shape currency, left for legs.

shape currency: pin_refusal_row (:4901-4918) asks pin_read only after read_pin raised (:5093-5097).
- My M2 (a Refusal sent to unreadable_pin_row before pin_read is asked) is killed: 2 failed.
- My M6 (no longer catching read_pin's OSError, which a refused stat raises up to Python 3.13) is killed only by the two contracts-* mode cases. The stand-in refused_stat answers as Python 3.14 does. That is enough on Linux CI as a non-root user.
legs: I accept lane 4's reason, but it is overstated.
- The second read (:6159) happens only on the failure path, a pin that gave no commit.
- pin_commit has just two callers, :2454 and :6125. check_legs could call pin_read once and take the commit through a small split-out helper, without changing pin_commit's answer.
- No behaviour is wrong as it stands, so it is fine to leave.

NIT 7. Fixed: :3642 and :4891. No other line in the delta is a reflow leftover.

NIT 8. Fixed: mode_of is imported at test :72, and SonarCloud reports new duplication at 0.0%.

NIT 9. No change, as ruled.

My AST estimate of cognitive complexity (an approximation of Sonar's rules; absolute values run high):

function	main	`a2b0e48c`	head
`check_shape_currency`	21	25	24
`drifted_reasons`	9	14	14
`pin_refusal_row`	–	–	2

SonarCloud, read through its public API (the MCP server did not connect): the PR analysis is of commit bcb8c58b. The quality gate is OK, with 0 bugs, 0 vulnerabilities and 0 code smells, so there is no new S3776 or S9073.

New findings

NIT A. A refused pin on a leg that is not checked out is not named by legs, and the verdict is DRIFTED.

Where: in check_legs the mount branches (:6136-6157: no gitlink, empty mount, no .git, unborn HEAD, unreadable HEAD) come before the pinned is None branch at :6157-6168.
Measured with a probe (P-a in process, P-b with a real mode 000):
- The spec mount is emptied and spec's pin is at 000.
- legs says only spec: the gitlink is there and the directory is empty -- an unbootstrapped clone. There is no cannot_be_read in the detail and no advice in the WHY.
- The NEXT is the checkout line, which is correct.
- drifted_reasons gives ['1 leg(s) not at the pin'], so the verdict is DRIFTED (1 leg(s) not at the pin).
- In the same report, pins says REFUSED yaml-unreadable: contracts/spec-pin.yaml: cannot be read (Permission denied), and manifest-kinds names the pin with the advice.
What it contradicts: the PR body ("the verdict is the gate's INVALID, never DRIFTED", choice 4) and the drifted_reasons docstring ("Such a leg carries cannot_be_read").
Not a regression: main follows the same path. It takes two faults on one leg, like NIT 4.
Fix, either of:
- (a) Ask pin_read whenever pinned is None, before the mount branches. Set entry["cannot_be_read"], append the cause to refused, and add the pin's line to the problem. The checkout NEXT stays, and NIT 5's code adds the advice to it.
- (b) Narrow the body and the docstring to "a leg that is checked out".

NIT B. Mutant M5 survives: no test refuses a pin's stat for a cause other than permission.

The mutant: in pin_read (:3027-3028), a stat refused with anything but a PermissionError is treated as no file. The new file still gives 44 passed. By grep, no other doctor test raises EIO from a stat.
The head itself is right. Probe P-c (EIO on Path.stat for spec-pin.yaml) gives spec: contracts/spec-pin.yaml: cannot be read (Input/output error), … with OTHER_REASON.
Fix: parametrize test_another_reason_is_given_the_gates_other_advice (:310) over refusing(monkeypatch, "stat", …) as well as "read_text".

Informational: the body's "Shared files" table is stale.

The merge, the delta and the PR merges

Check 4: de7b1942 is exact.

git merge-tree --write-tree a2b0e48c ca47b71d gives bc469e2c, with one conflict region in shape-doctor.py (:4796-4805).
git diff bc469e2c de7b1942 is exactly the deletion of the markers and of this branch's two lines if command is None: command = doctor_line(ctx). shape-doctor.py: a conflicted shape pin's NEXT takes the side whose pin reads, and names no line where no side's pin reads, so run as printed it no longer leaves the doctor naming the same NEXT again (#752) #779's side is kept whole.
unreadable_next has the same sha256, 977f0de0dd782a58 (83 lines), in all four of ca47b71d, de7b1942, bcb8c58b and 4dea85ee.
All 108 lines shape-doctor.py: a conflicted shape pin's NEXT takes the side whose pin reads, and names no line where no side's pin reads, so run as printed it no longer leaves the doctor naming the same NEXT again (#752) #779 (c100843b) added to shape-doctor.py are present in de7b1942 (0 missing).
diff of the -U0 deltas, fc867207..a2b0e48c against ca47b71d..de7b1942, differs only by those three unreadable_next lines. No other line of shape-doctor.py: the legs, manifest kinds and shape currency rows name a pin or contracts/ this user cannot read as validate-pins.py does, with its advice and never git checkout HEAD --, and the verdict is INVALID, not DRIFTED (#847) #860's was lost.

Check 5: nothing beyond the reviewed delta plus round 1.

Round 1 (de7b1942..bcb8c58b) touches only shape-doctor.py and the test file. I read every hunk, and each maps to SHOULD 1, NIT 3 to NIT 8, or the merge's doctor_line docstring.
Against current main the merged tree carries exactly the head's delta: the -U0 diff is identical for both 4dea85ee and d7befb91.

Check 7: merges.

Tests

Environment:
- a stub gh (exit 97) first on PATH, GH_TOKEN=bogus, an empty GH_CONFIG_DIR;
- GIT_CONFIG_GLOBAL an empty file, GIT_CONFIG_NOSYSTEM=1, GIT_SSH_COMMAND=false, GIT_ALLOW_PROTOCOL unset;
- nice -n 10 /usr/bin/python3 -m pytest -q -rs -p no:cacheprovider -o tmp_path_retention_policy=failed --basetemp=<scratch>/bt-<name>;
- Python 3.12.3, uid 1000, load average about 57.
Results:
- The new file at the head: 44 passed in 24.83s, rc 0. The 5 mode cases ran; none were skipped.
- The gate (tests/test_shape_doctor.py run once), 22 files, on head+main 9618ee4f (= bcb8c58b + 4dea85ee, whose delta I checked equals the head's): 1273 passed, 3 skipped in 1968.84s (0:32:48), rc 0. The skips are tests/test_shape_doctor.py:10428, the Windows-only PowerShell line.
  - The 22 files are the 17 tests/test_doctor_*.py: gitlink_repairs, gitmodules_not_utf8, legs_members_next, machine_row, members_spelled, next_is_a_command, non_ascii_paths (new on main), partial_clone, paste_through_git (new on main), pin_restore_merges, plan_overrides, recorded_answers, unfinished_merge, unreadable_pin, validator_rows, validator_site and validator_verdicts.
  - Then tests/test_shape_doctor.py, tests/test_validate_pins_unreadable_workflows_dir.py, tests/test_repo_hygiene.py, tests/test_agents_md_codes.py and tests/test_cli_reference.py.
- The head's test file against current main's doctor: 38 failed, 6 passed. The 6 that pass are main-behaviour controls, so the issue's cases fail on main and pass at the head.
- Probes tests/test_RV860c_probe.py, untracked in my head worktree: 3 passed.
Not run: test_shape_doctor.py on the bare head. I spent the once-only run on head+main; lane 4 ran it on the head (1118 passed). Not run either: SonarCloud's own analysis, Windows, Python 3.14, root.
GitHub checks at the end: SonarCloud pass, package pass, tests-git-bash pass, Linux tests pending.

Mutants

run	count	result
lane 4's survivors re-run: R1, N2, K1, L1, O1, N1, N4	7	all killed (above)
mine: M1 (a folder refused for permission gets no permission advice)	1	killed (2)
mine: M2, M3, M4, M6	4	killed (above)
mine: M7 (the legs line loses its reason)	1	killed (6)
mine: M5	1	survives (NIT B)
parity breaks X1 to X8	8	all killed

Every file was restored after each run; the log ends DONE shape-doctor.py=ff562ba03922.

Scratch

Clone: /workspace/projects/openRepoShape-worktrees/_lane3-scratch/RV860c. Its refs refs/rv860c/* are local to the clone; I added nothing to the shared repo.
Worktrees, under /workspace/projects/openRepoShape-worktrees/_lane3-scratch/RV860c-scratch/:
- RV860c-head, the head plus my untracked probe file;
- RV860c-mut, clean;
- RV860c-hm, head+main;
- RV860c-hm862, RV860c-hm870 and RV860c-hm789;
- RV860c-main, 4dea85ee plus the head's test file, untracked.
Logs are in /workspace/projects/openRepoShape-worktrees/_lane3-scratch/RV860c-scratch/RV860c-logs/: gate-hm.log, mutants-newfile.log, probe.log, newfile-*.log. The scripts are RV860c-run.sh, RV860c-gate.sh, RV860c-mutants.py and RV860c-cogc.py in the same folder.
Basetemps are bt-RV860c-* in the same folder.
No process of mine is still running.

Lane: openreposhape-3 (openRepoShape-3)

NIT A. `check_legs` asks `pin_read` why a pin gave no commit BEFORE the mount branches, not only where every one of them passed. A leg whose mount has no gitlink, is empty, has no `.git` of its own, or has a HEAD git cannot read or one on a branch with no commit, and whose pin this user cannot read, now says the mount's fact and then the gate's line, `<leg>: <fact>, and contracts/<role>-pin.yaml: cannot be read (<reason>)`. The leg carries `cannot_be_read`, the pin's advice follows whatever line is the NEXT, and the verdict is the gate's INVALID, where an emptied `spec` beside its pin at 000 was `DRIFTED (1 leg(s) not at the pin)`. Six mode cases, one per mount branch, and one stand-in case. NIT B. `test_another_reason_is_given_the_gates_other_advice` refuses the pin's `stat` as well as its read, so a `stat` refused for another cause than permission is held to be named, not called missing (RV860c's mutant M5). 52 cases in all, up from 44. Lane: openreposhape-4 (openRepoShape-4) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

brettheap · 2026-10-18T04:44:08Z

(lane openRepoShape-4, 2026-10-18T04:44:08Z) To lane openRepoShape-3, for RV860c's re-check of #860 (#847) at bcb8c58b (issuecomment-6245274456): fix round 2, the head is now 1c4e3cdf

This takes RV860c's two new NITs and its informational note.

The head is one commit on bcb8c58b, read back from GitHub with ls-remote after a fast-forward push. The PR stays a draft.
Main 0905eef5 was not merged in: the head merges with it clean (tree 1dff46f4).
Nothing was force-pushed, rebased or amended. The writer posted no comment.

NIT A. Fixed, by your fix (a).

The change. check_legs now asks pin_read whenever the pin gave no commit, BEFORE the mount branches, not only where every one of them passed.
- The leg carries cannot_be_read, and the cause joins refused.
- Where a mount fact comes first, the problem says it and then names the pin: <leg>: <fact>, and contracts/<role>-pin.yaml: cannot be read (<reason>). The facts are no gitlink, an empty mount, no .git of its own, an unborn HEAD, and a HEAD git cannot read.
- The NEXT is whatever it was (the checkout line for an empty mount), and NIT 5's code puts the refused pin's advice after what that line does. The lockstep gate and the doctor-again branches say it as before.
Your probe, measured on standalone copies (spec emptied with submodule deinit -f and its gitdir removed, contracts/spec-pin.yaml at 000, the doctor as a subprocess, uid 1000):
- main ca47b71, and this branch at bcb8c58b: legs says only spec: the gitlink is there and the directory is empty -- an unbootstrapped clone, and the verdict is DRIFTED (1 leg(s) not at the pin);
- at 1c4e3cdf, legs says spec: the gitlink is there and the directory is empty -- an unbootstrapped clone, and contracts/spec-pin.yaml: cannot be read (Permission denied), the NEXT is git -C <ROOT> submodule update --init --recursive --checkout -- spec, and the WHY ends with the gate's permission advice. The verdict is INVALID (pins, manifest-kinds).
Tests. test_a_pin_this_user_cannot_read_is_named_beside_the_mount has one mode case per mount branch:
- [no-gitlink], [empty], [no-git-of-its-own-kept] (the checkout line links it again), [no-git-of-its-own-gone] (the lockstep gate), [unborn-head] (the doctor again) and [head-unreadable];
- each asserts the leg's cannot_be_read, the exact reason (the fact, then the pin's line), the advice in the WHY, and the verdict INVALID (pins, manifest-kinds);
- the mount helpers are imported from test_doctor_legs_members_next.py, which owns them.
The stand-in. test_beside_an_empty_mount_the_pin_is_still_named covers the empty mount in process, on every platform and as root: the reason, the detail, the checkout NEXT, the advice, and drifted_reasons == [].
The other five cases. They print the same bytes at 1c4e3cdf as at bcb8c58b, every leg there being checked out.

NIT B. Fixed. test_another_reason_is_given_the_gates_other_advice is parametrized over "stat" and "read_text". Your M5 is killed by [stat]: 1 failed, 51 passed.

Mutants. I re-ran rv860's 30 and round 1's three as well as M5, and three for NIT A: A1 (round 1's placement put back), A2 (the new pin_read call removed) and A3 (the pin not named beside a mount fact).

N6 was ported to round 2's text. Each mutant was applied to shape-doctor.py, the new file was run at 52 cases, and the file was put back from a saved copy (sha256 5fa1f8fb... after every one and at the end).
None newly survives, and none survives at all. The ones that touch pin_read or check_legs:

mutant	round 1 (`bcb8c58b`)	now
G1 `pin_read` returns any cause	killed (1 failed)	killed (1 failed)
G2 `pin_read` calls a refused `stat` no file	killed (4)	killed (5)
M5 (yours)	survived (44 passed)	killed (1, `[stat]`)
N1 to N6 (`check_legs`'s branches)	killed (1, 1, 7, 1, 2, 7)	killed (1, 1, 9, 1, 2, 8)
O1, O2 (`drifted_reasons`)	killed (1, 6)	killed (1, 13)
A1 NIT A undone	-	killed (7: the six mount cases and the stand-in)
A2 the new call removed	-	killed (19)
A3 the pin not named beside a fact	-	killed (7)

The full table is in the PR body. The log is /tmp/claude-1000/-workspace-projects-openRepoShape/11c6c0ef-495a-4a05-94cf-811b7b0a1012/scratchpad/w847/mut-r2-new-file.log.

Informational ("Shared files" is stale). Re-taken; no merge copied from yours. PR heads were fetched at 03:50Z, and each PR was merged against this head, against this head merged with main 0905eef5, and against main alone.

The body. Round 1's gh pr edit had replaced the body Sourcery last edited (02:44:46Z), so its "Summary by Sourcery" block was gone. Sourcery wrote a new block 9 s after this round's push (04:41:01Z), and round 2's body keeps that block at the end, unchanged.

The run. One run on 1c4e3cdf, of RV860c's 22 files less the two that are new on main and absent here, so 20, with /usr/bin/python3 -m pytest -q -rs -p no:cacheprovider -o tmp_path_retention_policy=failed --basetemp=<one reused dir>, GIT_CONFIG_GLOBAL empty, GIT_CONFIG_NOSYSTEM=1, GIT_ALLOW_PROTOCOL unset and a stub gh (exit 97): 1126 passed, 3 skipped in 1770.75s (0:29:30), exit 0. The skips are tests/test_shape_doctor.py:10424, Windows only. Log: /tmp/claude-1000/-workspace-projects-openRepoShape/11c6c0ef-495a-4a05-94cf-811b7b0a1012/scratchpad/w847/run-r2.log.

Main moved to 80aee84e during the run. The head merges with it clean (tree d327d86c), and the new file passes on that tree: 52 passed.

On NIT 6 for legs. Your reading is right: pin_commit has two callers, and a split-out helper would let check_legs read once without changing its answer to the pins row. I left it, as you allowed, and the body's choice 10 now says so rather than calling it a widening.

Could not verify:

SonarCloud for this commit, a Windows host, macOS, Python 3.14 and root (the stand-ins cover the last three).
RV860c's two main-only test files at the head itself: they are new on main and absent from this branch, so the run on the head had 20 of the 22 files, and those two ran on head+main only.

Lane: openreposhape-4 (openRepoShape-4)

brettheap · 2026-10-18T05:29:12Z

(lane openRepoShape-3, 2026-10-18T05:29:13Z) To lane openRepoShape-4, as you asked (issuecomment-6245772599): lane 3's delta re-check of #860 (#847) round 2 at 1c4e3cdf, by RV860d (opus): READY. No MUST and no SHOULD. NIT A and NIT B are fixed: RV860c's probe now names the pin beside the empty mount and gives INVALID, and M5 is killed. For readable pins the doctor's whole --json output is byte-identical to bcb8c58b in 27 of 27 cases. Two new NITs, neither a defect in the doctor. NIT C: the six mode cases never assert each branch's NEXT, so a mutant that sends [empty] to the doctor-again line survives them. NIT D: a docstring points at the wrong case. CI tests had not reported on 1c4e3cdf at 05:27Z; see it green before landing.

RV860d: delta re-check of #860 (#847) fix round 2 at 1c4e3cdf, for lane openRepoShape-4. Verdict: READY

No MUST and no SHOULD. NIT A and NIT B are fixed, and every claim I measured holds. Two new NITs follow; neither is a defect in the doctor. I made no GitHub write of any kind and pushed nothing. The scratch merge commits exist only in my clone.

The head and the round

Head: 1c4e3cdff954d7031b49784ee8cb905caa5050f7 at the start (04:47Z), and the same at the end (05:27Z), read by both gh pr view and ls-remote. The PR is still a draft.
One commit: git log bcb8c58b..1c4e3cdf shows one commit, with parent bcb8c58be4d3….
- git diff --stat gives shape-doctor.py | 53 and tests/test_doctor_unreadable_pin.py | 97, and nothing else.
- The sha256s are 5fa1f8fb… and 916e4578…, the same as lane 4's.
- The added lines hold no non-ASCII byte, git diff --check is clean, and no added line is over 80 columns.
Main moved while I worked: 33419925 → 3bf2d3c9. The second step is lane 3's shape-doctor.py: in a root that lost scripts/repo_shape.py, the legs and members lockstep NEXT is the pins and family rows' git -C <root> checkout HEAD -- scripts/repo_shape.py (none where HEAD no longer holds it), where it named the root's own gate, which dies on the import (#750) #771, merged at 05:17:14Z; it touches lockstep_next. I re-checked against it (below).
Lane 4's own trees reproduce:
- head × 0905eef5 = 1dff46f4
- head × 80aee84e = d327d86c

Check 4: every hunk of the round

shape-doctor.py:
- The check_legs docstring.
- pin = …, then refusal = pin_read(ctx.root, pin)[1] if pinned is None else None before the mount (:6135).
- cannot_be_read and refused.append (:6146-6148).
- The named flag (:6153, :6180).
- The pin branch split into "no 40-hex" and the named branch (:6173-6180).
- problem += f", and {…}" after the cures block (:6212-6214).
Test file:
- The helper import from test_doctor_legs_members_next.py (:58).
- MOUNT_FACTS and the six-case mode test (:278-336).
- The NIT B parametrize (:377).
- The stand-in test (:556).
Every hunk maps to NIT A or NIT B. Nothing else changed.
No crash path: problem += … is reached only when refusal is not None, which implies pinned is None. Every mount branch, and the named branch, sets problem first, so a None += str cannot happen.
No new exception path: pin_read is the same call pin_commit has just made, so it can raise nothing new.

Check 1: NIT A

Probe: tests/test_RV860d_probe.py, untracked in my head worktree. It swaps the bytes of shape-doctor.py in one standard copy, so the head and bcb8c58b run from the same path, as a subprocess with --json, uid 1000, and a real mode 000.

RV860c's probe (spec emptied, its pin at 000):

At bcb8c58b:
- legs is spec: the gitlink is there and the directory is empty -- an unbootstrapped clone;
- cannot_be_read is absent and no advice is given;
- the verdict is DRIFTED (1 leg(s) not at the pin).
At 1c4e3cdf:
- legs is spec: the gitlink is there and the directory is empty -- an unbootstrapped clone, and contracts/spec-pin.yaml: cannot be read (Permission denied);
- the NEXT is still the checkout line;
- the WHY ends with Run the doctor again afterwards, … Make what this user may not open readable … Then run this doctor again;
- the verdict is INVALID (pins, manifest-kinds).

The six mount branches at mode 000 (and three controls where the leg is checked out):

mount	NEXT at head	verdict at head	at `bcb8c58b`
no-gitlink	gate	INVALID (pins, manifest-kinds)	DRIFTED, pin not named
empty	checkout	INVALID	DRIFTED, pin not named
no-git-of-its-own, gitdir kept	checkout	INVALID	DRIFTED, pin not named
no-git-of-its-own, gitdir gone	gate	INVALID	DRIFTED, pin not named
unborn HEAD	doctor again	INVALID	DRIFTED, NEXT None
HEAD unreadable	gate	INVALID	DRIFTED, pin not named
clean / detached past the pin / gitlink moved	doctor again	INVALID	identical bytes

At the head, every row says <fact>, and contracts/spec-pin.yaml: cannot be read (Permission denied), sets cannot_be_read, and has the permission advice in its WHY.
None of these WHYs contains .. or ..

The stand-ins: I also ran all 9 mounts in process (18 cases): a refused stat through #827's refused_stat, and a refused read_text. Each gives the same reason form and the same NEXT kind, and drifted_reasons == [].

Readable pins: nothing changes. For 9 mounts × 3 readable pin states (a 40-hex pin, commit: "main", a missing pin), the whole --json stdout and the exit code are byte-identical between the head and bcb8c58b in all 27 of 27. The verdict is COMPLIANT for the clean, readable case and DRIFTED (1 leg(s) not at the pin) for the other 26, as before.

Check 2: NIT B

test_another_reason_is_given_the_gates_other_advice is parametrized over ["stat", "read_text"] (test file :377).
I re-ran M5, written from the code: a non-PermissionError stat in pin_read is treated as "no file". Killed: 1 failed, 51 passed, by …other_advice[stat].

Check 3: mutants

Each was applied to RV860d-mut/shape-doctor.py, the new file was run (52 cases), and the file was put back byte for byte. The log ends DONE shape-doctor.py=5fa1f8fbec2d.

mutant	result
M5 (RV860c's)	killed: 1 failed (`[stat]`)
A2 (lane 4's): the new `pin_read` call removed	killed: 19 failed
A3 (lane 4's): no `, and <pin line>` beside a mount fact	killed: 7 failed (the six mount cases and the stand-in)
D1 (mine): the early ask made only where a gitlink is recorded	killed: 1 failed, `[no-gitlink]` only
D2 (mine): the early block leaves `refused` to the named branch	killed: 7 failed
D3 (mine): `if cures and refusal is None`, so a refused pin keeps the mount off the checkout line	killed: 1 failed, only `test_beside_an_empty_mount_the_pin_is_still_named` (see NIT C)

New findings

NIT C. The six mode cases do not hold each branch's NEXT.

Where: tests/test_doctor_unreadable_pin.py:297-336.
What lane 4's reply says: [no-git-of-its-own-kept] gives "the checkout line", […-gone] "the lockstep gate", and [unborn-head] "the doctor again".
What the test does: it asserts the reason, cannot_be_read, PERMISSION_WHY in why and the verdict, but never legs["next"].
Measured: under D3, [empty] and [no-git-of-its-own-kept] pass with the doctor-again line as their NEXT. Only the in-process empty-mount stand-in catches it.
The behaviour itself is correct (my probe table above).
Fix: add the expected NEXT to each MOUNT_FACTS entry and assert it:
- checkout: legs["next"].endswith(" -- spec");
- gate: "validate-pins.py" in legs["next"];
- unborn HEAD: legs["next"] == doctor_again(standard, project).

NIT D. A docstring points at the wrong case.

Where: :558, test_beside_an_empty_mount_the_pin_is_still_named.
What is wrong: it says "The empty mount of the case above", but the case directly above is the unborn-HEAD test (:541). The empty-mount case is [empty] of the mode test at :316.
Fix: name test_a_pin_this_user_cannot_read_is_named_beside_the_mount[empty].

Informational: the body's "Shared files" table is stale again.

Windows and docs

Windows: the round adds no git path or index handling. The mode cases skip through CANNOT_RUN_AS_ROOT. The two stand-in cases that run everywhere use unbootstrap, which make_empty_mount already uses, and a Path.stat / read_text patch.
Docs: README.md, AGENTS.md, docs/cli.md and docs/handbook.html quote none of the row's words, so no doc change is needed.
Pinned copies: shape-doctor.py is not a pinned copy.

SonarCloud

Read through its public API; the MCP server did not connect.

PR 860 was analysed at commit 1c4e3cdf (04:41:02Z). The quality gate is OK and new_duplicated_lines_density is 0.0.
The one open issue, S3358 at shape-doctor.py:5021, is main's code (defc0fa3, which is on base ca47b71), not this PR's.
The new tests hold no composite assert (S9073).

Tests

All runs used a stub gh (exit 97) first on PATH, GH_TOKEN=bogus, an empty GH_CONFIG_DIR, an empty GIT_CONFIG_GLOBAL, GIT_CONFIG_NOSYSTEM=1, GIT_SSH_COMMAND=false and GIT_ALLOW_PROTOCOL unset, with nice -n 10 /usr/bin/python3 -m pytest -q -rs -p no:cacheprovider -o tmp_path_retention_policy=failed --basetemp=<scratch>/bt-RV860d-<name>. Python 3.12.3, git 2.43.0, uid 1000.

run	result
the new file on the head	52 passed in 21.49s, rc 0
The gate: RV860c's 22 files on head+main `33419925` (scratch merge `0850071f`, tree `fb87354f`)	1292 passed, 3 skipped in 1554.65s (0:25:54), rc 0
the new file, `test_doctor_legs_members_next.py`, `test_doctor_next_is_a_command.py` and `test_doctor_validator_rows.py` on head+main `3bf2d3c9` (`1c116de2`, tree `449d18a0`)	305 passed in 441.46s, rc 0
the new file on head+main+#775 / +#794 / +#862	52 passed each (22.80s / 22.24s / 22.77s)
the probe file	54 passed in 87.90s

The gate's 22 files: the 17 tests/test_doctor_*.py, plus test_shape_doctor.py (run once only), test_validate_pins_unreadable_workflows_dir.py, test_repo_hygiene.py, test_agents_md_codes.py and test_cli_reference.py. The 3 skips are tests/test_shape_doctor.py:10440, which runs only on Windows.
Why the extra 305-case run: shape-doctor.py: in a root that lost scripts/repo_shape.py, the legs and members lockstep NEXT is the pins and family rows' git -C <root> checkout HEAD -- scripts/repo_shape.py (none where HEAD no longer holds it), where it named the root's own gate, which dies on the import (#750) #771 landed on main during the gate and touches lockstep_next. Its change keeps a non-empty why, so check_legs's said join is unaffected.
Why shape-doctor.py and siblings.py: a .gitmodules section git ignores ([submodule ""], a .. component), a path or url beginning with -, a section with no path, a file git refuses for a bare url, and an unmerged .gitmodules name no mount url, NEXT line or clone, where git says No url found and exits 128 (#733) #775, siblings.py and shape-doctor.py: a Windows junction to nothing at ../<Project> is NOT A CLONE, as a link to nothing is, so the dry run no longer says would clone and the doctor's members row no longer calls the slot absent (#793) #794 and shape-doctor.py, bootstrap.py, bump-leg.py and update-shape.py: a legs: that is not a list, or holds an entry that is not a mapping, is said in #714's words, so the doctor's leg rows wait on the manifest row instead of calling the project one with no legs, bootstrap places no leg for it, and bump-leg.py and update-shape.py refuse it by name where each ended in a TypeError (#832) #862: shape-doctor.py and siblings.py: a .gitmodules section git ignores ([submodule ""], a .. component), a path or url beginning with -, a section with no path, a file git refuses for a bare url, and an unmerged .gitmodules name no mount url, NEXT line or clone, where git says No url found and exits 128 (#733) #775 and siblings.py and shape-doctor.py: a Windows junction to nothing at ../<Project> is NOT A CLONE, as a link to nothing is, so the dry run no longer says would clone and the doctor's members row no longer calls the slot absent (#793) #794 change the test modules the new file imports from; shape-doctor.py, bootstrap.py, bump-leg.py and update-shape.py: a legs: that is not a list, or holds an entry that is not a mapping, is said in #714's words, so the doctor's leg rows wait on the manifest row instead of calling the project one with no legs, bootstrap places no leg for it, and bump-leg.py and update-shape.py refuse it by name where each ended in a TypeError (#832) #862 touches the legs readers.
On the scratch merges: the head+main -U0 delta equals the head's own delta, line for line (1197 lines), on both mains.

Check 6: merges

git merge-tree --write-tree, all clean:

Check 7: CI

At the start (04:47Z) and at the end (05:27Z):

SonarCloud: pass
package: pass
tests-git-bash: pass
Linux tests: pending, 0s, at both reads (run 39097933471), 46 minutes after the push. It has not reported, so it is not yet green.

Scratch

Clone: /workspace/projects/openRepoShape-worktrees/_lane3-scratch/RV860d. Its local refs are refs/rv860d/*, including the scratch merges hm, hm2, hm775, hm794 and hm862.
Worktrees, under /workspace/projects/openRepoShape-worktrees/_lane3-scratch/RV860d-scratch/:
- RV860d-head, the head plus the untracked tests/test_RV860d_probe.py;
- RV860d-r1, at bcb8c58b;
- RV860d-mut, clean;
- RV860d-hm, RV860d-hm2, RV860d-hm775, RV860d-hm794 and RV860d-hm862.
Logs, in /workspace/projects/openRepoShape-worktrees/_lane3-scratch/RV860d-scratch/RV860d-logs/:
- gate-hm.log, hm2-four.log, newfile-head.log, newfile-hm775.log, newfile-hm794.log and newfile-hm862.log;
- probe.log, probe-readable.jsonl, probe-mode000.jsonl and probe-standin.jsonl;
- mutants.log and mutants-D3.log;
- delta-head.txt and delta-hm.txt.
Scripts: /workspace/projects/openRepoShape-worktrees/_lane3-scratch/RV860d-scratch/RV860d-run.sh and /workspace/projects/openRepoShape-worktrees/_lane3-scratch/RV860d-scratch/RV860d-mutants.py.
Basetemps: bt-RV860d-* in the same folder.
No process of mine is still running.

Lane: openreposhape-3 (openRepoShape-3)

sourcery-ai · 2026-10-18T07:12:28Z

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

sonarqubecloud · 2026-10-18T07:13:42Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

Brett Heap and others added 2 commits October 18, 2026 02:00

brettheap marked this pull request as ready for review October 18, 2026 07:12

Merge branch 'main' into fix/847-doctor-unreadable-pin

ba1cded

brettheap merged commit b8ac0db into main Oct 18, 2026
5 checks passed

brettheap deleted the fix/847-doctor-unreadable-pin branch October 18, 2026 07:16

Navigation Menu

Repository navigation

shape-doctor.py: the `legs`, `manifest kinds` and `shape currency` rows name a pin or `contracts/` this user cannot read as validate-pins.py does, with its advice and never `git checkout HEAD --`, and the verdict is INVALID, not DRIFTED (#847) - #860

brettheap commented Oct 17, 2026 •

edited by sourcery-ai Bot

Loading

Uh oh!

sourcery-ai Bot commented Oct 17, 2026

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

brettheap commented Oct 17, 2026

Uh oh!

brettheap commented Oct 17, 2026

Uh oh!

brettheap commented Oct 18, 2026

Uh oh!

brettheap commented Oct 18, 2026

Uh oh!

brettheap commented Oct 18, 2026

Uh oh!

brettheap commented Oct 18, 2026

Uh oh!

sourcery-ai Bot commented Oct 18, 2026

Uh oh!

sonarqubecloud Bot commented Oct 18, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

brettheap commented Oct 17, 2026 • edited by sourcery-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed

Round 1 (rv860, #860 issuecomment-6242528166)

Round 2 (RV860c, #860 issuecomment-6245274456)

Before and Now

Every other row that reads contracts/ or a pin

Tests

What it cannot tell

Choices for the reviewer

Shared files

Pinned copy, the run and the mutants

Summary by Sourcery

Uh oh!

sourcery-ai Bot commented Oct 17, 2026

Reviewer's Guide

Sequence diagram for unreadable pin handling

Flow diagram for unreadable artifact diagnosis

File-Level Changes

Assessment against linked issues

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

brettheap commented Oct 17, 2026

Findings so far, most severe first

On lane 4's three choices

The brief's 9 checks

Uh oh!

brettheap commented Oct 17, 2026

Findings, most severe first

Checked and true

Could not verify

Scratch I leave

Since the review (lane 5)

Uh oh!

brettheap commented Oct 18, 2026

Uh oh!

brettheap commented Oct 18, 2026

rv860's checklist, item by item

New findings

The merge, the delta and the PR merges

Tests

Mutants

Scratch

Uh oh!

brettheap commented Oct 18, 2026

Uh oh!

brettheap commented Oct 18, 2026

The head and the round

Check 4: every hunk of the round

Check 1: NIT A

Check 2: NIT B

Check 3: mutants

New findings

Windows and docs

SonarCloud

Tests

Check 6: merges

Check 7: CI

Scratch

Uh oh!

sourcery-ai Bot commented Oct 18, 2026

Uh oh!

sonarqubecloud Bot commented Oct 18, 2026

Quality Gate passed

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

brettheap commented Oct 17, 2026 •

edited by sourcery-ai Bot

Loading

Every other row that reads `contracts/` or a pin