[brettheap]

Lane: openreposhape-4 (openRepoShape-4)
Claim: #547 (comment)

What changed and why

Both lines are #460's, in shape-doctor.py's pin_restore.

L2-8. Since #496 (#485), every copy conflicted beside the shape pin went to a person to merge by hand. That included the copies two update-shape.py apply runs to different targets wrote, which neither side had edited. A hand merge that kept both sides of a hunk, then --accept-local, pinned a stale line as the project's own edit.

• taken_with_the_pin reads each side's stage of contracts/shape-pin.yaml through check_pin (pin_at(..., whole=True)), for the commit it names and its files: rows.
• A side of a conflicted copy is proved unedited where three things hold:
  • that side's pin has a row for the copy;
  • the copy's stage is byte for byte the standard's own file at THAT side's commit;
  • the two stages hold ONE regular-file mode, 100644 or 100755 (one_regular_mode, fix round 1).
• The standard's file is mapped by update-shape.py's own source_for, so it is the file check compares. It is read by git show from the checkout the doctor runs from.
• That checkout is never read when it is a partial clone (partial_clone, fix round 1). There a read would fetch the blob from the promisor remote.
• A copy proved on both sides is named beside the pin in the one NEXT, git -C <root> checkout --ours -- <pin> <copies>, so the copy taken matches the pin kept.
• detail["taken_with_the_pin"] lists the copies taken. The why names them as taken whole, and why, beside what it still gives a person.

unreadable_next is touched too, by four lines. The manifest kinds row prints the same NEXT for the same conflicted pin, through unreadable_next.

• While the shape pin does not read, nothing calls a copy a copy. So a copy under contracts/ that the NEXT now takes whole came out "project" in that row's restore ("git not asked") while its NEXT overwrote the file. That copy is the naming copy, the one a root keeps there, and the issue names it.
• That is the defect shape-doctor.py: with contracts/shape-pin.yaml and a pinned copy both conflicted, the NEXT takes the taken side's copies whole, so pasting it drops a person's --accept-local edit to the copy and the doctor then says COMPLIANT #485 fixed for a copy left to a person.
• Now a copy the NEXT takes is "unmerged", as a copy left to a person is, and the row's detail carries the same taken_with_the_pin as the shape currency row's.
• Test (h) holds it. Without the change, (h) fails.

L2-9. A slip amended into bump-leg.py's own commit leaves the commit before it holding the leg pin for the OLD leg commit. The committed restore puts that pin back, and once it is committed the doctor said DRIFTED, with nothing about the closing step.

• The NEXT is unchanged.
• gitlink_left_behind adds to its why, where the pin put back names another commit than the root's gitlink for that leg: both commits, and "commit it, then run the bump-leg.py line the pins row names", with which line keeps the move and which undoes it.
• The gitlink is read by recorded_gitlink (the index, then HEAD), as the pins row reads it.

