[brettheap]

A recorded source whose .git this user cannot read is now refused as source-unreadable, naming that .git. check and execute no longer call a clone plan made with its .git at mode 000 "no longer whole", and no longer clone it again from GitHub. This uses the code and wording #1072 gave a recorded directory this user cannot enter (#918). No refusal code is new.

This PR lands only after the v1.2.0 tag.

Reproduced on main 4ed7c7bf5

Measured as uid 1000, with git 2.43.0 and Python 3.12.3. The run had a stub gh first on PATH that records and refuses every call, GH_TOKEN=bogus, an empty GH_CONFIG_DIR, GIT_SSH_COMMAND=false and an empty global git config. Remotes were local, under --local-remote-dir.

The source was a clone with origin at https://github.com/testorg/Thing.git, so plan recorded source.repository: testorg/Thing. plan --source <it> wrote the plan, and cloned: was set by hand where the row needs it. Then chmod 000 <it>/.git.

Row	check on main	execute --yes on main
.git a directory at 000, cloned: true	exit 2: NOTE "... 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, then source-unclonable; 1 gh repo clone	the same, 1 gh call
.git a directory at 000, cloned: false	exit 2: REFUSED git-failed: git rev-parse --is-inside-git-dir in <it> exited 128: fatal: not a git repository (or any of the parent directories): .git; 0 gh	the same
.git a file (gitdir:) at 000, cloned: true	as the directory row: NOTE, cloning, 1 gh call	the same
.git a file at 000, cloned: false	exit 2: git-failed, fatal: error opening '<it>/.git': Permission denied; 0 gh	the same
readable .git, cloned: true and false	exit 0, plan ok; 0 gh	exit 0, adoption verified; 0 gh

On this branch

Each of the four unreadable rows now exits 2 before anything is cloned or made, and gh is never asked:

REFUSED source-unreadable: the `.git` in the plan's `source.local_path`, `<it>/.git`: cannot be read (Permission denied), so whether `plan`'s clone is still whole, to be read, or no longer whole, to be cloned again, cannot be told
Remediation: a path this user cannot reach is never read as one that is not there, and nothing was cloned. Make it readable by this user: `chmod u+rx` on the directory and on every directory above it, or fix who owns them. Then run the same command again; or pass the source again with --source, which is held to the plan's `commit:`.

• With cloned: false, what cannot be told is "whether a repository is there".
• A .git that is a file is given chmod u+r on the file and chmod u+rx on every directory above it.
• The readable rows are unchanged: plan ok, adoption verified, 0 gh calls.

What changed

All in adopt-project.py, plus the regenerated docs/cli.md and one new test file.

• _git_refused(path) (new, after _not_a_whole_clone) asks the .git before git runs, through _is_a and _is_there (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):
  • A directory is asked whether its HEAD is there. That stat needs only the directory searched, and nothing of HEAD itself.
  • A regular file is opened, as git reads it.
  • Git's own answer cannot be used: it says "not a git repository" of a .git it cannot read, as it does of an emptied clone. With a directory .git, it also climbs to the parent, which may be another repository.
  • It returns (the OSError, whether the .git is a file), or None. None is returned where nothing is there, where the .git holds no HEAD (git's "no repository", as before), or where the .git is neither a directory nor a file.
  • None is also returned where the .git's own stat is refused. Then the directory itself cannot be searched, and adopt-project.py and family.py: a --source this user cannot enter, a UTF-8 plan checked under the C locale, and a member branch that is not UTF-8 still end in a traceback or a false refusal #918's cwd= guards name it, as before.
• Plan._recorded_source asks _git_refused right after asking whether the path is there, before it branches on source.cloned. That covers cloned: true and false alike. The new Plan._git_unreadable words the refusal. The insertion sits clear of adopt-project.py: under a one-byte locale such as Latin-1, check reads a plan written in UTF-8 whose source is there, asking the plan's UTF-8 bytes where the spelling as written names nothing, rather than refusing plan-source-gone (#1078) #1106's change to the there line.
• _source_unreadable takes the cure for a PermissionError as a keyword, permission=. It defaults to the directory's SOURCE_UNREADABLE_PERMISSION, so every other caller is unchanged. A .git file is given the new SOURCE_UNREADABLE_FILE_PERMISSION.
• SOURCE_OVERRIDE_HELP (the --source help of check and execute) now says "one this user cannot reach, or one whose .git this user cannot read, a clone plan made included, as source-unreadable, never cloned again".
  • It is worded so that argparse does not wrap inside source-unreadable.
  • docs/cli.md was regenerated with scripts/render-cli-reference.py.
  • No README, handbook, AGENTS.md or template sentence names this case. AGENTS.md's codes table is untouched, since no code is added.
• --source itself is unchanged. The issue names the recorded clone (see Out of scope).

Rows: tests/test_adopt_unreadable_clone_git.py (new, 18)

Row	main 4ed7c7bf5	this head
test_a_recorded_git_this_user_cannot_read_is_refused_by_name[check,execute x given,cloned x directory,file] (8, real mode 000, needs_a_mode)	8 failed: the refusal line is missing (git-failed, or source-unclonable after gh was asked)	8 passed
test_a_recorded_clone_whose_git_is_refused_is_not_cloned_again (in-process, the stat of .git/HEAD refused, so it runs as root and on Windows too)	failed: check read the clone, exit 0	passed
test_a_git_that_can_be_read_or_is_not_there_is_gits_question[5] (the helper)	5 failed: no _git_refused on main	5 passed
test_a_recorded_git_this_user_can_read_is_read_as_before[given,cloned x directory,file] (4 controls)	4 passed	4 passed

In total: 14 failed and 4 passed on main; 18 passed on this head. The permission rows skip as root and on Windows, as the repository's other permission rows do. The rows' at_mode_000 asserts that the mode bites (os.access(R_OK) is False), and gives the mode back in a finally.

Mutants

Each was applied alone to the committed adopt-project.py (sha256 b2b41532c3a5...) and its rows run. The file was then restored, and its sha256 checked equal to the commit's every time. git status was clean after all of them. All 8 were killed.

Mutant	Killed by
M1 the new guard removed (refused = None)	9 failed / 18: the 8 refused-by-name rows and the in-process row
M2 the guard applied to a readable .git (a PermissionError returned where the .git reads)	9 failed / 18: the 4 read-as-before rows and the 5 helper rows
M3 gh asked anyway (Source.clone of the record asked, then the same refusal raised)	9 failed / 18: the 8 refused-by-name rows (the gh log is not empty) and the in-process row (2 gh calls)
M4 a .git whose own stat is refused taken as the .git's	3 failed / 31: #1072's test_a_recorded_source_this_user_cannot_enter_is_refused_by_name[check-False], [check-True] and [execute-True] (the directory must still be named by itself)
M5 a .git file given the directory's cure	4 failed / 18: the 4 file rows
M6 a .git file never opened	4 failed / 18: the 4 file rows
M7 a .git with no HEAD refused	1 failed / 18: ..._is_gits_question[a-git-directory-with-no-head]
M8 what cannot be told swapped between cloned and given	9 failed / 18

Gate

Run at this head 7a2711d0, 16:35:44Z to 16:46:37Z, with /usr/bin/python3 -m pytest -p no:cacheprovider -o tmp_path_retention_policy=failed. The environment had EMAIL set; GIT_ALLOW_PROTOCOL, GIT_SSH_COMMAND and the LANES_* variables unset; an empty GIT_CONFIG_GLOBAL and GIT_CONFIG_NOSYSTEM=1; test author and committer identities; and a stub gh first on PATH, with GH_TOKEN=bogus and an empty GH_CONFIG_DIR.

Set	Result
test_adopt_unreadable_clone_git.py, test_adopt_source_clone_record.py, test_adopt_unenterable_source_and_locale.py, test_adopt_unsearchable_source.py, #1091's test_adopt_root_shape_paths.py and test_adopt_root_symlinks.py, test_pin_source_unreadable.py, test_cli_reference.py, test_agents_md_codes.py, test_repo_hygiene.py, test_scaffold_leg_path_collisions.py	839 passed, 3 skipped, rc=0
test_shape_doctor.py, 8 shards (62, 56, 54, 56, 60, 57, 58, 45 of 448)	62, 56, 54, 56, 60, 57, 55 + 3 skipped, 45 passed; every shard rc=0

test_pin_source_unreadable.py was added from a grep of tests/ for source-unreadable, _source_unreadable, SOURCE_UNREADABLE_, _recorded_source and SOURCE_OVERRIDE_HELP. pyflakes on adopt-project.py and the new test file reports nothing.

#1111's path-guard hygiene test (lane 1's rule, #473 16:26Z)

The guard asks the .git and its HEAD through adopt-project.py's own _is_a and _is_there. It adds no bare is_file, is_dir, exists, is_symlink or os.path test. tests/test_path_guard_hygiene.py from #1111's head b4484647 was run on a scratch merge of main 4ed7c7bf5, #1111 and this head:

• main + 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 + this head: 1 failed, 48 passed. The one failure is test_no_bare_guard_outside_a_stat_helper_or_the_allowlist[adopt-project.py], for three sites:
  • _PlannedRoot._no_directory: self._git().is_dir(here)
  • _PlannedRoot._into_git: self._git().is_dir(here.rpartition("/")[0])
  • _clone_ref_store: (probe / CLONE_GIT_DIR / "reftable").is_dir()
• main + 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 alone, without this head: the same three sites, the same 1 failed and 48 passed. They come from 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 (4ed7c7bf5, 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), which landed after 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's head was cut. 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 needs them allowlisted or fixed before it lands. This PR does not touch them.
• main + 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 + this head, with only those three sites allowlisted in a scratch copy of the test: 49 passed. This head adds no site.

Merge-trees

Each was run as git merge-tree --write-tree of this head against:

Against	Head	Result
origin/main	4ed7c7bf5	clean, tree 5e784b0f
#1125 fix/1020-bad-id-first-problem	2a53a8e6	clean, tree 76af7e33
#1123 fix/1061-makefile-follow-ups	5c3908f8	clean, tree 12859bc5
#1122 fix/1003-adopt-unenterable-source (_source_there)	c01c4d73	clean, tree 6222542f
#1121 fix/1047-next-make-bootstrap	1c517375	clean, tree e294504f
#1120 fix/1035-source-branch-shown	c55e55e3	clean, tree 46bcc762
#1119 fix/1083-check-asks-the-split-clone	9b998936	clean, tree dcc12164
#1118 fix/1089-named-link-skip-tests	c60066cb	conflict in tests/test_adopt_root_shape_paths.py only, which this head does not touch; #1118 conflicts there with origin/main alone too
#1106 l3-1078-one-byte-locale (_recorded_source's there line)	504a1dd6	clean, tree e59c5cf4
#1105 fix/1048-makefile-follow-up-gnu-read-order	b28f40de	clean, tree 67d4fec4

These are every open pull request that changes adopt-project.py, docs/cli.md or the new test file, as listed at 16:33Z.

Out of scope

Each was measured on this head, and none is changed here:

• plan --source <a repository whose .git is at 000>, and so check --source and execute --source: REFUSED git-failed: ... fatal: not a git repository, exit 2. No gh is asked and nothing is cloned, but the refusal does not name the .git. The issue names the recorded clone only. A follow-up could give _top_level the same guard.
• A readable .git directory whose HEAD is at 000 (cloned: true): still "no longer whole (git finds no repository there)", cloned again, 1 gh call.
• A readable .git file whose git directory is at 000 (cloned: true): the same, 1 gh call.
• Both of those are other files git reads, not the .git the issue measured. Naming every file git might be refused is a wider question, left for a ruling.
• 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 against main: see above (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 bare guards).
• adopt-project.py, shape_materialize.py and tests: a named bad link left out of the copy and pin findings takes no other path's finding with it, and the docstrings and the materializer's refusal name the #979 exception and what helps it (#1089) #1118 against main: git merge-tree of adopt-project.py, shape_materialize.py and tests: a named bad link left out of the copy and pin findings takes no other path's finding with it, and the docstrings and the materializer's refusal name the #979 exception and what helps it (#1089) #1118's head c60066cb with main alone conflicts in tests/test_adopt_root_shape_paths.py. This head does not touch that file.

Closes #1099

🤖 Generated with Claude Code
Lane: openreposhape-4 (openRepoShape-4)

Summary by Sourcery

Refuse recorded sources with unreadable .git metadata before repository validation or recloning, and clearly explain how to make them accessible.

Bug Fixes:

• Refuse recorded sources whose .git cannot be read as source-unreadable, naming the inaccessible path and preventing misleading clone recovery or GitHub recloning.

Enhancements:

• Handle unreadable .git directories and files consistently while preserving existing behavior for readable repositories and sources that cannot be entered.
• Provide tailored remediation guidance for inaccessible .git files and directories.

Documentation:

• Update the CLI reference to document that recorded sources with unreadable .git metadata are refused without recloning.

Tests:

• Add coverage for unreadable .git directories and files, readable controls, no-reclone behavior, and helper path-detection cases.

[sourcery-ai]

Reviewer's Guide

Implementation

Add file-specific permission guidance and detect unreadable .git directories or files before Git can mistake them for missing repositories.

• adopt-project.py L1969-1972, L2058-2061, L2646-2680 (+1 small edits)

Wire the .git refusal into recorded-source validation so both cloned and given sources are refused by path before clone recovery can run.

• adopt-project.py L6705-6710, L6734-6736, L6788-6806

UI

Update check and execute source help to include recorded sources whose .git cannot be read.

• adopt-project.py L18286-18288

Documentation

Regenerate the CLI reference so both command descriptions match the updated source help.

• docs/cli.md L650-653, L717-720

Tests

Add coverage for unreadable .git files and directories, ensuring recorded sources are refused without cloning while readable and absent cases retain their prior handling.

• tests/test_adopt_unreadable_clone_git.py L1-234

---

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]

