[brettheap]

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

Four guards held less than they said. One commit, 151a0861, on 8062810d. No shipped behaviour changes except one environment variable in the generator's --help children. No --help text changes, so docs/cli.md is not regenerated. No quoting changes.

What changed

1. scripts/render-cli-reference.py: child_env() sets PYTHONDONTWRITEBYTECODE=1. The template's siblings.py does from bootstrap import ... from its own directory, so the generator's --help child wrote templates/family-root/scripts/__pycache__/bootstrap.cpython-312.pyc (ignored by git, so silent). A person who runs the generator now gets the same tree as the test that runs it. The docstring says why. tests/test_cli_reference.py gets one test: the variable is in child_env() whatever the caller had, and an interpreter started under that environment reports sys.dont_write_bytecode as true.
2. tests/test_validator_child_encoding.py: the launcher guard sees family.py. interpreter_runs accepts [sys.executable or PYTHON, ...] as well as [sys.executable, ...], and LAUNCHERS gains "scripts/family.py": "inherited_child_environment". Dropping env= from family.py siblings' child (adopt-project.py plan raises UnicodeEncodeError in its terminal report, after the plan file is written, for a printable name stdout cannot encode (日本.md under cp1252, as on a redirected Windows stdout), so plan exits 1 before plan written to #214) now fails the guard.
3. tests/test_readme_windows_quoting_sentence.py: the inventory holds what it claims. It follows from repo_shape import shell_line as joined (and joined = shell_line, however many steps). It scans every file git ls-files lists (tracked, or new and not ignored) that is a .py file or starts with a python shebang, which adds the root bootstrap. It pins functions, not files, for the two tools the sentence names by particular lines: scripts/family.py (_print_next, _switch_command, _add_command, _print_next_steps, _checked_mount_path) and setup-project.py (family_next_command). shape-doctor.py stays every line, because the sentence says "shape-doctor.py's lines". Only the bodies of shell_quoted and shell_line in scripts/repo_shape.py are exempt, by name; the rest of that file is not. Nothing about quoting changes: the Git Bash dialect (option (a)) is its own v1.1.1 issue, and when it moves NAMED, this table moves with it.
4. tests/test_bump_leg_paste_lines.py: Sonar S5778. placement = bump_leg_module.leg_placement(leg) before the with pytest.raises(LegNotAsFound) in test_pasting_the_status_line_reads_that_leg, as the test above it does. Five lines; the hunk is :401-405, away from bump-leg.py and setup-project.py: the git switch -c line says under it what to do where an earlier act left that branch, so already exists is no dead end (#607's sentence, in the two tools it left) #657's hunks.

Evidence

The reproduction (.pyc). In a fresh shared clone at 8062810d, with PYTHONDONTWRITEBYTECODE unset, python3 scripts/render-cli-reference.py --check printed [ok] docs/cli.md is what the generator produces and left five .pyc files, among them templates/family-root/scripts/__pycache__/bootstrap.cpython-312.pyc at 11533 bytes (the size the issue reports). The same command on 151a0861 printed the same [ok] line and left none (find . -name '*.pyc' found 0).

Mutants. Each is applied to a copy at the head's test files; "old" is the same mutant under 8062810d's own tests.

Mutant	New tests	Old tests
M0: drop PYTHONDONTWRITEBYTECODE from child_env() (the base's behaviour)	test_child_env_leaves_no_bytecode_in_the_trees_it_runs fails: KeyError: 'PYTHONDONTWRITEBYTECODE'	none to run
M1: drop env= from family.py's siblings child (scripts/family.py:6543)	test_the_tools_that_run_the_projects_validators_give_them_an_environment[scripts/family.py] fails: scripts/family.py:6543 runs the interpreter without `env=inherited_child_environment()`	55 passed (survives)
V2: from repo_shape import shell_line as joined and a call, in update-shape.py	test_the_tools_that_quote_for_the_host_... fails: files are [family, setup-project, shape-doctor, update-shape]	3 passed (survives)
V3: family.py's _switch_command calls shell_line(..., "posix")	test_the_functions_that_quote_for_the_host_...[scripts/family.py] fails: _switch_command missing from the calling functions	3 passed (survives)
V5: a host-quoter call in the suffixless bootstrap	the file test fails: bootstrap is now among the files	3 passed (survives)
V6 (the exemption): a third function of scripts/repo_shape.py calls shell_line	the file test fails: scripts/repo_shape.py is now among the files	3 passed (survives)

Each new failure is one test, and the other tests of the file stay green (1 failed, 8 passed; 1 failed, 55 passed). V2, V3 and V5 are R588's mutants as the issue describes them.

Tests

On 151a0861, one run, run9.sh (gh stub first on PATH, GH_TOKEN bogus, empty GH_CONFIG_DIR):

tests/test_cli_reference.py tests/test_validator_child_encoding.py tests/test_readme_windows_quoting_sentence.py tests/test_bump_leg_paste_lines.py tests/test_family_siblings_placement.py tests/test_repo_hygiene.py: 227 passed in 698.59s.

Per file: test_cli_reference.py 23 (one new), test_validator_child_encoding.py 56 (one new case, [scripts/family.py]), test_readme_windows_quoting_sentence.py 9 (6 new: the scripts/family.py and setup-project.py function pins, the alias, the method name, the exemption, the suffixless file), test_bump_leg_paste_lines.py 33, test_family_siblings_placement.py and test_repo_hygiene.py 106 together.

Merge checks (git merge-tree --write-tree HEAD <ref>)

• origin/main 35133f29 (includes bump-leg.py and setup-project.py: the git switch -c line says under it what to do where an earlier act left that branch, so already exists is no dead end (#607's sentence, in the two tools it left) #657 as 78fe3fff, which edits tests/test_bump_leg_paste_lines.py at :53, :235-244 and setup-project.py): clean. On the predicted merge commit, test_readme_windows_quoting_sentence.py and test_validator_child_encoding.py pass (65 passed), and so does test_bump_leg_paste_lines.py (33 passed). family_next_command is still the only function in setup-project.py that calls shell_word.
• README, AGENTS.md, docs/cli.md and the handbook: pipx install openreposhape is the second way in and the first on native Windows, git-filter-repo is installed in install.sh's order and never with a bare pip install, and a first draft of the v1.1.0 release notes (#563) #630 (5b140bd3): conflicts in docs/handbook.html only, and it does so against 8062810d and 35133f29 without this commit, so not this change's. It changes scripts/render-cli-reference.py, docs/cli.md and tests/test_repo_hygiene.py; none of those hunks overlaps mine, and merge-tree reports no conflict in them.
• Lane 4's family.py work: the heads I could fetch are family.py: add's refusal of a member's own gitlink held only under another spelling of its row's path moves it back to that path in the index alone, so the printed remedy no longer takes the member's gitlink away from its row (#646) #670 (pr670) and scaffold-project.py and family.py: scaffold-bad-id and family-bad-id name an id derived from --project or --family as derived and say to change that flag, so --project North_Wind no longer says --id 'north_wind' must match and sends the person to an --id the naming policy then refuses (#659) #671; fix/664-surviving-mutants and fix/696-setup-family-folder are on origin too. Clean with each. Lane 4's other family.py branches (family.py add/bump/remove: a members file deleted unstaged, a git bisect, an empty sparse-checkout file, an empty rebase-merge/ and a merge conflicted in family.yaml meet a refusal or remedy that does not fit (#626's gaps) #684, family.py bump: a mount with a narrowed fetch refspec is refused member-to-local-only on a false detail, a commit only a tag holds is told "a pin the rest of the world cannot fetch", a mount with no origin is told to fix the network #686, family.py init: --created-by and GIT_AUTHOR_NAME are never asked whether the manifest can hold them, a whitespace-only GIT_AUTHOR_NAME fails after the remote exists, and a --family a Windows disk cannot hold exactly is accepted #688, family.py: the NEXT push line is a forced refspec for a branch beginning with + and fails for a branch named like a tag, and a tracking branch of 251-255 characters passes --dry-run, dies at the first commit once every remote exists #689, --local-remote-dir: family.py add takes a directory whose name is not UTF-8 into .gitmodules, the clone-URL refusal's remedy misses a link's target and a lone surrogate, and the READMEs' clone line is rendered unquoted #693, update-shape.py apply: a rollback line fails over a read-only contracts/ unsaid, committed on <branch>: lists a path the commit lacks, --branch v1.0.0 cannot push beside a tag v1.0.0, and a quoted "files": header is refused #674) are not on origin and not in the shared .git, so I could not check them. Predicted merges with family.py: add's refusal of a member's own gitlink held only under another spelling of its row's path moves it back to that path in the index alone, so the printed remedy no longer takes the member's gitlink away from its row (#646) #670, scaffold-project.py and family.py: scaffold-bad-id and family-bad-id name an id derived from --project or --family as derived and say to change that flag, so --project North_Wind no longer says --id 'north_wind' must match and sends the person to an --id the naming policy then refuses (#659) #671 and lane 5's fix/646 pass the two guards' files (65 passed each).
• Other open heads touching a tool the inventory reads: setup-project.py: a family folder is named after the holder's REPOSITORY, so the Quill/Quill that family.py init --name QuillWorks makes is detected with no flag, and the QuillWorks/QuillWorks that make siblings refuses is not (#696) #703 and fix/696 (setup-project.py), adopt-project.py: plan refuses --id '' and --elected-by '' by name, a derived id's refusal says to change --project, or in place to rename the source first, and an org read from a url is named as not given (#658) #699 (adopt-project.py), shape-doctor.py: submodule_config and gitmodules_entry read a holder's .gitmodules through one git config -z --list, so a section name holding a space or a byte that is not UTF-8, or a url holding NEL or U+2028, gives the doctor the mount url git and make siblings use, under any locale (#668) #700, shape-doctor.py: a checkout whose own contracts/repository-naming.yaml does not load is CANNOT ANSWER, exit 3, for a project, where it read INVALID (naming), exit 1; any other naming exit 2 "refuses"; and the EXIT CODES list names an unfinished merge (#678) #701, validate-pins.py and shape-doctor.py: one leg's gitlink off its pin beside another leg's digest or workflow reference names the step that comes first, that gitlink put back by hand, and then the other leg's bump-leg.py line, so neither finding says "First clear that finding" over a finding no line can clear first (#677) #702 and shape-doctor.py: the members row says, member by member, what make siblings does with the directory beside the holder, in its own word and in place's order, so it no longer says it places a member it leaves exactly as it is, and it spells every value it quotes, so an ESC or a CR in a url no longer reaches the terminal (#669, #673) #705 (shape-doctor.py), fix/664: clean, and the inventory file passes on each predicted merge (9 passed each). bootstrap.py and validate-family.py: a member no credential would check out fails the family bootstrap, every row's gitlink is asked before any checkout, and --no-members prints the case-variant move (#648) #682, tests/test_doctor_next_is_a_command.py: the comment-tail guard reads each string expression whole, across + and an f-string's pieces, and flags a # led by two or more blanks or a tab with or without a blank after it and a # that opens text after a part that is not a constant, so cmd #x, cmd + " " + "# x" and f"{cmd}{pad}# x" no longer reach a NEXT unseen (#679) #698 and tests: validate-pins.py's workflow scan skips a directory, a dangling symlink and a looping symlink named .yml, and both of siblings.py's headers print the holder's root and folder spelled, so the S_ISREG child check made lambda mode: True, or either path printed raw, now fails a test (#664) #706: clean.

Left out, and why

• No quoting change. The Git Bash dialect (option (a)) is a separate v1.1.1 issue; the inventory only holds what the sentence says today.
• docs/release-notes/v1.0.0.md:532 says the .pyc is left by test_cli_reference.py's children. That is true of v1.0.0 and I left it. The v1.1.0 notes (README, AGENTS.md, docs/cli.md and the handbook: pipx install openreposhape is the second way in and the first on native Windows, git-filter-repo is installed in install.sh's order and never with a bare pip install, and a first draft of the v1.1.0 release notes (#563) #630) may want one line.
• --others in the file listing. A new, untracked tool is scanned before it is added, as rglob did; a tracked file deleted from the work tree is skipped.

Checklist candidates

• A quoter handed on as a value is not a call. map(shell_quoted, words) or functools.partial(shell_line) is not seen by the inventory (said in host_calls' docstring). Nothing does it today.
• The function pin counts functions, not calls. A function with two host-dialect calls where only one is switched to POSIX still passes. Today the one-call functions are _switch_command, _print_next, _checked_mount_path.
• _print_next_steps prints a cd {shell_quoted(work)} line the sentence's list (NEXT, switch -c, add, git rm -r --cached) does not name. It belongs to the Git Bash dialect issue.
• The launcher guard's LAUNCHERS still has no row for src/openreposhape/cli.py (run_child([sys.executable, ...], env)) or setup-project.py (its own run with a PYTHON variable). Both spell the child differently from subprocess.run([sys.executable, ...]).

Closes #665

🤖 Generated with Claude Code

Summary by Sourcery

Harden repository guards and tests so generated trees remain clean and documented launcher and quoting inventories stay accurate.

Bug Fixes:

• Prevent CLI reference generation children from leaving Python bytecode artifacts in template directories.
• Ensure the validator launcher guard covers family.py's sibling-process environment propagation.
• Make the quoting inventory detect aliased and suffixless Python tools and enforce the documented calling functions.
• Avoid triggering Sonar S5778 by evaluating the leg placement before pytest.raises.

Enhancements:

• Strengthen static checks for child interpreter launchers and host-dialect quoting against the repository's complete shipped Python tool inventory.

Tests:

• Add regression coverage for bytecode suppression, family.py launcher validation, aliased quoting calls, function-level quoting inventories, suffixless Python files, and quoter exemptions.

[brettheap]

(lane openRepoShape-5, 2026-10-16T14:23Z) @codex review

[sourcery-ai]

Reviewer's Guide

The PR closes four coverage gaps in repository guards: it makes CLI-reference generation bytecode-free, enforces inherited child environments for family.py, strengthens the Windows host-quoting inventory to follow aliases and function-level callers across all shipped tools, and restructures one pytest exception test to satisfy S5778 without changing shipped behavior.

Sequence diagram for bytecode-free CLI reference generation

sequenceDiagram
    participant Generator as render-cli-reference.py
    participant Child as siblings.py --help
    participant Filesystem
    Generator->>Generator: child_env()
    Generator->>Child: subprocess.run(..., env=child_env())
    Child->>Filesystem: import bootstrap
    Filesystem-->>Child: module loaded
    Note over Child,Filesystem: PYTHONDONTWRITEBYTECODE=1
    Child-->>Generator: help text
    Generator-->>Filesystem: no __pycache__ or .pyc written

Loading

File-Level Changes

Change	Details	Files
Prevents the CLI reference generator's child processes from creating ignored Python bytecode artifacts.	Adds PYTHONDONTWRITEBYTECODE=1 to the generated child environment. Adds an integration test verifying both the environment value and Python's effective bytecode behavior.	scripts/render-cli-reference.py tests/test_cli_reference.py
Expands the validator child-environment guard to cover the family launcher.	Recognizes interpreter commands using sys.executable or PYTHON. Adds scripts/family.py to the launcher inventory so its siblings.py child must inherit the validated environment.	tests/test_validator_child_encoding.py
Makes the Windows quoting inventory accurately track aliases, shipped tools, and command-producing functions.	Resolves aliased and chained quoter bindings in AST analysis and records calling functions, including class methods. Scans tracked and non-ignored untracked Python files, including suffixless Python-shebang tools such as bootstrap. Pins the named functions for family.py and setup-project.py, preserves shape-doctor.py's all-lines rule, and limits exemptions to the two quoter implementation bodies. Adds mutation-focused tests for aliases, methods, suffixless files, exemptions, and function-level inventory changes.	tests/test_readme_windows_quoting_sentence.py
Avoids Sonar S5778 by evaluating the leg placement before entering pytest.raises.	Stores leg_placement(leg) before the exception assertion and passes the result into the tested call.	tests/test_bump_leg_paste_lines.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#665	Prevent CLI-reference child processes from writing bytecode into the templates tree, and add a guard that verifies the child environment disables bytecode.	✅
#665	Extend the validator-child launcher guard to recognize the sys.executable or PYTHON form and include scripts/family.py.	✅
#665	Make the quoting-sentence inventory detect aliased quoters, suffixless Python tools, the named tools’ specific calling functions, and host-quoter calls outside the two exempt quoter bodies.	✅
#665	Avoid placing leg_placement(leg) inside the pytest.raises block so an exception from that call cannot satisfy the expected-exception assertion.	✅

Possibly linked issues

• tests: four guards that do not hold what they say: a .pyc the CLI reference's child writes under templates/, a launcher guard blind to family.py, a quoting-sentence inventory with three holes, and an S5778 pytest.raises #665: The PR directly addresses all four issue items: disables child bytecode, covers family.py, closes quoting-inventory gaps, and fixes S5778.

---

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-16T14:26:03.145666Z	151a086	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

Here are some automated review suggestions for this pull request.

Reviewed commit: 151a0861dd

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

[chatgpt-codex-connector]

Decode Git paths with filesystem semantics

On POSIX, git ls-files -z returns raw filename bytes, so a tracked or untracked path containing a non-UTF-8 byte causes raw.decode("utf-8") to raise before the code can even determine whether the file is Python source. The previous Path.rglob approach preserved such names through Python's filesystem decoding, and this repository explicitly supports Git paths with non-UTF-8 bytes. Use os.fsdecode(raw) or UTF-8 with surrogateescape so an unrelated filename cannot break this test.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Pin individual host-quoting calls instead of function names

Reducing host_quoting() to its set of function keys makes this guard unable to detect a new or changed command inside an already-approved function. This already masks the cd {shell_quoted(work)} line in family.py::_print_next_steps: the README enumerates that tool's NEXT, switch -c, add, and git rm -r --cached lines, but the test passes because _print_next_steps also contains the approved switch -c call. Comparing the individual calls or command-producing helpers is necessary for the new guard to enforce the sentence it claims to protect.

Useful? React with 👍 / 👎.

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