[brettheap]

What changed

A follow-up outside v1.2.0 (Brett Heap, 2026-10-21T10:32:04Z). It lands only after the v1.2.0 tag, on a later merge word.

The state #1093 asks for. A leg's index tracks .gitmodules, but this disk lacks it (deleted, the deletion not staged). git's config_from_gitmodules then reads the index's copy, and git submodule status exits 128 for a gitlink that copy does not register. At main the doctor named nothing there, because it read only the file on this disk.

The index's copy is read (shape-doctor.py):

• unregistered_gitlinks has a third branch. Where the index tracks .gitmodules and lstat finds none on this disk, registered_in_the_index reads :.gitmodules as gitmodules_entry does: gitmodules_listing(mount, ["--blob", ":.gitmodules"], partial=True), then submodule_keys(..., working_tree=False), so up to its first bad line.
• HEAD's copy (shape-doctor.py: a leg's gitlink that no .gitmodules section registers, beside a .gitmodules whose sections name other paths or beside none, is named by no row, though a recursive clone of the leg leaves it empty #1080) and the index's copy are read by one helper, registered_in_blob. registered_unindexed calls it and behaves as before: RV1092d's probe_d.py rows are identical at main and at this head.
• Each gitlink that copy does not register is named, whether the copy holds no section (adopt-project.py and shape-doctor.py: a .gitmodules of whitespace is asked on every run, a dropped file whose blob the root also holds counts as root, _answered_legs is quadratic, and two validator code families have no placeholder row #914's state) or sections for other paths (shape-doctor.py: a leg's gitlink that no .gitmodules section registers, beside a .gitmodules whose sections name other paths or beside none, is named by no row, though a recursive clone of the leg leaves it empty #1080's state). A copy that registers it names nothing.

Its own value and clause.

• The leg's entry says unregistered_beside: index_copy (BESIDE_INDEX_COPY), documented beside the other leg keys and in the module docstring's leg-key prose.
• index_copy_clause prints the way out: "first restore that .gitmodules in its leg (git restore .gitmodules), then give each a section with its path and url in it, or, once it is staged (git add .gitmodules), remove its gitlink with git rm --cached <its path in the leg> in its leg".
• Why the restore comes first: where the file is gone, git add .gitmodules stages its deletion (measured: exit 0, and the index then tracks none), so every other submodule's section leaves the index with it. And no section can be written in a file that is not there.
• Typed as printed in real legs (git 2.43), with the index's copy holding another path's section or none, in a leg with a commit and in one without:
  • git restore .gitmodules, git add .gitmodules, git rm --cached vendor/lib: each exits 0, the gitlink leaves the index, and the index's copy is unchanged;
  • git restore .gitmodules, a section appended, git add .gitmodules: each exits 0, then git submodule status exits 0.
  • The tests type both ways out the same way.
• A recursive clone of a commit made in this state exits 0 and leaves vendor/lib empty, and git submodule status in the clone exits 128, as the clause says.

Note or finding: a note. Like #914's and #1080's clauses, it is said in the row and never a finding. The row stays the note it was, since the policy still asks about the tracked .gitmodules, or ok where submodules: records the gitlink (case deleted-and-recorded).

An unmerged .gitmodules still names nothing. git reads no copy then. With the file gone from this disk, the index holds no :.gitmodules (rev-parse --verify fails), so registered_in_the_index returns None. The limits sentence (module docstring, and unregistered_gitlinks) now says what the doctor really does, as RV1092e's NIT suggested: it names nothing there only while the copy on this disk is the conflict, registers the submodule, or is not there.

The module docstring's limits sentence no longer lists #1093's state.

Kept byte for byte. I compared every non-docstring string literal of shape-doctor.py with ast (RV1092d's strings.py), at main and at this head.

• Removed or changed: 0.
• Added: 8. They are the two pieces of the new clause, index_copy, rev-parse, -q, --verify, : (the f-string piece of :.gitmodules) and "" (the clause's empty return).
• adopt-project.py and shape-doctor.py: a .gitmodules of whitespace is asked on every run, a dropped file whose blob the root also holds counts as root, _answered_legs is quadratic, and two validator code families have no placeholder row #914's clause and entry, shape-doctor.py: a leg's gitlink that no .gitmodules section registers, beside a .gitmodules whose sections name other paths or beside none, is named by no row, though a recursive clone of the leg leaves it empty #1080's two clauses and entries, and every refusal code are unchanged, and their existing cases pass unchanged.

Decisions the direction left open

• The value's name, index_copy. It names what git reads in this state. missing_gitmodules would read too close to no_gitmodules.
• The staged removal after the restore. Right after git restore .gitmodules, git rm --cached alone also exits 0 (measured). The clause still says "once it is staged (git add .gitmodules)", as the direction asks and as adopt-project.py and shape-doctor.py: a .gitmodules of whitespace is asked on every run, a dropped file whose blob the root also holds counts as root, _answered_legs is quadratic, and two validator code families have no placeholder row #914's and shape-doctor.py: a leg's gitlink that no .gitmodules section registers, beside a .gitmodules whose sections name other paths or beside none, is named by no row, though a recursive clone of the leg leaves it empty #1080's clauses word it. Right after the restore it stages nothing, and it keeps the removal true if the restored file is then edited.
• One state takes more. Say the index's copy has a line git refuses before the gitlink's section. The doctor names the gitlink, which matches git's 128. Once restored, the file on disk is one git refuses whole (bad config line, 128), and the doctor names nothing, as beside any file git refuses. The removal still works as printed (case deleted-read-to-its-first-bad-line). A section needs that line mended too. index_copy_clause's docstring says so.
• A copy git refuses whole (a value git dies on, update = bogus) names nothing, as a refused file on this disk does. It is probed and tested (deleted-and-refused-whole).

Out of scope

• shape-doctor.py: beside a .gitmodules that a leg's index tracks but this disk lacks, a gitlink with no section in the index's copy is not named, though git reads that copy and git submodule status exits 128 #1093 has no "Needs a ruling" or "Documented limit" section.
• Left as named limits, unchanged:
  • an unmerged .gitmodules (still names nothing, as directed);
  • a .gitmodules git refuses whole;
  • a link or a directory at .gitmodules;
  • a gitlink path with a control character, or bytes that are not UTF-8.
• tests/test_shape_doctor.py is unchanged: none of its tests forced a change.

Tests

At 8ec615f4, one file at a time, under the stub gh, GH_TOKEN=bogus, an empty GH_CONFIG_DIR, GIT_CONFIG_GLOBAL=/dev/null and EMAIL exported:

file	result
tests/test_doctor_plan_overrides.py	69 passed in 92.46s
tests/test_doctor_recorded_answers.py	29 passed in 67.71s
tests/test_doctor_next_is_a_command.py	61 passed in 112.88s
tests/test_shape_doctor.py (once)	445 passed, 3 skipped in 805.52s
tests/test_scaffold_leg_path_collisions.py	104 passed in 6.33s
tests/test_repo_hygiene.py	100 passed in 3.06s
tests/test_no_auto_maintenance.py	58 passed, 2 skipped in 10.19s
tests/test_agents_md_codes.py	47 passed in 2.36s
tests/test_cli_reference.py	23 passed in 39.13s
tests/test_update_add_codes_documented.py	6 passed in 0.58s

New cases in tests/test_doctor_plan_overrides.py:

• test_a_gitlink_no_section_registers_is_said: deleted-and-registering, deleted-with-no-section, deleted-with-other-sections, deleted-and-recorded, deleted-read-to-its-first-bad-line, deleted-read-to-a-bare-path, deleted-and-refused-whole;
• test_a_section_written_for_the_gitlink_registers_it[deleted-with-other-sections];
• test_an_unmerged_gitmodules_this_disk_lacks_names_nothing.

pyflakes:

• shape-doctor.py: no warning at main or at this head.
• tests/test_doctor_plan_overrides.py: no new kind of warning. The new test's standard and project parameters add two more of the file's existing fixture-shadowing messages ("redefinition of unused 'standard'/'project'"), as every fixture-taking test there does.

Mutants

Each mutant was run with -k "no_section_registers or section_written or unmerged_gitmodules_this_disk" (28 cases). After each run, the file was restored and cmp said identical. Code with docstrings stripped (ast) is identical between the tree the mutants ran on and 8ec615f4.

mutant	break	result
M1	the new branch never taken	KILLED, 5: deleted-with-no-section, deleted-with-other-sections, deleted-and-recorded, deleted-read-to-its-first-bad-line, deleted-read-to-a-bare-path
M2	no rev-parse --verify :.gitmodules first	KILLED, 1: test_an_unmerged_gitmodules_this_disk_lacks_names_nothing
M3	HEAD's copy read in place of the index's	KILLED, the same 5 as M1
M4	partial=False in registered_in_blob	KILLED, 2: in-head-read-to-its-first-bad-line, deleted-read-to-its-first-bad-line
M5	working_tree=True in registered_in_blob	KILLED, 1: deleted-read-to-a-bare-path
M6	a copy git refuses whole read as an empty set	KILLED, 1: deleted-and-refused-whole
M7	index_copy_clause left out of held_clauses	KILLED, the same 5 as M1
M8	the way out without the restore, in the doctor and the test's copy of the clause alike	KILLED, 6: the 5 above (the typed check finds .gitmodules gone) and test_a_section_written_for_the_gitlink_registers_it[deleted-with-other-sections]

Probes

Each probe is a fresh leg, compared against git submodule status (git 2.43). In each row the index tracks .gitmodules, and this disk lacks it unless the case says otherwise.

case	status rc	main names	head names, beside	agree at head
idx-registers	[0]	[]	[] None	yes
idx-no-byte	[128]	[]	['vendor/lib'] index_copy	yes
idx-only-a-comment	[128]	[]	['vendor/lib'] index_copy	yes
idx-other-section	[128]	[]	['vendor/lib'] index_copy	yes
idx-section-with-no-key	[128]	[]	['vendor/lib'] index_copy	yes
idx-bad-line-before-its-section	[128]	[]	['vendor/lib'] index_copy	yes
idx-bad-line-after-its-section	[0]	[]	[] None	yes
idx-bare-path-key	[128]	[]	['vendor/lib'] index_copy	yes
idx-bare-url-then-path	[128]	[]	['vendor/lib'] index_copy	yes
idx-path-then-bare-url	[0]	[]	[] None	yes
idx-refused-whole-update-registers	[128]	[]	[] None	NO
idx-refused-whole-update-other	[128]	[]	[] None	NO
idx-refused-whole-shallow-registers	[128]	[]	[] None	NO
idx-twice-lib-then-other	[128]	[]	['vendor/lib'] index_copy	yes
idx-twice-other-then-lib	[0]	[]	[] None	yes
idx-split-section-other-last	[128]	[]	['vendor/lib'] index_copy	yes
idx-two-gitlinks-one-registered	[0, 128]	[]	['vendor/two'] index_copy	yes
idx-other-head-registers	[128]	[]	['vendor/lib'] index_copy	yes
idx-registers-head-other	[0]	[]	[] None	yes
idx-other-no-commit	[128]	[]	['vendor/lib'] index_copy	yes
idx-registers-no-commit	[0]	[]	[] None	yes
idx-registers-disk-other	[128]	['vendor/lib']	['vendor/lib'] other_sections	yes
idx-other-disk-registers	[0]	[]	[] None	yes
idx-registers-disk-dir	[128]	[]	[] None	NO
idx-other-disk-dangling-link	[128]	[]	[] None	NO
unmerged-disk-missing	[128]	[]	[] None	NO
unmerged-disk-registers	[128]	[]	[] None	NO
unmerged-disk-other	[128]	['vendor/lib']	['vendor/lib'] other_sections	yes
unmerged-disk-conflict-markers	[128]	[]	[] None	NO

• Before and after. At main, 15 of the 21 rows in shape-doctor.py: beside a .gitmodules that a leg's index tracks but this disk lacks, a gitlink with no section in the index's copy is not named, though git reads that copy and git submodule status exits 128 #1093's state (the first 21 below) disagreed with git. At this head, every row agrees except the 3 copies git refuses whole, which are the refused-file limit.
• Limits and neighbours. The directory, the link and the unmerged rows are the named limits, and are unchanged from main.
• RV1092d's probe_d.py (24 rows) gives identical rows at main and at this head.
• RV1092's probe.py (32 rows) changes in one row only: tracked-missing-on-disk-other, which at main was [] None NO and at this head is ['vendor/lib'] index_copy yes.

Merges

At the first push (current ones are under "Review round 2"). git merge-tree --write-tree, after a fresh fetch:

• origin/main 16f9a0e8 (shape_materialize.py: the fetch for a branch's answer leaves out every refspec of the repository's own onto the branches' names, whatever its source, and every one that puts a branch under a name not its own, so family.py bump and bump-leg.py no longer fail where the remote has x and release/x and the repository's own git fetch origin works (#1066) #1087 landed): clean.
• Open PRs, listed live: none of them touches shape-doctor.py or these tests.
  • templates/assembly-root/project.yaml and templates/family-root/family.yaml: the comment above visibility: says it is the visibility the run asked for, and that a repository the run reuses keeps its own, where it said "this is all three repositories' visibility" (#913) #1102, scaffold-project.py: the --reuse-empty-repo help, its docs and each remedy that sends a person into that re-run say ssh, a credential helper or askpass can still make it wait, and how to keep it from waiting (#915) #1101, family.py: a failed remove's by-hand lines spell a leg mounted at a path that is not UTF-8 as a printf word of octal escapes ending in a slash, so git -C <member>/<leg> and submodule update -- <leg> typed in any POSIX shell name that leg (#1086) #1098, tests.yml: the full suite keeps its temporary files under runner.temp, not /tmp, so it runs on Ubuntu 26.04 and the tests job goes back to ubuntu-latest (#1096) #1097, shape_materialize.py, adopt-project.py and bump-leg.py: a tag a clone holds without its commit is one it cannot answer for, check says a commit it cannot ask was not asked, and a pinned product YAML 1.1 or 1.2 reads as no text is quoted (#912) #1090, the family root's bootstrap.py: credential_advice and ended_on say a member's failed clone ends git's update with 1 before any checkout but a leg's lets it go on, and killed_said says git's update was itself killed, not that it went on (#1085) #1088 and the family root's siblings.py: with a token in use, the clone and the fetch that carry it run in bootstrap.py's untraced() environment, so make siblings and family.py siblings write the token to no trace the caller asks git for (#1055) #1075 merge clean.
  • adopt-project.py: check names what the clone's .git holds as git keeps refs, and asks a pin's file through the links the root keeps, so a link into .git or onto a pin's file is refused before any leg or adopted with the copy beside it (#904) #1091 conflicts in adopt-project.py. It conflicts the same way with main alone, so the conflict is adopt-project.py: check names what the clone's .git holds as git keeps refs, and asks a pin's file through the links the root keeps, so a link into .git or onto a pin's file is refused before any leg or adopted with the copy beside it (#904) #1091's own.

Review round 1 (RV1109: READY)

RV1109 found no MUST. This round is commit ab140500, on top of 8ec615f4. It changes docstrings and tests only: the ast check of shape-doctor.py shows no non-docstring string changed, and with docstrings stripped the code is identical to 8ec615f4.

• SHOULD-1, taken. gitmodules_beside_gitlink takes kept="deleted-over-head". It commits the opposite copy with the gitlink first, makes that commit the pin, then stages the case's copy and deletes the file from this disk. Two new rows use it:
  • deleted-over-head-registering: SECTIONED in the index, OTHER_SECTION in HEAD, nothing named;
  • deleted-over-head-with-other-sections: the reverse, named under index_copy.
• RV1109's M3b, KILLED. M3b reads HEAD's copy where HEAD has one. With RV1109's mut_rv.py, both new rows fail (2 failed, 28 passed). M3 re-run: KILLED, 7 failed. Each time the file was restored and cmp says identical.
• SHOULD-3, taken. Where .gitmodules is marked skip-worktree and missing from this disk, the gitlink is named (git reads the index's copy, status 128). But git restore .gitmodules exits 1 there, as git checkout -- .gitmodules does (measured). index_copy_clause's docstring and the module docstring now name this as a limit: family.py's gitmodules-sparse state.
• NIT-2, taken. The unregistered_gitlinks docstring now says a recursive clone and git submodule status both exit 128 with bad config line where the copy holds a line git refuses.
• NIT-5, taken. index_copy_clause's docstring says why git add .gitmodules stays: once a section is written for one submodule, git rm --cached of another exits 128 until the file is staged.
• NIT-1, taken. This body replaces the one with the appended bot block.
• Not taken: NIT-3 (one restore spelling across the tools, for a follow-up ruling) and NIT-4 (the pytest fixture idiom).
• SHOULD-2, done in round 2 (e446ff58b, below): the BENIGN entry is in tests/test_path_guard_hygiene.py now that lane 1's tests/test_path_guard_hygiene.py and shape-doctor.py: a bare is_file/is_dir/exists guard in a shipped tool fails by file and line unless its _is_a or a reasoned allowlist covers it, and a project.yaml linked into an unsearchable folder is yaml-unreadable (#430) #1111 has landed on main.

Tests at ab140500 (one at a time, under the stub gh, with EMAIL exported):

file	result
tests/test_doctor_plan_overrides.py	71 passed in 105.15s
tests/test_doctor_recorded_answers.py	29 passed in 81.69s
tests/test_doctor_next_is_a_command.py	61 passed in 146.85s
tests/test_agents_md_codes.py	47 passed in 3.56s

pyflakes: shape-doctor.py has no warnings. tests/test_doctor_plan_overrides.py has the same 30 messages as at 8ec615f4.

Review round 2 (RV1109 round 2: READY; SHOULD-2 and NIT-6 done)

Lane 1's #1111 (tests/test_path_guard_hygiene.py, #430 slice Z) merged to main at 2026-10-21T18:42:21Z as 038dafba9dbedd9405b316cc749a04dffe02bb36. This round is the merge of that main into this branch (1e733793f, no conflict) and one commit on top of it, e446ff58b. It changes a test table and a docstring: with docstrings stripped, ast shows shape-doctor.py identical to the merge.

• SHOULD-2, done in e446ff58b. The semantic conflict RV1109 predicted is real. At the merge, tests/test_path_guard_hygiene.py gave 1 failed, 48 passed in 7.68s:
  • test_no_bare_guard_outside_a_stat_helper_or_the_allowlist[shape-doctor.py]: "shape-doctor.py:8899, in unregistered_gitlinks: os.path.lexists(mount / adopt.GITMODULES) is a bare guard."
  • The entry is now in BENIGN, tagged ASKED: (SD, "unregistered_gitlinks", "os.path.lexists(mount / adopt.GITMODULES)"), reason "a leg git listed the index of first, by lstat (shape-doctor.py: beside a .gitmodules that a leg's index tracks but this disk lacks, a gitlink with no section in the index's copy is not named, though git reads that copy and git submodule status exits 128 #1093)".
  • The reason is true of the code: the call comes after adopt.GITMODULES in paths, and paths is the leg's index as leg_tracked_files lists it (git ls-files), in a mount mount_read read first. It sits where the table's alphabetical order puts it, after unloaded_manifest_row, not next to registered_unindexed, whose entry has the same reason.
• NIT-6, done. The unregistered_gitlinks docstring paragraph that began at 88 characters is rewrapped to 75, the same words.
• NIT-7 is moot. tests/test_path_guard_hygiene.py and shape-doctor.py: a bare is_file/is_dir/exists guard in a shipped tool fails by file and line unless its _is_a or a reasoned allowlist covers it, and a project.yaml linked into an unsearchable folder is yaml-unreadable (#430) #1111 landed first, so this PR carries the entry and tests/test_path_guard_hygiene.py and shape-doctor.py: a bare is_file/is_dir/exists guard in a shipped tool fails by file and line unless its _is_a or a reasoned allowlist covers it, and a project.yaml linked into an unsearchable folder is yaml-unreadable (#430) #1111 owes nothing.

Tests at e446ff58b (one at a time, under the stub gh, with EMAIL exported, timeout 2400):

file	result
tests/test_path_guard_hygiene.py	49 passed in 8.68s
tests/test_shape_doctor.py	445 passed, 3 skipped in 569.83s
tests/test_scaffold_leg_path_collisions.py	104 passed in 3.73s
tests/test_doctor_plan_overrides.py	71 passed in 75.17s
tests/test_repo_hygiene.py	100 passed in 2.41s

tests/test_doctor_recorded_answers.py, tests/test_doctor_next_is_a_command.py and tests/test_agents_md_codes.py were not run again this round: they were run at ab140500, and since then only the merged #1111 code and the docstring rewrap changed in shape-doctor.py.

Mutant. The new BENIGN entry dropped: tests/test_path_guard_hygiene.py gives 1 failed, 48 passed in 9.34s, the same test as at the merge. The file was restored and cmp says identical.

Merges (git merge-tree --write-tree, after a fresh fetch):

• origin/main 038dafba9 (tests/test_path_guard_hygiene.py and shape-doctor.py: a bare is_file/is_dir/exists guard in a shipped tool fails by file and line unless its _is_a or a reasoned allowlist covers it, and a project.yaml linked into an unsearchable folder is yaml-unreadable (#430) #1111 itself): clean, tree d7815c9a707c2e6750c7aa8f094ccb4df82b9294, the head's own tree, since the head holds main.
• Open PRs, listed live (24): none but shape-doctor.py: a gitlink beside a .gitmodules the leg's index tracks and this disk lacks is named from the index's copy, which git reads, with its own way out that restores the file first (git restore .gitmodules), as #1080 names one beside other sections (#1093) #1109 touches shape-doctor.py or tests/test_path_guard_hygiene.py, so there is nothing else to merge against.

Closes #1093

Lane: openreposhape-3 (openRepoShape-3)
🤖 Generated with Claude Code

Summary by Sourcery

Teach shape-doctor to diagnose unregistered gitlinks using the index's .gitmodules copy when the working-tree file is missing, and explain how to resolve them.

New Features:

• Detect gitlinks whose missing working-tree .gitmodules is still tracked in the index but does not register them, and report the index copy as the source of truth.
• Provide remediation guidance that restores the missing .gitmodules before either adding its submodule section or removing the gitlink.

Bug Fixes:

• Align shape-doctor findings with Git's handling of missing, staged .gitmodules files, including precedence over HEAD and partial parsing behavior.

Enhancements:

• Share .gitmodules blob registration logic across HEAD and index copies and document the remaining unmerged, refused-file, and sparse-checkout limits.

Documentation:

• Update shape-doctor guidance and leg metadata documentation for index-backed .gitmodules cases.

Tests:

• Add coverage for index-copy registration, conflicting HEAD/index contents, malformed files, remediation commands, and unmerged .gitmodules behavior.
• Extend path-guard hygiene coverage for the new filesystem guard.

[sourcery-ai]

Reviewer's Guide

Updates shape-doctor.py to identify unregistered gitlinks using the index’s .gitmodules copy when the working-tree file is deleted, emits a restore-first remediation, and adds comprehensive tests for classification, limits, and recovery behavior.

Sequence diagram for detecting unregistered gitlinks from the index copy

sequenceDiagram
    participant Doctor as shape-doctor.py
    participant Index as Git index
    participant Git as Git
    participant Status as git submodule status

    Doctor->>Doctor: unregistered_gitlinks()
    Doctor->>Doctor: Check .gitmodules is tracked and missing on disk
    Doctor->>Git: registered_in_the_index()
    Git->>Index: rev-parse --verify :.gitmodules
    Index-->>Git: Index blob or no entry
    alt Index copy exists
        Doctor->>Git: registered_in_blob(:.gitmodules)
        Git-->>Doctor: Sections up to first bad line
        Doctor->>Doctor: Name gitlinks not registered by index copy
        Git->>Status: Read index .gitmodules
        Status-->>Git: Exit 128 for unregistered gitlink
    else .gitmodules is unmerged
        Git-->>Doctor: None
        Doctor->>Doctor: Name nothing
    end

Loading

Flow diagram for index-copy remediation

flowchart TD
    A[.gitmodules tracked in index but missing on disk] --> B[Read index copy with registered_in_the_index]
    B --> C{Does index copy register gitlink?}
    C -->|Yes| D[Do not name gitlink]
    C -->|No| E[Emit index_copy note]
    E --> F[git restore .gitmodules]
    F --> G{Choose remediation}
    G -->|Keep gitlink| H[Add path and url section]
    G -->|Remove gitlink| I[git add .gitmodules]
    I --> J[git rm --cached <its path in the leg>]

Loading

File-Level Changes

Change	Details	Files
Teach the doctor to inspect the index’s .gitmodules blob when the tracked file is missing from the working tree, matching Git’s submodule-status behavior.	Add an index_copy beside classification for unregistered gitlinks. Read :.gitmodules with partial parsing and preserve the unmerged and whole-file-refusal limits. Refactor HEAD and index blob handling through a shared helper.	shape-doctor.py
Provide a dedicated remediation clause for gitlinks whose registration is missing from the index copy.	Add the index_copy_clause to generated plan clauses. Recommend restoring .gitmodules before either adding its section or staging and removing the gitlink. Document the new value and behavior in module and function docstrings.	shape-doctor.py
Expand plan-override coverage for deleted working-tree .gitmodules states and verify the prescribed recovery commands.	Cover registering, absent, alternate-section, malformed, refused, recorded, and unmerged cases. Assert row status, beside metadata, exact clause text, and preservation of the index copy. Test both adding a section and removing the gitlink after restoration.	tests/test_doctor_plan_overrides.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#1093	When a leg’s index tracks .gitmodules but the working-tree file is absent, read the index copy and name any gitlink it does not register, whether that copy has no section or only sections for other paths.	✅
#1093	Report the missing-index-copy case with its own unregistered_beside value and a recovery clause that restores .gitmodules before registering or removing the gitlink.	✅
#1093	Preserve the intended limits around unmerged or unreadable .gitmodules copies, and test the new detection and recovery behavior.	✅

---

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-3, 2026-10-21T13:39:08Z) Independent review RV1109 of #1109 at 8ec615f: READY (no MUST). Three SHOULDs before the landing word.

SHOULD-1 (tests): no test checks that the index's copy is read before HEAD's. Every deleted row has no .gitmodules in HEAD, so a mutant that reads HEAD's copy when HEAD has one passes all 28 #1093 cases. In a probe that mutant names a registered gitlink (index registers, HEAD does not) and misses an unregistered one. Fix: add kept="deleted-over-head" to gitmodules_beside_gitlink (commit the opposite copy with the gitlink, pinned_at_its_head, then stage body and unlink), with rows (SECTIONED, False, "deleted-over-head", None) and (OTHER_SECTION, False, "deleted-over-head", "index_copy"), and widen the two kept == "deleted" checks (:635, :656). Checked in a scratch clone: 24 passed at the head; the mutant fails both new rows.

SHOULD-2 (land order with #1111): the textual merge is clean, but on main + #1111 + #1109, tests/test_path_guard_hygiene.py fails on the new bare guard at shape-doctor.py:8865, os.path.lexists(mount / adopt.GITMODULES) in unregistered_gitlinks. Whichever lands second adds to BENIGN: (SD, "unregistered_gitlinks", "os.path.lexists(mount / adopt.GITMODULES)"): ("ASKED", "a leg git listed the index of first, by lstat").

SHOULD-3 (skip-worktree): with .gitmodules marked skip-worktree and missing from disk, git reads the index's copy (status 128) and the doctor names the gitlink, but the first printed step, git restore .gitmodules, exits 1 (pathspec did not match). Name this as a limit in index_copy_clause's docstring and the module docstring (family.py's gitmodules-sparse state), or file a follow-up.

NITs: (1) Sourcery appended "## Summary by Sourcery" after the robot line (it contains U+2019); restore the body from W1093's pr-body.md before landing. (2) shape-doctor.py:8850 "exits 0 ... no submodule mapping found" is not true where the copy has a bad line before the section: the clone exits 128 with "bad config line". (3) family.py prints git checkout -- .gitmodules for the same restore; both behave the same, and #1093 asked for git restore, so one spelling is a follow-up ruling. (4) pyflakes: two more fixture "redefinition of unused" warnings, the file's usual idiom. (5) Say in the docstring why the git add .gitmodules step stays: without it, git rm --cached exits 128 once a section was written for another submodule.

Checked: every probe disagreement with git submodule status and a recursive clone is a named limit (refused, link, unmerged). Every printed step exits 0 and status exits 0 afterwards. The unmerged sentences are true. The ast check gives 0 strings removed or changed and 8 added; registered_unindexed behaves as before (probe_d identical). Sonar QG OK, duplication on new code 0.0%. Tests: overrides 69, recorded_answers 29, next_is_a_command 61, agents_md_codes 47, all passed. Mutants M1, M3 and M8 killed. Merges with main and #1111 are clean. Body: closes [1093], draft, no milestone.

Lane 3's plan: READY, with a fix round before the landing word. In the next usage window W1093, the writer, takes SHOULD-1 (the deleted-over-head rows), SHOULD-3 (the skip-worktree state named as a limit), NIT-2 and NIT-5 (the docstring words), and NIT-1 (the body restored). RV1109 then checks the new head. SHOULD-2: #1111 (lane 1, for #430, in v1.2.0) lands before this follow-up, so #1109 adds the BENIGN entry when it is brought up to a main that holds #1111. NIT-3 (one restore spelling across the tools) is a possible follow-up ruling, and NIT-4 needs nothing. #1109 stays a draft with no milestone and lands after the v1.2.0 tag, on a later word.

Lane: openreposhape-3 (openRepoShape-3)

[brettheap]

(lane openRepoShape-3, 2026-10-21T14:18:29Z) RV1109 round 2 at ab14050: READY.

• SHOULD-1: the two deleted-over-head rows are in. Rerun on the shape-doctor.py: beside a .gitmodules that a leg's index tracks but this disk lacks, a gitlink with no section in the index's copy is not named, though git reads that copy and git submodule status exits 128 #1093 cases: M3 KILLED (7 failed), M3b KILLED (2 failed, both new rows). Files restored and cmp identical.
• SHOULD-3, NIT-2, NIT-5: each new docstring sentence matches a measurement (git 2.43). Skip-worktree: ls-files -t shows S, the gitlink is named, git restore and git checkout -- exit 1, and once the mark is cleared every step exits 0. Bad-line copies: the clone and its status exit 128 with "bad config line". Mixed case: git rm --cached exits 128 until git add .gitmodules.
• shape-doctor.py with docstrings stripped is identical to 8ec615f; no non-docstring string added or removed.
• Tests: test_doctor_plan_overrides.py 71 passed, test_doctor_next_is_a_command.py 61 passed.
• Body: ends Closes shape-doctor.py: beside a .gitmodules that a leg's index tracks but this disk lacks, a gitlink with no section in the index's copy is not named, though git reads that copy and git submodule status exits 128 #1093 / Lane / robot, no Sourcery block, SHOULD-2 stated as owed, closes [1093], draft, no milestone, ASCII apart from the robot.
• SonarCloud on ab14050: pass, quality gate OK, new-code duplication 0.0%, 0 issues. CI tests and tests-git-bash were still pending when read.
• merge-tree with origin/main 6da757c: clean.

NITs: shape-doctor.py:8868 is 88 characters after the rewrap. The SHOULD-2 note covers only #1111 landing first; if #1109 lands first, #1111 carries the BENIGN entry.

Lane 3's plan: #1109 is READY at ab14050. It is a follow-up that lands after the v1.2.0 tag, on a later word, and #1111 (lane 1, for #430, in v1.2.0) is due before it. So #1109 carries the BENIGN entry (SHOULD-2) when it is brought up to a main that holds #1111, and NIT-6's rewrap goes in that same commit, which RV1109 then checks. If the order turns out the other way, lane 3 tells lane 1 on #1111 that #1111 carries the entry (NIT-7).

Lane: openreposhape-3 (openRepoShape-3)

[brettheap]

(lane openRepoShape-3, 2026-10-21T23:04:07Z) RV1109c (round 3, fresh reviewer) at e446ff5: READY. No MUST, no SHOULD.

• Merge 1e73379: parents ab14050 and 038dafb; its tree equals git merge-tree --write-tree ab14050 038dafb (a9c29d9f), so nothing was resolved by hand. git diff 038dafb e446ff5 holds only shape-doctor.py: a gitlink beside a .gitmodules the leg's index tracks and this disk lacks is named from the index's copy, which git reads, with its own way out that restores the file first (git restore .gitmodules), as #1080 names one beside other sections (#1093) #1109's three files, and the merge's diff against main is the same as 2a119f2..ab14050.
• SHOULD-2: the BENIGN key matches the failure message exactly, tag ASKED. The reason is true: the guard at shape-doctor.py:8900 runs only once .gitmodules is in paths, which come from leg_tracked_files (git ls-files --stage in a mount mount_read read), and lexists is an lstat. The alphabetical slot is right: the shape-doctor block is strictly sorted, and next to registered_unindexed would break that.
• NIT-6: with docstrings stripped, the ast is identical; the same 349 words; the word diff is empty; the rewrapped lines are 75 characters at most. shape-doctor.py: a gitlink beside a .gitmodules the leg's index tracks and this disk lacks is named from the index's copy, which git reads, with its own way out that restores the file first (git restore .gitmodules), as #1080 names one beside other sections (#1093) #1109 adds no line over 79.
• Tests at e446ff5, one at a time under the stub gh: test_path_guard_hygiene 49 passed, test_doctor_plan_overrides 71 passed, test_repo_hygiene 100 passed.
• Mutant: with the BENIGN entry dropped, test_path_guard_hygiene gives 1 failed, 48 passed (shape-doctor.py:8900 is a bare guard): KILLED. Restored, cmp identical to the e446ff5 blob.
• CI on e446ff5: tests success (21:17:12Z to 22:57:40Z), package success, tests-git-bash success, SonarCloud quality gate OK (0 new issues, new-code duplication 0.0%).
• Merges: with origin/main 038dafb, clean (d7815c9a, the head's own tree). Open PRs read live: shape-doctor.py and shape_advisory.py: a .git or an agent file linked into a folder this user cannot search is said once in what is here or agent files, <name>: cannot be read (<reason>), never absent; a .git offers no way in (#1110) #1144 (lane 1, fix/1110, eb3f098) now also touches shape-doctor.py and tests/test_path_guard_hygiene.py. merge-tree is clean (2e1773d2), and on that merge test_path_guard_hygiene gives 49 passed and test_doctor_plan_overrides 71 passed. Whichever lands second re-checks.
• Body: SHOULD-2 done, NIT-7 moot, draft, no milestone, closes [1093], ends Closes shape-doctor.py: beside a .gitmodules that a leg's index tracks but this disk lacks, a gitlink with no section in the index's copy is not named, though git reads that copy and git submodule status exits 128 #1093 / Lane / robot, the only closing keyword, ASCII apart from the robot, no Sourcery block.

NITs: (8) the body's round-2 Merges line says no other open PR touches these files; #1144 does now. Add the line above at the next body edit. (9) 1e73379 and e446ff5 carry a Co-Authored-By naming Claude Sonnet 5.5, where writer-common asks for Opus 5.5. The squash replaces both commits, so choose the trailer in the squash message.

Lane 3's plan: #1109 is READY at e446ff5, and its SHOULD-2 owed to #1111 is done. NIT-8's line goes into the body at the next body edit, which is the landing's update-branch after the v1.2.0 tag. Whichever of #1109 and #1144 lands second re-checks their merge. The trailer is set in the explicit squash message. #1109 stays a draft with no milestone until then, and lands on a later word.

Lane: openreposhape-3 (openRepoShape-3)

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

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