RV1141: independent review of #1141 at 7a2711d0: READY

No MUST and no SHOULD; four NITs, all follow-ups. Measured as uid 1000, git 2.43.0, Python 3.12.3, with a stub gh first on PATH that logs and refuses every call, GH_TOKEN=bogus, an empty GH_CONFIG_DIR, GIT_SSH_COMMAND=false, an empty GIT_CONFIG_GLOBAL and GIT_CONFIG_NOSYSTEM=1. adopt-project.py is byte-identical on 4ed7c7bf5 and main 038dafba9, so "main" below is 038dafba9.

Reproduced, then fixed

plan --source <clone> with origin at https://github.com/testorg/Thing.git, cloned: set by hand, then chmod 000 <clone>/.git:

.git at 000	main check	scratch merge check
directory, cloned: true	rc 2, NOTE "no longer whole (git finds no repository there)", cloning testorg/Thing, 1 gh call	rc 2, source-unreadable naming <it>/.git, directory cure, 0 gh
directory, cloned: false	rc 2, git-failed ("not a git repository")	rc 2, source-unreadable, "whether a repository is there", 0 gh
file (--separate-git-dir), cloned: true	rc 2, NOTE, cloning, 1 gh call	rc 2, source-unreadable, file cure (chmod u+r on the file), 0 gh
file, cloned: false	rc 2, git-failed ("error opening ... Permission denied")	rc 2, source-unreadable, file cure, 0 gh

execute --yes gave the same: main asked gh once for the directory row with cloned: true, and the merge asked it 0 times (directory with cloned: true, file with cloned: false).

False-refusal probes (scratch merge; check, cloned: true unless noted)

Case	git's own answer	The PR
.git at 0100, 0300, 0500	works	plan ok, 0 gh (no false refusal)
.git at 0400, 0600 (no search)	"not a git repository"	source-unreadable, directory cure, 0 gh
worktree .git file, gitdir readable (cloned false and true)	works	plan ok, 0 gh
submodule .git file, readable (both)	works	plan ok, 0 gh
submodule .git file at 000 (both)	"error opening ... Permission denied"	source-unreadable, file cure, 0 gh
.git a symlink to a readable git dir (both)	works	plan ok, 0 gh
.git a symlink, its target dir at 000 (both)	"not a git repository"	source-unreadable naming <it>/.git, 0 gh
GIT_DIR set to another repo, .git readable (both, main and merge)	reads GIT_DIR	plan ok, as on main
GIT_DIR set to another repo, .git at 000 (both)	reads GIT_DIR	source-unreadable naming .git; main refused too, git-failed ("a git or gh command failed")
.git emptied (no HEAD)	"not a git repository"	NOTE, cloned again, 1 gh: unchanged, as intended
the clone directory itself at 000	n/a	#1072's source-unreadable naming the directory, unchanged
.git/HEAD, .git/objects, .git/refs or .git/config at 000	"not a git repository" / "unable to access '.git/config'"	NOTE, cloned again, 1 gh, identical on main (NIT-2)
worktree gitdir or its common .git at 000; submodule .git/modules/<m> at 000	"not a git repository: "	cloned: true: cloned again, 1 gh; cloned: false: git-failed; as on main
.git a symlink whose target's parent is at 000	"not a git repository"	cloned: true: cloned again, 1 gh, as on main (NIT-3)

No readable or usable .git is now refused. Every remaining clone-again row behaves exactly as on main.

Wording

Each refusal is true and actionable, and matches #1072's family: <named>: cannot be read (Permission denied), so <what> cannot be told. The directory cure "chmod u+rx on the directory" names the .git the line names. The .git file cure is chmod u+r on the file. With cloned: true the wording is "whether plan's clone is still whole, to be read, or no longer whole, to be cloned again,"; with cloned: false it is "whether a repository is there", as #1072's --source refusal says. SOURCE_OVERRIDE_HELP speaks of the recorded local_path, which matches the behaviour. test_cli_reference.py passes on the merge, so docs/cli.md agrees with the help.

Tests (scratch merge 0f3ac25c = main 038dafba9 + 7a2711d0, the gate environment)

