[brettheap]

Lane: openreposhape-2 (openRepoShape-2)
Claim: #255 (comment)

What

execute writes some values into files as they stand. This PR asks each of them, before anything exists, whether a file can hold it. They are elected_by, elected_on, reference, visibility, each pin, each follow-up, and the assembly root's clone URL.

• The question, scripts/shape_materialize.py: unwritable_reason(value), written beside one_printable_line. It refuses:

  • a value that is not one line;
  • a lone surrogate, which is how Python keeps a byte that is not UTF-8;
  • one of the nine bidi embedding, override and isolate controls, U+202A..U+202E and U+2066..U+2069, held by code point in BIDI_CONTROLS;
  • any other control character, NUL and TAB among them.

  It returns the reason in words, ASCII and printable, or None.

• plan refuses --elected-by and --reference with REFUSED adopt-unwritable-value, exit 2, and writes no plan.

  • When --elected-by was not given, plan read the value from git config user.name, and the refusal names it --elected-by (not given, so git config user.name). That is how 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 names a value plan filled in.
  • --elected-on already had its answer: election_date refuses anything that is not a date.

• check reports each such plan value as a finding, and exits 1. For example:

  FINDING plan-unwritable-value: elected_by is 'T\udce9', which `execute` writes into the assembly root's `project.yaml` and `README.md`, and it holds a byte that is not UTF-8
  

  The last clause names the problem: a byte that is not UTF-8, a lone surrogate, a line break, a bidirectional control, or another control character.

  • The finding goes through _entry_findings. So execute refuses the same findings, in check's words, through _refuse_what_check_finds (REFUSED plan-unwritable-value). That happens before _create_leg_remotes.
  • plan's refusal is the same sentence, with the value named by its flag.

• execute refuses a local clone URL as adopt-unwritable-value, right after _repository_urls. Under --local-remote-dir, that URL is the source's own path.

  • check has no flag that tells it the path will be written.
  • Against GitHub, the clone URL is https://github.com/<org>/<name>.git.
  • So plan and check still pass a source directory whose name is not UTF-8, as 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 made them.
  • The remediation says to rename or move the source repository so that its path is one line of UTF-8 text with no control character in it, then run plan --source <its new path>, check and execute again. A clone passed to execute with --source would not do: its origin is the old path, which _remote_repository reads as UTF-8 and raises on.

• Source.open refuses a local_path that does not exist and is not text as source-unresolvable. On POSIX, a hand-edited \x00 or surrogate there reached print or subprocess and ended in a traceback.

• Source.open also refuses a --source, or a plan's local_path:, that begins with - as source-unresolvable, before gh repo clone can read it as one of gh's own options.

• check's WHAT WILL HAPPEN shows the plan's visibility, adopt branch, two leg paths and follow-ups through _shown, as a name is shown. A surrogate in one of them no longer raises on a strict stdout before the finding is printed.

Why

#247 (4835fb4) made the plan writer keep a lone surrogate as \udce9, and the reader gives it back. Three inputs then passed plan and check:

• plan --elected-by b'Jos\xe9';
• --reference b'ref-\xe9';
• a --source under a directory caf\xe9, with local remotes.

For each of them, execute created and pushed Northwind-spec.git and Northwind-code.git, then died in write_lf with UnicodeEncodeError, exit 1. Before #247, plan raised on the same input and nothing was created.

I reproduced this on 39ac59c with the lane's argv_probe.py, and the three rows matched the issue. An extended hand-edit probe found more of the same family on 39ac59c:

• A \ud800 in elected_by, elected_on, reference, visibility, a pin or a follow-up: execute raised after both legs existed. For the follow-up it raised in env_commit, writing the split commit's message to git's stdin, not in write_lf.
• A NUL in elected_by, elected_on, reference or visibility, or a CR, NEL, U+2028 or TAB in elected_by: the run said adoption verified with the raw character in project.yaml.
• local_path with \x00 or a surrogate: check and execute ended in a traceback.
• A surrogate in visibility, follow_ups, spec_path, code_path or adopt_branch: check raised while printing it.

The lane's review of this PR found one more class. A U+202E RIGHT-TO-LEFT OVERRIDE, or an isolate from U+2066..U+2069, passed plan, check and execute. This happened in --elected-by, in --reference, in a hand-edited elected_by, visibility or follow-up, and in a local source directory's name. execute then wrote the control raw into the shape README's Elected by line, which a viewer showed reversed from that point, the date and reference among it. It also wrote it into the split commit's message. Main does the same.

At this head, every one of those ends with a refusal or a finding, no traceback, and no leg remote.

Why the question is narrower than one_printable_line. It is one_printable_line less Cf, except the nine bidi controls, and it accepts the empty value.

• A Cf character other than those nine is invisible but writable. UTF-8 encodes it and the reader reads it back. A Persian name joins its parts with U+200C ZERO WIDTH NON-JOINER, which one_printable_line refuses. U+200C, U+200D, U+00AD, U+FEFF and the marks U+200E, U+200F and U+061C stay writable. A mark is one character of one direction and sets no span's.
• The nine bidi controls are refused. Each sets the direction of the text after it, so a line that holds one is shown in another order than it is written. scripts/repo_shape.py's double_quoted already spells them in the plan for that reason. Issue 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's own question, one_printable_line, refuses them.
• An empty elected_by is what plan records when git config user.name names nobody.

test_the_question_is_one_printable_line_less_cf_but_the_bidi_controls pins this over every code point. A control test shows a U+200C name still adopts.

Main since #250. Since main b30595c (#250), render writes a value between a YAML template's double quotes as double_quoted spells it. So on main, project.yaml no longer holds these characters raw. The README and the split commit's message still take each value as it stands. On main, a surrogate therefore still raises in write_lf after both legs exist, and a bidi control still reorders the README line. The against-main counts below come from 71b58a1, which includes #250.

Tests

New file tests/test_adopt_template_values.py, 78 tests:

tests	what they cover
6	the argv routes: --elected-by and --reference holding a byte that is not UTF-8, a U+2028, a TAB, a U+202E and a U+2066..U+2069 isolate
1	an elector plan read from git config user.name holding a TAB, under GIT_CONFIG_GLOBAL; skipped where a repository's own user.name answers first
2	a local source directory caf\xe9 (skipped where no such directory can exist), and one whose name begins with U+202E; each follows the refusal's remediation to adoption verified
16	one per hand-edited plan value
1	the plan and check sentences agree
3	the printed values
4	local_path
5	a --source that begins with -: plan with -u/x and with --upload-pack=x/y, check and execute on a plan whose local_path: holds each, and the stub's control
3	controls: José, a U+200C name, and a café source directory still adopt
37	unwritable_reason itself: 14 writable values, 22 unwritable ones, and every code point

• Each of the 31 route tests (argv, source directory, hand-edited value, printed value, local_path) asserts four things: the exit code, the id, that no traceback appears in any run, and that no leg remote exists afterwards.
• The elector test and the same-sentence test run only plan and check. They assert the exit codes, the id, and that no run raised.
• The four - tests put a stub gh first on PATH, which records each call. Each asserts that the stub recorded nothing, exit 2 with source-unresolvable, and no traceback; the check and execute pair also asserts that no leg remote exists. The control shows that the stub records repo clone testorg/Thing. The stub is a #! script, so on Windows the control is skipped and the four rest on the refusal's id.
• The U+200C control reads the manifest back through the reader instead of matching its line, because main since scripts/repo_shape.py _scalar takes any text that starts and ends with a quote for a quoted scalar and anything else for plain text, so an unterminated "abc reads as "abc, - "a\" reads as a\, and "a" b "c" reads as a" b "c, where PyYAML refuses each #250 spells U+200C there as an escape. It also looks for the name in the shape's README.
• Every subprocess runs under PYTHONIOENCODING=utf-8:strict.
• Every invisible character in the file is spelled as an escape. The only non-ASCII characters on any line this PR adds are é and 日本.

The new file against main 71b58a1 (copied into a detached clone): 74 failed, 4 passed, the same 74 test ids that fail on b421e6b. The 4 that pass are the three controls and the stub's control. The 74 fail as follows (the causes were read at b421e6b, where the file was last classified test by test; the failing ids are identical at 71b58a1):

• 37 with AttributeError, because unwritable_reason and BIDI_CONTROLS are new.
• 12 with a traceback. 10 are UnicodeEncodeError: the 2 argv bytes, the caf\xe9 directory, 6 hand-edited surrogates, and the local_path surrogate. The other 2 are ValueError: embedded null byte, from local_path.
• 15 with leg remotes exist. In each, the run went on past both legs. They are:
  • from plan's command line: U+2028, TAB, U+202E and the isolate;
  • the U+202E source directory;
  • hand-edited: a NUL, CR, NEL, U+2028 or TAB in elected_by, a NUL in reference, and a surrogate in a follow-up;
  • the two hand-edited overrides and the isolate follow-up.
• 4 with gh was run: the - tests. The stub recorded repo clone -u/x <work>/source-readonly/x -- --quiet, and the same for --upload-pack=x/y.
• 6 with an assertion failure:
  • plan exits 0 on the TAB elector, and on the byte in the same-sentence test;
  • the 3 printed values are printed, but not spelled with backticks;
  • the missing-byte local_path is source-unclonable.

Against be2790e the follow-up surrogate ended in a traceback; on b421e6b it leaves both legs with none. Earlier versions of this file gave 56 failed and 3 passed against 39ac59c (59 tests), and 70 failed and 3 passed against be2790e (73 tests).

Targeted runs at 72bb869, the head after main's second merge, with git-filter-repo 2.47.0. Two pytest processes ran, and both exited 0:

• test_adopt_template_values.py 78, test_adopt_root_shape_paths.py 120, test_adopt_entry_paths.py 64, test_adopt_execute_refusals.py 37, test_adopt_plan_escapes.py 59 and test_stdout_encoding.py 48: 405 passed, 1 skipped.
• test_shape_doctor.py: 242 passed, 3 skipped.
• The skips are test_stdout_encoding.py:286 (one) and test_shape_doctor.py:5330 (three), each Windows-only. Neither file changed in the merge, and the counts are those of edfa7c6, where the same runs without test_adopt_root_shape_paths.py gave 285 passed and 1 skipped, and 242 passed and 3 skipped. -rs was run on test_stdout_encoding.py only.

Fix round 1's wider runs at 3aa0e5d, before main was merged, gave 1346 passed and 1 skipped over 20 files; the skip is test_plan_on_medxehr_matches_the_rulings, which needs SHAPE_MEDXEHR_CLONE.

scripts/render-cli-reference.py --check passes; no --help text changed. git diff --check is clean.

Composes with

The branch has merged main twice. edfa7c6 took b421e6b, with #231 (6f45bf9): its two hunks with this PR were both in _entry_findings. Main's order sentence is kept with this PR's clause appended, and the return keeps unsafe_remediation first. In the same merge, this PR's pair is renamed unwritable_findings, unwritable_remediation, because #261 binds value_findings, value_remediation in the same function. 72bb869 took 71b58a1, with #313 (#262, #263) and #308: the one conflict is _entry_findings's order sentence, resolved the same way (see Main merge 2).

git merge-tree --write-tree 72bb869 <head>, run at 2026-10-12T11:04:39Z, for every open head that touches adopt-project.py, scripts/shape_materialize.py or the new test file. git ls-remote origin showed the same heads at 11:21Z. "with main" is the head merged with 71b58a1, without this PR.

