[brettheap]

Closes #1035

What was wrong

plan's source line printed the source's branch as it is: ({source.branch}). A branch is a name its author chose, and git lets one hold U+202E and the other bidirectional controls, the line boundaries U+0085 and U+2028, and a zero-width space. A source on ma<U+202E>in, planned with --tracking-branch main, put the U+202E in the terminal's bytes, where it reorders what the line shows after it.

What changed

adopt-project.py, in _print_plan_report: the line names _shown(source.branch), the helper plan already uses for every other name it prints (the table, the follow-ups, the split message's listing, #199 and #900), and as check spells this branch in plan-stale and plan-tracking-branch-missing. No new escaper.

• A printable branch prints exactly as before: (main) stays (main).
• Any other branch is spelled between backticks: (`ma\u202ein`).
• The line for a source plan cloned is the same line, so it gets the same spelling.

Tests

tests/test_adopt_plan_source_branch_shown.py (new, 19 rows):

• Seven end-to-end rows make the branch in a real local source and run plan with the real gh unreachable, reading the bytes it prints: U+202E, U+2066, U+0085, U+2028, U+200B, an ordinary feat/x-1 (must print unchanged), and a branch that is not UTF-8 under a strict stdout (skipped where no filesystem can name the byte). Each asserts the raw character is not in stdout, the whole source line, and that the plan file still records the branch as it is.
• Twelve in-process rows call _print_plan_report with the branch set on the Source: seven ASCII controls (NUL, BEL, BS, CR, LF, ESC, DEL), which git refuses in any ref name so no source can hold one, and five characters for the cloned-source form.

On main's adopt-project.py: 18 failed, 1 passed (the ordinary-branch row, which guards against over-escaping). With this change: 19 passed.

Mutants, each run on the new file with the file restored and its sha256 checked after: raw branch 18 failed; _spelled for _shown 1 failed; repr 19 failed; _shown for ASCII branches only 11 failed; strips only U+202E 2 failed; _shown on the first character only 18 failed.

Gate, targeted (Linux, the landing gate's environment, a stub gh), at this head over two shards: 1708 passed, 1 skipped for the new file, the adopt tests that read plan's report, branch names or locale bytes, test_scaffold_leg_path_collisions.py, test_repo_hygiene.py and test_cli_reference.py; 445 passed, 3 skipped for test_shape_doctor.py. No failure.

Known follow-up, outside this change

plan written to {out} (in cmd_plan) prints the --out path as typed, so a bidi control in it reaches the terminal raw. It is the caller's own typed path and not repository data, and the issue names the source line only, so it is left as it is. Lane 4 files the issue for it.

The plan table's padding (#1034) is untouched.

Open PRs on adopt-project.py: this head merges cleanly with #1105 and #1106. #1091 conflicts with main itself in lines 695-860, away from the hunk here, and not because of this change.

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

Summary by Sourcery

Safely spell source branch names in plan reports to prevent terminal-confusing output without changing ordinary branch display.

Bug Fixes:

• Sanitize source branch names in plan reports so bidirectional controls, line separators, zero-width characters, ASCII controls, and non-UTF-8 bytes cannot reach the terminal raw while preserving the branch in the generated plan.

Enhancements:

• Keep printable branch names unchanged while applying the existing safe-name spelling consistently to cloned and local sources.

Tests:

• Add end-to-end and in-process coverage for unsafe, printable, control-character, cloned-source, and non-UTF-8 branch names.

[sourcery-ai]

Reviewer's Guide

The PR updates plan's source report to render branch names with the existing _shown escaping logic, preventing terminal-affecting characters and invalid UTF-8 from being emitted raw while preserving ordinary branch output. A focused test suite covers real Git/CLI paths, synthetic invalid ref names, cloned sources, and plan-file fidelity.

File-Level Changes

Change	Details	Files
Sanitize source branch names in the plan report before writing them to terminal output.	Changed the source summary to pass source.branch through the existing _shown formatter. Preserved unchanged output for printable branch names while escaping bidi controls, line boundaries, zero-width characters, ASCII controls, and invalid UTF-8 bytes. Applied the same branch spelling to cloned-source report lines.	adopt-project.py
Added regression coverage for safe branch rendering across real CLI execution and direct report generation.	Added end-to-end tests for bidi controls, Unicode line boundaries, zero-width space, ordinary branches, and non-UTF-8 branch bytes. Added in-process tests for ASCII controls that Git cannot store in ref names and for cloned sources. Verified the rendered source line remains printable and that the plan file retains the original branch name.	tests/test_adopt_plan_source_branch_shown.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#1035	Prevent plan’s source line from printing branch names containing bidi controls or other unprintable characters raw, while leaving printable branch names unchanged.	✅
#1035	Check other plan output for values printed raw and identify any remaining cases.	✅

Possibly linked issues

• adopt-project.py: the split commit's message and plan's report name each path, question and rule id one way only and never raw, the history scan's git-failed is one line, and the table pads a name as stdout prints it (#900) #1030: The PR applies the issue’s requested _shown(source.branch) change and tests unprintable branch names.

---

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.

[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

[brettheap]

RV1120: independent review of #1120 at c55e55e3: READY

Independent adversarial review for lane 4. No MUST, no SHOULD; four NITs for follow-ups, below.

Merge with current main

• PR head c55e55e33 (unchanged), current origin/main 823624d93 (after scaffold-project.py: the --reuse-empty-repo help, its docs and each remedy that sends a person into that re-run say ssh, a credential helper or askpass can still make it wait, and how to keep it from waiting (#915) #1101 and templates/assembly-root/project.yaml and templates/family-root/family.yaml: the comment above visibility: says it is the visibility the run asked for, and that a repository the run reuses keeps its own, where it said "this is all three repositories' visibility" (#913) #1102).
• git merge-tree --write-tree origin/main c55e55e33: exit 0, tree eaa314dc9d3e. The merged tree differs from main only in adopt-project.py (+6 -1) and tests/test_adopt_plan_source_branch_shown.py (new, 237 lines).
• Every gate below ran on the scratch merge commit 9480fc65f (main 823624d93 + the PR). Main's two new commits change the scaffold, docs and the YAML comments of two templates; the gate was re-run whole on the new merge all the same.

The fix

• _print_plan_report prints _shown(source.branch), the helper the table, follow-ups and questions already use. The cloned form shares the line. Nothing else changed.
• _shown, every code point. _shown("ma" + chr(cp) + "in") for all 0x110000 code points (Python 3.12.3, Unicode 15.0): no output holds a character str.isprintable() rejects, and no unprintable input comes back raw. Every Cc, Cf, Cs, Co, Cn, Zl, Zp, and Zs other than the ASCII space is spelled: bidi embeddings, overrides and isolates, LRM/RLM/ALM, U+200B-U+200D, U+2060, U+FEFF, U+00AD, U+180E, the tag characters, U+0085, U+2028/U+2029, U+00A0.
• End to end (a real source on the branch, plan --tracking-branch main, real gh unreachable): U+200D, U+2029 and U+00A0 are spelled; feat/caf\u00e9 and \u6a5f\u80fd/x print unchanged; a branch named `main` is spelled `\x60main\x60`.
• A branch that is not UTF-8 (caf<0xE9>), by PYTHONIOENCODING:

stdout	main	PR
utf-8:strict	(caf\udce9)	(`caf\udce9`)
utf-8:surrogateescape	raw byte 0xE9	(`caf\udce9`)
utf-8:replace	(caf?)	(`caf\udce9`)
utf-8:backslashreplace	(caf\udce9)	(`caf\udce9`)
ascii:strict	(caf\udce9)	(`caf\udce9`)
latin-1:surrogateescape	raw byte 0xE9	(`caf\udce9`)

• plan's other lines. The cloned form's owner/repo is held to [A-Za-z0-9_.-]. --project and --org are held to ^[A-Za-z0-9._/@+~-]{1,255}$ and --id to ^[a-z0-9][a-z0-9-]*$: measured with U+202E in each, and in an org read from the source's origin (U+202E and U+200B), every one is refused before any report, its value escaped. The table, follow-ups, questions and every NOTE spell what they name; the triad advisory goes through shape_advisory.printable. Beyond adopt-project.py: plan written to prints the caller's --out path raw, so a bidi control in it reaches the terminal, where the other plan lines spell paths with _shown #1115's --out, the one raw value found is N4.

The test file

• ASCII only: LC_ALL=C grep -nP '[^\x00-\x7F]' finds nothing in it or in the PR's added lines. c55e55e33 replaces exactly the four raw characters with \u202e, \u2066, \u2028, \u200b.
• On the merge: 19 passed, 0 skipped (the non-UTF-8 row ran).
• With main's adopt-project.py: 18 failed, 1 passed (the ordinary-branch row). Each fails for the right reason: the raw character is in the output (the five end-to-end rows, the seven controls, the five cloned rows), and the non-UTF-8 row lacks the backticks.

Gate (Linux, the landing gate's environment, stub gh), on 9480fc65f

Files	Result
the new file, test_adopt_source_clone_record, test_adopt_plan_escapes, test_adopt_plan_out_checked	205 passed
test_adopt_branch_names, test_adopt_tracking_branch, test_adopt_c_locale_bytes, test_adopt_literal_names, test_adopt_git_reads, test_tracking_branch_ref, test_non_utf8_git_failures	317 passed
test_scaffold_leg_path_collisions, test_repo_hygiene, test_cli_reference	227 passed
test_shape_doctor (two shards)	445 passed, 3 skipped (Windows-only PowerShell rows)

Mutants (mine; each on the new file, the file restored and its sha256 checked after each)

Mutant at the source line	Result
A: raw branch for a cloned source	5 failed
B: raw branch in place	13 failed
E: _spelled for every non-ASCII branch	0 failed (survives)
F: backticks stripped from the spelling	18 failed
G: only categories C* spelled	2 failed (U+2028 rows)
J: encode('ascii', 'backslashreplace')	18 failed
L: a surrogate replaced with ?	1 failed
M: the plan file records _shown(branch)	5 failed
N: isprintable() alone, no backtick rule	0 failed (survives)

E and N leave correct code's behaviour unpinned (N2 below); the PR's code is right on both.

Findings

• N1 (NIT), _shown itself. str.isprintable() passes the 267 Default_Ignorable code points that are not Cf: 263 Mn, among them U+034F, U+17B4/U+17B5, U+180B-U+180D, U+180F, U+FE00-U+FE0F and U+E0100-U+E01EF, and the four Lo fillers U+115F, U+1160, U+3164 and U+FFA0. Git takes them in a branch, and U+034F, U+3164 and U+FE0F reach plan's stdout raw (measured), so ma<U+034F>in reads as main. The unsafe-value refusal's repr prints U+3164 raw on stderr the same way. They reorder nothing, and this is the helper everywhere, not this line. Follow-up: treat Default_Ignorable_Code_Point as unprintable in _shown and escape it in _spelled_character, as plan and check both print through them.
• N2 (NIT), the tests. Add a printable non-ASCII branch (feat/caf\u00e9) to test_plan_names_an_ordinary_branch_as_it_did, and a row for a branch named `main`. Mutants E and N survive without them.
• N3 (NIT), the tests. The non-UTF-8 row runs only under utf-8:strict, where main wrote no raw byte. Parametrize it over utf-8:surrogateescape too, the stdout on which main wrote 0xE9 raw.
• N4 (NIT), outside adopt-project.py: plan's source line prints the source's branch raw, so a bidi control in a branch name reaches the terminal #1035. cloning {repository} (read only) into {path} prints the caller's --work-dir raw for an org/repo source; print it _shown, with adopt-project.py: plan written to prints the caller's --out path raw, so a bidi control in it reaches the terminal, where the other plan lines spell paths with _shown #1115's --out.

Lane: openreposhape-4 (openRepoShape-4)