[brettheap]

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

Four comments and docstrings said something main no longer does. They now say what the code beneath them does. A fix round after review added two more of the same kind (see "Fix round"). Comments and docstrings only: no behaviour, no --help text, no pinned copy, so no README, handbook or docs/cli.md change.

What changed

• adopt-project.py, the module docstring. It said the verification table reads code: 0 of N source paths (seeded from template). The printed row has no colon ( {leg:<6} {count:>5} of {N} source paths{note}). It now says the table's code row reads 0 of N source paths (seeded from template), the words AGENTS.md and README.md use since README.md and AGENTS.md: 28 statements the v1.0.0 accuracy pass found false are corrected to what the tools do on main (#483) #505 and the docstring of the verification function uses too. git grep 'code: 0 of' finds nothing now.
• shape-doctor.py, submodule_config. The last sentence of the docstring gave a reason that is true of the string and not decisive: "It is also what the row PRINTS, and a lone surrogate is a string no UTF-8 stream can write." The table goes through ascii_text and --json through json.dumps, so neither would raise on a lone surrogate. I dropped the sentence, the issue's first direction. The comparison with origin_url's reading of a clone's remote is the reason, and the paragraph already gives it first. This hunk carries the bytes of lane 3's 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, which landed as 55c6ba7d: the two removed lines and the one added line ( working clone.) are the same. So the hunk is on main already and drops out of the squash (see "Evidence").
• shape-doctor.py, run_validator. "It costs no child an import" holds for an unedited copy only. A new paragraph says a root whose own copy of a validator gained an import yaml read passes while site was on, and now reads crashed before reaching a verdict (exit 1): ModuleNotFoundError: No module named 'yaml', the crash its own CI gets, because validate.yml installs nothing. It calls that row a fair answer and says -S does not ask whether a copy was edited. No code change.
• tests/test_shape_doctor.py, the decoy test's two comments (the block above DECOY_REPO_SHAPE and the inline comment before reached). run_validator starts every child as [sys.executable, "-S", script, ...], so no child imports a sitecustomize. The comments now say that, say that replace-not-prepend and the shape-doctor.py: after #238 the doctor runs a root's OWN validator with the operator's PYTHONPATH still in the child's environment, so for an operator who exports one that reaches a repo_shape.py the manifest row of a root that lost its own scripts/repo_shape.py says ok ... passes again, the false pass #238 removed, where the project's own gate in CI fails on ModuleNotFoundError: No module named 'repo_shape' #306 review S1 case are held by test_run_validator_gives_the_child_exactly_the_pythonpath_it_is_given, and say that the decoy test holds the template row's real verdict under an exported PYTHONPATH.

Fix round

The review of the first two commits approved with nits. Two new commits take S1 and N1: 7f2bb36b makes both edits, and 426877bf rewrites the last sentence of the N1 comment, which did not parse ("...a future removal of -S, which test_run_validator_starts_every_child_with_no_site ... is the test that holds"). It now ends "...a future removal of -S; test_run_validator_starts_every_child_with_no_site (in tests/test_doctor_validator_site.py) is the test that holds -S." Both are comments and docstrings only.

