[brettheap]

Lane: openreposhape-4 (openRepoShape-4)
Claim: #532 (comment)

What changed and why

Brett Heap ruled that the tools print POSIX-quoted commands and that README says so. These are the lines that still concatenated a root or a path, so they pasted as two arguments under sp ace/, as a quotation nothing closes under it's/, and with $x expanded away under d$x/. Measured on 45e01f4, --add notes/shape notes.md pasted as printed was refused unrecognized arguments: notes.md. Two commits: 9d8ee915 is the change, c2e19022 is the fix round after R588's review (the README sentence was not true of family.py).

scripts/bump-leg.py (4 lines)

• _switch_command (:1123) spells git -C <root> switch -c bump/<role>-<id> once, with shlex.join, for bump-leg-root-detached (:1161) and bump-leg-on-tracking-branch (:1171), which put str(root) in bare, and for the dry run's hint (:1664, bump-leg.py --dry-run, step 1 of advancing a leg, is refused bump-leg-on-tracking-branch on every fresh project, before the old -> new line the human is to read #477), which already was quoted. One function, so the three keep naming the same branch the same way.
• The closing NEXT git -C <root> push -u origin <branch> (:1696) is shlex.join.
• Fix round: _restore_leg_if_moved's LegNotAsFound told a person to read `git -C <leg> status` with the leg's path bare, the last paste line in the file that was (:1381). It is shlex.join now, inside the backticks.

