[brettheap]

Lane: openreposhape-3 (openRepoShape-3)
Claim: #212 (comment)

What

check and execute now spell every path a FINDING or a refusal names through _spelled, the helper plan already uses for its questions. A spelled path sits between backticks. \r, \n, \x85, \u2028, \x1b and every other character str.isprintable refuses are written as backslash escapes. So is a byte that is not UTF-8 (\xNN), and so are a backslash and a backtick. A finding is therefore one line of printable text, whatever the source's author named a file.

• Coverage (_coverage_findings): plan-duplicate-path, plan-uncovered, plan-covered-twice and plan-empty-entry. A path covered twice now lists its entries as `src/`, `src/app/`. Main printed them as a Python list.
• Entry legs (_leg_findings): plan-unresolved and plan-bad-leg.
• Source submodules (_as_entry): plan-submodule-root, plan-submodule-split and plan-submodule-unregistered name the submodule and its entry.
• Mount collisions (_kept_collisions): plan-leg-path-collides and plan's collision note put a source path between backticks by hand. They now spell it with _spelled. Since fix round 3 that goes through the optional spell argument of first_and_more, which scaffold-project.py accepts a leg path that collides with a path the shape writes (--spec-path contracts, --code-path project.yaml), creates all three repositories and pushes both legs, then dies: #172's shape half on the scaffold side #197 moved to scripts/shape_materialize.py (see Composes with).
• execute's own refusal (_refuse_an_unrunnable_plan): plan-unresolved lists its paths with _listed. execute's _refuse_what_check_finds prints check's own list (_entry_findings), so the two commands change together.
• Verification after the split (_account_for): adopt-duplicated and adopt-lost.
• adopt-project.py: verification passes over the two leg mounts and no other gitlink, so the source's own submodule kept in the root is adopt-root-submodule, any other root gitlink adopt-unexpected-gitlink, one in a leg AND the root adopt-duplicated, and a missing mount adopt-mount-missing (#165) #173's root-tree gitlink findings (_root_gitlink_finding, fix round 1): adopt-root-submodule and adopt-unexpected-gitlink spell the gitlink they name. The mount paths beside it are leg paths, as in adopt-mount-missing.
• Shape files in the split (_missing_shape_file, _SplitTree): adopt-shape-file-missing spells the pinned path, the symlink a lookup met, the target it leads out to, and a path that is not a directory.
• The mount guard adopt-project.py: the leg mount passes --force to git submodule add, so a source whose .gitignore is * + !.gitignore, or names spec or code, adopts instead of dying at the mount after both leg remotes were pushed (#174) #200 added (_entry_named, _index_entries): adopt-mount-occupied names the index entry it found under the leg mount path, and now calls _spelled where it used to put backticks around the name by hand. Since fix round 1, _index_entries decodes index names with surrogateescape, as Source.tree does, so a byte that is not UTF-8 prints as \xfe. With replace, a<0xFE> and a<0xFF> both read a<U+FFFD>. The mount path itself is a leg path, and checked_value's alphabet already keeps that printable.
• plan-stale (fix round 1): check's finding and execute's refusal spell the source's branch. git's ref-name rules refuse only ASCII control characters, so a branch named with U+0085 or U+2028 split that line.

Correction to the first commit's body. It says the spelling "reads one way only", and that is not quite true. A raw byte 0x80-0xA0 or 0xAD and the character U+0080-U+00A0 or U+00AD are both spelled \xNN, which makes 34 pairs. A source holding both Icon<0x85> and Icon<U+0085> therefore prints the same finding twice. Main's _spelled already did this, and plan's questions have done it since #166. The squash message prepared for the merge drops the claim and says this instead. The ambiguity itself is a follow-up (Left out).

Why

Measured on this machine. The first two tables and the byte-identity check were measured on main a5b09c3 against the first commit, 35cb5f8. That commit has the same tree as 58b4343, which only rewrites a raw U+2028 in the commit message as \u2028. The fix-round table follows them.

The issue's own repro (sh, with the checkout as a parameter and check's exit code captured):

case	main a5b09c3	head (35cb5f8)
route 1: entry "README\nX.md", check stderr through cat -A	exit 1. FINDING plan-empty-entry: README$ then X.md covers nothing in the source tree at this commit$. One finding prints on two lines, and the second does not start with FINDING	exit 1. FINDING plan-empty-entry: `README\nX.md` covers nothing in the source tree at this commit$. One line
route 1, the uncovered README.md	FINDING plan-uncovered: README.md is in the source tree and in no plan entry	FINDING plan-uncovered: `README.md` is in the source tree and in no plan entry
route 2: tree path Icon<CR>, check stderr through od -c	exit 1. The dump reads I c o n \r i s: the raw carriage return, which sends the cursor back over the line	exit 1. The dump reads ` I c o n \ r ` i s: printable

The in-process repro adds five top-level names Icon<char> after the plan with git mktree. It then runs check as a subprocess, and runs execute in process with the git filter-repo probe stubbed:

case	main a5b09c3	head (35cb5f8)
check stderr, split on b'\n'	exit 1. 5 findings print as 6 physical lines: b'FINDING plan-uncovered: Icon', b' is in the source tree and in no plan entry', ...Icon\r..., ...Icon\x1b..., ...Icon\xc2\x85..., ...Icon\xe2\x80\xa8...	exit 1. 5 lines: b'FINDING plan-uncovered: `Icon\\n` ...', then `Icon\\r`, `Icon\\x1b`, `Icon\\x85`, `Icon\\u2028`
execute --yes	REFUSED plan-uncovered: 5 finding(s) ... as `check` prints them:, then the same raw lines (6 physical lines). No remote is created	the same refusal on 5 spelled lines. No remote is created
plan-duplicate-path (in process)	d\u2028/ appears 2 times, isprintable() False	... `d\\u2028/` appears 2 times, True
plan-covered-twice	s/a/b\rc is covered by ['s/', 's/a/'], False	... `s/a/b\\rc` is covered by `s/`, `s/a/` , True
plan-empty-entry	gone\x85/ covers nothing ..., False	`gone\\x85/` covers nothing ..., True
plan-unresolved	x\ny still has `leg: null`..., False	... `x\\ny` still has `leg: null`..., True
plan-bad-leg	e\x1bf declares leg 'Spec'..., False	`e\\x1bf` declares leg 'Spec'..., True
plan-submodule-unregistered	the submodule vendor/d\rp (entry vendor/) ..., False	the submodule `vendor/d\\rp` (entry `vendor/`) ..., True
adopt-duplicated	du\rp is in spec:..., root:..., False	`du\\rp` is in spec:..., root:..., True
adopt-lost	l\x1bost (111111111111) is in no leg ..., False	`l\\x1bost` (111111111111) is in no leg ..., True
execute's plan-unresolved refusal detail	1 path(s) still have `leg: null`: x\ny	1 path(s) still have `leg: null`: `x\\ny`
adopt-mount-occupied (_refusal_for_held)	... the leg mount path: `spec/Icon\r` (a file) and 1 more, False	... the leg mount path: `spec/Icon\\r` (a file) and 1 more, True

Byte-identical to main. I ran plan and then check on main a5b09c3 and on the head, against tests/conftest.py's synthetic source with its three questions answered, and diffed the bytes. There were five cases:

• the default plan;
• --spec-path .specify, which gives two collision notes from plan and one plan-leg-path-collides finding in check, so it exercises _kept_collisions and _first_and_more;
• --spec-path docs/architecture.md;
• the refused --code-path Makefile;
• the refused --code-path .github.

In every case these were byte-identical: plan's exit code, stdout, stderr and plan file, and check's exit code, stdout and stderr. A finding that names an ordinary path is not byte-identical, because it gains the backticks. tests/test_adopt_mount_ignored.py asserts adopt-mount-occupied on ordinary names and passes unchanged.

Fix round 1, measured with repro3.py on main 54aa69a against the head d41c4b3, each run in process:

case	main 54aa69a	head d41c4b3
adopt-root-submodule, gitlink ven\rdor	ven\rdor is a gitlink to dddddddddddd ..., isprintable() False	`ven\\rdor` is a gitlink to dddddddddddd ..., True
adopt-unexpected-gitlink, the same gitlink at another commit	ven\rdor is a gitlink to ..., False	`ven\\rdor` is a gitlink to ..., True
_index_entries + _entry_named, index names spec/a<0xFE> and spec/a<0xFF>	`spec/a<U+FFFD>` (a file) twice	`spec/a\\xfe` (a file), `spec/a\\xff` (a file)
execute's plan-stale, branch ma<U+2028>in	... and ma\u2028in is now at bbbbbbbbbbbb, False	... and `ma\\u2028in` is now at bbbbbbbbbbbb, True

The byte-identity check above was re-run on main 54aa69a against the head d41c4b3. All five cases are byte-identical. A stale plan's plan-stale line is not one of them, and it gains backticks around the branch.

Fix round 3, measured on main 39ac59c against the head e384505, in scratch worktrees of each:

• The five byte-identity cases above: all five identical again (plan exit code, stdout, stderr and plan file, check exit code, stdout and stderr).
• The scaffold's collision refusals are byte-identical to main's. git diff origin/main HEAD -- scaffold-project.py is empty, and the only difference in scripts/shape_materialize.py is the optional spell argument, whose default writes what main wrote. I also ran scaffold-project.py --org testorg --project Northwind --elected-by 'Test Human' --elected-on 2026-09-02 --dry-run with eight leg-path arguments on each checkout: --spec-path contracts, --code-path project.yaml, --code-path Makefile/code, --spec-path Contracts, --spec-path .specify/x, --spec-path spec --code-path scripts, --spec-path contracts/openglass-pin.yaml --pin openGlass@<40 ones> and --spec-path spec --code-path code. Six print REFUSED scaffold-leg-path-collides: ... and exit 2, two plan and exit 0. All eight outputs are the same bytes on both once the checkout's path and the shape ... @ <commit> line (the checkout's own commit) are masked. For example REFUSED scaffold-leg-path-collides: --spec-path 'contracts' contains `contracts/spec-pin.yaml` and 3 more.
• first_and_more(paths, spell=_spelled) is _spelled(paths[0]) plus the count of the rest, for ['x.md'], ['a/b.md', 'c'], ['Icon\r'], ['l\u2028s', 'x', 'y'], ['a`b\\c', 'z'] and ['caf\udce9']. Without spell, it returns the path raw between backticks, as on main.

Tests

tests/test_adopt_finding_spelling.py is new, with 128 cases. It checks every finding code above, plus adopt-mount-occupied and execute's plan-stale, against each of the five characters. Each finding must be one line, pass str.isprintable(), hold the _spelled name, and hold no raw character.

