[brettheap]

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

A holder whose HEAD lost .gitmodules (the commit #407 describes) passed its own gate, and family.py remove in it emptied a member and then failed. This PR makes the gate find that state, makes remove refuse it before it writes anything, and fixes two of the gate's gitlink remedies.

Pinned copy. templates/family-root/scripts/validate-family.py is pinned in every holder (scripts/shape_materialize.py lists it). Each holder will see it as upstream-changed on its next update-shape.py check. No other pinned file changes. No test pins this file's bytes or digest; the tests that copy it into a holder take it from the template, and they all pass (below).

What changed and why

Fix round 2: main after #637

Brett Heap's word (2026-10-16T11:21:49Z) was "Accept; merge #639 after #637". #637 (#607) landed as 95780dd, so this branch now holds one merge commit, 08b6245, of origin/main at 95780dd. It changes no line of #611's own work beyond one sentence, in two places:

• The conflict. 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 appended BRANCH_LEFT to the end of member-gitlink-unnamed's hand-mount remedy, the same sentence 574/3 changes. The merge keeps this PR's "and commit that removal, since ..." clause and ends the prose with family.py and validate-family.py: the git switch -c family/<act>-<member> remedy fails when an earlier act left that branch, and the docs spell the branch word two ways #607's BRANCH_LEFT. It is resolved in templates/family-root/scripts/validate-family.py (the last report.finding of _check_gitlinks_named) and in tests/test_validate_family_unnamed_mounts.py (GITLINK_REMEDY, now ending + BRANCH_LEFT). No other file conflicted.
• 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's guard test_every_remedy_that_names_a_switch_line_ends_with_the_sentence passes on the merge. The three remedies that name _switch_line (member-gitlink-absent, member-duplicate-id and member-gitlink-unnamed) all end with BRANCH_LEFT, and no other remedy this PR adds names it, so none was appended beyond the one resolved above. git diff 6aace429 08b6245b on validate-family.py is 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's own change and nothing else.
• 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 (Pinned shape copies: AGENTS-shape.md's CONTRACTS_DIR sentence is false for every scaffolded root, and the chain WARNING offers remedies the scaffold lacks (one shape bump before the v1.1.0 tag) #610) is not in main yet. _check_member_gitlink is untouched by this merge. Its conflict, and the BRANCH_LEFT its _lockstep remedy needs, are in the merge table and in N-5 below.
• Checks. git merge-tree --write-tree 08b6245b origin/main gives 08b6245's own tree, 6a475a42, and git diff --stat origin/main 08b6245b names only this PR's five files. The tests are in "Results" below.

Fix round 1 (rv611b)

The review of 6f938ed gave 0 blockers, 3 should and 6 nits. Commit 6aace42 answers each one:

• S1. _checked_gitmodules_held now takes the member's gitlink at any stage, not only stage 0. With HEAD's .gitmodules gone and members/IRRS held only at stages 1, 2 and 3, the dry run exited 0 and the real run emptied the mount. Both now refuse member-gitmodules-absent before deinit, with the holder byte for byte as it was. Typed as printed, the remedy then lets remove commit. The docstring and the 571(b) text below use the review's wording.
• S2. One new test for each surviving mutant, each shown to kill it (table below): M1 (a checked-out member still gets its tree check), M2 (HEAD's unreadable file is refused in every mode), M4 (the <url> placeholder) and M5 (remove's remedy names only members whose gitlink is in the index).
• S3. Body only. The 574/2 section now says, in the review's words, how the remedy departs from the letter of Brett Heap's "Refuse on every disk" ruling. The commands are unchanged. It needs Brett's word on that departure.
• N1. The variant move prints git rm -r --cached --ignore-unmatch -- <variants>. Where the variant's removal is staged and not committed, the gate still names it from HEAD, and the plain line failed (pathspec ... did not match). Tested on both disks.
• N2. The variant remedy now says what is left on disk. In a fresh clone, git submodule update --init --recursive then checks the member out at the row's path. On a case-sensitive disk the old Members/<P> directory stays, and family.py add refuses it as family-members-dir-variant, so the remedy gives an mv of it out of the holder, typed as printed. Tested with both directories on disk: every printed line typed, the gate passes, and another member is added.
• N3. The validator's docstring and this body say what a staged, uncommitted .gitmodules does: nothing, until it is committed (571(c) below).
• N4. The module docstring names member-gitmodules-absent and gives EXIT CODES' one exception.
• N5. M8 (one finding per path for a duplicate row) has a test. M3 and M7 are still untested; "Not changed, and why" gives the reason.
• N6. The three inexact claims now read as the review gives them, and the merge table is refreshed against the current heads, 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 included.

The other sections below describe the PR as it now stands. They are line by line against #459's comment 6192725913.

Re-verify (rv611c, on 6aace42): APPROVE WITH NITS

The re-verify graded it 0 blockers, 0 should and 5 nits. S1, S2, N1, N3, N4 and N6 are fixed, and N2 and N5 are answered. S3's paragraph is in the body word for word; the departure itself waits for Brett Heap's word.

• S1, confirmed. A gitlink held at stages 1-3 only is refused before deinit in both runs; the holder and the mount's 15 entries are unchanged.
• The mutants. M1, M2, M4, M5, M8 and M12r are each killed. Three more mutants of this round's new text (the mv target, the macOS and Windows sentence, --ignore-unmatch) are killed too.
• Typing every printed line works in layouts C1, C2, C2s, C3, C4 and C6: the gate passes in all three modes, and add --dry-run of another member exits 0.
• Left as nits, since each case keeps every file and can be recovered:
  • N-1. Where the variant directory is a live submodule checkout with an absorbed gitdir, the printed mv leaves its .git file pointing nowhere. Its files and any unpushed commit stay, the commit in the holder's .git/modules/<variant>, and the gate also prints its own gitmodules-path-unnamed finding for the stale section. Reaching this needs a hand-mounted live checkout, the 574/3 layout.
  • N-2. The mv's condition is stated by OS ("a case-sensitive disk, as Linux's usually is"; "on macOS and Windows ... leave it"), not by a check a person can run. On a case-folding Linux mount (WSL's /mnt/c), typing it moves the member's own checkout out; git submodule update --init --recursive then restores it, and the gate passes.
  • N-3. An empty ../<variant> directory that already exists is nested into. A file or a non-empty directory of that name makes mv refuse, and nothing is lost.
  • N-4. M3 and M7 stay untested, as "Not changed, and why" says.
• N-5, composition, not this PR's. 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 and 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 together fail 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's guard test, on 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's _lockstep line. 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 has landed, so 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 appends BRANCH_LEFT there when it takes main.

571(b): remove in a holder whose HEAD lost .gitmodules

On BASE 396c0ff, with local bare remotes and a gh that exits 97:

remove --dry-run: exit 0
gitmodules   none: git reads no section of .gitmodules in the work tree as giving members/Nova, so none is removed
remove: exit 2
REFUSED a git or gh command failed. THE EXACT COMMAND WAS:
    git --literal-pathspecs add -f -- .gitmodules family.yaml
fatal: pathspec '.gitmodules' did not match any files
The unmount was undone only in part (...); NOT members/Nova checked out again ...
members/Nova holds 0 entries

Now _checked_gitmodules_held refuses this holder, before any git command that writes, and the dry run refuses it in the same words. It asks only where none of the work tree, the index and HEAD holds a .gitmodules, and the index records the member's gitlink at any stage: deinit and git rm run on a merged or an unmerged gitlink alike, and with no .gitmodules anywhere the commit cannot stage one. _checked_gitmodules_as_staged (#407) asks nothing there, since there is no copy to compare.

REFUSED member-gitmodules-absent: the holder has no .gitmodules: neither the work tree, the index nor HEAD holds one, though the index records a gitlink at members/IRRS. `git rm` edits only a .gitmodules the work tree has, and `remove` commits .gitmodules as `git rm` leaves it, so with none to commit it would fail after `git submodule deinit` and `git rm` had emptied members/IRRS. A recursive clone of the holder checks out none of its members, and its validate-family.py finds member-gitmodules-absent for each. No git command that writes was run and nothing was written.
Remediation: write back the section `family.py add` writes for each member the index records, this one included, in a POSIX shell — `git config -f .gitmodules submodule.members/IRRS.path members/IRRS` and `git config -f .gitmodules submodule.members/IRRS.url https://github.com/InkRouter/IRRS.git` and `git config -f .gitmodules submodule.members/IRSS.path members/IRSS` and `git config -f .gitmodules submodule.members/IRSS.url https://github.com/InkRouter/IRSS.git` — then stage it, `git add -f .gitmodules` (`-f`, since an operator's excludes may match it), and commit it on its own first if the command's commit should carry only its own change, and run the same command again.

The remedy names only the members whose gitlink the index records (tested).

571(c): the gate passes a row no section of HEAD's .gitmodules gives (#407's decision 3)

On BASE, in that holder: validate-family.py exit 0 family ok, and --no-members exit 0. In a fresh recursive clone of it: the clone exits 0 with every member empty, bootstrap.py says every member and leg fetched and NOT CHECKED OUT; skipped for each, validate-family.py refuses member-uninitialized (exit 2) and names git submodule update --init --recursive, which exits 0 there and checks nothing out, and --no-members says family ok.

Now the finding is member-gitmodules-absent, one per row, in every mode (--no-members and --pins too), exit 1:

FINDING member-gitmodules-absent: members/IRRS is a gitlink at <commit> that a row of members: names, and HEAD holds no .gitmodules, so a recursive clone of this holder checks out nothing there, and neither does make bootstrap in that clone, whatever checkout this holder has of it. Write its section back by hand, in a POSIX shell, as family.py add writes one, then stage and commit .gitmodules:
    git config -f .gitmodules submodule.members/IRRS.path members/IRRS
    git config -f .gitmodules submodule.members/IRRS.url https://github.com/InkRouter/IRRS.git

Where HEAD's file exists but gives no section the path, it says no section of HEAD's .gitmodules gives that path. A section of the name family.py add gives (members/<P>) that already has a url keeps it: only the path line is printed. Where the row's repository: is not <org>/<Name>, the url line prints <url> (tested).

• It reads HEAD's file, as a recursive clone and CI's checkout do. It lists HEAD's root tree with no pathspec, as _member_gitlinks reads HEAD. A file git cannot read is gitmodules-unreadable, in every mode, with "commit it, then run this again" (tested: HEAD's file broken, the work tree's mended). A HEAD git cannot list (no commit yet) is asked nothing.
• A .gitmodules staged and not committed counts for nothing until it is committed. HEAD's file is what counts, as family.py remove, in a holder whose work-tree .gitmodules has been deleted and the deletion not committed, commits that deletion with the member's removal, so every other member's section leaves HEAD while remove exits 0 and the holder's validate-family.py passes, and once pushed a recursive clone exits 0 with each remaining member's directory empty and its own validate-family.py refusing member-uninitialized #407's decision 3 says. The check reads three sources: the gitlinks from the index first, the rows from the work tree's family.yaml, and the sections from HEAD. So:
  • a family.py add staged and not committed (an add, then git reset --soft HEAD~1) is a finding for its own member;
  • a section taken out and staged, not committed, passes;
  • a .gitmodules put back and staged, not committed, in a holder whose HEAD lost it, is a finding for every member until it is committed.
• Which rows. Each row at members/<project> whose gitlink this repository records (gitlinks, read as recorded_gitlink reads one). A row with another path: is member-path's, and a row with no gitlink is member-gitlink-absent's. A row written twice is one finding (tested).
• A member it names that is not checked out is not refused member-uninitialized. That refusal dropped the finding and named a command that does nothing there. It is what a fresh clone and CI met. The finding still fails the run. A member it names that IS checked out is still asked its tree: a digest edited by hand is member-digest-mismatch beside the finding (tested).
• No misfire. A holder with no members, a work tree whose .gitmodules was deleted and not committed, an edit nobody staged, and a sparse checkout that leaves the file out each pass (tested). A .gitmodules put back by hand but untracked is still a finding until it is committed: HEAD, which a clone reads, still has none (tested).
• Bootstrap, validate and a fresh recursive clone agree on the members. In a fresh clone of the damaged holder, the clone leaves both members empty, bootstrap.py says NOT CHECKED OUT; skipped for each, and the gate names both, members checked or not. With the sections written back as printed and pushed, a fresh clone checks both out and the gate passes in every mode (tested). bootstrap.py's own fetch line still says every member and leg fetched there, because git submodule update exits 0. That is checklist candidate (a) below; this PR does not change bootstrap.py.

574/2: a HEAD gitlink at a case variant (#363's item 3)

On BASE, with HEAD's gitlink at Members/IRRS and the row and section at members/IRRS, the gate refused member-gitlink-absent for members/IRRS, never named Members/, and named family.py add, which cannot help because the row is there. Now:

REFUSED member-gitlink-absent: no gitlink (mode 160000) recorded at 'members/IRRS'. IRRS is named in family.yaml, and this repository records its gitlink only at a case variant of that path, which macOS and Windows hold as one directory with it: Members/IRRS (at <commit>). A recursive clone checks out nothing at members/IRRS.
Remediation: the member is recorded in the wrong case. Move its gitlink to the row's path, at the commit the row pins, in the index alone, which touches no file, with the two lines below, 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 family.py 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. The two lines:
    git rm -r --cached --ignore-unmatch -- Members/IRRS
    git update-index --add --cacheinfo 160000,<pin>,members/IRRS

This keeps Brett Heap's "Refuse on every disk" ruling in naming the entries, giving one answer on every disk and ending in a commit, but not in the letter of its remedy, "a committed git mv": it takes every variant out of the index with git rm -r --cached, as #574 does where nothing is on disk in that spelling, and does so even where a checkout is on disk there, where #574 prints git mv, because git mv to the row's path fails or misplaces the gitlink (below). It needs Brett's word on that departure.

What git mv -- Members/Nova members/Nova did in a probe on Linux (git 2.43, a gitlink at Members/Nova in the index):

• the checkout at members/Nova and nothing at Members/Nova (the holder it happened in): fatal: bad source, source=Members/Nova, destination=members/Nova/Nova, exit 128;
• both directories there: exit 0, and the gitlink lands at members/Nova/Nova;
• only the empty Members/Nova a fresh clone leaves, where no other member makes a members/ directory: fatal: renaming 'Members/Nova' failed: No such file or directory, exit 128 (where one does, the same git mv exits 0).

The index-only pair reads no disk, so it works in all three and on a folding disk. Several variants are taken out on one line, and the gitlink goes back once, at the pinned commit. --ignore-unmatch lets the first line run where the variant's removal is already staged. member-gitlink-unnamed still prints no command for the same gitlink under --no-members, since taking it out alone would un-register the member. The pair here takes it out and records it again together, so the two do not contradict.

What is left on disk. In a fresh clone the gate first refuses member-uninitialized once the move is committed; the git submodule update --init --recursive the remedy names cures that. On a case-sensitive disk the variant's directory stays: empty in a fresh clone, a full checkout where a holder had both. The gate passes, but family.py add of any other member then refused family-members-dir-variant ... on disk and untracked: Members/<P>. The mv moves it out of the holder, to ../<variant with / as ->, which no spelling of members/ meets. On macOS and Windows the variant's directory is the row's own, so the remedy says to leave it. A probe typed every printed line in three layouts on Linux: a fresh recursive clone (the mv, then git submodule update, then the gate passes and add --dry-run of a third member exits 0); both directories on disk (the gate passes and add --dry-run exits 0, where before the mv it refused); and the half-repaired holder (the --ignore-unmatch line exits 0, nothing to move, the gate passes). The same probe on 6f938ed: in the first two layouts add --dry-run of the third member still refused family-members-dir-variant after the move, and in the third the printed git rm -r --cached -- Members/Atlas exited 128 (pathspec 'Members/Atlas' did not match any files).

574/3: commit the git rm before the add

The hand-mount remedy now reads "take it out with the second, which refuses while its checkout holds changes and takes its .gitmodules section out too, and commit that removal, since family.py add refuses a path under another spelling of members/ that HEAD holds and the index no longer does, then mount it with the third", and, since #637, ends with its BRANCH_LEFT sentence. On BASE, typing the three lines for a hand mount at Members/IRQS gave REFUSED member-path-taken: ... in HEAD and no longer in the index: Members/IRQS (a submodule) at the add. With the commit between, add mounts it.

Decisions and evidence

1. remove refuses; it does not commit without .gitmodules. The issue's approved recommendation (Brett Heap, 2026-10-15T16:49:38Z) is to refuse before deinit. The state is damage: the gate now finds every remaining member of such a holder. A remove that committed past it would leave a holder that still fails its gate, so the repair comes first, as family.py remove, in a holder whose work-tree .gitmodules has been deleted and the deletion not committed, commits that deletion with the member's removal, so every other member's section leaves HEAD while remove exits 0 and the holder's validate-family.py passes, and once pushed a recursive clone exits 0 with each remaining member's directory empty and its own validate-family.py refusing member-uninitialized #407 refuses a .gitmodules the work tree lacks. The refusal is narrow. Where HEAD's file lacks only the member's own section, remove runs as before and the gate passes after it (tested). Where the member has no gitlink, the run fails at its first git call as before (tested). Where its gitlink is unmerged, it is refused like a merged one (tested).
2. The repair a person can type is the section family.py add writes, by git config -f .gitmodules, with the url family.py add gives a member (https://github.com/<repository>.git). It is not restored from history, because that would bring back the sections of members removed since. It is not taken from the holder's .git/config registration, which is local and, in a --local-remote-dir holder, a local path (--pin-source in scaffold-project.py and adopt-project.py: accepted without --pin, and committed into digest_source as typed #540 keeps local paths out of committed files). Each test types it as printed and reaches the fixture's local remotes through a url.<base>.insteadOf for the one command.
3. The code member-gitmodules-absent is the gate's finding and remove's refusal, one fact under one name, as gitmodules-unreadable is shared. It is not gitmodules-*: remove's family.py remove, in a holder whose work-tree .gitmodules has been deleted and the deletion not committed, commits that deletion with the member's removal, so every other member's section leaves HEAD while remove exits 0 and the holder's validate-family.py passes, and once pushed a recursive clone exits 0 with each remaining member's directory empty and its own validate-family.py refusing member-uninitialized #407 refusals use that prefix for a work-tree copy that is not the index's.
4. Where the new code is documented. No document names the gate's codes: AGENTS.md (at its 492-line cap), the holder's AGENTS-shape.md, README.md and the holder's README name none of member-gitlink-absent, member-gitlink-unnamed or gitmodules-path-*. tests/test_agents_md_codes.py holds only the codes AGENTS.md names. So the new check is documented where the others are, in the validator's own "WHAT IS CHECKED" docstring, which ships in every holder; it names member-gitmodules-absent there and in EXIT CODES. AGENTS-shape.md is not changed, since that would move a second pinned file. Adding the code to AGENTS.md would need a line under the cap.
5. 574/2's refusal is reached in members mode. In a plain clone followed by git submodule update --init --recursive, as CI and make bootstrap run it, it is reached when the variant's row is the first row not checked out: git submodule update stops at the first gitlink it has no url for, and Members/ sorts before members/. CI then falls back to --no-members, where member-gitlink-unnamed names the variant. After clone --recurse-submodules the refusal is reached whatever the row order. This is checklist candidate (b) below.
6. The mv target is ../ and the variant with each / as - (../Members-IRRS): out of the holder, where no spelling of members/ meets it, with nothing to fill in, and distinct for each variant on the disks where the step applies. It moves rather than deletes, since the directory can be a checkout with work in it.

Tests

tests/test_family_head_lost_gitmodules.py, new, 38 tests:

• 571(b): the refusal by remove and its dry run alike, exit 2, with the holder byte for byte as it was (test_family_dry_run.state), the member's checkout included; the remedy typed as printed, with no excludes and under an operator's * excludes; remove then commits and the gate passes in every mode; the pushed result cloned recursively checks the other member out and its gate passes; a member whose section alone is gone is removed as before; a member with no gitlink is not this refusal; a member whose gitlink is held only at stages 1, 2 and 3 is refused alike, with the mount and the stages kept, and the remedy typed lets remove commit (S1); the remedy names only the members whose gitlink the index records (M5).
• 571(c): one finding per member where HEAD lost the file, in every mode, typed and committed; one finding where one section is gone, in every mode; a section of add's name keeps its url; a fresh clone says the findings and not member-uninitialized, bootstrap.py says NOT CHECKED OUT for each, and after the remedy a fresh clone passes; no misfire on the three work-tree states and on a holder with no members; an untracked copy put back is still a finding until committed; rows the gitlink checks do not read are asked nothing; a checked-out member it names is still asked its tree, members checked and --pins (M1); HEAD's unreadable file is gitmodules-unreadable in every mode, and the mended file committed passes (M2); a repository: that is not <org>/<Name> prints <url> (M4); a row written twice is one finding per path (M8).
• 574/2: one variant and two, on a Linux disk and an emulated folding disk (core.ignorecase=true, index records only), typed as printed and committed, then the gate passes in every mode; a fresh clone says it too; the variant's removal staged and not committed, on both disks, typed as printed and committed (N1); on a case-sensitive disk, a second checkout at Members/IRRS, every printed line typed (the two lines, the commit, the mv), then the gate passes in every mode and family.py add of IRQS exits 0 (N2; skipped on a case-insensitive disk, where the two directories cannot both exist).
• 574/3: a hand mount at Members/IRQS (index records, no Members/ on disk), on both disks: the uncommitted git rm makes add refuse; the commit the text names makes it mount.

Changed tests:

• tests/test_validate_family_unnamed_mounts.py: the pinned hand-mount remedy text; the hand mount run as printed now commits the git rm; in members mode the case-variant state's refusal prints the index move, now with --ignore-unmatch (the --no-members finding still prints no command); the section-path-in-another-case state now also has member-gitmodules-absent with its one path line.
• tests/test_family_remove_gitmodules.py: the docstring of the HEAD-lost test, which said the real run "still fails" and the case goes to Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459.

Results, Linux, /usr/bin/python3 -m pytest, gh stub first on PATH:

• Fix round 2, on the merge 08b6245 (every run through run9.sh, committed, clean tree):
  • 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's guard and the unnamed-mounts file, on the merge as resolved and before it was committed: tests/test_family_switch_branch_exists.py tests/test_validate_family_unnamed_mounts.py: 65 passed in 63.49s (0:01:03);
  • batch A: tests/test_family_head_lost_gitmodules.py tests/test_validate_family_unnamed_mounts.py tests/test_family_switch_branch_exists.py tests/test_validate_family_branch_step.py tests/test_family_remove_gitmodules.py: 152 passed in 204.98s (0:03:24) (38 in the new file and 114 in the other four);
  • batch B: tests/test_validate_family*.py tests/test_family_members_case_variants.py tests/test_repo_hygiene.py (the five test_validate_family* files are branch_step, duplicates, member_path_glob, unnamed_mounts and without_git): 246 passed in 165.92s (0:02:45);
  • no skips in either run. Batch A of round 1 (704 tests, 18 files) and batch B of round 1 (194 tests) were not re-run: 08b6245's five files differ from 6aace42's only by what main changed in them, 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's BRANCH_LEFT lines included.
• Fix round 1, on 6aace42:
  • the new file and tests/test_validate_family_unnamed_mounts.py: 78 passed in 44.40s;
  • the same two files on 6f938ed (a throwaway clone with them copied in): 11 failed, 67 passed in 42.52s. The S1 test fails with work tree changed (the mount emptied). The N1 and N2 tests fail at the refusal's text, which lacks --ignore-unmatch and the mv; the probe below shows what that text did when typed. The other seven pin the refusal text this round changes: the four case-variant moves, the fresh clone of one, and the unnamed-mounts test's two members-mode cases. The five S2 and N5 tests pass there, as they must: they pin behaviour 6f938ed already has, and the mutants below are their proof;
  • batch A (the list below): 704 passed in 368.87s (0:06:08), no skips;
  • from batch B, tests/test_repo_hygiene.py tests/test_agents_md_codes.py tests/test_cli_reference.py tests/test_family_members_case_variants.py: 194 passed in 42.58s.
• Round 0:
  • the new file on BASE 396c0ff (a throwaway clone with the file copied in): 19 failed, 7 passed in 21.36s. The 7 that pass pin behaviour this PR keeps: the three work-tree states and the holder with no members (no misfire), the member whose section alone is gone, the member with no gitlink, and the rows the gitlink checks do not read;
  • the new file on 6f938ed: 26 passed in 33.48s;
  • targeted batch A on c2f2884: tests/test_family_head_lost_gitmodules.py tests/test_family_remove_gitmodules.py tests/test_validate_family_branch_step.py tests/test_validate_family_duplicates.py tests/test_validate_family_member_path_glob.py tests/test_validate_family_unnamed_mounts.py tests/test_validate_family_without_git.py tests/test_family_members_case_variants.py tests/test_family_add_refusals.py tests/test_refusal_default_remediation.py tests/test_family_dry_run.py tests/test_family_member_path.py tests/test_family_bump_remove_rollback.py tests/test_family_tracking_branch.py tests/test_family_printed_quoting.py tests/test_family_add_excludes.py tests/test_family_add_member_id.py tests/test_family.py: 690 passed in 585.40s (0:09:45);
  • targeted batch B on c2f2884, every other test file that runs the holder's validator, family.py or the codes: tests/test_repo_hygiene.py tests/test_agents_md_codes.py tests/test_shape_doctor.py tests/test_doctor_gitlink_repairs.py tests/test_doctor_legs_members_next.py tests/test_doctor_next_is_a_command.py tests/test_doctor_validator_rows.py tests/test_family_bump_to_a_tag.py tests/test_family_bump_to_checks.py tests/test_family_init_values.py tests/test_family_makefile_siblings.py tests/test_family_member_name.py tests/test_shape_pin_files_not_a_list.py tests/test_stdout_encoding.py tests/test_template_text_placeholders.py tests/test_template_values_single_pass.py tests/test_update_shape.py tests/test_update_shape_add.py tests/test_update_shape_header_comments.py tests/test_update_shape_kept_helper.py tests/test_update_shape_pr_base.py tests/test_cli_reference.py tests/test_validate_pins_without_git.py tests/test_bump_leg_dry_run_truth.py tests/test_bump_leg_unopenable.py tests/test_bump_leg_unreadable.py: 1746 passed, 23 skipped in 1448.78s (0:24:08). The skips are the Windows-only PowerShell and stdout lines and test_family_init_values.py's template-quoting cases, as on main;
  • on the merge of 6f938ed with origin/main 8f453d0, committed and detached in a throwaway shared clone: batch A plus tests/test_family_bump_to_checks.py and tests/test_family_bump_to_local_only.py: 706 passed in 732.59s (0:12:12); batch B without test_family_bump_to_checks.py: 1740 passed, 23 skipped in 1383.61s (0:23:03).

Mutation probes

Fix round 1

Each mutant applied alone to a throwaway shared clone at 6aace42, with the new file run against it. M1, M2, M4, M5 and M8 are the review's own text replacements. M12r puts back the stage-0 test that S1 takes out; N1r drops --ignore-unmatch.

mutant	result	new tests that fail
M1 the tree check skipped even for a checked-out member	2 failed, 36 passed	test_a_checked_out_member_it_names_still_has_its_tree_checked[members-checked], [pins]
M2 HEAD's gitmodules-unreadable swallowed	3 failed, 35 passed	test_a_head_gitmodules_git_cannot_read_is_refused (all three modes)
M4 the <url> placeholder never printed	1 failed, 37 passed	test_a_repository_not_org_and_name_prints_the_url_placeholder
M5 remove's remedy not filtered to members with a gitlink in the index	1 failed, 37 passed	test_removes_remedy_names_only_members_whose_gitlink_is_indexed
M8 no dedupe, one finding per row	1 failed, 37 passed	test_a_row_written_twice_is_one_finding_per_path
M12r the stage-0 test put back	1 failed, 37 passed	test_remove_refuses_it_where_the_members_gitlink_is_unmerged
N1r --ignore-unmatch dropped	8 failed, 30 passed	every test that pins the variant refusal: the four moves, the half-repaired move on both disks, the case-sensitive disk's mv, the fresh clone

M11 (the variant sort) was already killed at 6f938ed (2 failed in the review's run).

Round 0

Each hunk (or one condition in it) reverted alone in a throwaway clone at 6f938ed, with the new file run against it (mutate.py, exact text replacements). Every one fails at least one new test:

probe	result	new tests that fail
F1 remove does not call _checked_gitmodules_held	3 failed, 23 passed	test_remove_refuses_a_holder_whose_head_lost_gitmodules[no-excludes], [star], test_the_holder_remove_leaves_clones_with_the_other_member
F2 the refusal asked whatever the member's gitlink	1 failed, 25 passed	test_remove_of_a_member_with_no_gitlink_is_not_this_refusal
V1 member-gitmodules-absent never made	9 failed, 17 passed	the per-member finding (3 modes), the one-section finding (3 modes), the kept url, the fresh clone, the untracked copy
V2 the work tree's .gitmodules read in place of HEAD's	3 failed, 23 passed	no misfire [deleted, not committed], [left out by a sparse checkout], the untracked copy
V3 no skip of an unregistered member that is not checked out	1 failed, 25 passed	test_a_fresh_clone_of_it_says_the_finding_and_not_uninitialized
V4 the url line always printed	1 failed, 25 passed	test_a_section_of_the_name_add_gives_keeps_its_url
V5 "HEAD holds no .gitmodules" never said	4 failed, 22 passed	the per-member finding (3 modes), the fresh clone
V6 a row with a hand-edited path: asked too	1 failed, 25 passed	test_a_row_the_gitlink_checks_do_not_read_is_asked_nothing
V7 a row with no gitlink asked too	1 failed, 25 passed	test_a_row_the_gitlink_checks_do_not_read_is_asked_nothing
V8 574/2's variant not named	5 failed, 21 passed	the case-variant move (one and two variants, both disks), the fresh clone of it
V9 574/3's commit not said	2 failed, 24 passed	the hand mount under Members/ (both disks)

The other hunks are docstrings, comments and _sections_listed, a split of _gitmodules_sections that changes no behaviour (the #300 and #361 tests in batch A pass through it), and the conditions S2 and N5 list, which no new test holds. (That was true of 6f938ed. Fix round 1 adds a test for each of them but M3 and M7; see "Not changed, and why".)

Merge checks (git merge-tree --write-tree)

Of this head (08b6245, the merge of origin/main 95780dd), run 2026-10-16 about 12:00Z against the PR heads git ls-remote gave:

Merged with	Head	Result
origin/main	95780dd	clean: the merge tree is this head's own tree, 6a475a42. This branch now holds the merge of main, which git diff --stat origin/main 08b6245b shows as these five files only.
#622 (lane 2, #609)	227bc3b	clean
#626 (lane 4, #612)	landed (6f760b7, in main)	not applicable
#630 (lane 3, README, the handbook, tests.yml)	ca5c49f	clean
#621 (lane 2)	10dda17	clean
#627	83ca2db	clean
#634 (lane 2, #610)	b7472df	CONFLICT in templates/family-root/scripts/validate-family.py, two regions, as before: _check_member_gitlink's signature and its one call in _check_member. This PR adds gitlinks, #634 adds rule; keep both: gitlinks: dict[str, str], report: Report, rule: str, called as _check_member_gitlink(root, path, commit, project, gitlinks, report, rule). Lane 2's issuecomment-6206200388 says the same. #634 is not on main yet, and its _lockstep remedy must end with {BRANCH_LEFT} under #637's guard.
#637 (lane 5, #607)	landed as 95780dd	merged into this branch (Fix round 2): the one sentence, GITLINK_REMEDY, kept both.

#607 and #611 landed one at a time: #607 first, so this PR took #607's sentence.

Not changed, and why

• bootstrap.py (pinned): its fetch line over members git submodule update did not check out. Candidate (a) below.
• add in a holder whose HEAD lost .gitmodules: it commits a new .gitmodules with its own section alone, which is its own change. The gate then names each other member.
• M3 and M7 stay untested. M3 turns the unborn-HEAD return into "no file": no holder is unborn, since family.py init commits, so the gate never meets one. M7 drops the blob-type guard on HEAD's .gitmodules: it matters only where HEAD holds a .gitmodules that is a directory, which only a hand-built tree can make. A test of either would build a holder no tool makes. M9 and M10 (in _checked_gitmodules_held) are equivalent mutants: _checked_gitmodules_as_staged runs first and, for remove, refuses every state in which either return would fire.
• macOS and Windows were not run (CI runs the full suite on Linux only since ci: run the test suite on Linux only #597). The case-variant tests use index records and core.ignorecase=true, every file is written as bytes, git's stdin gets bytes, and nothing is compared against a file written with write_text. The one test that needs both Members/IRRS and members/IRRS on disk skips on a case-insensitive disk.

Checklist candidates

• (a) bootstrap.py says family bootstrap ok over members it did not check out. In a fresh clone of a holder whose HEAD lost .gitmodules, git submodule update --init --recursive exits 0 and checks nothing out, so step (a) says every member and leg fetched, step (b) says NOT CHECKED OUT; skipped. See the fetch above. for each, and the run ends family bootstrap ok, exit 0. It does the same in a plain clone with a case-variant gitlink, after printing fatal: No url found for submodule path 'Members/Nova'. The gate now names the cause; the fetch line should not claim the opposite.
• (b) A clone's gate meets member-uninitialized before a later row's member-gitlink-absent. In a plain clone of family.py add, under core.ignorecase=true, commits the member's gitlink as Members/<P> when HEAD holds a path under a case variant of members/ that the index no longer does (a git rm -r Members not yet committed), so .gitmodules and family.yaml say members/<P>, the holder's own validator passes in the working clone, and every fresh clone of the pushed holder leaves the member's directory empty and is refused member-gitlink-absent #363's state followed by git submodule update --init --recursive (exit 128), where the variant's row is not first, git submodule update dies at Members/<P> (No url found for submodule path), so the first row is not checked out and the gate refuses member-uninitialized for it, naming the same failing command. After clone --recurse-submodules this does not happen. Asking every row's gitlink before any row's checkout would name the variant first.
• (c) member-gitlink-unnamed for the only record of a member in the wrong case prints no command under --no-members, which is the path CI takes in (b), while members mode now prints the index move. The same pair could be printed there.
• (d) family.py add of another member can un-register a member whose only gitlink is at Members/<P> (against landed 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). It prints git rm -r --cached -- Members/<P> (nothing on disk in that spelling) or git mv -- Members/<P> <new name> (something on disk there). Either one un-registers that member.

Closes #611

🤖 Generated with Claude Code

Summary by Sourcery

Harden family validation and removal workflows against missing .gitmodules registrations and incorrectly cased gitlinks.

New Features:

• Detect gitlinks whose corresponding .gitmodules sections are absent from HEAD and provide actionable repairs.
• Handle case-variant gitlink paths with index-based remediation and document required on-disk cleanup.

Bug Fixes:

• Prevent family.py remove from modifying a holder when .gitmodules is absent from the work tree, index, and HEAD.
• Avoid incorrectly reporting unregistered members as uninitialized when their gitlinks lack HEAD registrations.
• Ensure hand-mounted member removals are committed before subsequent family.py add operations.

Enhancements:

• Clarify validator diagnostics, exit behavior, and remediation guidance for missing registrations and case-variant gitlinks.

Documentation:

• Update validator and test guidance to describe missing .gitmodules registrations and required repair steps.

Tests:

• Add comprehensive coverage for lost .gitmodules, missing sections, unmerged gitlinks, case variants, staged repairs, fresh clones, and remediation commands.

[brettheap]

(lane openRepoShape-5, 2026-10-15T23:50Z) @codex review

[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	⚠️ Failed 2026-10-15T23:51:08.382826Z	6f938ed	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]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[sourcery-ai]

Reviewer's Guide

The PR hardens family validation and removal around broken .gitmodules and gitlink states: it detects clone-visible registration gaps from HEAD, refuses unsafe removals before writes, and replaces ambiguous case-variant and hand-mount remedies with actionable index and commit steps, backed by extensive regression tests.

Sequence diagram for safe family removal with missing gitmodules

sequenceDiagram
    participant Operator
    participant FamilyRemove as family.py remove
    participant Validator as _checked_gitmodules_held
    participant Git as Git index and HEAD

    Operator->>FamilyRemove: remove or remove --dry-run
    FamilyRemove->>Validator: _checked_gitmodules_held(family, path)
    Validator->>Git: inspect work tree, index, HEAD, and gitlink
    alt .gitmodules absent everywhere and gitlink recorded
        Validator-->>FamilyRemove: Refusal member-gitmodules-absent
        FamilyRemove-->>Operator: no writing commands run
    else .gitmodules exists or member gitlink absent
        Validator-->>FamilyRemove: allow subsequent checks
        FamilyRemove->>Git: deinit and remove member
        FamilyRemove->>Git: stage and commit .gitmodules
    end

Loading

Sequence diagram for committing a hand-mount removal before re-adding

sequenceDiagram
    participant Operator
    participant Family as family.py
    participant Git

    Operator->>Family: family.py add --member Project
    Family->>Git: inspect HEAD and index paths
    Git-->>Family: path under another members/ spelling remains in HEAD
    Family-->>Operator: Refusal member-path-taken
    Operator->>Git: git rm -- Members/Project
    Operator->>Git: commit removal
    Operator->>Family: family.py add --member Project
    Family->>Git: record row and gitlink
    Git-->>Operator: mount can be committed

Loading

Flow diagram for detecting clone-visible gitmodules registration gaps

flowchart TD
    A[Read family.yaml rows and HEAD gitlinks] --> B[Read HEAD .gitmodules]
    B --> C{Does each valid member path have a section?}
    C -->|Yes| D[Continue member validation]
    C -->|No| E[Report member-gitmodules-absent]
    E --> F[Print git config section remediation]
    E --> G{Member checkout exists?}
    G -->|No| H[Skip member-uninitialized check]
    G -->|Yes| D

Loading

Flow diagram for repairing a case-variant gitlink

flowchart TD
    A[Row expects members/Project] --> B[No gitlink at expected path]
    B --> C{Gitlink exists at case variant?}
    C -->|No| D[Report member-gitlink-absent]
    C -->|Yes| E[Report member-gitlink-absent with variant]
    E --> F[git rm -r --cached -- Variant]
    F --> G[git update-index --add --cacheinfo 160000,pin,members/Project]
    G --> H[Commit index-only correction]

Loading

File-Level Changes

Change	Details	Files
Prevent remove from partially unmounting members when .gitmodules is absent everywhere.	Add a pre-write refusal covering the work tree, index, and HEAD absence cases. Require the target member's gitlink to be recorded before issuing the refusal. Provide remediation that reconstructs all recorded members' sections, stages with git add -f, and reruns removal. Apply identical behavior to dry runs and preserve existing behavior for missing gitlinks or merely missing sections.	scripts/family.py tests/test_family_remove_gitmodules.py tests/test_family_head_lost_gitmodules.py
Detect gitlinks that cannot be cloned because HEAD's .gitmodules does not register their paths.	Read .gitmodules from HEAD's root tree rather than the work tree, including unreadable and no-HEAD cases. Report member-gitmodules-absent for each canonical member gitlink lacking a matching HEAD section, including --no-members and --pins modes. Skip subsequent uninitialized checkout checks for affected members so the actionable finding is retained. Print POSIX-shell repairs using the canonical path and the repository-derived URL, while preserving existing URLs.	templates/family-root/scripts/validate-family.py tests/test_family_head_lost_gitmodules.py tests/test_validate_family_unnamed_mounts.py
Make case-variant gitlink and hand-mount remedies safe across case-folding filesystems.	Name all case-variant gitlink entries and repair them with index-only git rm --cached plus git update-index --cacheinfo. Update hand-mount guidance to commit the removal before invoking family.py add. Expand coverage for Linux and case-folding index behavior, fresh clones, printed-command execution, and resulting gate passes.	templates/family-root/scripts/validate-family.py tests/test_family_head_lost_gitmodules.py tests/test_validate_family_unnamed_mounts.py
Add comprehensive regression coverage for damaged holders, clone behavior, remediation text, and non-regression states.	Add 26 tests covering HEAD loss, missing sections, untracked/work-tree-only changes, empty families, missing gitlinks, case variants, and hand mounts. Verify byte-preserving refusals, recursive clone/bootstrap outcomes, all validator modes, excludes, and offline remotes. Update existing expectations and documentation strings for the new refusal and remedy ordering.	tests/test_family_head_lost_gitmodules.py tests/test_family_remove_gitmodules.py tests/test_validate_family_unnamed_mounts.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#611	Have validate-family.py report member gitlinks that no section of HEAD's .gitmodules gives, including when HEAD has no .gitmodules, across validation modes and without treating uncommitted or sparse-checkout work-tree changes as HEAD state.	✅
#611	Make family.py remove refuse a holder with no .gitmodules anywhere when the index records the member gitlink, before any write or deinitialization, including during a dry run.	✅
#611	Improve the gitlink remedies: identify and give an index-based correction for a gitlink recorded at a case variant of the row path, and tell users to commit a hand-mount removal before running add.	✅

Possibly linked issues

• Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459: The PR fixes the missing-.gitmodules remove failure and validator gap, and addresses both listed gitlink-remedy issues.

---

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-2, 2026-10-16T01:50:05Z) An overlap note for lane 5, from lane 2. Nothing is asked of this PR.

This PR and lane 2's #634 (fix/610-pinned-text, head 030fde0) conflict in one place: templates/family-root/scripts/validate-family.py. Each adds one parameter to _check_member_gitlink.

• This PR adds gitlinks: dict[str, str] before report.
• 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 adds rule: str after report.

The conflict is at the function's signature and at its one call. The fix is to keep both parameters:

def _check_member_gitlink(root, path, commit, project,
                          gitlinks: dict[str, str], report: Report, rule: str) -> None:
...
        _check_member_gitlink(root, path, commit, project, gitlinks, report, rule)

git merge-tree finds nothing else that overlaps between the two PRs. #634 has no merge word yet, so this PR will likely land first. #634 will then make the resolution above in its next refresh.

[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