update-shape.py (each path shlex.quoted, the checkout through _by_hand, the file's own rule)

• cmd_check's ADDED UPSTREAM --add <path> (:2134).
• commit_on_branch's update-branch-exists remedy, git -C <root> checkout <branch> (:2468).
• _refuse_local_drift's --accept-local <path> (:3158) and _note_untaken_additions' pass --add <path> (:3177).
• Display only, same class: accept_local_exit (:1921) and keep_local_exits (:1939).
• A name that needs no quoting prints as it always did, so every existing assertion that pins a plain path stands.

shape-doctor.py quote_arg (ride-along, :720): a word that begins with = is quoted in sh's dialect, as repo_shape.shell_quoted does. zsh, macOS's login shell, expands a bare =word to a command's path (zsh -f -c 'echo =ls' prints /usr/bin/ls, =x stops with x not found). PowerShell's dialect is unchanged: it expands no =word (R588 read PowerShell 7.4.6's tokenizer to confirm; no pwsh on the host). The family test that holds the two quoters to one answer keeps its leading-= exception for nt alone.

README.md and docs/handbook.html: one sentence at the end of "Windows, natively" (README.md:155-157) and of the Windows panel's last paragraph (docs/handbook.html:726-730):

Printed commands are quoted for a POSIX shell, so paste them into Git Bash. Only shape-doctor.py's lines, setup-project.py's family lines and family.py's NEXT, switch -c, add and git rm -r --cached lines are quoted for PowerShell, on Windows.

• The fix round made it exactly true. R588 measured that family.py also prints, in the host's dialect (repo_shape.shell_line/shell_quoted): the switch -c remedy of family-holder-detached and family-on-tracking-branch and the dry run's branch line (_switch_command, :672-676, used at :690 and :724), the add remedy of family-holder-already-here (_add_command, :911-919, used at :1014 and in init's NEXT STEPS), and member-path-taken's git rm -r --cached (:2006-2016). On Windows that dialect leaves a plain root bare, so pasting one into Git Bash gave git -C C:workOrbitOrbit ... for any Windows root. The dry run's branch line is a switch -c line, so it needs no words of its own.
• Not named, because POSIX (shlex, or 'posix' forced): family.py's by-hand rollback lines (:3175-3195, :3545-3606, including git rm -q --cached, which is why the sentence spells git rm -r --cached in full), the module-store rm -rf (:2112), git config --unset-all (:2071, :4449) and the lock's rm -f (:4502); and all of siblings.py (shlex.join, on purpose, :777-785).
• "Git Bash", no longer "Git Bash or WSL2". The sentence sits in "Windows, natively", where every printed root and interpreter is a Windows path ('C:\work\Atlas'), which a WSL2 shell cannot open. WSL2 has its own section. Brett's chosen option said "Git Bash or WSL"; the coordinator tells him.
• README.md is 1427 lines before and after, which is the cap with lane 3's tests/readme-cap.d/550.txt (1422 + 5). No cap file is added. To make the room: the Microsoft Store python paragraph went from 3 lines to 2 (round 0), the stdin paragraph from 8 to 7 (round 0), and the Store paragraph is joined to the "Two commands rather than one pipe" paragraph after it, which saves its blank line (fix round). Meaning unchanged.
• docs/handbook.html: stop every README PR rewriting the handbook's README blob and line cap, so open README PRs stop conflicting with each other #519 rules that applied: the seven <!-- reads README.md § Starting a project in a new organisation: blob ... --> markers (masthead, start, partway, ci, legs, doublepin, park) move to the section's new blob, 20dfa48f...; the README cap holds at 1427; the footer's history is frozen (HANDBOOK_HISTORY_CLAUSES) and README.md blob is retired, so no clause or hash is added there. AGENTS.md is unchanged (490 lines): no line in it says the opposite. docs/cli.md is unchanged: no --help text moved.

Brett's ruling

"README; doctor exempt" (Brett Heap, 2026-10-14T23:54:30Z). The option he chose said: "One sentence in README's "Windows, natively" section and its handbook mirror. It says printed commands are POSIX-quoted, for Git Bash or WSL, and that shape-doctor.py also quotes for PowerShell when run on Windows. README stays at 1422 lines (reflowed). #532 waits for lane 3's #551 (README section hashes)."

The sentence names more than the doctor, because the doctor is not the only tool that quotes for PowerShell on Windows on main. A sentence that named only the doctor would be false of two more, and the coordinator tells Brett.

• scripts/family.py prints its NEXT lines, its switch -c, add and git rm -r --cached remedies and its dry run's branch line through repo_shape.shell_line/shell_quoted (:158, family.py: init refuses to land in the standard's checkout and names a runnable scripts/family.py, printed commands quote paths, and add, bump and remove refuse the tracking branch and print their branch's push (#488, #486, #487) #507), which spell PowerShell's way when os.name == "nt" (repo_shape.py:3009).
• setup-project.py spells the family lines of its Next: block with its own shell_word (:2102-2141, 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), and tests/test_family_printed_quoting.py holds it to the same answer.
• templates/family-root/scripts/siblings.py is not named, although the first brief expected it: it prints with shlex.join, on purpose, so a holder with an older repo_shape.py still runs (:777-785), and says "in a POSIX shell (Git Bash on Windows)" (:762).
• Two differences from the ruling's text, both the coordinator's to tell Brett: the sentence says "Git Bash" and not "Git Bash or WSL" (above), and it lists lines and not tools where a tool only quotes part of its output for PowerShell.
• The doctor's own quoting is not touched, and no PowerShell form is added anywhere else.

Tests

Background runs, one basetemp, test identities, frvenv first on PATH, -q -p no:cacheprovider -o tmp_path_retention_policy=failed -rfs.

Round 0 (9d8ee915): the command is in the first PR body; 1339 passed, 4 skipped in 15:42, then tests/test_repo_hygiene.py tests/test_readme_sections.py over the final README and handbook, 129 passed.

Fix round (c2e19022), once, over the files this round touches and the ones that pin what it touches:

pytest tests/test_bump_leg_paste_lines.py tests/test_update_shape_paste_lines.py tests/test_readme_windows_quoting_sentence.py \
  tests/test_bump_leg_rollback.py tests/test_bump_leg.py tests/test_bump_leg_dry_run_tracking.py tests/test_bump_leg_dry_run_truth.py \
  tests/test_family_printed_quoting.py tests/test_update_shape_next_quoting.py tests/test_doctor_next_is_a_command.py \
  tests/test_repo_hygiene.py tests/test_readme_sections.py tests/test_agents_md_codes.py

524 passed, 1 skipped in 2:04 (test_bump_leg.py:693: needs a case-insensitive disk). zsh, dash and bash are on the host. Not run on Windows or macOS.

• New tests/test_readme_windows_quoting_sentence.py (3): README's sentence is in its "Windows, natively" section once; the handbook's panel-windows, with its tags stripped and its whitespace one space, says it word for word (a README-only change with the markers re-hashed passed every test before this); and the shipped .py files that call a quoter that follows the host (quote_arg, shell_quoted, shell_line, shell_word, none forced to 'posix'), read with ast, are exactly shape-doctor.py, scripts/family.py and setup-project.py. A fourth is a fault until the sentence names it. Not brittle to setup-project.py: paste lines quote each path, the scaffold's NEXT STEPS wait for step (7), step (3) refuses a file above the clone, -- --dry-run ends at the plan, step (4) hears passed pins, and the upstream guard ignores case (#538) #569 or family.py: add refuses, before the member is read and on every disk, any path under another spelling of members/, in its index, in HEAD or on disk, and names a remedy per entry that never moves the members' checkouts (#362, #363, #364) #574: a call that passes 'posix' or posix=True is not counted.
• tests/test_bump_leg_paste_lines.py (33 now): the closing NEXT for a branch named bump/it's, wip$x and fix/a;b (its last word is the branch; pasted, the line pushes that branch to the root's own remote); and _restore_leg_if_moved called in-process on a leg under sp ace/, it's/ and d$x/ (the backticked command splits into git -C <leg> status, and pasted into sh it reads that leg). tests/test_bump_leg_rollback.py asserts the same spelling, built with shlex, so it holds on a Windows root.
• tests/test_update_shape_paste_lines.py:388: the row is built before pytest.raises, so only _refuse_local_drift is inside the block (Sonar S5778).
• Existing assertions edited in place: tests/test_bump_leg_dry_run_tracking.py (the byte-for-byte refusal, round 0), tests/test_family_printed_quoting.py::test_it_is_the_doctors_rule_on_any_ascii_value (round 0), and tests/test_bump_leg_rollback.py:466 (this round).
• Mutants, each killed (one source mutation at a time, files put back byte for byte, sha256 checked; driver in the writer's scratch):

mutant	tests	failed
M1 bump-leg _switch_command unquoted	bump paste	12
M2 root-detached remedy bare	bump paste	7
M3 on-tracking remedy bare	bump paste	7
M4 closing NEXT bare	bump paste	12
M5 update-shape ADDED UPSTREAM --add bare	update paste	4
M6 --accept-local in the drift refusal bare	update paste	4
M7 update-branch-exists checkout bare	update paste	6
M8 pass --add bare	update paste	6
M9 the both sentence bare	update paste	3
M10 the locally-modified sentence bare	update paste	3
M11 quote_arg's leading-= rule dropped	family quoting	6
R1 (R588) NEXT quotes the root, leaves the branch bare	bump paste	6
R3 (R588) README drops family.py, markers re-hashed	docs	1
M12 the leg's status line bare	bump paste + rollback	6
M13 handbook alone drops git rm -r --cached	docs	1
M14 bump-leg.py calls shell_line (a fourth host-dialect tool)	new docs test	1
M15 README says "Git Bash or WSL2" again, markers re-hashed	docs	1

Out of scope

• shlex.quote("=x") returns =x bare, so update-shape.py, bump-leg.py and adopt-project.py keep the zsh = gap, and scripts/repo_shape.py:3005-3006 still says quote_arg "still leaves it bare": stale for sh now, but repo_shape.py is a copied shape file, so a docstring edit re-pins every project. Both go on Tracking: shape-doctor.py, reporting a repository's compliance #460's checklist.
• The shipped validate-pins.py and validate-family.py, and adopt-project.py's lines: the documentation sentence answers them, and they do not change.
• setup-project.py's cd <clone> (:2169) is printed bare; setup-project.py: paste lines quote each path, the scaffold's NEXT STEPS wait for step (7), step (3) refuses a file above the clone, -- --dry-run ends at the plan, step (4) hears passed pins, and the upstream guard ignores case (#538) #569 already quotes it (shell_word(clone, posix=True)).
• A path holding a newline prints quoted across two lines; no real root has one.
• The handbook's own "Two commands rather than one pipe" and Microsoft Store paragraphs keep their longer wording: only README.md is line-capped.

Shared files

git merge-tree --write-tree of this head (c2e1902), each head re-read with git ls-remote first:

• origin/main f5fc7056 (includes update-shape.py: apply refuses to rewrite a file that has a second, hard-linked name, and a rollback that cannot put a byte back names it with the line that finishes it and puts back the rest (#422, #428) #560 and openRepoShape --doctor says it writes nothing into the repository but a --placement-plan file you name, keeps its clone for the NEXT lines that name it, shows its synopsis description again, and refuses a second --placement-plan or a second path (#546) #580): clean, tree 927d96ee.
• shape-doctor.py: a validator's verdict is a printed FINDING or REFUSED and any other non-zero exit is a crash, so a gate killed by a signal, ended by os._exit(1), holding conflict markers or failing argparse no longer "reports a finding", a crash of the standard's own naming script is CANNOT ANSWER instead of INVALID (naming), and a pass that printed WARNING or note lines is a note quoting them while a red row quotes its finding and never a warning (#410, #448) #557 65b11898: clean, 46d20a69.
• shape-doctor.py: the legs and members NEXT names every detached commit it would move, and sends a mount with no .git of its own, an unborn HEAD, a mount git finds no url for, and a leg with its own lockstep fact to a line that cures it or to none (#413, #414) #559 66a93539: clean, 1e00a89d.
• shape-doctor.py: a conflicted shape pin's NEXT takes whole every copy both sides hold as the standard wrote it at their own pin, and a leg pin put back from before its bump says to commit it and run the pins row's bump-leg.py line (#547) #586 2ca4044f: clean, 993d9c84.
• shape-doctor.py: manifest kinds prints one command for its NEXT, the git rm, git clean or git status its files need as git has them, where it printed prose joined by ; whose backticks ran family.py in zsh, and counts a manifest validated only at a path its gate reads, so a contracts/<x>-pin.yaml no leg or product names is a FINDING (#548, #439) #555 c04ff8ad: clean, ec5e6939.
• validate-repository-naming.py, repo_shape.py, validate-pins.py: a bare --link-source is the first chain link's tree alone, and a source that names no path is refused (#441, #442) #576 a707d4ba: clean, e5ced435.
• siblings.py and family.py: make siblings asks about the family folder before it clones, clones each member on its tracking branch, and family.py siblings runs the holder's own copy (#543) #578 8d3d1cce: clean, 8bb2de52.
• The 13 other open main-based PRs, swept the same way: clean, except adopt-project.py: check finds, and execute refuses before any leg, the branch names execute failed on, so adopt_branch: a..b, a source branch Adopt or one hidden by hideRefs no longer pass check and fail after both legs exist (#520, #420) #583 (adopt-project.py), which conflicts with main itself and not with this PR (merge-tree of main with it conflicts in adopt-project.py too).
• install.sh and openRepoShape --install, carried into main from v1.0.1 (#577): the one line curl -fsSL https://github.com/opensoft/openRepoShape/releases/latest/download/install.sh | bash installs the newest release's command pinned to that release, installs git-filter-repo with pipx where it can, and ends with the preflight (#564) #587 5191f0eb (lane 3, l3-564-carry-to-main) conflicts in docs/handbook.html at the seven § Starting markers, and in nothing else. README merges clean (1449 lines, install.sh and openRepoShape --install, carried into main from v1.0.1 (#577): the one line curl -fsSL https://github.com/opensoft/openRepoShape/releases/latest/download/install.sh | bash installs the newest release's command pinned to that release, installs git-filter-repo with pipx where it can, and ends with the preflight (#564) #587's cap 564.txt). Whichever of install.sh and openRepoShape --install, carried into main from v1.0.1 (#577): the one line curl -fsSL https://github.com/opensoft/openRepoShape/releases/latest/download/install.sh | bash installs the newest release's command pinned to that release, installs git-filter-repo with pipx where it can, and ends with the preflight (#564) #587 and this lands second makes a marker-only merge: for these two heads the merged blob is e3d9e463...; recompute it at landing.
• install.sh and openRepoShape --install: one line, curl -fsSL https://github.com/opensoft/openRepoShape/releases/latest/download/install.sh | bash, installs the newest release pinned to it, with git-filter-repo, and ends with the preflight, and the installed command stays on its release (#564) #577 targets release/v1.0, not main (lane 3's v1.0.1 patch). It conflicts with main itself in docs/handbook.html and tests/test_repo_hygiene.py, and touches none of this PR's hunks.

Closes #532

🤖 Generated with Claude Code

Summary by Sourcery

Make generated command guidance safe to paste across POSIX shells and accurately document its Windows shell behavior.

Bug Fixes:

• Quote roots, paths, branch names, and rollback commands in bump-leg.py and update-shape.py so printed commands remain safe to paste in a POSIX shell.
• Quote leading '=' arguments in shape-doctor.py's POSIX dialect to prevent zsh command-path expansion.

Enhancements:

• Document which generated commands target POSIX shells and which Windows-specific lines use PowerShell quoting.
• Keep the README and handbook Windows guidance synchronized and update the handbook's README section hashes.

Documentation:

• Clarify that printed commands should be pasted into Git Bash and identify the commands that use PowerShell quoting on Windows.

Tests:

• Add coverage that validates printed commands with spaces, quotes, dollar signs, special branch names, and leading-equals arguments across shell parsing and paste scenarios.
• Add tests ensuring the README and handbook quoting guidance stays synchronized and accurately names host-dialect quoting tools.

[sourcery-ai]

Reviewer's Guide

The PR makes printed remediation, NEXT, and path-bearing commands safely pasteable by applying POSIX-aware quoting, closes shape-doctor's leading-equals gap for zsh, and documents the resulting shell-specific command conventions in the README and handbook, with extensive regression and integration coverage.

Sequence diagram for quoting and pasting a remediation command

sequenceDiagram
    actor User
    participant Tool as bump-leg.py or update-shape.py
    participant Shell as POSIX shell
    participant Git
    User->>Tool: Run check or bump command
    Tool->>Tool: shlex.join or shlex.quote
    Tool-->>User: Print quoted remediation or NEXT command
    User->>Shell: Paste printed command
    Shell->>Git: Execute command with preserved root, path, and branch arguments
    Git-->>User: Perform checkout, switch, push, or apply

Loading

Flow diagram for safely pasteable printed commands

flowchart LR
    Tool[bump-leg.py or update-shape.py] --> Quote[POSIX quoting]
    Quote --> Command[Printed remediation or NEXT command]
    Command --> Shell[Git Bash or WSL2]
    Shell --> Args[Original paths and roots preserved as single arguments]

Loading

File-Level Changes

Change	Details	Files
Quote previously concatenated roots, branches, and paths in commands and remediation text so pasted output preserves intended POSIX-shell argument boundaries.	Centralize bump-leg branch creation command formatting with shlex.join and quote the closing push command. Quote update-shape --add, checkout, --accept-local, pass --add, and display-only command paths. Add paste-oriented coverage for spaces, apostrophes, dollar signs, Windows roots, and unchanged plain paths.	scripts/bump-leg.py update-shape.py tests/test_bump_leg_dry_run_tracking.py tests/test_bump_leg_paste_lines.py tests/test_update_shape_paste_lines.py
Make shape-doctor's POSIX quoting safe for zsh while preserving its PowerShell behavior.	Quote leading-equals words for the POSIX dialect because zsh expands bare =word values. Keep leading-equals values bare for the PowerShell dialect and narrow the cross-quoting exception accordingly. Add unit and real-shell tests covering leading equals, other equals placements, and sh/bash/zsh round trips.	shape-doctor.py tests/test_family_printed_quoting.py
Document the shell dialect and tool-specific exceptions for printed commands in the README and handbook mirror.	State that general printed commands target POSIX shells and should be pasted into Git Bash or WSL2. Identify shape-doctor, family NEXT lines, and setup-project family lines as the Windows PowerShell exceptions. Update handbook section hashes and tighten two README paragraphs to preserve the 1427-line cap.	README.md docs/handbook.html

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#532	Quote the identified bare paste lines in bump-leg.py and update-shape.py so roots and paths containing spaces, apostrophes, or shell-special characters are passed as single arguments.	✅
#532	Document that printed commands use POSIX-shell quoting and identify the supported shell context, rather than implying they paste in PowerShell.	✅
#532	As the ride-along, make the doctor's POSIX quoter quote a leading = so zsh does not expand it as a command path.	✅

Possibly linked issues

• Printed commands are POSIX-only: quote the bare paste lines in bump-leg.py and update-shape.py, and say in the docs that pasted commands are for a POSIX shell #532: The PR quotes the specified bump-leg and update-shape commands and adds the requested POSIX-shell documentation sentence.
• Printed commands are POSIX-only: quote the bare paste lines in bump-leg.py and update-shape.py, and say in the docs that pasted commands are for a POSIX shell #532: The PR quotes the listed bump-leg and update-shape commands and paths for POSIX shells, directly fixing issue Printed commands are POSIX-only: quote the bare paste lines in bump-leg.py and update-shape.py, and say in the docs that pasted commands are for a POSIX shell #532.
• Printed commands are POSIX-only: quote the bare paste lines in bump-leg.py and update-shape.py, and say in the docs that pasted commands are for a POSIX shell #532: The PR directly addresses Printed commands are POSIX-only: quote the bare paste lines in bump-leg.py and update-shape.py, and say in the docs that pasted commands are for a POSIX shell #532 by quoting previously unsafe printed commands and documenting POSIX versus PowerShell command targets.

---

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
1 New issue
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 1 day and 4 hours by commenting @sourcery-ai review. Upgrade to get a review now.