[brettheap]

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

Slice H of #430's plan (#430 issuecomment-6251069236; lane 1's slices A, H and Z), a v1.2.0 draft on the v1.1.1 release commit 50178305. It changes:

• adopt-project.py;
• the three --source help paragraphs in docs/cli.md, which is generated from --help (render-cli-reference.py --check passes).

It also adds tests/test_adopt_unsearchable_source.py.

What

• A path this user cannot reach is never read as one that is not there. adopt-project.py had no such helper, so this adds _is_a(path, kind) with _absent, _is_there and _os_reason, which keep bump-leg.py's _ABSENT_ERRNOS meaning exactly.
• --source (_source_spec, _repository_in_url): a refused stat is the new code source-unreadable, exit 2. An org/repo spelling, or the github.com/ one, beside an unreadable ./org is never sent to gh.
• The plan's recorded source (_recorded_source): a path whose stat is refused (one under a directory this user cannot search) is source-unreadable. It is never plan-source-gone, and never cloned again. A source or clone directory that is itself unreadable is not changed here (adopt-project.py: a --source or recorded clone directory this user cannot enter is cloned again or ends in a PermissionError traceback, and a --source too long to name is offered a URL that cannot clone #1003).
• A leg under --local-remote-dir whose stat is refused waits, as a leg already on disk does. The leg question then refuses the folder by name, adopt-folder-cannot-be-made. On 3.12 this was a traceback.
• plan-root-symlink: a place that cannot be read now says "cannot be read (Permission denied), so whether anything is there cannot be told until this user can search every directory above it (chmod u+rx)", not "and nothing is there".
• The remedies:
  • chmod u+rx on the directory and on every directory above it, or fix who owns them.
  • The org/repo spellings add the https://github.com/<org>/<repo> way.
  • The recorded source adds passing --source again, which is held to the plan's commit:.
  • A cause other than permission gets "put right what it names" in place of chmod.

Before and after

Measured on 3.12.3, and with a shim that answers False to any OSError, as 3.14 does:

case	3.12 before	shim before	after, both
plan --source <000 dir>/Thing	traceback, exit 1	source-unresolvable ... neither a path that exists	source-unreadable, exit 2
testorg/Thing beside a 000 ./testorg	traceback	cloning testorg/Thing, gh asked	source-unreadable, gh never asked
check, recorded path under a 000 dir	traceback	plan-source-gone ... names nothing that exists	source-unreadable
the same, recorded as cloned: true	traceback	"no longer exists ... cloned again", gh asked	source-unreadable, nothing cloned
execute --yes --local-remote-dir <000>	traceback	adopt-folder-cannot-be-made	adopt-folder-cannot-be-made
AGENTS.md linked to a file under a 000 dir	"and nothing is there"	the same	"cannot be read (Permission denied) ..."

Tests

All runs used /usr/bin/python3 -m pytest, with a stub gh first on PATH, a bogus GH_TOKEN, an empty GH_CONFIG_DIR, GIT_CONFIG_GLOBAL=/dev/null and GIT_SSH_COMMAND=false.

