[brettheap]

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

Fix round 3 (b52e8d1), on main 5751460, merged in as b34b738. #223 has landed, so this branch takes it with main. The seven assertions its spelling of finding paths changed now use that spelling. No code changed in round 3. Round 2 (355ab2d) was verified ready. That round refuses a byte that is not UTF-8 as policy, now that #247 put #199's byte-exact path listing on main, and refuses any other surrogate because the path list cannot be written with it. It also tells a name of carriage returns alone that its line would be literal: alone, which matches every path. The refused set is unchanged since round 1. At merge, use the squash message in the last section; the first pushed subject still says "admits every path git can take literally", which round 1 made untrue.

What

• One test, entry_path_problem(path), asked by check and by execute. It is _misread(path) or _refused_by_policy(path), so a name with a reason of each kind is told the misreading.
  • check reports what it finds as a new finding, plan-unsafe-path: FINDING plan-unsafe-path: `<path>` has leg: <leg>, and `execute` will not extract it into a leg: <reason>.
  • The finding is listed FIRST in _entry_findings, so a path that is a git option is refused as that, not only as the uncovered file it also leaves. Its remediation is printed once.
  • execute refuses the same finding in check's words, through _refuse_what_check_finds, before any leg repository exists.
  • An entry answered root or drop is not judged, because it never becomes a line of the filter's path list.
• _misread: what git, git filter-repo or this tool's own write of the path list would not carry as it stands. Each was measured with git-filter-repo 2.47.0, whose get_paths_from_file strips \r and \n from each line's end and looks for ==> first:
  • an empty path: a literal: line alone kept every path in the leg;
  • a line feed anywhere: the rest of the name is read as a line of its own;
  • a carriage return at the END: it is stripped, so Icon\r (the macOS folder-icon file) extracted Icon, another file. A name of carriage returns alone leaves literal: alone, which kept every path;
  • a NUL, which no command line carries;
  • a surrogate outside U+DC80 to U+DCFF, such as a hand-edited \ud800. No source path holds one, because Source.tree reads a byte that is not UTF-8 as one of U+DC80 to U+DCFF. write_paths_listing cannot write one: it raised UnicodeEncodeError;
  • ==>, which filter-repo reads as a rename anywhere on a line.
• _refused_by_policy: names git and git filter-repo take literally, refused anyway. Each finding says "which execute refuses as policy, though git and git filter-repo would take it literally":
  • a name that is nothing but whitespace;
  • a control character (C0, DEL, C1), or U+2028 or U+2029, including a carriage return that does not end the name;
  • a byte that is not UTF-8, which Source.tree keeps as one of U+DC80 to U+DCFF (NOT_UTF8_BYTES). Since 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, write_paths_listing writes it as that byte. It is held until adopting such a name end to end is measured on macOS and Windows (Left out);
  • a leading -, the threat model's first rule.
• Everything else a source tree holds is now extracted: spaces, letters outside ASCII, #, $, (, ;, &, quotes, [, *, ?, a leading :, a leading or trailing space, a backslash, and the spellings glob:, regex: and literal:.
• _leg_paths now only collects the paths and no longer runs checked_value on them. The values that are options stay under checked_value as unsafe-value: a leg's mount path, the branch, the repository names and the organisation.
• _extract_leg writes each --paths-from-file line as literal:<path>, through 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 byte-exact write_paths_listing. Written bare, #notes.md is a comment and glob:/regex:/literal: are directives.
• _mount_the_legs runs git --literal-pathspecs rm -r -q -- <path>. Even after --, git reads a path as a pathspec: [ID].tsx also matches D.tsx, and :!keep.md matches every path except keep.md.
• shape_materialize.env_commit passes every commit message to git commit -F - as UTF-8 (encoding="utf-8", errors="replace").
  • The adoption's split message names every entry path.
  • The change also reaches scaffold-project.py's assembly commit, scripts/family.py's holder commit, and the first commit git_init_commit makes in a scaffolded or seeded leg.
  • errors="replace" also applies when encoding. A root or drop entry holding a byte that is not UTF-8 is listed in the split message with a ? in place of that byte (measured: caf?.md). On main, execute refuses that root entry as unsafe-value instead, because main's _leg_paths judges every entry.
• The module docstring's check paragraph names the entry-path test (lane 2's N4).

Why

Measured on this machine with git 2.43.0, git-filter-repo 2.47.0 and Python 3.12.3, on main 4835fb4 and the head 355ab2d, at 21:43Z. Each source was built in git's index, then planned. Every unanswered entry was answered root, then check and execute were run with --local-remote-dir.

source holds	main check	main execute	head check	head execute
My Notes.md, docs/User Guide.md, Übersicht.md (the issue)	0 plan ok	2 REFUSED unsafe-value: a plan path is 'My Notes.md', no leg	0 plan ok	0 adoption verified; all three in the spec leg
#notes.md	0 plan ok	2 REFUSED unsafe-value, no leg	0 plan ok	0 adoption verified; in the spec leg
[ID].tsx (code) beside D.tsx (root)	0 plan ok	2 REFUSED unsafe-value, no leg	0 plan ok	0 adoption verified; [ID].tsx in the code leg, D.tsx still in the root
-notes.md	0 plan ok	2 REFUSED unsafe-value, no leg	1 FINDING plan-unsafe-path: ... it begins with -, which execute refuses as policy, though git and git filter-repo would take it literally ...	2 REFUSED plan-unsafe-path, no leg
notes\t.md	0 plan ok	2 REFUSED unsafe-value, no leg	1 FINDING plan-unsafe-path: ... it holds the control character \t, which execute refuses as policy ...	2 REFUSED plan-unsafe-path, no leg
a==>b.md	0 plan ok	2 REFUSED unsafe-value, no leg	1 FINDING plan-unsafe-path: ... it holds ==>, which git filter-repo --paths-from-file reads as a rename ...	2 REFUSED plan-unsafe-path, no leg
caf\xe9.md (byte 0xE9)	0 plan ok	2 REFUSED unsafe-value, no leg	1 FINDING plan-unsafe-path: ... it holds \xe9, which is not UTF-8 and which execute refuses as policy, though git and git filter-repo would take it literally ...	2 REFUSED plan-unsafe-path, no leg