Set	Result
test_adopt_unreadable_clone_git.py + test_adopt_unenterable_source_and_locale.py	31 passed
test_path_guard_hygiene.py (#1111, now on main) + test_cli_reference.py	72 passed
test_adopt_unsearchable_source.py, test_agents_md_codes.py, test_repo_hygiene.py, test_adopt_source_clone_record.py	274 passed
test_scaffold_leg_path_collisions.py	104 passed
test_shape_doctor.py, 8 shards, every id list non-empty	445 passed, 3 skipped, 448 ids: shards 00 to 07 gave 62, 56, 54, 56, 60, 57, 55 + 3 skipped and 45. Shards 03 and 04 hit this review's 200 s limit and were rerun with no limit by the lane at 13:42-13:46Z on the same merge 0f3ac25c, 56 and 60 passed

The new file run against main's adopt-project.py (copied into a main worktree): 14 failed, 4 passed, as claimed. They fail for the right reasons:

• the 8 mode rows: git-failed, or the NOTE plus source-unclonable, where source-unreadable is asserted;
• the in-process row: check read the clone;
• the 5 helper rows: no _git_refused.

The 4 controls pass on both.

Mutants (own, on the merge; 31 rows: the new file + #1072's file; sha256 b2b41532c3a5 checked after every one)

Mutant	Result
M1 guard removed (refused = None)	KILLED, 9 failed
M2 the .git's own refused stat taken as the .git's	KILLED, 3 failed (#1072's cannot_enter rows)
M3 return (exc, a_file) without _absent	SURVIVED: equivalent. _is_there already answers an absent HEAD False, so _absent is reached only by a race on the file's open
M4 every refusal swallowed	KILLED, 9 failed
M5 a .git file never opened	KILLED, 4 failed
M6 the directory asked by os.listdir (read permission)	KILLED, but only by the in-process row (1 failed)
M7 cures swapped	KILLED, 9 failed
M8 untold wording swapped	KILLED, 9 failed
M9 names local_path, not its .git	KILLED, 9 failed
M10 guard for cloned: true only	KILLED, 4 failed
M11 guard for cloned: false only	KILLED, 5 failed
M12 the directory asked for read permission, then HEAD (os.access(R_OK) else listdir)	SURVIVED (NIT-1)

Merge-tree

git merge-tree --write-tree of 7a2711d0:

• against origin/main 038dafba9: clean, tree c6a2e736. The merged tree differs from main only in adopt-project.py, docs/cli.md and the new test file.
• against each open PR touching adopt-project.py or docs/cli.md, all clean:

PR	Head
#1153	590ab96e
#1143	7af5fabc
#1125	2a53a8e6
#1123	5c3908f8
#1122	c01c4d73 (_source_there)
#1121	1c517375
#1120	c55e55e3
#1119	bba168bd
#1118	2307036a
#1106	504a1dd6
#1105	b28f40de

Findings

• NIT-1 (test gap). _git_refused's docstring says the directory check needs "only search permission". No row pins that, and M12, which demands read permission, survives all 31 rows.

  • The behaviour is right: 0100 and 0300 measured plan ok, 0 gh.
  • Fix: add a row with the .git at 0100 (and 0300), with cloned: true, asserting plan ok and an empty gh log.

• NIT-2 (out of scope, adopt-project.py: plan --source of a repository whose .git is at mode 000 is refused git-failed with no name for the .git, and a clone whose .git/HEAD or whose gitdir: target is at mode 000 is called no longer whole and cloned again, where #1141 refuses a recorded clone's unreadable .git by name (see #1099) #1151). These are still "no longer whole", with 1 gh call, identical to main:

  • HEAD, objects/, refs/ or config in .git at 000;
  • a worktree's gitdir or common directory at 000;
  • a submodule's .git/modules/<m> at 000.

  adopt-project.py: plan --source of a repository whose .git is at mode 000 is refused git-failed with no name for the .git, and a clone whose .git/HEAD or whose gitdir: target is at mode 000 is called no longer whole and cloned again, where #1141 refuses a recorded clone's unreadable .git by name (see #1099) #1151 names HEAD and the .git file's git directory. Add objects/, refs/ and config: git's own "is a git directory" asks HEAD, objects/ and refs/, and config gives "unable to access '.git/config': Permission denied".

• NIT-3 (docstring). _git_refused says a .git whose own stat is refused "is in a path this user cannot search". That is false for a .git symlink whose target is under a directory this user cannot search. Measured: with cloned: true it is cloned again, 1 gh, as on main.

  • Fix: reword the sentence, and list the case in adopt-project.py: plan --source of a repository whose .git is at mode 000 is refused git-failed with no name for the .git, and a clone whose .git/HEAD or whose gitdir: target is at mode 000 is called no longer whole and cloned again, where #1141 refuses a recorded clone's unreadable .git by name (see #1099) #1151.

• NIT-4 (Sonar, gate passed). The PR adds two Sonar issues:

  • S3776: _recorded_source cognitive complexity is now 17 > 15 (adopt-project.py:6652).
  • S1192: "whether a repository is there" now appears 3 times (:2090).

  Fix: move the two-line guard into a helper (or into _git_unreadable, returning None), and make the phrase a constant.

Lane: openreposhape-4 (openRepoShape-4)

[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]

M1141: main merged into #1141, new head 0b8fb3205. A delta review of the merge only is asked for.

Head 0b8fb3205645e6a841e325607b4d7295b636b66e is ONE merge commit (no rebase, pushed without force, 7a2711d03..0b8fb3205). Its parents are 7a2711d03 (the head RV1141 graded READY) and main 11560eb9f. GitHub had said CONFLICTING; it now says MERGEABLE, draft, closingIssuesReferences [1099].

Main moved three times during the work (bd3e9c148, then 93d293141, then 11560eb9f) and once more after the gate, to 105b5daf9. That last commit touches none of this PR's three files, and git merge-tree --write-tree origin/main HEAD against 105b5daf9 is clean.

Conflicts: 2 files, 3 hunks, no others

1. adopt-project.py, SOURCE_OVERRIDE_HELP (1 hunk). This branch widened "one this user cannot reach" to "or one whose .git this user cannot read" and ended the string there. Main (adopt-project.py: check and execute run with GIT_NO_LAZY_FETCH=1 and refuse a partial-clone source that lacks an object its branches, tags or HEAD reach as source-partial-clone, so neither fetches into the source any more (#1145) #1180, the source-partial-clone rule) appended its sentences ("Either source, where it is a partial clone ... makes it whole.") after "never cloned again.". Both are independent facts about the same --source help, so both are kept: our sentence, then main's sentences word for word. Only the closing ") moved, to the end of main's text. No word of either side changed.
2. docs/cli.md (2 hunks: the --source help of check and of execute). The same text as rendered. Not hand-edited: regenerated with python3 scripts/render-cli-reference.py, and its --check says "docs/cli.md is what the generator produces". Against main the file differs only in those two rewrapped paragraphs.

Order of the two rules, read in the merged code and not changed: cmd_check and cmd_execute call plan.open_source (where _recorded_source asks _git_refused) and only then _refuse_a_partial_clone_short. A recorded .git this user cannot read is therefore refused source-unreadable before the partial-clone check reads anything.

How to see only the merge: git show --remerge-diff 0b8fb3205 shows just the two resolutions above. Against 11560eb9f the head differs only in adopt-project.py, docs/cli.md and tests/test_adopt_unreadable_clone_git.py (318 insertions, 12 deletions); the 78 changed lines of adopt-project.py are those of 7a2711d03 against 4ed7c7bf5, but for the two lines that end SOURCE_OVERRIDE_HELP.

Gate at 0b8fb3205

Run with CI's pin, git-filter-repo 2.47.0 (git filter-repo --version prints a40bce548d2c), first on PATH. A first pass run before it was on PATH skipped the filter-repo rows; it is superseded, and every count below is from runs with it. Each run used /usr/bin/python3 -m pytest -p no:cacheprovider -o tmp_path_retention_policy=failed, one reused basetemp, at most 2 runs at once, EMAIL set, GIT_ALLOW_PROTOCOL, GIT_SSH_COMMAND and the LANES_* variables unset, an empty global git config with GIT_CONFIG_NOSYSTEM=1, test identities, and a stub gh first on PATH that logs and refuses every call (GH_TOKEN=bogus, empty GH_CONFIG_DIR). The stub's log was never written: 0 gh calls in all of it.

Set	Result
test_adopt_unreadable_clone_git.py (18), test_adopt_source_clone_record.py, test_adopt_unenterable_source_and_locale.py, test_adopt_unsearchable_source.py, test_adopt_root_shape_paths.py, test_adopt_root_symlinks.py, test_pin_source_unreadable.py, test_pin_source_top_level.py, test_adopt_partial_clone_source.py, test_adopt_check_throwaway_repos.py, test_adopt_next_make_reads_first.py, test_adopt_nested_attributes.py, test_adopt_reencoded_files.py, test_adopt_template_values.py	1047 passed, 4 skipped, rc=0
test_adopt_pins.py, test_pinned_copy_text.py, test_pin_pattern_line_break.py, test_adopt_work_dir_refusal.py, test_adopt_plan_flag_refusals_first.py	427 passed, rc=0
test_cli_reference.py, test_agents_md_codes.py, the hygiene pair test_repo_hygiene.py and test_path_guard_hygiene.py (now with main's change to it), test_scaffold_leg_path_collisions.py, test_doctor_unsearchable_links.py, test_command_scopes_built_at_the_test.py, test_scaffold_partial_pin_source.py	463 passed, rc=0
test_shape_doctor.py, 8 shards of its 449 ids (57, 57, 57, 57, 57, 57, 54 + 3 skipped, 50), every id list non-empty	446 passed, 3 skipped, every shard rc=0

Total 2383 passed, 7 skipped. The skips are the host's: 3 rows need the reftable backend (git 2.45; this host has 2.43), 1 needs a disk that ignores case, 3 print a PowerShell line that exists only on a Windows host.

Two earlier merge heads of this work, e8928f6a1 (on main bd3e9c148) and 547788bdc (on 93d293141), were gated with the same sets and passed as well; they were never pushed, and were superseded when main moved.

Merge-trees (git merge-tree --write-tree, this head against each)

• origin/main 11560eb9f: clean, tree 2719ddb11 (the head's own tree). Against 105b5daf9: clean.
• The 24 open PRs that change adopt-project.py, docs/cli.md or the new test file, listed at 14:35Z: 23 clean (repo_shape.py and adopt-project.py: a plain integer of more digits than this Python reads, or a decimal too large to be finite, is yaml-unparsable by its line, where it was a ValueError traceback or "the number inf", and _read_as says a float in digits with no exponent, where it said "the number 1e+300" (#1212) #1249 80ec29177, adopt-project.py: a refused command's REFUSED block spells each character a terminal acts on in the command, its directory and what it printed, as _first_said spells gh's, so --local-remote-dir no longer reaches the terminal raw there; a NOTE before NEXT: says when the source's path in its clone command holds a character a terminal does not show as itself; and rows pin six sites #1177's 148 left to chance (#1195) #1225 73c9f57e8, adopt-project.py: check and execute read one list of a plan's problems against its source, in the order a person mends them (another repository, a refused name, a moved source, an unanswered entry), so check's first finding is execute's refusal for each pair (#1113) #1210 791106c2b, adopt-project.py, shape_materialize.py and the assembly-root template: a kept GNUmakefile/ is a directory GNU make stops at, python3 scripts/bootstrap.py names python on Windows, and the template says what to run where make reads another file #1207 6fa1edd56, adopt-project.py: _pin_row_problem says a pin field whose value is not text as _read_as says what the plan's reader read, "records commit: as the number 7", where it spelled it as Python does, commit: 7 and True, so check and execute name it in the words the plan's other refusals use under the same plan-pin-malformed (#1114) #1198 d38e4e36d, adopt-project.py: _github_name reads no owner over 39 characters or repository over 100, so plan --source <50 b's>/Thing never asks gh for a name GitHub cannot hold, no remedy offers --org <50 b's>, and check and execute never clone such a record again (#1129) #1194 900f77af9, adopt-project.py: plan runs with GIT_NO_LAZY_FETCH=1, refuses a partial-clone --source that lacks objects as source-partial-clone, and names a partial --pin-source it could read only by fetching and the fetch that makes it whole (#1162) #1190 e42134e10, adopt-project.py: check names the case twins the plan keeps in one repository as plan-case-twins on every disk, a one-blob set as a NOTE in a leg and, in the root, two paths in one folder, and execute refuses the finding before any leg (#1161) #1189 5c4fcd9db, adopt-project.py: a --source, or a plan's source.local_path, with a part of its repository git reads at mode 000 (the .git, its HEAD, objects, refs or config, the git directory a gitdir: line names, or a directory above it) is refused source-unreadable naming that part, never git-failed and never cloned again (#1151) #1186 07486a498, adopt-project.py: plan's table pads each name by the columns a terminal gives it, not the code points it holds, so a wide or combining name's leg column lines up under leg with every other row's (#1034) #1178 c4beba193, adopt-project.py: the --plan path in check and execute, and the --local-remote-dir path in execute's bare, leg and split lines, are named with _shown, as #1154 names --out and --work-dir, so a bidi control, an escape, a line feed or a byte that is not UTF-8 in either no longer reaches the terminal as it was typed (#1152) #1177 5208e874e, adopt-project.py and repo_shape.py: a name that holds a default-ignorable character, which a terminal draws as nothing, is spelled by its code point in plan's lines and in the unsafe-value refusal, so a branch ma<U+034F>in no longer prints as main (#1128) #1171 8162b874e, adopt-project.py: check names each case twin at the shape's copy, above it and at the manifest, before a link there or after it, and at a pin's file whose exact spelling holds nothing, as _KeptTree keeps every row, not the first (#1138) #1170 24ee133aa, adopt-project.py: plan written to and cloning <repository> (read only) into name the caller's --out and --work-dir with _shown, as the other lines of the report name a path, so a bidi control, a line feed or a tab in either no longer reaches the terminal as it was typed (#1115) #1154 8a7828332, adopt-project.py: under a one-byte locale such as Latin-1, a clone check makes again for a plan's clone record that neither spelling names is compared with both, so it is kept and the next run reads it rather than cloning again (#1112) #1153 ff33ba12a, adopt-project.py: a --work-dir link into a loop that Python 3.12 reads past a link that does not loop names the loop, Windows' winerror 1921 counts as one, and a path read as the loop's link says so, with tests for r1065's mutants (#1074) #1143 7af5fabc3, adopt-project.py: check and execute ask a plan's org: and id: right after its three repository names, so a bad one beside an unanswered entry, a moved source, a refused name or another repository is that one refusal in both, and a pins: entry that is no pin is said as _read_as says it (#1020) #1125 9549006fe, README.md, adopt-project.py and the handbook: a kept directory entry makefile/ is tested, README says make at the root reads a kept GNUmakefile or makefile instead, and a docstring says the shape's Makefile alone holds CONTRACTS_DIR (#1061) #1123 5c3908f8d, adopt-project.py: an org/repo --source too long for the disk is refused as a path is, naming no GitHub repository and offering no url, so --source <300 a's>/Thing is no longer offered https://github.com/<300 a's>/Thing, which can never clone (#1003) #1122 c01c4d73d, adopt-project.py: plan's source line names the source's branch as _shown names a path, so a bidi control, a line boundary or a byte that is not UTF-8 in it is spelled and no longer reaches the terminal raw (#1035) #1120 c55e55e33, adopt-project.py, shape_materialize.py and tests: a named bad link left out of the copy and pin findings takes no other path's finding with it, and the docstrings and the materializer's refusal name the #979 exception and what helps it (#1089) #1118 2307036ab, adopt-project.py: under a one-byte locale such as Latin-1, check reads a plan written in UTF-8 whose source is there, asking the plan's UTF-8 bytes where the spelling as written names nothing, rather than refusing plan-source-gone (#1078) #1106 504a1dd65, shape_materialize.py and the pinned AGENTS-shape.md: where the root keeps a GNUmakefile or a makefile, which GNU make reads first, the Makefile collision follow-up no longer says the shape's make targets arrive with the merge, and the pinned file says make reads the first of the three and the block reaches it only once that file holds it (#1048) #1105 b28f40de0).
• adopt-project.py: the mount removes a path a case twin is at or under with git rm -f and writes the twins the root keeps back from the index, so on a disk that ignores case execute keeps a set the plan splits across repositories or drops (#1183) #1237 63c527185: conflict in tests/test_adopt_check_throwaway_repos.py only, a file this PR does not touch. It conflicts there with origin/main alone too.

Asked

A delta review of the merge only, as above. The PR's own diff against main is unchanged in substance from the head RV1141 graded READY, and the four RV1141 NITs are still open follow-ups; this merge does not touch them.

Lane: openreposhape-4 (openRepoShape-4)

[brettheap]

RD1141: independent delta review of #1141 at 0b8fb320: READY

No MUST, no SHOULD, one NIT. Scope: the merge 0b8fb3205 only (parents 7a2711d03, the head RV1141 graded READY, and main 11560eb9f). Measured as uid 1000, git 2.43.0, Python 3.12.3, with a stub gh first on PATH that logs and refuses every call (its log has 0 lines), GH_TOKEN=bogus, an empty GH_CONFIG_DIR, GIT_SSH_COMMAND=false, an empty GIT_CONFIG_GLOBAL, GIT_CONFIG_NOSYSTEM=1, and git-filter-repo 2.47.0 first on PATH (git filter-repo --version prints a40bce548d2c). Main moved after M1141's comment: 105b5daf9, then b66d8f0cc, then 0d5704b3d (my last fetch, 15:09Z). None of the three touches adopt-project.py, docs/cli.md or the new test file.

1. The delta is unchanged

• The head is ONE merge commit with parents 7a2711d03 and 11560eb9f (git log --format='%H %P'). The merge-base of those two is 4ed7c7bf5, so RV1141's graded delta is git diff 4ed7c7bf5 7a2711d03 (3 files, 316 insertions, 10 deletions) and the head's is git diff 11560eb9f 0b8fb3205 (3 files, 318 insertions, 12 deletions).
• git show --remerge-diff 0b8fb3205 shows exactly three conflict hunks in two files (adopt-project.py 1, docs/cli.md 2) and nothing else: no hand edit outside a conflict.
• Diff of the two diffs (hunk headers and index lines stripped, then diff): 12 differing lines (4 in the graded delta, 8 in the head's), all inside those three hunks.
  • adopt-project.py, 2 lines in each delta: the - line ("planmade included, assource-unreadable, never cloned again.") in the graded delta, which is 4ed7c7bf5's line; the same words ending again. " in the head's, which is main's line) and the + line ("source-unreadable, never cloned again.") against "source-unreadable, never cloned again. "). The closing ") moved to the end of main's sentences, as M1141 said.
  • docs/cli.md, in each of the two hunks (check's and execute's --source): the head's delta also removes the line Either source, where it is a partial clone (git clone(main's wrap, which the graded delta never had), and its last+line is ``source-unreadable, never cloned again. Either`` followed by a new +linesource, where it is a partial clone (git clone, where the graded delta's last + line ends at again..
• The other direction: adopt-project.py changed against the branch parent (git diff 7a2711d03 0b8fb3205) equals main's own delta (git diff 4ed7c7bf5 11560eb9f) on every line but those two SOURCE_OVERRIDE_HELP lines. tests/test_adopt_unreadable_clone_git.py is the same blob on 7a2711d03 and the head (fe3be9ca1ac9).
• Main's delta from 4ed7c7bf5 to 11560eb9f has no hunk before line 7770 of adopt-project.py except a docstring at line 110, so it touches none of _source_unreadable, _not_a_whole_clone, _git_refused or _recorded_source, which all sit above line 7770. Its changes in cmd_check and cmd_execute are the _refuse_a_partial_clone_short calls, the _lazy_fetch_off decorator and adopt-project.py: execute's NEXT prints make bootstrap where GNU make at the root reads a kept makefile or GNUmakefile, which has no bootstrap rule #1047's surviving= argument.

2. Each conflict hunk keeps both sides

SOURCE_OVERRIDE_HELP evaluated from the four commits with ast.literal_eval:

• 7a2711d03's string equals 4ed7c7bf5's with one phrase added (, or one whose .git this user cannot read): True.
• 11560eb9f's string starts with 4ed7c7bf5's and adds only the partial-clone tail: True.
• The head's string equals 7a2711d03's string + main's tail, byte for byte: True. No word of either side changed.
• adopt-project.py check --help and execute --help on the head (COLUMNS=80) print the paragraph in full: "... and one this user cannot reach, or one whose .git this user cannot read, a clone plan made included, as source-unreadable, never cloned again. Either source, where it is a partial clone (git clone --filter) that lacks an object its branches, tags or HEAD reach, is refused as source-partial-clone before anything reads it: ... makes it whole." It reads correctly, and argparse does not wrap inside source-unreadable.

3. docs/cli.md

• python3 scripts/render-cli-reference.py --check on the head: [ok] docs/cli.md is what the generator produces, exit 0.
• git diff 11560eb9f 0b8fb3205 -- docs/cli.md is only the two rewrapped paragraphs.
• Same --check on a scratch merge of main, the head and adopt-project.py: plan runs with GIT_NO_LAZY_FETCH=1, refuses a partial-clone --source that lacks objects as source-partial-clone, and names a partial --pin-source it could read only by fetching and the fetch that makes it whole (#1162) #1190 (the one other open PR that edits docs/cli.md): ok.

4. The order of the two refusals

Probe on the head (rd1141-head-wt), a partial clone of a small origin (--filter=blob:none, --no-checkout and checked out), recorded in the plan as source.local_path; .git a directory or a gitdir: file (--separate-git-dir shape); cloned false or true; check and execute --yes:

Case	Rows	Result
.git at mode 000, partial clone	16 (2 clones x 2 kinds x 2 cloned x 2 verbs)	all 16: rc 2, REFUSED source-unreadable naming <it>/.git, never source-partial-clone; 0 gh calls, 0 upload-pack runs, no remotes/ directory made
.git readable, same partial clones	8 (2 x 2 x 2)	all 8: rc 2, REFUSED source-partial-clone with the git fetch --refetch --no-filter origin cure; not source-unreadable; 0 upload-pack runs
.git readable, cloned: true, check	1	source-partial-clone, 0 gh, 0 upload-pack

Same 16 rows on main b66d8f0cc (no _git_refused): all 16 fail: the 8 given rows with git-failed ("not a git repository" or "error opening ... Permission denied"), and the 8 cloned rows with source-unclonable after gh repo clone was asked (the suite's gh guard caught the call: 8 teardown errors).

The order cannot flip the answer, which is why it is robust: with .git at 000 the partial-clone rule's own two questions see nothing. Measured through the head's module on the same clones: _promisor_remotes is ['origin'] and _objects_lacking is 28 while the .git is readable, and [] and None while it is at 000 (directory and file alike), where _git_refused answers. So _refuse_a_partial_clone_short would return silently on such a source even if it ran first; source-unreadable comes from plan.open_source, ahead of it, in both cmd_check and cmd_execute.

5. Gate on a scratch merge of the head with current main

Scratch merge a6e3f7997 = 0b8fb3205 + main b66d8f0cc (tree f55be2f5; it differs from main in the PR's three files only: 318 insertions, 12 deletions). /usr/bin/python3 -m pytest -p no:cacheprovider -o tmp_path_retention_policy=failed, a basetemp per job, 2 jobs at a time, 15:00Z to 15:08Z; -rs on every run.

Set (collected)	Result
test_adopt_unreadable_clone_git.py (18), test_adopt_partial_clone_source.py (38)	56 passed
test_adopt_source_clone_record.py (100), test_adopt_unenterable_source_and_locale.py (13), test_adopt_unsearchable_source.py (27)	140 passed
test_cli_reference.py (23), test_repo_hygiene.py (101), test_path_guard_hygiene.py (121), test_scaffold_leg_path_collisions.py (104)	349 passed
test_shape_doctor.py, 8 shards of its 449 ids (57, 57, 57, 57, 57, 57, 54 + 3 skipped, 50), every shard list non-empty (checked before any ran)	446 passed, 3 skipped, every shard rc 0

Total 991 passed, 3 skipped, 0 failed. The 3 skips are one reason: "the PowerShell line is printed, and powershell.exe exists, only on a Windows host" (tests/test_shape_doctor.py:10516). No row skipped for lack of git-filter-repo (needs_filter_repo rows ran; no skip reason names it). Nothing was installed.

6. Merge-trees (git merge-tree --write-tree, head against each)

• origin/main 0d5704b3d: clean, tree 4a15d1fc. The merged tree differs from main in adopt-project.py, docs/cli.md and tests/test_adopt_unreadable_clone_git.py only. Against b66d8f0cc: clean, tree f55be2f5.
• The 30 other open PRs that change adopt-project.py or docs/cli.md, listed at 15:00Z (52 open in all): 29 clean: adopt-project.py: check's compare for the mount's git rm skips the .gitattributes it leaves and reads its exit code, so the root's failing filter is plan-attributes-reencoded alone, and a refused compare is named in git's words (#1192) #1253 18c2aaef5, adopt-project.py: a source whose refs this user cannot list is refused source-unreadable naming the directory, never source-default-branch-not-local "(its branches: none)" (#1219) #1252 40b030cbf, adopt-project.py: execute unsets the leg clone's remote.origin.url before git filter-repo, so under a Latin-1 locale a source under a directory named with the byte 0xE9 is extracted, where filter-repo died printing that url as U+FFFD, and every branch of the source is still rewritten as before (#1247) #1251 825923c76, repo_shape.py and adopt-project.py: a plain integer of more digits than this Python reads, or a decimal too large to be finite, is yaml-unparsable by its line, where it was a ValueError traceback or "the number inf", and _read_as says a float in digits with no exponent, where it said "the number 1e+300" (#1212) #1249 80ec29177, tests/test_adopt_plan_value_order.py: a bad id: or org: beside a --work-dir that is a file or a shared one, or beside a gone source, is the value's refusal in both check and execute, so the head ask is pinned against _work_root's other refusals and the source (#1179) #1226 f61be9f59, adopt-project.py: a refused command's REFUSED block spells each character a terminal acts on in the command, its directory and what it printed, as _first_said spells gh's, so --local-remote-dir no longer reaches the terminal raw there; a NOTE before NEXT: says when the source's path in its clone command holds a character a terminal does not show as itself; and rows pin six sites #1177's 148 left to chance (#1195) #1225 73c9f57e8, adopt-project.py: check and execute read one list of a plan's problems against its source, in the order a person mends them (another repository, a refused name, a moved source, an unanswered entry), so check's first finding is execute's refusal for each pair (#1113) #1210 791106c2b, tests/conftest.py and tests/test_adopt_plan_paths_spelled.py: under a one-byte locale such as Latin-1 the 0xff --work-dir row skips and the two U+00E9 rows read the child's UTF-8, so none of the three fails on a tool that is right, and the bytes helper starts its child as run_script does (#1196) #1209 13a2c58cb, adopt-project.py, shape_materialize.py and the assembly-root template: a kept GNUmakefile/ is a directory GNU make stops at, python3 scripts/bootstrap.py names python on Windows, and the template says what to run where make reads another file #1207 6fa1edd56, adopt-project.py: _pin_row_problem says a pin field whose value is not text as _read_as says what the plan's reader read, "records commit: as the number 7", where it spelled it as Python does, commit: 7 and True, so check and execute name it in the words the plan's other refusals use under the same plan-pin-malformed (#1114) #1198 d38e4e36d, adopt-project.py: _github_name reads no owner over 39 characters or repository over 100, so plan --source <50 b's>/Thing never asks gh for a name GitHub cannot hold, no remedy offers --org <50 b's>, and check and execute never clone such a record again (#1129) #1194 900f77af9, adopt-project.py: plan runs with GIT_NO_LAZY_FETCH=1, refuses a partial-clone --source that lacks objects as source-partial-clone, and names a partial --pin-source it could read only by fetching and the fetch that makes it whole (#1162) #1190 e42134e10, adopt-project.py: check names the case twins the plan keeps in one repository as plan-case-twins on every disk, a one-blob set as a NOTE in a leg and, in the root, two paths in one folder, and execute refuses the finding before any leg (#1161) #1189 7d2f651e7, adopt-project.py: a --source, or a plan's source.local_path, with a part of its repository git reads at mode 000 (the .git, its HEAD, objects, refs or config, the git directory a gitdir: line names, or a directory above it) is refused source-unreadable naming that part, never git-failed and never cloned again (#1151) #1186 07486a498, tests/test_adopt_plan_paths_spelled.py: seven mutants of the plan written to and cloning ... into lines that no row killed now fail one, so a printable non-ASCII path prints as typed, ESC, CR and a non-UTF-8 --work-dir are spelled, a relative --out is not made absolute, an --out that ends in a space or is wrapped in backticks is spelled, and execute spells the clone line as plan does (#1167) #1185 d193617c7, adopt-project.py: plan's table pads each name by the columns a terminal gives it, not the code points it holds, so a wide or combining name's leg column lines up under leg with every other row's (#1034) #1178 c4beba193, adopt-project.py: the --plan path in check and execute, and the --local-remote-dir path in execute's bare, leg and split lines, are named with _shown, as #1154 names --out and --work-dir, so a bidi control, an escape, a line feed or a byte that is not UTF-8 in either no longer reaches the terminal as it was typed (#1152) #1177 5208e874e, adopt-project.py and repo_shape.py: a name that holds a default-ignorable character, which a terminal draws as nothing, is spelled by its code point in plan's lines and in the unsafe-value refusal, so a branch ma<U+034F>in no longer prints as main (#1128) #1171 8162b874e, adopt-project.py: check names each case twin at the shape's copy, above it and at the manifest, before a link there or after it, and at a pin's file whose exact spelling holds nothing, as _KeptTree keeps every row, not the first (#1138) #1170 24ee133aa, adopt-project.py: plan written to and cloning <repository> (read only) into name the caller's --out and --work-dir with _shown, as the other lines of the report name a path, so a bidi control, a line feed or a tab in either no longer reaches the terminal as it was typed (#1115) #1154 8a7828332, adopt-project.py: under a one-byte locale such as Latin-1, a clone check makes again for a plan's clone record that neither spelling names is compared with both, so it is kept and the next run reads it rather than cloning again (#1112) #1153 ff33ba12a, adopt-project.py: a --work-dir link into a loop that Python 3.12 reads past a link that does not loop names the loop, Windows' winerror 1921 counts as one, and a path read as the loop's link says so, with tests for r1065's mutants (#1074) #1143 7af5fabc3, adopt-project.py: check and execute ask a plan's org: and id: right after its three repository names, so a bad one beside an unanswered entry, a moved source, a refused name or another repository is that one refusal in both, and a pins: entry that is no pin is said as _read_as says it (#1020) #1125 9549006fe, README.md, adopt-project.py and the handbook: a kept directory entry makefile/ is tested, README says make at the root reads a kept GNUmakefile or makefile instead, and a docstring says the shape's Makefile alone holds CONTRACTS_DIR (#1061) #1123 5c3908f8d, adopt-project.py: an org/repo --source too long for the disk is refused as a path is, naming no GitHub repository and offering no url, so --source <300 a's>/Thing is no longer offered https://github.com/<300 a's>/Thing, which can never clone (#1003) #1122 c01c4d73d, adopt-project.py: plan's source line names the source's branch as _shown names a path, so a bidi control, a line boundary or a byte that is not UTF-8 in it is spelled and no longer reaches the terminal raw (#1035) #1120 c55e55e33, adopt-project.py, shape_materialize.py and tests: a named bad link left out of the copy and pin findings takes no other path's finding with it, and the docstrings and the materializer's refusal name the #979 exception and what helps it (#1089) #1118 2307036ab, adopt-project.py: under a one-byte locale such as Latin-1, check reads a plan written in UTF-8 whose source is there, asking the plan's UTF-8 bytes where the spelling as written names nothing, rather than refusing plan-source-gone (#1078) #1106 504a1dd65, shape_materialize.py and the pinned AGENTS-shape.md: where the root keeps a GNUmakefile or a makefile, which GNU make reads first, the Makefile collision follow-up no longer says the shape's make targets arrive with the merge, and the pinned file says make reads the first of the three and the block reaches it only once that file holds it (#1048) #1105 b28f40de0.
• adopt-project.py: the mount removes a path a case twin is at or under with git rm -f and writes the twins the root keeps back from the index, so on a disk that ignores case execute keeps a set the plan splits across repositories or drops (#1183) #1237 63c527185: conflict in tests/test_adopt_check_throwaway_repos.py only, a file this PR does not touch; merge-tree of adopt-project.py: the mount removes a path a case twin is at or under with git rm -f and writes the twins the root keeps back from the index, so on a disk that ignores case execute keeps a set the plan splits across repositories or drops (#1183) #1237 with origin/main alone conflicts in that file too.

Mutants

Applied alone to a copy of the head, run, then restored with cp; the sha256 of adopt-project.py (2d5f5124...) and docs/cli.md (39cdd460...) was checked equal to the head's after every one, and git status is clean but for my untracked probe file.

Mutant	Result
MR1 the branch's .git phrase dropped from SOURCE_OVERRIDE_HELP, docs left	KILLED, 5 failed / 23 (test_cli_reference.py: help vs file, committed reference vs generator, the generator's own --check, 2 checkout rows)
MR2 main's partial-clone sentences dropped from the help, docs left	KILLED, 5 failed / 23, the same rows
MR3 docs/cli.md's execute paragraph put back to the pre-merge wrap	KILLED, 5 failed / 23, the same rows
MR4 the guard removed (refused = None), which is the order of the two rules falling to main's	KILLED, 25 failed, 18 passed, 8 teardown errors: 9 of the PR's own 18 rows, and all 16 of my probe rows
MR5 the guard asked after the cloned: false branch has read the clone	KILLED, 12 failed / 43: the 4 given rows of the PR's file and 8 probe rows

Findings

• NIT-1 (test gap, follow-up). No row in the repository pins a partial clone whose recorded .git is unreadable. The PR's 9 refused-by-name rows and test_adopt_partial_clone_source.py each cover one rule, and the two rules now share --source's help and check/execute. The behaviour is right and cannot be flipped by a reorder (section 4), so this is a guard against a later refactor only. Fix: one parametrized row in tests/test_adopt_unreadable_clone_git.py (or in test_adopt_partial_clone_source.py) that makes Source("nocheckout"), puts the .git at mode 000 under needs_a_mode, and asserts REFUSED source-unreadable, no source-partial-clone, and 0 gh and 0 upload-pack runs. My probe is at /workspace/projects/openRepoShape-worktrees/_lane4-scratch/tools/run/rd1141/probe/test_rd1141_probe.py (16 + 8 rows) and can be cut down to it.

Not re-reviewed, and not changed by the merge: RV1141's four NITs (the 0100/0300 row, the HEAD/objects/refs/config rows for #1151, the _git_refused docstring on a symlinked .git, and the two Sonar issues, of which SonarCloud's comment of 14:54Z shows 2 new issues, gate passed).

Lane: openreposhape-4 (openRepoShape-4)