[brettheap]

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

What changes, and why

Adoption's first run on a Windows runner (#471's probe run 38312924968) failed one ordinary case: a source that tracks its own root .gitattributes. execute writes the shape's * text=auto eol=lf beside it at shape/.gitattributes, and git reads attributes for a path only from the .gitattributes files of its own directory and those above it, so that copy governs shape/ alone. The nine copies contracts/shape-pin.yaml names at their own paths (Makefile, AGENTS-shape.md, five under scripts/, contracts/repository-naming.yaml, .github/workflows/validate.yml) answered to the source's rule. A Windows checkout wrote them with CRLF, and validate-pins.py, which digests the bytes on disk (#51), reported shape-copy-drift on each. Under Git for Windows' default core.autocrlf=true any root .gitattributes but the shape's does it, *.png binary included, so every adopted source that keeps one was exposed. A root-level file takes attributes from the root .gitattributes alone, so no file beside the source's can fix it.

Brett Heap ruled at 2026-10-12T22:48Z (ruling A): the split appends a marked block of /<copy> text eol=lf lines to the source's own root .gitattributes. He accepted that this overrides "never written over" for that one file, that the verification gets an exception for it, and that update-shape --add extends the block.

The change, by tool

• scripts/shape_materialize.py spells the block once:
  • EOL_BLOCK_HEAD, a comment line naming openRepoShape and 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;
  • then eol_line(path), /<path> text eol=lf, for each pinned copy outside shape/ (eol_block_paths), in the pin's order. Each line is literal and anchored; a path git would read as a pattern is refused (materialize-attributes-path);
  • with_eol_block appends it after the source's bytes, adding only a final newline the file lacked;
  • materialize_assembly_root appends it when the shape's .gitattributes collided, and records the copies in Materialized.eol_block. A .gitattributes that is a symlink is not written through;
  • the .gitattributes follow-up says what the block protects, that a Windows clone reports shape-copy-drift without it, that none of the source's lines changed, and that merging the rest of shape/.gitattributes is optional. It ends with update-shape.py and shape-doctor.py: no NEXT line pre-fills --accept-local for a locally edited shape copy, so the apply a row names, pasted, meets update-local-drift and its question to the human instead of re-pinning the edit as the standard, and a shape/ collision copy merged into its original and removed is merged-away to check, whose apply drops its pin row behind the same yes, so an adopted root that did its follow-up validates green again (#501, #502) #512's sentence (update-shape.py, validate-pins.py and shape-doctor.py: once an adopted root does its own follow-up "merge shape/.gitignore into .gitignore" and removes the merged copy, the copy's pin row is copy-missing, so the project's bootstrap.py and its validate check go red, apply refuses with a remedy (--accept-local) that is refused in the same words, and no tool removes the row, which leaves only undoing the merge or the hand edit of the pin that AGENTS.md forbids #502) for every other pinned copy, under the same condition as the merge: only then remove shape/.gitattributes, after which update-shape.py check reports its pin row merged-away and apply drops the row. The follow-up for a .gitattributes that is a symlink has no such sentence, because it never sends anyone to merge or remove the copy, which stays pinned.
• adopt-project.py:
  • imports this change's four names from shape_materialize (ATTRIBUTES, eol_block_paths, eol_line, with_eol_block) in a statement of their own, so that none of them sits in the shared list 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 (open) also edits;
  • prints the append;
  • lists every line it added in the split commit's message, under APPENDED TO .gitattributes;
  • verification: _land_the_eol_block counts the source's .gitattributes as landed in the root only when its blob there is exactly the source's bytes followed by the block for the copies outside shape/, recomputed from the split's own pin. Anything else is still adopt-lost: a source line changed, the block short of a copy or holding one too many, or a line after it.
• update-shape.py apply --add names each added copy in the block:
  • through the ledger, so a refusal puts the file back, and the commit carries the file with the copies;
  • a root with no block, or whose .gitattributes is a symlink, is left alone;
  • the block is found in a CRLF checkout of the file too.
• A source with no root .gitattributes, or one the plan sends to a leg, keeps today's behaviour: the shape's own file is the root's.

Documentation

The docs are corrected in this PR (Brett Heap, 2026-10-13T11:30Z). They had first been handed to lane 5's #483 (issuecomment-6134543847, on his word at 2026-10-12T23:24Z), but #483 closed through #505 (af01068b) before this change was on main. README.md (1422 lines) and AGENTS.md (490) are at their line caps, so each keeps its count and is reworded in place:

• README.md, ### Ambiguous is an answer, and no source line is overwritten (was "nothing is overwritten"). The collision paragraph now says that a kept root .gitattributes gets a block of /<copy> text eol=lf lines appended, and that the verification counts that file "as the source's bytes plus the block". To keep the paragraph at seven lines, .gitignore leaves the example list and "after the split" leaves "root tree".
• README.md, "Why .gitattributes is one of the copies": * text=auto eol=lf "(or the block appended to an adopted root's own file, 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)" puts the answer where the digests are.
• AGENTS.md step 7: the table accounts for every source path "by blob sha (a kept root .gitattributes as the source's bytes plus the line-ending block the split appends)". This is one line longer.
• AGENTS.md, the no-code variant's item 2: it no longer restates "and the table still accounts for every source path by blob sha". It already says "step 7 included", and dropping the clause saves the line step 7 gained.
• docs/handbook.html:
  • mirrors both README paragraphs: the <strong> heading, the collision paragraph and the verification, and the .gitattributes paragraph;
  • its footer adds a clause for 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 after main's last, which is now update-shape.py, validate-pins.py and shape-doctor.py: once an adopted root does its own follow-up "merge shape/.gitignore into .gitignore" and removes the merged copy, the copy's pin row is copy-missing, so the project's bootstrap.py and its validate check go red, apply refuses with a remedy (--accept-local) that is refused in the same words, and no tool removes the row, which leaves only undoing the merge or the hand edit of the pin that AGENTS.md forbids #502's, in the footer's ; ... added (#NNN) form. Each merge of main since review round 1 that moved the footer (f391e58, d41cc29, 89c6a6c, 8beb3d9) conflicted there alone, and kept main's clauses whole;
  • its README.md blob is the hash of the merged README.md, recomputed at each of those merges (f3b378dc5704de79ee63972d0ea0be14dc693209 at 9f28d90, the value tests/test_repo_hygiene.py checks).

"The only change to its history is ONE split commit" (README.md and the handbook) is unchanged. The block is in that commit, so it still holds.

Tests

• tests/test_adopt_attributes_eol_block.py (new, no git filter-repo, so every CI job runs it):
  • the block's text;
  • the materializer's append, including the no-collision and symlink cases. The symlink case skips on Windows (needs_disk_symlinks), as the adoption suites' other disk-symlink tests do: a link whose target is spelled config/attributes leads nowhere there;
  • extending, in LF and CRLF checkouts;
  • the follow-up, whose ending is pinned exactly (update-shape.py and shape-doctor.py: no NEXT line pre-fills --accept-local for a locally edited shape copy, so the apply a row names, pasted, meets update-local-drift and its question to the human instead of re-pinning the edit as the standard, and a shape/ collision copy merged into its original and removed is merged-away to check, whose apply drops its pin row behind the same yes, so an adopted root that did its follow-up validates green again (#501, #502) #512's row sentence, under the merge's own condition), the link variant's, which says nothing of a row, and the split message;
  • the verification, with six mutants of the file, each adopt-lost.
• tests/test_adopt_ignored_shape_files.py:
  • the "Beside, not over" assertion now says the source's bytes come first and the block after them, naming nothing under shape/;
  • test_a_checkout_that_writes_crlf_still_bootstraps clones the adopted assembly under core.autocrlf=true and under core.eol=crlf, set in git's command scope so the Windows job's own core.autocrlf=false cannot outrank it. The source's own README.md, checked out CRLF, is the control, and every pinned copy must be LF on disk and bootstrap green.
• tests/test_update_shape_add.py: --add extends the block on a branch commit, leaves a root without the block alone, and a refused apply puts the block back. The module fixture's check that no copy list still names a stripped file now reads list entries, not every string in the materializer (the new ATTRIBUTES constant is not a list entry).
• tests/test_adopt_filter_repo_failure.py: the two tests whose stub git-filter-repo is a #! script lose WINDOWS_SKIP, because git starts that stub, and Git for Windows runs a #! script with its own sh. test_following_the_notice_after_a_failed_leg_ends_adoption_verified now compares the leg repositories it reads out of the notice with their spelled form: the notice names a path between backticks with each backslash escaped (adopt-project.py check and execute print a source path raw in a FINDING, so a \r, \n, \x85, U+2028 or ESC in a name overwrites, splits or escapes the line on a terminal, where plan's questions spell the same path with _spelled #212), so a Windows path reads D:\\a\\... there, and the raw str() the test compared with before holds on POSIX alone. The nine other #!-stub tests stub gh, which adopt starts through subprocess. On Windows CreateProcess finds only gh.exe there, never a .cmd, and their arguments (a pull request's body) hold newlines a batch file cannot receive. They stay skipped.
• tests/test_adopt_pins.py: the module fixture deletes its shutil.copytree copy of a repository with rmtree from tests/conftest.py, which clears the read-only bit git gives its objects and retries. shutil.rmtree raised PermissionError: [WinError 5] there, and the first Windows run of the adoption suites ended all 12 pin tests (four tests, three spellings) in an error at setup (see Runs).
• tests/test_update_shape_merged_away.py: the fixture's body is one helper, adopt_and_clone, which adopted_here and a new adopted_with_attributes (the same source, keeping a root .gitattributes) call. test_a_merged_away_attributes_copys_row_goes_and_the_root_file_stays follows the follow-up's own sentence through a real adoption. It merges shape/.gitattributes into the root file and removes it, then pastes check's NEXT: the row is merged-away, apply drops it and nothing else in the pin moves, the root file stays as the merge left it, block and all, validate-pins.py exits 0 and the doctor reads COMPLIANT.

Mutation check: three mutants, each removing one half of the fix, are each caught by the tests that pin that half. They are: no append in the materializer, no verification exception, and no --add extension.

Runs

Run locally on Linux at e2922e8 (the change on main at cc8f2da), with git-filter-repo 2.47.0 on PATH:

• the 29 files that skip without it (bar test_shape_doctor.py, run below), plus the new module: 2046 passed;
• test_shape_doctor.py, test_scaffold_leg_path_collisions.py, test_repo_hygiene.py and test_agents_md_codes.py: 553 passed, 3 skipped (the PowerShell line, printed only on a Windows host);
• all eight test_update_shape*.py files: 341 passed, 3 skipped (junctions, Windows only).

Then at 8f8cf6f, after merging main at 47b1e06 (20a188e, no conflicts) and the docs commit:

• test_shape_doctor.py, test_scaffold_leg_path_collisions.py, test_repo_hygiene.py, test_agents_md_codes.py and test_cli_reference.py (line caps, the handbook's README blob, AGENTS.md's codes): 575 passed, 3 skipped (the PowerShell line);
• the four test files this change adds or extends: 98 passed.

Then at 4aba2bd, after review round 1:

• the same five files: 575 passed, 3 skipped;
• the four test files this change adds or extends, with the six new tests: 104 passed;
• test_adopt_leg_path_collisions.py, test_adopt_e2e.py and test_adopt_root_manifest.py, the other callers of _predict_collisions and the follow-ups: 148 passed.

Then at cf2cfaf, after folding in #497 (30922cd) and NIT-6:

• test_adopt_ignored_shape_files.py, test_adopt_attributes_eol_block.py and test_repo_hygiene.py: 126 passed, none skipped;
• test_shape_doctor.py -k "filter or adopt" (tests.yml: the Windows job installs git-filter-repo 2.47.0, so the 23 test files that skip without it run there and an adoption is executed on Windows for the first time, and the comments and docstrings that said that job installs none now say why it does (#471) #497 edited its docstrings): 7 passed, 345 deselected;
• actionlint 1.7.12 on .github/workflows/tests.yml: no findings.

Then at d131876, after merging main at f391e58 (c349ab4; its one conflict was the handbook's footer) and the fixture fix to tests/test_adopt_pins.py (the verifier's run):

• test_adopt_pins.py, test_adopt_attributes_eol_block.py, test_adopt_ignored_shape_files.py, test_update_shape_add.py and test_repo_hygiene.py: 216 passed, none skipped;
• test_shape_doctor.py, test_scaffold_leg_path_collisions.py, test_agents_md_codes.py and test_cli_reference.py: 526 passed, 3 skipped (the PowerShell line).

Then at 91ed4a5, after merging main at d41cc29 (cb5f5a7) and at 89c6a6c (c8cb46a), each with the handbook's footer as its one conflict, and moving the .gitattributes-symlink paragraph of collision_follow_up's docstring up beside the docstring's first paragraph, so that the docstring's end, which #512 (#502) also extends, merges without a hand resolution:

• the three hygiene files, test_adopt_pins.py, test_adopt_attributes_eol_block.py, test_adopt_ignored_shape_files.py, test_adopt_execute_refusals.py, test_adopt_filter_repo_failure.py, test_adopt_clone_template.py, test_adopt_entry_paths.py, test_adopt_mount_ignored.py, test_adopt_submodules.py, test_adopt_verify.py, test_update_shape_add.py, test_shape_doctor.py and test_scaffold_leg_path_collisions.py: 1264 passed, 3 skipped.

Then at 9f28d90, after two more merges of main, the fold, and the import move:

• main at 8beb3d9 (000b0b0: update-shape.py and shape-doctor.py: no NEXT line pre-fills --accept-local for a locally edited shape copy, so the apply a row names, pasted, meets update-local-drift and its question to the human instead of re-pinning the edit as the standard, and a shape/ collision copy merged into its original and removed is merged-away to check, whose apply drops its pin row behind the same yes, so an adopted root that did its follow-up validates green again (#501, #502) #512, with adopt-project.py: --org and --project must name the repository the source names, compared without case, so plan refuses --project BillingService for acme/billing-service as adopt-not-the-source instead of writing a plan whose execute acts on acme/BillingService, check finds and execute refuses a plan edited to name another as plan-not-the-source, and a source whose own name the naming policy refuses is told to rename it first, never to retype --project (#499) #513 and openRepoShape --doctor: the installed form keeps the clone of the standard it ran from and names it on the report's last line, so a NEXT line pasted after the command has exited runs instead of dying with can't open file, and it hands --json and --placement-plan <file> on to shape-doctor.py instead of refusing them (#500) #510 before it) conflicted in the handbook's footer alone. main at b0826e0 (7924d75: adopt-project.py: check follows each symlink the plan keeps where the shape writes its files, and execute refuses one the shape cannot write through, or one it writes beneath that git checks out as a file, before any leg exists, so such a link no longer breaks the run after both legs are pushed or has the shape's files written outside the assembly (#183, #178) #504, lane 1's check of root-kept symlinks) conflicted in three hunks, in adopt-project.py's from shape_materialize import (...) list and in materialize_assembly_root's docstring and tail, and each keeps both sides: adopt-project.py: check follows each symlink the plan keeps where the shape writes its files, and execute refuses one the shape cannot write through, or one it writes beneath that git checks out as a file, before any leg exists, so such a link no longer breaks the run after both legs are pushed or has the shape's files written outside the assembly (#183, #178) #504's spell is passed through, and the .gitattributes block is appended after it. adopt-project.py: check follows each symlink the plan keeps where the shape writes its files, and execute refuses one the shape cannot write through, or one it writes beneath that git checks out as a file, before any leg exists, so such a link no longer breaks the run after both legs are pushed or has the shape's files written outside the assembly (#183, #178) #504 does not touch the handbook;
• the two changes do not contradict each other, asked of real adoptions through plan, check and execute (the symlinks are under Known limits). materialize-attributes-path needs no spell: only eol_line raises it, over the shape's own copy-list names, which are never resolved through a link, and spell is for the names a source's symlinks lead to;
• the fold is 8579d4f (the follow-up's row sentence and its tests, above). The import move is 9f28d90: merging 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 (open) into this branch has the same conflict regions in adopt-project.py as merging it into main at b0826e0, compared region by region, so this change adds none;
• 22 files, with git-filter-repo 2.47.0 on PATH: 1771 passed, 3 skipped, none failed. The skips are the PowerShell line (tests/test_shape_doctor.py:9119, printed only on a Windows host), and no adoption test skipped. The files are the three hygiene files; test_adopt_attributes_eol_block.py, test_adopt_pins.py, test_adopt_ignored_shape_files.py, test_adopt_execute_refusals.py, test_adopt_filter_repo_failure.py, test_adopt_clone_template.py, test_adopt_entry_paths.py, test_adopt_mount_ignored.py, test_adopt_submodules.py, test_adopt_verify.py, test_adopt_project_is_the_source.py, test_adopt_leg_path_collisions.py, test_adopt_root_symlinks.py and test_adopt_finding_spelling.py; test_update_shape_add.py, test_update_shape_merged_away.py and test_update_shape.py; test_shape_doctor.py and test_scaffold_leg_path_collisions.py.

Then at 1ce4f45, the head, after merging main at 3121945 (#494, lane 3's change for #370: a refusal built without a remedy prints its REFUSED line alone):

• the merge was clean. No file conflicted, and the handbook's footer was not touched, because repo_shape.py, validate-pins.py, family.py: a refusal built without a remedy prints its REFUSED line alone, the assembly root's validate-pins.py still adds the lockstep remedy to its own, and add refuses a .gitmodules git cannot rea (#370) #494 changes neither README.md nor docs/handbook.html (the README blob stays f3b378dc5704de79ee63972d0ea0be14dc693209). The two changes share only adopt-project.py, where repo_shape.py, validate-pins.py, family.py: a refusal built without a remedy prints its REFUSED line alone, the assembly root's validate-pins.py still adds the lockstep remedy to its own, and add refuses a .gitmodules git cannot rea (#370) #494's one hunk is in _failed_loudly, which this change does not touch. The one refusal this change adds, materialize-attributes-path, names its own remedy, so it prints as it did;
• the 22 files above and repo_shape.py, validate-pins.py, family.py: a refusal built without a remedy prints its REFUSED line alone, the assembly root's validate-pins.py still adds the lockstep remedy to its own, and add refuses a .gitmodules git cannot rea (#370) #494's test_refusal_default_remediation.py: 1791 passed, 3 skipped (the PowerShell line), none failed, and no adoption test skipped.

The Windows probe was ci/w471-probe-2 (b09370d): this change at b2c0924, before its rebase onto cc8f2da, with #497's git-filter-repo install, run on Windows only over the files that skip without it and the two test files this change adds or extends, with no xfail mark. Run 38321799510: 1754 passed, 2 failed, 32 skipped. test_the_assembly_bootstraps_where_it_failed_with_shape_copy_missing[its-own-attributes], the case #471 found, passed there. The two failures were the tests' own and are fixed above: the notice-following test's expectation, and the symlink test's missing Windows skip. Neither fix changes a tool, so no third probe was run.

This pull request's own tests-windows job installs git-filter-repo too (#497 is folded in, below), so its CI was the first to run the adoption suites on Windows over this fix:

• cf2cfaf (run 38398207725) ended 6517 passed, 561 skipped, 12 errors in 1:21:06, and no test failed. All 12 errors were at the module fixture of tests/test_adopt_pins.py (four tests, three spellings): PermissionError: [WinError 5] from shutil.rmtree over the read-only objects of a copied repository. d131876 is the fix (see Tests);
• d131876 (run 38418701101) passed on all three OSes, and so did 91ed4a5 (run 38483318578), whose Windows job took 127.5 minutes;
• 9f28d90 (run 38569393760) passed on all three OSes and SonarCloud. Its Windows job finished at 15:27Z, 138 minutes after the run started. It is this pull request's H0 under ruling 27;
• 1ce4f45, its clean merge of main at 3121945, is the head (run 38591604388): Linux tests passed at 16:04Z and SonarCloud at 15:42Z. That is what ruling 27 asks of a head that adds only a clean merge of main to H0. Its macOS and Windows jobs were still running when this body was written.

Review round 1 (#511 at 8f8cf6f, NOT MERGEABLE on one MUST)

Fixed at ea9c209 (tools and tests) and 4aba2bd (README.md); no amend, rebase or force.

• MUST-1, a symlinked .gitattributes under core.symlinks=false:
  • Git for Windows' default checks a tracked link out as a plain file holding its target's path. So the disk check said "not a link", and the block was appended INTO the link: the split kept mode 120000 over the old target followed by the block. execute then said "none of its own lines was changed" and failed adopt-lost: .gitattributes after both legs were pushed. Main verifies the same source.
  • _append_eol_block now also asks git's index (_tracked_as_link, ls-files --stage, mode 120000).
  • Tests, on every platform, with the link in the index only:
    • test_a_link_checked_out_as_a_plain_file_is_not_written_through, in the materializer, with the link checked out under core.symlinks=false;
    • test_a_linked_attributes_file_checked_out_as_a_plain_file_adopts, end to end, with core.symlinks=false in git's command scope for every git the run starts. The split's entry is the source's 120000 blob, unchanged, and the run verifies.
• SHOULD-2, the follow-up for a link was false:
  • plan now reads the link from the source tree's mode. Its follow-up says the split appended nothing, says git reads no .gitattributes that is a symlink, and names the remedy: a regular file in its place, or a clone's .git/info/attributes for that clone alone. It lists the exact lines.
  • test_the_follow_up_for_a_linked_attributes_file_lists_the_lines_it_needs checks those lines against the ones the materializer gives a regular file. The end-to-end test above reads the follow-up in the plan and in the split message.
• SHOULD-3, own .gitattributes plus a root-kept contracts -> meta:
  • The verification looked for the shape's pin among the split's plain files, so this source ended adopt-lost: .gitattributes. Main verifies it.
  • The pin is now read through the split's links (_pin_through_links over _SplitTree), as _shape_file_findings reads it. The docstring is corrected.
  • Tests:
    • test_the_pin_is_read_through_a_link_the_root_kept, with the link in the tree only, on every platform;
    • test_own_attributes_and_a_linked_contracts_kept_in_the_root_adopt, end to end, with a disk link (needs_disk_symlinks).
• NIT-1: --add now extends the LAST head line, which is the block adoption appended (test_the_last_block_is_extended_when_the_source_held_the_head_already).
• NIT-4: README.md's --add sentence now says that it names the file in a root .gitattributes block of 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. Lines 1078-1088 are re-wrapped, and README.md stays at 1422 lines. The handbook's README blob is recomputed at every footer round, so no value is kept here (see Documentation). The handbook does not list --add's acts.
• SHOULD-1: resolved by folding tests.yml: the Windows job installs git-filter-repo 2.47.0, so the 23 test files that skip without it run there and an adoption is executed on Windows for the first time, and the comments and docstrings that said that job installs none now say why it does (#471) #497 in (below), with its xfail removed by hand in the merge commit.
• NIT-2, NIT-3 and NIT-5: listed under Known limits.

Mutants, each undoing one fix, were run against the new tests in a scratch worktree at 4aba2bd: the unmutated tree passed all 6 new tests, and each mutant was caught:

• disk-only-link-check (MUST-1) failed both link tests;
• flat-pin-lookup (SHOULD-3) failed both contracts -> meta tests;
• no-link-follow-up (SHOULD-2) failed the follow-up test and the end-to-end one;
• first-head (NIT-1) failed the last-block test.

Folded in #497

#497 (ci/windows-adoption-suites) is superseded by this pull request. Its two reviewed commits are merged here at 30922cd, the merge of its head 6824181, which also carries #497's update-branch merge of cc8f2da:

• a528006:

  • tests.yml's tests-windows job installs git-filter-repo 2.47.0, the ubuntu job's pin, on one PowerShell line, and still runs the whole suite;
  • the workflow's comments, and seven test docstrings that named the Windows job as the one without the tool, now say what stays true.

  At tests.yml: the Windows job installs git-filter-repo 2.47.0, so the 23 test files that skip without it run there and an adoption is executed on Windows for the first time, and the comments and docstrings that said that job installs none now say why it does (#471) #497's base, 23 test files skipped without the tool (the 21 that spell shutil.which("git-filter-repo"), test_adopt_filter_repo_failure.py and test_adopt_git_reads.py), 178 of their 1731 items. The tool adds about 8 to 11 minutes to the Windows job. Its first run there was probe run 38312924968: 1696 passed, 34 skipped, and 1 failed, the case this change fixes.

• a8b5064: a strict Windows xfail (WINDOWS_CRLF_COPIES) on test_the_assembly_bootstraps_where_it_failed_with_shape_copy_missing[its-own-attributes].

The two branches merged with no conflict, so git kept that xfail. Over this fix the case passes on Windows (probe run 38321799510), and a strict xfail that passes fails as XPASS(strict). The merge commit therefore removes it by hand, as #511's review gave it:

• it keeps tests.yml: the Windows job installs git-filter-repo 2.47.0, so the 23 test files that skip without it run there and an adoption is executed on Windows for the first time, and the comments and docstrings that said that job installs none now say why it does (#471) #497's module docstring change at lines 26-27;
• it deletes the #: KNOWN ON WINDOWS, AND STRICT comment and the WINDOWS_CRLF_COPIES constant;
• it restores the test's (adopted, tmp_path) signature, without request and without the applymarker lines.

git diff 4aba2bd 30922cd -- tests/test_adopt_ignored_shape_files.py is #497's two docstring lines and nothing else. actionlint 1.7.12 on .github/workflows/tests.yml reports nothing.

Known limits, for #457's checklist

• A project adopted before this change has no block, and update-shape --add only extends a block that is there.
• A root .gitattributes that is a symlink (on the disk, or only in git's index) gets no block. Git reads no .gitattributes that is a link, so the pinned copies at the root still check out CRLF on Windows until a human replaces the link with a regular file. The plan's follow-up says so and lists the exact lines. Since adopt-project.py: check follows each symlink the plan keeps where the shape writes its files, and execute refuses one the shape cannot write through, or one it writes beneath that git checks out as a file, before any leg exists, so such a link no longer breaks the run after both legs are pushed or has the shape's files written outside the assembly (#183, #178) #504 (b0826e0), check refuses three such links as plan-root-symlink, and execute refuses them before any leg exists: a dangling one, one to an absolute path with nothing there, and one that climbs above the root to nothing. This change alone wrote the shape's copy through the first two (the absolute one wrote a file outside the assembly) and failed after both legs were pushed on the third. Every link check passes gives the same split as this change alone, blob for blob: the link kept, no block, the shape's copy beside it.
• A nested .gitattributes that sets eol or -text for a pinned copy under it outranks the root block for that copy.
• A copy written through a root-kept symlinked directory (.github -> ci) is named by its link spelling, so its line in the block governs nothing (NIT-2). adopt-project.py: check follows each symlink the plan keeps where the shape writes its files, and execute refuses one the shape cannot write through, or one it writes beneath that git checks out as a file, before any leg exists, so such a link no longer breaks the run after both legs are pushed or has the shape's files written outside the assembly (#183, #178) #504 still accepts such a link. Measured at 1ce4f45 with a source rule * text=auto eol=crlf, validate-pins.py reports shape-copy-drift for that one copy. This is not a regression: main at 3121945, with no block, reports nine for the same source.
• A source .gitattributes committed with CRLF under a non-auto text/eol rule is renormalised whole when the split re-stages it. It fails closed, as adopt-lost: .gitattributes (NIT-3). A CRLF blob under * text=auto is fine. Main at 3121945 behaves the same.
• Out of scope: the block settles line endings only. A source filter= or working-tree-encoding= rule still reaches a pinned copy. With *.py working-tree-encoding=UTF-16LE-BOM, execute stops after both legs exist, at git add -A. An ident rule reaches none, because no pinned copy holds $Id$.

Closes #471

🤖 Generated with Claude Code

[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 3 days and 9 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[sourcery-ai]

Reviewer's Guide

This PR fixes Windows bootstrap drift for adopted projects that keep a root .gitattributes by appending an exact, pinned-copy-specific LF block, teaches adoption verification and update-shape --add to handle that exception transactionally, and adds cross-platform tests and documentation.

Sequence diagram for adopting a project with a root .gitattributes

sequenceDiagram
    participant Adopt as adopt-project.py
    participant Materializer as shape_materialize.py
    participant Source as Source root
    participant Git as Git checkout
    participant Verify as Adoption verification

    Adopt->>Materializer: materialize_assembly_root()
    Materializer->>Source: with_eol_block(existing, eol_block_paths)
    Source-->>Materializer: Source bytes plus exact pinned-copy LF block
    Materializer-->>Adopt: Materialized.eol_block
    Adopt->>Verify: _land_the_eol_block()
    Verify->>Verify: with_eol_block(source bytes, pinned paths)
    Verify-->>Adopt: Count root .gitattributes as landed
    Git-->>Source: Checkout pinned copies with LF bytes

Loading

Sequence diagram for extending the LF block with update-shape --add

sequenceDiagram
    participant User
    participant Update as update-shape.py
    participant Ledger as Rollback ledger
    participant Attributes as Root .gitattributes
    participant Pin as Shape pin

    User->>Update: apply --add
    Update->>Attributes: extend_eol_block(existing, added paths)
    Attributes-->>Update: Extended block
    Update->>Ledger: write(.gitattributes, extended block)
    Update->>Pin: Repin added copies
    Update->>Ledger: Commit paths including .gitattributes
    Ledger-->>User: Refusal restores original file

Loading

File-Level Changes

Change	Details	Files
Append and maintain a marked line-ending block in adopted roots that retain their own .gitattributes.	Generate anchored /<copy> text eol=lf entries for pinned copies outside shape/, preserving source bytes and handling missing final newlines. Avoid writing through symlinked attributes files and provide targeted follow-up guidance. Record appended entries in materialization results and the split commit message.	scripts/shape_materialize.py adopt-project.py
Teach adoption verification to accept the attributes-file exception without weakening exact source accounting.	Recompute the expected block from the split's pin and count the root file only when it is exactly the source bytes followed by that block. Continue reporting adopt-lost for missing, extra, reordered, trailing, or modified content.	adopt-project.py
Extend adopted line-ending blocks when new copies are added.	Detect and extend existing blocks in LF or CRLF checkouts without duplicating entries. Use the rollback ledger so refused updates restore the attributes file, while leaving roots without a block or symlinked files unchanged.	update-shape.py scripts/shape_materialize.py
Add coverage for materialization, verification, Windows checkout behavior, and update rollback.	Test block formatting, path validation, collision and symlink behavior, follow-up text, commit messaging, and verification mutants. Exercise CRLF-producing clones and bootstrap validation on Windows-like configurations. Cover update-shape.py apply --add, including idempotence and refusal rollback, and make filter-repo failure tests Windows-compatible.	tests/test_adopt_attributes_eol_block.py tests/test_adopt_ignored_shape_files.py tests/test_update_shape_add.py tests/test_adopt_filter_repo_failure.py
Update operator and user documentation to describe the .gitattributes exception and verification semantics.	Clarify that no source lines are overwritten while a kept root .gitattributes receives an appended block. Document verification as source bytes plus the exact block and update the handbook's README blob reference.	README.md AGENTS.md docs/handbook.html

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#471	Install git-filter-repo 2.47.0 in the Windows CI job so the adoption suites execute there rather than skip.	❌	The PR explicitly says its Windows job still does not install git-filter-repo and that the suites will run only after #497 lands. It adds Windows-relevant tests, but does not close the CI installation gap.
#471	Fix ordinary-repository Windows adoption failures, including line-ending handling and the other identified Windows issues such as paths, launching git-filter-repo, and cleanup of read-only object files.	❌	The PR addresses the root-.gitattributes line-ending failure: it appends and verifies a block of LF rules and tests CRLF checkouts. It does not implement the other ordinary Windows fixes named by the issue, so this broader objective is only partially addressed.
#471	Measure the adoption suites' cost on Windows and establish how and when to run full macOS and Windows release-commit CI, including a dispatch run if needed.	❌	The PR reports a targeted Windows probe, but does not measure the suites' added runtime in the Windows job or resolve whether they should run on every PR. It also does not add or document a workflow_dispatch release-commit run.

---

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.

[brettheap]

(lane openRepoShape-1, 2026-10-13T23:35:35Z)

A note for lane openRepoShape-4: lane 1 holds opensoft/openRepoShape main for PR #504. Please do not land on main until LANES.md says #504 LANDED or HOLD WITHDRAWN.

• The HOLD. It is Amendment 10, written on LANES.md at 2026-10-13T23:05:14Z. A refresh line names main 173c00e. It applies Brett Heap's HOLD-per-landing rule, a RULED line in lanes/log/openRepoShape-1.md at 11:03:55Z.
• openRepoShape --doctor: the installed form keeps the clone of the standard it ran from and names it on the report's last line, so a NEXT line pasted after the command has exited runs instead of dying with can't open file, and it hands --json and --placement-plan <file> on to shape-doctor.py instead of refusing them (#500) #510 landed under it at 23:32:40Z. No harm was done: it touches none of adopt-project.py: check follows each symlink the plan keeps where the shape writes its files, and execute refuses one the shape cannot write through, or one it writes beneath that git checks out as a file, before any leg exists, so such a link no longer breaks the run after both legs are pushed or has the shape's files written outside the assembly (#183, #178) #504's files, so adopt-project.py: check follows each symlink the plan keeps where the shape writes its files, and execute refuses one the shape cannot write through, or one it writes beneath that git checks out as a file, before any leg exists, so such a link no longer breaks the run after both legs are pushed or has the shape's files written outside the assembly (#183, #178) #504 took it with gh pr update-branch. But adopt-project.py: check follows each symlink the plan keeps where the shape writes its files, and execute refuses one the shape cannot write through, or one it writes beneath that git checks out as a file, before any leg exists, so such a link no longer breaks the run after both legs are pushed or has the shape's files written outside the assembly (#183, #178) #504's three-OS CI had to restart, and Windows alone takes 75-100 minutes.
• This PR changes adopt-project.py, one of adopt-project.py: check follows each symlink the plan keeps where the shape writes its files, and execute refuses one the shape cannot write through, or one it writes beneath that git checks out as a file, before any leg exists, so such a link no longer breaks the run after both legs are pushed or has the shape's files written outside the assembly (#183, #178) #504's files. If it landed under the HOLD, adopt-project.py: check follows each symlink the plan keeps where the shape writes its files, and execute refuses one the shape cannot write through, or one it writes beneath that git checks out as a file, before any leg exists, so such a link no longer breaks the run after both legs are pushed or has the shape's files written outside the assembly (#183, #178) #504 would need a new tested merge, not just an update-branch.
• The end of the HOLD. It ends with a HOLD RELEASED line on LANES.md once adopt-project.py: check follows each symlink the plan keeps where the shape writes its files, and execute refuses one the shape cannot write through, or one it writes beneath that git checks out as a file, before any leg exists, so such a link no longer breaks the run after both legs are pushed or has the shape's files written outside the assembly (#183, #178) #504 lands. That is expected around 01:00-01:15Z if CI stays green.

Thank you.

[sonarqubecloud]

Quality Gate passed

Issues
5 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