[brettheap]

Lane: openreposhape-1 (openRepoShape-1)
Claim: #906 (comment)

A v1.2.0 draft, authored on the v1.1.1 release commit 50178305; this body is for head 369f2781, one fix round on 10f25e4b after lane 1's review r906, which found the first commit not ready. Lane 3 filed #906 from its triage of #457 (L2-72, L2-73, L1-91, L1-93 and L1-75): five printed sentences that say what the run does not do. It changes adopt-project.py, scripts/shape_materialize.py and five test files, one of them new (tests/test_adopt_printed_sentences.py).

What

1. L2-72, the Makefile follow-up. follow_ups_for said "the root Makefile wires CONTRACTS_DIR" even where the root keeps a Makefile of the source's own. Then the shape's goes beside it as shape/Makefile with the block, and the root wires nothing. Now it says "the shape's Makefile wires ...; but the source keeps a Makefile of its own at the root, so that block waits in shape/Makefile until the two are merged, and the run adds none of it to the root's Makefile", as Pinned shape copies: one bump, so AGENTS-shape.md is true of every root, the scaffold's chain WARNING offers only its own sources and spells --pin-source, the root's not-used note spells it too, and THE LOCKSTEP RULE's bump runs (#610) #634 words it for AGENTS-shape.md. A new _root_keeps is the one reading, shared with _predict_collisions. Otherwise the line is as it was.
2. L2-73, the spec leg's own path. contracts_from_code_leg takes the plan's follow-ups. Where one says a file must "read across the assembly root" (holds_a_read_across), check's mount the legs at X/ and Y/ and the split message's mounted back here at X/ and Y/ end ", so from the code leg the spec leg is ../spec/", plus " and the spec leg's contracts/ is ../spec/contracts/" where contracts/ is there too. With no read-across line they are as before.
3. L1-91, where execute stops. The finding no longer says "would stop there". For a refused store or copy it says execute would stop "no later than committing the split, and sooner where a step before it meets the same rule: extracting or seeding a leg, or mounting the legs, where the rule reaches the .gitmodules it writes"; for a refused checkout, "at its first clone of the source" (STOPS_AT_THE_SPLIT, STOPS_AT_A_CLONE).
4. L1-93, what a link target names. Two sentences said "a path names no attribute", which holds only for a link target with no space, tab or carriage return: git reads the target as one line of rules, and separates its fields on all three.
   • _kept_nested_attributes's docstring says so. The code was right already: it asks about every kept link.
   • scripts/shape_materialize.py's _attributes_link_follow_up, the printed sentence Tracking: adopt-project.py, converting an existing repository in place #457's L1-93 names, now says a checkout "reads only the link's own text, the path it leads to, as one line of rules, which names an attribute only where that text holds a space, a tab or a carriage return, so, for a link to a path, no line-ending rule reaches the pinned copies outside it". _append_eol_block's docstring and a comment in adopt-project.py say the same.
5. L1-75, visibility. Under --local-remote-dir, WHAT WILL HAPPEN prints create <Project>-spec and <Project>-code with no (private), since execute makes bare repositories. Against GitHub the line is unchanged.

Why

Measured on 50178305, git 2.43, Linux:

• L2-72: after a real execute --local-remote-dir of a source with its own root Makefile, make contracts-dir at the root printed No rule to make target. CONTRACTS_DIR was only in shape/Makefile.
• L2-73: the issue says v1.1.0 printed ../spec/specs/. It did not: v1.0.1 did, and adopt-project.py: after the hand edit of legs.spec_path or legs.code_path it asks for, the read-across follow-up and the contracts/ rule's reason still name the plan-time paths #600 took the path out of the follow-up. The tests follow ../spec/specs/001-feature/spec.md from the code leg of a recursive clone and reach the file.
• L1-91: with _refuse_what_check_finds patched out, core.safecrlf=true over a kept CRLF file stops execute at REFUSED committing the split; * working-tree-encoding=UTF-16LE with .gitattributes exempted, at REFUSED mounting the legs (failed to encode '.gitmodules'); a failing smudge filter, at REFUSED extracting the spec leg; and, with the code leg seeded (src/ and .github/ answered root) under core.autocrlf=true and core.safecrlf=true, at REFUSED seeding the code leg, where _seed_leg's own git add -A meets the rule before the split does.
• L1-93, nested: a nested .github/.gitattributes link to config/attributes or docs/read me.md left the workflow copy LF; to *.yml eol=crlf, with a space, a tab or a carriage return between the fields, it wrote CRLF.
• L1-93, root: clones of a source whose root .gitattributes links to config/attributes or docs/read me.md left a committed-LF notes.txt LF; links to * eol=crlf, with a space, a tab or a carriage return, wrote it CRLF. A test holds each.