The last row, before and after #247. Earlier, on this branch merged with #199's first head (d566e12) and with only the Cs branch disabled, check said plan ok. Then execute exited 1 with a UnicodeEncodeError in _extract_leg, after both leg remotes were created. With #247's write_paths_listing on main, the same source on 53e82ed with the refusal disabled gives check 0 plan ok and execute 0 adoption verified. The spec leg holds the byte 0xE9, and the split commit's message lists the file as caf?.md. So round 2 refuses it as policy, not as a misreading (Decision).

Measurements behind the two kinds:

• Misread. git filter-repo --paths-from-file was run with one literal:<name> line per name:
  • literal: alone kept every path;
  • literal:\r and literal:\r\r kept every path (round 2);
  • docs\nregex:.* kept every path, with or without literal:;
  • literal:Icon\r kept Icon, a different file;
  • literal:a==>b.md alone kept every path, and beside literal:keep.md it kept only keep.md.
  • Separately, git --literal-pathspecs rm -- "" exits 128, and subprocess raises ValueError on a NUL in argv.
  • On 53e82ed, write_paths_listing raises UnicodeEncodeError on \ud800, \udc7f and \udd00, and writes \udce9 as the byte 0xE9. With the Cs refusal disabled there, a hand-edited entry "\ud800.md" is refused anyway, as plan-empty-entry, before any leg.
• Policy. Each sample was filtered with one literal:<name> line, and removed in a fresh clone with git --literal-pathspecs rm -r -q -- <name>. The samples were a tab, \x01, ESC, DEL, \x85, \x0b, \x0c, \x1c, U+2028, a\rb.md, -n.md, one space and three spaces. Every one exited 0, and filter-repo kept, and git rm removed, exactly that file and nothing else. This is the independent review's measurement, repeated here. A byte that is not UTF-8 was measured end to end on Linux, as above.
• The refused set is unchanged. Round 1: the old and new entry_path_problem agree on is None for all of 200,001 random names, drawn from an alphabet of every boundary character. Round 2: 53c529c and 355ab2d refuse the same names, byte for byte, of 5,679,428. Those are every code point alone, after a, before a and between a and b, plus every sequence of 1 to 4 of 33 boundary tokens. Each head refuses 1,181,465 of them.
• env_commit. A message holding 文書.md and Übersicht.md was committed under LC_ALL=C PYTHONUTF8=0 PYTHONCOERCECLOCALE=0. On main it exits 1 with UnicodeEncodeError: 'ascii' codec can't encode characters. On the head it exits 0, and the commit body is UTF-8 bytes.
• Unchanged (round 1, on a5b09c3 and 53c529c). Three sources hold no refused name: the issue's, #notes.md and [ID].tsx. For each:
  • the plan file and plan's stderr are byte-identical (cmp);
  • plan's stdout differs only in the --out path it prints;
  • on the same answered plan, check's stdout and stderr are byte-identical.

Decision

The lane's decision, which the issue asked for with evidence: accept what a source tree holds. Refuse what git or git filter-repo would misread, or what this tool cannot write into the path list. Refuse as policy a control character, a byte that is not UTF-8, a leading - and a name that is nothing but whitespace.

• An entry's path is a fact of the source, not an option. plan writes it from the tree, and every command is argv with shell=False. In execute, an entry's path reaches git in only two places: a line of the filter's listing, and a pathspec after --. Both are now spelled so that git reads them literally, with literal: and --literal-pathspecs.
• The issue's other option was to state the restriction in the question. That would leave a top-level My Notes.md with one remedy only, renaming it in the source, for a name git handles fine.
• The policy refusals are kept, and named as policy. The review measured, and the table above repeats, that git and filter-repo take a tab, a control character, a leading - and a blank name literally. They stay refused because an adoption tool refusing conservatively is the safer default:
  • A name holding a control character is almost never meant.
  • Printed as it stands, it cannot be seen for what it is: git log prints ESC and \x01 in a commit message raw, measured.
  • A leading - is the threat model's first rule for any value this tool hands git.
  • A blank name shows as nothing wherever it is printed.
  • The refusal costs a rename, or a root or drop answer, and no adoption.
  • Each finding now says it is policy and gives no misreading's reason. Narrowing the set instead would need every downstream reader of a leg's paths (the plan YAML, _spelled, git submodule add, the doctor) measured for each character. That is not done here.
• A byte that is not UTF-8 is refused as policy (the coordinator's ruling on round 2). Lane 5's review of 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 (finding S2) handed this case to this fix. Before 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, the path list was written as strict UTF-8, and execute crashed after both leg remotes existed. 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 write_paths_listing now writes the byte, and on Linux such a source is extracted and verified with the refusal disabled. It is still held, for three reasons:
  • a name that holds one prints as an escape, never as itself;
  • the split commit's message lists it with a ?;
  • nobody has measured adopting it on macOS or Windows, where the clone _extract_leg makes must check the name out.
  • Adopting such a name end to end is the follow-up in Left out.
• A surrogate no byte is read as stays a misreading. Only a hand edit puts one in a plan, it names no source path, and write_paths_listing cannot write it.

Tests

The targeted set was run with git-filter-repo 2.47.0 on PATH, on the fix-round-3 head b52e8d1, which holds main 5751460. Earlier rounds ran it on 355ab2d and 53c529c, and on f9656bd and 5a8df76, which share one tree.

The files are test_adopt_entry_paths, test_adopt_e2e, test_adopt_execute_refusals, test_adopt_ignored_shape_files, test_adopt_leg_path_collisions, test_adopt_leg_paths, test_adopt_plan, test_adopt_spec_only, test_adopt_submodules, test_adopt_mount_ignored, test_repo_hygiene, test_windows_paths, test_shape_doctor and test_cli_reference. Since round 2 they also include #247's test_adopt_plan_escapes and #173's test_adopt_verify, and on b52e8d1 #223's test_adopt_finding_spelling, #234's test_scaffold_leg_path_collisions, #230's test_git_output_decoding and #246's test_stdout_encoding, all of which came with merges of main. test_adopt_mount_ignored is #200's: it tests _mount_the_legs, where this branch's git --literal-pathspecs rm sits beside #200's mount changes. The skips are test_adopt_plan.py::test_plan_on_medxehr_matches_the_rulings, which needs SHAPE_MEDXEHR_CLONE, and on b52e8d1 one case of test_stdout_encoding.py that is about Windows' own default.

b52e8d1: 1472 passed, 2 skipped in 734.97s (0:12:14)   (20 files)
355ab2d: 1180 passed, 1 skipped in 622.75s (0:10:22)   (16 files)
53c529c: 1100 passed, 1 skipped in 940.08s (0:15:40)   (14 files)
f9656bd: 1095 passed, 1 skipped in 433.90s (0:07:13)
5a8df76: 1095 passed, 1 skipped in 928.71s (0:15:28)

• tests/test_adopt_entry_paths.py (new):
  • the admitted names;
  • the refused names, as MISREAD and POLICY, each asserting its kind's words. The policy test also asserts that no misreading's words appear ("line of its own", "ends its line", "strips", "matches every path", "rename"). Round 2 moves the bytes that are not UTF-8 (\udce9, \udcff, \udc80) to POLICY. It keeps \ud800 in MISREAD, adds \udc7f and \udd00 at the bounds, and adds \r and \r\r with the words "literal: alone, which matches every path";
  • check and execute on each hand-edit class (empty, whitespace-only, leading -, control character, ==>);
  • a control character in the source;
  • a byte that is not UTF-8, put straight into git's index. check names it first, with the policy reason, and execute refuses it before any leg exists;
  • root and drop entries not judged;
  • the split message under a foreign locale;
  • an end-to-end adoption of every admitted kind of name, ending in adoption verified.
• Existing tests: the assertions in test_adopt_execute_refusals.py, test_adopt_e2e.py and test_adopt_submodules.py that expected unsafe-value for an entry path now expect plan-unsafe-path. Round 3 moves seven of them to adopt-project.py: check and execute spell every path a FINDING or a refusal names as plan's questions spell it, so a source name holding a carriage return, a line feed, U+0085, U+2028 or an ESC no longer overwrites, splits or escapes the line it is printed on (#212) #223's spelling of finding paths (Composes with). The docstring 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 test_a_leg_extracts_a_path_that_is_not_utf8 now names plan-unsafe-path in place of SAFE_ARG_RE.
• Mutations of test_adopt_entry_paths.py, end-to-end test aside:

mutation	head	tests that fail
no policy refusal of a byte that is not UTF-8	355ab2d	4
no misreading of any other surrogate	355ab2d	3
a name of carriage returns alone told the old "blank" words	355ab2d	2
a policy refusal given the old line-break reason	53c529c	7
no trailing-carriage-return rule	53c529c	2
no policy half at all	53c529c	20
policy asked before the misreading	53c529c	7

The review measured mutations of the mechanism on f9656bd. Dropping literal: fails 1 test, and dropping --literal-pathspecs fails 1, both in the end-to-end test.

• What the Windows job skips:
  • test_adopt_entry_paths.py::test_a_source_with_such_names_is_adopted_and_verified needs git filter-repo, which that job does not install. So does all of test_adopt_e2e.py, including the changed test_a_plan_path_that_is_a_git_option_is_refused. The same refusal is asserted without filter-repo in test_adopt_execute_refusals.py, which runs everywhere.
  • test_a_control_character_in_the_source_is_found_and_refused is POSIX-only, because NTFS cannot hold a tab in a file name. The hand-edit cases of the same refusal run everywhere.
  • The end-to-end test adds the names only a POSIX disk holds (?, *, ", :, a leading or trailing space, a backslash) only where os.name != "nt". The macOS job runs them.
  • The non-UTF-8 test builds its name in git's index, so it runs on Windows. If git there will not record the name, the test skips and says so.

Composes with

Refreshed at 23:32Z on 2026-10-11, at the shas git ls-remote --heads origin 'fix/*' printed then.

Main. This branch holds main 5751460, merged as b34b738 with no conflict. Before that, main 4835fb4 was merged as 53e82ed. Since its base a5b09c3, it has taken #173, #224, #244, #247, #234, #233, #235, #246, #230, #218, #257, #226, #219, #220, #265 and #223.

• 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 (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, lane 5). Its one hunk with this branch was _extract_leg's listing write. It is resolved as lane 5 resolved it: write_paths_listing(listing, [f"literal:{path}" for path in paths]), keeping both comments. _extract_leg is never called with an empty paths. Its one caller, _build_the_legs, calls it only for a leg not in seeded_legs(paths_for), and such a leg is seeded from templates/<role>-root/ instead. So the helper's lone \n for an empty list cannot be written. The independent reviewer of round 1 reached the same answer.
• adopt-project.py: check and execute spell every path a FINDING or a refusal names as plan's questions spell it, so a source name holding a carriage return, a line feed, U+0085, U+2028 or an ESC no longer overwrites, splits or escapes the line it is printed on (#212) #223 (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). It spells every path a FINDING names as _spelled spells it, in backticks. Merged in clean in git. Seven of this branch's test cases asserted the bare spelling, and round 3 updates them:
  • test_adopt_entry_paths.py::test_check_reports_the_path_first_and_says_what_to_do, 5 cases, and test_adopt_execute_refusals.py::test_a_path_that_is_a_git_option_is_still_unsafe_not_uncovered, now expect FINDING plan-uncovered: `specs/;
  • test_adopt_submodules.py::test_an_unregistered_submodule_is_told_why_git_ignores_its_entry[path-option-like] takes the entry's own path, -dep, from the case's orphan for startswith("-") and entry_path_problem, and names the finding by the spelled submodule.
  • adopt-project.py: check and execute spell every path a FINDING or a refusal names as plan's questions spell it, so a source name holding a carriage return, a line feed, U+0085, U+2028 or an ESC no longer overwrites, splits or escapes the line it is printed on (#212) #223's first_and_more(paths, spell=None) in scripts/shape_materialize.py composes: this branch touches only env_commit there.

git merge-tree --write-tree <sibling> b52e8d1, with every sibling at its pushed sha, and the same against main 5751460. "Clean with main" means every hunk listed is one this branch adds.

sibling	result
fix/adopt-relative-submodule-url (#190, PR #245) @ 1abe078	CONFLICT adopt-project.py, 3 hunks; clean with main. Resolution below.
fix/adopt-template-values-utf8 (#255, PR #270) @ aed9190	CONFLICT adopt-project.py, 2 hunks (_entry_findings' docstring and return); clean with main. Resolution below.
fix/adopt-plan-quote-yaml-keywords (#181) @ a0ff15b	CONFLICT adopt-project.py, 2 hunks (_entry_findings' docstring and return); clean with main
fix/adopt-root-kept-symlinks @ 04792d2	CONFLICT: main has 1 hunk in adopt-project.py (the import list) and 1 in scripts/shape_materialize.py; this branch adds 2 (_entry_findings' docstring and return)
fix/yaml-quote-boundaries @ 21fc213	CONFLICT scripts/repo_shape.py, which main has too; this branch adds none
fix/adopt-gitmodules-rejected-values (#215, PR #240) @ 0733360	CLEAN
fix/adopt-clone-without-template (PR #268) @ 65073c1	CLEAN
fix/adopt-record-submodule-placement @ 2f5cda9	CLEAN
fix/adopt-late-failure-notice @ cdfb308	CLEAN
fix/adopt-report-filter-repo-failure (#171, PR #184) @ f416e13	CLEAN
fix/leg-path-yaml-scalars (PR #266) @ aa2be9a	CLEAN
fix/plan-literal-follow-up-grep (#216, PR #228) @ f0d4334	CLEAN
fix/validator-child-encoding @ 5757e29	CLEAN

The other pushed fix/* branches touch none of this branch's files.

• _entry_findings. Four siblings conflict with this branch in _entry_findings. Whichever lands second keeps the unsafe-path findings FIRST, with their remediation in front, and adds its own after:
  • adopt-project.py keeps a source submodule's relative url = ../x unchanged in the leg, where git resolves it against the leg's remote, so execute says adoption verified and the assembly's recursive clone fails unless the dependency happens to sit beside the leg #190 (1abe078) takes local_remote_dir and returns a 3-tuple. Keep this branch's block above _entry_findings (NOT_EXTRACTED through _unsafe_path_findings, with NOT_UTF8_BYTES), then adopt-project.py: a relative .gitmodules url the plan keeps in a leg is resolved from the source's remote and from the leg's, and where the two differ check finds it and execute refuses before any leg exists, so a recursive clone no longer fails after adoption verified (#190) #245's signature. Then return (findings + submodule_findings, unsafe_remediation + remediation, notes). In _refuse_what_check_finds' docstring, keep this branch's sentence and adopt-project.py: a relative .gitmodules url the plan keeps in a leg is resolved from the source's remote and from the leg's, and where the two differ check finds it and execute refuses before any leg exists, so a recursive clone no longer fails after adoption verified (#190) #245's "BUT FROM THE REMOTES THIS RUN WOULD CREATE (adopt-project.py keeps a source submodule's relative url = ../x unchanged in the leg, where git resolves it against the leg's remote, so execute says adoption verified and the assembly's recursive clone fails unless the dependency happens to sit beside the leg #190)" paragraph. Measured on c2b5302, an earlier head of the same branch, merged with this branch at 53c529c and main e7d1720: the PR's three files plus test_adopt_relative_submodule_url.py gave 262 passed.
  • adopt-project.py: since #247 a byte that is not UTF-8 in --elected-by, --reference or the --source directory passes plan and check, and execute pushes both legs before it dies with UnicodeEncodeError in write_lf #255 (aed9190): return (findings + submodule_findings + value_findings, unsafe_remediation + remediation + value_remediation);
  • adopt-project.py plan writes null, true and other YAML keywords unquoted, so plan --spec-path null silently mounts the leg at the default spec #181: return (findings + misread + submodule_findings, unsafe_remediation + ([MANIFEST_MISREAD_REMEDIATION] if misread else []) + remediation). misread there is a local variable, unrelated to this branch's _misread function;
  • fix/adopt-root-kept-symlinks: return (findings + submodule_findings + _root_symlink_findings(plan, source, tree)), unsafe_remediation + remediation.
  • Each docstring keeps this branch's order ("each entry's path, then coverage, ...") and adds the sibling's clause.

Left out

• plan should ask entry_path_problem of each entry it writes, and ask root or drop where it refuses (lane 2's review, P3; not filed): on 53c529c a source holding -notes.md or notes\t.md is planned leg: spec with no question, and check then exits 1 with plan-unsafe-path; main had the same gap, and refused such a path only at execute.
• Adopt a source holding a name that is not UTF-8 end to end (not filed). 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 byte-exact write_paths_listing is on main, and this branch writes each literal: line through it; on Linux such a name was extracted and verified with the refusal disabled. What is left is to lift the policy refusal of NOT_UTF8_BYTES in _refused_by_policy, measure execute on macOS and Windows (where _extract_leg's clone must check the name out), and test it through to adoption verified.
• Whether to narrow the policy refusals (not filed). Admitting a tab, a control character or a blank name in a leg needs each downstream reader measured first: the plan YAML, _spelled, the doctor's placement plan, and a Windows clone.
• plan's cross_leg_references passes a spec directory's name to git grep with no -e, and passes code entries as glob pathspecs. These are the same entry paths, reaching git in plan through a door this branch does not touch. Already filed as adopt-project.py plan's cross_leg_references passes a spec directory's name to git grep -F with no -e and the code entries as glob pathspecs, so a spec directory named -notes or a code entry named :cache silently drops the follow-up, a code entry named * names files that are not in the code leg, a name outside ASCII is printed in git's quoted spelling, and a spec directory named -O<cmd> is run as git grep's pager when a tracked file holds the planned commit's hash #216 (lane 3, fix/plan-literal-follow-up-grep, PR 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, trial merge clean).
• shape_materialize.run() decoded git's output with the locale codec (scripts/shape_materialize.py run() decodes every git and gh message with the locale codec, so a push rejection or any other failure that names a non-ASCII path raises UnicodeDecodeError in place of REFUSED and the ruleset hint under a non-UTF-8 locale, after both leg remotes exist #217). That is settled on main by PR shape_materialize.run() and 26 other git and gh calls read what the child wrote as UTF-8 whatever the locale, so an adopt-project.py execute whose leg push is rejected with a message naming a non-ASCII path ends REFUSED pushing the spec leg and the ruleset hint under LC_ALL=C PYTHONUTF8=0, not a UnicodeDecodeError traceback (#217) #230, which this branch now holds.
• plan's stdout raised UnicodeEncodeError on a name outside cp1252 on Windows without UTF-8 mode (adopt-project.py plan raises UnicodeEncodeError in its terminal report, after the plan file is written, for a printable name stdout cannot encode (日本.md under cp1252, as on a redirected Windows stdout), so plan exits 1 before plan written to #214). That is settled on main by PR adopt-project.py and five other tools escape a name their stdout cannot encode, so plan on 日本.md under a cp1252 stdout (strict, or Windows' default surrogateescape) no longer exits 1 after writing the plan (#214) #246, which this branch now holds.

Squash message for the merge

The pushed commits' subjects cannot be amended, so this is the final message: subject, body and both trailers, true at b52e8d1.

adopt-project.py: `check` and `execute` judge an entry's path by one test, `entry_path_problem`, so a source holding `My Notes.md` no longer checks `plan ok` and is then refused by `execute` as `unsafe-value`, and a path `git filter-repo` would misread, or one refused as policy, is a `check` finding that says which, refused before any leg exists (#196)

On main at 4835fb4 `check` asked nothing of an entry's path, and
`execute` asked `checked_value`, whose alphabet (`SAFE_ARG_RE`) is meant
for the values that are options. A source holding `My Notes.md`,
`#notes.md` or `[ID].tsx` checked `plan ok`, and `execute` refused the
same plan as `unsafe-value`. So did #166's split instruction for a
`docs/User Guide.md` beside a `docs/theme` submodule.

DECISION: accept what a source tree holds. Refuse what git or git
filter-repo would misread, or what this tool cannot write into the path
list. Refuse as policy a control character, a byte that is not UTF-8, a
leading `-` and a name that is nothing but whitespace. An entry's path
is a fact of the source, not an option: `plan` writes it from the tree,
and every command is argv with `shell=False`. The issue's other choice
was to state the restriction in the question. That leaves a top-level
`My Notes.md` with a rename in the source as its only remedy. The policy
refusals are names git and filter-repo take literally, measured, and
each finding says it is policy. A byte that is not UTF-8 is written
byte-exact since #247, and is held until adopting such a name end to
end is measured on macOS and Windows.

WHAT CHANGED
- `entry_path_problem(path)`, ONE test, is `_misread(path) or
  _refused_by_policy(path)`, so a name with a reason of each kind is
  told the misreading.
  - `check` reports what it finds as the new finding `plan-unsafe-path`:
    "`<path>` has leg: <leg>, and `execute` will not extract it into a
    leg: <reason>".
  - It is listed FIRST in `_entry_findings`, so a path that is a `git`
    option is refused as that and not only as the uncovered file it also
    leaves. Its remediation is said once.
  - `execute` refuses the same finding in `check`'s words, through
    `_refuse_what_check_finds`, before any leg exists.
  - An entry answered `root` or `drop` is not judged: it is never a line
    of the filter's list.
- `_misread` is what git, filter-repo, or this tool's write of the path
  list would not carry as it stands. Each case is measured with
  git-filter-repo 2.47.0, whose `get_paths_from_file` strips `\r` and
  `\n` from each line's end and looks for `==>` first:
  - an empty path: a `literal:` line alone kept every path in the leg;
  - a line feed anywhere: the rest of the name is read as a line of its
    own, so `docs\nregex:.*` kept every path;
  - a carriage return at the END: it is stripped, so `Icon\r`, the macOS
    folder-icon file, extracted `Icon`, another file. A name of carriage
    returns alone leaves `literal:` alone, which kept every path;
  - a NUL, which no command line carries;
  - a surrogate outside U+DC80 to U+DCFF, such as a hand-edited
    `\ud800`: no source path holds one, and `write_paths_listing`
    raised `UnicodeEncodeError` on it;
  - `==>`, which filter-repo reads as a rename anywhere on a line.
- `_refused_by_policy` covers names git and filter-repo take literally.
  Samples of each kind were measured: a tab, `\x01`, ESC, DEL, `\x85`,
  `\x0b`, `\x0c`, `\x1c`, U+2028, a carriage return inside a name,
  `-n.md`, and one and three spaces. Each, as one `literal:` line and as
  a literal `git rm`, extracted and removed exactly that path:
  - a name that is nothing but whitespace;
  - a control character (C0, DEL, C1), or U+2028 or U+2029, a carriage
    return that does not end the name included;
  - a byte that is not UTF-8, which `Source.tree` keeps as one of
    U+DC80 to U+DCFF (`NOT_UTF8_BYTES`). With the refusal disabled, a
    source holding `caf\xe9.md` was extracted and verified on Linux,
    the byte in the leg, and the split message listed `caf?.md`;
  - a leading `-`, the threat model's first rule.
- `_leg_paths` collects the paths without `checked_value`. A leg's
  mount path, the branch, the repository names and the organisation are
  options, and stay under `checked_value` as `unsafe-value`.
- `_extract_leg` writes each `--paths-from-file` line as
  `literal:<path>`, through #247's byte-exact `write_paths_listing`.
  Written bare, `#notes.md` is a comment, and `glob:y.md`, `regex:x.md`
  and `literal:z.md` are directives.
- `_mount_the_legs` runs `git --literal-pathspecs rm -r -q -- <path>`.
  After `--` a path is still a pathspec: `[ID].tsx` also removed
  `D.tsx`, and `:!keep.md` removed every path but `keep.md`.
- `shape_materialize.env_commit` hands `git commit -F -` the message as
  UTF-8 (`encoding="utf-8", errors="replace"`).
  - The split message names every entry path. Under a cp1252 or POSIX
    `C` locale without UTF-8 mode, `文書.md` raised `UnicodeEncodeError`
    after both legs were pushed.
  - The change reaches every message `env_commit` writes:
    scaffold-project.py's assembly commit, scripts/family.py's holder
    commit, and `git_init_commit`'s first commits.
  - `errors="replace"` also applies when encoding. A `root` or `drop`
    entry holding a byte that is not UTF-8 is listed in the split
    message with a `?` in its place (`caf?.md`), where a strict encode
    would have raised.
- The module docstring's `check` paragraph names the entry-path test.

MEASURED on this machine (git 2.43.0, git-filter-repo 2.47.0). Each
source was planned, its unanswered entries answered `root`, then
`check` and `execute` were run with local remotes. Main 4835fb4
(a5b09c3 printed the same, but `plan` raised there on `caf\xe9.md`,
which is #199) -> this change:
- `My Notes.md`, `docs/User Guide.md`, `Übersicht.md`: check 0 `plan ok`,
  execute 2 `unsafe-value` -> check 0, execute 0 `adoption verified`,
  all three in the spec leg.
- `#notes.md`: check 0, execute 2 `unsafe-value` -> execute 0, in the
  spec leg.
- `[ID].tsx` (code) beside `D.tsx` (root): check 0, execute 2
  `unsafe-value` -> execute 0. `[ID].tsx` is in the code leg, and
  `D.tsx` is still in the root.
- `-notes.md`, `notes\t.md`, `caf\xe9.md` (byte 0xE9): check 0
  `plan ok`, execute 2 `unsafe-value` -> check 1 `FINDING
  plan-unsafe-path`, which says the refusal is policy; execute 2
  `REFUSED plan-unsafe-path`; no leg remote created.
- `a==>b.md`: the same exits, with the finding naming the rename
  misreading.
- Before #247, merged with #199's first head (d566e12) and without the
  rule, `caf\xe9.md` checked `plan ok`, and `execute` raised
  `UnicodeEncodeError` in `_extract_leg` after both leg remotes existed.
- The set of refused names is the same as at fix round 1, compared on
  5,679,428 names.

UNCHANGED:
- What `plan` writes and prints.
- What `check` prints for a plan none of whose entry paths it refuses
  (byte-identical to main for three sources).
- Every option value's `unsafe-value` refusal.

TESTS:
- tests/test_adopt_entry_paths.py:
  - the admitted names, and the refused ones as MISREAD and POLICY, each
    asserting its own words. A policy finding names no misreading;
  - `check` and `execute` on each hand-edit class, on a control
    character in the source, and on a byte that is not UTF-8 put
    straight into git's index;
  - `root`/`drop` not judged;
  - the split message under a foreign locale;
  - an end-to-end adoption of every admitted kind of name. It skips
    without git filter-repo, as on the Windows job.
- The assertions in test_adopt_execute_refusals.py, test_adopt_e2e.py and
  test_adopt_submodules.py that expected `unsafe-value` for an entry
  path now expect `plan-unsafe-path`, with every path a finding names
  spelled as #212's change (PR #223) spells it.

LEFT OUT:
- Adopting a name that is not UTF-8 end to end: lifting the policy
  refusal, and measuring macOS and Windows (#247's listing is on main).
- `plan` asking `entry_path_problem` of each entry it writes, and
  offering `root` or `drop` where it refuses.
- `cross_leg_references` handing entry paths to `git grep` (#216).

Lane: openreposhape-3 (openRepoShape-3)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Closes #196

🤖 Generated with Claude Code

Summary by Sourcery

Make entry paths literal-safe throughout adoption while consistently identifying and refusing paths that Git would misread or policy disallows.

New Features:

• Add unified entry-path validation so plans accept literal paths Git can safely process while reporting unsafe paths during check and execute.
• Preserve literal entry paths during extraction, removal, and commit-message creation, including paths with spaces, special characters, and non-ASCII text.

Bug Fixes:

• Prevent valid source paths from being incorrectly rejected as unsafe option values or silently misinterpreted by Git and git-filter-repo.
• Refuse path names that Git tooling would misread or that the adoption policy disallows before creating any leg repositories.
• Ensure commit messages are encoded as UTF-8 across locale settings, replacing unencodable characters instead of failing late.

Enhancements:

• Prioritize path-safety findings and provide consistent remediation guidance shared by check and execute.

Documentation:

• Update adopt-project documentation to describe entry-path validation during check.

Tests:

• Add comprehensive coverage for admitted, misread, policy-refused, edited-plan, non-UTF-8, locale, and end-to-end entry paths.
• Update existing refusal and submodule tests for the new plan-unsafe-path finding behavior.

[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-11T19:06Z) @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

The PR separates source entry paths from option-like configuration values, validates paths once through shared check/execute findings, and escapes Git’s filter-list and pathspec interpretations so legitimate names are adopted literally while unsupported paths are refused before any legs are created.

Sequence diagram for literal entry-path validation during adoption

sequenceDiagram
    participant User
    participant Check
    participant Execute
    participant Findings
    participant GitFilter as GitFilterRepo
    participant Git as Git

    User->>Check: check(plan)
    Check->>Findings: _entry_findings(plan, source)
    Findings->>Findings: entry_path_problem(path)
    alt path cannot be carried literally
        Findings-->>Check: FINDING plan-unsafe-path
        Check-->>User: finding and remediation
    else path is admissible
        Findings-->>Check: no path finding
        Check-->>User: plan ok
    end

    User->>Execute: execute(plan)
    Execute->>Findings: _refuse_what_check_finds(plan, source)
    alt plan-unsafe-path exists
        Findings-->>Execute: refuse before leg creation
        Execute-->>User: REFUSED plan-unsafe-path
    else all findings pass
        Execute->>GitFilter: _extract_leg with literal:path lines
        GitFilter-->>Execute: extracted legs
        Execute->>Git: mount with --literal-pathspecs
        Git-->>Execute: mounted assembly
        Execute-->>User: adoption verified
    end

Loading

Flow diagram for literal entry-path handling

flowchart TD
    A[Source tree entry path] --> B{Entry answered root or drop?}
    B -->|Yes| C[Do not judge path]
    B -->|No| D["entry_path_problem(path)"]
    D --> E{Git or filter list cannot carry it literally?}
    E -->|Yes| F[check reports plan-unsafe-path]
    F --> G[execute refuses before legs exist]
    E -->|No| H[_leg_paths collects raw path]
    H --> I[_extract_leg writes literal:path]
    I --> J[git filter-repo reads path literally]
    J --> K[_mount_the_legs uses --literal-pathspecs]
    K --> L[Adoption verified]

Loading

File-Level Changes

Change	Details	Files
Centralize entry-path validation and make check/execute report and enforce the same pre-extraction finding.	Add entry_path_problem for empty, whitespace-only, control/line-separator, non-UTF-8 surrogate, ==>, and leading-dash paths. Add first-class plan-unsafe-path findings with shared remediation, excluding entries answered root or drop. Remove path validation from _leg_paths so execute refuses before creating leg repositories and preserves finding precedence.	adopt-project.py
Make Git path handling literal at both extraction and mount-removal boundaries.	Prefix filter-repo path-list lines with literal:. Use git --literal-pathspecs rm when removing mounted paths.	adopt-project.py
Ensure split commit messages are sent to Git as UTF-8 across locale configurations.	Configure env_commit subprocess input/output with UTF-8 encoding and replacement errors.	scripts/shape_materialize.py
Expand regression coverage for accepted and refused source-tree paths and end-to-end adoption behavior.	Add comprehensive unit, refusal-order, non-UTF-8, foreign-locale commit, and filter-repo end-to-end tests. Update existing execute, submodule, and adoption expectations from unsafe-value to plan-unsafe-path where appropriate. Verify refused paths create no leg repositories and accepted metacharacter/directive-like names are preserved.	tests/test_adopt_entry_paths.py tests/test_adopt_e2e.py tests/test_adopt_execute_refusals.py tests/test_adopt_submodules.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#196	Make check and execute apply the same shared safety test to plan entry paths, with check reporting the path-specific finding and execute refusing it before creating any leg repositories.	✅
#196	Prevent valid source paths containing spaces or non-ASCII characters from being rejected merely because they are not in the option-safe alphabet, while refusing paths that Git or the path-list format cannot safely carry.	✅
#196	Ensure accepted paths are passed literally through extraction and assembly operations, including paths that could otherwise be interpreted as filter-repo directives, pathspec patterns, or Git options.	✅
#199	Ensure that adopt-project.py plan produces a usable result for source paths containing line breaks, either by escaping them so the generated plan round-trips through the loader or by refusing the source during planning with a clear path-specific remediation.	❌	The PR detects and refuses line-break paths only during check/execute; it does not modify y() or the plan-writing path, nor does it make plan refuse such sources. Consequently, a source containing Icon\r or \n still causes plan to write an unparsable YAML file before the new finding can run, leaving check unable to load the plan and still producing yaml-unparsable without the entry-specific finding.

---

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-2, 2026-10-11T19:09:10Z) A note ahead of this lane's read-only review of f9656bd: GitHub links #199 to this PR as an issue it closes. The PR's closing references are #196 and #199, because the body's sentence "The #199 merges resolve #199's one import conflict to #199's side" reads as the keyword resolve #199. Merging as it stands would close lane openRepoShape-5's #199, whose fix is still on fix/adopt-plan-linebreak-names. Rewording that sentence (for example "settle #199's one import conflict") drops the link and leaves Closes #196. No hold is requested.

[brettheap]

(lane openRepoShape-3, 2026-10-11T19:57Z) fix round 1 (independent review, codex is out of quota): kept the refused set (the old and new rule agree on 200,001 random names), and every plan-unsafe-path finding now gives its true reason. _misread covers what git-filter-repo or this tool's UTF-8 listing would misread: an empty path, a line feed, a carriage return at the end (Icon\r extracted Icon), a NUL, a non-UTF-8 byte, and ==>. _refused_by_policy covers names git and filter-repo take literally, and each such finding says "refuses as policy": whitespace-only names, control characters and U+2028/U+2029, and a leading -. A tab is no longer told that a line break would end its line. Also: the env_commit docstring now names scaffold-project.py, scripts/family.py and git_init_commit, and says errors="replace" encodes too. The body now has the root-kept-symlinks 04792d2 row and the squash message to use at merge. Targeted set 1100 passed, 1 skipped on 53c529c.

[brettheap]

(lane openRepoShape-2, 2026-10-11T20:09:43Z)

This lane reviewed PR #231 at f9656bd, read-only, in its own detached worktrees. It authored nothing and holds no claim. The branch has since moved to 53c529c, which this review did not cover.

MERGEABLE WITH NITS. Two things before merging:

• The body still links 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 as an issue it closes (20:04Z); fix it first.
• 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 merges cleanly in git, but 7 of this PR's assertions fail on the merge. Whichever lands second updates them.

This PR need not take main 54aa69a first.

Findings:

• P3: plan writes an answer that check refuses, and asks no question. cmd_plan (adopt-project.py:1314) never asks entry_path_problem (one caller, line 2008). A source with -notes.md gets leg: spec and nothing to answer, then check exits 1 with plan-unsafe-path. adopt-project.py: a plan that sends .gitmodules to one leg and a submodule it registers to another passes check and execute, says adoption verified, and the assembly's recursive clone then fails: plan should ask, check should find, execute should refuse #166's split question still names such entries (src/a\nb.py) without saying "root or drop". Main refused only at execute. Fix in plan or a follow-up.
• nit: adopt-project.py:1961-1967 tells a tab, ESC or DEL that "a line break would end its line". git filter-repo takes a literal: line with each of them exactly (measured), so the rule is wider than the stated decision. Not a regression; 53c529c's subject says it fixes the wording.
• nit: the body's merge table is stale now. adopt-project.py plan writes null, true and other YAML keywords unquoted, so plan --spec-path null silently mounts the leg at the default spec #181 (a0ff15b) and fix/adopt-root-kept-symlinks (04792d2) each conflict in 2 hunks, where main merges both cleanly.

What I checked by running it:

• The issue's case. On main, check says plan ok, then execute exits 2 with unsafe-value: a plan path is 'My Notes.md'. On the head, execute exits 0 with adoption verified.
• Probes. On the head, refused names answered root/drop, plus * and :!keep.md dropped, verify, and the files beside them stay in the root.

Tests:

tree	files	result
head	PR's 4 files	243 passed
main + PR's tests	PR's 4 files	60 failed, all for the right reason
head	other targeted adopt files	852 passed, 1 skipped
head	env_commit's callers (scaffold, family, trailers)	287 passed

render-cli-reference.py --check is ok. All 7 mutants of the decisive lines were killed.

Merges:

other side	result
main 54aa69a	clean; the PR's files plus test_adopt_verify.py: 260 passed
#199 d5fdc22	2 hunks (main has 1); resolve as write_paths_listing(listing, [f"literal:{path}" for path in paths])
a0ff15b, 04792d2	2 hunks each in _entry_findings; keep the unsafe findings first
b0c959e	5 hunks, as on main
#212 d41c4b3	clean
nine other heads	clean

Full report: handoffs/xFactory/attachments/lane-openRepoShape-2/review231-f9656bd/final-report.md in opensoft/brett-wip.

[brettheap]

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

There is one conflicting hunk, at the _extract_leg listing write. #199 writes filter-repo's path listing byte-exact through write_paths_listing, and this PR adds the literal: prefix. The resolution is write_paths_listing(listing, [f"literal:{path}" for path in paths]), keeping both comments, and the targeted run on it gave 156 passed.

One subtlety the second lander should check: with an empty paths list the helper writes one \n, where this PR's code writes nothing. We did not establish whether _extract_leg can be called that way. Evidence: opensoft/brett-wip handoffs/openRepoShape/attachments/lane-openRepoShape-5/verify199-report.md (commit f64bb587c).

[brettheap]

(lane openRepoShape-3, 2026-10-11T22:02Z) fix round 2 (independent review, codex is out of quota): the head is now 355ab2d. It merges main 4835fb4 as 53e82ed, which brings #247, and then makes one fix-round-2 commit. The merge's one conflict, _extract_leg's listing write, is resolved as lane 5 resolved it: write_paths_listing(listing, [f"literal:{path}" for path in paths]), keeping both comments. Lane 5's question has an answer: _extract_leg is never called with an empty paths. Its only caller, _build_the_legs, calls it only for a leg not in seeded_legs(paths_for), and such a leg is seeded from the template instead, so the lone \n cannot be written; the round-1 reviewer found the same. With #247 on main, this branch's old category-Cs reason ("written as UTF-8 text ... the write would fail after both leg repositories exist") was false. Per the coordinator's ruling, a byte that is not UTF-8 (U+DC80 to U+DCFF, NOT_UTF8_BYTES) is now refused as POLICY, in the same "though git and git filter-repo would take it literally" form. Measured on the merged tree with the refusal disabled: caf\xe9.md checks plan ok and execute says adoption verified, with the byte in the leg and caf?.md in the split message. Adopting such a name end to end, including macOS and Windows, stays the Left-out follow-up. Any other surrogate, such as a hand-edited \ud800, stays a misreading with a measured reason: write_paths_listing raises UnicodeEncodeError on it and no source path holds one. The refused set is unchanged: 53c529c and 355ab2d agree on all 5,679,428 names compared. The reviewer's nit is fixed: a name of carriage returns alone (\r, \r\r) is now told that its line would be literal: alone, which matches every path (re-measured: such a line kept the whole tree). Its test rows assert those words. Lane 2's N4 is fixed too: the module docstring's check paragraph names the entry-path test. #247's test docstring that named SAFE_ARG_RE now names plan-unsafe-path. The body no longer links #199 as an issue this PR closes; closingIssuesReferences is [196] only. "Composes with" is refreshed at today's shas, and #247 is listed as on main. Lane 2's P3 (plan writes leg: spec for -notes.md and asks nothing) is one sentence under "Left out", per the coordinator's ruling. Lane 2's nit about a tab, ESC or DEL was already settled by 53c529c. The seven assertions #223's spelling breaks are not in this round: they come with the next merge of main once #223 lands (prepared: 355ab2d + 941e096 with them updated gives 486 passed across 8 files). Main has since moved to 39ac59c and merges with 355ab2d clean. Mutations: dropping the policy refusal of bytes fails 4 tests, dropping the other-surrogate misreading fails 3, and the old carriage-return words fail 2. Targeted set on 355ab2d (the brief's 13 files plus test_adopt_mount_ignored, test_adopt_plan_escapes and test_adopt_verify): 1180 passed, 1 skipped in 622.75s; the skip is test_plan_on_medxehr_matches_the_rulings, which needs SHAPE_MEDXEHR_CLONE. The squash message in the body is updated and true at 355ab2d.

[brettheap]

(lane openRepoShape-3, 2026-10-11T23:47Z) fix round 3 (independent review, codex is out of quota): the head is now b52e8d1. With #223 landed, this branch merges main 5751460 as b34b738, with no conflict and both trailers. That merge brings #223, #226, #230, #246, #218, #219, #220, #257, #265, #234, #233 and #235. One fix-round-3 commit then moves the seven assertions #223's spelling of finding paths broke to that spelling:

• the five test_check_reports_the_path_first_and_says_what_to_do cases and test_a_path_that_is_a_git_option_is_still_unsafe_not_uncovered now expect FINDING plan-uncovered: `specs/;
• test_an_unregistered_submodule_is_told_why_git_ignores_its_entry[path-option-like] asks entry_path_problem about the raw entry path -dep, taken from the case's orphan, and names the finding by the spelled submodule.

Round 3 changes no code. #223's first_and_more(paths, spell=None) in scripts/shape_materialize.py composes, because this branch touches only env_commit there. The refused set is unchanged: 355ab2d and b52e8d1 refuse the same names out of 5,679,428 compared. Targeted set on b52e8d1 (the brief's 13 files plus test_adopt_mount_ignored, test_adopt_plan_escapes, test_adopt_verify, test_adopt_finding_spelling, test_scaffold_leg_path_collisions, test_git_output_decoding and test_stdout_encoding): 1472 passed, 2 skipped in 734.97s. The skips are test_plan_on_medxehr_matches_the_rulings, which needs SHAPE_MEDXEHR_CLONE, and one test_stdout_encoding.py case that is about Windows' own default.

I updated the body:

• "Composes with" is at the 23:32Z shas. adopt-project.py: a relative .gitmodules url the plan keeps in a leg is resolved from the source's remote and from the leg's, and where the two differ check finds it and execute refuses before any leg exists, so a recursive clone no longer fails after adoption verified (#190) #245 (1abe078), adopt-project.py: a value execute writes into a file is asked whether a file can hold it, in plan, in check and in execute before any leg exists, so a byte that is not UTF-8 in --elected-by, --reference or a local --source directory no longer pushes both legs before write_lf raises (#255) #270 (aed9190), adopt-project.py plan writes null, true and other YAML keywords unquoted, so plan --spec-path null silently mounts the leg at the default spec #181 and fix/adopt-root-kept-symlinks each conflict in _entry_findings, and a resolution is given for each.
• In "Left out", scripts/shape_materialize.py run() decodes every git and gh message with the locale codec, so a push rejection or any other failure that names a non-ASCII path raises UnicodeDecodeError in place of REFUSED and the ruleset hint under a non-UTF-8 locale, after both leg remotes exist #217 and adopt-project.py plan raises UnicodeEncodeError in its terminal report, after the plan file is written, for a printable name stdout cannot encode (日本.md under cp1252, as on a redirected Windows stdout), so plan exits 1 before plan written to #214 are now marked as settled on main.
• The squash message is true at b52e8d1, and closingIssuesReferences is [196] only.

[sonarqubecloud]

Quality Gate passed

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