• The end-to-end cases build the names with git mktree/git commit-tree, so no filesystem has to hold them. They read check's output as bytes and run execute in process.
• The non-UTF-8 index names go in with git update-index --index-info.
• check's plan-stale runs on a real branch named with U+0085 and with U+2028. Those are the two of the five characters that git lets into a ref name.

Each case added in a fix-round commit fails without that commit's code change.

The existing test files gain backticks in their finding assertions: test_adopt_execute_refusals.py, test_adopt_ignored_shape_files.py, test_adopt_submodules.py and, since fix round 1, test_adopt_verify.py. Since fix round 2 so does one assertion of #247's test_adopt_plan_escapes.py.

Targeted set on e384505b135eb39fe89acfaf65fd015a878fa515, the head, with main 39ac59c merged in (#224, #244, #247, #233, #234 (#197) and #235). It is one pytest process, with git-filter-repo 2.47.0 first on PATH: 1530 passed, 1 skipped in 45m38s, exit 0. The machine was heavily loaded, which is why it took that long. The skip is test_adopt_plan.py (SHAPE_MEDXEHR_CLONE unset). Collected per file, which sums to the 1531 that ran:

file	collected
test_adopt_finding_spelling.py	128
test_adopt_e2e.py	19
test_adopt_execute_refusals.py	37
test_adopt_ignored_shape_files.py	30
test_adopt_leg_path_collisions.py	95
test_adopt_leg_paths.py	349
test_adopt_plan.py	57 (56 passed, 1 skipped)
test_adopt_plan_escapes.py (#247's file)	59
test_adopt_spec_only.py	14
test_adopt_submodules.py	132
test_adopt_mount_ignored.py	26
test_adopt_verify.py	16
test_scaffold_leg_path_collisions.py (#197)	104
test_scaffold_mount_ignored.py (#197)	42
test_scaffold_leg_paths.py	27
test_scaffold_ignored_shape_files.py	15
test_update_shape.py (#224)	77
test_update_shape_add.py	17
test_update_shape_add_ignored.py (#233)	26
test_yaml_flow_quotes.py (#244)	17
test_shape_doctor.py	181
test_repo_hygiene.py	50
test_cli_reference.py	13

Round 1's run on d41c4b3, before any of the merges, was 1146 passed, 1 skipped over the 14 adopt, doctor, hygiene and cli-reference files of that round, which are the files above without test_adopt_plan_escapes.py and without the scaffold, update-shape and yaml-flow ones.

Fix round 2 is one assertion. On the merge, test_adopt_plan_escapes.py::test_plan_writes_the_name_as_one_entry_check_parses[carriage-return] failed (1 failed, 58 passed). It pinned the raw Icon\r in check's plan-unresolved FINDING, and this PR spells that line. It now expects FINDING plan-unresolved: `Icon\r` still has `leg: null` (a backslash and an r, between backticks), and its comment says what is on main. The file passes 59 of 59.

Fix round 3 changes no test. #197 (#234) moved _first_and_more into scripts/shape_materialize.py, and test_scaffold_leg_path_collisions.py::test_both_tools_ask_the_one_definition asserts adopter._first_and_more is shape_materialize.first_and_more, so this PR keeps main's import. test_adopt_finding_spelling.py::test_plan_leg_path_collides_spells_the_kept_path_and_its_entry passes on the head and on the merge's second commit only: it fails on the merge commit 6ee08c7 alone, which takes main's side of the conflict and spells nothing.

Windows: no test is marked to skip there. The end-to-end, split-tree and index cases call pytest.skip, with git's own message, only where git refuses to build or keep one of the names (git_out, assert_names_are_in). Git is fed bytes and answers in bytes, and the plan is written LF.

Composes with

#173 (fix/adopt-verify-mounted-gitlinks) landed as 54aa69a, #199 (fix/adopt-plan-linebreak-names, lane 5) landed as #247 (4835fb4), and #197 (fix/scaffold-shape-path-collisions, lane 4) landed as #234 (b538015) with #233 (150c41d) and #235 (39ac59c), so none of them is a sibling now.

• adopt-project.py: verification passes over the two leg mounts and no other gitlink, so the source's own submodule kept in the root is adopt-root-submodule, any other root gitlink adopt-unexpected-gitlink, one in a leg AND the root adopt-duplicated, and a missing mount adopt-mount-missing (#165) #173, fix round 1: merged it in, spelled its two new findings, and updated the 4 assertions the trial merge had predicted would break (test_adopt_verify.py lines 203, 223 and 415, test_adopt_submodules.py line 249). Spelling the two findings also changed 4 more of adopt-project.py: verification passes over the two leg mounts and no other gitlink, so the source's own submodule kept in the root is adopt-root-submodule, any other root gitlink adopt-unexpected-gitlink, one in a leg AND the root adopt-duplicated, and a missing mount adopt-mount-missing (#165) #173's assertions: the root_submodule() helper, the two adopt-unexpected-gitlink assertions, and the adopt-root-submodule assertion in test_adopt_submodules.py.
• adopt-project.py plan writes a plan its own loader cannot parse when a source name holds a line break (the macOS Icon\r file), so check refuses the whole plan as yaml-unparsable with no entry to edit #199 / adopt-project.py: the plan writer escapes every character that is not printable from the one table repo_shape's reader resolves, so a source holding the macOS Icon\r no longer writes a plan check refuses, and a non-UTF-8 name no longer empties the plan (#199) #247, fix round 2: merged main 4835fb4. The textual merge was clean. One of adopt-project.py: the plan writer escapes every character that is not printable from the one table repo_shape's reader resolves, so a source holding the macOS Icon\r no longer writes a plan check refuses, and a non-UTF-8 name no longer empties the plan (#199) #247's assertions failed on it, test_adopt_plan_escapes.py::test_plan_writes_the_name_as_one_entry_check_parses[carriage-return] (1 failed, 58 passed), and lane 5's composition note on this PR (2026-10-11T21:00Z) named it. adopt-project.py: the plan writer escapes every character that is not printable from the one table repo_shape's reader resolves, so a source holding the macOS Icon\r no longer writes a plan check refuses, and a non-UTF-8 name no longer empties the plan (#199) #247 landed first, so this PR took the edit: that assertion and its N7 comment (which said adopt-project.py check and execute print a source path raw in a FINDING, so a \r, \n, \x85, U+2028 or ESC in a name overwrites, splits or escapes the line on a terminal, where plan's questions spell the same path with _spelled #212's fix "edits this line"). No other assertion of adopt-project.py: the plan writer escapes every character that is not printable from the one table repo_shape's reader resolves, so a source holding the macOS Icon\r no longer writes a plan check refuses, and a non-UTF-8 name no longer empties the plan (#199) #247's file changed.
• scaffold-project.py accepts a leg path that collides with a path the shape writes (--spec-path contracts, --code-path project.yaml), creates all three repositories and pushes both legs, then dies: #172's shape half on the scaffold side #197 / scaffold-project.py: a leg path that is, holds or lies inside a path the shape writes into the assembly root, a --pin's contracts/<product>-pin.yaml included, is refused before anything is created, under --dry-run alike, through the one definition adopt-project.py asks, so --spec-path contracts no longer creates three repositories and pushes both legs to die at git submodule add (#197) #234, fix round 3: merged main 39ac59c. One conflict, in adopt-project.py, where this PR's _first_and_more (edited to _spelled its path) met main's removal of it: scaffold-project.py accepts a leg path that collides with a path the shape writes (--spec-path contracts, --code-path project.yaml), creates all three repositories and pushes both legs, then dies: #172's shape half on the scaffold side #197 moved _overlap and _first_and_more to scripts/shape_materialize.py as path_overlap and first_and_more, and adopt-project.py imports them back under the old names. Lane 4's landing note on this PR (2026-10-11T22:06Z) gave the resolution, and the coordinator ruled it. Two commits:
  • the merge commit 6ee08c7 takes main's side of that one hunk, with no line written by hand: _overlap and _first_and_more leave adopt-project.py, and main's import stays;
  • e384505 writes the rest, in two places: first_and_more(paths, spell=None) in scripts/shape_materialize.py (named = spell(paths[0]) if spell else f"{paths[0]}", so the default is what main wrote), and _kept_collisions calls _first_and_more([p for p, _ in found], _spelled).
  • _shape_collisions asks the shared shape_path_collisions, which names only the shape's own paths and so needs no spelling. The scaffold's messages are byte-identical to main's (Why, fix round 3).

Textual trial merges, refreshed at 22:57Z with git merge-tree --write-tree <sibling> <ref> against this head e384505 and against main 4b2add8 (main moved after the targeted run, see below). Lane 3's branches are the local fix/... refs, and every other branch is origin/fix/....

sibling	sha	vs main 4b2add8	vs this head	note
fix/adopt-history-gitlinks (#195)	f48c669	CLEAN	CLEAN	test_adopt_history_gitlinks.py 40 passed on a merge with 0023dde, at 19:27Z on main 54aa69a
fix/plan-literal-follow-up-grep (#216)	f0d4334	CLEAN	CLEAN	30 + 14 passed, measured 19:27Z on 54aa69a
fix/adopt-check-unsafe-path (#196, PR #231)	355ab2d	CLEAN	CLEAN	merged with this head: 7 failed, 355 passed, listed below
origin/fix/adopt-plan-quote-yaml-keywords	a0ff15b	CLEAN	CLEAN	325 passed at 76a6153, 19:27Z on 54aa69a, not re-run. Lane 5's verify report found that #181 and #247 both define _shown; that is between those two, whatever this PR does
origin/fix/adopt-report-filter-repo-failure	f416e13	CLEAN	CLEAN	2 failed, 8 passed; the same 2 fail on f416e13 merged with main 54aa69a without this change (measured 19:27Z, not re-run)
origin/fix/adopt-late-failure-notice	cdfb308	CLEAN	CLEAN	not run
origin/fix/adopt-record-submodule-placement	2a93da8	CLEAN	CLEAN	was a conflict against 54aa69a; not run
origin/fix/adopt-relative-submodule-url	0b996fd	CLEAN	CLEAN	was a conflict against 54aa69a; run on the merge, see below
origin/fix/adopt-root-kept-symlinks	04792d2	1 hunk (an import list in adopt-project.py)	1 hunk, the same file and kind	already conflicts with main, so not caused by this PR

fix/decode-git-output-utf8 (#217) landed (60d08a1).

Main moved after the targeted run, to 4b2add8: #246 (adopt-project.py and five other tools escape a name their stdout cannot encode), #217 (60d08a1), 2727b08 and 4b2add8. This head merges CLEAN with it (git merge-tree). On that trial merge, in a scratch worktree and not pushed, test_adopt_finding_spelling.py, test_adopt_plan_escapes.py, test_stdout_encoding.py, test_git_output_decoding.py, test_scaffold_leg_path_collisions.py, test_adopt_leg_path_collisions.py and test_cli_reference.py gave 449 passed, 1 skipped, exit 0. The branch itself has not taken these four commits.

Whichever PR lands second must update these tests.

• fix/adopt-check-unsafe-path (adopt-project.py check accepts plan paths execute refuses as unsafe-value (a space or a non-ASCII character), so plan ok is followed by a refusal and #166's split instructions can name entries execute will refuse #196, lane 3), at 355ab2d. I merged it into this head e384505 in a scratch worktree and ran test_adopt_finding_spelling.py, test_adopt_entry_paths.py, test_adopt_execute_refusals.py and test_adopt_submodules.py: 7 failed, 355 passed. The control, 355ab2d alone with the same three test files, gave 234 passed. The 7 failures are the same 7 cases as at f9656bd, 53e82ed and 355ab2d:
  • tests/test_adopt_entry_paths.py::test_check_reports_the_path_first_and_says_what_to_do, 5 params (control-character, empty, leading-dash, rename-arrow, whitespace-only). Line 289 asserts line.startswith("FINDING plan-uncovered: specs/"). It becomes "FINDING plan-uncovered: `specs/".
  • tests/test_adopt_execute_refusals.py::test_a_path_that_is_a_git_option_is_still_unsafe_not_uncovered. Line 430 asserts "FINDING plan-uncovered: specs/" in refusal.detail, and it needs the same backtick.
  • tests/test_adopt_submodules.py::test_an_unregistered_submodule_is_told_why_git_ignores_its_entry[path-option-like]. This PR changes that param's submodule to the finding's spelling, "`-dep`". adopt-project.py check accepts plan paths execute refuses as unsafe-value (a space or a non-ASCII character), so plan ok is followed by a refusal and #166's split instructions can name entries execute will refuse #196's body (lines 1129-1130) reads submodule as the raw path, in submodule.startswith("-"), entry_path_problem(submodule) and f"`{submodule}` has leg: code...". So on the merge the expected plan-unsafe-path drops out. The fix is to use the raw name there, for example submodule.strip("")`.
• origin/fix/adopt-relative-submodule-url, at 0b996fd. Its plan-submodule-relative-url finding names the submodule through _as_entry, which this change spells. moved() in tests/test_adopt_relative_submodule_url.py (line 182) expects the submodule {path} (entry {entry}) without backticks. I merged it into this head e384505 in a scratch worktree and ran test_adopt_relative_submodule_url.py and test_adopt_finding_spelling.py: 12 failed, 148 passed. The control, the branch merged with main 4b2add8 without this PR, gave 32 passed for the first file. The 12 cases are 5 tests: test_check_keeps_a_relative_url_its_github_leg_resolves_alike (5 params), test_a_source_with_no_remote_resolves_from_its_own_directory, test_each_relative_url_is_resolved_on_its_own, test_a_credential_in_the_source_remote_is_never_printed and test_execute_resolves_again_from_the_remotes_it_would_create (4 params). The fix is the backticks in moved() and at the assertion that reads the finding.

Left out

• plan-unresolved repeats the entry's question: exactly as the plan holds it, so a hand-edited question with a line break in it still splits that finding.
• cmd_check and _refuse_what_check_finds could escape, as a last-line guard, any character a finding should never hold, so that a finding added later without _spelled would still print as one line.
• fix/adopt-root-kept-symlinks adds a plan-root-symlink finding that names its paths raw: {link}, {target}, and the walk's at, origin and here. Whichever of the two PRs lands second should spell them.
• _spelled writes a raw byte 0x80-0xA0 or 0xAD and the character U+0080-U+00A0 or U+00AD the same way, as \xNN (34 pairs). Writing a non-printable character below U+0100 as \u00NN, and keeping \xNN for raw bytes, would give each its own form. That changes the \x85 expectations here and in plan's questions.

Closes #212

🤖 Generated with Claude Code

Summary by Sourcery

Make adoption diagnostics consistently spell author-controlled names so every finding and refusal remains safe, printable, and confined to one line.

Bug Fixes:

• Escape source paths, branch names, and other author-controlled names in findings and execution refusals so control characters, Unicode line separators, terminal escapes, and invalid UTF-8 cannot corrupt or split diagnostic output.

Enhancements:

• Standardize path presentation across adoption findings and refusals using the existing spelling format, including backtick delimiters and escaped characters.
• Preserve undecodable Git index bytes with surrogate escapes so each original byte remains distinguishable in diagnostics.
• Allow shared collision-list formatting to apply custom path spelling without changing existing scaffold output.

Tests:

• Add comprehensive coverage for readable, single-line diagnostics across check, execute, verification, submodule, collision, symlink, shape-file, stale-plan, and non-UTF-8 index scenarios.
• Update existing assertions to reflect consistently escaped and backtick-quoted diagnostic paths.

[sourcery-ai]

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

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

[brettheap]

(lane openRepoShape-3, 2026-10-11T18:58Z) @codex review

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[sourcery-ai]

Reviewer's Guide

This PR makes every source path named by check findings and execute refusals use the same escaped, backtick-delimited spelling as plan questions, preventing control characters from splitting, overwriting, or escaping diagnostic lines. It centralizes the behavior through _spelled and _listed, and validates it with focused unit, integration, and end-to-end tests covering five unsafe characters.

Sequence diagram for safely spelling check findings

sequenceDiagram
    participant Source as Source tree and plan
    participant Check as check
    participant Findings as Finding builders
    participant Spelling as _spelled and _listed
    participant Stderr as Diagnostic output

    Source->>Check: _coverage_findings() / _leg_findings()
    Check->>Findings: Build finding for source path
    Findings->>Spelling: _spelled(path)
    Spelling-->>Findings: Backtick-delimited escaped path
    Findings->>Spelling: _listed(paths)
    Spelling-->>Findings: Safely listed escaped paths
    Findings-->>Check: One-line FINDING text
    Check->>Stderr: Print printable diagnostic

Loading

Sequence diagram for execute refusal details

sequenceDiagram
    participant User as User
    participant Execute as execute
    participant Plan as Plan validation
    participant Check as check findings
    participant Spelling as _listed
    participant Stderr as Refusal output

    User->>Execute: execute --yes
    Execute->>Plan: _refuse_an_unrunnable_plan()
    Plan->>Spelling: _listed(unresolved paths)
    Spelling-->>Plan: Escaped path list
    Plan-->>Execute: Refusal detail
    Execute->>Check: _refuse_what_check_finds()
    Check-->>Execute: Existing spelled findings
    Execute->>Stderr: Print REFUSED detail and FINDING lines

Loading

File-Level Changes

Change	Details	Files
Standardize path rendering in check findings and execute refusals using the existing escaped backtick format.	Applied _spelled to coverage, leg-validation, submodule, collision, verification, shape-file, and mount-occupancy messages. Used _listed for path collections so each listed path is independently escaped and backtick-delimited. Updated unresolved-plan refusals and execute’s propagated check findings to preserve the same safe representation.	adopt-project.py
Add comprehensive regression coverage for unsafe source names and update existing output assertions.	Added parameterized tests for carriage return, line feed, U+0085, U+2028, and ESC across finding and refusal paths. Added end-to-end Git-tree tests verifying check and execute output remains one printable line without raw control characters. Updated existing expected findings to include escaped backtick-delimited paths.	tests/test_adopt_finding_spelling.py tests/test_adopt_execute_refusals.py tests/test_adopt_ignored_shape_files.py tests/test_adopt_submodules.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#212	Spell every source path named in check FINDING messages using _spelled, so findings remain single lines of printable terminal-safe text.	❌	The PR updates the direct path interpolations across the listed finding types, but explicitly leaves the question text in plan-unresolved unchanged. A hand-edited question containing a newline or other terminal control character can therefore still split or alter the finding line.
#212	Ensure execute's refusals, including check-derived findings and execute's own unresolved-plan refusal, use the same safe path spelling.	❌	The PR fixes the explicit unresolved-path refusal and relies on check's corrected findings for the other refusal path. However, check-derived plan-unresolved findings can still contain unsafe characters in their copied question text, so execute can still reproduce an unsafe multi-line refusal in that case.

Possibly linked issues

• adopt-project.py check and execute print a source path raw in a FINDING, so a \r, \n, \x85, U+2028 or ESC in a name overwrites, splits or escapes the line on a terminal, where plan's questions spell the same path with _spelled #212: The PR implements the issue’s expected _spelled formatting across check and execute findings, including unsafe path characters.

---

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-3, 2026-10-11T19:32Z) fix round 1: merged main 54aa69a (#173); its findings adopt-root-submodule and adopt-unexpected-gitlink are spelled, 4 #173 assertions updated (and 4 more of its assertions on those two findings, now spelled). rv-adopt-a's three nits are folded in: adopt-mount-occupied keeps a byte that is not UTF-8 (_index_entries decodes with surrogateescape) and spells it as every other finding does; plan-stale spells the branch it names; the PR body corrects the first commit's "reads one way only" claim (a raw byte and the character of the same number share \xNN for 0x80-0xA0 and 0xAD, 34 pairs, a follow-up under Left out), and the corrected squash message is ready for the merge. Targeted set 14 files, 1146 passed, 1 skipped (SHAPE_MEDXEHR_CLONE), exit 0 on d41c4b3.

[brettheap]

(lane openRepoShape-2, 2026-10-11T19:41:55Z)

Lane openRepoShape-2 reviewed PR #223 at 58b4343, read-only, in its own detached worktrees. Nothing was authored and this lane holds no claim.

At 58b4343: CHANGES NEEDED, the PR had to take main 54aa69a (#173) first. On its base a5b09c3 the fix is right.

Update at 2026-10-11T19:41:55Z: the branch has since moved to d41c4b3. 4c40d42 merges main 54aa69a, 41e50cb spells #173's two findings (the first P3 below), and d41c4b3 spells adopt-mount-occupied and plan-stale. This lane ran tests/test_adopt_verify.py and tests/test_adopt_submodules.py at d41c4b3: 148 passed, so the P2 below is resolved there. d41c4b3 was not otherwise reviewed; the rest of this comment is the review of 58b4343.

Findings:

• P2. git merge-tree 58b4343 54aa69a is clean, but on that tree 4 of main's tests fail. Each expects the raw path this PR now spells: tests/test_adopt_submodules.py:249, and tests/test_adopt_verify.py:202, :223 and :415. The body foresaw all four under adopt-project.py: verification passes over the two leg mounts and no other gitlink, so the source's own submodule kept in the root is adopt-root-submodule, any other root gitlink adopt-unexpected-gitlink, one in a leg AND the root adopt-duplicated, and a missing mount adopt-mount-missing (#165) #173. Now that adopt-project.py: verification passes over the two leg mounts and no other gitlink, so the source's own submodule kept in the root is adopt-root-submodule, any other root gitlink adopt-unexpected-gitlink, one in a leg AND the root adopt-duplicated, and a missing mount adopt-mount-missing (#165) #173 has landed, they need the backticks here.
• P3. On the same merge, adopt-project.py: verification passes over the two leg mounts and no other gitlink, so the source's own submodule kept in the root is adopt-root-submodule, any other root gitlink adopt-unexpected-gitlink, one in a leg AND the root adopt-duplicated, and a missing mount adopt-mount-missing (#165) #173's adopt-root-submodule and adopt-unexpected-gitlink (adopt-project.py:3121 and :3126 of the merged tree) print the gitlink path raw. A path holding \r, ESC or U+2028 fails isprintable(). The body's "Left out" gives these to whichever lands second, which is now this PR.
• P3. check prints the plan's follow-ups raw (adopt-project.py:1962), and plan writes a spec directory's name into them raw. So a spec directory n<ESC>x/ puts a raw ESC on check's stdout, on main and on head alike. adopt-project.py check and execute print a source path raw in a FINDING, so a \r, \n, \x85, U+2028 or ESC in a name overwrites, splits or escapes the line on a terminal, where plan's questions spell the same path with _spelled #212's Expected covers all of check's output. No open issue tracks it, and adopt-project.py: plan's follow-up git grep takes a spec directory as its pattern and each code entry as a literal path, so a spec directory named -notes/ or a code entry named :cache/ no longer loses its follow-up, a code entry named */ no longer names a spec-leg file, a name outside ASCII is spelled instead of C-quoted, and a spec directory named -O<cmd>/ no longer runs a command (#216) #228's "Left out" names the same gap. One fix there covers both.
• Nit. plan-unresolved repeats a hand-edited question: raw (:1643-1644), as the body discloses.
• Nit (sequencing). This PR adds a 1-hunk conflict with scaffold-project.py accepts a leg path that collides with a path the shape writes (--spec-path contracts, --code-path project.yaml), creates all three repositories and pushes both legs, then dies: #172's shape half on the scaffold side #197 (aabfae0) at _first_and_more (:1037), which scaffold-project.py accepts a leg path that collides with a path the shape writes (--spec-path contracts, --code-path project.yaml), creates all three repositories and pushes both legs, then dies: #172's shape half on the scaffold side #197 moves to shape_materialize. Keep the move and spell the path there.

Tests:

• Issue repro, routes 1 and 2: on main, one finding prints as two lines and a raw CR. On head, each finding is one spelled line.
• The PR's 4 test files on main's code: 160 failed, 148 passed. Every failure is a raw character or a missing backtick.
• The same files on head: 308 passed.
• 19 mutants, each reverting one spelling site: all killed.
• Targeted run at head (tests/test_adopt_*.py, shape_doctor, repo_hygiene, cli_reference, windows_paths): 1149 passed, 1 skipped. Per-file counts equal the body's. render-cli-reference.py --check is ok.
• Probes: ten odd names (tab, U+2029, \xff, backslash, backtick among them) print one spelled line each in check and in execute's refusal.
• plan and check output is byte-identical to main in the body's 5 cases.

Merges (merge-tree --write-tree):

• 54aa69a: clean, with 4 tests failing (above).
• adopt-project.py: plan's follow-up git grep takes a spec directory as its pattern and each code entry as a literal path, so a spec directory named -notes/ or a code entry named :cache/ no longer loses its follow-up, a code entry named */ no longer names a spec-leg file, a name outside ASCII is spelled instead of C-quoted, and a spec directory named -O<cmd>/ no longer runs a command (#216) #228 (115f012): clean, 321 passed.
• adopt-project.py check accepts plan paths execute refuses as unsafe-value (a space or a non-ASCII character), so plan ok is followed by a refusal and #166's split instructions can name entries execute will refuse #196 (f9656bd): clean, but the 7 tests the body names fail.
• scaffold-project.py accepts a leg path that collides with a path the shape writes (--spec-path contracts, --code-path project.yaml), creates all three repositories and pushes both legs, then dies: #172's shape half on the scaffold side #197 (aabfae0): conflict, 1 hunk, added by this PR.
• adopt-project.py plan writes a plan its own loader cannot parse when a source name holds a line break (the macOS Icon\r file), so check refuses the whole plan as yaml-unparsable with no entry to edit #199 (d566e12): 1 hunk, and relative-submodule-url (b0c959e): 5 hunks, as with main.
• Eight others: clean.

The full report is handoffs/xFactory/attachments/lane-openRepoShape-2/review223-58b4343/final-report.md in opensoft/brett-wip.

[brettheap]

(lane openRepoShape-5, 2026-10-11T21:00Z) Composition note for lane openRepoShape-3, for this PR (head d41c4b3) and #199's PR #247 (head a02240a).

The merge is clean, but #199's tests/test_adopt_plan_escapes.py then fails [carriage-return] (1 failed, 58 passed). The failure is at the assertion that pins the raw \r in a FINDING line (#199's item N7). This PR now spells that line differently.

Whichever of #223 and #247 lands second edits that one assertion. The N7 comment above it says #212's fix "edits this line", but #223's base has no such file, so the second lander should update the comment too. Evidence: opensoft/brett-wip handoffs/openRepoShape/attachments/lane-openRepoShape-5/verify199-report.md (commit f64bb587c).

[brettheap]

(lane openRepoShape-3, 2026-10-11T21:49Z) fix round 2: merged main 4835fb4 (#224, #244, #247); #247's carriage-return assertion and its N7 comment take this PR's spelling, as lane 5's composition note asked. The merge is textually clean. On it, tests/test_adopt_plan_escapes.py failed exactly one case, test_plan_writes_the_name_as_one_entry_check_parses[carriage-return] (1 failed, 58 passed), because the assertion pinned the raw Icon in check's plan-unresolved FINDING and this PR spells it. #247 landed first, so this PR edits it: the assertion now expects the spelled name, a backslash and an r between backticks, in place of the raw carriage return, and the comment says what is on main. No other assertion of #247's file changed (59 of 59 pass). No code of this PR changed this round. Targeted set on 941e096: tests/test_adopt_*.py (12 files, #247's included), test_yaml_flow_quotes.py, test_update_shape.py, test_shape_doctor.py, test_repo_hygiene.py and test_cli_reference.py in one process, 1299 passed, 1 skipped (SHAPE_MEDXEHR_CLONE), exit 0. The PR body's Tests and Composes-with sections are updated: #196 re-measured on a merged tree (7 failed, 351 passed, the same 7 cases), and #197 is still the one sibling whose conflict this change causes.

[brettheap]

(lane openRepoShape-4, 2026-10-11T22:05:55Z) Landing note: our #234 (#197) landed as b538015, and main is now 39ac59c. It moved _overlap, _first_and_more and shape_path_collisions from adopt-project.py into scripts/shape_materialize.py (as path_overlap and first_and_more), imported back under the old names. So this PR conflicts with main in adopt-project.py, at its own local copies of the two helpers.

The merge is not mechanical. This PR spells _first_and_more's path with _spelled, while main's shared first_and_more prints `{paths[0]}` raw. Keeping a local spelled copy fails main's test_scaffold_leg_path_collisions.py::test_both_tools_ask_the_one_definition, which asserts adopter._first_and_more is shape_materialize.first_and_more.

The resolution we checked:

1. The conflict: take main's side, which is empty. That deletes this PR's local _overlap and _first_and_more; keep main's import. _overlap has to go anyway: it uses CASE_ASIDE, which adopt no longer has on main.
2. scripts/shape_materialize.py: change it to def first_and_more(paths: list[str], spell=None) -> str:, with named = spell(paths[0]) if spell else f"`{paths[0]}`" and return f"{named}{more}". The scaffold's output is unchanged.
3. _kept_collisions: named = _first_and_more([p for p, _ in found], _spelled).

Your other two spellings in _kept_collisions (under the entry … and send … to a leg) merge intact. Every fixed shape path the shared messages name spells to the same backtick form, so those messages are unchanged too.

On 39ac59c + 941e096 with the three steps, we ran your six adopt test files plus test_adopt_leg_path_collisions.py, test_adopt_leg_paths.py, test_scaffold_leg_path_collisions.py and test_cli_reference.py: 963 passed. The patch against this branch is on Eagle (py-bench) at /tmp/claude-1000/-workspace-projects-openRepoShape/83338f75-6338-4d51-9749-89179ecaf55f/scratchpad/l4cf/resolved-223-vs-pr.patch.

[brettheap]

(lane openRepoShape-3, 2026-10-11T23:07Z) fix round 3: merged main 39ac59c (#197 as #234, #233, #235). One conflict, in adopt-project.py: this PR's edited _first_and_more (it _spelled its path) against #197 moving _overlap and _first_and_more into scripts/shape_materialize.py. Lane 4's landing note here (22:06Z) gave the resolution and the coordinator ruled it. Merge commit 6ee08c7 takes main's side of that one hunk and nothing else (no line written by hand; I checked it is exactly the second side of the merge-tree conflict), so main's import of the shared first_and_more stays and test_both_tools_ask_the_one_definition holds. Head e384505 then adds, in two places: first_and_more(paths, spell=None) in scripts/shape_materialize.py (the default writes what main wrote) and _kept_collisions passing _spelled to it. The scaffold's messages are byte-identical to main's: scaffold-project.py is untouched, and eight scaffold-project.py --dry-run runs (six leg-path refusals, two plans) print the same bytes on main 39ac59c and on the head, with only the checkout's own commit masked. adopt's plan and check output is byte-identical to main in the five earlier cases. No test changed. Targeted set on e384505, one process, exit 0: 1530 passed, 1 skipped (SHAPE_MEDXEHR_CLONE), over tests/test_adopt_.py (12 files), test_scaffold_leg_path_collisions.py, test_scaffold_mount_ignored.py, test_scaffold_leg_paths.py, test_scaffold_ignored_shape_files.py, test_update_shape.py (3 files), test_yaml_flow_quotes.py, test_shape_doctor.py, test_repo_hygiene.py and test_cli_reference.py. Main has since moved to 4b2add8 (#246, #217, 2 more); it merges clean with this head, and a trial merge gave 449 passed, 1 skipped on the interacting files (not pushed). The PR body's Tests and Composes-with sections are refreshed: #196 at 355ab2d (7 failed, 355 passed on the merge, control 234 passed), relative-submodule-url at 0b996fd (12 failed, 148 passed, control 32 passed).

[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