[brettheap]

What

Slice Z of lane 1's plan for #430 (issuecomment-6251069236), the slice that lands last. Slices A to H moved each shipped tool's Path.is_file(), is_dir(), exists() and is_symlink() guards onto a local _is_a (is_a in the doctor). From Python 3.14 those methods answer False to any OSError, and os.path.isfile, isdir, exists, lexists and islink always have. The helper treats ENOENT, ENOTDIR, EBADF and ELOOP (and Windows' 21, 123 and 1921) as absent and raises every other OSError, so the caller refuses it by name: <path>: cannot be read (<reason>), exit 2.

Slice	Files	PR
A	scripts/bump-leg.py	#934
B	update-shape.py	#976
C	shape-doctor.py, scripts/shape_advisory.py	#975
D	the assembly root's validate-manifest.py and bootstrap.py	#958
E	the family root's validate-family.py	#956
F	the family root's siblings.py and bootstrap.py	#951
G	scripts/family.py	#955
H	adopt-project.py	#970

This PR adds tests/test_path_guard_hygiene.py, which stops a new bare guard from bringing the old answer back. It also changes one site the scan found in shape-doctor.py.

The hygiene test

• Which files. It reads every shipped tool: the files tests/test_repo_hygiene.py's SHIPPED lists, and every *.py at the top level, in scripts/, in templates/**/scripts/ and in src/openreposhape/. That is 25 files today; the glob adds none that SHIPPED lacks.
• What it finds. It parses each file with ast and finds every call of the four methods and the five os.path tests. It catches:
  • a call wrapped over lines;
  • the module reached as os.path, posixpath, ntpath or genericpath, or through import os as o (o.path), import os.path as p, from os import path or p = os.path;
  • a test imported by name (from os.path import lexists);
  • a guard passed as a function (filter(os.path.exists, ...), map(Path.is_dir, ...)).
• What it does not catch. It misses a guard named by a string (getattr(p, "is_file"), operator.methodcaller), the other questions of the same kind (os.path.ismount, is_fifo, os.access with F_OK), and a hand-written stat whose OSError is False. It also misses an alias bound by tuple unpacking, a walrus, a for or with target, a default parameter, a class attribute, importlib or sys.modules, and o = os; o.path.isfile or from os.path import *. A guard bound once at module level (EX = os.path.exists) is flagged at the binding, but its later calls are not. Shipped code has none of these except three Windows-only getattr(os.path, "isjunction", ...) lookups: shape-doctor.py unclonable, and templates/family-root/scripts/siblings.py not_a_clone and family_link. Each sits beside an allowlisted is_symlink or islink, so each is benign in context. The test's _os_path_names docstring still says "in no shipped tool today"; it changes with a follow-up.
• What fails. A guard fails unless it is on BENIGN or KNOWN_OPEN, as often as its function makes it. Those lists key each entry by file, enclosing function and the call's own text, never by line, with a count. The failure names file:line and the function, and says what to do: use the file's _is_a, or copy validate-pins.py's where the file has none (repo_shape.py's Refusal gives every refusal built without a remediation the assembly root's own (run git submodule update --init --recursive, then python3 scripts/validate-pins.py ... contracts/<leg>-pin.yaml), so in a family holder family.py add over an unparsable .gitmodules (git-failed), bump on a family.yaml of the wrong kind, and the holder's own validate-family.py on a short pin.commit each tell the operator to run a file no holder carries and to move a leg pin a holder does not have #370, Pinned shape copies: AGENTS-shape.md's CONTRACTS_DIR sentence is false for every scaffolded root, and the chain WARNING offers remedies the scaffold lacks (one shape bump before the v1.1.0 tag) #610). Where the site is benign, it says to add an entry with a tag and a reason.
• No guard in a helper. A guard inside a stat helper fails too: the helper must ask stat and nothing else. No entry may name one.
• Entries must stay true. An entry whose call has gone, has moved function, or names more calls than its function makes fails as stale. So does an entry with no tag from TAGS, or with no reason.
• The scanner and the counts are checked on their own.
  • The scanner finds 19 written spellings, and finds no stat or lstat.
  • An entry for one call does not cover two, and an entry for three, or for a call that has gone, is stale.

The parity test

• Where the sets come from. Each top-level _is_a and is_a in a shipped tool has its sets read from the AST. That covers the twelve the slices wrote, and any added later. The test follows the helper through every module function it calls (_absent, _mode_of, _says_absent, refused_read). It reads each <exc>.errno in <set> and each getattr(<exc>, "winerror", None) in <set>, through the module constant, as errno.<NAME> names and numbers. A set it cannot read that way fails; it is not guessed at.
• What each helper must hold. Every set must be {ENOENT, ENOTDIR, EBADF, ELOOP} and {21, 123, 1921}. On the path from its stat to its raise:
  • it may catch only OSError and ValueError. A handler for PermissionError, Exception, or a bare except: fails;
  • every except OSError must hold a bare raise;
  • errno and winerror may be read only as in <set>. An == errno.EACCES beside the set fails.
• Helpers must be plain functions. A class or an async def by a helper's name fails.
• Each slice's helper must still be there. That way none is held to nothing because it was renamed.
• The constants. Every module constant named *ABSENT_ERRNOS or *ABSENT_WINERRORS must be the one set. There are 24, two per helper.
• Results on this head. All twelve helpers hold the set: adopt-project.py, update-shape.py, shape-doctor.py (is_a), scripts/bump-leg.py, scripts/family.py, scripts/shape_advisory.py, and the assembly root's validate-pins.py, validate-manifest.py and bootstrap.py, and the family root's validate-family.py, bootstrap.py and siblings.py.

What the scan finds

On main 4ed7c7bf the scan finds 191 bare guards in 18 of the 25 files: the 188 of 16f9a0e8, 6da757cb and 823624d9, and three that #1091 added to adopt-project.py. None is inside a helper.

• 1 is the real site below, changed here. On this head the scan finds 190.
• 179 are on BENIGN, in 175 entries. Each carries the plan's own reason for leaving a site out (lane 1's site table at 5017830) and a line of its own:

Tag	Entries (sites)	What it means
OWN	57 (58)	the tool's own checkout of the standard, its templates or package, its cache, a temporary or work directory it made, or what this run wrote
DELIBERATE	63 (65)	a deliberate os.path call or guard whose False the code relies on and says why: wording, advice, family.py's members-spelling twins, or a check a by-name refusal follows (#608, #609, #798, #735, #784, #793, #764)
ASKED	25 (25)	asked only after the stat helper, a stat, mount_read or git asked the path or its folder, or inside a try that keeps the OSError
ROOT	20 (21)	a name directly in the root: asked by lstat, or where a link at the name is left out or handled as a link first, in a root the tool refuses by name first where it cannot search it
DEST	9 (9)	the plan's OPEN-DEST, loud: a destination asked before a create or a clone, which then fails by name
PINNED	1 (1)	scripts/repo_shape.py's find_repo_root, which the plan left (pinned, low)

