[brettheap]

What

The three follow-ups of #1046 (#977), which lane 1's review of that pull request (r1046) left for later as its NIT-C, NIT-D and NIT-E. None is a regression. Each is a test, a sentence or a docstring: adopt-project.py changes only in a docstring.

(a) Mutant R10: a kept directory entry makefile/ is tested. Dropping the rstrip("/") in twins, in _makefile_follow_up, left every test passing. With a kept makefile/, _root_keeps finds Makefile by its directory form, so folded is True. Without the rstrip, twins is empty and twins[0] raises in plan. The code is right; only the test was missing. ANSWERED in tests/test_adopt_make_reads_first.py gains a ("makefile/", "root") row, id makefile-directory, which expects the line a kept makefile file gets. GNU make 4.3 stops on a directory with makefile: Is a directory. (r1046's measure), so the case is contrived, and the comment above ANSWERED says so.

(b) README says that make at the root reads a kept GNUmakefile or makefile instead. Section "Adopting an existing repository":

• Before: "...shape/Makefile, which holds the export until a person merges the two."
• After: "...shape/Makefile, which holds the export until a person merges the two; make at the root reads a kept GNUmakefile or makefile instead."

README.md is at its cap, 1482 lines (1422 + the 60 in tests/readme-cap.d/), so the paragraph is tightened and stays at 12 lines, and README.md stays at 1482. Three phrasings are shorter. No fact is lost; the word "honest" is:

• "the plan says so up front" for "the plan says so instead of letting it be discovered later";
• a colon for "because" before the assistant-stubs clause;
• "The tool names the edit and does not make it; making it silently would be the dangerous half." for "The tool does not make the edit — naming it is the honest half, making it silently would be the dangerous one."

The handbook's adopt section says nothing of CONTRACTS_DIR, as in #1046, so only its marker moves, to the section's new blob (a7154cc3, from readme_fingerprint over readme_segments). SENTENCE in the test follows the new text.

(c) The docstring of contracts_from_code_leg. It said "CONTRACTS_DIR is the root Makefile's alone", which predates #977. It now says the shape's Makefile's alone: the root's Makefile, or, where the source keeps a Makefile of its own, shape/Makefile.

Measured

Mutants of twins in _makefile_follow_up, each in a scratch git clone --shared of this head, restored by sha256 (e3f38a53...79f5c before and after each):

Mutant	Test file on main	Test file on this head
both rstrip("/") dropped (R10)	32 passed, 1 failed: README's sentence, which this head's README no longer matches, and nothing to do with the mutant	1 failed, 33 passed: [makefile-directory], IndexError: list index out of range
rstrip("/") dropped from the filter only	not run	1 failed, 33 passed: the same IndexError
rstrip("/") dropped from the element only	not run	1 failed, 33 passed: the line names makefile/ where it names makefile

So R10 survived the 32 rows on main and the new row kills it, and both halves of it.

Tests

• tests/test_adopt_make_reads_first.py: 33 tests on main, 34 here.
• Gate on the merge of this head with main at 6da757cb, named files only, one basetemp, a stub gh first on PATH, GH_TOKEN=bogus, GIT_SSH_COMMAND=false, GIT_CONFIG_GLOBAL=/dev/null:
  • test_adopt_make_reads_first, test_adopt_contracts_dir, test_adopt_printed_sentences: 122 passed (34, 34, 54).
  • test_repo_hygiene, test_readme_sections, test_readme_windows_quoting_sentence, test_family_docs_one_spelling, test_setup_by_hand_commands, test_update_add_codes_documented, test_doctor_plan_overrides, test_agents_md_codes, test_cli_reference, test_pinned_copy_text, test_scaffold_leg_path_collisions: 584 passed.
  • test_shape_doctor.py in 4 shards: 445 passed, 3 skipped (the PowerShell line, Windows only).

Merge with main

main moved to 6da757cb while this was made, and was merged here as 3d1c37a6. It touched adopt-project.py elsewhere, and neither README.md nor docs/handbook.html, so the cap and the re-wrap hold. Since then main has moved to 823624d9, and its #1101 added 7 README lines and tests/readme-cap.d/915.txt. r1123's independent review measured the merge with 823624d9 (tree a317e482):

• README.md is 1489 lines, exactly at its cap of 1489.
• The adopt handbook marker is unchanged, at a7154cc3.
• The tests passed: 210 + 70 + 104; the doctor 445 passed and 3 skipped; groups A (122) and B (584).

Not in this PR

#1048 covers the same gap in collision_follow_up, AGENTS-shape.md and the NOTE in adopt-project.py. adopt_makefile_block's docstring in scripts/shape_materialize.py says the block is appended "to the assembly root's Makefile", the same older claim, and is left to it. It is filed as #1135, since #1048 and its PR #1105 do not hold it.

Closes #1061

Lane: openreposhape-1 (openRepoShape-1)

🤖 Generated with Claude Code

Summary by Sourcery

Clarify makefile ownership and root-level make behavior while covering retained makefile directory entries in adoption tests.

Enhancements:

• Clarify which root-level makefiles are read when adopting an existing repository and which Makefile owns CONTRACTS_DIR.
• Add coverage for a retained makefile/ directory entry to protect makefile discovery behavior.

Documentation:

• Update the README and handbook reference marker to document root make behavior.

Tests:

• Extend adoption tests to cover retained makefile directories and keep the documented README sentence synchronized.

[sourcery-ai]

Reviewer's Guide

Implementation

Update the contracts read-across docstring to describe CONTRACTS_DIR as belonging to the shape’s Makefile, which may be the root Makefile or shape/Makefile.

• adopt-project.py L3721-3724

Documentation

Clarify that root-level make reads a kept GNUmakefile or makefile, and refresh the handbook’s README section fingerprint.

• README.md L816-827
• docs/handbook.html L1290

Tests

Add coverage for a kept makefile/ directory and update the README sentence expectation and test commentary for the clarified Makefile behavior.

• tests/test_adopt_make_reads_first.py L132-139, L183-186 (+4 small edits)

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[brettheap]

(lane openRepoShape-1, 2026-10-21T15:35:44Z) r1123, lane 1's independent reviewer (not the writer), reviewed #1123 at 5c3908f8: READY on condition, a complete review. Lane 1 has now met the condition in the body. No MUST. The merge with main 823624d9 is green: README is 1489 lines at a cap of 1489, and the handbook marker is unchanged. The README sentence is true, measured with /usr/bin/make. The new row is the only one that kills R10. Lane 1 met S1 and S2 in the body: adopt_makefile_block's docstring is now filed as #1135, because #1048 and #1105 do not hold it, and the merge section names 823624d9. NIT-1 is softened in the body. NIT-2 and NIT-3 are left. The review follows in full.

---

r1123: review of PR #1123 (Closes #1061)

Verdict: READY on condition. Every check in the brief is finished, so this report is complete. It is not marked PARTIAL even though the checkpoint asked for an early send. The merged tree is green, the README sentence is true when measured with /usr/bin/make, and the new row kills R10 and both of its halves. The condition is the two SHOULDs below: one is a hand-off nobody holds, the other is a body section that has gone stale. Neither needs a code change.

Scratch mutants are restored. sha256 after restore: head clone adopt-project.py e3f38a53…79f5c, base clone 933d072e…d5bc4c. Both clones and the merged clone show a clean git status. My worktree is at 5c3908f8 and clean.

Merge with current main 823624d9

• git merge-tree --write-tree 5c3908f8 823624d9 is clean and gives tree a317e482. I built it in the scratch clone /workspace/projects/openRepoShape-worktrees/_lane1-scratch/r1123/merged. Checking it out took a local commit-tree (4ebbcf10), which was never pushed.
• README cap: README.md is 1489 lines. The test prints the cap is 1422 + 2 (460.txt) + 5 (550.txt) + 12 (563.txt) + 22 (564.txt) + 10 (606.txt) + 1 (683.txt) + 2 (711.txt) + 2 (785.txt) + 1 (786.txt) + 7 (915.txt) + 3 (921.txt) = 1489. It sits exactly at the cap, and the test passes.
• Handbook marker: I recomputed readme_fingerprint of the § Adopting segment on the merged tree and got a7154cc3186677058edf16e13594e83d5907f6c5. It is the only adopt marker in docs/handbook.html, and it matches.
• Results:

Files	Result
test_repo_hygiene (100), test_readme_sections (76), test_adopt_make_reads_first (34)	210 passed
test_cli_reference (23), test_agents_md_codes (47)	70 passed
test_scaffold_leg_path_collisions	104 passed
test_shape_doctor, 4 shards of 112	112, 112, 112, then 109 passed with 3 skipped (PowerShell, Windows only) = 445 passed, 3 skipped
Writer's group A on the merged tree	122 passed (34, 34, 54)
Writer's 11-file group B on the merged tree	584 passed

• Main's commits since 6da757cb (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, 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) touch none of adopt-project.py, scripts/shape_materialize.py, tests/conftest.py or the three adopt test files (git diff --stat is empty). They do not touch the § Adopting segment either.
• No MUST: nothing on the merged tree fails a marker or the cap.

Is the README sentence true? Yes.

I ran real adoptions with the test helper adopt_with_legs_mounted_away, then /usr/bin/make (GNU Make 4.3) at the root of each clone:

Kept at the root	make which	make contracts-dir	-f <shape's> contracts-dir
none	no which rule (only the shape's Makefile)	exit 0, …/Northwind/legs/spec/contracts	exit 0
makefile	makefile	exit 2, No rule to make target 'contracts-dir'	exit 0
GNUmakefile	GNUmakefile	exit 2, No rule	exit 0
Makefile	Makefile	exit 2, No rule	shape/Makefile, exit 0
Makefile + makefile	makefile	exit 2, No rule	shape/Makefile, exit 0
Makefile + GNUmakefile	GNUmakefile	exit 2, No rule	shape/Makefile, exit 0
makefile + GNUmakefile	GNUmakefile	exit 2, No rule	exit 0

A minimal probe with a directory named makefile/ gives make: *** makefile: Is a directory. Stop., which matches the body's quote.

The three trims, sentence by sentence (old against new):

1. "says so instead of letting it be discovered later" became "says so up front". Same meaning.
2. The sentence on plan, follow_ups: and CONTRACTS_DIR is unchanged up to "merges the two". The new clause is appended there.
3. "does not make the edit — naming it is the honest half, making it silently would be the dangerous one" became "names the edit and does not make it; making it silently would be the dangerous half". Both facts are kept; the word "honest" is lost (NIT-1).
4. "because" became a colon. Same meaning.

The paragraph stays at 12 lines (README.md:809-820 at 5c3908f8). No other file quotes the old phrases (git grep finds none), and the handbook's adopt section paraphrases none of them.

The docstring (c) is true

execute passes append={"Makefile": adopt_makefile_block(...)} (adopt-project.py:14868). The block is added to the shape's Makefile wherever place writes it: at the root, or at shape/Makefile when path.exists() (scripts/shape_materialize.py:4645-4676). Nothing else exports CONTRACTS_DIR. One small gap is NIT-2.

Findings

MUST: none.

SHOULD

• S1: the hand-off "left to shape_materialize.py and the pinned AGENTS-shape.md: two sentences say a kept Makefile holds the shape's block back, and leave out a kept makefile or GNUmakefile, which GNU make reads first #1048" is not held by anyone.
  • The body says adopt_makefile_block's docstring (scripts/shape_materialize.py:1140, "appends to the assembly root's Makefile") is left to shape_materialize.py and the pinned AGENTS-shape.md: two sentences say a kept Makefile holds the shape's block back, and leave out a kept makefile or GNUmakefile, which GNU make reads first #1048.
  • shape_materialize.py and the pinned AGENTS-shape.md: two sentences say a kept Makefile holds the shape's block back, and leave out a kept makefile or GNUmakefile, which GNU make reads first #1048's three boxes name only collision_follow_up, AGENTS-shape.md and the NOTE.
  • Its PR, shape_materialize.py and the pinned AGENTS-shape.md: where the root keeps a GNUmakefile or a makefile, which GNU make reads first, the Makefile collision follow-up no longer says the shape's make targets arrive with the merge, and the pinned file says make reads the first of the three and the block reaches it only once that file holds it (#1048) #1105 (head 5a4de7f7, closes shape_materialize.py and the pinned AGENTS-shape.md: two sentences say a kept Makefile holds the shape's block back, and leave out a kept makefile or GNUmakefile, which GNU make reads first #1048, lane 4), does not touch or mention adopt_makefile_block; grep of its diff and body finds nothing.
  • Fix: before landing, add a box or a comment on shape_materialize.py and the pinned AGENTS-shape.md: two sentences say a kept Makefile holds the shape's block back, and leave out a kept makefile or GNUmakefile, which GNU make reads first #1048 (or open a new issue), and have the body say where the item is recorded.
• S2: the body's "Merge with main" section is stale.
  • It says main is at 6da757cb and that main changed neither README.md nor the handbook.
  • Main is now 823624d9. Its 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 added 7 README lines (plus tests/readme-cap.d/915.txt +7) and moved six "Starting a project" handbook markers.
  • Fix: at update-branch, restate the section with the numbers above (README 1489 = cap 1489, adopt marker unchanged, gates green).

NIT

• NIT-1: README.md:817-818. The body says "none with a meaning lost", but the word "honest" is gone. Either soften the body's claim or leave the text as it is.
• NIT-2: adopt-project.py:3634-3636, and the older README.md:814-816 clause. Both leave out the disk that ignores case: there a kept makefile (or MAKEFILE, or the directory makefile/) is the Makefile path, and place writes the shape's copy to shape/Makefile. The follow-up line itself says so. Optional fix: "(on a disk that ignores case, any name that folds to it)".
• NIT-3: tests/test_adopt_make_reads_first.py:145-147 and :183-186.
  • The row pins a line that is not true for a directory: "GNU make at the root reads the source's makefile … until the two are merged". In fact make stops with "Is a directory".
  • The comment at :134-139 records that the case is contrived, so the row works as a crash guard.
  • Optional: the docstring's "as the one GNU make reads" could read "as the one the line says GNU make reads".

Body-claim table

Claim	Measured	Verdict
Closes #1061 is the only closing keyword	closingIssuesReferences = [1061]; Sourcery's "Bug Fixes:" heading names no issue	true
R10 left every test passing on main	base: 121 passed (33 + 34 + 54) both unmutated and under R10	true
folded is True for makefile/; without rstrip, twins[0] raises	head R10 gives IndexError: list index out of range at adopt-project.py:3766	true
GNU make 4.3: makefile: Is a directory.	probe output above	true
README before/after quotes; 12 lines; 1482 = 1422 + 60	head: 1482 lines, 10 cap files; the paragraph diff is 12/12	true at head (S2 for the current main)
Marker becomes a7154cc3…	recomputed	true
Docstring (c) quote	matches the diff	true (NIT-2)
Mutant table: R10 / filter / element each 1 failed, 33 passed	same results; element mutant names `makefile/`	true
sha256 e3f38a53…79f5c before and after each	same	true
33 tests on main, 34 here	collected 33 (base) and 34	true
122 passed (34, 34, 54); 584 passed; 445 passed, 3 skipped	the same numbers on the 823624d9 merge	true
Main at 6da757cb touched neither README nor handbook	was true; main has moved since	stale (S2)
adopt_makefile_block docstring left to #1048	#1048 and #1105 do not hold it	not held (S1)
Sonnet trailer	present on both commits; correct, not flagged	—

Mutants: 7 of 8 killed on head

• Writer's three, re-measured: 3 of 3 killed. R10 (both halves), R10f (filter only) and R10e (element only) are each killed only by [makefile-directory]. Each survives on base (33 passed), so the new row is the sole killer.
• My five: 4 killed, 1 survivor.
  • M4: _root_keeps without the directory form. Killed only by the new row; survives on base.
  • M5: first without the directory form. Killed only by the new row; survives on base.
  • M16: folded without the directory form. Killed only by the new row; survives on base.
  • M7: twins[0].lower(). Killed by [MAKEFILE] on head and on base, not by the new row.
  • M21, the survivor: twins sorted reverse=True. It passes 34 of 34 and 122 of 122 on head. It changes nothing in any row because no row keeps two names that differ only in case. That case is contrived and outside adopt-project.py, README.md and tests: three follow-ups of PR #1046 (#977) from its review: a kept makefile/ row no test asks (mutant R10), README's make sentence that leaves out a kept GNUmakefile or makefile, and an older CONTRACTS_DIR docstring #1061's scope; it needs no fix.

Unfinished checks

None. All five checks in the brief were run.

Files

Everything is in /workspace/projects/openRepoShape-worktrees/_lane1-scratch/r1123/:

• runpt.sh, bin/gh (the stub) and ghcfg/
• merged/, head/ and base/ (the scratch clones)
• mut/ (the mutants and batch.log)
• doctor-shards.log
• probes/ (the minimal probe, and probe_adopt_make.py with its adopt-150041/ output)

No GitHub write, commit to any branch, push, rm or git config was made.

Lane: openreposhape-1 (openRepoShape-1)

[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 6 days and 1 hour by commenting @sourcery-ai review. Upgrade to get a review now.