[brettheap]

Lane: openreposhape-4 (openRepoShape-4)
Claim: #501 (comment) and #502 (comment)

Two audit findings in update-shape.py and the doctor's shape currency and pins rows, one commit each: 7b4024b (#501) and a5eb55d (#502). Both change which command a row names and what apply does with a pin row. Four rounds followed: 9899f25 (the review's three nits), ddb2df8 (the merge of main d41cc294, #402's squash, which brings #347 and #496 with it), 6943280 (the pins row under #347's link refusal) and c29b9b4 (the merge of main cf118ff7, #513).

#501 (audit auU-02): no NEXT line pre-fills --accept-local

What was wrong. For every locally-modified row, update-shape.py check put --accept-local <path> in the apply on its NEXT line, beside --yes. The doctor's shape currency row did the same in the apply after its check. AGENTS.md tells an assistant to run the command a row names. Pasted, that line re-pinned the project's own edit as the standard: exit 0, a green validate-pins.py and a COMPLIANT doctor. update-local-drift exists to ask the human whether the project keeps the edit, and it never fired.

What changes (commit 7b4024b). Brett Heap ruled on 2026-10-13: "Stop pre-filling it".

• check's NEXT and the doctor's shape currency row leave the flag out for a locally-modified row. Since shape-doctor.py: a NEXT is only the command, and the sentence that ended twenty-five of them after # is the row's why, on a WHY line of its own and "why" in --json, so a NEXT pasted into an interactive zsh -- which reads that # as a word -- no longer hands the comment to the command as arguments, runs what follows its ;, or runs the make bootstrap in its backticks, and the template validator's line is env PYTHONPATH=... python3 ... (#277) #402 that row's NEXT is the check alone and its why is the apply, which carries no flag. Pasted, the apply meets update-local-drift. Its remediation names the three exits: revert the edit, carry it upstream, or --accept-local on the human's word.
• check still names the flag in that row's detail, as the human's to give: "Whether the project keeps the edit is the human's decision: revert it, carry it upstream, or, on their word, apply --accept-local <path>". It already does this for both.
• apply_command loses the parameter that carried the paths. --yes stays in both lines, as ruled.
• The doctor's check_shape_currency loses its accept string with the flag. Its pin-only branch is main's byte for byte, and the apply in its why keeps shape-doctor.py: a NEXT is only the command, and the sentence that ended twenty-five of them after # is the row's why, on a WHY line of its own and "why" in --json, so a NEXT pasted into an interactive zsh -- which reads that # as a word -- no longer hands the comment to the command as arguments, runs what follows its ;, or runs the make bootstrap in its backticks, and the template validator's line is env PYTHONPATH=... python3 ... (#277) #402's form, the lane's trailer included, minus the flag.

#502 (audit auU-03): a merged-away collision copy's row goes

What was wrong. An in-place adoption pins the shape's copy of a name the source already uses under shape/. The adoption's follow-up then says to merge that copy into the original. If the merged copy is then removed, its pin row names a file that is not there. validate-pins.py said shape-copy-missing, and with it bootstrap.py and CI's validate went red. update-shape.py called the row copy-missing and refused update-conflict. That refusal's remediation said to re-run with --accept-local, which _refuse_conflicts never honours for that state. The doctor named that refused step. No tool removed the row: the only ways out were undoing the merge or the hand edit of the pin that AGENTS.md forbids.

What changes (commits a5eb55d, 9899f25 and 6943280). Brett Heap ruled "for auU-03, the pin row goes" (2026-10-12T23:16Z) and "check names, apply drops" (2026-10-13T11:02Z).

• A new verdict, merged-away. classify asks merged_into first. A row is merged-away when three things hold:
  • its path is under shape/;
  • nothing is at that path (lexists, so a dangling link or a directory still counts as something);
  • the root holds a file at the original path, shape/X -> X.
    The name is the act the follow-up asks for, spelled like the other states. It is not a conflict, and the upstream is not read for it.
• apply drops the row from the pin it rewrites (_repin). It prints dropped shape/X (merged into X and removed; its pin row goes, and nothing is copied), and its confirmation and commit message say so too. It needs no new flag: the yes that covers every other row covers this one. A dropped row is no longer a pinned path on the NEXT line, and update-rewrite-symlink no longer asks about a path nothing is written at.
• Every other missing copy stays copy-missing. That covers a pinned copy deleted anywhere else, and a shape/ copy whose original is gone too. update-conflict's remediation is now built per state (conflict_remediation). A copy-missing row is told to put the copy back from the project's own history, because --accept-local has no bytes to keep, and that this command never records the deletion of a copy the project still needs (it does record a merged-away row's). It names both ways back: git checkout HEAD -- <path> for a deletion not yet committed, the parent of the removing commit (git log -1 -- <path> names it) for a committed one (9899f25). both, upstream-removed and unmapped keep their old words (MERGE_BY_HAND).
• The doctor counts merged-away as drift and names it in the verdict (DRIFTED (2 merged-away)). Its shape currency row's reason counts a merged-away row where there is one (9899f25).
• The pins row names the same update-shape.py check the shape currency row names, as a single command. It does so only when every finding the gate reports is a merged-away row's shape-copy-missing, judged by the same merged_into, and only where check can read the root. A root that keeps its pin, the contracts directory above it or its manifest as a symlink is refused by check itself (update-shape.py: a pinned copy, contracts/shape-pin.yaml or the manifest kept as a symlink, or under one, is refused as update-rewrite-symlink before anything is written, and check calls such a copy copy-is-link, so apply no longer writes the standard's bytes at the link's end and reports a commit that does not hold them (#286) #347's update-rewrite-symlink), so the row keeps the gate there and the shape currency row says to replace the link (6943280). Any other finding keeps the gate as the NEXT.
• The adoption's follow-up (collision_follow_up in scripts/shape_materialize.py) tells a pinned copy's follow-up what happens to its row: "Then remove shape/X: update-shape.py check reports its pin row merged-away, and apply drops the row." A rendered file such as shape/README.md has no row and is told nothing about one.

Tests

New and changed tests:

• tests/test_update_shape_merged_away.py (new) builds one real adoption out of the standard that the doctor tests build, and has seven tests, nine items:
  • test_a_merged_away_copys_row_goes_and_the_project_is_green_again is the issue's own flow, end to end. The gates go red. check and both doctor rows name the step. check's NEXT is pasted, and the two rows go with nothing else in the pin moved. Then bootstrap.py and validate-pins.py are green, the doctor is COMPLIANT, and there is nothing left to do.
  • test_a_shape_copy_removed_with_its_original_stays_copy_missing: the refusal, with or without --accept-local, names the copy's own remedy.
  • test_a_pinned_copy_deleted_elsewhere_stays_copy_missing: next to a merged-away row, it is still refused, and the pins row keeps the gate.
  • test_a_deletion_not_yet_committed_comes_back_from_head (9899f25): after rm and a refused apply, the remediation's git checkout HEAD -- <path>, run as named, puts the copy back, check has nothing to do, and the refused apply wrote nothing.
  • test_the_currency_rows_counts_name_a_merged_away_row (9899f25): the shape currency row's counts sum to its rows where a merged-away row is one of them.
  • test_the_pins_row_keeps_the_gate_while_check_refuses_a_linked_record (6943280), with the pin, the contracts directory and the manifest each kept as a committed link: both copies merged away, check refused update-rewrite-symlink, the pins row keeps the gate and says nothing of merged-away, and the shape currency row names replacing the link. With the link replaced and committed, the pins row names check.
  • test_the_plans_follow_up_says_what_happens_to_the_row.
• tests/test_update_shape.py::test_checks_next_leaves_a_local_edit_to_the_human (new) pastes check's NEXT over a committed local edit. The paste is refused, the row's digest is unchanged, and the three exits are named. The row is re-pinned only once the person's flag is added.
• tests/test_shape_doctor.py:
  • test_an_edited_shape_copy_is_drift_and_names_update_shape used to require the flag on purpose. It now asserts that no line of the report carries it, and its docstring says why.
  • P10b (test_a_conflicted_copys_next_agrees_with_shape_currency_and_agents_md) pastes the shape currency apply as printed. It is refused update-local-drift, and it ends COMPLIANT once the person's --accept-local is added.
  • shape-doctor.py: a conflicted shape pin's NEXT takes the pin alone and gives a copy conflicted beside it to a person to merge by hand, so pasting it no longer drops an edit kept with --accept-local and then says COMPLIANT (#485) #496's helper re_pinned_from_the_merge follows that apply, as spelled, to its refusal before it adds the person's flag: update-local-drift with the update side's pin taken, update-conflict with the person's side's.
• tests/test_doctor_next_is_a_command.py (shape-doctor.py: a NEXT is only the command, and the sentence that ended twenty-five of them after # is the row's why, on a WHY line of its own and "why" in --json, so a NEXT pasted into an interactive zsh -- which reads that # as a word -- no longer hands the comment to the command as arguments, runs what follows its ;, or runs the make bootstrap in its backticks, and the template validator's line is env PYTHONPATH=... python3 ... (#277) #402's): _shape_currency_moved asserts --accept-local is absent from the row's why.
• tests/test_update_shape_next_quoting.py: the local-edit variant expects no flag. test_a_path_check_offers_to_accept_is_one_argument is deleted, because the path it quoted is no longer on that line.

Targeted run at c29b9b4, with git-filter-repo on PATH, over tests/test_repo_hygiene.py, test_agents_md_codes, test_cli_reference, test_update_shape_merged_away, test_update_shape, test_update_shape_rewrite_symlink, test_update_shape_next_quoting, test_shape_doctor, test_doctor_next_is_a_command, test_openreposhape_command and test_adopt_leg_path_collisions: 850 passed, 3 skipped, 0 failed. The three skips are the PowerShell tests at tests/test_shape_doctor.py:9118, which run on a Windows host only. The head before the last merge, 6943280, ran green on tests, tests-macos, tests-windows and SonarCloud. c29b9b4 is that head merged with main cf118ff7, and its one hand resolution is the handbook footer.

Mutants. Each mutant ran in a scratch checkout, with the tests of the commit named and the tools reverted, or, for the last, one line of them changed:

• update-shape.py check's NEXT, and the doctor's shape currency row that sends the reader to it, already carry --accept-local <path> for every locally edited shape copy, so pasting the command AGENTS.md says to run as named re-pins the project's edit as the standard: no refusal, no question to the human, a green validate-pins.py and a COMPLIANT doctor, though AGENTS.md says never to pass --accept-local and that keeping the edit is the human's decision #501 reverted (the tools at main 47b1e06c, the tests at 7b4024b): 8 fail, of the 52 in test_update_shape_next_quoting.py and the three tests named above. These are the new check test, the five local-edit quoting variants, the doctor drift test and P10b. The quoting variants fail on argv equality, because the reverted line still carries --accept-local <path>. The other three fail on assert '--accept-local' not in ....
• update-shape.py, validate-pins.py and shape-doctor.py: once an adopted root does its own follow-up "merge shape/.gitignore into .gitignore" and removes the merged copy, the copy's pin row is copy-missing, so the project's bootstrap.py and its validate check go red, apply refuses with a remedy (--accept-local) that is refused in the same words, and no tool removes the row, which leaves only undoing the merge or the hand edit of the pin that AGENTS.md forbids #502 reverted (the tools at 7b4024b, the tests at a5eb55d): all 4 merged-away tests fail. The rows read copy-missing where merged-away is expected, the refusal has the old remediation, and the follow-up lacks the row sentence.
• The nit round reverted (update-shape.py and shape-doctor.py at a5eb55d, the tests at 9899f25): the three new tests fail, each on the old sentence or the old count.
• The pins row's link question changed (one line of with_merged_away_rows, all else at c29b9b4): removed, all three link cases fail, each at assert 'merged_away' not in ...; asked of the pin alone, not the manifest, only manifest-at-a-link fails.

Docs

The docs are corrected in this PR, as Brett Heap ruled at 2026-10-13T11:30Z for each lane-4 fix. The branch holds main cf118ff7 (#513). README.md keeps its 1422 lines, its cap, and AGENTS.md its 490, its cap. docs/handbook.html has no cap and is 1943 lines against main's 1942, because its footer clause wraps onto one more.

• AGENTS.md:286-289, updating step 1: the verdict list adds merged-away ("a shape/ copy merged into its own file and removed: apply drops its row"). The line about a file with no row ends at "none of your business."; its clause "an adopted project merged some of them away on purpose" gave the line room.
• AGENTS.md:297, step 3: "No NEXT line passes it: apply refuses, and asks."
• README.md:1044: the verdict list adds "merged-away (below)".
• README.md:1069-1071: "Once a human merges one and removes it, check calls its row merged-away and apply drops the row. A file with no row is no shape copy; re-deriving the list would resurrect it."
• docs/handbook.html:
  • 1419-1420 and 1442 are the README's twins.
  • The footer at 1882-1883 records "the merged-away verdict, whose row apply drops, added (update-shape.py, validate-pins.py and shape-doctor.py: once an adopted root does its own follow-up "merge shape/.gitignore into .gitignore" and removes the merged copy, the copy's pin row is copy-missing, so the project's bootstrap.py and its validate check go red, apply refuses with a remedy (--accept-local) that is refused in the same words, and no tool removes the row, which leaves only undoing the merge or the hand edit of the pin that AGENTS.md forbids #502)", after adopt-project.py plan never compares --project (or --org) with the repository it adopts in place, so a source named billing-service is refused with a remediation that steers to --project BillingService, which plans and checks plan ok against acme/billing-service, and execute then acts on acme/BillingService: a raw git ls-remote failure when no such repository exists, and, when a different repository of that name does, both legs, the split branch, the pull request and the topic on that repository #499's clause, which is main's last.
  • 1885 names the new README blob ae817c5fdb324ff60440b959a15f3ad3b2a18b43.
• No --help text changed, so docs/cli.md stands. Its --accept-local line describes the flag, not a NEXT line.
• templates/*/AGENTS-shape.md is unchanged. It is a pinned copy, and nothing in it is false now. It does say "Never edit a file that has a row", next to a follow-up that says to remove shape/X. One sentence there would settle it, but that file is a copy every project pins.

Shared files

• shape-doctor.py: a NEXT is only the command, and the sentence that ended twenty-five of them after # is the row's why, on a WHY line of its own and "why" in --json, so a NEXT pasted into an interactive zsh -- which reads that # as a word -- no longer hands the comment to the command as arguments, runs what follows its ;, or runs the make bootstrap in its backticks, and the template validator's line is env PYTHONPATH=... python3 ... (#277) #402 (d41cc294, for shape-doctor.py: fifteen NEXT builders end the command with # <comment>, which a stock interactive zsh (macOS's default shell) does not read as a comment, so pasting the line hands the comment's words to the command as arguments, runs whatever follows a ;, and runs the make bootstrap the legs and members comments put in backticks, then exits 127 #277), update-shape.py: a pinned copy, contracts/shape-pin.yaml or the manifest kept as a symlink, or under one, is refused as update-rewrite-symlink before anything is written, and check calls such a copy copy-is-link, so apply no longer writes the standard's bytes at the link's end and reports a commit that does not hold them (#286) #347 (8cd7dbe5, for update-shape.py apply rewrites a pinned copy, contracts/shape-pin.yaml or the manifest THROUGH a symlink the root keeps at that path (Rollback.write opens it r+b), so the standard's bytes land at the link's end, outside the root if that is where it points, with exit 0, and --branch reports a commit holding a file that commit does not contain #286) and shape-doctor.py: a conflicted shape pin's NEXT takes the pin alone and gives a copy conflicted beside it to a person to merge by hand, so pasting it no longer drops an edit kept with --accept-local and then says COMPLIANT (#485) #496 (fc488548, for 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) are on main, and ddb2df8 merged them in. Where each met this PR:
  • shape-doctor.py: a NEXT is only the command, and the sentence that ended twenty-five of them after # is the row's why, on a WHY line of its own and "why" in --json, so a NEXT pasted into an interactive zsh -- which reads that # as a word -- no longer hands the comment to the command as arguments, runs what follows its ;, or runs the make bootstrap in its backticks, and the template validator's line is env PYTHONPATH=... python3 ... (#277) #402, check_shape_currency: its (command, why) return is kept, with update-shape.py check's NEXT, and the doctor's shape currency row that sends the reader to it, already carry --accept-local <path> for every locally edited shape copy, so pasting the command AGENTS.md says to run as named re-pins the project's edit as the standard: no refusal, no question to the human, a green validate-pins.py and a COMPLIANT doctor, though AGENTS.md says never to pass --accept-local and that keeping the edit is the human's decision #501's comment beside it and no accept string. The row's NEXT is the check, and its why is the apply without the flag.
  • shape-doctor.py: a NEXT is only the command, and the sentence that ended twenty-five of them after # is the row's why, on a WHY line of its own and "why" in --json, so a NEXT pasted into an interactive zsh -- which reads that # as a word -- no longer hands the comment to the command as arguments, runs what follows its ;, or runs the make bootstrap in its backticks, and the template validator's line is env PYTHONPATH=... python3 ... (#277) #402, tests/test_shape_doctor.py P10b: both PRs changed the same assertion line, and this PR had to, because that line asserted the flag update-shape.py check's NEXT, and the doctor's shape currency row that sends the reader to it, already carry --accept-local <path> for every locally edited shape copy, so pasting the command AGENTS.md says to run as named re-pins the project's edit as the standard: no refusal, no question to the human, a green validate-pins.py and a COMPLIANT doctor, though AGENTS.md says never to pass --accept-local and that keeping the edit is the human's decision #501 removes. It now asserts "--accept-local" not in currency["next"] + currency["why"].
  • shape-doctor.py: a NEXT is only the command, and the sentence that ended twenty-five of them after # is the row's why, on a WHY line of its own and "why" in --json, so a NEXT pasted into an interactive zsh -- which reads that # as a word -- no longer hands the comment to the command as arguments, runs what follows its ;, or runs the make bootstrap in its backticks, and the template validator's line is env PYTHONPATH=... python3 ... (#277) #402, tests/test_doctor_next_is_a_command.py: its case check_shape_currency-copies-moved asserted --accept-local <copy> in the row's why, which update-shape.py check's NEXT, and the doctor's shape currency row that sends the reader to it, already carry --accept-local <path> for every locally edited shape copy, so pasting the command AGENTS.md says to run as named re-pins the project's edit as the standard: no refusal, no question to the human, a green validate-pins.py and a COMPLIANT doctor, though AGENTS.md says never to pass --accept-local and that keeping the edit is the human's decision #501 removes. It asserts the flag's absence now. The file's guard against a # tail passes in full, 42 items: this PR's pins row NEXT is a single command.
  • update-shape.py: a pinned copy, contracts/shape-pin.yaml or the manifest kept as a symlink, or under one, is refused as update-rewrite-symlink before anything is written, and check calls such a copy copy-is-link, so apply no longer writes the standard's bytes at the link's end and reports a commit that does not hold them (#286) #347 refuses a pin, a manifest or a pinned copy kept as a symlink, or under one, as update-rewrite-symlink, and check calls such a copy copy-is-link. The merge exposed the interplay 6943280 fixes, in the pins row above. A merged-away row is not a path apply writes through, so _refuse_writes_through_a_link leaves it out.
  • shape-doctor.py: a conflicted shape pin's NEXT takes the pin alone and gives a copy conflicted beside it to a person to merge by hand, so pasting it no longer drops an edit kept with --accept-local and then says COMPLIANT (#485) #496's helper re_pinned_from_the_merge read --accept-local <copy> out of the shape currency row's apply when the update side's pin is taken, so two of its cases (test_a_copy_conflicted_with_the_shape_pin_is_left_to_a_person[the-update-side-ours] and test_a_makefile_conflicted_with_the_shape_pin_keeps_the_projects_target[the-update-side-ours]) failed on the merged tree with ValueError: '--accept-local' is not in list. After update-shape.py check's NEXT, and the doctor's shape currency row that sends the reader to it, already carry --accept-local <path> for every locally edited shape copy, so pasting the command AGENTS.md says to run as named re-pins the project's edit as the standard: no refusal, no question to the human, a green validate-pins.py and a COMPLIANT doctor, though AGENTS.md says never to pass --accept-local and that keeping the edit is the human's decision #501 the apply as spelled is refused, update-local-drift here, naming --accept-local <copy>, and moves nothing, so the helper follows it to the refusal and then adds the person's flag. Its sentence in the unmerged restore's why now says the shape currency row never names the flag and that the apply it names is refused, asking for it. The four parametrized cases pass.
• scaffold-project.py and family.py init: --reuse-empty-repo reuses a leg that is empty or whose one commit is the scaffold's own seed, and the ruleset hint offers that re-run, by an operator holding the bypass right, as its one exit, so a project a ruleset refused part-way is finished by one re-run, not refused scaffold-remote-exists for its own legs or sent to a pull request with no base (#462) #506 (for scaffold-project.py, family.py init: after a ruleset refuses the first push, neither exit RULESET_HINT offers can finish: the pull request has no base in the repository gh repo create left empty, and the scaffold's re-run is refused scaffold-remote-exists for its own two empty legs, so a ruleset-protected organisation cannot seed a new project; --reuse-empty-repo is to reuse empty legs, and the hint is to offer only that re-run #462), family.py: init refuses to land in the standard's checkout and names a runnable scripts/family.py, printed commands quote paths, and add, bump and remove refuse the tracking branch and print their branch's push (#488, #486, #487) #507 and openRepoShape --doctor: the installed form keeps the clone of the standard it ran from and names it on the report's last line, so a NEXT line pasted after the command has exited runs instead of dying with can't open file, and it hands --json and --placement-plan <file> on to shape-doctor.py instead of refusing them (#500) #510, which each conflicted with this branch at the handbook footer, have landed, and so have setup-project.py: the clone path <into>/<Project> is refused in step (3), before anything is created, when anything at all stands there, naming the path and telling a rehearsal's leftover clone apart as one to move or delete, and the plan names the clone path before the yes, so rehearsing and then running for real in the same folder - README's own order - no longer creates three repositories and then refuses with a hand clone that fails on the same directory (#498) #509, family Makefile: siblings, park and resume refuse by name when scripts/siblings.py is absent, and update-shape.py says the Makefile it copies calls it, so a holder updated without --add no longer fails on can't open file (#489) #503, adopt-project.py: check names, and execute refuses before the work directory is made, a plan whose source: or legs: is not a mapping or whose allow_empty_legs: or paths: is not a list of what plan writes, and asks the same first of a pins: that is not a list, so a number or a boolean in any of the four no longer ends both in a traceback and allow_empty_legs: code is no longer read as four legs (#386) #435 and scaffold-project.py: a leg path the project's own YAML reader would read back as another type (null, ~, true, False, 2026, 1.5) is refused before anything is created, under --dry-run alike, through the one definition adopt-project.py asks, so --spec-path 2026 no longer creates three repositories whose first bootstrap fails manifest-leg-path, and adopt-project.py execute no longer says adoption verified before that bootstrap fails (#225) #266, which merged cleanly. The footer is where the landings met this PR: c29b9b4's one hand resolution keeps main's clauses through adopt-project.py plan never compares --project (or --org) with the repository it adopts in place, so a source named billing-service is refused with a remediation that steers to --project BillingService, which plans and checks plan ok against acme/billing-service, and execute then acts on acme/BillingService: a raw git ls-remote failure when no such repository exists, and, when a different repository of that name does, both legs, the split branch, the pull request and the topic on that repository #499's, adds this PR's (#502) clause after them, and sets README.md blob to the merged README's.
• tests.yml and adopt-project.py: the Windows job installs git-filter-repo 2.47.0, so the adoption test files that skip without it run there, and a source that keeps its own root .gitattributes gets one marked block of /<copy> text eol=lf lines appended to it in the split, so a Windows clone writes the pinned copies at the root with the bytes the pin records; the verification counts that file as the source's bytes followed by exactly that block, and update-shape.py apply --add extends it (#471) #511 (open; tested at 91ed4a57) conflicts with this branch in docs/handbook.html, and only at the footer, as it does with main cf118ff7: the fix log line and the README blob line, which every docs PR rewrites. Whichever lands second takes a footer round.
• repo_shape.py, validate-pins.py, family.py: a refusal built without a remedy prints its REFUSED line alone, the assembly root's validate-pins.py still adds the lockstep remedy to its own, and add refuses a .gitmodules git cannot rea (#370) #494, adopt-project.py: check follows each symlink the plan keeps where the shape writes its files, and execute refuses one the shape cannot write through, or one it writes beneath that git checks out as a file, before any leg exists, so such a link no longer breaks the run after both legs are pushed or has the shape's files written outside the assembly (#183, #178) #504 and docs/release-notes/v1.0.0.md: the v1.0.0 release notes, a draft for Brett to amend before he tags, saying what 1.0 contains and promises, how to pin it by commit, what changed on the way grouped by the five tracking areas, and every known limit as the input that triggers it and what the person sees (#472) #473 (a draft) merge cleanly with this branch (git merge-tree at 1d9e8b2a, 64b2cc05 and 67360ccd). repo_shape.py, validate-pins.py, family.py: a refusal built without a remedy prints its REFUSED line alone, the assembly root's validate-pins.py still adds the lockstep remedy to its own, and add refuses a .gitmodules git cannot rea (#370) #494 changes shape-doctor.py and adopt-project.py: check follows each symlink the plan keeps where the shape writes its files, and execute refuses one the shape cannot write through, or one it writes beneath that git checks out as a file, before any leg exists, so such a link no longer breaks the run after both legs are pushed or has the shape's files written outside the assembly (#183, #178) #504 scripts/shape_materialize.py, both in other places.

Left as they were (for the v1.0.0 checklist)

• MERGE_BY_HAND still tells upstream-removed and unmapped rows to re-run with --accept-local, which _refuse_conflicts honours on both alone. This is the same defect update-shape.py, validate-pins.py and shape-doctor.py: once an adopted root does its own follow-up "merge shape/.gitignore into .gitignore" and removes the merged copy, the copy's pin row is copy-missing, so the project's bootstrap.py and its validate check go red, apply refuses with a remedy (--accept-local) that is refused in the same words, and no tool removes the row, which leaves only undoing the merge or the hand edit of the pin that AGENTS.md forbids #502 fixes for copy-missing, but neither ruling covered those two states.
• For a pinned copy deleted outside shape/, the doctor's shape currency NEXT still names check, whose apply refuses it. update-conflict now names the remedy.
• The pins row asks linked_record about the pin and the manifest alone, and the gate about shape-copy-missing. A pinned copy kept as a link beside merged-away rows (and, by the same reading, an upstream-removed or unmapped row beside them) is green to validate-pins.py, so the row still names check and says the apply it prints drops their rows. check prints REFUSAL AHEAD for the other row, and that apply is refused. Nothing is written. Keeping the gate while check's conflicts are non-empty would settle it.
• The shape currency row's counts name merged-away and the five original states alone, so a copy-is-link, copy-missing, upstream-removed, unmapped or already-at-target row is still a path under no count, as it was on main. That is outside update-shape.py, validate-pins.py and shape-doctor.py: once an adopted root does its own follow-up "merge shape/.gitignore into .gitignore" and removes the merged copy, the copy's pin row is copy-missing, so the project's bootstrap.py and its validate check go red, apply refuses with a remedy (--accept-local) that is refused in the same words, and no tool removes the row, which leaves only undoing the merge or the hand edit of the pin that AGENTS.md forbids #502.

Closes #501
Closes #502

🤖 Generated with Claude Code

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

[sourcery-ai]

Reviewer's Guide

The PR makes generated remediation commands safer by leaving local-edit acceptance to the human, and introduces an end-to-end merged-away state that removes stale pin rows for intentionally merged collision copies while preserving appropriate handling for other missing files.

Sequence diagram for human-controlled local drift acceptance

sequenceDiagram
    participant Human
    participant Check as update-shape.py check
    participant Apply as update-shape.py apply
    participant Drift as update-local-drift
    participant Pin as shape-pin.yaml

    Human->>Check: Run check on locally-modified row
    Check-->>Human: NEXT apply --yes&#59; detail names --accept-local
    Human->>Apply: Paste NEXT command
    Apply->>Drift: Refuse local drift
    Drift-->>Human: Choose revert, carry upstream, or accept locally
    Human->>Apply: Re-run with --accept-local path
    Apply->>Pin: Re-pin accepted local bytes

Loading

Flow diagram for dropping a merged-away collision pin row

flowchart TD
    A[shape/X pin row] --> B{shape/X is absent?}
    B -- No --> C[Keep normal classification]
    B -- Yes --> D{Root file X exists?}
    D -- No --> E[copy-missing]
    D -- Yes --> F[merged-away]
    F --> G[apply --yes]
    G --> H[Drop shape/X row from pin]
    G --> I[Copy nothing]
    H --> J[validate-pins.py green]

Loading

File-Level Changes

Change	Details	Files
Require explicit human consent before accepting locally modified shape copies.	Removed prefilled --accept-local flags from check and doctor-generated apply commands. Kept the flag in diagnostic remediation text and routed pasted commands through update-local-drift. Simplified apply_command and updated coverage for command quoting and refusal behavior.	update-shape.py shape-doctor.py AGENTS.md tests/test_update_shape.py tests/test_update_shape_next_quoting.py tests/test_shape_doctor.py
Add automatic cleanup for collision copies that were merged into their original and removed.	Added the merged-away classification for absent shape/ paths whose original root file remains. Excluded merged-away rows from rewritten pins without copying bytes, and reported the drop in output, confirmation, and commit messages. Preserved copy-missing for other deletions and added state-specific remediation. Updated doctor gate recommendations and drift reporting so eligible pin findings name the same update-shape.py check step.	update-shape.py shape-doctor.py tests/test_update_shape_merged_away.py
Document collision-copy row cleanup in adoption follow-ups and user guidance.	Added follow-up instructions explaining that removing a merged collision copy leads check to report merged-away and apply to drop its row. Documented the new verdict and the rule that NEXT commands do not pre-accept local edits. Updated the handbook change log and README blob reference.	scripts/shape_materialize.py AGENTS.md README.md docs/handbook.html

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#501	Ensure update-shape.py check and the doctor's shape currency NEXT command do not pre-fill --accept-local for locally modified shape copies, so running the command as printed reaches update-local-drift and asks the human to decide whether to keep the edit.	✅
#501	Keep the human's available choices clear while documenting that the flag is a human decision, not something a NEXT command supplies automatically.	✅
#502	Provide a supported way to remove the pin row for a merged-away shape/ collision copy, so the adopted project can complete its follow-up and return its pin validation and bootstrap gates to green.	✅
#502	Keep other missing pinned copies as copy-missing, with a remediation that does not direct users to retry with --accept-local when that option cannot resolve the state.	✅
#502	Make the adoption follow-up and doctor guidance identify the merged-away remedy, and document the new verdict and behavior.	✅

Possibly linked issues

• update-shape.py, validate-pins.py and shape-doctor.py: once an adopted root does its own follow-up "merge shape/.gitignore into .gitignore" and removes the merged copy, the copy's pin row is copy-missing, so the project's bootstrap.py and its validate check go red, apply refuses with a remedy (--accept-local) that is refused in the same words, and no tool removes the row, which leaves only undoing the merge or the hand edit of the pin that AGENTS.md forbids #502: The PR implements the issue’s remedy: check identifies merged-away copies and apply removes their pin rows.
• #auU-02: The PR removes --accept-local from check and doctor NEXT commands, so pasted apply commands trigger update-local-drift and ask the human.

---

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
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