• S1, a third stale sentence. The docstring of test_run_validator_gives_the_child_exactly_the_pythonpath_it_is_given said that for the callers which pass no pythonpath, "only a probe like this one, or (b)'s decoy, can see that they have none". That is false under -S: a run_validator that keeps the variable for those callers passes the decoy test in all three cases and fails the probe test twice (the second row of the table below). It now says only a probe like this one can see that they have none, and that the decoy of (b) could before -S (shape-doctor.py: run_validator starts a root's OWN validator under the doctor's interpreter with site processing on, so a .pth in the operator's user site or in a virtualenv's site-packages that names a directory holding repo_shape.py stands in for the copy the root lost, and the manifest row says ok ... passes for a gate that fails in CI on ModuleNotFoundError: the false pass #238 removed and #306 closes for PYTHONPATH alone #342). It is the same defect as the issue's, in a place the issue did not name. "Could" holds for the manifest and pins cases: with -S removed, 2 of the 3 decoy cases fail, and the family case never caught it.
• N1, the inline comment overstated the loop. The comment above reached said "What this loop still holds is that no row quotes the decoy or says it exited 86." Under -S the loop cannot fire. It now says so, says the loop is kept as a tripwire for a future removal of -S, and names test_run_validator_starts_every_child_with_no_site in tests/test_doctor_validator_site.py as the test that holds -S. That test is on main.
• N2, this body. The merge checks and the notes on 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 were stale (they cited de926142 and a conflict that is gone). They are rerun and rewritten below.

Evidence

Only comments and docstrings changed. git diff 8062810d 426877bf has 74 changed lines (44 added, 30 removed) in three files. A script checked each changed line against the file's comment tokens and docstring spans (both sides of the diff): 0 outside. A second check parsed each file at the base and at the head, blanked every docstring, and compared the ASTs: identical in all three files. For the two fix-round commits together, the AST of tests/test_shape_doctor.py with docstrings blanked is identical to the one at a2113cff, git diff --check is clean, and the longest added line is 75 columns (73 in the second commit).

What the squash holds. git merge-tree --write-tree of this head with origin/main 20c8873b gives the tree 6ead2ffc. git diff 20c8873b 6ead2ffc is 71 changed lines in three files, and shape-doctor.py has 8 of them: the new run_validator paragraph and nothing else. git diff of the two trees has no hunk that mentions submodule_config, surrogate, PRINTS or working clone. On main, submodule_config's docstring has no "PRINTS" sentence and ends in working clone.. The same two checks on that tree: 0 lines outside comments and docstrings, ASTs identical. On main 2d988200 with the head 426877bf the squash is the same: 71 changed lines, 8 of them in shape-doctor.py, 0 outside comments and docstrings, ASTs identical, and no hunk that mentions submodule_config.

python3 scripts/render-cli-reference.py --check, at 426877bf: [ok] docs/cli.md is what the generator produces. Only the first line of a module docstring is help text, and none of the first lines changed.

The decoy comments, measured. I did not take the issue's reading on trust. In a throwaway clone at the base I put each #306 regression into run_validator and ran the two tests (test_an_exported_pythonpath_does_not_reach_a_template_validator, three cases, and test_run_validator_gives_the_child_exactly_the_pythonpath_it_is_given, six):

mutant	with -S (main)	with -S removed
the standard's scripts/ put in FRONT of the operator's value	decoy test: 3 of 3 pass. Probe test: 1 of 6 fails	decoy test: 3 of 3 fail
the variable kept for the callers that pass none (S1)	decoy test: 3 of 3 pass. Probe test: 2 of 6 fail	decoy test: 2 of 3 fail
the operator's directory AHEAD of the standard's	decoy test: 3 of 3 fail. Probe test: 1 of 6 fails	not run

So on main the decoy test catches neither #306 regression and the probe test catches both, as lane 4's R342 measured on #636's head. The third row is why the comment says the raising repo_shape.py "still bites": it kills an operator-first order. The review re-ran these mutants on a2113cff and got the same counts.

The run_validator paragraph, measured. A root whose own validate-manifest.py is import yaml plus a print, run through run_validator from this tree: exit 1 and ModuleNotFoundError: No module named 'yaml'. The same call with -S taken out of the child's argv: exit 0, manifest ok. yaml is importable from the machine's site-packages and not without site.

Tests

With the real gh unreachable (a stub first on PATH, a bogus token, an empty GH_CONFIG_DIR).

On a2113cff, before the fix round:

• tests/test_cli_reference.py, tests/test_repo_hygiene.py, tests/test_agents_md_codes.py, tests/test_scaffold_leg_path_collisions.py: 250 passed (57.5 s).
• tests/test_doctor_gitmodules_not_utf8.py, tests/test_doctor_validator_rows.py, tests/test_doctor_validator_site.py, tests/test_doctor_validator_verdicts.py, tests/test_adopt_spec_only.py, tests/test_adopt_entry_paths.py, tests/test_adopt_submodules.py (the files that drive run_validator, submodule_config or the seeded-leg row): 334 passed (28 min 18 s).
• tests/test_shape_doctor.py, in two halves run side by side (the first 204 test ids, then the last 204): 204 passed in 11 min 31 s, and 201 passed, 3 skipped in 4 min 58 s. That is all 408 tests. The 3 skips are the PowerShell-line tests, which need powershell.exe on a Windows host.
• The review ran all of tests/test_shape_doctor.py there: 405 passed, 3 skipped (512 s). On the predicted merge with main 2fac9790 it ran test_shape_doctor.py, test_doctor_validator_site.py, test_doctor_validator_rows.py, test_doctor_validator_verdicts.py, test_doctor_gitmodules_not_utf8.py, test_repo_hygiene.py, test_cli_reference.py and test_agents_md_codes.py: 632 passed, 3 skipped (760 s).

On 426877bf, after the fix round, which changes comments and docstrings only, so the runs above stand:

• The two tests the fix round touches, test_an_exported_pythonpath_does_not_reach_a_template_validator (3 cases) and test_run_validator_gives_the_child_exactly_the_pythonpath_it_is_given (6 cases), run by node id: 9 passed (11.7 s). The same 9 also passed (16.1 s) at 7f2bb36b.
• tests/test_repo_hygiene.py: 77 passed (1.9 s). It also passed (2.0 s) at 7f2bb36b.

No test fails on the base, because nothing here changes behaviour. The AST comparison above is the proof in their place.

Merge checks

git merge-tree --write-tree of this head against origin/main and against every ref on origin that could meet it. The full run was on 2026-10-16, with the head 7f2bb36b (the one before the last comment commit) and main 20c8873b: the 41 branches (fix/*, l3-*, wip/*, docs/* and release/v1.0) and the 55 PR heads from #630 up. That is 96 refs. I ran #731's head ab55c29f through the same list. After 426877bf I re-ran main, now 2d988200, and the six heads that edit tests/test_shape_doctor.py, the one file that commit touches (#705, #737, #740, l3-669-members-row, l3-680-doctor-signals and l3-697-crash-cure-next), and #630: all clean.

• origin/main: clean. At 20c8873b, with the head 7f2bb36b, the predicted tree is 6ead2ffc. At 2d988200 (three adopt-project.py commits later, with their tests and a change in scripts/shape_materialize.py), with the head 426877bf, it is 7ee5caf4, and the squash is the same three files (43 added, 28 removed). shape_materialize.py, scaffold-project.py and family.py: the folder refusals and family-operation-in-progress name a path as shown_source names it, so an ESC or a line break in a path no longer reaches the terminal (#692) #731's head ab55c29f is clean with 2d988200 too. This head with shape_materialize.py, scaffold-project.py and family.py: the folder refusals and family-operation-in-progress name a path as shown_source names it, so an ESC or a line break in a path no longer reaches the terminal (#692) #731's head: clean.
• 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's head 6fd33a93: clean. It conflicted with main in docs/handbook.html when this body was first drafted, and no longer does, with or without this change.
• 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 and 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 have landed (55c6ba7d and 20c8873b), and so has 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, and 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: _default_branch keeps a branch name's byte that is not UTF-8, so a source whose HEAD or origin/HEAD is on caf<e9> is refused or adopted past it, and no longer ends plan, check and execute in a traceback (#425) #717 and adopt-project.py: a --work-dir that is a file or cannot be made is refused by name in plan, check and execute, and --help says what --work-dir is and where --org comes from (#650) #719 for adopt-project.py. Their heads still merge clean with this head.
• Every ref that edits shape-doctor.py, tests/test_shape_doctor.py or adopt-project.py merges clean with this head, except the two old heads named in the bullet after next. They include the heads of PRs not on main yet (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, adopt-project.py, shape-doctor.py: a plan's answer against a rule is recorded and an empty .gitmodules asks nothing, so docs/ answered code is not MISPLACED after adoption verified, nor a .gitmodules emptied by git rm asked on every run (#655) #721, shape-doctor.py: an own-copy validator row whose crash is a root's lost scripts/repo_shape.py names git -C <root> checkout HEAD -- scripts/repo_shape.py as its NEXT (none where HEAD no longer holds it) and the validator in its WHY (#697) #737 and shape-doctor.py and update-shape.py: run from a partial clone of the standard, the shape currency row asks without fetching whether the clone holds what the comparison reads, and is CANNOT ANSWER with a fetch for a person to run where it does not, and a read that fails is refused, never a copy called both (#683) #742, and lane 3's l3-680, l3-683, l3-687, l3-691 and l3-697, which were not on origin when this body was first drafted). shape-doctor.py: the members row prints a mount url and a stranger's origin raw, so an ESC in either reaches the terminal as a control, where make siblings spells the same values in its WRONG ORIGIN finding #673 has no branch or PR head on origin.
• Four refs conflict with origin/main on their own, and so with this head: docs/release-notes-v1.0.0 and release/v1.0, and the pre-squash heads of the landed family.py and validate-family.py: where an earlier act left the branch, the switch -c remedy says to give it another name, or go back only if it holds work not merged yet, and the docs say family/add-<Project> (#607) #637 and bump-leg.py, scaffold-project.py and family.py: git status --porcelain and git config user.name are read as bytes, so a file name that is not UTF-8 is bump-leg-root-dirty or the DIRTY warning and a user.name that is not UTF-8 is refused family-unwritable-value naming --created-by, where each ended in a UnicodeDecodeError traceback (#423, #426) #641. Their conflicts do not come from this change.
• Two landed pre-squash heads conflict with this head only because they are old. shape-doctor.py: a family holder's .gitmodules is read as bytes and a url that is not UTF-8 is replaced, as make siblings reads it, so --root reaches a verdict where a member mounted from a legacy-code-page directory ended in a UnicodeDecodeError traceback, exit 1, with none (#432) #632 conflicts with main on its own. shape-doctor.py: every validator child starts with -S, so no .pth in the user's or a virtualenv's site-packages stands in for the repo_shape.py a root lost, and the manifest row is the gate's own ModuleNotFoundError (#342) #636 merges clean with main, but its old head conflicts with this head in run_validator's docstring, next to the text shape-doctor.py: every validator child starts with -S, so no .pth in the user's or a virtualenv's site-packages stands in for the repo_shape.py a root lost, and the manifest row is the gate's own ModuleNotFoundError (#342) #636 added; main has that text, and this head merges clean with main.
• Refs that conflict with main on their own are not made worse. 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, bootstrap.py and AGENTS-shape.md: a leg with an operation in progress or an ignored file in the way is refused, P9 names the branch it left, and no git is git-not-runnable, so make bootstrap loses nothing (#704) (#694) #745, validate-family.py and validate-pins.py: a staged gitlink removal says to commit it, member-gitlink-absent puts the gitlink back by hand, the variant mv is guarded, and a pin row with no path: is shape-pin-row (#681) #747, fix/648, fix/681 and fix/704 conflict with main in templates/family-root/scripts/validate-family.py; shape-doctor.py and update-shape.py: run from a partial clone of the standard, the shape currency row asks without fetching whether the clone holds what the comparison reads, and is CANNOT ANSWER with a fetch for a person to run where it does not, and a read that fails is refused, never a copy called both (#683) #742 and l3-683 in shape-doctor.py. Each merges clean with this head.
• Every other open head and branch: clean.

Left out

Nothing from the issue. Its four lines are done. The decoy test's sitecustomize machinery is dead code under -S and I left it, because the issue says comment only. The comment above reached now says it is kept as a tripwire.

Checklist candidates

• The decoy test's sitecustomize.py and exit-86 trap never run. DECOY_SITECUSTOMIZE, os._exit(86) and the (exit 86) and DECOY clauses in reached can only fire for a child started without -S. They are kept as a tripwire and the comment says so. The other choice is to remove them; test_run_validator_starts_every_child_with_no_site already holds -S. Small, tests only.

Closes #666

🤖 Generated with Claude Code

Summary by Sourcery

Enhancements:

• Align comments and docstrings with the validator execution model, including isolated child processes and the actual verification output.

[brettheap]

(lane openRepoShape-5, 2026-10-16T17:22Z) @codex review

[sourcery-ai]

Reviewer's Guide

This documentation-only PR updates stale comments and docstrings to describe the current verification output and validator isolation accurately, including -S, missing dependencies, exported PYTHONPATH, and the decoy test’s actual coverage. Runtime behavior, CLI help, generated documentation, and ASTs remain unchanged.

Sequence diagram for isolated validator execution and dependency failure

sequenceDiagram
    participant Doctor as shape-doctor.py
    participant Child as Validator child
    participant Site as Python site packages
    participant YAML as yaml dependency

    Doctor->>Child: run_validator(ctx, script, args)
    Doctor->>Child: Start with [sys.executable, -S, script, ...]
    Child--xSite: Skip site initialization
    Child->>YAML: import yaml
    YAML--xChild: ModuleNotFoundError
    Child-->>Doctor: Exit 1 with crash text
    Doctor-->>Doctor: Report crashed before reaching a verdict

Loading

File-Level Changes

Change	Details	Files
Correct documentation of the seeded verification row to match the output format.	Removed the stale colon from the documented code row. Kept the description aligned with the existing seeded-template wording.	adopt-project.py
Document validator behavior under isolated child execution and missing validator dependencies.	Removed the misleading rationale from the submodule configuration docstring. Explained that edited validators can crash under -S when CI dependencies such as yaml are unavailable. Clarified that -S enforces execution isolation rather than detecting edited copies.	shape-doctor.py
Align decoy-test comments and docstrings with actual -S behavior and test coverage.	Explained that sitecustomize is inert because validator children are launched with -S. Identified the direct PYTHONPATH probe as the coverage for replace-not-prepend and S1 regressions. Reframed the decoy assertions as a tripwire for any future removal of -S and identified the dedicated isolation test. Corrected the claim about detecting absent PYTHONPATH for callers that pass no value.	tests/test_shape_doctor.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#666	Make the adopt-project.py verification-row docstring and the submodule_config docstring accurately describe current behavior.	✅
#666	Clarify in run_validator's docstring that the no-import claim applies only to unedited validator copies and that edited copies can fail when their own CI dependencies are unavailable.	✅
#666	Correct the decoy test's comments to reflect that -S prevents sitecustomize from running and identify the test that now guards the relevant PYTHONPATH behavior.	✅

Possibly linked issues

• Comments that say what main no longer does: submodule_config's reason, run_validator's "costs no child an import", the decoy test's sitecustomize claim under -S, and the verification row's colon in adopt-project.py's header #666: The PR addresses the issue’s requested documentation corrections; submodule_config was already fixed on main, and related test comments receive extra clarifications.

---

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-16T17:24:15.112013Z	a2113cf	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. You're on a roll.

Reviewed commit: a2113cffb5

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

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

Sourcery assessment

Approved.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook