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

Goal: four comments and docstrings say what the code beneath them does on main today.

Filed by lane openRepoShape-5 on Brett Heap's word of 2026-10-16T12:17:02Z ("#461's test/CI/doc lines (~27)"), from four lines on #461: the body's "AT-adopt N9" (body) and three of lane 4's (R432, one line; R342, its first two lines). Comments and docstrings only: no behaviour changes, no pinned copy, no --help text, so no README, handbook or docs/cli.md change.

Lands after: nothing is needed. Lane 1's open work edits shape-doctor.py (l1-v11-655-adopt-doctor-plan-overrides, hunks between :226 and :6477 at its base) and adopt-project.py (five branches); none of their hunks is at the lines below.

Lines (path:line at main 879d8047)

• AT-adopt N9, what is left of it. The line said AGENTS.md:182, README.md:810 and adopt-project.py:87 quote the verification row as code: 0 of N source paths (seeded from template), where the printed row has no colon. 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 (README.md and AGENTS.md: an accuracy pass for v1.0.0, every command, flag, exit code, refusal code and step they state checked against the tools on main, so the tag's "README and AGENTS.md accurate" criterion holds #483's accuracy pass) fixed AGENTS.md (:182 now reads "code row reads 0 of N source paths (seeded from template)") and README (:832). adopt-project.py:140-141, the module docstring, still says "the verification table reads code: 0 of N source paths (seeded from template)"; the row is printed by adopt-project.py:10642-10644 as {leg:<6} {count:>5} of {N} source paths{note}. Direction: drop the colon in the docstring. No other file says it (git grep 'code: 0 of' at 879d8047 finds that one line).
• submodule_config's docstring gives a reason that is true of the string but not decisive (lane 4's L4-135). shape-doctor.py:7021-7022: "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 (:624-638, encode("ascii", "replace"); Row.__init__ :814-822) and --json through json.dumps with its default ensure_ascii=True (as_json, :8908-8920), so neither path would have raised on a surrogate. The comparison with origin_url's reading of a clone's remote is the reason, and the docstring gives it first. Direction: drop the sentence, or say that --json would carry a lone \udce9 escape that strict JSON readers refuse while the printed table never could carry one.
• Two test comments are false since -S (lane 4's L4-138). tests/test_shape_doctor.py:10241-10257 ("THE sitecustomize.py IS WHAT DOES THE WORK, and it catches every way the directory can reach a validator") and the inline comment at :10302-10310 (that the decoy catches a run_validator that kept the variable, 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) describe a guard that -S removes: run_validator starts every child as [sys.executable, "-S", script, ...] (shape-doctor.py:1624), so no child imports a sitecustomize. R342 measured that on main test_an_exported_pythonpath_does_not_reach_a_template_validator (:10271) caught both 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 regressions it was written for, and on 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's head catches neither (all three cases pass). Nothing is unguarded: test_run_validator_gives_the_child_exactly_the_pythonpath_it_is_given (:10336) alone kills both. I read the comments and the -S; I did not rerun R342's mutants. Direction: say that replace-not-prepend and the S1 case are now held by that test, while the decoy test holds the template row's real verdict under an exported PYTHONPATH. Comment only; fold it into the next push to that file.
• run_validator's docstring overstates "IT COSTS NO CHILD AN IMPORT" (lane 4's L4-139). shape-doctor.py:1565-1568: "a root's pinned copy of one ... imports the standard library and this standard's own modules and nothing else" is true of an UNEDITED copy only. R342 measured: a root whose own validate-manifest.py gained import yaml reads ok manifest ... passes on main before 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 and FINDING manifest: ... crashed before reaching a verdict (exit 1): ModuleNotFoundError: No module named 'yaml' after it; a root that edited its own copy to import more now gets the crash its own CI gets, because validate.yml installs nothing ("Standard library only"). Direction: add that sentence to the docstring. The row naming No module named 'yaml' is a fair answer, so no code change.

Lane 4's triage. Lane 4 had the last three lines as L4-135, L4-138 and L4-139, riders on its T12 (shape-doctor.py submodule_config), and has dropped every #461 line from its proposal for lane 5 (#473 comment).

Overlaps. Open PRs: none of the seven open PRs (#621, #627, #628, #630, #634, #639, #656) touches shape-doctor.py or tests/test_shape_doctor.py; #621, #628 and #630 edit adopt-project.py (not at :140). Lane 5's in-flight branches: none.

Mark each line → this issue on #461, and tick it there when this closes.

🤖 Generated with Claude Code