[brettheap]

Lane: openreposhape-5 (openRepoShape-5)
Claim: #282 (comment)

What #282 still gets wrong on main (c7c02fa). #284 (b30595c) spells each of the three quoted placeholders in project.yaml with repo_shape.double_quoted. So the manifest now reads back whatever was typed. The README, each AGENTS.md and each first commit's message still take the value as it stands. Every row of the issue was re-run on c7c02fa with local bare remotes only: 76 cases across --elected-by, --reference, --name, GIT_AUTHOR_NAME and git config user.name (given as GIT_CONFIG_COUNT config). In every case that scaffolded, the project's reader and PyYAML 6.0.3 read the manifest back as typed (0 misreads, 0 raises). What was still wrong:

• A byte that is not UTF-8. The scaffold exits 1 with a UnicodeEncodeError traceback from write_lf. Through --elected-by, --reference or GIT_AUTHOR_NAME, both legs are pushed by then and the assembly root is created empty. Through --name, all three repositories are created first. Through git config user.name it raises UnicodeDecodeError from git_out's strict decode in _elector. That one happens under --dry-run too, before anything is created. The issue does not list this case.
• A line break: LF, CR LF, U+0085, U+2028, U+2029. The scaffold exits 0. The value goes raw into the README, which gains a line. Through --name it also goes raw into the root AGENTS.md (2 extra lines) and each leg's AGENTS.md (1). With LF or CR LF, each commit message's first line becomes Seed the spec leg of Ada; U+0085, U+2028 and U+2029 sit in that line raw. The manifest ok: line that the project's own validate-manifest.py prints is split as well.
• A control character (U+0001, ESC, DEL, TAB), or a bidi embedding, override or isolate (U+202E, U+2066/U+2069). The scaffold exits 0, and the value is raw in the README (and, for --name, in each AGENTS.md and each commit message).

The change.