Tests

tests/test_adopt_printed_sentences.py, 54 tests, a group for each item. OWN_MAKEFILE_FOLLOW_UP sits beside MAKEFILE_FOLLOW_UP in tests/test_adopt_contracts_dir.py; that file, test_adopt_leg_keys.py, test_adopt_reencoded_files.py and test_adopt_attributes_eol_block.py take the new text.

• Without the fix: with 50178305's adopt-project.py and shape_materialize.py put back (a scratch copy of the tree), 38 of the 54 fail, and one test each in test_adopt_attributes_eol_block.py and test_adopt_reencoded_files.py. The 16 that pass pin what the fix leaves alone: the Makefile line where the root keeps none (2), where execute really stops (4), and what git does with a link target, nested (5) and at the root (5).
• Against the first commit (10f25e4b): 8 fail: the three finding rows that say where execute stops for a store (the seeded-leg row among them), the docstring test, the two kept-Makefile line tests, test_the_follow_up_for_a_linked_attributes_file_lists_the_lines_it_needs, and test_a_refusal_says_where_execute_stops_and_the_way_out.

Run with /usr/bin/python3 -m pytest, a stub gh first on PATH, a bogus GH_TOKEN, an empty GH_CONFIG_DIR, GIT_CONFIG_GLOBAL=/dev/null and GIT_SSH_COMMAND=false, on head 369f2781, one run per file:

• printed_sentences 54, attributes_eol_block 46, eol_block_through_links 13 (2 skipped), nested_attributes 79, contracts_dir 34, leg_keys 44, reencoded_files 53, agents_md_codes 47, cli_reference 23, repo_hygiene 78; adopt_e2e 27, adopt_plan 67 (1 skipped, SHAPE_MEDXEHR_CLONE unset), adopt_submodules 167; test_shape_doctor 445 (3 skipped, PowerShell, a Windows host only); test_scaffold_leg_path_collisions 104. All passed.
• Not re-run since 10f25e4b, where they passed, and none reads a sentence this round changed: plan_yaml_quoting 518, and the 13-file batch of 1088 passed, 2 skipped (among them leg_paths, literal_names, entry_paths, leg_path_collisions, execute_refusals, c_locale_bytes, plan_escapes, stdout_encoding, shape_advisory).

Known limits and follow-ups

• Follow-up adopt-project.py: a kept lower-case makefile or GNUmakefile still gets "the root Makefile wires CONTRACTS_DIR", and README.md's CONTRACTS_DIR sentence has no kept-Makefile case (follow-ups to #906) #977 (a): a kept lower-case makefile or GNUmakefile gets the old line, because _root_keeps compares names byte for byte, while GNU make reads that file before Makefile (r906's probe: make contracts-dir at the root has no rule for either name).
• Follow-up adopt-project.py: a kept lower-case makefile or GNUmakefile still gets "the root Makefile wires CONTRACTS_DIR", and README.md's CONTRACTS_DIR sentence has no kept-Makefile case (follow-ups to #906) #977 (b): README.md:810 says "the root Makefile it materializes exports CONTRACTS_DIR" without the kept-Makefile case. It is not edited here: its section, "Adopting an existing repository", is bound to the handbook (README_HEADING_TO_HANDBOOK_ID and HANDBOOK_READS["adopt"] in tests/test_repo_hygiene.py, marker at docs/handbook.html:1278), so an edit fails handbook_marker_problems until the handbook is re-read, which serializes across lanes. The issue holds the wording: "the shape's Makefile exports CONTRACTS_DIR, pointing at ...; it is the root's Makefile, or, where the source keeps a Makefile of its own, shape/Makefile, which holds the export until a person merges the two".
• A root .gitattributes link whose text holds a separator is read by git as a rule line, as measured above. check still treats every root link as giving no rule (attributes_link), so what its findings say for such a link is not measured here. The printed follow-up no longer claims it does.
• The L1-91 words are hedged ("no later than ... and sooner where ..."), because the stop depends on the rule.

Closes #906

🤖 Generated with Claude Code

Summary by Sourcery

Make adoption messages accurately describe generated files, cross-leg paths, execution failure points, attribute-link semantics, and local bare-repository visibility.

New Features:

• Clarify adoption output with the spec leg’s path, accurate Makefile ownership, precise refusal stopping points, and Git attribute-link behavior.
• Suppress repository visibility labels when local remote directories create bare repositories.

Bug Fixes:

• Correct printed guidance for sources that retain a root Makefile, read-across paths without a contracts directory, Git attribute links containing rule separators, and execution failures that occur before the split commit.

Enhancements:

• Centralize root-path retention detection and use plan follow-ups to determine when cross-leg paths should be displayed.

Tests:

• Add comprehensive coverage for the five corrected printed-sentence behaviors, including end-to-end adoption, refusal, path, attribute, and local repository cases.

[sourcery-ai]

Reviewer's Guide

Updates adopt-project.py’s printed guidance and documentation to reflect actual Makefile placement, cross-leg navigation, Git refusal stop points, nested attribute parsing, and local bare-repository visibility, with broad regression and end-to-end coverage in a new printed-sentences test module.

Sequence diagram for local adoption guidance and execution stop points

sequenceDiagram
    participant User
    participant Adopt as adopt-project.py
    participant Plan
    participant Git
    User->>Adopt: plan
    Adopt->>Plan: _plan_follow_ups
    Adopt->>Adopt: contracts_from_code_leg
    Adopt->>Adopt: _print_what_will_happen
    Adopt-->>User: Print leg paths and create repositories
    User->>Adopt: execute
    Adopt->>Git: clone source
    alt checkout refusal
        Git-->>Adopt: refusal
        Adopt-->>User: execute stops at its first clone of the source
    else extraction or mount refusal
        Adopt->>Git: extract or mount legs
        Git-->>Adopt: refusal
        Adopt-->>User: execute stops before committing the split
    else no refusal
        Adopt->>Git: commit split
        Git-->>Adopt: success
    end

Loading

Flow diagram for adopt-project guidance generation

flowchart TD
    Plan[Plan follow-ups and leg paths] --> Makefile[follow_ups_for]
    Plan --> Mounts[contracts_from_code_leg]
    Plan --> Refusals[_reencoded_files_findings]
    Plan --> Visibility[_print_what_will_happen]
    Makefile --> RootCheck[_root_keeps]
    RootCheck --> MakefileText[Makefile placement guidance]
    Mounts --> ReadAcross[holds_a_read_across]
    ReadAcross --> MountText[Spec-leg path guidance]
    Refusals --> StopText[execute stop-point guidance]
    Visibility --> LocalText[Local bare-repository visibility]
    MakefileText --> Output[Printed adoption guidance]
    MountText --> Output
    StopText --> Output
    LocalText --> Output

Loading

File-Level Changes

Change	Details	Files
Make adoption output accurately describe Makefile placement and cross-leg paths.	Detect when the source keeps its own root Makefile and explain that the generated block remains in shape/Makefile until merge. Derive and print the spec leg’s path for read-across follow-ups, optionally alongside its contracts path. Share root-preservation logic between collision prediction and follow-up generation.	adopt-project.py tests/test_adopt_contracts_dir.py tests/test_adopt_leg_keys.py tests/test_adopt_printed_sentences.py
Clarify execution stopping points for Git re-encoding refusals.	Add explicit stop-location metadata for checkout, store, and copy refusals. Report that execution may stop during extraction or mounting, rather than implying it always stops at the refused final step. Add unit and execution-level coverage for clone, mount, and split-commit scenarios.	adopt-project.py tests/test_adopt_reencoded_files.py tests/test_adopt_printed_sentences.py
Correct adoption visibility output for local bare repositories.	Suppress plan visibility in WHAT WILL HAPPEN when --local-remote-dir creates bare repositories. Retain visibility output for GitHub-backed repository creation. Add coverage across private, public, and internal plan visibility values.	adopt-project.py tests/test_adopt_printed_sentences.py
Make nested attributes documentation match Git’s parsing behavior.	Document that link targets without whitespace are patterns with no attributes, while whitespace separates patterns from attributes. Add regression coverage for path targets, space-separated rules, and tab-separated rules.	adopt-project.py tests/test_adopt_printed_sentences.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#906	Make the Makefile follow-up describe where the contracts block actually waits when the source keeps its own root Makefile.	✅
#906	Print the spec leg’s path from the code leg beside the mounts whenever the plan has a read-across follow-up, while retaining the contracts-specific path where applicable.	✅
#906	Correct the printed finding about where execution stops, narrow the link-target docstring claim, and omit visibility from WHAT WILL HAPPEN for local bare repositories.	✅

