Tracking: the test suite, CI and the docs

Lane: openreposhape-3 (openRepoShape-3)

The parent issue for one area of openRepoShape: the test suite, the three-OS CI gate, and the docs that state what the tools do. Brett Heap ruled on 2026-10-12 that the open issues are grouped under one parent per area, with a release milestone. Every open issue in this area is a sub-issue here.

v1.0.0. The first release is "core flows, all OSes": every procedure in AGENTS.md works end to end for ordinary repositories on Linux, macOS and Windows. The tag waits for every in-scope issue to close and for a full test run to pass on all three OSes on the release commit. In this area, the sub-issues in the v1.0.0 milestone are:

tests/test_shape_doctor.py, tests/conftest.py and setup-project.py: a clone of a just-pushed --local-remote-dir bare repository is git's local clone, which links or copies each loose object file while git's background maintenance can pack and delete them, so on the macOS runner it dies failed to copy file to ... No such file or directory, every doctor test errors at setup, and setup.sh refuses after creating all three repositories #440 (P1): macOS CI: git's local clone of a just-pushed bare remote races background maintenance; three failures, two in 90 minutes, each a 20-minute 3-OS rerun.
tests-windows never executes an adoption: git-filter-repo is not installed there, so the eight adopt suites skip and v1.0.0's "adopt works on Windows" is unverified #471 (release gate): tests-windows never executes an adoption (no git-filter-repo), so "adopt works on Windows" is unverified. Proposed holder: lane 4.
v1.0.0 release notes: nothing in the repository says what the release covers or lists its known limits #472 (release gate): the v1.0.0 release notes, listing the known limits. Proposed holder: lane 4.

Known limits. Every other sub-issue is a known limit: only exotic input triggers it (bytes that are not UTF-8, the C locale, control characters, hand-edited YAML, symlink tricks, names that differ only by case). The release notes list them, and they are worked when a release takes them in. A new edge case that review finds goes on this checklist, not into a new issue, unless it is in a release's scope or would hit a real user (Brett Heap, 2026-10-12).

Edge cases found in review of lane openRepoShape-3's pull requests, kept here rather than filed:

→ Tests: about a dozen fixtures still clone a just-pushed local bare remote by plain path (the #440-class macOS flake), with small test-only fixes alongside #544 About a dozen fixtures (in tests/test_update_shape.py, tests/test_doctor_validator_rows.py and tests/test_family.py, and adopt and scaffold fixtures) and templates/family-root/scripts/siblings.py still clone a just-pushed local remote by plain path. None has failed in CI. Move them to the helper setup-project.py: the root clone of --local-remote-dir is --no-local and its two leg clones are rewritten to file://, and the two session fixtures that clone a scaffold do the same, so a maintenance run packing the just-pushed objects mid-walk no longer dies failed to copy file to ... No such file or directory (#440) #467 adds once it lands. From setup-project.py: the root clone of --local-remote-dir is --no-local and its two leg clones are rewritten to file://, and the two session fixtures that clone a scaffold do the same, so a maintenance run packing the just-pushed objects mid-walk no longer dies failed to copy file to ... No such file or directory (#440) #467.

Known limits found by lane openRepoShape-3's acceptance passes (standard 36538fd, each re-checked on main 7a8b981) and kept here rather than filed:

→ README.md and the handbook: the by-hand setup steps dry-run the scaffold without the --visibility and --elected-by that setup passes #550 AT-scaffold N4: README's by-hand version of what setup runs (README.md:531-533) dry-runs scaffold-project.py --org <your-org> --project Atlas --dry-run without the --visibility and --elected-by of the real run on the next line, while setup's own dry run passes both (setup-project.py:1587-1604), so the plan a person reads names a different elector than the real run writes. (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 may correct this first.)
→ 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 AT-adopt N9: 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), but the printed row has no colon ( code 0 of 7 source paths (seeded from template), adopt-project.py:5553-5554). (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 may correct this first.)
→ adopt-project.py: remove the temp work roots it makes without --work-dir, keep a recorded --source clone, and point the tests' TMPDIR at their basetemp #526, done in adopt-project.py and tests/conftest.py: a run without --work-dir removes the empty work directory it made, and a recorded clone that is gone is cloned again, so no empty openreposhape-adopt-* is left and no source-unclonable follows (#526) #594 (c972032) The test suite never points TMPDIR at its own scratch for the adopt runs (tests/conftest.py sets none, and no adopt suite does; the five that set it are test_cli_reference, test_family_add_refusals and three scaffold suites), so every plan, check and execute a test runs without --work-dir leaves an openreposhape-adopt-* directory in the system temp folder, outside pytest's tmp_path retention: 15,206 sit in one container's /tmp (2,992 of the first 3,000 empty), 226,165 on the family pass's machine. Direction: one autouse fixture pointing TMPDIR into the session's basetemp; the tool-side half is the first line under Tracking: adopt-project.py, converting an existing repository in place #457.
→ .github/workflows/tests.yml: no merge_group trigger, so GitHub's merge queue cannot be turned on for main: a queued pull request would wait for a tests check that never runs #895 Deferred (2026-10-14), after 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: L3-2: the CI workflow has no merge_group trigger (.github/workflows/tests.yml:12-16), so GitHub's merge queue cannot batch landings. Enabling it also needs a ruleset change, and every required check, SonarCloud included, must report on merge_group.
CI cost: the Windows job runs serially, 75-130 minutes a run; shard it, or run it under xdist. Moot since ci: run the test suite on Linux only #597 (654c476c): CI has no full Windows job now.
CI cost: the workflow's concurrency group cancels main's previous run on every landing. Fixed by .github/workflows/tests.yml: a push run on main is grouped by its commit, so the next landing no longer cancels it, and every landing gets its own Linux result (#592) #593 (024ea55e): a push run is grouped by its commit.
→ tests/conftest.py: one helper builds the url.<base>.insteadOf rewrite that clone_just_pushed and read_through_git each build, and the plain-path git submodule update --init sites of #554's review use it (#440) #662 Tests (tests: every test that clones a just-pushed local remote by its plain path now clones it with clone_just_pushed, so the macOS failed to copy file race of #440 cannot reach it; load_without_bytecode keeps the doctor's and the Windows-path tests' loads of the family root's scripts from writing .pyc into the templates; the not-a-list doctor cases hold INVALID, exit 1; and GOOD_KEYS holds th #554's review, 2026-10-14): git submodule update --init of a plain-path URL is still git's local clone of a just-pushed remote, at tests/test_family_bump_remove_rollback.py:337 and :908 and tests/test_doctor_legs_members_next.py:630 and :981. The same -c url.<base>.insteadOf rewrite clone_just_pushed uses would cover them.
→ 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 Tests (tests: every test that clones a just-pushed local remote by its plain path now clones it with clone_just_pushed, so the macOS failed to copy file race of #440 cannot reach it; load_without_bytecode keeps the doctor's and the Windows-path tests' loads of the family root's scripts from writing .pyc into the templates; the not-a-list doctor cases hold INVALID, exit 1; and GOOD_KEYS holds th #554's review): tests/test_cli_reference.py leaves templates/family-root/scripts/pycache/bootstrap.cpython-312.pyc. scripts/render-cli-reference.py runs the template's siblings.py --help in a child whose child_env() does not set PYTHONDONTWRITEBYTECODE. Set it there, or in the test.
→ tests/conftest.py: one helper builds the url.<base>.insteadOf rewrite that clone_just_pushed and read_through_git each build, and the plain-path git submodule update --init sites of #554's review use it (#440) #662 Tests (tests: every test that clones a just-pushed local remote by its plain path now clones it with clone_just_pushed, so the macOS failed to copy file race of #440 cannot reach it; load_without_bytecode keeps the doctor's and the Windows-path tests' loads of the family root's scripts from writing .pyc into the templates; the not-a-list doctor cases hold INVALID, exit 1; and GOOD_KEYS holds th #554's review, optional): a hygiene test that refuses a plain-path recursive git clone of a just-pushed remote in tests/ outside conftest.py, so a new one, like adopt-project.py: y() quotes what the plan's loader would read as a keyword, so --spec-path null, --id null and --tracking-branch true adopt as typed, and plan, check and execute refuse, before anything exists, a value the project's own loader would read back as something else from the line execute writes #518's at tests/test_adopt_plan_yaml_quoting.py:2036, is caught when it is added. Closed unwritten by tests/conftest.py: one helper builds the url.<file URI>.insteadOf rewrite that clone_just_pushed, read_through_git and the adopt tests' pasted each built, and the empty-mount submodule update --init sites use it (#662) #748, as tests/conftest.py: one helper builds the url.<base>.insteadOf rewrite that clone_just_pushed and read_through_git each build, and the plain-path git submodule update --init sites of #554's review use it (#440) #662 allowed (lane 3's triage, 2026-10-18).

(lane openRepoShape-2, 2026-10-12T21:19Z)

This is an edge case this lane's review of #343 found and kept off the issue list, per the v1.0.0 rule that a new edge case goes on its area's Tracking parent.

→ rides with Tests: about a dozen fixtures still clone a just-pushed local bare remote by plain path (the #440-class macOS flake), with small test-only fixes alongside #544 L2-2: tests/test_shape_pin_files_not_a_list.py:152 (update-shape.py read_pin refuses update-pin-row, and the pinned validate-pins.py and validate-family.py report shape-pin-row, when a shape pin's files: is not a list, so files: 5, true or 1.5 no longer ends check, apply, shape-doctor.py and the project's own validator in TypeError: ... is not iterable (#290) #343) accepts the doctor's exit 3 (returncode in (1, 3)), and the module docstring (:22-25) still says the doctor's verdict is shape-doctor.py: a root's own contracts/shape-pin.yaml that does not read as a pin (a merge conflict, a non-UTF-8 byte, a commit: that is not 40 hex, a deleted file) is INVALID, exit 1, with the git command that puts back the last pin a tool wrote as its NEXT, instead of CANNOT ANSWER, exit 3, sending the reader to git fetch --all in the standard (#237) #267's to move. shape-doctor.py: a root's own contracts/shape-pin.yaml that does not read as a pin (a merge conflict, a non-UTF-8 byte, a commit: that is not 40 hex, a deleted file) is INVALID, exit 1, with the git command that puts back the last pin a tool wrote as its NEXT, instead of CANNOT ANSWER, exit 3, sending the reader to git fetch --all in the standard (#237) #267 is on main (decff87): a root pin that read_pin refuses is INVALID, exit 1, and exit 3 (CANNOT ANSWER) is the regression shape-doctor.py: a root's own contracts/shape-pin.yaml that does not read as a pin (a merge conflict, a non-UTF-8 byte, a commit: that is not 40 hex, a deleted file) is INVALID, exit 1, with the git command that puts back the last pin a tool wrote as its NEXT, instead of CANNOT ANSWER, exit 3, sending the reader to git fetch --all in the standard (#237) #267 fixed. ROOT_PIN_FAULTS pins INVALID only for files: 5, true and 1.5, so a doctor that answered CANNOT ANSWER for files: abc, a quoted string or a mapping would still pass this file. Fix: assert returncode == 1 and the INVALID verdict, and update the docstring. Seen at update-shape.py read_pin refuses update-pin-row, and the pinned validate-pins.py and validate-family.py report shape-pin-row, when a shape pin's files: is not a list, so files: 5, true or 1.5 no longer ends check, apply, shape-doctor.py and the project's own validator in TypeError: ... is not iterable (#290) #343's head 91a4a4f. Fixed by tests: every test that clones a just-pushed local remote by its plain path now clones it with clone_just_pushed, so the macOS failed to copy file race of #440 cannot reach it; load_without_bytecode keeps the doctor's and the Windows-path tests' loads of the family root's scripts from writing .pyc into the templates; the not-a-list doctor cases hold INVALID, exit 1; and GOOD_KEYS holds th #554 (2247dbff): the test now asserts returncode == 1.

Lane: openreposhape-5 (openRepoShape-5)

(lane openRepoShape-5, 2026-10-12T21:26Z) One item for this area's checklist, from this lane's #456 work on 2026-10-12. This lane filed it as #469 before reading the ruling that new review edge cases go on the area's checklist; #469 is closed as moved here. It is not in v1.0.0's scope, and no ordinary repository hits it.

Please fold this line into the checklist:

→ rides with Tests: about a dozen fixtures still clone a just-pushed local bare remote by plain path (the #440-class macOS flake), with small test-only fixes alongside #544 tests/test_shape_doctor.py:438-452 and tests/test_windows_paths.py:80-92 load templates/family-root/scripts/bootstrap.py and siblings.py with spec.loader.exec_module, which writes templates/family-root/scripts/__pycache__/*.pyc into the template tree (ignored, so git status is silent). Today nothing reads every file under templates/family-root after them, so the suite is green by order. Both roots' scripts/bootstrap.py: main escapes what stdout cannot encode and spells each value it prints, so name: "a\ud83db" or 日本 under PYTHONIOENCODING=ascii no longer ends make bootstrap in a traceback (#391) #456's CI failed this way for the assembly root (run 38297896001: tests/test_scaffold_leg_path_collisions.py read a .pyc as UTF-8). Direction: sys.dont_write_bytecode around each exec_module, as Both roots' scripts/bootstrap.py: main escapes what stdout cannot encode and spells each value it prints, so name: "a\ud83db" or 日本 under PYTHONIOENCODING=ascii no longer ends make bootstrap in a traceback (#391) #456's load() does, ideally one helper in tests/conftest.py. Fixed with Tests: about a dozen fixtures still clone a just-pushed local bare remote by plain path (the #440-class macOS flake), with small test-only fixes alongside #544: on main 879d8047 both files load it with load_without_bytecode.

Lane: openreposhape-5 (openRepoShape-5)

(lane openRepoShape-5, 2026-10-12T22:20Z) For this area's two release criteria that no issue held: on Brett Heap's word of 2026-10-12, lane 5 takes the release notes (#482: docs/release-notes/v1.0.0.md, by pull request, kept a draft until the last in-scope issue closes) and the README and AGENTS.md accuracy pass (#483). Both are on the v1.0.0 milestone.

The notes will be built from this parent's checklist and the other four parents' (#457-#460), and from the open issues left off the milestone. When you fold or tick a checklist item, the notes follow at the refresh just before the tag; nothing for you to do.

(lane openRepoShape-2, 2026-10-13T14:07Z)

This lane's review of #435 found this test gap. Per the v1.0.0 rule, a new edge case goes on its area's Tracking parent, so it is listed here and not filed as an issue.

→ rides with Tests: about a dozen fixtures still clone a just-pushed local bare remote by plain path (the #440-class macOS flake), with small test-only fixes alongside #544 L2-13 (nit, tests): no test holds that a bare or absent source: or legs: is not a _plan_key_findings finding. Fixed with Tests: about a dozen fixtures still clone a just-pushed local bare remote by plain path (the #440-class macOS flake), with small test-only fixes alongside #544: on main 879d8047, tests/test_adopt_execute_refusals.py:1039-1041 holds source-bare, source-absent and legs-bare.
- adopt-project.py:4374 and :4379 (as adopt-project.py: check names, and execute refuses before the work directory is made, a plan whose source: or legs: is not a mapping or whose allow_empty_legs: or paths: is not a list of what plan writes, and asks the same first of a pins: that is not a list, so a number or a boolean in any of the four no longer ends both in a traceback and allow_empty_legs: code is no longer read as four legs (#386) #435 landed them, main f391e58) exempt source is None and legs is None. That follows the function's docstring: a key that is absent or bare is read as it always was, plan-no-source for source: and the names' own refusal for legs:.
- GOOD_KEYS (tests/test_adopt_execute_refusals.py:1020) holds that rule for pins:, allow_empty_legs: and paths: only.
- Two mutants survive all 150 tests in that file. Each drops one is None arm, so a bare key becomes plan-bad-source or plan-bad-legs. The behaviour is right today.
- Fix: add source-bare, source-absent and legs-bare rows to the control table. Each asserts no plan-bad- finding and the code main gives.

docs/release-notes/v1.0.0.md: brought up to main 3121945, so section …

(lane openRepoShape-5, 2026-10-15T17:27Z) #578 (#543) landed as 3f768a6 and takes #543's half of the fixture line here. That is the "→ #544" line: "About a dozen fixtures … and templates/family-root/scripts/siblings.py still clone a just-pushed local remote by plain path".

The siblings.py half is done. Its member clone is now git clone --no-local. A member url that is a path on disk is read through git instead of copied file by file, so a repack in that remote cannot break the clone halfway (tests/test_shape_doctor.py, tests/conftest.py and setup-project.py: a clone of a just-pushed --local-remote-dir bare repository is git's local clone, which links or copies each loose object file while git's background maintenance can pack and delete them, so on the macOS runner it dies failed to copy file to ... No such file or directory, every doctor test errors at setup, and setup.sh refuses after creating all three repositories #440).
The fixtures half stays with Tests: about a dozen fixtures still clone a just-pushed local bare remote by plain path (the #440-class macOS flake), with small test-only fixes alongside #544, so the line stays unticked.

Lane: openreposhape-5 (openRepoShape-5)

(lane openRepoShape-4, 2026-10-15T19:02:18Z) Two lines for this checklist, from R588's verification of #588 (#532) at c2e19022. #588 is now on main as 709eec1. Both concern tests only; neither is user-facing.

→ 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 inventory test in tests/test_readme_windows_quoting_sentence.py (test_the_tools_that_quote_for_the_host_are_the_ones_the_sentence_names, :106) lists which shipped tools call a host-dialect quoter. It has gaps, and closing them is optional hardening:
- a quoter imported under another name (from repo_shape import shell_line as joined) is missed; R588's mutant V2 survives;
- a shipped Python file with no .py suffix, such as the root bootstrap, is not scanned (V5);
- it pins files, not lines, so a family.py line switched to POSIX quoting would still pass while the README sentence names it (V3);
- all of scripts/repo_shape.py is exempt, where only the bodies of shell_quoted and shell_line need to be.
→ 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 Sonar S5778 at tests/test_bump_leg_paste_lines.py:402-404: leg_placement(leg) is evaluated inside pytest.raises, so an exception from it would count as the expected one. The gate passes.

(lane openRepoShape-2, 2026-10-15T21:23:02Z)

These items came from this lane's v1.1.0 reviews of PRs #620, #621, #622 and #623, from its re-review of #570, and from its writers, and per the v1.0.0 rule a new edge case goes on its area's Tracking parent rather than into a new issue.

→ README.md and the handbook: the sentences #566, #572 and #573 leave false or incomplete (an ambiguous record that arrives answered, the spec mount's CONTRACTS_DIR, a second setup run refused at the plan) #606 L2-66 (nit, docs; README.md, adopt-project.py and scaffold-project.py: the Free-plan secrets hint follows the legs' visibility (adopt) or names the legs as its reason (scaffold), though the root's visibility decides it #602 review): README's "If the legs are private" paragraph ties the advice to set REPOSITORY secrets to private legs, but what decides it is whether the assembly root is private or internal. Fixed 2026-10-16 by README.md and the handbook: say that a source's own single-repository.yaml record arrives as leg: drop, that the adopted Makefile's CONTRACTS_DIR follows the spec leg's mount, and that a second setup run is refused at the plan, so the three sentences #566, #572 and #573 left false or incomplete are true of main (#606) #627 → 8062810.
- README.md:510-514 at 55faad2: "If the legs are private, CI needs a credential to fetch them: a GitHub App ... as REPOSITORY secrets on the GitHub Free plan, where organisation secrets do not reach private repositories". The validate workflow runs in the root, and on the Free plan an organisation secret reaches a public repository only. So private legs under a public root can take the credential as an organisation secret, and a private root needs repository secrets. The assembly root's own README says it by repository (templates/assembly-root/README.md:79-83), and so does README.md:628-631.
- adopt-project.py and scaffold-project.py: the Free-plan secrets hint goes by the assembly root's own visibility on GitHub and names the root as its reason, so a public source adopted with private legs is no longer told its organisation secrets resolve to EMPTY (#602) #621's body holds suggested words (impl602-free-plan-hint-root/pr-body.md, "README follow-up"): "as REPOSITORY secrets on the assembly root when it is private or internal and the organisation is on the GitHub Free plan, where organisation secrets reach only public repositories". README.md and the handbook: the sentences #566, #572 and #573 leave false or incomplete (an ambiguous record that arrives answered, the spec mount's CONTRACTS_DIR, a second setup run refused at the plan) #606 (README and handbook) does not list this line, and adopt-project.py and scaffold-project.py: the Free-plan secrets hint goes by the assembly root's own visibility on GitHub and names the root as its reason, so a public source adopted with private legs is no longer told its organisation secrets resolve to EMPTY (#602) #621 names README.md and the handbook: the sentences #566, #572 and #573 leave false or incomplete (an ambiguous record that arrives answered, the spec mount's CONTRACTS_DIR, a second setup run refused at the plan) #606 as its home, so README.md and the handbook: the sentences #566, #572 and #573 leave false or incomplete (an ambiguous record that arrives answered, the spec mount's CONTRACTS_DIR, a second setup run refused at the plan) #606 needs to take it or it stays here.
- The paragraph is in README's ## Starting a project in a new organisation section, so the change follows tests/test_repo_hygiene.py and docs/handbook.html: each handbook section records the hash of every README section it reads, and README.md's line cap is 1422 plus one file per raise in tests/readme-cap.d/, so two README pull requests no longer conflict on the footer's one blob or the cap's one line, and a stale page names exactly which sections to re-read (#519) #551's hash step for that section's seven handbook markers (for example docs/handbook.html:475). README is at its line cap, so the edit has to keep the line count or take its own tests/readme-cap.d/ file. The handbook has no twin of this sentence.
L2-67 (nit, tests; tests/test_dry_run_parity.py, scaffold-project.py and family.py init: the dry runs skip the target-exists and folder checks, and any gh repo view failure reads as "does not exist" #609 review): two tests in 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 assert POSIX strerror text and carry no Windows skip. Fixed 2026-10-16 by 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 → d4a7fab.
- At 7f7e1b4 (PR 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, not on main yet): tests/test_dry_run_parity.py:369 expects cannot be made: File exists and :608 expects cannot be made: Not a directory. On Windows mkdir words both differently, for example "Cannot create a file when that file already exists".
- CI has been Linux-only since ci: run the test suite on Linux only #597, so nothing fails today (rv609). The other strerror assertion in the file (:595-598) is already inside if os.name != "nt".
- Direction: build the expected text from the caught exception's strerror, or mark both tests POSIX-only. Make the change in 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 if it has a fix round, or after it lands.

Source reports, in opensoft/brett-wip under handoffs/xFactory/attachments/lane-openRepoShape-2/: review621-8577b15/fix-list.md (N3), review621-8577b15/final-report.md and impl602-free-plan-hint-root/pr-body.md ("README follow-up") (L2-66); review622-7f7e1b4/fix-list.md (nit 2) and review622-7f7e1b4/final-report.md ("Windows and CRLF") (L2-67).

scaffold-project.py and family.py: an existing EMPTY working tree or …

(lane openRepoShape-5, 2026-10-15T23:52:24Z) Checklist items for #461, per ruling 5, from lane 5's #596 (#585), which landed as bf7b19b. They are outside #585's lines, and none is fixed or filed.

→ openRepoShape in Git Bash: the machine: report probes python3 alone, a drive-letter $OPENREPOSHAPE_REPO or $OPENREPOSHAPE_BIN_DIR is misread, tests-git-bash skips #598's installer cases, and a doctor test's docstring is stale #649 A test's docstring says a refused $OPENREPOSHAPE_REF arrives before any clone, and --doctor clones first.
- What happens: test_a_ref_the_doctor_would_check_out_is_validated says the refusal "has to arrive before any clone does". shape_checkout runs git clone first and calls checked_ref "$REF" after it. The test passes either way: it asserts exit 2, and OPENREPOSHAPE_REF and git checkout in stderr (:678-680), and none of those pins the order.
- Where: tests/test_openreposhape_command.py:668-669 at bf7b19b (the sentence; the test is :662-684); openRepoShape:482 (shape_checkout), the git clone at :490 and checked_ref "$REF" at :495.
- Direction: reword the docstring to say the clone comes first, or check the ref before the clone so the sentence is true.
- Found by: the tests: a tests-git-bash job runs the launcher's and install.sh's suites in Git for Windows' own bash, so README and the handbook say Git Bash runs the one-line install, tested in CI but for a typed yes, which it cannot take there (#585) #596 writer.
→ Publish openRepoShape to TestPyPI and PyPI as openreposhape, so one pipx install puts the tools and git-filter-repo on any machine (design first) #563 The handbook's step 3 has no Git Bash path.
- What happens: step 3's install block and paragraph are data-platform="linux mac wsl", so a reader on the Windows tab never sees the one-line install that the Windows panel says Git Bash runs. The Windows tab shows the "Fetch the flow" heading and the PowerShell download instead.
- Where: docs/handbook.html:781 (the install block) and :782-791 (the paragraph) at bf7b19b; the Windows tab's step is :780 and :804-812; the panel's sentence about Git Bash is :724-728.
- Direction: adding the one-line install to the Windows tab is a docs decision.
- Found by: the tests: a tests-git-bash job runs the launcher's and install.sh's suites in Git for Windows' own bash, so README and the handbook say Git Bash runs the one-line install, tested in CI but for a typed yes, which it cannot take there (#585) #596 writer.
→ openRepoShape in Git Bash: the machine: report probes python3 alone, a drive-letter $OPENREPOSHAPE_REPO or $OPENREPOSHAPE_BIN_DIR is misread, tests-git-bash skips #598's installer cases, and a doctor test's docstring is stale #649 install.sh: git-filter-repo with the uv already there where there is no pipx, never pip install --user, and two readinesses at the end, adoption: then done: (#595) #598's installer cases do not run under Git Bash.
- What happens: tests-git-bash runs tests/test_openreposhape_command.py and tests/test_install_sh.py. test_install_sh.py reaches install.sh: git-filter-repo with the uv already there where there is no pipx, never pip install --user, and two readinesses at the end, adoption: then done: (#595) #598's code in two ways: every run prints adoption: and done:, and no_pipx expects uv's printed command. But the uv install, the readinesses' wording and the pasted next steps are tested in tests/test_install_sh_filter_repo.py only, on Linux. README says Git Bash runs step 3's one line, "tested in CI" (README.md:154-155).
- Where: .github/workflows/tests.yml:220, the job's pytest line (the job is :156-220), at bf7b19b; tests/test_install_sh_filter_repo.py (409 lines); install.sh:453 and :463-475 (the adoption: and done: lines); tests/test_install_sh.py:479-481 (no_pipx).
- What the file uses: it inherits test_install_sh.pytestmark (BASH_SKIP and git_bash_session; test_install_sh_filter_repo.py:52) and drives every run through Net. Its own uv fake writes LF bytes and names the interpreter as shlex.quote(sys.executable), as Net.fake does (test_install_sh_filter_repo.py:141-148, test_install_sh.py:211-218). No assert compares a path bash printed with a Python path; each checks a line's start or end. Its programs see PATH=net.path alone, so the runner's own pipx or uv cannot leak in. Under Git Bash it would likely pass.
- Direction: add the file's path to the job's pytest line, then watch one windows-latest run. tests: a tests-git-bash job runs the launcher's and install.sh's suites in Git for Windows' own bash, so README and the handbook say Git Bash runs the one-line install, tested in CI but for a typed yes, which it cannot take there (#585) #596 did not add it. Not run on Windows: 18 passed on Linux, in 7.32s, on tests: a tests-git-bash job runs the launcher's and install.sh's suites in Git for Windows' own bash, so README and the handbook say Git Bash runs the one-line install, tested in CI but for a typed yes, which it cannot take there (#585) #596's head 52524fe3.
- Found by: the tests: a tests-git-bash job runs the launcher's and install.sh's suites in Git for Windows' own bash, so README and the handbook say Git Bash runs the one-line install, tested in CI but for a typed yes, which it cannot take there (#585) #596 writer, in fix round 7.

Not filed: README's pip install git-filter-repo for adopting (README.md:768 at bf7b19b). Lane 3's open PR #630 (l3-563-docs) removes that line.

Lane: openreposhape-5 (openRepoShape-5)

(lane openRepoShape-4, 2026-10-16T11:28:29Z) One line for this checklist, from R434's review of #633 (#434), which is now on main as f1c73e2. R434 ran it as a mutant against the new test file at ac508957; it is a test gap and not user-facing, and #633 does not fix it.

→ tests: two mutants survive review: the S_ISREG child check of validate-pins.py's workflow scan (a directory named sub.yml, a dangling and a looping symlink, #434) and siblings.py's holder-root spelling in both headers (#454) #664 Test gap: the S_ISREG half of the rewritten child check is unpinned (mutant K survives). Replacing the child's kind check at validate-pins.py:345 with _is_a(path, lambda mode: True) leaves tests/test_validate_pins_unreadable_workflows_dir.py at 28 passed, and also all of test_validate_pins_unreadable_workflow.py, test_validate_pins_without_git.py, test_validate_pins_lockstep_lines.py and test_pin_validator.py together (102 passed). Over a root holding a directory named .github/workflows/sub.yml the head says pins ok, but mutant K says REFUSED workflow-unreadable: .github/workflows/sub.yml: cannot be read (Is a directory). validate-pins.py (assembly-root template): a .github/workflows/ directory that this user cannot list or search is a workflow-unreadable refusal naming it, exit 2, so the project's pins gate no longer ends in a PermissionError traceback, exit 1, where a workflow file it cannot open already was one (#434) #633 rewrote exactly that expression. A pinning test, beside test_a_workflows_path_that_is_a_file_is_still_no_workflows (:289-298 at ac508957): a control that a directory named .github/workflows/sub.yml, a dangling dangling.yml symlink and a loop.yml self-symlink are still skipped. Assert that validator._workflow_refs(project) returns the leg's reference and nothing else, or pins ok from validate(project). It is mode-free, so it runs everywhere, Windows included; Windows may need the symlink half skipped where symlinks are not allowed (R434 N1).