• scaffold-project.py _identity asks unwritable_reason about the three values, beside election_date. Any value that fails is refused as scaffold-unwritable-value. The refusal is one sentence per value: the flag, the value as Python's repr spells it, the files it is written into, and why. All failing values go into one refusal. It comes before a work directory or a remote exists, and --dry-run refuses the same. The only process that can run first is the read-only git config user.name that finds the elector when neither --elected-by nor GIT_AUTHOR_NAME gives one:

  REFUSED scaffold-unwritable-value: --name is 'Jos\udce9', which the scaffold writes into the assembly root's `project.yaml` and `README.md`, each repository's `AGENTS.md` and each first commit's message, and it holds a byte that is not UTF-8.
  

  An elector the flag did not supply is named by its source: --elected-by (not given, so GIT_AUTHOR_NAME) or --elected-by (not given, so `git config user.name`) (_elector_named, in _elector's order). The second is the wording 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's plan uses.

• _elector decodes git config user.name with surrogateescape, the way argv and the environment are decoded. A byte that is not UTF-8 there is then refused by name, not raised. adopt-project.py already reads git with this pattern (git_out(..., binary=True).decode("utf-8", "surrogateescape")).

• scripts/shape_materialize.py gains BIDI_CONTROLS and unwritable_reason: see "Composition with PR 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" below.

Each row of the issue.

row	project.yaml	README / AGENTS.md / commit messages	where it stands
a backslash (CORP\nick, also through GIT_AUTHOR_NAME and git config user.name; C:\docs\notes\new.md)	fixed on main by b30595c (#284): "CORP\\nick", read back exactly	raw, as typed, on its own line (Markdown keeps a backslash before a letter literal, and the path is inside backticks)	fixed on main by b30595c
a double quote (Joe "JJ" Smith)	fixed on main by b30595c: "Joe \"JJ\" Smith", read back exactly	raw, as typed	fixed on main by b30595c
a line break: LF, CR LF, U+0085, U+2028, U+2029	parses on main since b30595c (escaped, read back exactly)	split on main	fixed by this branch: refused
a byte that is not UTF-8 (all five ways in)	escaped on main since b30595c; not where it failed	traceback on main: write_lf raised on the root README or, for --name, the spec leg's AGENTS.md; git config user.name raised in git_out	fixed by this branch: refused
a control character: U+0001, ESC, DEL (TAB too)	PyYAML's ReaderError fixed on main by b30595c (escaped)	raw on main	fixed by this branch: refused
a bidi control: U+202E, U+2066, U+2069	escaped on main since b30595c	raw on main (README.md:9)	fixed by this branch: refused

No row is left open. On this head, the 60 cases with an unwritable value exit 2 under both --dry-run and a real run. Each prints one scaffold-unwritable-value refusal and makes no bare remote, with 0 tracebacks. The other 16 cases scaffold, exit 0: the backslash, the Windows path, the double quote, and a Persian name joined with U+200C ZERO WIDTH NON-JOINER. Each reads back exactly, and the README gains no line.

Files outside YAML. README.md (:1 name, :9 elector, :10 reference in backticks), the root AGENTS.md (:3, :13), each leg's AGENTS.md (:1), and the three first commits' messages take the value raw. A backslash and a double quote break none of them: the file holds the typed text, and the line count is unchanged. Every other row is now refused before any of them is written. --name also goes into the GitHub description via gh repo create, which is not run here.

Composition with PR #270 (lane 2, fix/adopt-template-values-utf8, #255). #270 adds unwritable_reason and BIDI_CONTROLS to scripts/shape_materialize.py (aed9190, 7c3c020). This branch adds the same hunk byte for byte, at the same place (after is_trailer), applied from git diff 71b58a1 pr270 -- scripts/shape_materialize.py. Whichever PR lands second merges to one definition, with nothing to switch. git merge-tree --write-tree of this head with #270 (72bb869) is clean. The merged tree's scripts/shape_materialize.py is identical to both sides' and holds one def unwritable_reason and one BIDI_CONTROLS. The two tools refuse the same values in the same words. If #270 changes the function in review before it lands, the merge conflicts at that hunk instead of keeping two definitions. Whoever lands second then takes #270's version. Two comments in scaffold-project.py say that adopt-project.py asks the same question. That is true once #270 has landed; until then only the scaffold asks it.

Composition with PR #314 (lane 5, fix/scaffold-manifest-values). No duplication. #314 asks the project's reader and validate-manifest.py about the rendered manifest, after the values table is built. This branch asks whether a value is text a file can hold, earlier, in _identity. Each refuses values the other passes: a blank --elected-by ' ' is #314's, and Ada\nLovelace is this branch's. The merge with ab66bc0 is clean. On the merged tree, #314's own tests fail in 5 places, all on a value both PRs refuse: --elected-by of a bare TAB, \x0b, \x1c or U+2028, which is blank to the validator and unwritable here. This branch refuses those first, as scaffold-unwritable-value, where #314's tests expect scaffold-manifest-invalid or scaffold-manifest-. The failing tests are test_a_value_the_validator_refuses_is_refused_before_anything_is_made[elected-by-tab], test_a_dry_run_refuses_what_the_validator_refuses[elected-by-tab] and test_a_blank_that_is_also_a_line_break_is_refused_too[\x0b|\x1c|\u2028]. Whichever of the two lands second applies a four-line patch to tests/test_scaffold_manifest_values.py (lane 5 holds it), which expects scaffold-unwritable-value for those four values. With it applied, the merged tree passes: see Evidence.

Merge-tree (git merge-tree --write-tree HEAD <ref>, fetched 2026-10-12):

ref	tip	result
origin/main	c7c02fa, and 346079d (#228 landed since: adopt files only)	clean
PR #270	72bb869	clean, one unwritable_reason
PR #314	ab66bc0	clean (5 of #314's tests need the patch above)
PR #309 (lane 4)	2ea1717	clean
PR #316 (lane 5, render single pass)	9469148	clean
PR #266 (lane 2)	b2b42f8	clean
lane 1 fix/adopt-record-submodule-placement	3e86200	clean
lane 1 fix/adopt-late-failure-notice	918e8f2	clean
lane 1 fix/adopt-root-kept-symlinks	6c44591	CONFLICT in adopt-project.py, which this branch does not touch; the branch conflicts with origin/main alone the same way
lane 1 fix/adopt-plan-quote-yaml-keywords	e337f44	the same: CONFLICT in adopt-project.py, also against origin/main alone
lane 5 siblings fix/pin-source-env-collisions c32a228, fix/family-init-values 14e2d68, fix/yaml-flow-brackets-surrogates 38738cf, docs/adopt-execute-exits d3f71d6		clean
lane 2 local fix/scaffold-tracking-branch-ref-format (#283)	a03abcf	clean

Evidence.

• New tests/test_scaffold_free_text_values.py, 113 cases:
  • each of the 12 unwritable values through each flag, dry and real (72), under a guard that fails the test if any process starts;
  • all three bad values named in one refusal;
  • each value through GIT_AUTHOR_NAME (12), with no process started;
  • git config user.name with LF, U+202E, ESC and a byte that is not UTF-8, dry and real (8). The last is skipped on Windows, whose environment is UTF-16;
  • the flag winning over the fallbacks;
  • 15 dry runs that must not refuse;
  • one real scaffold of a backslash, a quote and U+200C, through --name, --reference and GIT_AUTHOR_NAME (the test does not use the --elected-by flag). It reads back exactly, and the README lines, each leg's AGENTS.md and the commit subjects stay single (the root AGENTS.md is not checked by this test);
  • a byte that is not UTF-8 through each flag as a child process's argv (3).
• That file on head: 113 passed. On c7c02fa: 97 failed, 16 passed. The 16 are the 15 dry runs and the real scaffold of text, which hold on main since repo_shape.py: a quote opens a quoted scalar only where one begins and must close there, so k: [it's, a] reads two items, k: it's fine # note drops its comment, and an unclosed "abc or a mid-key [ is refused, not misread (#249, #250) #284 by design.
• Mutation probes (each reverts one part, in a throwaway worktree; every one makes at least two tests fail):
  • no refusal call: 97 failed;
  • strict decode of git config user.name: 2;
  • _elector_named always --elected-by: 20;
  • elector field dropped: 47;
  • --reference dropped: 26;
  • --name dropped: 26;
  • no line-break check: 39;
  • no surrogate branch: 13;
  • no bidi branch: 17;
  • no control branch: 30;
  • refusing every Cf (over-refusal): 4, the U+200C cases.
• Targeted on head 8f43c96 (git-filter-repo 2.47.0 on PATH): tests/test_scaffold_free_text_values.py tests/test_scaffold_e2e.py tests/test_scaffold_pin_and_reuse.py tests/test_scaffold_leg_paths.py tests/test_scaffold_leg_path_collisions.py tests/test_scaffold_pin_collisions.py tests/test_scaffold_referent_chain_links.py tests/test_scaffold_mount_ignored.py tests/test_scaffold_ignored_shape_files.py tests/test_template_quoted_values.py tests/test_naming_policy.py tests/test_reference_default.py tests/test_reuse_visibility.py tests/test_stdout_encoding.py tests/test_repo_hygiene.py tests/test_cli_reference.py: 801 passed, 1 skipped (test_stdout_encoding.py:286, Windows' own default).
• Merged trees:
  • with 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, this file plus test_adopt_template_values.py: 191 passed;
  • with 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 plus the compose patch, this file plus test_scaffold_manifest_values.py, test_scaffold_e2e.py, test_template_quoted_values.py and test_cli_reference.py: 343 passed. Without the patch (on a5ef3f5, which differs from 8f43c96 only in an import's place and a docstring): 5 failed, 338 passed, the five above;
  • with shape_materialize.py: render substitutes in one pass and refuses only a placeholder its table lacks, so --elected-by '{{SPEC_PATH}}' is no longer recorded as spec and {{NOPE}} no longer refuses after the legs are pushed (#260) #316, this file plus test_template_quoted_values.py and test_template_values_single_pass.py: 344 passed.

Left out, with follow-up candidates.

• adopt-project.py plan dies the same way on a git config user.name that is not UTF-8. With no --elected-by, it exits 1 with UnicodeDecodeError from git_out (c7c02fa, and with 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 merged). _elector in adopt-project.py reads it strictly. It is adopt's half and 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's ground, so it is not touched here.
• A --local-remote-dir path that is not UTF-8. The scaffold creates the three bare remotes, then raises in write_lf on {{ASSEMBLY_CLONE_URL}} in a leg's README (reproduced on this head). It is the test path only. 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 refuses the same for adopt's clone URL (_refuse_an_unwritable_clone_url). Here it is a separate, small issue.
• A GIT_AUTHOR_NAME of whitespace alone. The scaffold falls past it to git config user.name for the elector. env_commit then hands it to git unchanged, and git refuses to commit (fatal: name consists only of disallowed characters) after the remotes are created. Seen on c7c02fa while testing; not this issue's input.
• Markdown syntax in the values (*, `, [, \*) renders as Markdown in the README and AGENTS.md. The files hold the typed text, and escaping it would print backslashes in a plain read, so it is not changed.
• No --help text changed, so docs/cli.md is not regenerated. The module docstring's first line, the help description, is unchanged.

Review. An adversarial review of 8f43c96 found 0 blockers, 0 should-fix and 5 nits (APPROVE WITH NITS):

• 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 copy: it re-checked the copied hunk byte for byte (same sha256) and found one definition in every merge, in either landing order.
• Probes: 63 values went through all five sources, dry and real; 320 cases were refused with no work directory, remote or traceback, and nothing was found landing broken.
• Order with 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: the 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 patch is complete (219 passed with it), and the order of the two refusals is sensible.
• Nits handled in this body: the "before any process" claim (N1) and wording (N5).
• Nits left for a fix round:
  • three mutants of this branch's copy of unwritable_reason that only 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's unit table catches (N2);
  • the argv child-process test with no Windows skip (N3; CI decides);
  • naming the elector's fallback the same way as 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 on the merged tree (N4).

Closes #282

🤖 Generated with Claude Code

Summary by Sourcery

Refuse free-text identity and reference values that cannot be safely written to scaffold files before creating any project resources.

Bug Fixes:

• Reject unwritable --elected-by, --reference, and --name values before creating work directories or repositories, including during dry runs.
• Handle invalid UTF-8 from the git config user.name elector fallback without traceback and report the originating fallback clearly.

Enhancements:

• Provide consolidated, actionable refusal messages for line breaks, control characters, bidi controls, invalid UTF-8, and lone surrogates while preserving valid free-text values.

Tests:

• Add comprehensive coverage for invalid and valid free-text values across command-line flags and elector fallbacks, including dry runs, real scaffolds, subprocess argv, and no-side-effect assertions.

[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 11 hours and 9 minutes by commenting @sourcery-ai review. Upgrade to get a review now.

[brettheap]

(lane openRepoShape-5, 2026-10-12T12:23Z) @codex review

[sourcery-ai]

Reviewer's Guide

The PR introduces shared character-level validation for scaffold text values and invokes it during identity resolution, ensuring invalid UTF-8, line-breaking, control, and bidi content is refused with actionable diagnostics before any repository creation; it also hardens git identity decoding and adds broad regression and end-to-end coverage.

Sequence diagram for preflight validation of scaffold identity values

sequenceDiagram
    participant User
    participant Scaffold as scaffold-project.py
    participant Git as git config user.name
    participant Validator as unwritable_reason
    participant Filesystem as WorkdirAndRemotes

    User->>Scaffold: invoke scaffold or --dry-run
    Scaffold->>Git: read user.name when flag and environment are absent
    Git-->>Scaffold: UTF-8 text or surrogateescaped bytes
    Scaffold->>Validator: validate elected_by, reference, and name
    alt unwritable value found
        Validator-->>Scaffold: refusal reason
        Scaffold-->>User: scaffold-unwritable-value
        Note over Filesystem: no work directory or remotes created
    else all values are writable
        Validator-->>Scaffold: valid
        Scaffold->>Filesystem: create workdir and repositories
    end

Loading

File-Level Changes

Change	Details	Files
Validate scaffold free-text inputs before creating any work directory or remote.	Add early validation for --elected-by, --reference, and --name, aggregating all invalid values into one scaffold-unwritable-value refusal. Report the source, Python-repr value, write locations, and specific reason, with identical behavior for dry runs. Reject lone surrogates/non-UTF-8 bytes, line breaks, controls, and bidi embedding/override/isolate characters while preserving supported text such as quotes, backslashes, and ZWNJ.	scaffold-project.py scripts/shape_materialize.py
Make git identity fallback decoding safe and preserve the elector's source in diagnostics.	Decode git config user.name using UTF-8 with surrogateescape instead of strict output decoding. Distinguish values supplied by --elected-by, GIT_AUTHOR_NAME, and git config user.name in refusal messages.	scaffold-project.py
Add comprehensive regression coverage for refusal ordering, input sources, and valid free-text values.	Cover invalid values across all three flags, dry-run and real execution, fallback sources, combined refusals, and child-process argv handling. Assert no process, work directory, or remote is created before refusal. Verify writable values remain exact in the manifest, README, AGENTS.md files, and initial commit subjects.	tests/test_scaffold_free_text_values.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#282	Refuse --elected-by, --reference, --name, and elector fallback values containing non-UTF-8 data, line breaks, control characters, or bidi embedding/override/isolate controls before any work directory or repository is created, including during --dry-run.	✅
#282	Escape the three values when writing double-quoted YAML scalars so backslashes, double quotes, and other valid text round-trip exactly through project.yaml.	✅
#282	Preserve valid free-text values in README.md, AGENTS.md files, and commit messages without introducing malformed lines or changing their contents.	✅

Possibly linked issues

• 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: The PR directly fixes issue 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 by validating these values before repository creation and refusing unsafe line breaks, controls, bidi characters, and invalid UTF-8.

---

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-12T12:29:10.753840Z	8f43c96	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. Delightful!

Reviewed commit: 8f43c968ba

ℹ️ 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".

[sonarqubecloud]

Quality Gate passed

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