Possibly linked issues

• adopt-project.py: five printed sentences say what the run does not do: the Makefile follow-up beside a root Makefile, the contracts/-only read-across path, execute would stop there, a path names no attribute, and WHAT WILL HAPPEN under --local-remote-dir #906: The PR implements all five requested fixes: Makefile follow-up, read-across path, execution-stop wording, attribute docstring, and local-remote visibility.

---

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-18T18:31:12Z) Independent review of #964 at 10f25e4b, by lane 1's reviewer r906 (opus), who is not its writer: NOT READY. Of the five items, L2-72, L2-73 and L1-75 are met, and L1-91 and L1-93 are not yet true. Lane 1 fixes all of them here.

• MUST-1: the L1-91 sentence leaves out a step where execute stops. With the code leg seeded under core.autocrlf=true and core.safecrlf=true, execute stops at REFUSED seeding the code leg., which "extracting a leg, or mounting the legs" does not name. Fix: "extracting or seeding a leg, or mounting the legs", with a STOPS row for a seeded leg.
• MUST-2: the sentence Tracking: adopt-project.py, converting an existing repository in place #457's L1-93 names is the printed one, at scripts/shape_materialize.py:1004 (from adopt-project.py check: a kept or moved file other than .gitattributes whose blob git add would re-encode passes, and execute ends adopt-lost or dies mounting the legs after both legs are pushed #654), with its docstring at :870. The branch leaves it as it was. A root .gitattributes link whose target holds a separator writes CRLF, so "no line-ending rule reaches the pinned copies outside it" is false there. Fix: those two places and tests/test_adopt_attributes_eol_block.py:399 together.
• SHOULD-1: git's attribute parser also splits on a carriage return. A nested link to *.yml\reol=crlf, with no space and no tab, wrote CRLF (git 2.43). So "no space or tab" becomes "no space, tab or carriage return", with a row for it.
• Met, with mutants:
  • L2-73's path covers a prefix of the text that is not a prefix of a segment, case, a parent segment, and mounts that are not text.
  • L2-72 and L1-75.
  • 16 of 18 mutants are killed; the 2 that survive are equivalent.
• Tests: 325 passed over the changed files and the docs and codes files.
• Follow-ups, filed with the round:
  • a kept lower-case makefile or GNUmakefile still gets the old line;
  • README.md:810, whose section is bound to the handbook, with corrected wording.

Lane 1's writer f906 makes the round, then r906 re-checks the new head.

Lane: openreposhape-1 (openRepoShape-1)

[brettheap]

(lane openRepoShape-1, 2026-10-18T19:00:21Z) Re-check of #964 at 369f2781, by r906 (opus), who is not its writer: READY.

• MUST-1: execute's stops now name seeding: "extracting or seeding a leg, or mounting the legs ...". A STOPS row measures REFUSED seeding the code leg..
• MUST-2: scripts/shape_materialize.py's printed follow-up (:1003-1009) and its docstrings now say a link's text is read as rules. It names an attribute only where it holds a space, a tab or a carriage return. Five root-link rows measure this: the copy is CRLF only for the three separator targets.
• SHOULD-1: "space, tab or carriage return" is git's full set of separators. Vertical tab, form feed, U+00A0 and line feed all leave the copy LF (git 2.43).
• The NITs are fixed.
• Tests: the four files that hold a changed sentence give 187 passed. M17b, M20, M21 and M22 are caught.
• Wording: the body's adopt-project.py: a kept lower-case makefile or GNUmakefile still gets "the root Makefile wires CONTRACTS_DIR", and README.md's CONTRACTS_DIR sentence has no kept-Makefile case (follow-ups to #906) #977 wording and adopt-project.py: a kept lower-case makefile or GNUmakefile still gets "the root Makefile wires CONTRACTS_DIR", and README.md's CONTRACTS_DIR sentence has no kept-Makefile case (follow-ups to #906) #977's own are corrected, as r906 asked.
• Optional NITs:
  • "As one line of rules": a target with a line feed is read as several lines. The claim about attributes still holds.
  • "For a link to a path": a path can itself hold a space.

#964 takes its turn once its tests are green at 369f2781, gated over main as it then stands. An explicit squash message replaces the first commit's WIP text.

Lane: openreposhape-1 (openRepoShape-1)

[sonarqubecloud]

Quality Gate passed

Issues
2 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 2 days and 7 hours by commenting @sourcery-ai review. Upgrade to get a review now.