Every addition is in why, never in a NEXT (#548's rule).

Fix round 1 (R586's review at 5248e70), in 2ca4044:

• F1, the mode. A copy whose executable bit the project changed on one side was taken whole as --ours. That dropped the other side's mode, while the why said neither side held an edit.
  • pin_restore now keeps each stage's mode from the ls-files -u -z listing it already reads.
  • taken_with_the_pin proves a copy only where the stages the two sides hold agree on one regular-file mode.
  • A side with no stage is left to the blob read, which proves nothing. So each reason has its own check, and each check its own test.
• F5, no fetch (R586's O1, the coordinator's decision). Where the standard's checkout is a partial clone, pin_restore proves nothing, every copy stays a person's, and the why says the checkout is a partial clone, so nothing was read from it.
  • The check reads only config: extensions.partialclone or remote.*.promisor.
  • update-shape.py's shared Upstream.blob is untouched. The shape currency row's older reach on a clean root goes on Tracking: shape-doctor.py, reporting a repository's compliance #460's checklist.
• N1. taken_with_the_pin returns at once when there is no copy to prove.
• F2, F3, F4. New tests for a delete/modify conflict and for a side whose pin has no row for the copy. The three composite asserts SonarCloud reported (S9073) are split.

Brett's ruling

"Prove and take" (Brett Heap, 2026-10-14T23:54:30Z), on #547 L2-8:

• The proof: each side's stage is byte-identical to the standard's own file at the commit THAT side's pin names.
• Both sides proved: the copy is pure tool output and is taken WHOLE, as the copy that matches the pin the restore keeps. It is not sent to a person.
• Anything not proved stays the hand merge, exactly as today.
• The why names the copies taken and the copies left. The NEXT stays ONE command.
• The standard's files come from the checkout the doctor runs from: "Never fetch, clone or touch the network. If the commit is absent, the copy is unproved."

Tests

New tests/test_doctor_pin_restore_merges.py, 16 tests. Every state is real git: the standard moved on by real commits, the project re-pinned by the real apply, a real merge, and the root under a directory whose name holds a blank and an apostrophe. Every NEXT is run as the reader's shell reads it.

• (a) both sides pure: both copies are taken whole with the pin, and the root is COMPLIANT once project.yaml is merged and the merge committed;
• (b) one side edited, parametrized over each side: a hand merge;
• (c) the same merge as (a), asked of a checkout short of one side's commit or of both: a hand merge;
• (d) a path the standard lacks at the commit one side's pin names: a hand merge, though that side's stage is the standard's file at another commit;
• (e) one copy taken and one left, and the why names both;
• (f) L2-9: the slip amended into the bump gives the sentence; then the NEXT, a commit, and the pins row's keep-the-gitlink line end COMPLIANT. In the control, the slip is a commit of its own, and nothing is added;
• (g) the NEXT that takes copies, run by sh -c (WINDOWS_SKIP);
• (h) the naming copy, taken whole: unmerged in the manifest kinds row's restore, and listed in taken_with_the_pin by both rows;
• (i) the Makefile made executable on one side, parametrized over each side: left to a person, and bootstrap.py still taken.
  • The x bit is set in the INDEX (update-index --chmod=+x), which is the same state on every system.
  • Clearing bootstrap.py's bit would not be: Windows commits it 100644.
• (j) a delete/modify conflict: the Makefile, at stages 1 and 2, left to a person and still unmerged after the NEXT;
• (k) the other side's pin restaged without the Makefile's files: row (plumbing, bytes on stdin): the Makefile left, and bootstrap.py still taken;
• (l) a --filter=blob:none clone of the standard: every copy left, the why's sentence, and C2's two blobs still missing afterwards. rev-list --objects --missing=print checks that, and it never fetches.

Targeted set, Linux, run with test identities and the frvenv on PATH, over 2ca4044's bytes (sha256 of every file checked against the head's blobs):

• Files: the new file, test_shape_doctor.py, test_doctor_next_is_a_command.py, test_doctor_unfinished_merge.py, test_bump_leg.py, test_doctor_gitlink_repairs.py and test_repo_hygiene.py.
• Result: 576 passed, 4 skipped, exit 0, in 12 min 15 s.
• Skips (-rs):
  • 3 at test_shape_doctor.py:9227: "the PowerShell line is printed, and powershell.exe exists, only on a Windows host";
  • 1 at test_bump_leg.py:693: "needs a disk that ignores case (macOS, Windows)".
• On the predicted merge with main dd3f23a (update-shape.py: a files: or shape: header with a trailing comment is rewritten and keeps it, --branch is judged the same from any directory, and apply's messages say what is true (#437, #431, #535) #558, bootstrap.py: a leg detached off the pin is left where it is and said, so a commit made there is no longer stranded when its branch is already at the pin, the not moving an existing branch line names where the checkout is, and bump-leg.py and AGENTS-shape.md say "or says why not" (#533) #556 and openRepoShape --doctor says it writes nothing into the repository but a --placement-plan file you name, keeps its clone for the NEXT lines that name it, shows its synopsis description again, and refuses a second --placement-plan or a second path (#546) #580 in it), the new file: 16 passed.

Mutants, run against the new file at 2ca4044's bytes (R586's runner, copied):

mutant	result
M1 take whole without the proof	killed: 10 failed
M2a prove only the ours side	killed: 4 failed
M2b prove only the theirs side	killed: 3 failed
M3a compare each side against the other side's pin	killed: 8 failed
M3b compare both sides against the kept pin	killed: 8 failed
M4 drop L2-9's sentence	killed: 1 failed (f, amended)
M5 drop the unreadable_next change	killed: 1 failed (h)
R1 swap the stages	killed: 8 failed
R2 drop the files: row requirement	killed: 1 failed (k), where it survived at 5248e70
R3 a missing stage counts as proved	killed: 1 failed (j), where it survived at 5248e70
R4 one proved copy takes them all	killed: 5 failed
R5 a read the standard cannot answer counts as proved	killed: 3 failed (c ×2, d)
F1 drop the mode check	killed: 2 failed (i ×2)
F5 drop the partial-clone check	killed: 1 failed (l)

No existing assertion changed outside the new file.

What stays a hand merge

Exactly what did before, for any copy not proved on BOTH sides:

• a side whose stage differs from the standard's file at its pin's commit, or is missing (a delete/modify conflict);
• a mode the two sides disagree on;
• a side's pin that does not read, or has no files: row for the copy;
• a pinned commit the standard's checkout the doctor runs from does not hold;
• a path the standard does not have at that commit;
• any read that fails.

And every conflicted copy where the standard's checkout is a partial clone. There, a read can fetch, so nothing is read, and the why says so.

None of these proves that the copy holds no edit of the project. Taking such a copy whole is the loss #485 fixed: a copy kept by --accept-local on one side, dropped with the hunks git merged cleanly beside it. The manifest and README.md stay a person's, as before (#267).

Shared files

What this changes in shape-doctor.py:

• pin_restore (its ls-files -u listing now keeps each stage's mode);
• pin_at, which gains a whole read used only by pin_restore's new helper;
• the new helpers taken_with_the_pin, as_the_standard_wrote_it, one_regular_mode, partial_clone and gitlink_left_behind, and the constants REGULAR_FILE_MODES and PARTIAL_CLONE_WHY. Only pin_restore uses them;
• four lines and one docstring sentence of unreadable_next (above).

git merge-tree --write-tree of 2ca4044 against each head, every head re-read by git ls-remote at 12:41Z and again before the push:

ref	head	result
origin/main (#580 landed as dd3f23a)	dd3f23a	clean, tree 58f85167
origin/fix/doctor-validator-verdicts (#557)	65b1189	clean, tree 8d69bbdd
origin/fix/doctor-next-detached-commits (#559)	66a9353	clean, tree 0da21408
origin/l3-548-manifest-kinds (#555)	c04ff8a	clean, tree 0e4532ec
l3-546-doctor-writes-wording (#580)	(landed; branch deleted)	in main above
fix/posix-paste-lines (P9)	not pushed	—

• source_for, check_pin, root_kind and Upstream are byte-identical in update-shape.py between b4c1f50 and dd3f23a. The proof reads the standard through them, so main's update-shape.py changes do not move it.

Out of scope

• The v1.0.0 release notes (docs/release-notes/v1.0.0.md:512-513) list L2-8 and L2-9 as known limits. This PR lifts both, so the v1.1.0 notes should drop them. This PR does not edit the v1.0.0 notes.
• R586's O2 is left as it was: a conflicted copy the KEPT side's pin has no row for is neither taken nor named in the why, as on main.
• R586's O3 is left as it was: the NEXT's pathspecs are not --literal-pathspecs; today's copy names hold no glob characters.
• The shape currency row's lazy fetch from a partial-clone standard on a clean root is older than this PR. It goes on Tracking: shape-doctor.py, reporting a repository's compliance #460's checklist.

Closes #547

🤖 Generated with Claude Code

Summary by Sourcery

Safely resolve provably tool-generated shape-copy conflicts and provide complete recovery guidance for restored leg pins.

New Features:

• Automatically take conflicted shape copies whole with the pin when both sides are proven byte-identical to the standard’s files at their respective pinned commits.
• Report the same taken-copy resolution in manifest-kind diagnostics and include guidance for leg pins restored ahead of their recorded gitlinks.

Bug Fixes:

• Prevent unedited tool-generated copies from being incorrectly sent to manual merge, while keeping edited, mode-conflicted, unreadable, missing, and partial-clone cases manual.
• Clarify the follow-up required when restoring a leg pin whose commit differs from the root gitlink.

Enhancements:

• Include file modes and partial-clone safety in copy verification, avoiding network-fetching reads and preserving executable-bit correctness.

Tests:

• Add comprehensive integration coverage for pure, edited, missing, deleted, mode-conflicted, partially cloned, and incompletely pinned copies, plus leg-pin restoration and shell-executed NEXT commands.

[sourcery-ai]

Reviewer's Guide

This PR makes shape-pin conflict restoration safely take only proven tool-generated copies alongside the pin, keeps all uncertain copies for manual merging, and adds actionable guidance for leg pins restored from before their bump; extensive real-git tests validate behavior, diagnostics, and generated commands.

Sequence diagram for safely restoring conflicted shape copies

sequenceDiagram
    participant Doctor as shape-doctor.py
    participant Git as Git index
    participant Pin as contracts/shape-pin.yaml
    participant Standard as Standard checkout

    Doctor->>Pin: pin_at(:2, whole=True)
    Pin-->>Doctor: commit and files rows
    Doctor->>Pin: pin_at(:3, whole=True)
    Pin-->>Doctor: commit and files rows
    Doctor->>Git: Read stage 2 and stage 3 copy blobs
    Git-->>Doctor: Conflicted copy contents
    Doctor->>Standard: source_for(copy, commit)
    Standard-->>Doctor: Standard blob at each side's commit
    alt Both stages match their pinned standard blobs
        Doctor->>Git: checkout --ours -- pin copy
        Doctor-->>Doctor: Record taken_with_the_pin
    else Any proof fails
        Doctor-->>Doctor: Leave copy for manual merge
    end

Loading

Sequence diagram for restoring a leg pin left behind by a bump

sequenceDiagram
    participant Doctor as shape-doctor.py
    participant History as Pin history
    participant Root as Root index or HEAD
    participant User
    Doctor->>History: Find newest readable pre-break leg pin
    History-->>Doctor: Restored pin commit
    Doctor->>Root: recorded_gitlink(leg path)
    Root-->>Doctor: Current root gitlink
    alt Pin commit differs from root gitlink
        Doctor-->>User: why: commit restored pin, then run the pins row's bump-leg.py line
        User->>User: Commit restored pin
        User->>User: Run bump-leg.py --to gitlink to keep move or --to pin commit to undo
    else Commits match
        Doctor-->>User: No additional gitlink guidance
    end

Loading

Flow diagram for proven-copy conflict restoration

flowchart TD
    A[Conflicted shape pin and copies] --> B[Read both side pins with pin_at]
    B --> C{Each side names the copy and its commit is readable?}
    C -- No --> F[Leave copy for a person]
    C -- Yes --> D[Compare each stage with standard blob via source_for]
    D --> E{Both sides match byte for byte?}
    E -- Yes --> G[Add copy to taken_with_the_pin]
    G --> H[One NEXT checks out pin and proven copies together]
    E -- No --> F

Loading

File-Level Changes

Change	Details	Files
Automatically takes conflicted shape copies whole only when both merge stages are proven byte-identical to the standard output referenced by their respective pins.	Extended pin reads to optionally return validated pin metadata and rows. Added proof helpers that compare staged copy blobs with source files resolved through update-shape.py mappings and each side's pinned commit. Updated the single restore NEXT and diagnostics to include proven copies while preserving hand merges for anything unproven. Added taken and person-merge details, including consistent handling in the manifest-kinds row.	shape-doctor.py tests/test_doctor_pin_restore_merges.py
Explains the follow-up required when restoring a leg pin from before a bump leaves it inconsistent with the root gitlink.	Compares the restored leg pin commit with the recorded index-or-HEAD gitlink. Adds actionable why text directing reviewers to commit the restored pin and run the pins row's bump-leg.py command, distinguishing keep versus undo. Leaves the generated NEXT unchanged and covers amended-bump and control histories.	shape-doctor.py tests/test_doctor_pin_restore_merges.py
Adds comprehensive real-git coverage for safe copy taking, fallback hand merges, shell execution, diagnostics, and leg-pin repair guidance.	Covers pure, edited, partially proven, missing-commit, and missing-source cases. Verifies quoting and execution of generated commands under paths containing spaces and apostrophes. Validates manifest-kinds parity and the amended-versus-separate bump behavior.	tests/test_doctor_pin_restore_merges.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#547	For a conflicted shape pin, take a conflicted copy whole alongside the restored pin when both sides’ stages match the standard’s file at the commit named by that side’s pin; leave copies that cannot be proved unedited for a hand merge.	✅
#547	When restoring a leg pin from before a breaking bump commit leaves the pin’s commit out of sync with the root’s gitlink, explain that the restored pin must be committed and direct the user to the pins row’s bump-leg.py command to keep or undo the move.	✅

Possibly linked issues

• Tracking: shape-doctor.py, reporting a repository's compliance #460: The PR fixes both issue lines: it takes copies proven unedited on both sides with the conflicted shape pin, and explains the follow-up for an outdated restored leg pin.

---

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.

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