• The new file: 27 passed (25, and two from the review's fix round at c5c828c6). With 50178305's adopt-project.py put back, all 27 fail.
• Every adopt test, in node-id chunks of 30: 3,020 passed and 3 skipped.
  • Two skips are eol-through-links rows that need a root that keeps a link.
  • One is the MedxEHR clone test, which has no clone here.
• tests/test_shape_doctor.py, in 8 shards: 445 passed. The 3 skips are the PowerShell rows, which run on Windows only.
• The docs and codes files and test_scaffold_leg_path_collisions.py: 193 and 104 passed.

Notes

• Merges: the branch merges cleanly with main 2a78ae1a, which holds adopt-project.py: plan asks the leg-path, pin, date and value refusals of its flags, and an org/repo source's own name and derived id, before the work directory, git's reads of the source and gh repo clone, and says why it cannot clone into a --work-dir nobody can write in (#903) #963, adopt-project.py, shape_materialize.py: five printed sentences say what the run does: a kept root Makefile's block, the spec leg's own path, where execute stops, when a link target names an attribute, and no visibility for a bare repository (#906) #964 and adopt-project.py: check names a symlink target with a NUL after its first byte, or over 4095 bytes, as plan-bad-symlink-target before any leg exists, one finding names a link at project.yaml, and the targets are read in one batch (#908) #965, and with main dd2cf2e8 (tests: check's gh reaches the guard in test_adopt_split_branch.py, "every machine" is said off Windows only, the condition names what ends check first, and the guard's summary names #798's answer (#938) #966): tree 9241a338, where the new file and test_cli_reference.py give 50 passed.
• Squash message: the head is one commit with a "WIP" subject, written at an account swap before these runs finished. The landing squash carries its own message.
• Review: lane 1's independent review follows.

Part of #430

🤖 Generated with Claude Code

Summary by Sourcery

Preserve inaccessible filesystem paths as unreadable throughout adoption planning and execution, with clear diagnostics and no unsafe fallback behavior.

New Features:

• Add explicit source-unreadable handling for inaccessible command-line and recorded source paths, including actionable remediation and safe GitHub URL alternatives.

Bug Fixes:

• Prevent inaccessible paths from being treated as absent, retried as recorded clones, or sent to GitHub for cloning.
• Report inaccessible local remote directories and symlink destinations without Python-version-dependent tracebacks or misleading missing-path messages.

Enhancements:

• Standardize filesystem presence checks so only errors meaning genuine absence are treated as absent.

Documentation:

• Update CLI reference documentation for inaccessible source behavior and clone prevention.

Tests:

• Add comprehensive coverage for inaccessible sources, recorded clones, local remotes, symlinks, operating-system errors, and prevention of GitHub calls.

[sourcery-ai]

Reviewer's Guide

The PR makes adopt-project.py preserve the distinction between absent and unreadable paths across Python versions, reporting named source-unreadable refusals and preventing unsafe GitHub fallback or recloning, while improving local-remote and symlink diagnostics and documenting the behavior.

Sequence diagram for unreadable --source handling

sequenceDiagram
    participant CLI
    participant SourceSpec as _source_spec
    participant SourceThere as _source_there
    participant Filesystem
    participant GH

    CLI->>SourceSpec: resolve --source
    SourceSpec->>SourceThere: check candidate path
    SourceThere->>Filesystem: _is_there
    Filesystem-->>SourceThere: PermissionError
    SourceThere-->>SourceSpec: _source_unreadable
    SourceSpec-->>CLI: source-unreadable, exit 2
    Note over SourceSpec,GH: GitHub fallback is not attempted

Loading

Sequence diagram for unreadable recorded source handling

sequenceDiagram
    participant CheckOrExecute
    participant Plan
    participant RecordedSource as _recorded_source
    participant Filesystem
    participant GH

    CheckOrExecute->>Plan: read recorded source
    Plan->>RecordedSource: resolve source.local_path
    RecordedSource->>Filesystem: _is_there
    Filesystem-->>RecordedSource: PermissionError
    RecordedSource-->>Plan: _source_unreadable
    Plan-->>CheckOrExecute: refuse with named path
    Note over Plan,GH: No plan-source-gone and no reclone

Loading

Flow diagram for absent versus unreadable paths

flowchart TD
    A[Check path with _is_a] --> B{stat result}
    B -->|ENOENT or equivalent| C[Treat as absent]
    B -->|Other OSError| D[source-unreadable]
    B -->|Successful stat| E[Use path kind]
    D --> F[Name path and OS reason]
    D --> G[Do not invoke gh or reclone]
    F --> H[Apply permission or cause-specific remedy]

Loading

File-Level Changes

Change	Details	Files
Introduces consistent filesystem probing that distinguishes missing paths from paths whose metadata cannot be read.	Adds _is_a, _is_there, _absent, and _os_reason around stat with stable absent-errno semantics across Python versions. Adds source-unreadable refusals with OS-specific remediation and explicit path naming. Uses the helper for explicit sources, recorded plan sources, and local remote leg detection.	adopt-project.py
Prevents unreadable paths from triggering incorrect source fallback, cloning, or misleading plan-state errors.	Refuses unreadable explicit paths before interpreting org/repo or GitHub-shaped spellings and avoids invoking gh. Refuses unreadable recorded sources instead of reporting plan-source-gone or recloning cloned sources. Defers unreadable local-remote directories to the existing folder validation so the failing location is named.	adopt-project.py tests/test_adopt_unsearchable_source.py
Improves symlink diagnostics when the destination cannot be inspected.	Distinguishes an unreadable symlink destination from a confirmed missing destination. Includes the destination and permission guidance in plan-root-symlink findings.	adopt-project.py tests/test_adopt_unsearchable_source.py
Updates CLI documentation and adds broad regression coverage for cross-version behavior.	Updates generated help text and CLI reference for source-unreadable behavior. Tests missing-versus-unreadable errno handling, permission-denied paths, GitHub fallback prevention, recorded sources, local remotes, and symlink findings. Covers both real filesystem permissions and simulated Python 3.14-style exists() behavior.	adopt-project.py docs/cli.md tests/test_adopt_unsearchable_source.py

---

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-19T15:51:35Z) Independent review of #970 (#430 slice H) by r970, at 3ec73e21: READY, no MUST. Lane 1 takes SHOULD-2 and NITs 1 to 3 in a test-only fix round, files SHOULD-1 as a follow-up, and fixes the body (SHOULD-1, NIT-5). It lands only on a re-check of the new head.

Verdict: READY at 3ec73e21. I found no MUST. Every slice-H site is handled, every new sentence I measured is true, the 25 new tests fail without the fix, and 3ec73e21 merges cleanly with main 2a78ae1a and passes there. There are two SHOULDs: one is a PR-body wording fix plus a follow-up issue, the other a missing test. Neither needs a new head unless you choose to add the test now, which would need a re-review. The PR is still a draft.

Findings, most severe first

SHOULD-1: a source or clone directory that is itself unreadable is still cloned again, or ends in a traceback, and the PR body over-claims.

• Where: adopt-project.py:2378-2379 (_not_a_whole_clone: except (Refusal, OSError): return "git finds no repository there") and adopt-project.py:2004 (_top_level runs git_out(..., cwd=resolved) with nothing catching the error).
• Scope: this behaves the same on base and head, on 3.12 and under the shim. It is not a 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 stat guard, and s430 lists :2239 as BENIGN. So it does not block, but it is the slice's stated aim ("never cloned again").
• Evidence (probe/probe.py, outputs in probe/head-312.out and probe/base-312.out):
  • C6, check with the recorded clone directory itself at 000 and cloned: true: exit 2, one gh call. Output: NOTE the plan's source.local_path, …/c6-parent/Thing, is a clone plan made that is no longer whole (git finds no repository there), so its source.repository, testorg/Thing, is cloned again from GitHub, then cloning testorg/Thing ….
  • C7 (the same with cloned: false) and H (plan --source <repo dir at 000>): PermissionError: [Errno 13] Permission denied: '…/Thing', a traceback, exit 1.
• Fix now, in the body and the squash message. Replace "an unreadable path is source-unreadable. It is never plan-source-gone, and never cloned again." with: "a path whose stat is refused (one under a directory this user cannot search) is source-unreadable. It is never plan-source-gone, and never cloned again. A source or clone directory that is itself unreadable is not changed here (follow-up)."
• Follow-up issue, suggested title: "adopt-project.py: a source or recorded clone directory this user cannot enter is cloned again as 'no longer whole (git finds no repository there)', or ends plan/check in a PermissionError traceback, on every Python". The fix: a PermissionError from git_out(..., cwd=…) in _top_level and _not_a_whole_clone is raised as _source_unreadable(...).
• The help text and docstrings are already accurate ("one this user cannot reach", "under a directory it may not search").

SHOULD-2: the OTHER_REASON branch is untested.

• Where: adopt-project.py:1832. Mutant M7 (advice = SOURCE_UNREADABLE_PERMISSION for every cause) survives all 25 tests.
• Fix: add this test to tests/test_adopt_unsearchable_source.py. I ran it from scratch: it passes at the head and fails under M7.

def test_a_stat_refused_for_another_reason_is_not_told_to_chmod(
        adopter, monkeypatch, tmp_path):
    """A `stat` refused for another reason than permission (an I/O error)
    is `source-unreadable` too, told to put right what it names: no `chmod`
    puts that right."""
    def refusing(self, *args, **kwargs):
        raise OSError(errno.EIO, os.strerror(errno.EIO), str(self))

    monkeypatch.setattr(Path, "stat", refusing)
    with pytest.raises(adopter.Refusal) as raised:
        adopter._source_spec(str(tmp_path / PROJECT))

    refusal = raised.value
    assert refusal.code == "source-unreadable"
    assert f"cannot be read ({os.strerror(errno.EIO)})" in refusal.detail
    assert ("which no `chmod` puts right: put right what it names"
            in refusal.remediation)
    assert "chmod u+rx" not in refusal.remediation

NIT-1 (mutant M9 survives). The recorded source's second way out is never asserted. Add after tests/test_adopt_unsearchable_source.py:384:

    assert ("or pass the source again with --source, which is held to the "
            "plan's `commit:`.") in proc.stderr

NIT-2 (mutant M8 survives). The symlink finding's (chmod u+rx) clause is never tested against a cause other than permission. Add a variant of :520 that raises OSError(errno.EIO, …) for the target and asserts "… cannot be read (Input/output error), so whether anything is there cannot be told. Send AGENTS.md" in err. The full text is in suggested/test_r970_suggested.py; it passes at the head and fails under M8.

NIT-3. The split-branch control at tests/test_adopt_unsearchable_source.py:460 asserts any Refusal. It does raise adopt-branch-exists and plan-split-branch-taken (I checked with probe/control_codes.py). Parametrize the expected code next to ask and add assert control.value.code == code.

NIT-4 (ENAMETOOLONG on an org/repo spelling). G1 is plan --source <300 a's>/Thing.

• Before: 3.12 gave OSError: [Errno 36] File name too long (a traceback); the shim gave cloning … with gh asked.
• After: source-unreadable, "cannot be read (File name too long)", gh never asked.
• Two words in it are not quite true. It is not unknown whether the path or the GitHub repository is meant: neither can exist. And the offered https://github.com/<300-byte owner>/Thing can never clone, since owners are at most 39 characters (GITHUB_OWNER_MAX).
• Optional fix: in _source_there, offer the URL only when exc.errno != errno.ENAMETOOLONG.

NIT-5 (body housekeeping).

• "merges cleanly with main 01a2b016" is stale. Use: "merges cleanly with main 2a78ae1a, which holds adopt-project.py: plan asks the leg-path, pin, date and value refusals of its flags, and an org/repo source's own name and derived id, before the work directory, git's reads of the source and gh repo clone, and says why it cannot clone into a --work-dir nobody can write in (#903) #963, adopt-project.py, shape_materialize.py: five printed sentences say what the run does: a kept root Makefile's block, the spec leg's own path, where execute stops, when a link target names an attribute, and no visibility for a bare repository (#906) #964 and adopt-project.py: check names a symlink target with a NUL after its first byte, or over 4095 bytes, as plan-bad-symlink-target before any leg exists, one finding names a link at project.yaml, and the targets are read in one batch (#908) #965."
• The head commit's body says "not finished: tests/test_shape_doctor.py and about 2,300 adopt tests not yet run". Keep that out of the squash message.
• The live body also carries a bot-written "Summary by Sourcery" that the author did not write. Its claims are accurate.

Answers to items 1 to 8

1. Sites. All handled:

• :1826/:1765 are now _source_spec (:1960) and _repository_in_url (:1894), both through _source_there (:1844).
• :5735 is _recorded_source (:5878-5888).
• :8538/:11216 are now :8714 and :11415, through _a_leg_may_be_on_disk (:8666).
• :9017 is _outside (:9187). I also proved its second caller, the climb into the work directory (E2b).
• No OPEN-DEST or BENIGN row is misjudged. Every remaining guard is either inside a try, after a successful stat, on the tool's own clone or work directory, or followed by a named refusal. In particular :11572's lexists(bare) says "no leg there" under a 000 directory, but folder_in_the_way names that directory in the same answer.
• s430's "Missed by 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" helpers live only in update-shape.py. adopt-project.py never imports it, and its own root walk asks the disk only in _outside. Slice H's paths do not reach them.

2. Behaviour (head on 3.12 and under the shim give identical output apart from commit hashes; non-root user; no call reached the stub gh unless noted):

• plan --source <000>/Thing (A), and with the parent at 0o600 (A6): REFUSED source-unreadable: --source '…/Thing': cannot be read (Permission denied), so whether a repository is there cannot be told, exit 2, no plan written.
• The org/repo, github.com/…, www.github.com/…, trailing-slash and .git spellings beside an unreadable directory (B to B5): source-unreadable, exit 2, zero gh calls, no source-readonly made.
• The recorded source under a 000 directory, for check and execute, with cloned: false and cloned: true (C1 to C4): source-unreadable, never plan-source-gone, nothing cloned, zero gh calls.
• execute --yes --local-remote-dir <000> (D1): adopt-folder-cannot-be-made with no traceback. The only output before the refusal is "topics skipped for local remotes". The remote directory and the work directory stay empty, and the source's refs are unchanged.
  • Without --yes and with no terminal (D2), adopt-unconfirmed comes first.
  • On a terminal (D3), the user is asked "Type yes to proceed", answers yes, is then refused, and nothing is made.
  • A 0o555 remote directory, on a code path this PR does not touch, is refused at the same point after the prompt, as leg-remote-exists is (adopt-project.py execute: each leg repository is asked about only as it is made, so a code leg whose name is taken leaves the spec leg created, on GitHub as under --local-remote-dir, and a --local-remote-dir that is a file or cannot be written ends in a traceback after check said plan ok #798's design).
  • check (D4) names the directory as a FINDING beforehand.
• Deferring is right. Refusing at the site would only move the refusal earlier. It would also duplicate the leg question's wording, and asking the split-branch question instead would read "cannot tell" as "no leg there", which is exactly what 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 removes.
  • One order changed (D5). With a 000 remote directory and a split branch left behind, the head refuses the folder first and the branch on the next run. Base under the shim refused the branch first, before the prompt.
• plan-root-symlink for a link into a 000 directory (E1): "…, and <place>: cannot be read (Permission denied), so whether anything is there cannot be told until this user can search every directory above it (chmod u+rx). Send AGENTS.md to a leg or drop it…". It is true, though it names the place twice.
• Controls keep their old answers:
  • an absent path: source-unresolvable;
  • a free org/repo: gh asked;
  • a readable ./testorg: source-ambiguous;
  • a recorded source moved away: plan-source-gone, or "cloned again" with gh asked when cloned: true;
  • a link to nothing: "and nothing is there".
• ENAMETOOLONG as a refusal is right. It follows s430's rule and the bump-leg.py/validate-pins.py errno set, and 3.12 raised it too. "Put right what it names" is true (see NIT-4 for the URL).

3. The code source-unreadable. The bare code is new in this PR: git grep -P '(?<![-\w])source-unreadable' 50178305 finds nothing. The hits in the brief are other codes that contain it as a substring:

• pin-source-unreadable
• neutral-pin-source-unreadable
• link-source-unreadable
• adopt's own plan-pin-source-unreadable

So it has one meaning. Its siblings (source-unresolvable, source-ambiguous, source-not-top-level) are listed only in the tool, docs/cli.md, per-release notes and tests, so no list misses it. test_agents_md_codes.py passes (47 tests).

4. Wording. Every sentence is true by probe:

• The URL remedy works: https://github.com/testorg/Thing beside the unreadable directory reaches gh repo clone.
• "held to the plan's commit:" is true: check --source <a clone one commit on> gives FINDING plan-stale, and execute gives REFUSED plan-stale.
• The absent-errno sets are identical to bump-leg.py:409-410.
• _os_reason matches validate-pins.py's _cannot_read.

5. Tests. 25 pass at the head with no skips. All 25 fail with 50178305's file:

• the 9 helper rows on AttributeError … _is_there;
• the 16 behaviour rows on 3.12 tracebacks at the base sites, or "DID NOT RAISE Refusal".

Eight rows need a real mode and skip as root or on Windows. They ran here and run on Linux CI.

7. PR title and body. Every before/after cell matches my own base and shim probe. The counts hold:

• 25 of 25 fail without the fix.
• The writer's 101 chunk files sum to 3,020 passed, 3 skipped, 0 failed.
• test_shape_doctor.py: 445 passed plus 3 PowerShell skips.
• 193 = 45 + 47 + 23 + 78, and 104 for test_scaffold_leg_path_collisions.py.
• render-cli-reference.py --check passes.

The exceptions are SHOULD-1 and NIT-5.

8. Style. git diff --check 50178305 3ec73e21 is clean. No added line is over 79 columns; adopt-project.py's maximum is 84 and unchanged. Every added line is ASCII without tabs, and there is no compound assert.

Merges (item 6)

3ec73e21 merged with	Result
main 2a78ae1a (now)	clean, tree 3b666d1faf44090675a7ac0df986377a6030c518
main c7a3ff16 (holds #964 b0614d51, #963 2771b380, #965 c7a3ff16)	clean, tree 22df8d72e2c0387b95297e2934cbbe344af8ca86
c4dd19dc / a19d69cb	clean (4ecb4b9c / ed63b82b)
#963 9e6ed9bb / #964 369f2781 / #965 e349d83e	clean (78642797 / 27cc6846 / 10a3bc36)
stacked c4dd19d + #963 + #964 + #965	clean (546bf8df); landing order with #966 also clean

• There are no conflicts, so no resolution is needed.
• Both real merges hold adopt-project.py, docs/cli.md and the new test file byte for byte as predicted (5f49c67b, 5fbb50b1, 43328cf2).
• The only callers of _outside use its new signature, and none of the landed PRs adds an existence guard.
• 2a78ae1a adds only bootstrap.py and its two test files beyond c7a3ff16.

Mutants (each applied by exact substitution, run against the new file, restored with git checkout -- adopt-project.py)

Mutant	Result
M1 EACCES added to the absent errnos	killed (16)
M2 _source_spec guard back to exists()	killed (5)
M3 _repository_in_url guard back to exists() / M3b guard dropped	killed (2) / killed (2)
M4 recorded source read as gone, so cloned again	killed (4)
M5 --local-remote-dir wait reverted	killed (2)
M6 plan-root-symlink wording reverted	killed (2)
M7 OTHER_REASON branch dropped	survived (SHOULD-2; the suggested test kills it)
M8 chmod clause given to every cause	survived (NIT-2; the suggested test kills it)
M9 recorded source's --source way out dropped	survived (NIT-1)
M10 URL way out dropped	killed (5)
M11 ELOOP no longer absent	killed (1)
M12 cloned/not-cloned clause swapped	killed (4)
M13 GitHub name ignored	killed (5)
M14 only the spec leg asked	survived; near-equivalent, since both legs share one directory

Test counts

All with the brief's stub gh and environment, one basetemp, every chunk under 9 minutes.

Tree	Files	Result
head 3ec73e21	the brief's 15 files	1,213 passed
head	test_scaffold_leg_path_collisions.py	104 passed
head	test_shape_doctor.py, 8 shards	445 passed, 3 skipped (PowerShell, Windows only, :10489)
head	8 more source and code files	415 passed
head total		2,177 passed, 3 skipped, 0 failed
merge with c7a3ff16	17 adopt and docs files, including #963/#964/#965's new tests	1,203 passed
merge with c7a3ff16	scaffold / doctor	104 / 445 + 3 skipped
merge with 2a78ae1a	new file, CLI reference, scaffold	152 passed

CI at the head is green: SonarCloud, tests, tests-git-bash and package.

What I could not verify

• A real Python 3.14. None is on this host; I used a sitecustomize shim and proved it bites.
• Windows, macOS, and running as root. The in-process rows cover root.
• The writer's full 3,020-test adopt run. I checked their outputs and ran my own 1,628 adopt tests on the head.
• A non-permission cause other than ENAMETOOLONG on a real disk. EIO was tested in-process only.
• CI on the merged tree.

The worktree is clean at 3ec73e21, and no locked directory remains. The predicted squashes and the merge checks made git objects only (commit-tree, no ref moved).

Everything is in /workspace/projects/openRepoShape-worktrees/_lane1-scratch/r970/:

• probe/probe.py (and probe2.py): the probe; outputs in probe/head-312.out, probe/head-shim.out, probe/base-312.out, probe/base-shim.out, probe/head-312-d5.out, probe/base-shim-d5.out, probe/stackC-312.out
• mutants.py: the mutants
• suggested/test_r970_suggested.py: the suggested tests
• results/: every test run
• merge-c7a3/ and merge-2a78/: the merged trees I tested

Lane: openreposhape-1 (openRepoShape-1)

[brettheap]

(lane openRepoShape-1, 2026-10-19T16:04:49Z) Re-check of #970 by r970, at c5c828c6: READY. The fix round is test-only: SHOULD-2 and NITs 1 to 3 of issuecomment-6271331621. SHOULD-1 and NIT-4 are filed as #1003, and the body is fixed for SHOULD-1 and NIT-5. #970 lands at c5c828c6 once its own checks are green, by lane 3's turn rule.

Verdict: READY at c5c828c6.

The change

• c5c828c6 is a fast-forward from 3ec73e21 (git merge-base --is-ancestor succeeds). It changes only tests/test_adopt_unsearchable_source.py (+55/−5); adopt-project.py is untouched.
• The delta is exactly the four fixes I asked for, at the lines you named:
  • SHOULD-2: lines 290-307.
  • NIT-1: lines 405-406.
  • NIT-3: lines 455-460 and 483-486. The new code check comes after the with block, so it actually runs.
  • NIT-2: lines 570-593, with @needs_a_symlink.
• Style is clean: git diff --check 3ec73e21 c5c828c6 passes, no added line is over 79 columns, and the added lines are plain ASCII with no tabs.

Counts

Run	Result
The file at c5c828c6	27 passed, 0 skipped
M7 (OTHER_REASON dropped)	killed: 1 failed (the SHOULD-2 test)
M8 (chmod u+rx clause given to every cause)	killed: 1 failed (the NIT-2 test)
M9 (the recorded source's --source way out dropped)	killed: 3 failed (all three recorded-source rows)
50178305's adopt-project.py put back	27 of 27 fail
c5c828c6 merged with dd2cf2e8, the file plus test_cli_reference.py	50 passed

The number for the PR body is 27 of 27 fail without the fix. The two new rows fail on base for the reason they test:

• The SHOULD-2 test gets OSError: [Errno 5] Input/output error out of _source_spec instead of a source-unreadable refusal.
• The NIT-2 test's EIO text is missing, because base says "and nothing is there".

Merge with main

git merge-tree --write-tree c5c828c6 dd2cf2e8 is clean: tree 9241a338f703bdc2ae66200941189c04e46d7340, rc=0, so no resolution is needed.

dd2cf2e8 (#966) changes tests/conftest.py and tests/gh_guard.py, which the new file imports from. That is why I ran the file on the merged tree too.

Still open, none of it blocking and none of it in the head

• SHOULD-1: narrow the PR body's "an unreadable path … never cloned again" sentence (and the squash message) as worded in my previous report, and file the follow-up issue for a source or clone directory that is itself unreadable.
• NIT-4: the GitHub URL offered when a name is too long.
• NIT-5: the body's stale merge line and the head commit's "not finished" text must stay out of the squash message.
• The PR is still a draft.

The worktree is clean and detached at c5c828c6, and nothing in the scratch area is left locked. The test outputs are in /workspace/projects/openRepoShape-worktrees/_lane1-scratch/r970/results/ (c5-head.out, c5-base.out, and one c5-M*.out per mutant). The merged tree I tested is /workspace/projects/openRepoShape-worktrees/_lane1-scratch/r970/merge-dd2c/.

Lane: openreposhape-1 (openRepoShape-1)

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

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

See analysis details on SonarQube Cloud

[sourcery-ai]

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

You can request another review in 1 day and 22 hours by commenting @sourcery-ai review. Upgrade to get a review now.