[brettheap]

#457's L1-84, L1-85, L1-87 and L1-K4, filed together as #914 from lane 3's triage at 5017830. One commit, 3c933e05, cut from main 00f6d7f7. Every line number below is this branch's.

L1-84: a .gitmodules that holds no section (shape-doctor.py)

State at main. The doctor asked nothing only of a .gitmodules of no byte (#655). One holding \n, \r\n, a BOM, spaces or a comment was asked on every run. No record could answer it, and nothing said to delete it. An empty one beside a gitlink was set aside like the emptied file, and no row named the gitlink that nothing registers.

Decided: "empty" means no section, as the Direction says. That is no byte, or only what git's own config reader passes over:

• a whole UTF-8 byte-order mark at the start;
• blank lines, where blank is git's own isspace (space, tab, CR, LF);
• comments opened by # or ;.

holds_no_section (shape-doctor.py:8632) reads it the way git's reader loops over the top of a file. A section, even one with no key, stays asked. So do part of a BOM, a vertical tab and a form feed, which git refuses with bad config line (exit 128, measured). The test also checks that every body read as empty is one git config --file .gitmodules --list reads with exit 0 and no output.

What the doctor says.

• In a leg that holds no submodule, the file asks nothing, as before. The row says how to remove it (empty_clause, :8146), because no record can answer it.
• Beside a submodule of its leg, a section-less .gitmodules is no emptied file: it registers none of the leg's submodules.
  • It stays the question it was: asked, or answered where submodules: places every submodule (empty_gitmodules, :8574).
  • The leg's entry names each submodule under the new --json key unregistered_submodules.
  • The row says what to do (unregistered_clause, :8161).
• git submodule add refuses a path the index already holds (fatal: 'vendor/lib' already exists in the index, measured). So the remedy says to write the section, or to remove the gitlink.

Measured, main 00f6d7f7 against this head. The code leg's .gitmodules in a scaffolded project, --json, placement row:

state	main	head
no byte	ok, not asked	ok, not asked, removal said
\n, \r\n, BOM, spaces and tab, # comment, ; comment, BOM + comment + CRLF	note, asked, NEXT --placement-plan	ok, not asked, removal said
[submodule "x"] (a section, no key)	note, asked	note, asked
part of a BOM, or a vertical tab (git: exit 128)	note, asked	note, asked
no byte + an unregistered gitlink vendor/lib	note, .gitmodules NOT asked, gitlink unnamed	note, asked, gitlink named under unregistered_submodules
\n or a comment + that gitlink	note, asked, gitlink unnamed	note, asked, gitlink named
that gitlink and no .gitmodules at all	note, unnamed	unchanged (out of scope, below)

Measured for the remedy's claims, git 2.43: clone --recurse-submodules of a leg with an unregistered gitlink exits 0 and leaves the directory empty, and git submodule status there exits 128 with no submodule mapping found in .gitmodules.

L1-85: the record's exception, a linear _answered_legs, and a file's row with a /

• README.md's verdict table (README.md:1212) names the exception in the MISPLACED (n paths) row, in place, so no line is added and the cap ledger needs no raise (README.md stays at 1482 = the cap).
  • The handbook's copy of the row says the same (docs/handbook.html:1672).
  • Its two markers for "Keeping a project's shape current" (:1555, :1617) move from blob 5edbfec7 to 355e197f, the README section's new blob, computed by test_repo_hygiene's own readme_fingerprint.
• _answered_legs (adopt-project.py:7108) looks up each path's own names (_covering_names), as the doctor's answered_questions already does. One entry covers a path where exactly one of those names is a plan entry's, spelled by one entry, so it gives the same answer.
  • Timed on this host, best of 3: 3.65 s on main, 0.26 s here, for 120,000 files and 300 entries. Lane 1 measured 6.90 s -> 0.52 s.
  • Same answer, keys and order: 40,000 seeded fuzz cases (duplicates, null paths and legs, paths ending in /, doubled /), and the 120,000 x 300 case.
• A file's row with a / (slashed_rows, shape-doctor.py:8684; slashed_clause, :8186). The Direction leaves open whether to say it or refuse it.
  • Decided: say it, as adopt-project.py and shape-doctor.py: a plan answer that overrides a confident rule passes check and execute, then the doctor's first run says MISPLACED, and an emptied .gitmodules is asked on every run #655's unslashed says the other spelling. The leg's entry names the row under the new --json key slashed, and the row says it answers nothing. It is never a finding and never read as the file's row.
  • Refusing it would belong to the project's validate-manifest.py, which runs where the legs are not checked out and so cannot tell a file from a directory.

L1-87: an identical drop counts as drop (adopt-project.py:15129)

_account_for now asks whether a path was dropped before it counts the root's same blob as its landing (:15148). A dropped path whose only landing is the root's is counted drop. A dropped path in a leg is counted, or found adopt-duplicated, exactly as before. The old elif for a dropped path with no landing could no longer be reached, and is gone.

• Measured: _account_for over 4 source paths with 2 identical drops.
  • main: root 3, drop 0;
  • head: root 1, drop 2;
  • no findings at either.
• _verify on the identical-drop case: the table reads root 1 of 4 and drop 1 of 4, where main read root 2 of 4 and drop 0 of 4.

L1-K4: the records' codes have no placeholder row, by statement (scripts/shape_materialize.py:5022)

The Direction allows either mapping them or saying they have no row. No placeholder carries a submodules: or answered_paths: row: execute appends both after the render its gate asks (adopt-project.py's append["project.yaml"] = record). So FINDING_PLACEHOLDER's comment says why they have none. If a caller ever renders a record into that question, manifest_judged answers None, which leaves every value to the validator.

test_the_records_codes_have_no_placeholder_row asks the shipped validator over a manifest of bad records. It holds the comment to the ten codes the validator makes: manifest-submodules, manifest-submodule-{path,leg,resolution,commit}, manifest-answered-paths and manifest-answered-{path,leg,resolution,commit}.

Every change of words

No refusal code, and no word of any existing refusal, changes. What a person sees that changed:

1. The placement row's clause for an empty .gitmodules (shape-doctor.py:8146):
   • was: the policy asks nothing of N `.gitmodules` that hold(s) no byte and so register(s) no submodule (#655): <paths>
   • now: the policy asks nothing of N `.gitmodules` that hold(s) no section and so register(s) no submodule, in a leg that holds none (#655, #914): <paths>; nothing needs one, and `git rm -f .gitmodules` in its leg removes it
2. New clause (:8161): N submodule(s) sit beside a `.gitmodules` of their leg that holds no section, so nothing registers them and a recursive clone of the leg leaves each empty (#914): <paths>; give each a section with its `path` and `url` in that `.gitmodules`, or, once that `.gitmodules` is staged (`git add .gitmodules`), remove its gitlink with `git rm --cached <its path in the leg>` in its leg
3. New clause (:8186): N row(s) of project.yaml's `answered_paths:` name a file with the `/` only a directory's row ends with, so each answers nothing (#914): <paths>
4. New --json keys on a leg's entry, each present only where there is one: unregistered_submodules, slashed.
5. The MISPLACED row of README.md's verdict table and of the handbook's gains (unless `answered_paths:` answers it into that leg).
6. execute's verification table: an identical drop moves from the root count to the drop count. Numbers only; no words change.

Out of scope

• Tracking: adopt-project.py, converting an existing repository in place #457's L1-104, named in 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 as "also in this area". It is in v1.1.1's known limits, and 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 does not ask for it.
• A gitlink that nothing registers beside a .gitmodules that has sections, or beside none at all. No row names it, at main or here (the last table row above). L1-84 is the empty file's case. A row for every unregistered gitlink is a new check on a leg's integrity, not a placement answer, and is its own issue.
• 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 has no "Needs a ruling" or "Documented limit" section.

Tests

Each command ran alone, under a stub gh first on PATH (exits 97), GH_TOKEN=bogus, an empty GH_CONFIG_DIR and EMAIL=tests@openreposhape.invalid. The full command is /usr/bin/python3 -m pytest -q -p no:cacheprovider --basetemp=<scratch>/bt-<name> -o tmp_path_retention_policy=failed tests/<file>.

file	result
tests/test_adopt_answered_legs.py (new)	9 passed in 0.19s
tests/test_adopt_verify.py	31 passed in 15.65s
tests/test_adopt_manifest_values.py	80 passed in 80.43s
tests/test_doctor_plan_overrides.py (final)	40 passed in 43.94s
tests/test_shape_doctor.py (once)	445 passed, 3 skipped in 601.65s
tests/test_scaffold_leg_path_collisions.py	104 passed in 4.10s
tests/test_repo_hygiene.py (final)	100 passed in 2.11s
tests/test_readme_sections.py	76 passed in 0.42s
tests/test_agents_md_codes.py	47 passed in 1.80s
tests/test_cli_reference.py	23 passed in 29.36s
tests/test_update_add_codes_documented.py	6 passed in 0.45s
tests/test_no_auto_maintenance.py	60 passed in 9.04s

Mutants

Each mutant was applied alone, and only the named tests were run. Each file was then restored, and cmp against git show HEAD:<file> said it was the same. All 11 were KILLED.

id	file	mutation	killed by
M1a	shape-doctor.py	BOM not stripped	test_an_empty_gitmodules_is_asked_nothing[a-byte-order-mark], [a-mark-and-a-comment]
M1b	shape-doctor.py	vertical tab and form feed made blanks	[a-vertical-tab]
M1c	shape-doctor.py	comments not passed over	[a-comment], [a-semicolon-comment], [a-mark-and-a-comment]
M2	shape-doctor.py	if held: -> if False:	test_a_sectionless_gitmodules_beside_a_submodule_is_said, all 4
M3	shape-doctor.py	removal advice dropped from the clause	test_an_empty_gitmodules_is_asked_nothing, 8 of 11
M4	shape-doctor.py	path[:-1] in named -> path in named	test_a_file_row_with_a_slash_is_said[a-file-row-with-a-slash]
M5a	adopt-project.py	spelled-once check dropped	[one-entry-spelled-twice], test_a_seeded_fuzz_answers_as_the_old_loop
M5b	adopt-project.py	back to _covering over every entry	test_no_entry_is_held_against_every_path
M6	README.md	the row's new words removed	test_the_verdict_table_names_the_records_exception, test_the_handbook_follows_the_readmes_outline
M7	adopt-project.py	main's order: if drop and not landings:	test_an_identical_drop_is_counted_as_dropped, test_the_drop_is_asked_before_the_root[dropped-and-the-root-holds-its-bytes]
M8	scripts/shape_materialize.py	"manifest-submodule-path": "PROJECT_ID" row added	test_the_records_codes_have_no_placeholder_row

Merges

git merge-tree --write-tree of this head was run with each of the following. Every one is clean, with no conflicted path:

• origin/main at 4a6b9afde, the tip when this round was checked, and at 6c861635c, which lane 3 named; the tip is one commit past it and touches none of this PR's files;
• adopt-project.py: check's throwaway repositories are made in the work directory with the source's object format and no hook of this machine's; a path git refuses is plan-path-git-refuses, a repository git cannot make there adopt-git-unasked (#910) #1031 at 74c17705;
• scripts/shape_materialize.py, family.py and adopt-project.py's check: a manifest the template's own reader makes no mapping of is told it is a defect in the copy of the standard, naming the template file, and manifest_invalid's docstring is true for the holder (#1059) #1064 at 166ae7bd, which also edits tests/test_adopt_manifest_values.py;
• bump-leg.py: the leg's fetch leaves out every refspec of the leg's own that can bring a tag under origin/, and one onto the branches' names from another namespace, by the rule family.py bump asks, now one function both tools import, so a branch and a tag of one name no longer fail it and a tag no longer answers for a branch (#1037) #1068 at 5312a7d3;
• adopt-project.py: a bad link that plan-empty-symlink or plan-bad-symlink-target names is no longer named again by plan-root-blocks-shape-copy or plan-root-holds-pin, so it gets one finding, and the #908 comments say Linux's bound (#979) #1070 at 20d2d4ba;
• tests: five adopt tests fail when the thing they guard is removed: bytes on stdin, a stub gh that keeps its #! line, a cleared GIT_ALLOW_PROTOCOL, each guard of two pairs reached alone, and three name shapes (#916) #1071 at 24273dd4;
• adopt-project.py and family.py: a source this user cannot enter is source-unreadable, a UTF-8 plan reads its source under the C locale, and a member on a branch that is not UTF-8 is put back on it (#918) #1072 at 2ffd8235.

Lane 3's W918 branch (l3-918-source-and-locale) was not pushed when this was checked.

Follow-ups

• Other unregistered gitlinks, a gitlink that no .gitmodules section registers beside a .gitmodules whose sections name other paths or beside none: 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.

Review round

RV1073 reviewed 3c933e05 and found one MUST. This round is one commit, b58a4e2c, on top of it, pushed as a fast-forward.

• MUST-1 (shape-doctor.py:8163): the empty clause's advice git rm .gitmodules exits 1 where the leg's .gitmodules is staged and not committed, or changed on disk and not staged. It now says git rm -f .gitmodules. Measured, git 2.43, exit 0 and an empty git ls-files .gitmodules in each of four states: committed as empty; staged and not committed (the state a plain git rm of the leg's only submodule leaves); committed with a section and emptied on disk; and a plain git rm of the only submodule, uncommitted. EMPTY_CLAUSE (tests/test_doctor_plan_overrides.py:272) says -f, and test_an_empty_gitmodules_is_asked_nothing types the printed command in the leg for each of the 8 bodies not asked, and asserts exit 0 and an empty git ls-files .gitmodules.
• SHOULD-1 (shape-doctor.py:8193-8196): git rm --cached exits 128 (please stage your changes to .gitmodules) where the leg's tracked .gitmodules has an edit that is not staged. The clause now says once that .gitmodules is staged (git add .gitmodules). Measured on a committed .gitmodules with a section, emptied on disk only, beside a gitlink: git rm --cached vendor/lib alone exits 128, and git add .gitmodules then git rm --cached vendor/lib both exit 0. The new case no-byte-and-an-unstaged-edit of test_a_sectionless_gitmodules_beside_a_submodule_is_said asserts that for a tracked .gitmodules (staged in the fixture, not committed, which git treats the same way here), and the other 4 cases type the same two commands.
• NIT-1 (same lines): the clause names the path as <its path in the leg>, not the row's code/vendor/lib, which typed in the leg exits 128 (pathspec 'code/vendor/lib' did not match) where vendor/lib exits 0. Chosen over a command per path because it keeps the clause one sentence, and the clause already used a placeholder. The tests type each printed command with the placeholder replaced by vendor/lib.
• NIT-2: no change.
• NIT-3: no change.
• Words: item 1 and item 2 of "Every change of words" now read as the commit prints them. The changed words are git rm .gitmodules to git rm -f .gitmodules in item 1, and in item 2 or remove its gitlink with git rm --cached in its leg to or, once that .gitmodules is staged (git add .gitmodules), remove its gitlink with git rm --cached in its leg. No other printed word changes. In this body, items 1 and 2, the Merges section, the new Follow-ups section and this Review round changed; every other word is as it was.
• Line numbers: the numbers elsewhere in this body are at 3c933e05. At b58a4e2c, empty_clause stays at :8146, and unregistered_clause is at :8166, slashed_clause at :8199, empty_gitmodules at :8587, holds_no_section at :8645 and slashed_rows at :8697.
• Tests at b58a4e2c, each alone under the stub gh, with the command of "Tests" above: test_doctor_plan_overrides.py 41 passed in 64.37s (the "Tests" table's row for it was 40 passed at 3c933e05); test_shape_doctor.py (once) 445 passed, 3 skipped in 729.85s; test_scaffold_leg_path_collisions.py 104 passed in 6.07s; test_adopt_answered_legs.py 9 passed in 0.28s; test_adopt_verify.py 31 passed in 23.86s; test_readme_sections.py 76 passed in 0.33s; test_repo_hygiene.py 100 passed in 2.99s; test_no_auto_maintenance.py 60 passed in 9.62s. pyflakes on shape-doctor.py and the edited test file reports the same 24 messages as at 3c933e05 (the test file's fixture imports), none new.
• Mutants of the round, each applied alone and the files then restored (cmp against the saved copy said the same). All 4 KILLED:
  • A, the doctor prints plain git rm .gitmodules: test_an_empty_gitmodules_is_asked_nothing, all 8 bodies not asked, on the expected clause;
  • B, the doctor and EMPTY_CLAUSE both print plain git rm .gitmodules (the defect as RV1073 found it): the same 8, on the typed command's exit 1, the following file has changes staged in the index;
  • C1, the doctor and UNREGISTERED_CLAUSE both drop the staging step: test_a_sectionless_gitmodules_beside_a_submodule_is_said[no-byte-and-an-unstaged-edit], on the typed git rm --cached exit 128;
  • C2, the doctor and UNREGISTERED_CLAUSE both print the row's code/vendor/lib: all 5 cases of that test, on exit 128, pathspec 'code/vendor/lib' did not match.
• Merges at b58a4e2c: see "Merges" above. adopt-project.py: a --work-dir that is, or runs through, a symlink round a loop is refused in words that name the link and the loop, not "(File exists)", and a symlink to a file is named as one (#978) #1065 is not listed, as it has landed in 6c861635c.

Closes #914

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

Summary by Sourcery

Refine adoption and shape-doctor validation to report edge cases accurately and keep verification counts aligned with the project plan.

New Features:

• Improve shape diagnostics for sectionless .gitmodules files, unregistered submodules, and file paths incorrectly written with a trailing slash.

Bug Fixes:

• Count identical dropped files as drops rather than root landings during adoption verification.
• Correct placement handling so answered paths are recognized consistently and documented as an exception to misplaced-path findings.

Enhancements:

• Optimize answered-path leg resolution by looking up each path's covering names instead of scanning every plan entry.
• Clarify that validator findings for submodules: and answered_paths: records intentionally have no placeholder rows.

Documentation:

• Update the README and handbook verdict documentation for paths answered into a leg.

Tests:

• Add coverage for sectionless .gitmodules detection, unregistered gitlinks, slashed file rows, answered-leg resolution, identical drops, and record placeholder behavior.

[sourcery-ai]

Reviewer's Guide

This PR implements the remaining #914 shape-reporting rules: it aligns empty .gitmodules detection with Git’s config reader, distinguishes unregistered gitlinks, reports ineffective slash-suffixed file answers, optimizes answered-leg resolution without changing semantics, counts identical drops correctly, and documents/tests the intentional absence of placeholders for record-level validator findings.

Sequence diagram for identical drop accounting

sequenceDiagram
    participant Plan
    participant Account as _account_for
    participant Verify as _verify
    Plan->>Account: _account_for(before, after, drops)
    Account->>Account: Check whether path is dropped
    alt Dropped with no landing or root landing
        Account-->>Verify: Increment drop
    else Not dropped or landed in a leg
        Account-->>Verify: Count landing or finding
    end
    Verify-->>Plan: Report root and drop totals

Loading

Flow diagram for .gitmodules shape reporting

flowchart TD
    A["Inspect .gitmodules"] --> B{"holds_no_section?"}
    B -- No --> C["Keep .gitmodules question"]
    B -- Yes --> D{"Leg holds submodules?"}
    D -- No --> E["empty_gitmodules\nSuggest git rm .gitmodules"]
    D -- Yes --> F["unregistered_submodules\nSuggest adding path and url\nor removing gitlink"]

Loading

Flow diagram for answered_paths slash validation

flowchart TD
    A["Inspect answered_paths rows"] --> B{"Row path ends with /?"}
    B -- No --> C["No slashed finding"]
    B -- Yes --> D{"Path without / is a file?"}
    D -- No --> E["Directory row spelling is valid"]
    D -- Yes --> F["slashed\nRow answers nothing\nNever a finding"]

Loading

File-Level Changes

Change	Details	Files
Refine .gitmodules emptiness and report previously ambiguous repository states with actionable diagnostics.	Treat a file as sectionless when Git would ignore its BOM, blanks, or comments, while preserving sections and Git-invalid bytes as questions. Distinguish sectionless files in legs with no submodules from those beside unregistered gitlinks; add removal or registration guidance and unregistered_submodules JSON details. Add tests covering Git config semantics, gitlink behavior, JSON output, and generated clauses.	shape-doctor.py tests/test_doctor_plan_overrides.py
Report malformed answered_paths: spellings and document their non-finding behavior.	Detect rows ending in / that actually name files, expose them as slashed, and explain that they answer nothing without treating them as findings. Update the MISPLACED documentation in the README and handbook to note answered_paths: exceptions. Add regression coverage for file, directory, other-leg, and nonexistent-path cases.	shape-doctor.py README.md docs/handbook.html tests/test_doctor_plan_overrides.py
Make answered-leg lookup path-oriented and preserve plan semantics with substantially lower lookup cost.	Replace scanning every plan entry for each path with _covering_names-based lookup while retaining duplicate, invalid-leg, slash, null, and ordering semantics. Add focused and seeded-fuzz tests plus a performance guard ensuring _covering is not invoked.	adopt-project.py tests/test_adopt_answered_legs.py
Classify identical root landings of dropped paths as drops.	Evaluate drop membership before assigning a single root landing, moving only the affected count while preserving leg landings and duplicate findings. Add unit and verification-table coverage for dropped, kept, missing, conflicting, and byte-mismatched landings.	adopt-project.py tests/test_adopt_verify.py
Clarify that submodule and answered-path validator findings intentionally have no materialization placeholder.	Document the post-render append behavior and safe manifest_judged fallback. Test all generated validator codes for both record types and ensure none maps to FINDING_PLACEHOLDER.	scripts/shape_materialize.py tests/test_adopt_manifest_values.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#914	Have the doctor treat a .gitmodules with no section as empty when the leg has no submodules, explain how to remove it, and identify unregistered submodules when such a file sits beside gitlinks.	✅
#914	Document the answered_paths: exception in the verdict table, make _answered_legs faster without changing its answers, and report file rows ending in / that answer nothing.	✅
#914	Count an identical dropped source path as drop rather than root, and account for the manifest-submodule* and manifest-answered* validator codes by documenting why they have no placeholder row.	✅

Possibly linked issues

• 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: The PR addresses the issue’s specified doctor behavior, README documentation, linear _answered_legs, drop-first accounting, and placeholder-code explanation.

---

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-20T21:22:28Z) RV1073, lane 3's independent review of #1073 at 3c933e0 (Ruling 8). Verdict: NOT READY, one MUST.

MUST 1. shape-doctor.py:8157-8158. The empty clause's advice "git rm .gitmodules in its leg removes it" is false wherever the leg's .gitmodules is not committed as it is on disk. Measured, git 2.43, and the doctor prints the clause in each state:

• staged, not committed (adopt-project.py and shape-doctor.py: a plan answer that overrides a confident rule passes check and execute, then the doctor's first run says MISPLACED, and an emptied .gitmodules is asked on every run #655's own case, what a plain git rm of a leg's only submodule leaves before its commit, and the state stage_bytes builds in test_an_empty_gitmodules_is_asked_nothing): rc 1, "error: the following file has changes staged in the index: .gitmodules (use --cached to keep the file, or -f to force removal)";
• committed with a section, emptied on disk, not staged: rc 1, "has local modifications";
• committed as emptied: rc 0.
  An untracked .gitmodules is never named (it is not in ls-files), so that case is fine.
  Fix: print git rm -f .gitmodules. It measured rc 0 in all four states and leaves the file in neither the index nor the disk. It discards nothing a section registers: the clause is printed only where the disk copy holds no section and the leg holds no gitlink. Update EMPTY_CLAUSE (tests/test_doctor_plan_overrides.py:272) and item 1 of the body's words list, and have test_an_empty_gitmodules_is_asked_nothing run the printed command in its leg for each body not asked, asserting exit 0 and an empty git ls-files .gitmodules.

SHOULD 1. shape-doctor.py:8182-8183. git rm --cached <path> dies (rc 128, "fatal: please stage your changes to .gitmodules or stash them to proceed") where the leg's tracked .gitmodules has an unstaged edit, for example one with a section emptied on disk only, which the doctor reads as sectionless and so names the gitlink. git checks that before --cached or -f. Fix: add "once its .gitmodules is staged", or detect the unstaged edit. The committed, staged-gitlink (the fixture) and populated-clone cases measured rc 0.

NIT 1. shape-doctor.py:8183. The row names code/vendor/lib, and typed as printed in the leg, git rm --cached code/vendor/lib is rc 128 (pathspec did not match); vendor/lib works. Say "<its path in the leg>", or print the command per path.
NIT 2. Same remedy: a staged gitlink whose clone is at another commit is rc 1 ("use -f to force removal"). git names the way out; optional.
NIT 3. Sourcery's summary, appended after the robot line, says the record's exception now prevents MISPLACED; this PR only documents it. It adds no closing keyword, and the squash message is explicit.

Held:

• holds_no_section: 29 bodies (W914's 11 plus FF, NUL, BOM twice, LF then BOM, NBSP, lone CR, CR CR LF, no line end, NUL or CR in a comment, a key with no section, [s], and more) under git config --file .gitmodules --list: every body read as empty is rc 0 with no output; 0 unsafe mismatches. A section with no key stays asked, as the Direction says.
• The new clause's claims: recursive clone rc 0 with an empty directory; git submodule status rc 128 "no submodule mapping found"; git submodule add rc 128 "already exists in the index".
• --json keys are documented where empty_gitmodules and unslashed are (module text and constants), and PLACEMENT_LEG_KEYS plus the new tests hold them.
• _answered_legs: my own fuzz, 60,000 cases (17,116 with answers), 0 differences, order included; equivalent by construction too.
• slashed: a fair reading, the mirror of adopt-project.py and shape-doctor.py: a plan answer that overrides a confident rule passes check and execute, then the doctor's first run says MISPLACED, and an emptied .gitmodules is asked on every run #655's unslashed.
• _account_for: the removed elif drop was reachable only at landings == [] with a drop, which the new first branch takes with the same effect. Only tests/test_adopt_verify.py:446 names the old counts, as main's.
• K4 comment true: execute passes both records as append to materialize_assembly_root, which runs no validator; the 10-code test passes.
• Words list complete; no refusal code or text changed.
• Tests at the head, one at a time: test_adopt_answered_legs 9 passed, test_adopt_verify 31, test_doctor_plan_overrides 40, test_readme_sections 76, test_repo_hygiene 100, and the K4 test 1.
• Mutants M2, M4, M5b, M7 all KILLED; each file restored, cmp exit 0.
• merge-tree clean against origin/main 6c86163, adopt-project.py: check's throwaway repositories are made in the work directory with the source's object format and no hook of this machine's; a path git refuses is plan-path-git-refuses, a repository git cannot make there adopt-git-unasked (#910) #1031 74c1770, scripts/shape_materialize.py, family.py and adopt-project.py's check: a manifest the template's own reader makes no mapping of is told it is a defect in the copy of the standard, naming the template file, and manifest_invalid's docstring is true for the holder (#1059) #1064 166ae7b, adopt-project.py: a --work-dir that is, or runs through, a symlink round a loop is refused in words that name the link and the loop, not "(File exists)", and a symlink to a file is named as one (#978) #1065 228531a, bump-leg.py: the leg's fetch leaves out every refspec of the leg's own that can bring a tag under origin/, and one onto the branches' names from another namespace, by the rule family.py bump asks, now one function both tools import, so a branch and a tag of one name no longer fail it and a tag no longer answers for a branch (#1037) #1068 5312a7d, tests: five adopt tests fail when the thing they guard is removed: bytes on stdin, a stub gh that keeps its #! line, a cleared GIT_ALLOW_PROTOCOL, each guard of two pairs reached alone, and three name shapes (#916) #1071 24273dd, adopt-project.py and family.py: a source this user cannot enter is source-unreadable, a UTF-8 plan reads its source under the C locale, and a member on a branch that is not UTF-8 is put back on it (#918) #1072 a1b18fe.
• Body: closingIssuesReferences [914]; ends Closes 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, Lane, robot; the only character above U+007F is the robot emoji.
• Left out: Tracking: adopt-project.py, converting an existing repository in place #457's L1-104 acceptable (v1.1.1 known limit). Other unregistered gitlinks acceptable as their own issue; suggested title: "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".
  Skipped: test_shape_doctor.py (per the brief), the timing, the rest of test_adopt_manifest_values.py, and tests on merged trees.

Lane 3's decisions for the fix round (F1073, running): MUST-1 becomes git rm -f .gitmodules, with the test running the printed command; SHOULD-1 tells the person to stage the leg's .gitmodules first; NIT-1 names the path as the leg spells it; NIT-2 and NIT-3 need no change. A delta review follows. The left-out case is filed as follow-up #1080.

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

[brettheap]

(lane openRepoShape-3, 2026-10-20T21:53:53Z) RV1073d, lane 3's independent delta review of #1073's fix round at b58a4e2 (Ruling 8). Verdict: READY. No MUST, no SHOULD.

Held:

• MUST-1: shape-doctor.py:8163 prints git rm -f .gitmodules. test_an_empty_gitmodules_is_asked_nothing types the printed command in the leg for every body not asked and asserts an empty git ls-files .gitmodules.
• SHOULD-1 and NIT-1: the case no-byte-and-an-unstaged-edit really holds an unstaged .gitmodules edit (its bare git rm --cached is rc 128, "please stage your changes"). git add .gitmodules then git rm --cached vendor/lib exit 0 there and in the other 4 cases.
• Words: a diff of every printed string in shape-doctor.py between 3c933e0 and b58a4e2, docstrings left out, shows exactly the two changed tails. Items 1 and 2 of "Every change of words" match them.
• Body: closingIssuesReferences [914]. The authored text ends Closes 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, the Lane line, the robot line, and has no other closing keyword. The only character above U+007F is U+1F916. 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 appears only under Follow-ups.
• Tests at b58a4e2, one at a time, under the stub gh: test_doctor_plan_overrides.py 41 passed; test_repo_hygiene.py 100 passed. test_shape_doctor.py skipped, per the brief.
• Mutant B (plain git rm in the doctor and EMPTY_CLAUSE): KILLED, 8 failed, by the typed command's rc 1 "has changes staged in the index".
• Mutant C1 (staging step dropped from the doctor and UNREGISTERED_CLAUSE): KILLED, only [no-byte-and-an-unstaged-edit] failed, by the typed git rm --cached vendor/lib rc 128 "please stage your changes to .gitmodules".
• Both files restored after each mutant, cmp exit 0.
• merge-tree --write-tree: clean (rc 0, no conflicted path) against origin/main 4a6b9af, scripts/shape_materialize.py, family.py and adopt-project.py's check: a manifest the template's own reader makes no mapping of is told it is a defect in the copy of the standard, naming the template file, and manifest_invalid's docstring is true for the holder (#1059) #1064 166ae7b, tests: five adopt tests fail when the thing they guard is removed: bytes on stdin, a stub gh that keeps its #! line, a cleared GIT_ALLOW_PROTOCOL, each guard of two pairs reached alone, and three name shapes (#916) #1071 24273dd and adopt-project.py and family.py: a source this user cannot enter is source-unreadable, a UTF-8 plan reads its source under the C locale, and a member on a branch that is not UTF-8 is put back on it (#918) #1072 2ffd823.

NITs (body only; the squash message is written by hand):

• NIT-a: the Review round's Words bullet says "every other word of this body is as it was", but the Merges section was rewritten (new main tip, adopt-project.py: a bad link that plan-empty-symlink or plan-bad-symlink-target names is no longer named again by plan-root-blocks-shape-copy or plan-root-holds-pin, so it gets one finding, and the #908 comments say Linux's bound (#979) #1070, tests: five adopt tests fail when the thing they guard is removed: bytes on stdin, a stub gh that keeps its #! line, a cleared GIT_ALLOW_PROTOCOL, each guard of two pairs reached alone, and three name shapes (#916) #1071 and adopt-project.py and family.py: a source this user cannot enter is source-unreadable, a UTF-8 plan reads its source under the C locale, and a member on a branch that is not UTF-8 is put back on it (#918) #1072 added) and Follow-ups was added.
• NIT-b: the SHOULD-1 bullet calls the new case "a committed .gitmodules". The fixture stages it without a commit. git's check compares the index with the working tree, so the behaviour is the same, and the test's docstring correctly says "tracked".

Lane 3: NIT-a and NIT-b are fixed in the body now. #1073 lands at b58a4e2 through its pilot, chained after #1064, #1071 and #1072, one HOLD at a time.

Lane: openreposhape-3 (openRepoShape-3)

[sourcery-ai]

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

You can request another review in 3 days by commenting @sourcery-ai review. Upgrade to get a review now.