[brettheap]

Lane: openreposhape-4 (openRepoShape-4)

Claim: #454 (comment) and #629 (comment)

What changed and why

Two issues, one writer, because both rewrite the header lines of templates/family-root/scripts/siblings.py.

#454: make siblings, park and resume print what a manifest says and are never ended by it. The two reports opened with a plain print of family.yaml's name: (_run_placement, dispatch_all) and every member row was printed raw. On main 8f453d0e, name: "a\ud83db" (a lone surrogate) ended siblings.py --dry-run in UnicodeEncodeError (exit 1), make siblings, make park and make resume in exit 2, and make park parked nothing; the line holds a literal dash, so under PYTHONIOENCODING=ascii it raised for every name, InkRouter included; a raw ESC or CR reached the terminal as the control it is. All of it reproduced first, in a real holder from family.py init into local remotes.

The house pattern is #391's (ec4a7a0e), done in the same words: escape_unencodable_stdout() is the first statement of main, and spelled() goes round every value a line prints that a manifest, a member row or a disk gave. Both are #391's, in scripts/repo_shape.py; siblings.py adds them to the from repo_shape import line it already has and defines neither. Spelled: the name and root (both headers), the folder and the link, a member's project, path, url and the reason its tracking branch is not known, Sibling.row's project and branch, the FINDING lines' project, directory, origin and --make-args, and the member's own [project] and --- lines. The member's own make is still handed the RAW target, the mv lines a person pastes stay quoted and unspelled, and git's own words are left as git wrote them. A plain name prints exactly what it printed before (a golden of both runs' whole output, which passes on the base too).

#629: the holder's README names its folder after the repository. family.py init --family Quill --name QuillWorks wrote a README that said cd QuillWorks and laid out QuillWorks/QuillWorks, while family_folder_name asks for the repository's name, Quill: a holder laid out as its README said got WARNING the holder's parent folder is 'QuillWorks', not 'Quill', cloned nothing and make exited 2.