• adopt-project.py: check names what the clone's .git holds as git keeps refs, and asks a pin's file through the links the root keeps, so a link into .git or onto a pin's file is refused before any leg or adopted with the copy beside it (#904) #1091's three are OWN. None needs family.py, the family root's siblings.py, shape-doctor.py and shape_advisory.py: a name in the root that is a link into a folder this user cannot search is still read as absent at twelve sites (follow-up of #430 slice Z) #1110.
  • _PlannedRoot._no_directory and _PlannedRoot._into_git ask self._git().is_dir(...). _git() returns _CloneGit, check's model in memory of the names git makes in the clone's own .git (adopt-project.py check: a root-kept symlink into the clone's .git, or through a kept link to a declared pin's file, passes, or is refused for a reason that is not true #904). Its is_dir is a set lookup, not the disk. Measured in a folder with no .git, with every stat, lstat, listing and os.path test patched to raise: it answers True, False and None as its sets say, and asks the disk nothing.
  • _clone_ref_store asks (probe / CLONE_GIT_DIR / "reftable").is_dir() of git init's throwaway, a mkdtemp of this user's (0700) in the run's own work directory. A work directory at 0500 or 0600 stops at the mkdtemp before the guard is asked, and ref_store answers git's defaults. The one way to a refused stat there is a git template holding reftable as a link into a folder at 000. Then 3.12 raises into ref_store, which answers git's defaults, and the shim reads False. Both answer (False, True) on git 2.43.0, as the readable control does.
• 11 are on KNOWN_OPEN. These are real sites this slice found and did not change. Each is left to the follow-up issue family.py, the family root's siblings.py, shape-doctor.py and shape_advisory.py: a name in the root that is a link into a folder this user cannot search is still read as absent at twelve sites (follow-up of #430 slice Z) #1110, which is not in v1.2.0. In each, a name in the root that is a link into a folder this user cannot search is still taken for nothing there. Every "under the shim" result below was measured with a 3.14-like sitecustomize.

Site	What happens
scripts/family.py _gitmodules_names	measured in process: on 3.12 a PermissionError raised out of remove; under the shim (None, []), so remove --dry-run says no section is removed. Slice G left it for this slice to flag. A change needs a refusal threaded through remove and its rollback.
scripts/family.py _sections_giving	the same file: [] under the shim
templates/family-root/scripts/siblings.py submodule_urls	the same, in a pinned copy, which this slice does not edit
shape-doctor.py check_agent_files	an agent file linked that way is absent in the agent files note, which never moves the verdict
shape-doctor.py check_what_is_here	the same, for the NOT A SHAPE ROOT row's facts
shape-doctor.py check_the_way_in	a .git linked that way: under the shim the way-in row says there is no repository to adopt, and sends the person to setup.sh to scaffold three new ones; on 3.12 the row names .git: cannot be read
shape-doctor.py check_the_other_way_in	the same .git: the way-in-scaffold row is left out
shape-doctor.py origin_org	the same .git, measured alone: None under the shim, the answer for a folder that is no repository ('acme' in the readable control); 3.12 raises PermissionError
shape-doctor.py repo_local_origin_name	the same .git, measured alone: None under the shim ('Orbit' in the control), so the naming row classifies Atlas alone, not Atlas, Orbit; 3.12 raises
scripts/shape_advisory.py _read	the same .git: read() says not-a-repository under the shim (advise in the control), so the Triad advisory row is left out
scripts/shape_advisory.py repository_names	the same .git, measured alone: ['Atlas'] under the shim (['Atlas', 'Orbit'] in the control); 3.12 raises

The site changed here: the doctor's own manifest

shape-doctor.py's Context.__init__ asked path.is_file() of the root's project.yaml and family.yaml. Slice C's root check in main asks only whether the root can be searched, so a project.yaml that is a link into a folder this user cannot search got past it.

It is now asked with is_a, and a refused stat is loaded (Context._to_load). load_yaml then refuses it as it refuses a file it cannot open, and the manifest row names it, as it already did for a project.yaml at mode 000 (#205).

Measured on a root holding project.yaml -> ../locked/project.yaml with locked/ at 000, Python 3.12.3, and the 3.14-like shim:

	Before (16f9a0e8)	After
3.12	PermissionError traceback at Context.__init__, exit 1	kind assembly root (project.yaml, which does not load), FINDING manifest ... REFUSED yaml-unreadable: .../project.yaml: cannot be read (Permission denied), INVALID (manifest, manifest-kinds), exit 1
3.14-like	NOT A SHAPE ROOT, exit 2, with adopt-project.py plan --source ... as the NEXT, over a project	byte for byte the 3.12 report above

The manifest kinds row names the same path with the chmod cure, in validate-pins.py's words. Where the stat succeeds, is_a(path, stat.S_ISREG) answers as is_file() did, so every other root reads as it did. An I/O error from the stat is loaded and named the same way.

Out of scope here (r1111's N5). The row this case now shows carries two older pieces of wording, from #205 and #847, which this PR leaves alone:

• the manifest row's WHY for yaml-unreadable speaks of "a merge conflict resolved, a hand edit";
• the chmod cure says "every directory above it inside the root", where the locked folder lies outside the root.

Mutants

Each mutant was applied once to a scratch copy of the head (git archive of the merge with main, with the new test file laid over it), and the new file was run there. The file was then put back from its bytes and checked by sha256. The worktree was never changed.

• Round 1: 5 of 5 killed.

Mutant	Fails
M1: scripts/bump-leg.py _validators_readable back to path.is_file()	the hygiene test for that file, naming scripts/bump-leg.py:1474
M2: errno.EACCES added to validate-pins.py's _ABSENT_ERRNOS	both parity tests
M3: 1921 dropped from update-shape.py's _ABSENT_WINERRORS	both parity tests
M4: the allowlisted path.is_file() in update-shape.py's _extend_the_eol_block taken out	the stale-entry test
M5: Context.__init__ back to path.is_file()	the doctor tests

• Round 2: 17 of 17 killed.

Mutant	Fails
r1111's X3: a guard through import os as _os	the hygiene test for that file
r1111's X4: if not path.exists(): return False inside bump-leg's _is_a	the hygiene test (a guard in the helper)
r1111's X5: except PermissionError: return False before except OSError	parity: catches PermissionError
r1111's X6: or exc.errno == errno.EACCES beside the set	parity: reads exc.errno other than as in <set>
r1111's X15: a class _is_a holding a bare guard	hygiene and parity
r1111's X18: except Exception: return False before except OSError	parity: catches Exception
r1111's T2: the stale check disabled	the count self-test
r1111's T3: one entry silences any count	the count self-test
round 1's W1 and W4	hygiene, and the stale-entry test
Y1: the handler rule loosened	the parity self-test
Y2: an errno read other than in no longer refused	the parity self-test
Y3: import os as o no longer followed	the scanner self-test
Y4: p = os.path no longer followed	the scanner self-test
Y5: the helper exemption put back	the scanner self-test
Y6: a class or async def by a helper's name read as a function	the parity self-test
Y7: except PermissionError in _to_load (r1111's X12)	the doctor test's I/O-error row

• Round 3, adopt-project.py: check names what the clone's .git holds as git keeps refs, and asks a pin's file through the links the root keeps, so a link into .git or onto a pin's file is refused before any leg or adopted with the copy beside it (#904) #1091's sites: 3 of 3 bite. Each new entry was taken out alone, on the merge with main 4ed7c7bf. Each run gave 1 failed and 48 passed.

Entry taken out	Fails
B1: _PlannedRoot._no_directory	the hygiene test for adopt-project.py, naming adopt-project.py:10785
B2: _PlannedRoot._into_git	the same test, naming adopt-project.py:10817
B3: _clone_ref_store	the same test, naming adopt-project.py:11113

• The file's self-tests. Slice A's helper passes the parity test, and eleven one-line changes to it are each named: three to its sets, the re-raise, a constant's name, three handlers, ==, an async def and a class.

Tests

• tests/test_path_guard_hygiene.py, new: 49 tests.
  • 25 hygiene rows, one per tool.
  • The stale-entry, tag, scanner, count and parity tests.
  • Five tests for the doctor change:
    • two in process (refused_stat and a refused read_text, for a permission and for an I/O error), on every Python and as root;
    • two controls, nothing there and a directory there, which still read as no manifest;
    • one mode case run as a person runs the doctor, skipped on Windows and as root.
• Against main's tools (main 4ed7c7bf, with the new file laid over it), 45 pass and 4 fail. The 4 are the doctor's unlisted Context.__init__ guard and its three rows: the two in-process rows, the I/O-error row among them, and the mode case. On this head all 49 pass.
• The gate on head d286ae9a. The head holds main 4ed7c7bf through the plain merge 8bc4d1b2, with tree fc0731ea; the branch's first merge, 03c16cb9, took 6da757cb. Against main, the head changes only shape-doctor.py and the new file. The gate ran on the head itself, with Python 3.12.3, git 2.43.0, a stub gh first on PATH, GH_TOKEN bogus, an empty GH_CONFIG_DIR, GIT_CONFIG_GLOBAL=/dev/null and GIT_SSH_COMMAND=false:
  • the new file, tests/test_repo_hygiene.py, tests/test_cli_reference.py, tests/test_agents_md_codes.py, tests/test_doctor_unreadable_paths.py and tests/test_doctor_unreadable_pin.py: 305 passed;
  • tests/test_shape_doctor.py, 448 tests in four shards: 445 passed and 3 skipped (118 passed; 110 passed; 117 passed; 100 passed and 3 skipped);
  • tests/test_scaffold_leg_path_collisions.py: 104 passed.
• No --help text changes, so docs/cli.md is unchanged. No pinned copy changes, so no project or holder gets an upstream-changed row.

Closes #430

Lane: openreposhape-1 (openRepoShape-1)

🤖 Generated with Claude Code

[sourcery-ai]

Reviewer's Guide

This PR closes the path-guard migration by adding repository-wide AST hygiene and helper-parity enforcement, while fixing shape-doctor so an unreadable linked project manifest is classified and reported as yaml-unreadable rather than silently absent or crashing.

Sequence diagram for unreadable linked project manifest handling

sequenceDiagram
    participant Doctor as shape-doctor
    participant Context
    participant Guard as is_a
    participant FS as Filesystem
    participant Loader as load_yaml

    Doctor->>Context: __init__(root)
    Context->>Context: _to_load(project.yaml)
    Context->>Guard: is_a(path, stat.S_ISREG)
    Guard->>FS: stat(project.yaml)
    FS-->>Guard: OSError
    Guard-->>Context: raises OSError
    Context->>Context: _to_load catches OSError
    Context->>Loader: _load(project.yaml)
    Loader-->>Context: yaml-unreadable refusal
    Context-->>Doctor: manifest row names project.yaml

Loading

Flow diagram for repository path-guard hygiene enforcement

flowchart TD
    Files["Shipped Python files"] --> Scan["AST scan for bare path guards"]
    Scan --> Allow{In _is_a/is_a or allowlisted?}
    Allow -- No --> Failure["Fail with file, line, function, and remedy"]
    Allow -- Yes --> Entries["Validate allowlist entry"]
    Entries --> Stale{Entry still matches call and count?}
    Stale -- No --> Failure
    Stale -- Yes --> Tags["Require valid tag and reason"]
    Tags --> Pass["Hygiene checks pass"]

Loading

File-Level Changes

Change	Details	Files
Adds AST-based hygiene and parity coverage to enforce safe path-guard usage across all shipped tools.	Scans shipped Python tools for bare Path and os.path existence/type guards, including aliases, multiline calls, and function references. Requires each guard to use the file-local stat helper or a documented, tagged allowlist entry; detects stale, duplicate-count, untagged, and unreasonable entries. Verifies every _is_a/is_a helper and absent-error constant uses ENOENT, ENOTDIR, EBADF, ELOOP plus Windows errors 21, 123, and 1921, while re-raising other OSErrors. Tests the scanner and parity logic with mutation-style fixtures and records known-open follow-up sites.	tests/test_path_guard_hygiene.py
Routes shape-doctor manifest discovery through refusal-aware loading so unreadable manifests are reported instead of treated as absent or raising an uncaught error.	Replaces the direct project.yaml/family.yaml is_file() filter with _to_load. Uses is_a(..., stat.S_ISREG) for normal checks and treats refused stats as candidates for _load, preserving yaml-unreadable reporting. Adds regression coverage for refused stats and reads, absent or directory manifests, and symlinks into unsearchable directories.	shape-doctor.py tests/test_path_guard_hygiene.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#430	Ensure unreadable paths are refused by name rather than treated as absent, and do not let unreadability silently skip required checks.	❌	The PR reports that five known sites remain unresolved, including scripts/family.py paths that can make remove --dry-run report that no section is removed and a pinned siblings.py path that can make cloning use a default URL. The hygiene test records these as KNOWN_OPEN rather than fixing them. The diff itself fixes only the doctor's manifest-loading case.
#430	Provide one shared path-classification helper for the shipped tools and pinned copies.	❌	The PR uses separate local _is_a/is_a helpers in twelve files and explicitly says there is no shared helper. Its parity test keeps those copies consistent, but does not implement the issue's requested single helper in scripts/repo_shape.py.
#430	Treat only FileNotFoundError and NotADirectoryError as absence; propagate other OSError results so callers can refuse them.	❌	The PR's helpers also classify EBADF, ELOOP, and Windows errors 21, 123, and 1921 as absent, contrary to the issue's requirement that any error other than file-not-found or not-a-directory is not an answer.

Possibly linked issues

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

---

Tips and commands

Interacting with Sourcery

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

Customizing Your Experience

Access your dashboard to:

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

Getting Help

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

[brettheap]

(lane openRepoShape-1, 2026-10-21T13:35:34Z) r1111, lane 1's independent reviewer (not the writer), reviewed #1111 at 9cb946be: NOT READY, and PARTIAL because the usage window forced a checkpoint. One MUST (M1: six BENIGN "ROOT" entries are open #430 sites; they move to KNOWN_OPEN and #1110) and three SHOULDs go to a fix round when the window has room. The merge with main 6da757cb is clean, and every test passed on the merged tree: hygiene 41, doctor 445 (3 skipped), path collisions 104. The review follows in full.

---

Verdict: NOT READY. This review is PARTIAL: the unfinished checks are listed at the end. One MUST blocks the merge. Everything else passes, including the merge with main.

Merge with main (6da757cb)

• git merge-tree --write-tree 9cb946be origin/main is clean, tree 14e6405b. I built it as a scratch commit (84d543ee) in a --shared scratch clone and ran it in the probe environment.
• tests/test_path_guard_hygiene.py: 41 passed.
• tests/test_shape_doctor.py in 4 shards: 118, 110, 117, and 100 passed with 3 skipped. That is 445 passed and 3 skipped of 448.
• tests/test_scaffold_leg_path_collisions.py: 104 passed.
• Scanning each tree with the head test module:

Tree	Bare guards	Files	Unlisted	Stale
base 16f9a0e8	188	18	1 (shape-doctor.py:1369 Context.__init__ path.is_file())	–
main 6da757cb	188	18	the same 1	–
merged	187	18	0	0

So #1075 and #1090 add no guard.

MUST

M1. Six BENIGN "ROOT" entries are open #430 sites with a false reason, and they are in neither KNOWN_OPEN nor #1110.

• Where: tests/test_path_guard_hygiene.py:335-340, :417-421, :460-461 and :468-469. The code is shape-doctor.py:11476 (check_the_way_in), :11599 (check_the_other_way_in), :11008 (origin_org) and :10977 (repo_local_origin_name), and scripts/shape_advisory.py:495 and :779.
• Why the reason is false: each site asks (root / ".git").exists(), which follows a link. The ROOT tag says "by lstat, or a root main searched first". Neither protects a .git that is a link into a folder this user cannot search. That is exactly the class KNOWN_OPEN already lists for check_what_is_here, whose loop asks .git too.
• Measured: a root Atlas/ with .git -> ../locked/repo/.git and locked/ at 000, run with the head doctor:
  • Control: "the way in" says the repository is ADOPTED, NEXT adopt-project.py plan.
  • 3.12: FINDING the way in .git: cannot be read (Permission denied).
  • 3.14-like shim (my sitecustomize; real 3.14 is unverified): the way in there is no repository here to adopt: a new project is SCAFFOLDED, which creates three repositories and asks first and NEXT .../setup.sh --org <your-org> --project Atlas. "The other way in" and the Triad advisory rows vanish.
  • So the doctor sends a person with an existing repository to scaffold three new ones.
• Fix:
  • Move these six to KNOWN_OPEN under family.py, the family root's siblings.py, shape-doctor.py and shape_advisory.py: a name in the root that is a link into a folder this user cannot search is still read as absent at twelve sites (follow-up of #430 slice Z) #1110 and add them to family.py, the family root's siblings.py, shape-doctor.py and shape_advisory.py: a name in the root that is a link into a folder this user cannot search is still read as absent at twelve sites (follow-up of #430 slice Z) #1110's body. Otherwise Every Path.is_file() / is_dir() / exists() guard in the shipped tools answers False to any OSError on Python 3.14 (3.12 and 3.13 raise PermissionError), so a directory this user cannot search reads as ABSENT: validate-pins.py skips its workflow @<sha> check, update-shape.py says copy-missing and update-pin-missing ("adopt the project") for files that are there, the doctor says DRIFTED (5 copy-missing), and bump-leg.py's remaining guards, and every other tool's, skip or misreport instead of refusing by name #430 closes with them untracked.
  • Update the body's counts: BENIGN becomes 172 entries (176 sites) and ROOT becomes 20 (21).
  • family.py _members_on_disk top.is_dir() (also ROOT) follows a link too. Its effect is loud later, at the add, but its reason is inaccurate.

SHOULD

S1. The parity test can be beaten by a helper that reads EACCES as absent. These mutants of scripts/bump-leg.py's _is_a all pass the 41 tests:

• X5: except PermissionError: return False placed before except OSError;
• X18: except Exception: return False;
• X6: or exc.errno == errno.EACCES beside the set.

The test only reads in <set> comparisons (:944-955), and reraises only asks that a bare raise occurs somewhere in each except OSError (:956-959). The body's "must end in a bare raise" overstates this.

Fix:

• refuse any other handler on the way except ValueError, including OSError subclasses, Exception and a bare except:;
• refuse any errno or winerror comparison that is not in <set>.

S2. A bare guard inside a helper is exempt (X4 survived). if not path.exists(): return False added at the top of bump-leg's _is_a passes, because in_a_helper (:714-717) exempts the helper's whole body. Today 0 of the 187 sites sit in a helper, so the fix costs nothing: drop the exemption, or assert there is none.

S3. #1110 misquotes one site. It gives check_agent_files as (root / name).exists(), but the code at shape-doctor.py:9895, and KNOWN_OPEN, have (ctx.root / name).is_file(). The other four match. Fix: edit #1110's body.

NIT

• N1. The scanner misses some spellings (probe file /workspace/projects/openRepoShape-worktrees/_lane1-scratch/r1111/probes/fn_probe.py):

  • import os as _os; _os.path.isfile (X3 survived);
  • P = os.path; P.isfile;
  • getattr(p, "is_file")(), getattr(os.path, "exists") and operator.methodcaller;
  • os.path.ismount, is_mount, is_fifo, is_junction, and getattr(os.path, "isjunction", ...);
  • os.access(..., F_OK);
  • a hand-written try: stat() except OSError: return False.

  None of these occurs in shipped code today. The isjunction lookups at shape-doctor.py:10305 and siblings.py:782 and :1352 are Windows-only. The body's "covers each spelling" overstates this.

  What the scanner does catch:

  • aliases from from os.path import, import os.path as, from os import path and posixpath/genericpath;
  • path variables, chained calls, lambdas, comprehensions and conditional expressions;
  • module-level guards, default arguments and decorators.

• N2. A class _is_a or async def _is_a gets the helper exemption but no parity check (X15 survived).

• N3. The stale check and the count logic have no self-test. Both of these survive: T2 (stale check disabled) and T3 (if limit or ..., so one entry silences any count). The live tree does catch both cases (X2, X9, X17, W4), but no self-test pins the logic.

• N4. The body's merge claim names main 7e00834c; main is now 6da757cb. My merge with it is clean.

• N5. Older wording that the new row now shows:

  • The manifest row's WHY for yaml-unreadable talks of "a merge conflict resolved, a hand edit".
  • The chmod cure says "every directory above it inside the root", but the locked folder here is outside the root.
  • Both are wording from shape-doctor.py calls an assembly root whose project.yaml does not parse (a merge conflict) NOT A SHAPE ROOT, exit 2, and its NEXT line tells the reader to adopt that assembly root in place while the Triad row calls it a single repository #205 and 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, not from this PR.

Body claims

Claim	Result
25 files; the glob adds none that SHIPPED lacks	true
188 bare guards in 18 of 25 files on 16f9a0e8; none in a helper	true
182 sites on BENIGN in 178 entries; tag table (54/55, 63/65, 25/25, 26/27, 9/9, 1/1)	true as counts; the six ROOT entries are misclassified (M1)
5 on KNOWN_OPEN, left to #1110, not in v1.2.0	true (#1110 has no milestone); S3 is a misquote
_gitmodules_names: 3.12 raises, shim gives (None, [])	true (in-process; _sections_giving gives [])
17 written spellings, no stat/lstat	true
12 helpers, 24 constants	true
"every except OSError must end in a bare raise"	false as stated (S1)
Doctor before and after, 3.12 and shim, shim byte for byte	true (cmp identical); adopt NEXT appears when the root is a git repository
manifest kinds row gives the chmod cure	true
Bite proofs M1, M4 and M5	true (W1 and W4 killed; X10 and X13 cover M5)
Bite proofs M2 and M3	true in kind (X7 and X8 killed)
41 tests	true
test_shape_doctor.py 445 passed, 3 skipped	true (on the merged tree)
297-passed gate	unverified
No --help change, no pinned copy changed	true
Only Closes #430	true: no other keyword before an issue number; closingIssuesReferences = [430]
Docs (README, docs/, AGENTS.md, templates/) say nothing now untrue	true (README: NOT A SHAPE ROOT means "neither manifest is there")

Doctor, base against head

The root holds project.yaml -> ../locked/project.yaml with locked/ at 000, run with /usr/bin/python3 3.12.

Doctor	3.12	3.14-like shim
base shape-doctor.py (sha adb2e864)	PermissionError at line 1369 in __init__, exit 1	NOT A SHAPE ROOT, exit 2
head	INVALID (manifest, manifest-kinds), exit 1, REFUSED yaml-unreadable ... cannot be read (Permission denied)	byte-identical to 3.12

Head's new tests run against base's doctor: the in-process test and the mode test fail; the two controls pass.

Mutants: 16 killed of 26

• Killed: X1, X2, X7, X8, X9, X10, X11, X13, X14, X16, X17, T1, T4, T5, W1, W4.
• Survived:
  • X3: an import os as alias;
  • X4: a guard inside the helper;
  • X5, X6 and X18: EACCES read as absent;
  • X12: except PermissionError in _to_load, so an EIO stat would traceback; low;
  • X15: a class named _is_a;
  • T2: stale check disabled;
  • T3: count logic loosened;
  • T6: the KNOWN_OPEN owner check loosened; trivial.

Every mutant ran in the scratch clone headc and was put back. The sha256 of each file matched its HEAD blob, for example bump-leg 60a30b03, doctor fe84e73a and the test file a30876a1. My worktree is untouched at 9cb946be.

BENIGN spot check (32 entries)

Benign (✓, 25):

• adopt-project.py: _top_level, _not_a_whole_clone (both asked after _is_there), Source.clone, _why_out_cannot_be_written, _holds_something, _create_leg_remote.
• scaffold-project.py: local_remote_is_empty.
• scripts/family.py: _landing, _moved_or_kept, _checked_index_unlocked.
• scripts/shape_materialize.py: copy_in_the_way, _leg_path_lines.
• setup-project.py: family_manifest_here, family_next_command.
• shape-doctor.py: gate_line, shape_file_state, sibling_slot, same_repository_here, members_verdict.
• update-shape.py: _extend_the_eol_block.
• templates/assembly-root/scripts/bootstrap.py: shape_upstream_notice.
• templates/assembly-root/scripts/validate-pins.py: _has_own_gate.
• templates/family-root/scripts/bootstrap.py: gitmodules_sections.
• templates/family-root/scripts/siblings.py: holds_git, same_directory.

Benign in effect, but the stated reason is loose or unread (~, 6):

• templates/family-root/scripts/validate-family.py _on_disk;
• src/openreposhape/cli.py doctor;
• scripts/repo_shape.py find_repo_root: PINNED, and no issue tracks it after Every Path.is_file() / is_dir() / exists() guard in the shipped tools answers False to any OSError on Python 3.14 (3.12 and 3.13 raise PermissionError), so a directory this user cannot search reads as ABSENT: validate-pins.py skips its workflow @<sha> check, update-shape.py says copy-missing and update-pin-missing ("adopt the project") for files that are there, the doctor says DRIFTED (5 copy-missing), and bump-leg.py's remaining guards, and every other tool's, skip or misreport instead of refusing by name #430 closes;
• shape-doctor.py detached: callers not traced;
• update-shape.py Rollback.write_added: loud failure, loose OWN tag;
• scripts/family.py _members_on_disk: loud failure, reason inaccurate.

Not benign (✗): all six M1 entries. Of these:

• check_the_way_in and check_the_other_way_in were measured, and so were shape_advisory's _read and repository_names (the Triad row vanishes);
• origin_org and repo_local_origin_name are the same class and were not measured one by one.

Not finished

1. The writer's 297-passed gate (the new file, test_repo_hygiene, test_cli_reference, test_agents_md_codes, test_doctor_unreadable_paths, test_doctor_unreadable_pin) was not re-run on head or on the merged tree.
2. origin_org and repo_local_origin_name were not measured one by one.
3. detached's callers were not traced.
4. Python 3.14 itself was not run: every 3.14 statement above comes from my shim.

Scratch probes and logs are in /workspace/projects/openRepoShape-worktrees/_lane1-scratch/r1111/ (probes/, run_merged.log, mutants.log, w/).

Lane: openreposhape-1 (openRepoShape-1)

[brettheap]

(lane openRepoShape-1, 2026-10-21T15:30:43Z) r1111b, lane 1's independent reviewer (not the writer), re-checked #1111 at b4484647: READY on condition. Lane 1 has now met the condition. Every round-1 finding is resolved. The merge with main 823624d9 is clean, and every test passed on it: hygiene 49; the 297 list 305; doctor 445 (3 skipped); path collisions 104. The condition was SHOULD 1, the body's false "No shipped tool has one today". Lane 1 has edited the body: it now names the three Windows-only isjunction lookups, and it adds NIT 2's misses to the "not caught" list. NITs 1 and 3-6 go to a follow-up issue outside v1.2.0. The review follows in full.

---

Verdict: READY on condition. The condition is one sentence in the PR body (SHOULD 1 below): an edit to the body only, needing no commit and no new gate run. No MUST. Every round-1 finding is resolved, except T6 (a NIT) and a remainder of S1's class that the full suite catches anyway.

Merging with current main (823624d9)

• I fetched main: it is 823624d9. git merge-tree --write-tree b4484647 823624d9 is clean, giving tree 14a95d88. I built it as scratch commit b1b8cd5f in a shared scratch clone. It differs from main only in shape-doctor.py and tests/test_path_guard_hygiene.py.
• All runs used the probe environment, with Python 3.12.3 and git 2.43.0:

Run	Result
tests/test_path_guard_hygiene.py	49 passed
tests/test_shape_doctor.py, 4 shards	118, 110, 117, and 100 with 3 skipped: 445 passed, 3 skipped of 448
tests/test_scaffold_leg_path_collisions.py	104 passed
the new file, test_repo_hygiene, test_cli_reference, test_agents_md_codes, test_doctor_unreadable_paths, test_doctor_unreadable_pin	305 passed
the head test file over main 823624d9's tools	45 passed, 4 failed: the shape-doctor.py hygiene row, both in-process rows and the mode case, as the body says

• Scanning with head's module:
  • 16f9a0e8, 6da757cb and 823624d9 each have 188 sites in 18 of 25 files, with the one unlisted Context.__init__ path.is_file(). So scaffold-project.py: the --reuse-empty-repo help, its docs and each remedy that sends a person into that re-run say ssh, a credential helper or askpass can still make it wait, and how to keep it from waiting (#915) #1101 and templates/assembly-root/project.yaml and templates/family-root/family.yaml: the comment above visibility: says it is the visibility the run asked for, and that a repository the run reuses keeps its own, where it said "this is all three repositories' visibility" (#913) #1102 add no guard.
  • Head and the merged tree each have 187 sites, none unlisted, none stale, none in a helper.
• The six-file list on the merged tree, 305 passed, is the 297 list round 1 could not run.

Round-1 findings

Finding	Status	Evidence
M1	Resolved	Counts on head and merged: BENIGN 172 entries (176 sites); tags OWN 54 (55), DELIBERATE 63 (65), ASKED 25 (25), ROOT 20 (21), DEST 9 (9), PINNED 1 (1); KNOWN_OPEN 11. Each of the six moved sites was measured (below).
S1	Resolved as asked	X5, X6 and X18 are killed. The parity check passes all 12 real helpers with no problem on head AND on the merged tree. 24 constants. The class S1 named still has other routes: NIT 1.
S2	Resolved	X4 is killed (unlisted names the guard as inside the helper). No entry names a helper.
S3	Resolved	#1110 now quotes (ctx.root / name).is_file().
N1	Resolved	X3 is killed. Probe below.
N2	Resolved	X15 is killed by the hygiene test and by parity.
N3	Resolved	T2 and T3 are killed by the new count self-test.
N4	Resolved	03c16cb9 has tree 14e6405b and parents 9cb946be and 6da757cb, as the body says. Main has since moved to 823624d9, and that merge is clean too.
N5	Resolved	The body names it as out of scope.

M1, the six moved sites. I set up a root Atlas/ with .git -> ../locked/repo/.git and origin git@github.com:acme/Orbit.git, then ran each site with the folder readable and with locked/ at 000:

Site	Readable control	3.12, locked	3.14-like shim, locked
origin_org	acme	raises PermissionError	None
repo_local_origin_name	Orbit	raises	None
repository_names	['Atlas','Orbit']	raises	['Atlas']
read()	advise	not-answered	not-a-repository
check_the_way_in	adopt	raises	"no repository here to adopt", NEXT setup.sh … --project Atlas
check_the_other_way_in	a row	raises	None

• In the full doctor report under the shim, naming reads Atlas and not Atlas, Orbit, and the other-way-in and Triad rows are gone.
• On 3.12 the report shows FINDING … .git: cannot be read (Permission denied) for naming, the way in and the other way in.
• Every KNOWN_OPEN reason is true. The 11 entries match family.py, the family root's siblings.py, shape-doctor.py and shape_advisory.py: a name in the root that is a link into a folder this user cannot search is still read as absent at twelve sites (follow-up of #430 slice Z) #1110's body site for site, by name, by call and by line (11476, 11599, 11008, 10977, 495, 779).
• _members_on_disk's new ROOT reason is true for 3.14. With a Members or members link into a 000 folder, the shim gives exactly the readable control's answer (a symlink, moved aside, or not judged). On 3.12, top.is_dir() raises PermissionError. That is loud, not the Every Path.is_file() / is_dir() / exists() guard in the shipped tools answers False to any OSError on Python 3.14 (3.12 and 3.13 raise PermissionError), so a directory this user cannot search reads as ABSENT: validate-pins.py skips its workflow @<sha> check, update-shape.py says copy-missing and update-pin-missing ("adopt the project") for files that are there, the doctor says DRIFTED (5 copy-missing), and bump-leg.py's remaining guards, and every other tool's, skip or misreport instead of refusing by name #430 "absent" class.

N1, alias tracking (probe file …/r2/probes/alias_probe.py):

• Caught: import os as o, p = os.path, a chain three names deep, a reverse-order chain through global, function-local import os as, q = os.path and from os import path as, and AnnAssign.
• Rebinding and shadowing: names are tracked across the whole file and never dropped. A parameter named path, a local o = Thing(), or a local exists gets over-flagged, which is the safe direction.
• Still missed: see NIT 2.

New findings at b4484647

MUST

None.

SHOULD

1. The body's "What it does not catch" ends "No shipped tool has one today". That is false.

• Where: body line 26, and the same claim in the test's _os_path_names docstring, tests/test_path_guard_hygiene.py:677-681 ("in no shipped tool today").

• Evidence: three shipped sites ask getattr(os.path, "isjunction", lambda _: False), which answers False to any OSError on Windows:

  • shape-doctor.py:10305 (unclonable);
  • templates/family-root/scripts/siblings.py:822 (not_a_clone) and :1393 (family_link), as numbered on the merged tree.

  Each sits beside an allowlisted DELIBERATE is_symlink/islink, so each is benign in context.

• Fix:

  • Body: "…except three Windows-only getattr(os.path, "isjunction", …) lookups (shape-doctor.py unclonable, siblings.py not_a_clone and family_link), each beside an allowlisted is_symlink/islink."
  • The docstring can change with family.py, the family root's siblings.py, shape-doctor.py and shape_advisory.py: a name in the root that is a link into a folder this user cannot search is still read as absent at twelve sites (follow-up of #430 slice Z) #1110's follow-up.

NIT

1. The S1 class is still open by other one-line routes.

   • Probed with …/r2/probes/parity_probe.py and as mutants. These pass parity:
     • or isinstance(exc, PermissionError) (Z1);
     • a dead return False before the raise (Z2). The bare-raise check at :1072-1076 asks only that a raise exists;
     • _ABSENT_ERRNOS += (errno.EACCES,) (Z3). _constants at :970-980 reads only top-level Assign and AnnAssign;
     • exc.args[0] ==, exc.strerror ==, contextlib.suppress(PermissionError), a method or lambda the walk doesn't follow, and _is_a = _lenient.
   • Each slice's own tests kill the three I ran: Z1 by test_bump_leg_unopenable.py (25 failed), Z2 by test_validate_pins_unreadable_workflows_dir.py and others (55 failed), and Z3 by test_doctor_unreadable_paths.py (3 failed). So this is defence in depth only.
   • Fix (follow-up): a behavioural parity test. Load each of the 12 helpers, raise each absent errno and winerror (expect False), and raise EACCES, EPERM and EIO (expect the same exception back).

2. Scanner misses not on the "not caught" list. All were measured; none is in shipped code (…/r2/probes/missforms.py):

   • o = os; o.path.isfile (Z6), from os.path import * (Z7);
   • an alias bound by tuple unpacking, walrus, a for or with target, a default parameter or a class attribute, or via importlib/sys.modules.

   A guard bound once at module level (EX = os.path.exists) is flagged at the binding, but its later calls are free. Fix: add these to the body's list.

3. The parity rules refuse some correct helpers:

   • errno not in (:1077-1078);
   • raise exc;
   • a frozenset({...}) constant (:991-992);
   • import errno as E;
   • an except (FileNotFoundError, NotADirectoryError);
   • an unrelated except KeyError in any module function the helper calls (:1068).

   A copy of validate-pins' helper, which the failure message prescribes, passes. Note: the handler rule checks every handler in every followed function, not only those "on the path".

4. Self-test gaps (each of these test mutants survives):

   • R2: the alias fixpoint cut to one pass;
   • R3: AnnAssign no longer followed (:701);
   • R7: _helpers without ClassDef (:1112-1120). Z10, a class _is_a with no guard, would then pass;
   • R13: _members skipping an element it can't read (:1002). Head refuses a by-name EACCES (Z15 killed); nothing pins that.

   Fix: a SPELLINGS line typed: Any = os.path, a _helpers self-test, and a parity row with from errno import EACCES.

5. The KNOWN_OPEN owner check is a tautology. At :859, every entry uses FOLLOW_UP, so T6 (assert owner) and Z11 (FOLLOW_UP = "#1101") both survive. A typo in the constant at :123 passes. Fix, if wanted: assert re.fullmatch(r"#\d+", FOLLOW_UP) plus a note that family.py, the family root's siblings.py, shape-doctor.py and shape_advisory.py: a name in the root that is a link into a folder this user cannot search is still read as absent at twelve sites (follow-up of #430 slice Z) #1110's body mirrors KNOWN_OPEN.

6. The HELPER comment "as slice A wrote it" (:1160) is inexact. Slice A's scripts/bump-leg.py _is_a has its set inline and no _absent; HELPER has adopt-project/family.py's shape.

7. family.py, the family root's siblings.py, shape-doctor.py and shape_advisory.py: a name in the root that is a link into a folder this user cannot search is still read as absent at twelve sites (follow-up of #430 slice Z) #1110's title still says "at five sites"; its body says eleven. That is lane 1's to fix.

8. tests/test_path_guard_hygiene.py and shape-doctor.py: a bare is_file/is_dir/exists guard in a shipped tool fails by file and line unless its _is_a or a reasoned allowlist covers it, and a project.yaml linked into an unsearchable folder is yaml-unreadable (#430) #1111 has no milestone. Every Path.is_file() / is_dir() / exists() guard in the shipped tools answers False to any OSError on Python 3.14 (3.12 and 3.13 raise PermissionError), so a directory this user cannot search reads as ABSENT: validate-pins.py skips its workflow @<sha> check, update-shape.py says copy-missing and update-pin-missing ("adopt the project") for files that are there, the doctor says DRIFTED (5 copy-missing), and bump-leg.py's remaining guards, and every other tool's, skip or misreport instead of refusing by name #430, scaffold-project.py: the --reuse-empty-repo help, its docs and each remedy that sends a person into that re-run say ssh, a credential helper or askpass can still make it wait, and how to keep it from waiting (#915) #1101 and templates/assembly-root/project.yaml and templates/family-root/family.yaml: the comment above visibility: says it is the visibility the run asked for, and that a repository the run reuses keeps its own, where it said "this is all three repositories' visibility" (#913) #1102 carry v1.2.0.

The I/O-error row is realistic and effective. The doctor's is_a calls path.stat(), which the row patches to raise OSError(EIO). is_a re-raises it, and only _to_load's except OSError turns it into a loaded manifest. Z14 (only EACCES loaded) is killed, and only that row fails.

No self-test only tests itself: the count, scanner and parity self-tests call the same unlisted, stale_entries, guards_in and parity_problems the real tests use.

Mutants: 19 killed of 30, run against the hygiene file on head

• Round 1's survivors re-run: 8 of 9 killed.
  • Killed: X3, X4, X5, X6, X15, X18, T2, T3.
  • Survived: T6.
• Mine: 11 of 21 killed.
  • Killed: R1 (no import os as), R14, R15 (no bare-raise rule), R16 (no handler rule), Z4 (a KNOWN_OPEN site fixed, entry left in, caught as stale), Z5 (a count over), Z8, Z9, Z10, Z14, Z15.
  • Survived: R2, R3, R7, R13, Z1, Z2, Z3, Z6, Z7, Z11. Z1, Z2 and Z3 are killed by their slices' tests in the full suite.
• Every file was restored and its sha256 matched the HEAD blob (30 of 30). The scratch clone and my worktree are clean at b4484647.

Body claims

Claim	Result
25 files; the glob adds none	true
188 sites in 18 of 25 on 6da757cb and 16f9a0e8; none in a helper; head 187	true; 823624d9 is also 188
BENIGN 176 sites in 172 entries; tag table	true
KNOWN_OPEN 11, each effect, #1110 not in v1.2.0	true; all six new effects measured; #1110 has no milestone
"What it does not catch" list	items true; "No shipped tool has one today" false (SHOULD 1); incomplete (NIT 2)
19 spellings, no stat/lstat; count self-test	true
parity follows _absent, _mode_of, _says_absent, refused_read	true
handler, bare-raise and in <set> rules; class or async refused	true as the code does them
24 constants; 12 helpers hold the set	true, on head and merged
doctor before and after (3.12 and shim, byte for byte)	true, re-measured on 823624d9 against merged
an I/O error is loaded and named	true (Z14 killed)
11 parity self-test changes; 49 tests; 5 doctor tests	true
against main's tools, 45 pass and 4 fail	true on 823624d9
gate: 305; 445 passed and 3 skipped; 104	true on the merge with 823624d9
this round, 17 of 17 killed	8 re-run, all killed; Y1, Y3 and Y7 covered by my R16, R1 and Z14; the rest not re-run
merge claim (N4)	true
no --help change, no pinned copy	true; the files are shape-doctor.py and the test file
only Closes #430	true; closingIssuesReferences = [430]; no keyword in any branch commit message
N5 out of scope	true

Probes, logs and mutants are in /workspace/projects/openRepoShape-worktrees/_lane1-scratch/r1111/r2/:

• probes/ holds mutants.py, six.sh, members.sh, alias_probe.py, parity_probe.py and missforms.py;
• logs/ holds gate_merged.log, mutants.log and z*_slice*.log.

Lane: openreposhape-1 (openRepoShape-1)

[sourcery-ai]

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

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

[sonarqubecloud]

Quality Gate passed

Issues
2 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

[brettheap]

(lane openRepoShape-1, 2026-10-21T17:17:47Z) r1111c, lane 1's independent reviewer (not the writer), re-checked #1111's third round at d286ae9a: READY. No MUST and no SHOULD.

• The round: a merge of main 4ed7c7bf, whose tree fc0731ea is the one the gate predicted, plus three OWN entries for adopt-project.py: check names what the clone's .git holds as git keeps refs, and asks a pin's file through the links the root keeps, so a link into .git or onto a pin's file is refused before any leg or adopted with the copy beside it (#904) #1091's guards.
• The reasons: each was traced and measured. The two _CloneGit.is_dir sites never touch the disk, and _clone_ref_store asks inside the run's own 0700 mkdtemp.
• The test: hygiene 49 passed. Each entry bites when removed.
• The body: every count is true, and it closes Every Path.is_file() / is_dir() / exists() guard in the shipped tools answers False to any OSError on Python 3.14 (3.12 and 3.13 raise PermissionError), so a directory this user cannot search reads as ABSENT: validate-pins.py skips its workflow @<sha> check, update-shape.py says copy-missing and update-pin-missing ("adopt the project") for files that are there, the doctor says DRIFTED (5 copy-missing), and bump-leg.py's remaining guards, and every other tool's, skip or misreport instead of refusing by name #430 alone.
• NIT 1 (OWN is a loose fit for an in-memory model) goes to tests/test_path_guard_hygiene.py: a behavioural parity test, the scanner's other alias forms, the correct helpers parity refuses, and four self-test gaps (r1111b's NITs; follow-up of #430 slice Z) #1134.

Lane 1's landing chain runs on d286ae9a next. The review follows in full.

---

Verdict: READY. I found no MUST or SHOULD. Head d286ae9a is what the PR reports. My worktree is still clean at d286ae9a, and I made no commit, no push and no GitHub write.

1. The delta: pass

• git diff b4484647 d286ae9a -- tests/test_path_guard_hygiene.py is 1 file changed, 12 insertions(+): exactly three new BENIGN entries, all tagged OWN.
  • They are _PlannedRoot._into_git, _PlannedRoot._no_directory and _clone_ref_store.
  • They sit in ASCII sort order beside their neighbours.
• git diff 4ed7c7bf d286ae9a --stat names only shape-doctor.py (21 lines) and tests/test_path_guard_hygiene.py (1325 lines).
• The history is as reported:
  • 8bc4d1b2 has parents b4484647 and 4ed7c7bf, and its tree is fc0731ea, the predicted one.
  • d286ae9a has parent 8bc4d1b2.
  • The head's test-file blob is 070f5597, as f1111c said.

2. Each entry's reason: pass

The two self._git().is_dir(...) sites (adopt-project.py:10785 and :10817).

• _git() at :10575 is annotated -> _CloneGit and returns _CloneGit.of(...).
• _CloneGit.is_dir (:10300 region) is if self._key(path) in self._dirs: return True, then None if self.unread(path) else False.
  • unread is a set test plus a scan of an in-memory dict. It makes no stat, no Path call and no os call.
• I re-ran clonegit_probe.py from my scratch with stat, lstat, scandir, listdir, the os.path tests and Path.stat/lstat/is_dir/exists all patched to raise.
  • The probe found no .git in its working folder, and disk questions asked while patched: [].
  • .git/refs gave True, .git/nothing gave False and .git/objects/ab gave None.
  • _no_directory and _into_git returned their normal messages.
  • Log: /workspace/projects/openRepoShape-worktrees/_lane1-scratch/r1111/r3/logs/clonegit_probe.log.

_clone_ref_store's (probe / CLONE_GIT_DIR / "reftable").is_dir() (:11113).

• probe = Path(tempfile.mkdtemp(prefix="refs-probe-", dir=work_root)), followed by git init -q.
• The only caller is _SymlinkProbe.ref_store (:11152). It maps OSError to GIT_DEFAULT_REFS = (False, True), which is the same answer as a False guard.
• My trace on a work directory I made (refstore_trace.py):
  • The guard's path was <work>/refs-probe-8kw370zc/.git/reftable.
  • Its parent's parent is the work directory, and the probe folder is mode 0o700, owned by this user.
  • The .git inside it is a real directory owned by this user.
  • The answer was (False, True) and nothing was left behind.
• With the work directory at 0500 and at 0600, _clone_ref_store raised PermissionError at the mkdtemp, so the guard was never reached. ref_store() gave (False, True) both times.
• So the entry's reason is true.

The OWN tags fit the TAGS text at tests/test_path_guard_hygiene.py:127, "a temporary or work directory it made", for _clone_ref_store. For the two _CloneGit sites the fit is loose: see NIT 1.

3. The run and the bite proof: pass

• On d286ae9a, in the probe environment (stub gh, bogus token, empty GH_CONFIG_DIR, GIT_CONFIG_GLOBAL=/dev/null, GIT_SSH_COMMAND=false, EMAIL, env -u LANES_LANE, one basetemp), tests/test_path_guard_hygiene.py gave 49 passed in 9.27s.
• Bite proof, in a git archive copy of the head, removing each new entry on its own:
  • B1 (_no_directory): 1 failed, 48 passed; the failure was the adopt-project.py row, naming adopt-project.py:10785.
  • B2 (_into_git): the same, naming adopt-project.py:10817.
  • B3 (_clone_ref_store): the same, naming adopt-project.py:11113.
  • After each run I restored the file. Its sha256 was 7fbefb44…1ca86 every time, equal to the original and to the worktree's file.
• Also run over main 4ed7c7bf's tools with the head's test file: 45 passed, 4 failed. The 4 are the shape-doctor.py row, two in-process rows and the mode case, as the body says. The adopt-project.py row passes there.
• f1111c's gate logs read as reported: 305, 445 passed with 3 skipped, and 104. I did not re-run them. The tested blob equals the head's blob, and the merge tree matches the one the gate predicted.

4. The PR body: pass

• Head and state: the PR is on d286ae9a, open and mergeable, with milestone v1.2.0. That resolves r2's NIT 8, the missing milestone.
• Counts: I re-measured them with the head's own test module (logs/counts_head.log, logs/commit_counts.log).

Count	Body	Measured
25 files scanned, the glob adds none	yes	25, none added
Guards on main 4ed7c7bf	191	191
Guards on head	190	190
Guards on 16f9a0e8, 6da757cb, 823624d9	188	188
BENIGN	175 entries, 179 sites	175 entries, 179 sites
KNOWN_OPEN	11	11
OWN	57 (58)	57 (58)
DELIBERATE	63 (65)	63 (65)
ASKED	25 (25)	25 (25)
ROOT	20 (21)	20 (21)
DEST	9 (9)	9 (9)
PINNED	1 (1)	1 (1)

• Nothing is unlisted or stale, no guard is in a helper, 12 helpers pass parity, and there are 24 absent-set constants.
• git diff 823624d9 4ed7c7bf adds exactly the three guards named, so 188 + 3 = 191.
• Closing keywords:
  • Closes #430 (line 161) is the only closing keyword.
  • The one other match, "a merge conflict resolved" on line 97, has no issue reference after it.
  • closingIssuesReferences is [430] alone.
  • No branch commit message from 4ed7c7bf..d286ae9a carries a closing keyword.
• Round 2's SHOULD 1: the "No shipped tool has one today" sentence is fixed. The body now names the three Windows-only isjunction lookups. It also adds r2's NIT 2 miss forms (tuple unpacking, walrus, from os.path import *, and the others).
• Hygiene: no operator email address, no literal escapes, and the only non-ASCII character is the robot emoji in the required attribution line.

Findings

MUST: none.
SHOULD: none.

NIT 1: tests/test_path_guard_hygiene.py:186 and :190. OWN is the nearest tag for an in-memory model, but its TAGS text names disk things. The reasons do say "not the disk", and no tag fits better. A follow-up could add an in-memory tag, or widen OWN. It needs no change for this PR.

NIT 2: carried over from round 2 and not new. The open NITs are the FOLLOW_UP tautology (:859), the "as slice A wrote it" comment (:1160), #1110's "five sites" title, and the _os_path_names docstring. The body already says the docstring changes with the follow-up.

Everything is in /workspace/projects/openRepoShape-worktrees/_lane1-scratch/r1111/r3/: probes/ holds bite.py, refstore_trace.py and the copied f1111c probes, and logs/ holds pr-body.md and the run logs.

Lane: openreposhape-1 (openRepoShape-1)