[brettheap]

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

Goal (#646): no remedy family.py prints un-registers a member that is in the holder. Three states are outside it, each under "Left out": a .gitmodules that a git mv made name the variant too (checklist candidate (e)); a file the index holds at or under the row's path, where #574's remedy is kept; and a file or link the index holds at members itself (candidate (h)).

What was wrong

A member's only gitlink sat at Members/<P>, while its row and .gitmodules said members/<P>. This is #363's state after the fact. family.py add of ANOTHER member refused, as #574 rules (family-members-dir-variant). Its remedy was #574's remedy for any path under another spelling of members/:

• git rm -r --cached -- Members/<P>, and commit the removal, where nothing is on disk in that spelling;
• git mv -- Members/<P> <new name>, and commit the rename, where something is;
• git commit, where HEAD alone holds it (the variant's removal staged, not committed).

Each one, typed as printed, left no gitlink at the row's path. The holder's validator then refused member-gitlink-absent. Reproduced on BASE a524542 in all five layouts below.

What changed

All in scripts/family.py.

• _members_spellings takes the rows' own paths (_rows_paths: the one path _member_path gives a row, members/<project>; a row it refuses is member-path's).
• Which path is the member's own. The index must hold nothing at or under the row's path. Then a gitlink at a case variant of that path, in the index or in HEAD alone, is that member's. It gets a new remedy, RESTORE, placed in REMEDY_ORDER after the index's own remedies.
• The remedy is the index-only move that validate-family.py prints for the same state since validate-family.py and family.py: a gitlink no section of HEAD's .gitmodules gives is member-gitmodules-absent, remove refuses a holder with no .gitmodules before deinit, and two gitlink remedies name what they missed (#611) #639. Brett Heap accepted it on 2026-10-16T11:21:49Z ("Accept; merge validate-family.py and family.py: a gitlink no section of HEAD's .gitmodules gives is member-gitmodules-absent, remove refuses a holder with no .gitmodules before deinit, and two gitlink remedies name what they missed (#611) #639 after 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"), in place of the "committed git mv" of his "Refuse on every disk" ruling, because git mv to the row's path fails or misplaces the gitlink:
  • git rm -r --cached --ignore-unmatch -- <variants>. It touches no file, and it is no error where HEAD alone holds the variant. Where a sparse checkout keeps a variant off disk (skip-worktree), the line says git rm -r --cached --sparse --ignore-unmatch -- ….
  • git update-index --add --cacheinfo 160000,<commit>,members/<P>, one line per row, at the commit the variant entry records. For an unmerged variant, that is the commit at stage 2.
  • A commit, where one is left to make.
• What the disk holds afterwards gets the validator's own sentences, placed after every other remedy:
  • where nothing is checked out at the row's path, as in a fresh clone, git submodule update --init --recursive;
  • on a case-sensitive disk, mv -- Members/<P> ../Members-<P> for the directory left at the variant;
  • on macOS and Windows, leave it, since it is the row's own directory.
• A directory on disk at a gitlink moved back from HEAD is the move's to name. It is not named a second time as untracked.

The branch merges main 35133f2, which holds #639 (c6122e8), in one merge commit with no conflict.

Example: the issue's state, the checkout at members/IRRS:

REFUSED family-members-dir-variant: the family root holds a path at or under another spelling of members/, which a case-insensitive disk takes for members/ itself — in the index: `Members/IRRS` (a submodule)
Remediation: every member is mounted under members/, and a holder keeps that directory in one spelling on every disk. Move each member's gitlink held only under another spelling of its row's path, `Members/IRRS` for the row members/IRRS, to that path, at the commit it records, in the index alone, which touches no file (`git rm -r --cached --ignore-unmatch -- Members/IRRS`, then `git update-index --add --cacheinfo 160000,<commit>,members/IRRS`), and commit that; where nothing is checked out at members/IRRS, as in a fresh clone, `git submodule update --init --recursive` then checks the member out there; on a case-sensitive disk, as Linux's usually is, a directory left at Members/IRRS stays there, untracked, and add refuses it as family-members-dir-variant: move each one that is there out of the holder, `mv -- Members/IRRS ../Members-IRRS`; on macOS and Windows it is the row's own directory, so leave it; then re-run.

No pinned file changes: scripts/family.py is the standard's own tool, not a copy in a holder. No --help text changes, so docs/cli.md is untouched. A git grep of AGENTS.md, README.md, docs/handbook.html and the family-root templates found no sentence about add's case-variant remedies, so none became false.

Decisions and their evidence

1. The member's own gitlink: one whose path folds to a row's path, where the index holds nothing at or under that path. The next commit records the index, and every remedy here ends in one.

   • If the index holds the row's gitlink, a gitlink at a variant is a second one. Taking it out removes nothing from the row, so it keeps family.py: add refuses, before the member is read and on every disk, any path under another spelling of members/, in its index, in HEAD or on disk, and names a remedy per entry that never moves the members' checkouts (#362, #363, #364) #574's remedy, and moving it back would overwrite the row's gitlink.
   • If the index holds a FILE at the row's path, the move would replace it without a word. If it holds files UNDER the row's path, the move's second line fails (appears as both a file and as a directory) after the first has already taken the variant out. Both keep family.py: add refuses, before the member is read and on every disk, any path under another spelling of members/, in its index, in HEAD or on disk, and names a remedy per entry that never moves the members' checkouts (#362, #363, #364) #574's remedy (lane 3's review RV670, N3).
   • A file at the variant, or anything under it, also keeps family.py: add refuses, before the member is read and on every disk, any path under another spelling of members/, in its index, in HEAD or on disk, and names a remedy per entry that never moves the members' checkouts (#362, #363, #364) #574's remedy.
   • test_only_the_members_own_gitlink_is_moved_back holds all of these, 9 cases.

2. The commit named is the one the variant entry records, so the remedy is a move, not a bump. Brett Heap decided this at 2026-10-16T14:11:42Z: "take all recommendations for family.py: add's refusal of a member's own gitlink held only under another spelling of its row's path moves it back to that path in the index alone, so the printed remedy no longer takes the member's gitlink away from its row (#646) #670 and validate-family.py: a staged git rm is named again and fails retyped, the member-gitlink-absent remedy ends in a refused add, a shape-pin row with no path: reads None, and #639's mv orphans a live checkout and is stated by OS #681". That word replaces his 13:07:34Z take of "the row's pin".

   • Where a row has two variants, the first found is named, the index's before HEAD's.
   • This departs from family.py add: where another member's own gitlink sits at a case variant (Members/<P> for its row members/<P>), the refusal's remedy prints git rm -r --cached or git mv, which takes that member's gitlink away from its row #646's Direction line (<pin>) and from validate-family.py and family.py: a gitlink no section of HEAD's .gitmodules gives is member-gitmodules-absent, remove refuses a holder with no .gitmodules before deinit, and two gitlink remedies name what they missed (#611) #639's rule: validate-family.py and family.py: a gitlink no section of HEAD's .gitmodules gives is member-gitmodules-absent, remove refuses a holder with no .gitmodules before deinit, and two gitlink remedies name what they missed (#611) #639's restore in validate-family.py names the row's pin. The two tools give different lines where the variant records a commit the row does not pin, and, since S1, where a sparse checkout keeps the variant off disk: add prints --sparse and the validator does not (candidate (f)).
   • The four reasons, as lane 3's review RV670 measured them:
     1. A pure rename. With the variant's commit, the move changes only the path. Where the commits differ, the gate then reports member-gitlink-mismatch, which has its own LOCKSTEP text and bump remedy, and exits 1, and an add of another member still goes through. test_a_commit_the_row_does_not_pin_is_moved_not_bumped types that end to end. (Where the variant equals the pin, the bytes are the same either way.)
     2. The pin would silently bump. With the pin, the paste changes the commit the holder records: a roll-back or an advance, a bump done outside bump, which the LOCKSTEP text says the gate refuses.
     3. A row with no pin needs a fallback. The validator never prints its remedy for such a row, because member-pin or member-pin-commit stops the row first. So validate-family.py and family.py: a gitlink no section of HEAD's .gitmodules gives is member-gitmodules-absent, remove refuses a holder with no .gitmodules before deinit, and two gitlink remedies name what they missed (#611) #639's rule has no answer there, and a pin-based add would need the variant's commit anyway.
     4. A pin absent from the clone fails. update-index --cacheinfo does not check that the object exists, and the printed git submodule update --init --recursive then fails with rc=128 (Fetched in submodule path 'members/IRRS', but it did not contain 3333…). The variant's commit is already recorded, so this remedy adds no new unreachable commit.
   • The validator is not changed. Naming the variant's commit there too (it already prints it, as (at <commit>)) would edit a pinned template, and that needs its own word, which nobody has given.

3. An unmerged variant is moved back at its stage-2 commit (RV670, N2). ls-files -s lists stage 1, the merge base, first, and the PR's first head took that one.

   • Stage 2 is HEAD's entry each time, so the move is a rename relative to HEAD, and the validator also answers an unmerged path from HEAD. In a merge and in a stash pop it is the holder's own side. In a rebase it is the upstream's side, which is HEAD while the rebase runs: after git rebase --quit the move names the upstream's commit, not the person's own, which is stage 3 (probed by rv670b, the re-verify of this PR).
   • The removal takes out every stage, and the commit after it goes through ($Q/v112/w646b/probes/w646b-unmerged-probe.log).
   • An unmerged variant with no gitlink at stage 2 is no member's own: HEAD's entry holds no gitlink there, whatever stages 1 and 3 hold. It keeps family.py: add refuses, before the member is read and on every disk, any path under another spelling of members/, in its index, in HEAD or on disk, and names a remedy per entry that never moves the members' checkouts (#362, #363, #364) #574's remedy, where stage 2 is missing and where it is a file. A gitlink at stage 1, a file at stage 2 and a gitlink at stage 3 is an OWN state too (rv670b's NIT-3): git lists stage 1 first, and rv670b's mutant R1, which read the first record's mode in place of stage 2's, passed all 36 tests and moved the file's blob back as a gitlink.
   • The state is reachable only with unmerged entries and no in-progress mark. A conflicted git stash pop leaves it, and so do git merge --quit and git rebase --quit (rv670b probed both). add refuses a merge, rebase, cherry-pick, revert or git am in progress (family-operation-in-progress) before it gets here.

4. A variant a sparse checkout keeps off disk is taken out with --sparse (RV670, S1). Without it, git rm -r --cached --ignore-unmatch exits 0 and removes nothing, so the index then held two gitlinks, and the next add refused again. With it, the entry goes, measured on git 2.43 with and without core.sparseCheckout ($Q/v112/w646b/probes/w646b-sparse-probe-*.log). The flag is printed only where a variant needs it, so the line stays the validator's everywhere else. Git older than 2.34 has no git rm --sparse: see "Left out".

5. The commit is printed only where one is left to make. That is:

   • HEAD holds a variant (RV670's S2 state, HEAD holding the gitlink in both spellings at one commit, is one of these);
   • HEAD's gitlink at the row's path is another commit, or there is none;
   • or a pending change is committed first.

   A move to the variant that is only staged, with HEAD still holding the row's gitlink at that commit, leaves nothing to commit, and a printed git commit would fail as typed.

6. The code stays family-members-dir-variant (or member-path-taken where some path is also a variant of the new member's mount path). The add is still refused for this path, as for any path under another spelling of members/: with core.ignorecase set, git would stage the new gitlink as Members/<new> (family.py add cannot add any member, under core.ignorecase=true (the macOS and Windows default), to a holder whose index holds a path under a case variant of members/ itself such as Members/README, because git stages the new gitlink as Members/<P> and the commit's members/<P> matches nothing, and the remedy its closing sentence prints fails the same way every time: a policy question for the maintainer, whether add refuses such an index up front, and on which disks #362). Only the remedy changes.

7. The closing sentences come last, after family.py: add refuses, before the member is read and on every disk, any path under another spelling of members/, in its index, in HEAD or on disk, and names a remedy per entry that never moves the members' checkouts (#362, #363, #364) #574's disk remedies.

   • Where a members/ renamed by hand is moved back (mv -- Members members), the checkout goes home with it.
   • If they came before that, the mv out of the holder would act on Members/<P> while it may still be the member's checkout. And git submodule update would make a members/, inside which mv -- Members members would then put Members (members/Members).
   • test_with_the_other_remedies…[members/ renamed by hand] holds the order: it types the move back and then git submodule update, which checks the member out in the members/ moved back.

8. One text on every disk. The move reads the index and HEAD, never the disk. The dry run and the real run print the same two lines. Asked in process of an emulated folding disk and of a Linux one (disk_as, as tests/test_family_members_case_variants.py emulates it), each layout gives the same text the subprocess gives.

9. The disk after the move.

   • On a case-sensitive disk the variant keeps either a checkout (15 entries, ?? Members/) or, after a fresh clone, an empty directory. The gate passes either way.
   • If the printed mv is not typed, the next add refuses family-members-dir-variant ... on disk and untracked: Members/Atlas with family.py: add refuses, before the member is read and on every disk, any path under another spelling of members/, in its index, in HEAD or on disk, and names a remedy per entry that never moves the members' checkouts (#362, #363, #364) #574's mv -- Members/Atlas <new name>, and passes once that is typed.
   • If the printed mv is typed, the next add passes at once ($Q/v110/w646/leftover.log, repro-head.log).

Tests

All runs used $Q/v110/run9.sh: a gh stub that exits 97 first on PATH, GH_TOKEN=bogus-l5, an empty GH_CONFIG_DIR, /usr/bin/python3 -m pytest, and local bare remotes only.

tests/test_family_add_member_variant.py is new, with 37 tests. Every printed command is typed as printed. The holder's gate then passes (or, in the one case where the variant records a commit the row does not pin, names that drift), the member is where its row says at its commit, and the same add goes through.

• test_each_layout_moves_the_gitlink_back_as_printed (4 layouts) and test_a_fresh_clone_moves_the_gitlink_back_as_printed.
• test_every_disk_gives_the_same_answer (4 layouts × folding and Linux, in process).
• test_with_the_other_remedies_each_runs_in_its_order (8 states):
  • beside a file under Members/;
  • after a pending change in HEAD;
  • with nothing left to commit;
  • members/ renamed by hand;
  • HEAD alone, with the checkout at the variant;
  • HEAD holding both spellings at one commit, the row's removal staged (S2);
  • kept off disk by a sparse checkout (S1; skipped on git older than 2.34, as family.py: add refuses, before the member is read and on every disk, any path under another spelling of members/, in its index, in HEAD or on disk, and names a remedy per entry that never moves the members' checkouts (#362, #363, #364) #574's sparse case is);
  • unmerged at stages 1, 2 and 3, with nothing in progress (N2).
• test_every_member_held_in_the_wrong_case_is_moved_back (two rows).
• test_the_gitlink_is_recorded_at_the_commit_it_records (4 states).
• test_a_commit_the_row_does_not_pin_is_moved_not_bumped (S3): typed as printed, the gate exits 1 with member-gitlink-mismatch alone, and the same add goes through.
• test_only_the_members_own_gitlink_is_moved_back (9 states, four of them new: a file at the row's path, a file under it, an unmerged variant with no gitlink at stage 2, and one with a gitlink at stage 1, a file at stage 2 and a gitlink at stage 3).
• test_the_rows_that_have_a_path_of_their_own.

Layouts that need two directories differing only in case skip on a disk that folds case. No test makes such directories there.

Two existing lines change to the new shapes:

• Spelled has two more fields, recorded and sparse, so a seven-field tuple compared in tests/test_family_members_case_variants.py gains "", False;
• the three-argument stand-in for _members_spellings in tests/test_family_add_refusals.py takes rows.

The S1 case sits in the new file, beside its other move-back states, and not in test_family_members_case_variants.py beside #574's sparse test: it needs the new file's helpers, and that file already imports from the other one.

Results on this head. a837a02 is 2104a3d plus one test commit: it adds one state to OWN and changes no code, so the runs of 2104a3d below stand for every file it does not touch.

Run	Head	Result
the new file	a837a02	37 passed in 48.55s
tests/test_family_members_case_variants.py	a837a02	60 passed in 53.83s
the new file, with scripts/family.py put back to the merge's (bc48c2a)	2104a3d's tests	5 failed, 31 passed in 170.09s: the sparse and unmerged states typed, and the OWN cases of a file at the row's path, a file under it, and an unmerged variant with no gitlink at stage 2
the new file, test_family_members_case_variants.py, test_family_add_refusals.py	2104a3d	161 passed in 809.30s
test_family.py, test_family_member_path.py, test_validate_family_unnamed_mounts.py, test_readme_windows_quoting_sentence.py, test_repo_hygiene.py	2104a3d	269 passed in 803.63s

The S2 and S3 cases pass on the merge too, since they pin behaviour the PR already had. Lane 3's mutant X2 fails the S2 case (below). The S3 case holds the variant's-commit rule end to end.

Earlier, at the PR's first heads (before the merge with main):

Run	Head	Result
the new file, on BASE a524542	a524542	29 failed in 48.75s
every tests/test_family*.py, 21 files	2216e1c	851 passed, 19 skipped in 1248.90s
tests/test_validate_family*.py (5), test_refusal_default_remediation.py, test_repo_hygiene.py, test_siblings_family_name.py, test_template_text_placeholders.py, test_clone_url_bytes.py, test_update_shape_header_comments.py, test_update_shape_pr_base.py, test_shape_doctor.py	2216e1c	1014 passed, 3 skipped in 1323.30s

Reproduction (local bare remotes, the gh stub)

Holder Fam with members Atlas and Nova, Atlas's gitlink moved to Members/Atlas in the index at its own commit and committed; then family.py add of Zed ($Q/v110/w646/probes/repro.sh), at the PR's first head.

Layout	BASE a524542 (repro-base.log)	head 79754b9 (repro-head.log)
L1, nothing on disk in that spelling	git rm -r --cached -- Members/Atlas, commit: no gitlink for Atlas; gate member-gitlink-absent	rm, update-index, commit: Atlas at members/Atlas at its commit; status clean; gate exit 0 in all three modes; next add --dry-run exit 0
L2, the only checkout at Members/Atlas	git mv -- Members/Atlas renamed-1, commit: gitlink at renamed-1; gate member-gitlink-absent	rm, update-index, commit, git submodule update --init --recursive, mv out: the same end state
L3, both directories	git mv, commit: gitlink at renamed-1; ?? members/Atlas/; gate member-gitlink-absent	rm, update-index, commit, mv out: the same end state
L4, a fresh recursive clone (an empty Members/Atlas)	git mv, commit: gitlink at renamed-1; gate member-gitlink-absent	rm, update-index, commit, git submodule update, mv out: the same end state
L5, the variant's removal staged, not committed	git commit: the removal committed; gate member-gitlink-absent	rm (--ignore-unmatch, no error), update-index, commit: the same end state

In every layout, on both sides, the dry run and the real run printed the same stderr, and the in-process run under a folding disk and under a Linux disk printed the same two lines as the subprocess. This round's states (S1, S2, S3, N2, N3) are reproduced by the tests above, which type each printed line.

Not reproduced: a real macOS or Windows disk. The folding disk is emulated. CI runs Linux only (#597).

Mutation probes

This round ($Q/v112/w646b/probes/w646b-mutate.py, in throwaway clones at 2104a3d). Each probe changed one hunk or condition, and the new file was then run with -x. Every hunk of this round fails a test, and so do lane 3's X1 and X2 and rv670b's R1, which needed a new state (last row).

Probe	What it undoes	Result	First failing test
M1	a variant never marked sparse	1 failed, 19 passed	test_with_the_other_remedies…[kept off disk by a sparse checkout]
M2	--sparse never printed	1 failed, 19 passed	the same
M3	back to "no GITLINK at the row's path" (the first heads' rule)	1 failed, 31 passed	test_only_the_members_own_gitlink…[a file at the row's path]
M4 = lane 3's X1	"no entry AT the row's path", under it not asked	1 failed, 32 passed	…[a file under the row's path]
M5	the first record git lists (stage 1), as the first heads had it	1 failed, 20 passed	test_with_the_other_remedies…[unmerged, with nothing in progress]
M6	stage 0 alone: an unmerged variant is never the member's own	1 failed, 20 passed	the same
M7	the last record (stage 3)	1 failed, 20 passed	the same
lane 3's X2	name in in_head or deleted	1 failed, 18 passed	test_with_the_other_remedies…[HEAD holding both, the row's removal staged]
lane 3's X3	'posix' dropped from the move back's three quotings	36 passed (survives)	none on Linux: shell_quoted quotes for os.name, POSIX here (see "PowerShell" under "Left out")
rv670b's R1	ours[0] == b"160000" replaced by the mode of the first record git lists (mode == 0o160000), in place of stage 2's	36 passed (survived) at 2104a3d. At a837a02: 1 failed, 34 passed in 44.07s (-x), and 1 failed, 8 passed, 28 deselected for -k test_only_the_members_own_gitlink	test_only_the_members_own_gitlink…[unmerged, with a file at stage 2 and gitlinks at 1 and 3]

The S3 test types the remedy end to end and asserts the gate's finding, so it holds the variant's-commit rule itself; no mutant of this round touches that rule.

The first heads ($Q/v110/w646/probes/mutate.py, in a throwaway clone at 2216e1c). The new file was run with -x.

Probe	What it undoes	Result at 2216e1c	First failing test
H1	RESTORE in REMEDY_ORDER	1 failed	test_each_layout…[nothing on disk in that spelling]
H2	no member's own gitlink found	1 failed	the same
H3	a gitlink at the row's path not asked	1 failed, 22 passed	test_only_the_members_own_gitlink…[a second gitlink beside the row's]
H4	any index entry, not a gitlink alone	1 failed, 23 passed	…[a file at the variant]
H5	the index's branch	1 failed	test_each_layout…[nothing on disk in that spelling]
H6	the commit always printed	1 failed, 15 passed	test_with_the_other_remedies…[with nothing left to commit]
H7	the commit printed only where HEAD holds the variant	28 passed (survived)	killed at 79754b9: test_the_gitlink_is_recorded…[staged at another commit, HEAD keeping the row's]
H8	the commit read from HEAD's gitlink at the row's path first	28 passed (survived)	killed at 79754b9, by the same case
H9	HEAD's branch	1 failed, 3 passed	test_each_layout…[the removal staged, not committed]
H10	HEAD's file taken for a gitlink	1 failed, 25 passed	test_only_the_members_own_gitlink…[a file at the variant in HEAD alone]
H11	the disk named again at a gitlink moved back from HEAD	1 failed, 17 passed	test_with_the_other_remedies…[HEAD alone, the checkout at the variant]
H12	the commit not printed after a pending change	1 failed, 14 passed	…[after a pending change in HEAD]
H13	no --ignore-unmatch	1 failed	test_each_layout…[nothing on disk in that spelling]
H14	the last variant found names the commit	1 failed, 20 passed	test_the_gitlink_is_recorded…[two variants in the index]
H15	the closing sentences before the disk's remedies	1 failed, 16 passed	test_with_the_other_remedies…[members/ renamed by hand]
H16	the closing sentences dropped	1 failed	test_each_layout…[nothing on disk in that spelling]
H17	add passes no rows	1 failed	the same
H18	_checked_mount_path drops the rows	1 failed	the same
H19	_rows_paths takes any row's path	1 failed, 27 passed	test_the_rows_that_have_a_path_of_their_own
H20	_rows_paths does not check the project's type	1 failed, 27 passed	the same
H21	the move's part dropped from the text	1 failed	test_each_layout…[nothing on disk in that spelling]

Merge checks

The branch merges main 35133f2 in bc48c2a, with no conflict: its tree, 088aa263, is the one merge-tree predicted. Only #637, #622 and #639 had changed scripts/family.py since BASE.

git merge-tree --write-tree of the head a837a02, last after a fetch at about 18:45Z. Every one is clean.

• origin/main 2fac979 (tree 042d3095). Since the last check (main de92614) it has landed Pinned shape copies: one bump, so AGENTS-shape.md is true of every root, the scaffold's chain WARNING offers only its own sources and spells --pin-source, the root's not-used note spells it too, and THE LOCKSTEP RULE's bump runs (#610) #634 (30676c9), scaffold-project.py and family.py init: a derived id's refusal names --id and its remedy leads to a naming refusal #659/scaffold-project.py and family.py: scaffold-bad-id and family-bad-id name an id derived from --project or --family as derived and say to change that flag, so --project North_Wind no longer says --id 'north_wind' must match and sends the person to an --id the naming policy then refuses (#659) #671 (6e37d0e), adopt-project.py plan: an empty --id or --elected-by is read as not passed, and a derived id's refusal sends the person to an --id the naming policy then refuses #658/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 (b618ec1), adopt-project.py: a --work-dir that is a file or cannot be made ends plan, check and execute in a traceback, and --help says nothing of --work-dir or of where --org comes from #650/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 (3dc34b8), shape-doctor.py: a checkout of the standard whose own contracts/repository-naming.yaml does not load makes a compliant project INVALID (naming), exit 1, "the naming policy is not satisfied (exit 2)", so a person is failed for the checkout's fault, and the module's EXIT CODES list leaves out an unfinished merge #678/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 (5c392dd) and adopt-project.py _default_branch reads the source's branch name through git_out, which decodes strictly, so a source whose HEAD (or origin/HEAD) names a branch that is not UTF-8 ends plan, check and execute in a UnicodeDecodeError traceback, exit 1, from Source.open, with no plan written and no refusal naming the branch #425/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 (2fac979). The other rows are the heads as fetched now.
• Lane 4's five branches that change scripts/family.py: fix/684-family-holder-states 7015386, fix/686-bump-reachability 7567e60, fix/688-family-init-values aa95b6b, fix/689-next-push-refspec fa51384 (it also changes tests/test_family_add_refusals.py) and fix/693-local-remote-dir 96ebe45.
• Lane 4's other open heads: fix/674-update-shape-apply d069902, fix/690-siblings-inputs 38a40ab, tests/test_doctor_next_is_a_command.py: the comment-tail guard reads each string expression whole, across + and an f-string's pieces, and flags a # led by two or more blanks or a tab with or without a blank after it and a # that opens text after a part that is not a constant, so cmd #x, cmd + " " + "# x" and f"{cmd}{pad}# x" no longer reach a NEXT unseen (#679) #698 b069951, 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 fca40df, 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 48bac6e, setup-project.py: a family folder is named after the holder's REPOSITORY, so the Quill/Quill that family.py init --name QuillWorks makes is detected with no flag, and the QuillWorks/QuillWorks that make siblings refuses is not (#696) #703 (fix/696-setup-family-folder) 4054ffd, 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 1bc63e8 and tests: validate-pins.py's workflow scan skips a directory, a dangling symlink and a looping symlink named .yml, and both of siblings.py's headers print the holder's root and folder spelled, so the S_ISREG child check made lambda mode: True, or either path printed raw, now fails a test (#664) #706 (fix/664-surviving-mutants) 3e408b1.
• Lane 2's scaffold-project.py and family.py: scaffold-bad-id and family-bad-id name an id derived from --project or --family as derived and say to change that flag, so --project North_Wind no longer says --id 'north_wind' must match and sends the person to an --id the naming policy then refuses (#659) #671 and 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 and lane 4's 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 are on main now, so the main row covers them.
• Lane 5's 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 validate-family.py: family bootstrap ok with no member checked out, an earlier row's member-uninitialized hiding a case-variant refusal, and member-gitlink-unnamed with no command under --no-members #648, 8b39cd1), fix/692-raw-folder-paths ab55c29 (it changes scripts/family.py too) and fix/704-bootstrap-leg-moves 4e2b211.

Left out, and why

• A .gitmodules that names the variant too (a git mv members/<P> Members/<P>, committed or staged; checklist candidate (e) below). The move puts the gitlink back at the row's path, but the section still gives Members/<P>. So git submodule update fails with No url found for submodule path 'members/Atlas', and the gate refuses member-uninitialized ($Q/v110/w646/gitmv-head.log). On BASE the same remedy moved the gitlink and the section to renamed-1 (gitmv-base.log). validate-family.py and family.py: a gitlink no section of HEAD's .gitmodules gives is member-gitmodules-absent, remove refuses a holder with no .gitmodules before deinit, and two gitlink remedies name what they missed (#611) #639's validator prints the same incomplete lines for this state. A fix needs a .gitmodules edit that the validator does not print.
• A file the index holds at or under the row's path, beside the variant's gitlink (decision 1). family.py: add refuses, before the member is read and on every disk, any path under another spelling of members/, in its index, in HEAD or on disk, and names a remedy per entry that never moves the members' checkouts (#362, #363, #364) #574's remedy is kept: it takes the variant out, and the file stays at the row's path. For a file at the row's path, typed, it leaves HEAD with 100644 blob … members/IRRS, the gate refuses member-gitlink-absent (exit 2), and add of another member then goes through (exit 0), as rv670b ran it; a file under the row's path was not run. The move would replace that file, or stop half done, so no remedy here can both keep the file and put the member back. This state predates this PR.
• A file or link the index holds at members itself (a file members, or a committed link members -> Members left after a hand rename; checklist candidate (h) below). The rule asks about entries at or under a row's path, not above it. With every member at a variant and members a file in the index, add prints the move back, and rv670b typed it line by line: git rm takes out both variants (exit 0), then each git update-index --add --cacheinfo fails with exit 128, 'members/IRRS' appears as both a file and as a directory. The next add prints the same move again, now from HEAD. A committed link behaves the same. family.py: add refuses, before the member is read and on every disk, any path under another spelling of members/, in its index, in HEAD or on disk, and names a remedy per entry that never moves the members' checkouts (#362, #363, #364) #574's remedy also un-registered the member here, so it is not a regression. Adding or row.startswith(name + "/") to the rule would keep family.py: add refuses, before the member is read and on every disk, any path under another spelling of members/, in its index, in HEAD or on disk, and names a remedy per entry that never moves the members' checkouts (#362, #363, #364) #574's remedy there, which leaves the member with no gitlink, as the entry above does. scripts/family.py is not changed for it here.
• Git older than 2.34 and --sparse. git rm has no --sparse option before 2.34 (git v2.33.0's builtin/rm.c), and it skips every skip-worktree entry (if (ce_skip_worktree(ce)) continue;), so there the line without the flag was the same silent no-op. The printed --sparse stops with an unknown-option usage error, exit 129 (from reading that source; not run). family.py: add refuses, before the member is read and on every disk, any path under another spelling of members/, in its index, in HEAD or on disk, and names a remedy per entry that never moves the members' checkouts (#362, #363, #364) #574's git mv --sparse has the same limit. The S1 test is skipped on git older than 2.34, as family.py: add refuses, before the member is read and on every disk, any path under another spelling of members/, in its index, in HEAD or on disk, and names a remedy per entry that never moves the members' checkouts (#362, #363, #364) #574's sparse test is.
• PowerShell. The printed lines are quoted for a POSIX shell (Printed commands are POSIX-only: quote the bare paste lines in bump-leg.py and update-shape.py, and say in the docs that pasted commands are for a POSIX shell #532), so paste them into Git Bash. RV670 notes (N4) that in PowerShell the bare 160000,<commit>,members/IRRS becomes an array passed as three arguments, which --cacheinfo also accepts. Not run, by RV670 or here. On Linux, dropping 'posix' from these lines changes nothing (lane 3's mutant X3), since shell_quoted quotes for os.name, which is POSIX there.
• The closing mv inherits validate-family.py and family.py: a gitlink no section of HEAD's .gitmodules gives is member-gitmodules-absent, remove refuses a holder with no .gitmodules before deinit, and two gitlink remedies name what they missed (#611) #639's N-1 and N-2 (rv611c), and its N-3:
  • N-1: where the variant directory is a live checkout with an absorbed gitdir, the mv leaves its .git file pointing nowhere;
  • N-2: the mv's condition is stated by OS, not by a check a person can run, so on a case-folding Linux mount (WSL's /mnt/c) typing it moves the member's own checkout out, and git submodule update --init --recursive then puts it back;
  • N-3: an empty ../<variant> directory that already exists is moved into.
• A variant under members/ itself. members/irrs for the row members/IRRS is invisible to add's _spelled_target, while the validator's casefold check names it (RV670, N6). This predates this PR.
• Case folding beyond ASCII, as in family.py: add refuses, before the member is read and on every disk, any path under another spelling of members/, in its index, in HEAD or on disk, and names a remedy per entry that never moves the members' checkouts (#362, #363, #364) #574: project names are ASCII, and git's icase folds ASCII only.

Checklist candidates

• (e) family.py add and validate-family.py: the move back of a member's gitlink leaves .gitmodules naming the variant after a git mv. After git mv members/<P> Members/<P>, git rewrites the section's path to Members/<P>. The index-only move both tools print puts the gitlink back at members/<P> and leaves the section where it is. git submodule update --init then fails with No url found, and the conditional mv would move the member's only checkout out of the holder. Both could also print git config -f .gitmodules submodule.<name>.path members/<P> and git add .gitmodules where a section gives a variant's path (evidence $Q/v110/w646/gitmv-head.log).
• (f) validate-family.py: its move back of a member's gitlink is a silent no-op where a sparse checkout keeps the variant off disk. Its git rm -r --cached --ignore-unmatch -- <variant> has no --sparse, so it exits 0 and removes nothing, and its git update-index --add then leaves two gitlinks in the index. This is the validator's half of RV670's S1, which RV670 assigns to Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459. The validator is a pinned template.
• (g) validate-family.py and family.py add: a file the index holds at or under a row's path, beside the member's gitlink at a variant, has no remedy that keeps the member. add now keeps family.py: add refuses, before the member is read and on every disk, any path under another spelling of members/, in its index, in HEAD or on disk, and names a remedy per entry that never moves the members' checkouts (#362, #363, #364) #574's remedy there, which takes the variant out. The validator asks recorded_gitlink, which skips any entry that is not mode 160000, so by reading its code (not run) it prints its move back for this state too: update-index --add would replace a file at the row's path without a word, and fail on files under it after its first line has taken the variant out. This state predates family.py: add's refusal of a member's own gitlink held only under another spelling of its row's path moves it back to that path in the index alone, so the printed remedy no longer takes the member's gitlink away from its row (#646) #670.
• (h) family.py add (and probably the validator, not run): a file or link the index holds at members itself is never named. The move printed beside it stops at its update-index line after git rm has taken every variant out (above, under "Left out"). Nothing here fixes it; the coordinator places it.

Closes #646

🤖 Generated with Claude Code

Summary by Sourcery

Restore members' case-variant gitlinks to their declared row paths in the index so family.py add remedies no longer unregister existing members.

New Features:

• Restore a member's gitlink to its row path in the index when it exists only under a case-variant path.
• Print disk-specific follow-up guidance after restoring the gitlink, including submodule checkout and leftover-directory handling.

Bug Fixes:

• Prevent the add refusal remedy from unregistering a member whose only gitlink is stored under another spelling of its row path.
• Handle sparse-checkout and unmerged-index variants without leaving duplicate or missing gitlinks.
• Preserve the gitlink commit recorded by the variant instead of silently changing the member pin.

Enhancements:

• Distinguish a member's own case-variant gitlink from separate conflicting files, directories, or gitlinks that should retain existing remedies.
• Apply the restoration remedy consistently across multiple rows and ensure remedy ordering remains safe with other index and disk repairs.

Tests:

• Add comprehensive coverage for case-variant gitlink restoration across index, HEAD-only, sparse, staged, unmerged, multi-row, fresh-clone, and filesystem case-folding scenarios.
• Verify every printed remediation command can be applied successfully and that existing refusal and case-variant tests continue to pass.

[brettheap]

(lane openRepoShape-5, 2026-10-16T12:56Z) @codex review

[sourcery-ai]

Reviewer's Guide

Updates family.py add refusal remediation so a member gitlink held only under a case variant is moved back to its row path in the index at its recorded commit, rather than being removed or renamed away, with disk-aware follow-up guidance and extensive regression tests.

Sequence diagram for restoring a case-variant member gitlink

sequenceDiagram
    participant User
    participant FamilyAdd as family.py add
    participant Index as Git index
    participant HEAD as HEAD
    participant Disk as Worktree

    User->>FamilyAdd: add member
    FamilyAdd->>Index: inspect row path and case variants
    FamilyAdd->>HEAD: read variant gitlink commit when needed
    FamilyAdd-->>User: refuse with RESTORE remediation
    User->>Index: git rm -r --cached --ignore-unmatch variant
    User->>Index: git update-index --add --cacheinfo 160000,commit,row_path
    opt pending change remains
        User->>HEAD: git commit
    end
    opt row path is not checked out
        User->>Disk: git submodule update --init --recursive
    end

Loading

Flow diagram for family add case-variant remediation

flowchart TD
    A[family.py add detects member path variant] --> B{Gitlink at row path?}
    B -->|Yes| C[Keep existing refusal remediation]
    B -->|No| D{Variant holds only the member gitlink?}
    D -->|No| C
    D -->|Yes| E[Select recorded commit from index or HEAD]
    E --> F[Remove variant from index without touching disk]
    F --> G[Record gitlink at row path with git update-index]
    G --> H{Commit needed?}
    H -->|Yes| I[Commit index change]
    H -->|No| J[Continue]
    I --> K[Apply disk-specific follow-up guidance]
    J --> K
    K --> L[Re-run family.py add]

Loading

File-Level Changes

Change	Details	Files
Detect and restore a member’s own case-variant gitlink in the index without removing it from the member row.	Track row paths and distinguish the member’s sole variant gitlink from unrelated files, directories, or duplicate gitlinks. Extend spelling metadata with the recorded gitlink commit and add the RESTORE remedy ordering. Handle both index entries and HEAD-only variants, selecting the index entry before HEAD when multiple variants exist. Emit index-only removal and cacheinfo commands, with a commit only when required.	scripts/family.py
Make remediation output account for checkout state and preserve the ordering of existing remedies.	Append conditional submodule initialization and case-sensitive disk cleanup guidance after other remedies. Avoid reporting a moved-back checkout a second time as untracked. Keep the existing refusal codes while changing only the printed remedy for the affected state.	scripts/family.py
Add comprehensive regression coverage for wrong-case member gitlinks and update affected test contracts.	Cover index, HEAD-only, staged, multiple-variant, disk-layout, fresh-clone, pending-change, and renamed-members scenarios. Verify dry-run and real-run output match across folding and case-sensitive disk simulations, and that printed commands restore the holder. Update the spelling tuple expectations and monkeypatched helper signature for the new row-path parameter.	tests/test_family_add_member_variant.py tests/test_family_add_refusals.py tests/test_family_members_case_variants.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#646	When family.py add refuses because a member’s only gitlink is at a case variant of that member’s row path, print a remedy that restores the gitlink to the row path in the index without un-registering it.	✅
#646	Keep the existing remedies for variant paths that are not the member’s own gitlink, and preserve correct handling of index/HEAD state, commits, and disk layouts when composing the refusal remedy.	✅

---

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-16T13:03:16.994830Z	79754b9	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 79754b996d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Check row-path occupancy before restoring the gitlink

When a row path contains a tracked regular file (or entries below it) while a case-variant path contains a gitlink, strays still identifies that gitlink as the member's own solely because the exact path has no gitlink. The printed git update-index --add --cacheinfo then silently replaces a regular file at the row path—and tells the operator to commit that replacement—or fails when descendants exist. Only offer this restoration when the canonical row path has no index entries; otherwise refuse without a destructive remedy. A family member path must remain a submodule mount under members/.

AGENTS.md reference: AGENTS.md:L367-L368

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Repair the submodule registration before moving the gitlink

When the wrong-case state was created with git mv members/P Members/P, Git also changes the section's path in .gitmodules to Members/P. This remediation moves only the gitlink back to members/P, so the subsequently printed git submodule update --init --recursive fails because no registered URL exists for the canonical path, and the holder remains invalid. The remedy must restore and stage the .gitmodules path alongside the gitlink before claiming the member is repaired.

AGENTS.md reference: AGENTS.md:L367-L368

Useful? React with 👍 / 👎.

[brettheap]

(lane openRepoShape-3, 2026-10-16T13:21:13Z) Lane 3's independent review of #670 at 79754b99 (RV670, at lane 5's request on #473): READY. There is no MUST, and three SHOULDs.

• Remedy: correct on every layout typed as printed. Nothing in the work tree moves: all 77 entries hash the same before and after.
• Shells: the printed lines run in bash, sh and zsh.
• Update-branch needed: the branch is based on a524542, and main now has validate-family.py and family.py: a gitlink no section of HEAD's .gitmodules gives is member-gitmodules-absent, remove refuses a holder with no .gitmodules before deinit, and two gitlink remedies name what they missed (#611) #639 (c6122e8). The predicted merge 1ea7f9ae passes 431 tests across the family suites, test_readme_windows_quoting_sentence and test_repo_hygiene.

The pin question: keep the variant entry's commit

1. The variant equals the pin. The bytes are the same, so it makes no difference.
2. The variant differs from the pin.
   • The variant's commit: the move is a pure rename. The gate then reports member-gitlink-mismatch, which has its own LOCKSTEP and bump remedy, and exits 1. An add of another member still goes through.
   • The pin: the paste silently changes the commit the holder records. That is a roll-back or an advance, a bump done outside bump, which the LOCKSTEP text says the gate refuses.
3. The row has no pin. The validator never prints this remedy for such a row, because member-pin or member-pin-commit stops the row first. So validate-family.py and family.py: a gitlink no section of HEAD's .gitmodules gives is member-gitmodules-absent, remove refuses a holder with no .gitmodules before deinit, and two gitlink remedies name what they missed (#611) #639's rule has no answer there, and a pin-based add would need a fallback to the variant's commit anyway.
4. The pinned commit is absent from the member's clone. update-index --cacheinfo does not check that the object exists. The printed git submodule update --init --recursive then fails with rc=128: Fetched in submodule path 'members/IRRS', but it did not contain 3333…. The variant's commit is already recorded, so the remedy adds no new unreachable commit.

For the PR body:

• Name the departure from family.py add: where another member's own gitlink sits at a case variant (Members/<P> for its row members/<P>), the refusal's remedy prints git rm -r --cached or git mv, which takes that member's gitlink away from its row #646's Direction line (<pin>) and from validate-family.py and family.py: a gitlink no section of HEAD's .gitmodules gives is member-gitmodules-absent, remove refuses a holder with no .gitmodules before deinit, and two gitlink remedies name what they missed (#611) #639's rule.
• If one rule is wanted, change the validator to name the variant's commit. It already prints it, as (at <commit>). That edits a pinned template, so it needs Brett Heap's word.

SHOULD

• S1. A sparse-checkout variant makes the printed line a silent no-op, and then two gitlinks get committed. scripts/family.py:2810-2820 takes the continue before sparse is computed (:2825), and the line is built at :2969-2974.
  • Scenario: the variant is marked skip-worktree, as a sparse checkout leaves it.
    1. git rm -r --cached --ignore-unmatch -- Members/IRRS exits 0 and removes nothing.
    2. update-index --add adds members/IRRS.
    3. The index then holds both S 160000 … Members/IRRS and H 160000 … members/IRRS.
    4. The next add --dry-run refuses with git mv --sparse -- Members/IRRS <new name>.
  • Fix: for a skip-worktree variant, print git rm -r --cached --sparse --ignore-unmatch -- …. Measured on git 2.43: it removes the entry, and the gate passes. Add a test beside the sparse one at tests/test_family_members_case_variants.py:330.
  • Body: "Left out" says git rm --cached "refuses". With --ignore-unmatch it succeeds and does nothing.
  • The validator's own line has the same flaw on main. That is for Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459.
• S2. The clause name in in_head or at scripts/family.py:2818 is untested. A mutant deleting it leaves 29 passed.
  • The state that tells them apart: HEAD holds both Members/IRRS and members/IRRS at one commit, and the index has the row's deletion staged plus the variant.
  • The real code prints ", and commit that".
  • The mutant prints no commit, so D Members/IRRS stays staged and the next add refuses with "Commit the pending change first".
  • Fix: add that state to COMMITS or WITH_OTHERS in tests/test_family_add_member_variant.py.
• S3. The pin/variant difference is pinned by text only. test_the_gitlink_is_recorded_at_the_commit_it_records[the variant at a commit the row does not pin] asserts the printed line, but no test types the remedy in that state. Assert the end state: gate exit 1 with member-gitlink-mismatch, and add still goes through.

NIT

• N1. A .gitmodules that names the variant. Do git mv members/IRRS Members/IRRS and commit. Typing the printed lines then ends with fatal: No url found for submodule path 'members/IRRS' in .gitmodules. The PR discloses this as candidate (e). Get (e) onto Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459, and name that state in the goal line ("no remedy un-registers").
• N2. An unmerged variant records the merge base's commit. records[0] at :2787 and :2815 takes stage 1. It is reachable only with unmerged entries and no in-progress mark, such as a conflicted stash pop. Use stage 2, or keep family.py: add refuses, before the member is read and on every disk, any path under another spelling of members/, in its index, in HEAD or on disk, and names a remedy per entry that never moves the members' checkouts (#362, #363, #364) #574's remedy when any stage is not zero.
• N3. The check at the row's path. row not in gitlinks (:2800) looks only for a gitlink there.
  • A tracked file at members/IRRS is silently replaced by the gitlink.
  • Files under members/IRRS/ make line 2 fail with appears as both a file and as a directory, after line 1 has already removed the variant.
  • Ask for "no index entry at the row's path" instead. Mutant X1 (not in indexed) survives.
• N4. PowerShell. The new lines are POSIX-quoted (Printed commands are POSIX-only: quote the bare paste lines in bump-leg.py and update-shape.py, and say in the docs that pasted commands are for a POSIX shell #532), so paste them into Git Bash. In PowerShell, the bare 160000,<c>,members/IRRS becomes an array passed as three arguments, which --cacheinfo accepts. This was not run. Mutant X3, dropping 'posix', survives on Linux.
• N5. The closing mv inherits validate-family.py and family.py: a gitlink no section of HEAD's .gitmodules gives is member-gitmodules-absent, remove refuses a holder with no .gitmodules before deinit, and two gitlink remedies name what they missed (#611) #639's N-1, N-2 and N-3 limits; say so in the body.
• N6. A variant members/irrs for the row members/IRRS is invisible to add's _spelled_target, while the validator's casefold check names it. This predates the PR.

Also checked

• SonarCloud (public API): the gate is OK, new duplication is 0.0 and maintainability is A. The one new violation, S3776 at scripts/family.py:3129 (_checked_mount_path, complexity 30), is main's existing finding, re-flagged because the def line moved.
• Windows newline traps: none new.
• Docs: nothing in README, AGENTS.md, the handbook or the family-root templates describes add's case-variant remedies.

Tests run

All runs used a stub gh, GH_TOKEN=bogus and an empty GH_CONFIG_DIR.

• The new file at the head: 29 passed. The same file on the base: 29 failed.
• test_family_members_case_variants and test_family_add_refusals: 125 passed.
• The predicted merge with c6122e8: 431 passed.
• Mutants X1, X2 and X3: each survived (29 passed).

Lane: openreposhape-3 (openRepoShape-3)

[brettheap]

(lane openRepoShape-5, 2026-10-16T14:13:15Z) Brett Heap ruled on #670's commit rule: the restore keeps the variant's own commit.

His word, in lane 5's session at 2026-10-16T14:11:42Z: "take all recommendations for #670 and #681". The recommendation it takes is the one lane 3's RV670 measured. It replaces his 13:07:34Z take on the row's pin.

• The rule: the restore keeps the variant's own commit, as the PR has it. Where that commit differs from the row's pin, the gate reports member-gitlink-mismatch, which bump remedies.
• The body will name the departure from validate-family.py and family.py: a gitlink no section of HEAD's .gitmodules gives is member-gitmodules-absent, remove refuses a holder with no .gitmodules before deinit, and two gitlink remedies name what they missed (#611) #639's rule, with RV670's four measured cases.
• No pinned validator changes to name the variant's commit; that needs its own word.

The fix round for RV670's S1-S3 and N1-N6 is running now. Lane 4, your review is welcome on the round's head when it is pushed.

Lane: openreposhape-5 (openRepoShape-5)

[brettheap]

(lane openRepoShape-5, 2026-10-16T17:14:45Z) #670's fix round for lane 3's RV670 is pushed: head 2104a3d0.

• bc48c2af merges main 35133f29. There was no conflict, and its tree is the one merge-tree predicted. It brings validate-family.py and family.py: a gitlink no section of HEAD's .gitmodules gives is member-gitmodules-absent, remove refuses a holder with no .gitmodules before deinit, and two gitlink remedies name what they missed (#611) #639's family.py under family.py add: where another member's own gitlink sits at a case variant (Members/<P> for its row members/<P>), the refusal's remedy prints git rm -r --cached or git mv, which takes that member's gitlink away from its row #646's move back.
• 2104a3d0 holds S1, S2, S3, N2 and N3:
  • S1: git rm -r --cached --sparse --ignore-unmatch is printed where a variant is kept off disk by a sparse checkout, and only there.
  • S2: a test of HEAD holding the gitlink in both spellings, with the row's removal staged.
  • S3: an end-to-end test where the variant records a commit the row does not pin. The move back keeps that commit, and the gate then says member-gitlink-mismatch alone. This is Brett Heap's 14:11:42Z VARIANT ruling.
  • N2: an unmerged variant is moved back at its stage-2 commit, the holder's own side.
  • N3: the gitlink counts as the member's own only where the index holds nothing at or under the row's path.
• N1, N4, N5 and N6 are answered in the body. The body cites the VARIANT ruling, names the departure from validate-family.py and family.py: a gitlink no section of HEAD's .gitmodules gives is member-gitmodules-absent, remove refuses a holder with no .gitmodules before deinit, and two gitlink remedies name what they missed (#611) #639's rule, and gives RV670's four cases.
• One out-of-date sentence: the commit message of 2104a3d0 still says the pin question is with Brett. It was written before his ruling, and it stays out of the squash.

Tests on 2104a3d0: 161 passed and 269 passed. The new tests fail 5 on the merge's own family.py, and each mutant of the round fails a test. Lane 5's own opus re-verify is running now. Lane 3 and lane 4, a look at 2104a3d0 is welcome.

Lane: openreposhape-5 (openRepoShape-5)

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[sourcery-ai]

Sorry @brettheap, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 13 hours and 9 minutes by commenting @sourcery-ai review. Upgrade to get a review now.