• templates/family-root/README.md names the folder with {{FAMILY}}, a placeholder family.py init already fills with --family (the same string family_folder_name reads from repository:): the cd, the two layout lines and the doubled-name sentence, plus one sentence saying both are named after the REPOSITORY and the display name names no folder. {{FAMILY_NAME}} stays only as the README's title. No new placeholder; scripts/family.py is not touched (lane 2's scaffold-project.py and family.py: both runs ask whether each folder they make can be made and take only gh's not-found answer as "absent", so --dry-run refuses a file where a folder goes, or a gh repo view that fails otherwise, by name as the real run does, and a refused init leaves no empty family folder (#609) #622 and lane 4's family.py: add, bump and remove refuse before their first write a merge, cherry-pick, revert, rebase or git am in progress, a .gitmodules, members/ or family.yaml the sparse checkout leaves out, and a file named members, which each failed after writing and was rolled back, or committed in the wrong place (#612) #626 are in flight there).
• templates/family-root/AGENTS.md is unchanged on purpose: the issue's lines 3 and 7 use {{FAMILY_NAME}} as a title (the family holder **X**, X's own) and name no folder.
• siblings.py says which name it means: where name: and the repository's name differ, the placement header gets one line under the folder's own, on a stopped run and a passing one alike (the folder is named after the holder's REPOSITORY, Quill, and never after name: QuillWorks, which is only a display name); where they are one string nothing is added. The module docstring says which name <Family> is. --make asks nothing of the folder and keeps its header.

Pinned shape copies. templates/family-root/scripts/siblings.py is in FAMILY_COPIED_VERBATIM and digest-pinned in every holder, so a holder that re-syncs reads upstream-changed for it. No digest or blob of it is recorded in this repository (#578 changed the file with no pin edit, as #391 did for bootstrap.py). README.md of the family root is templated, not pinned. scripts/repo_shape.py is not changed. A holder that keeps its own repo_shape.py without the two names siblings.py now imports is refused by apply as update-accept-local-missing-name (#536), which already counts siblings.py among the importers. No --help text moved, so docs/cli.md is unchanged; AGENTS.md, README.md and the handbook say nothing this makes false.

Tests

New file tests/test_siblings_family_name.py, 150 tests, on the harness of test_bootstrap_spelling.py (stdouts answered in bytes and decoded strictly in the encoding given; imports its helpers and family_template) and test_family.py (a real holder with a scaffolded member, local bare remotes, no gh):

• the first line of siblings.py --dry-run and --make park --dry-run under utf-8:strict, utf-8:surrogateescape, cp1252:surrogateescape, cp1252:strict, ascii:strict and utf-8:replace: a lone surrogate, ESC and CR, 日本, a Persian name with its ZWNJ (raw, as on main), and the rest of templates/assembly-root/scripts/bootstrap.py and templates/family-root/scripts/bootstrap.py: main prints the manifest's name with a plain print before any step runs, so name: "a\ud83db" (a lone surrogate) ends make bootstrap in a UnicodeEncodeError traceback, exit 1 (make: 2), and the validator that names the problem is never reached; a valid name the stdout cannot encode ends the same way #391's name rows; the control InkRouter under every stdout; byte-identity with the plain print for the names that printed raw; the whole output of both runs for a plain holder; make siblings, make park and make resume on a lone-surrogate name;
• member rows: an ESC in a project name or a U+2028 in a path with the member not checked out (placement and dispatch); then a real clone whose directory holds U+2028: the clone line, the member's own bootstrap header, present, the branch column, NOT A CLONE, WRONG ORIGIN (the origin itself holds a separator), and --make (header, would run, a failing verb), each run for real or dry;
• family.py init --name: the holder's README and AGENTS.md name its folder after the display name, where make siblings needs the repository's name, so a holder laid out as its README says clones nothing #629: a holder made with --family Quill --name QuillWorks; its README's cd, folder and holder lines read OUT OF THE README TEXT and followed (the holder cloned into the folder it names, cd into the directory it names), then scripts/siblings.py and make siblings clone the member beside it with no WARNING; the display name appears once, as the title; the old QuillWorks/QuillWorks layout is still refused, nothing cloned, and the run says which name it means.

Against main 8f453d0e (the new file with the unfixed templates): 85 failed, 65 passed; the 65 are the byte-identity, plain-golden and fixture-sanity rows that must pass there too.

Targeted run (log /tmp/claude-1000/-workspace-projects-openRepoShape/11c6c0ef-495a-4a05-94cf-811b7b0a1012/scratchpad/k454/final-run.log, run over the same bytes as this commit): the new file; test_family.py, test_family_siblings_placement.py, test_family_makefile_siblings.py, test_family_printed_quoting.py, test_park_resume_targets.py, test_family_tracking_branch.py, test_family_init_values.py, test_family_init_landing.py, test_free_plan_hint.py, test_template_values_single_pass.py, test_template_text_placeholders.py, test_template_quoted_values.py, test_update_shape.py, test_update_shape_add.py, test_update_shape_kept_helper.py, test_bootstrap_spelling.py, test_windows_paths.py, test_scaffold_leg_path_collisions.py, test_shape_doctor.py, test_repo_hygiene.py, test_cli_reference.py, test_agents_md_codes.py: 2081 passed, 22 skipped, exit 0. The skips are test_family_init_values.py:219 (16) and :291 (3), whose templates quote the placeholder, and test_shape_doctor.py:9965 (3), a PowerShell line that needs a Windows host.

Mutants (each reverts one part of the fix, run over the new file):

mutant	result
main without escape_unencodable_stdout()	killed, 40 failed
family_folder_name prefers name: (R605's M4, which survived 166 tests)	killed, 70 failed
the README's cd {{FAMILY}} back to cd {{FAMILY_NAME}}	killed, 4 failed
the member would clone line prints the raw project, url and path	killed, 2 failed
family_name_note returns nothing	killed, 2 failed
Sibling.row prints the project raw	killed, 10 failed

What it cannot tell

• A REAL run over a member whose project name holds a lone surrogate still ends in a UnicodeEncodeError where place hands the name to git clone as an argument (--dry-run is fine and spelled). That is a manifest value passed to git rather than printed, templates/assembly-root/scripts/bootstrap.py and templates/family-root/scripts/bootstrap.py: main prints the manifest's name with a plain print before any step runs, so name: "a\ud83db" (a lone surrogate) ends make bootstrap in a UnicodeEncodeError traceback, exit 1 (make: 2), and the validator that names the problem is never reached; a valid name the stdout cannot encode ends the same way #391's own "left out" class (assembly-root bootstrap.py: a lone surrogate or NUL in tracking_branch (or a leg's branch:) ends make bootstrap in a subprocess traceback in step (a), and validate-manifest.py says manifest ok, so no tool names it #455); reproduced on this head, not fixed here.
• parent_folder_warning's prose lines (the holder's path, the parent folder) print raw on stderr, as does its mv command, which has to run as typed (family.py and siblings.py print commands with unquoted paths, so under a folder with a space the member-git-dir-cached remedy's rm -rf would delete the wrong directory, and add's push line fails #486). Not a function either issue names.
• The README is templated, not pinned: a holder that already exists keeps the README it was made with (cd QuillWorks). What reaches it is siblings.py, through update-shape.py apply, whose new header line says which name it means.
• AGENTS.md and AGENTS-shape.md say "named after the family", which has always been --family's name; left as they are.

Shared files

git merge-tree --write-tree of this head 1a42df41 (read from ls-remote just before) against main 4cf5fb07 and each open PR head: clean (exit 0) against main and #590, #620, #621, #622 (5263d788 at the first read, 227bc3b0 now), #623, #626 (207d4e1d), #627, #628, #630 (82f9403d, which lists templates/family-root files), #631, #632, #633, #634, #635, #636, #637 (a2776959, which also lists templates/family-root/README.md), #638, #639. #599 conflicts in .github/workflows/tests.yml, README.md, docs/handbook.html, install.sh, openRepoShape and tests/test_install_sh.py, and main alone conflicts with it in those six and in tests/test_openreposhape_command.py too; none of them is this PR's file. Main moved from 8f453d0e to 4cf5fb07 while this was written (#583, #614, #618, #619, #596, #594, #617); git diff --name-only between them names none of this PR's three files.

Closes #454
Closes #629

🤖 Generated with Claude Code

Summary by Sourcery

Make family sibling operations robust for unusual text and consistently base holder-folder naming on the repository name.

Bug Fixes:

• Prevent sibling placement and dispatch commands from failing or emitting unsafe terminal control characters when manifest, member, path, branch, or URL text cannot be safely written to stdout.
• Align the family-root README and sibling layout checks on the repository name rather than the display name, including clear messaging when the names differ.

Enhancements:

• Add explicit output explaining which family name determines the holder folder while preserving raw values for filesystem paths and executed commands.

Documentation:

• Update the family-root README to describe the repository-based folder layout and distinguish it from the display name.

Tests:

• Add comprehensive coverage for output spelling across encodings and unusual Unicode/control characters, sibling placement and dispatch behavior, and repository-versus-display-name folder layouts.

[sourcery-ai]

Reviewer's Guide

Updates siblings.py to safely spell all user-controlled output without changing raw filesystem or command arguments, preventing traceback failures under problematic names and encodings, while standardizing holder-folder documentation and validation on the repository name instead of the display name; adds comprehensive regression coverage for both issues.

Sequence diagram for safe siblings output and member operations

sequenceDiagram
    participant CLI
    participant Siblings as siblings.py
    participant RepoShape as repo_shape.py
    participant Filesystem
    participant GitOrMake as git_or_make

    CLI->>Siblings: main(argv)
    Siblings->>RepoShape: escape_unencodable_stdout()
    Siblings->>Filesystem: load manifest and inspect members
    Siblings->>RepoShape: spelled(manifest_and_disk_values)
    RepoShape-->>Siblings: printable text
    Siblings->>GitOrMake: raw paths, targets and arguments
    GitOrMake-->>Siblings: operation result
    Siblings->>RepoShape: spelled(result_summary_values)
    Siblings-->>CLI: safe status output

Loading

Flow diagram for repository-based family folder validation

flowchart TD
    Init["family.py init --family Quill --name QuillWorks"] --> Manifest["family.yaml: repository = Quill, name = QuillWorks"]
    Manifest --> Folder["family_folder_name uses repository name: Quill"]
    Folder --> README["README documents Quill/Quill and cd Quill"]
    Folder --> Check{"Holder parent folder is Quill?"}
    Check -->|yes| Place["Clone members beside holder"]
    Check -->|no| Warning["Warn, print mv command, stop without cloning"]

Loading

File-Level Changes

Change	Details	Files
Make all manifest-, member-, and disk-derived text printed by siblings.py safe and unambiguous across stdout encodings and terminal controls.	Initialize stdout escaping before argument parsing or any output. Route printed names, paths, URLs, branches, findings, command previews, and member rows through the shared spelled() helper while preserving raw values for filesystem and subprocess operations. Use the shared escape_unencodable_stdout() helper to prevent UnicodeEncodeError failures in siblings, park, and resume. Add extensive encoding, control-character, surrogate, dry-run, real-clone, and dispatch coverage.	templates/family-root/scripts/siblings.py tests/test_siblings_family_name.py
Align the family-root README and siblings.py folder semantics around the repository name rather than the display name.	Change README folder, cd, layout, and doubled-name text to use {{FAMILY}}, leaving {{FAMILY_NAME}} only for the title. Keep family_folder_name based on the manifest repository and add a note when repository and display names differ. Document and test the Quill/QuillWorks layout, including refusal of the legacy doubled-display-name layout and successful cloning from the README-described layout.	templates/family-root/README.md templates/family-root/scripts/siblings.py tests/test_siblings_family_name.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#454	Make siblings.py's placement and dispatch reports—including make siblings, make park, and make resume—safe to print for arbitrary family names and member-row values: avoid encoding tracebacks on restrictive stdout encodings and spell terminal controls and unencodable characters.	✅
#629	Make the holder README name its folder after the holder repository, so the documented layout passes the folder check and make siblings clones members.	✅
#629	Clarify which family name siblings.py uses when the display name differs from the repository name, and test the documented layout with a real holder and member clone.	✅

Possibly linked issues

• family.py init --name: the holder's README and AGENTS.md name its folder after the display name, where make siblings needs the repository's name, so a holder laid out as its README says clones nothing #629: The PR changes README folder placeholders from display name to repository name and documents the distinction, so the README layout works with make siblings.
• family-root siblings.py: make siblings, park and resume print the family's name with a plain print, so name: "a\ud83db" ends each in a UnicodeEncodeError, and the literal dash ends every name under PYTHONIOENCODING=ascii #454: The PR adds stdout escaping and spelled() handling for siblings.py headers and member rows, directly fixing family-root siblings.py: make siblings, park and resume print the family's name with a plain print, so name: "a\ud83db" ends each in a UnicodeEncodeError, and the literal dash ends every name under PYTHONIOENCODING=ascii #454's encoding errors and raw controls.

---

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

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