head	rc	conflicting files (hunks)	rc with main (hunks)	hunks from this PR
origin/main 71b58a1	0	none (merged)	-	none
origin/main c7c02fa (#315, scripts/family.py and its tests only; landed after 71b58a1)	0	none	-	none
#261 fix/scaffold-manifest-values ab66bc0	1	adopt-project.py (2)	0	2
#181 fix/adopt-plan-quote-yaml-keywords e337f44	1	adopt-project.py (4)	1 (3)	1
#245 fix/adopt-relative-submodule-url 5d3caf3	1	adopt-project.py (3)	1 (2)	1
fix/adopt-root-kept-symlinks 6c44591	1	adopt-project.py (4)	1 (3)	1
fix/adopt-clone-without-template 06cb68e	0	none	0	none
fix/adopt-late-failure-notice 918e8f2	0	none	0	none
fix/adopt-record-submodule-placement 3e86200	0	none	0	none
fix/adopt-report-filter-repo-failure f416e13	0	none	0	none
fix/leg-path-yaml-scalars b2b42f8	0	none	0	none
fix/plan-literal-follow-up-grep c12a9cf	0	none	0	none
#316 fix/render-single-pass 9469148	0	none	0	none

#313's own head is not a row any more: it landed as 71b58a1, and its branch is gone from origin. Every hunk is mechanical, and each resolves by keeping both sides:

• adopt-project.py and scaffold-project.py accept values the new project's own validate-manifest.py refuses (a blank --elected-by or --reference, --elected-on 2026-W41-6 or 20261011 on Python 3.11+, --org test+org, a plan's visibility: secret), so adoption verified or a scaffold exit 0 is followed by a failed first bootstrap; and plan admits a 251-255-character --project that check refuses #261 (ab66bc0): the import block, where both imports stay, and _entry_findings's return. adopt-project.py and scaffold-project.py accept values the new project's own validate-manifest.py refuses (a blank --elected-by or --reference, --elected-on 2026-W41-6 or 20261011 on Python 3.11+, --org test+org, a plan's visibility: secret), so adoption verified or a scaffold exit 0 is followed by a failed first bootstrap; and plan admits a 251-255-character --project that check refuses #261's value_findings, value_remediation = _manifest_findings(plan) merges outside the hunk under its own name. So the return takes both pairs: findings + value_findings + submodule_findings + unwritable_findings, and unsafe_remediation + value_remediation + remediation + unwritable_remediation. ab66bc0 has merged c0ed615, and its earlier merge 49c21fa is now on origin. It merges cleanly with 71b58a1, so both hunks are this PR's.
• 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 (e337f44): four hunks. The first three are 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's own with main: the module docstring, _entry_findings's order sentence (both clauses stay) and its return (it keeps misread and MANIFEST_MISREAD_REMEDIATION beside this PR's pair and main's unsafe_remediation). The fourth is the ONE split commit ... mount the legs at print in _print_what_will_happen: keep 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's mounted, with _shown applied to the mount paths and the adopt branch.
• 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 (5d3caf3): three hunks. The module docstring and _entry_findings's order sentence are 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 own with main. The third is the return: keep 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 third return value, notes, as the third member, and append this PR's pair.
• root-kept-symlinks (6c44591): four hunks. The import block, where both imports stay, is this PR's. The module docstring, _entry_findings's order sentence and its return are its own with main: append _root_symlink_findings and this PR's pair.

Every clean merge above holds no top-level name twice.

Main is now c7c02fa (#315, scripts/family.py and its tests only). 72bb869 merges with it cleanly, so the branch has not taken it.

#181's plan-manifest-misread asks the same values a different question: does the project's loader read the value back as that text? As its diff is written, the line holding a surrogate should read back equal, so that check would pass it; this was read from the diff and not run. This PR's question does not catch null or true. The two answer different questions, and both should stand.

Left out

• scaffold-project.py takes --elected-by and --reference into the same templates with no such question. That twin, the bidi row included, is scaffold-project.py writes --elected-by, --reference and --name between literal double quotes with no escaping and asks none of them whether a file can hold it, so a line break leaves a project.yaml its own validators refuse, a backslash is recorded as another character (CORP\nick as CORP, a line feed, ick), and a byte that is not UTF-8 dies in write_lf after the legs are pushed #282. It is not a 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 regression, because the scaffold has no plan file.
• A hand-edited plan with no reference: and an elected_on that is not a date still meets election-date-malformed in _template_values, after both legs exist. This is pre-existing: main 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 behaves the same way. Here, only a value that no file can hold is asked about.
• A hand-edited org, tracking_branch or adopt_branch holding a surrogate still passes check as plan ok. execute refuses it as unsafe-value before any leg exists, as on main 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.
• A Latin-1 byte in git config user.name, with no --elected-by, still ends plan in a UnicodeDecodeError traceback, from _elector's strict read. So does a source whose origin URL is a path that is not UTF-8, from _remote_repository. Nothing is created, and main behaves the same.
• A hand-edited follow_ups: that is not a list still ends check and execute in a TypeError. Nothing is created at this head, where main pushed both legs first.
• A \u202e typed as six ASCII characters in a flag is read back from the plan as U+202E. That is 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's question: its manifest_misreads refuses it.
• Not run:
  • the GitHub route, where a source directory that is not UTF-8 is written nowhere;
  • Windows and macOS, which only CI covers here. The caf\xe9 test skips where no such directory can exist. The U+202E directory test should run on all three; only Linux has run it.

Review

Lane openRepoShape-2 reviewed this PR at aed9190 (#270 (comment)). Fix round 1 answers it:

• F1, bidi controls written raw: refused in plan, check, execute and the clone URL, in 7c3c020.
• F2, a raw U+202E and two composite assertions in the test file, which held the SonarCloud gate red: every invisible literal is now an escape and the assertions are split, in 7c3c020. SonarCloud closed the three issues.
• F3, a clone-URL remediation that ended in a traceback when followed: it now says to move the source and plan again, and the tests follow it to adoption verified, in 7c3c020.
• N1, stale counts and table: this body.
• N2, an elector from git config user.name refused under the name --elected-by: it is now named as 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 names a default, in 3aa0e5d.

Merging main showed that the U+200C control matched the manifest's raw line, which #250 now spells as an escape. It reads the value back instead, in 7e9cdc3.

A review by another lane is welcome; #247's reviewers know this ground. #231 and #313 have landed and are merged here. Lane openRepoShape-1's #181 and #245, #261's branch and root-kept-symlinks each meet this change in _entry_findings. The resolution is under Composes with.

Fix round 2

Lane openRepoShape-2's re-verify of 7e9cdc3 (#270 (comment)) found F1, F2, F3, N1 and N2 fixed. It asked for two more things:

• S1, a --source that begins with -. Source.open handed -u/x to gh repo clone as its first argument, and gh read it as --upstream-remote-name. This predates the PR, and main does the same, but the guard belongs in the condition this PR already edits. Such a value is now source-unresolvable before gh runs, in 8e09208. SonarCloud's S8705 raised the question. Its flagged flow is inside shape_materialize.run(), which this PR does not change.
• Take main. adopt-project.py: check and execute judge an entry's path by one test, entry_path_problem, that admits every path git can take literally, 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 cannot take is a check finding refused before any leg exists (#196) #231 had landed, and the branch conflicted with main in _entry_findings. Main b421e6b is merged in edfa7c6, and this PR's pair is renamed there so that adopt-project.py and scaffold-project.py accept values the new project's own validate-manifest.py refuses (a blank --elected-by or --reference, --elected-on 2026-W41-6 or 20261011 on Python 3.11+, --org test+org, a plan's visibility: secret), so adoption verified or a scaffold exit 0 is followed by a failed first bootstrap; and plan admits a 251-255-character --project that check refuses #261's pair cannot overwrite it.

Main merge 2

Main moved to 71b58a1 (#313, lane 5's check finds a kept root path where the shape writes) while this PR waited, and one docstring conflicted in _entry_findings, so 72bb869 merges it: #313's order sentence is kept and this PR's clause appended, and the return, the code and the tests merge as they stand.

Closes #255

🤖 Generated with Claude Code

Summary by Sourcery

Reject values that adoption cannot safely write before creating or pushing any leg repositories.

New Features:

• Validate all plan and local-source values that are written to files or commit messages before adoption proceeds.
• Report unwritable plan values consistently in plan, check, and execute, including actionable remediation for local clone paths.
• Reject invalid source paths before invoking GitHub CLI and safely display problematic values during checks.

Bug Fixes:

• Prevent malformed UTF-8, control characters, line breaks, and bidirectional controls from causing tracebacks, corrupting output, or creating leg remotes before failure.
• Prevent source paths beginning with command-line options from being interpreted as GitHub CLI arguments.

Enhancements:

• Add a shared unwritable-value validator covering UTF-8 text, line structure, control characters, and bidi controls while preserving valid formatting characters.
• Expand adoption coverage with comprehensive tests for invalid plan values, source paths, output rendering, and refusal side effects.

Tests:

• Add 78 tests covering unwritable values, source resolution, safe output, refusal consistency, and prevention of partial adoption.

[sourcery-ai]

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

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

[brettheap]

(lane openRepoShape-2, 2026-10-11T23:02:46Z) @codex review

[sourcery-ai]

Reviewer's Guide

The PR prevents adoption from creating or pushing leg repositories when values that execute writes to manifests, README files, commit messages, or local clone URLs cannot be represented as single-line UTF-8 text. It centralizes the validation predicate, wires consistent plan/check/execute handling and safe diagnostics through the adoption flow, validates source paths early, and adds broad regression coverage.

Sequence diagram for unwritable adoption value validation

sequenceDiagram
    actor User
    participant Plan as plan
    participant Check as check
    participant Execute as execute
    participant Validator as unwritable_reason
    participant Remotes as leg remotes
    participant Files as manifests README commit message

    User->>Plan: pass adoption values
    Plan->>Validator: validate --elected-by and --reference
    alt unwritable value
        Validator-->>Plan: reason
        Plan-->>User: REFUSED adopt-unwritable-value
    else writable value
        Plan-->>User: write plan
    end

    User->>Check: inspect plan
    Check->>Validator: validate plan values
    alt unwritable plan value
        Validator-->>Check: finding
        Check-->>User: FINDING plan-unwritable-value
    else writable values
        Check-->>User: plan ok
    end

    User->>Execute: execute plan
    Execute->>Validator: validate plan values and local clone URL
    alt unwritable value
        Validator-->>Execute: refusal
        Execute-->>User: REFUSED plan-unwritable-value or adopt-unwritable-value
        Note over Execute,Remotes: No leg remotes are created
    else writable values
        Execute->>Remotes: _create_leg_remotes
        Execute->>Files: write_lf and commit follow-ups
        Files-->>Execute: adoption completes
    end

Loading

Flow diagram for safe adoption validation

flowchart TD
    A[Adoption input or plan] --> B{unwritable_reason}
    B -->|line break, control character, or surrogate| C[Refuse or report finding]
    C --> D[No leg remotes or pushed repositories]
    B -->|single-line UTF-8 text| E{Execution context}
    E -->|plan| F[Write plan]
    E -->|check| G[Show safe values and findings]
    E -->|execute| H[Validate local clone URL]
    H -->|unwritable| C
    H -->|writable| I[Create leg remotes and write files]

    J[local_path] --> K{exists and is text path}
    K -->|no| L[Refuse source-unresolvable]
    K -->|yes| A

Loading

File-Level Changes

Change	Details	Files
Centralize detection of values that cannot be safely represented in the files or commit messages written by adoption.	Add unwritable_reason to reject multiline values, lone surrogates/non-UTF-8 bytes, and control characters while allowing empty values and format characters. Use the predicate for command-line plan inputs, hand-edited plan values, pins, follow-ups, and the local clone URL. Reuse shared finding text so plan, check, and execute report or refuse the same underlying problem.	scripts/shape_materialize.py adopt-project.py
Move failures caused by invalid source paths and local clone URLs ahead of repository creation.	Classify non-text or invalid local_path values as source-unresolvable instead of allowing print/subprocess tracebacks. Refuse an unwritable local clone URL immediately after repository URL resolution and before leg remotes are created.	adopt-project.py
Make diagnostic output safe when plans contain values that cannot be emitted directly to strict UTF-8 stdout.	Apply _shown to visibility, adopt branch, leg paths, and follow-up values in the WHAT WILL HAPPEN output.	adopt-project.py
Add comprehensive regression coverage for invalid and valid text values across all adoption routes.	Cover plan refusals, check findings, execute refusals, source-path handling, safe rendering, local clone URLs, and absence of tracebacks or leg remotes. Exhaustively test unwritable_reason against writable values, control characters, line separators, surrogates, and non-ASCII text. Verify valid accented, format-character, and UTF-8 path inputs continue to adopt.	tests/test_adopt_template_values.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#255	Reject non-UTF-8, surrogate, line-breaking, and other unwritable values supplied through --elected-by or --reference during plan creation, so no invalid plan is written.	✅
#255	Ensure check and execute detect unwritable plan/template values consistently and refuse execution before creating or pushing any leg remotes, including values written to the assembly templates, pins, and follow-up commit messages.	✅
#255	Prevent a local source path containing non-text bytes or otherwise unwritable characters from causing traceback failures, and specifically reject an unwritable local clone URL before execution creates remotes.	✅

Possibly linked issues

• 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: PR directly fixes issue 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 by rejecting unwritable values before plans or leg remotes are created.

---

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.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-11T23:12:20.790638Z	aed9190	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🚀

Reviewed commit: aed9190bce

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[brettheap]

(lane openRepoShape-2, 2026-10-12T00:03:59Z)

This lane reviewed its own PR #270 at aed9190, before any fix round, read-only in its own detached worktrees, against main c3f4987.

CHANGES NEEDED. Every route the issue names now ends in a refusal or finding, with no traceback and no leg. The controls still adopt, and all 10 mutants are killed. Three small fixes:

• F1 (P3), fix here. unwritable_reason (scripts/shape_materialize.py:814) admits all of Cf, so the bidi controls U+202A to U+202E and U+2066 to U+2069 pass all three commands. They are written raw into project.yaml, README.md and the split commit's message, and tests/test_adopt_template_values.py:466 pins U+202E as writable. The issue asked one_printable_line, which refuses them. Refuse those nine; keep U+200C.
• F2 (P3), fix here. The SonarCloud gate fails: text:S6389 flags the raw U+202E at test line 466, and python:S9073 flags composite assertions at :494 and :495. Escape every invisible literal in the file, and split both assertions.
• F3 (P3), fix here. The clone-URL refusal's remediation (adopt-project.py:2990) ends in a UnicodeDecodeError traceback when followed, because the clone's origin is the old path. Renaming the directory, or removing that origin, both adopt.
• Nits: the body's counts and merge table predate c3f4987, and a TAB in git config user.name is refused under the name --elected-by.
• Follow-ups (no open match):
  • a Latin-1 byte in user.name or origin gives a plan traceback;
  • follow_ups: 5 raises TypeError;
  • with no reference:, a non-date elected_on creates both leg repositories before it is refused.
• Already covered: quotes and backslashes are 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's (scaffold: scaffold-project.py writes --elected-by, --reference and --name between literal double quotes with no escaping and asks none of them whether a file can hold it, so a line break leaves a project.yaml its own validators refuse, a backslash is recorded as another character (CORP\nick as CORP, a line feed, ick), and a byte that is not UTF-8 dies in write_lf after the legs are pushed #282).

Tests.

• head: 59 passed;
• main with the file: 56 failed for the issue's reasons, 3 controls passed;
• merge with main c3f4987: 1437 passed, 2 skipped across 23 targeted files; merge with d94d155: 346 passed, 1 skipped across 6 files;
• CI tests, macOS and Windows: green.

Merges. Clean with main and nine heads. This PR adds _entry_findings hunks with #231 (2), #245 (2), root-kept-symlinks (2) and #181 (3). #181's branch must first rename its second _shown, which shadows main's: main+#181 fails 9 tests.

Report: opensoft/brett-wip handoffs/xFactory/attachments/lane-openRepoShape-2/review270-aed9190/final-report.md.

[brettheap]

(lane openRepoShape-2, 2026-10-12T01:09:14Z)

This lane re-verified its own PR #270 at 7e9cdc3 after fix round 1.

CHANGES NEEDED: one small guard, and the branch must take main.

Items:

• F1, fixed. All nine bidi controls are refused by plan (2), check (1), execute (2) and the clone URL, with no leg and no traceback. Seven other Cf characters still adopt.
• F2, fixed. Sonar closed all three issues.
• F3, fixed. The remediation, followed as worded, adopts for a caf\xe9 directory and for a U+202E directory.
• N1, N2, fixed.

S8705. No line this PR adds runs a command, and the flagged flow lies wholly in run(). Main carried the same issue from 2026-09-03, traced from update-shape.py --branch. It closed at 00:30Z on a family.py-only commit, leaving #270 the only PR showing it. Its question did find a real injection on head and main alike: plan --source=-u/x runs gh repo clone -u/x ..., and gh reads -u as its own option. git sees only --quiet. Fix here: add or spec.startswith("-") at adopt-project.py:401, with a test. If S8705 is still open after the branch takes main, accept it.

Tests:

• head: all 15 mutants killed;
• merge with ede15ce: 1630 passed, 5 skipped;
• scratch resolution with main 6f45bf9: 385 passed.

CI: tests and macOS pass; Windows is pending; SonarCloud fails.

Merges: head conflicts with main 6f45bf9 and b421e6b, 2 hunks in _entry_findings from #231. Rename this PR's value_findings pair, which #261 also binds.

Report: opensoft/brett-wip handoffs/xFactory/attachments/lane-openRepoShape-2/review270-aed9190/reverify-1.md.

[brettheap]

(lane openRepoShape-2, 2026-10-12T01:52:15Z)

This lane re-verified its own PR #270 at edfa7c6 after fix round 2.

MERGEABLE once tests-windows passes.

• S1, fixed. --source=-u/x, --upload-pack=... and --no-upstream/x, and a plan local_path: beginning with -, are refused source-unresolvable; gh never runs. org/repo and URLs still reach gh.
• Merge commit: only the two adopt-project.py: check and execute judge an entry's path by one test, entry_path_problem, that admits every path git can take literally, 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 cannot take is a check finding refused before any leg exists (#196) #231 hunks, as recommended, and the rename missed nothing. adopt-project.py: check and execute judge an entry's path by one test, entry_path_problem, that admits every path git can take literally, 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 cannot take is a check finding refused before any leg exists (#196) #231's tests pass on the merged head.
• F1 to F3, N1 and N2 still hold.

Tests:

• merge with main c0ed615: 1700 passed, 5 skipped;
• 16 of 16 mutants killed, the dropped guard among them.

CI: SonarCloud passes (S8705 closed), tests and macOS pass, Windows is pending.

Merges:

• clean with c0ed615;
• scaffold-project.py and adopt-project.py ask the project's YAML reader and validate-manifest.py about the manifest's values before anything exists, so --id null, --tracking-branch true and a blank --elected-by are refused (#258, #261) #314 (7defac7) conflicts only in text, with no findings lost. Keep both imports and return both PRs' lists. On that merge, three of this PR's hand-edit tests (elected_on, visibility) expect the wrong refusal code, because adopt-project.py and scaffold-project.py accept values the new project's own validate-manifest.py refuses (a blank --elected-by or --reference, --elected-on 2026-W41-6 or 20261011 on Python 3.11+, --org test+org, a plan's visibility: secret), so adoption verified or a scaffold exit 0 is followed by a failed first bootstrap; and plan admits a 251-255-character --project that check refuses #261's finding comes first. The second lander loosens them.
• adopt-project.py: check finds, and execute refuses before any leg exists, a kept root path where the shape writes a directory or its shape/ copy, whether the disk keeps case or not; the materializer never writes over a copy (#262, #263) #313, 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, 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 and root-kept-symlinks give 1 to 3 mechanical hunks.

Report: opensoft/brett-wip handoffs/xFactory/attachments/lane-openRepoShape-2/review270-aed9190/reverify-2.md.