Tracking: update-shape.py and bump-leg.py, keeping a project's shape copies and leg pins current

Lane: openreposhape-3 (openRepoShape-3)

The parent issue for one area of openRepoShape: keeping a project current: re-syncing its copied shape files (update-shape.py) and moving a leg's pin (bump-leg.py). Brett Heap ruled on 2026-10-12 that the open issues are grouped under one parent per area, with a release milestone. Every open issue in this area is a sub-issue here.

v1.0.0. The first release is "core flows, all OSes": every procedure in AGENTS.md works end to end for ordinary repositories on Linux, macOS and Windows. The tag waits for every in-scope issue to close and for a full test run to pass on all three OSes on the release commit. In this area, the sub-issues in the v1.0.0 milestone are:

update-shape.py: check's and apply's NEXT lines print the root path unquoted where landing_failed's and the rollback hand-fix lines quote it with shlex, so a root under a path with a space pastes as a different command, and none of them quotes for cmd.exe or PowerShell #325 (P2): check and apply NEXT lines print the root unquoted: a root under My Projects or OneDrive - Org pastes as another command.
make bootstrap, bump-leg.py and update-shape.py apply run the project's own validate-pins.py in the operator's environment, so for a project that pins a neutral product with no local checkout of it each one calls gh api repos/<org>/<product>/git/trees/<sha> with the operator's token, though bump-leg.py says "a project runs its own gate offline" and update-shape.py that "apply is otherwise offline": the three callers #297 named and left #411 (P2): Only a project that declares descent: bootstrap, bump-leg and apply call gh api with the operator token though README says offline. Docs fix.
update-shape.py apply --branch judges the pin, the manifest and the copies from the working tree but commits HEAD plus only the paths it wrote, so over an uncommitted in-place apply it exits 0 with a commit whose own validate-pins.py is red, dies on git's "nothing to commit", or says "nothing to do" and makes no branch #436 (P2): After an uncommitted in-place apply, a later apply --branch exits 0 with a commit its own validator rejects, or "nothing to do" with no branch.

Known limits. Every other sub-issue is a known limit: only exotic input triggers it (bytes that are not UTF-8, the C locale, control characters, hand-edited YAML, symlink tricks, names that differ only by case). The release notes list them, and they are worked when a release takes them in. A new edge case that review finds goes on this checklist, not into a new issue, unless it is in a release's scope or would hit a real user (Brett Heap, 2026-10-12).

Edge cases found in review of lane openRepoShape-3's pull requests, kept here rather than filed:

→ bump-leg.py --to <an annotated tag's own id>: the dry run previews it and exits 0, and the validators refuse the real run only after the rewrite #534 bump-leg.py --to <an annotated tag's own id>: the dry run previews the tag's id as the new commit and exits 0, while the real run is refused only by its validators after the rewrite (rolled back, exit 2), so the dry run does not say what the real run does. From family.py: bump refuses a --to that names an annotated tag, a tree or a blob as member-to-not-a-commit before the checkout, naming the commit a tag names, and its dry run refuses alike, so a release tag's own id no longer exits 0 with a commit pinning the tag over a gitlink at its commit, which the holder's validate-family.py refused as member-gitlink-mismatch (#405) #466's "Left out".
→ update-shape.py: four messages (a commit line when there is nothing to commit, a source path nothing names, the commit message's hand-edit claim, a bare gh pr create) #535 A branchless apply that moves the pin back to what HEAD already commits still prints a commit line, and pasted, git answers "nothing to commit". No commit comes out red, so it is outside update-shape.py apply --branch judges the pin, the manifest and the copies from the working tree but commits HEAD plus only the paths it wrote, so over an uncommitted in-place apply it exits 0 with a commit whose own validate-pins.py is red, dies on git's "nothing to commit", or says "nothing to do" and makes no branch #436. From update-shape.py: apply --branch compares the pin, the manifest and every pinned copy with HEAD before its first write and refuses a difference as update-branch-uncommitted, so an in-place apply left uncommitted no longer ends in a commit its own validate-pins.py refuses, in git's "nothing to commit", or in "nothing to do" with no branch made (#436) #474's "Left out".
→ Printed commands are POSIX-only: quote the bare paste lines in bump-leg.py and update-shape.py, and say in the docs that pasted commands are for a POSIX shell #532 bump-leg.py prints three more commands with the root bare, so a root under My Projects/ pastes as another command, the defect update-shape.py: check's and apply's NEXT lines print the root path unquoted where landing_failed's and the rollback hand-fix lines quote it with shlex, so a root under a path with a space pastes as a different command, and none of them quotes for cmd.exe or PowerShell #325 names for update-shape.py: the switch -c remedies of bump-leg-root-detached and bump-leg-on-tracking-branch (scripts/bump-leg.py:1028 and :1038) and the closing NEXT git -C <root> push -u origin <branch> (:1514); bump-leg.py: --dry-run runs on the project's tracking branch and ends by naming the git switch -c the real run needs, so step 1 of "Advancing a leg" prints the old -> new line on a fresh project instead of being refused bump-leg-on-tracking-branch before it (#477) #484 quotes only its own new dry-run line. (Not asked for; found while checking bump-leg.py: --dry-run runs on the project's tracking branch and ends by naming the git switch -c the real run needs, so step 1 of "Advancing a leg" prints the old -> new line on a fresh project instead of being refused bump-leg-on-tracking-branch before it (#477) #484's quoting.) From the review of bump-leg.py: --dry-run runs on the project's tracking branch and ends by naming the git switch -c the real run needs, so step 1 of "Advancing a leg" prints the old -> new line on a fresh project instead of being refused bump-leg-on-tracking-branch before it (#477) #484.
→ bootstrap.py: a commit on a detached leg, the not moving an existing branch text, and what bump-leg.py and AGENTS-shape.md still promise (one re-pin) #533 Since templates/assembly-root/scripts/bootstrap.py: a tracking branch behind the pin is fast-forwarded to it, and a fresh clone's branch past the pin with no commit of its own is moved back to it, so bump-leg.py then make bootstrap, and git clone --recurse-submodules then make bootstrap, leave the leg on its branch AT the pin, no longer detached under not moving an existing branch (#475) #490 (7348c57), make bootstrap puts a leg back on its tracking branch only when that branch is at or behind the pin, or ahead of it with no commit of its own; a branch with commits of its own past the pin is not moved, and the leg stays detached at the pin. Three texts still promise more: AGENTS.md:355 and README.md:995 ("make bootstrap re-places it on its tracking branch AT the new pin"), and bump-leg.py's unconditional print after every bump (scripts/bump-leg.py:1513). Every project's AGENTS-shape.md and docs/handbook.html carry the same promise. Lane openRepoShape-5's suggested words, from its read of templates/assembly-root/scripts/bootstrap.py: a tracking branch behind the pin is fast-forwarded to it, and a fresh clone's branch past the pin with no commit of its own is moved back to it, so bump-leg.py then make bootstrap, and git clone --recurse-submodules then make bootstrap, leave the leg on its branch AT the pin, no longer detached under not moving an existing branch (#475) #490: "make bootstrap in the root puts it back on its tracking branch when that branch is at or behind the new commit, or ahead of it with no commit of its own; a branch with commits of its own past the pin is not moved (bootstrap says not moving an existing branch), and the leg stays detached at the pin. Say which when you relay the result." Stale the other way: shape-doctor.py:2914 and :2989 and tests/test_doctor_legs_members_next.py:10 still say bootstrap never moves an existing branch whose tip is not the pin. From lane openRepoShape-5's read of templates/assembly-root/scripts/bootstrap.py: a tracking branch behind the pin is fast-forwarded to it, and a fresh clone's branch past the pin with no commit of its own is moved back to it, so bump-leg.py then make bootstrap, and git clone --recurse-submodules then make bootstrap, leave the leg on its branch AT the pin, no longer detached under not moving an existing branch (#475) #490 and the review of templates/assembly-root/scripts/bootstrap.py: a tracking branch behind the pin is fast-forwarded to it, and a fresh clone's branch past the pin with no commit of its own is moved back to it, so bump-leg.py then make bootstrap, and git clone --recurse-submodules then make bootstrap, leave the leg on its branch AT the pin, no longer detached under not moving an existing branch (#475) #490.
→ rides with bootstrap.py: a commit on a detached leg, the not moving an existing branch text, and what bump-leg.py and AGENTS-shape.md still promise (one re-pin) #533 bootstrap prints checked out, and then git said: (templates/assembly-root/scripts/bootstrap.py:251) over a checkout git refused when HEAD was already on the branch at the pin, for example behind a stale index.lock. Nothing was checked out, so the line should say git refused a checkout that would have changed nothing; git's own lines after it stay useful, because the lock also blocks the person's next commit. Nit 1 of the verification of templates/assembly-root/scripts/bootstrap.py: a tracking branch behind the pin is fast-forwarded to it, and a fresh clone's branch past the pin with no commit of its own is moved back to it, so bump-leg.py then make bootstrap, and git clone --recurse-submodules then make bootstrap, leave the leg on its branch AT the pin, no longer detached under not moving an existing branch (#475) #490. Fixed by 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 (64fc9a86): with nothing checked out it now prints nothing to check out, and then git said:.
→ Printed commands are POSIX-only: quote the bare paste lines in bump-leg.py and update-shape.py, and say in the docs that pasted commands are for a POSIX shell #532 Every command the tools print outside the doctor is quoted for a POSIX shell, so a Windows root whose path holds an apostrophe, such as C:\work\O'Brien\Atlas or C:\Users\Jane O'Neill\Atlas, prints 'O'"'"'Brien', which PowerShell does not read as one argument (a root with only blanks or backslashes is fine: a single-quoted string is a PowerShell verbatim string): update-shape.py:2419 (_by_hand) and :2900 (the landing NEXT), shlex.quote at :3184-3222, the switch -c line bump-leg.py: --dry-run runs on the project's tracking branch and ends by naming the git switch -c the real run needs, so step 1 of "Advancing a leg" prints the old -> new line on a fresh project instead of being refused bump-leg-on-tracking-branch before it (#477) #484 added to bump-leg.py, the repair line shape-doctor.py and validate-pins.py: a gitlink that is not its pin is offered both repairs, bump-leg.py --to the gitlink's commit to keep the move and --to the pin's to undo it, so a gitlink committed by hand no longer ends at a gate t (#478) #495 added to the shipped validate-pins.py, adopt-project.py:3938 and :4799, scripts/family.py (:2847 and the hand fixes at :3216-3277) and the shipped validate-family.py (the root at :733 and :1071, a member path at :1055 and :1069); only shape-doctor.py's quote_arg has a PowerShell alphabet (:551-600) and its own lines are right for PowerShell, the tests round-trip each line through shlex.split, and update-shape.py:2413-2418 calls the POSIX-only choice deliberate ("Git Bash is one, cmd.exe and PowerShell are not"). The shipped validators reach a project only through update-shape.py, so a change there is a re-pin for every project. Decide one rule: one shared quoter that spells nt PowerShell's way, or say in the docs that these lines are for a POSIX shell. (Line numbers are main 7a8b981's; later landings moved some.) From the review of bump-leg.py: --dry-run runs on the project's tracking branch and ends by naming the git switch -c the real run needs, so step 1 of "Advancing a leg" prints the old -> new line on a fresh project instead of being refused bump-leg-on-tracking-branch before it (#477) #484 (codex, thread 4253285979) and of shape-doctor.py and validate-pins.py: a gitlink that is not its pin is offered both repairs, bump-leg.py --to the gitlink's commit to keep the move and --to the pin's to undo it, so a gitlink committed by hand no longer ends at a gate t (#478) #495 (codex, finding 3 of the review).
→ Printed commands are POSIX-only: quote the bare paste lines in bump-leg.py and update-shape.py, and say in the docs that pasted commands are for a POSIX shell #532 update-shape.py still prints four commands or paths for pasting with no quoting, the defect update-shape.py: every NEXT line a run prints quotes its root, upstream, --accept-local paths, branch and lane trailer with shlex.quote, so check's apply, apply --branch's git -C <root> push && gh pr create and apply's own git -C <root> checkout -b && git -C <root> commit paste whole from a root under my projects/, it's here/ or $HOME/ (#325) #374 fixed for its NEXT lines (re-checked on main 7ab11cf): the update-branch-exists remediation's git -C <root> checkout <branch> (update-shape.py:2033-2034), check's ADDED UPSTREAM list of --add <path> (:1759), apply's pass --add <path> note (_note_untaken_additions, :2618) and the update-local-drift remediation's --accept-local <path> (_refuse_local_drift, :2585). Measured on 45e01f4 and on update-shape.py: every NEXT line a run prints quotes its root, upstream, --accept-local paths, branch and lane trailer with shlex.quote, so check's apply, apply --branch's git -C <root> push && gh pr create and apply's own git -C <root> checkout -b && git -C <root> commit paste whole from a root under my projects/, it's here/ or $HOME/ (#325) #374's head merged with it: with the root under sp ace, it's or d$x, the pasted git -C … checkout exits 128 or is a shell syntax error, and --add notes/shape notes.md pasted as printed is refused unrecognized arguments: notes.md. From update-shape.py: every NEXT line a run prints quotes its root, upstream, --accept-local paths, branch and lane trailer with shlex.quote, so check's apply, apply --branch's git -C <root> push && gh pr create and apply's own git -C <root> checkout -b && git -C <root> commit paste whole from a root under my projects/, it's here/ or $HOME/ (#325) #374's "Left out" and update-shape.py: check's and apply's NEXT lines print the root path unquoted where landing_failed's and the rollback hand-fix lines quote it with shlex, so a root under a path with a space pastes as a different command, and none of them quotes for cmd.exe or PowerShell #325's writer (draft U2, kept here under the v1.0.0 scope rule rather than filed).

Known limits found by lane openRepoShape-3's acceptance passes (standard 36538fd, each re-checked on main 7a8b981) and kept here rather than filed:

→ bump-leg.py: a root on +x is told push -u origin +x (forced), a branch named like a tag passes bump-leg-on-tracking-branch, bump-leg-root-dirty prints C1 controls raw, and committed <sha>: lists paths the commit lacks #672, update-shape.py apply: a rollback line fails over a read-only contracts/ unsaid, committed on <branch>: lists a path the commit lacks, --branch v1.0.0 cannot push beside a tag v1.0.0, and a quoted "files": header is refused #674 AT-scaffold N9: bump-leg.py's committed <sha>: <paths> line (:1491) and update-shape.py's committed on <branch>: <paths> (:2743) list the paths staged, not the ones the commit changed, and in the repair case (bump-leg.py --to a gitlink that was moved by hand) the old -> new line reads the gitlink, so it says X -> X while the pin moves.
Closed 2026-10-14, obsolete: Brett Heap's "Stop pre-filling it" on 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, landed as 8beb3d9 (update-shape.py and shape-doctor.py: no NEXT line pre-fills --accept-local for a locally edited shape copy, so the apply a row names, pasted, meets update-local-drift and its question to the human instead of re-pinning the edit as the standard, and a shape/ collision copy merged into its original and removed is merged-away to check, whose apply drops its pin row behind the same yes, so an adopted root that did its follow-up validates green again (#501, #502) #512). AT-family N2: after a person hand-merges a both file and commits it, check's NEXT still lacks that file's --accept-local (update-shape.py:1705 builds it from the locally-modified rows only), so the line pasted as printed is refused update-conflict again and only AGENTS.md's step 4 (and the refusal's own text at :2531-2535) gets the person through; decide it together 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, which is about the same line.
→ update-shape.py: four messages (a commit line when there is nothing to commit, a source path nothing names, the commit message's hand-edit claim, a bare gh pr create) #535 AT-family N3: the update-conflict remedy says to read the upstream bytes with git show <target>:<source path> (update-shape.py:2531-2535), but neither the refusal nor check says what the source path of the file is (for a project's scripts/validate-manifest.py it is templates/assembly-root/scripts/validate-manifest.py).
→ update-shape.py: four messages (a commit line when there is nothing to commit, a source path nothing names, the commit message's hand-edit claim, a bare gh pr create) #535 AT-family N4: the commit apply writes (update-shape.py:2005-2012) says "the copies are not hand-edited and the digests are recomputed", and never names a file --accept-local re-pinned from the project's own bytes, so the history carries a claim that is false for exactly those files.
→ update-shape.py: four messages (a commit line when there is nothing to commit, a source path nothing names, the commit message's hand-edit claim, a bare gh pr create) #535 AT-family N7: the bare gh pr create --repo <org>/<Project> --base <branch> --head <branch> that apply --branch prints without --pr (update-shape.py:3195-3200) carries no --title, --body or --fill; gh pr create --help says a prompt asks for them, so in a shell with no terminal the pasted line likely stops there. Not run (a real gh pr create is never run in these probes).

Lane: openreposhape-5 (openRepoShape-5)

(lane openRepoShape-5, 2026-10-12T21:26Z) One item for this area's checklist, from the independent review of #456 (#391) at d0aea3e. It is not in v1.0.0's scope: it needs a project that has edited its own copy of the shared library and then declined check's merge-by-hand.

Please fold this line into the checklist:

Closed 2026-10-14: a duplicate of the --accept-local scripts/repo_shape.py line, now update-shape.py apply --accept-local scripts/repo_shape.py can keep an old helper that a newly copied file imports from, and make bootstrap then fails with ImportError #536. Both roots' scripts/bootstrap.py: main escapes what stdout cannot encode and spells each value it prints, so name: "a\ud83db" or 日本 under PYTHONIOENCODING=ascii no longer ends make bootstrap in a traceback (#391) #456 moves spelled() and escape_unencodable_stdout() into scripts/repo_shape.py, and both roots' bootstrap.py import them. A project that keeps a locally edited scripts/repo_shape.py (check reads it both) with apply --accept-local scripts/repo_shape.py, while taking the new bootstrap.py, gets an ImportError from scripts/bootstrap.py, --help and make bootstrap. Meanwhile apply's validators pass, check then reads everything unchanged, and the project's CI never runs bootstrap. Reproduced with a real scaffolded project. Following check's merge-by-hand avoids it. Direction: apply refuses a kept --accept-local copy that lacks a name another copied shape file imports from it.

(lane openRepoShape-4, 2026-10-16T11:38:10Z) One line for this checklist, from R342's review of #636 (#342), which is now on main as c22da12. R342 read it on the merged tree and did not run it; #636 does not fix it.

→ bump-leg.py: a root on +x is told push -u origin +x (forced), a branch named like a tag passes bump-leg-on-tracking-branch, bump-leg-root-dirty prints C1 controls raw, and committed <sha>: lists paths the commit lacks #672, update-shape.py apply: a rollback line fails over a read-only contracts/ unsaid, committed on <branch>: lists a path the commit lacks, --branch v1.0.0 cannot push beside a tag v1.0.0, and a quoted "files": header is refused #674 update-shape.py's and bump-leg.py's run_validator still start the root's own validator with site on. update-shape.py:2206-2220 and scripts/bump-leg.py:1000-1017 on the merged tree (shape-doctor.py: every validator child starts with -S, so no .pth in the user's or a virtualenv's site-packages stands in for the repo_shape.py a root lost, and the manifest row is the gate's own ModuleNotFoundError (#342) #636 on main 4cf5fb07): both run [sys.executable, script] with an environment copied whole from os.environ (scripts/shape_materialize.py:256,276). So shape-doctor.py: after #238 the doctor runs a root's OWN validator with the operator's PYTHONPATH still in the child's environment, so for an operator who exports one that reaches a repo_shape.py the manifest row of a root that lost its own scripts/repo_shape.py says ok ... passes again, the false pass #238 removed, where the project's own gate in CI fails on ModuleNotFoundError: No module named 'repo_shape' #306's PYTHONPATH route and shape-doctor.py: run_validator starts a root's OWN validator under the doctor's interpreter with site processing on, so a .pth in the operator's user site or in a virtualenv's site-packages that names a directory holding repo_shape.py stands in for the copy the root lost, and the manifest row says ok ... passes for a gate that fails in CI on ModuleNotFoundError: the false pass #238 removed and #306 closes for PYTHONPATH alone #342's .pth and usercustomize routes both still reach apply's rollback gate and bump's validator gate, where the doctor's children now start with -S. Read, not run. apply refuses copy-missing, so whether a lost repo_shape.py can reach its gate at all is the first thing to measure (R342 Tracking: update-shape.py and bump-leg.py, keeping a project's shape copies and leg pins current #458).

Lane: openreposhape-4 (openRepoShape-4)

bump-leg.py and setup-project.py: the `git switch -c` line says under…

(lane openRepoShape-4, 2026-10-16T14:10:49Z; edited 2026-10-16T14:28:42Z) These are 6 of lane 4's 23 checklist lines on this issue, from 1 of its comments of 2026-10-15: the ones no other lane held when lane 4 read this issue at 13:17Z. The other 17 are held by other lanes' issues, listed in lane 4's triage summary on #473. Five of these six, L4-74 to L4-78, are lines 1 to 5 of lane 5's #704 (v1.1.0), filed at 13:45Z from the same comment. Lane 4's #709, filed later for all six, is closed as its duplicate. #704 defers L4-79 ("stays on #458"), so L4-79 stays here, open. Lane 4's lines on #457 to #461 are numbered together, L4-01 to L4-161, in posting order, so the numbers here have gaps. Each is copied word for word, with the comment it came from. Brett Heap approved lane 4's triage at 2026-10-16T13:36:07Z ("approve all triage recommendations"); a line ticked below is ticked on that word.

→ bootstrap.py: moving a leg off a branch overwrites an ignored file and ends a merge, P9 does not name the branch it leaves, a branch at its upstream's tip is left when HEAD is on a branch, a HEAD outside refs/heads/ is read two ways #704 [L4-74] Every bootstrap placement that changes files OVERWRITES an ignored file at a path the pin tracks, silently: the on-branch merge --ff-only (bump-leg.py, then make bootstrap, leaves the leg detached: bootstrap never fast-forwards a local tracking branch that is behind the new pin, though AGENTS.md, README and bump-leg.py say it re-places it #475), P9 (place_at_pin from another branch), the missing-branch checkout -b, and T7 (bootstrap.py and AGENTS-shape.md: a leg on another branch is placed when its tracking branch is at the pin and left when it is behind, and the family holder's copy still promises placement unconditionally #603). R603 measured it on main and on bootstrap.py: a leg on another branch whose tracking branch is behind the pin is fast-forwarded and checked out as one at the pin already is, and the family holder's AGENTS-shape.md and bump-leg.py say bootstrap places a leg where that loses no commit (#603) #615's head alike, with the ignored file listed in info/exclude or in the other branch's .gitignore. Possible fix: --no-overwrite-ignore on those checkouts and on the merge; git 2.43 has the flag for both. (was issuecomment-6201724792)
→ bootstrap.py: moving a leg off a branch overwrites an ignored file and ends a merge, P9 does not name the branch it leaves, a branch at its upstream's tip is left when HEAD is on a branch, a HEAD outside refs/heads/ is read two ways #704 [L4-75] Moving a leg off a branch with a merge in progress (merge --no-commit) ENDS the merge: MERGE_HEAD is removed and the staged result is carried onto the tracking branch. This happens in P9, on the missing-branch path and in T7. A cherry-pick or revert in progress should go the same way when its staged file does not block the checkout; that is reasoned only. Possible fix: refuse to move off a branch with an operation in progress, and say so. (was issuecomment-6201724792)
→ bootstrap.py: moving a leg off a branch overwrites an ignored file and ends a merge, P9 does not name the branch it leaves, a branch at its upstream's tip is left when HEAD is on a branch, a HEAD outside refs/heads/ is read two ways #704 [L4-76] P9's line (on <branch> at <pin> (branch tip == pin)) does not name the branch HEAD left. T7's does, after bootstrap.py: a leg on another branch whose tracking branch is behind the pin is fast-forwarded and checked out as one at the pin already is, and the family holder's AGENTS-shape.md and bump-leg.py say bootstrap places a leg where that loses no commit (#603) #615's fix round 1. (was issuecomment-6201724792)
→ bootstrap.py: moving a leg off a branch overwrites an ignored file and ends a merge, P9 does not name the branch it leaves, a branch at its upstream's tip is left when HEAD is on a branch, a HEAD outside refs/heads/ is read two ways #704 [L4-77] A tracking branch AHEAD of the pin with no commit of its own (its tip is its upstream's remote-tracking ref) is left with not moving an existing branch whenever HEAD is on the branch, on another branch, or on a branch with no commit yet. move_back_to_pin starts only from HEAD detached at the pin. Moving it back would lose no commit, so templates/assembly-root/AGENTS-shape.md:95-96 ("places each leg ... where that loses nothing") is false of these states. (was issuecomment-6201724792)
→ bootstrap.py: moving a leg off a branch overwrites an ignored file and ends a merge, P9 does not name the branch it leaves, a branch at its upstream's tip is left when HEAD is on a branch, a HEAD outside refs/heads/ is read two ways #704 [L4-78] HEAD as a symbolic ref outside refs/heads/: P9 places the leg, while T7 prints which is neither. This is exotic, and byte-identical to main. (was issuecomment-6201724792)
[L4-79] Reasoned only, for case-insensitive disks: the current != refs/heads/<branch> compare is case-sensitive. A branch that differs from the tracking branch only in case could take the T7 path, and branch -f would then write the loose ref file both names share. (was issuecomment-6201724792)

Lane: openreposhape-4 (openRepoShape-4)

update-shape.py: `current_branch` and `Rollback.new_branch` read a br…

(lane openRepoShape-3, 2026-10-17T11:51:28Z) One line for #458, from lane 2's review of #802 (#675), issuecomment-6233233871. It is outside #675's scope and already wrong on main bf1f099b.

update-shape.py's kept-copy check reads a handler that binds and then re-raises as a fallback.
- Example: except ImportError: / NEW = None / raise.
- The check counts that handler as answering NEW, but Python stops on the re-raised ImportError, so a copy that cannot start is not refused.
- With update-shape.py: the git show <target>:<source> a remedy prints is shell-quoted, so a source path with a blank or a ' pastes; the missing-name refusal says the validators pass only where none of them meets a line; and its readers skip an if TYPE_CHECKING:, if False: or if 0: body and a statement after a raise, as Python does (#675) #802's _reached in place, a handler whose reached body ends in a raise could answer nothing.
- Lane 2 reasoned it from the code; it was not run.

Lane: openreposhape-3 (openRepoShape-3)

(lane openRepoShape-2, 2026-10-17T12:00:49Z)

One line from rv766's independent review of lane 2's PR #814 for #766, at 0e516bba. #814 spells bump-leg.py's root through shown_path in three refusals and the dry run's branch line. The commands they tell a person to paste are left as they are, for the reason given in #459's L2-104. Per the v1.0.0 rule, an edge case goes on its area's tracking parent and not into a new issue. #814 lands only once this line is here.

L2-105 (nit; scripts/bump-leg.py, family.py, scaffold-project.py and bump-leg.py: init's plan rows, seven refusals and bump-leg's root name each path as shown_path names it, so an ESC or a line break in a holder, folder, lock, local remote or root no longer reaches the terminal from those plan rows or those refusals' details #814 review; edge case): bump-leg.py's switch -c and NEXT lines still name the root raw inside shell quotes. Credited: rv766.
- Sites, at 0e516bba:
  - _switch_command (scripts/bump-leg.py:1171, shlex.join at :1187), in bump-leg-root-detached (:1232), in bump-leg-on-tracking-branch (:1242), and in the dry run's the real run needs a branch line (:1807). That last line names the root spelled and then raw, on the same line.
  - The closing NEXT git -C <root> push (:1858).
- What happens:
  - An ESC in the root's path reaches the terminal, and the copied line no longer pastes to that path.
  - A line break prints a forged line of its own.
- Direction: as Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459's L2-104. Spell the path and give the command in words where shown_path spells it. A path shown_path prints as it is keeps today's line byte for byte.
- Also raw: bump-leg-root-not-a-project, bump-leg-manifest-unreadable and bump-leg-wrong-kind ({path}, :183, :192, :196), a --root the person typed.
- Ruling 5: edge case; v1.1.1 only if a real user hits it (Brett Heap's 13:35:28Z "yes create v1.1.1").

Lane: openreposhape-2 (openRepoShape-2)

bootstrap.py and AGENTS-shape.md: a leg with an operation in progress…

(lane openRepoShape-4, 2026-10-17T13:19:28Z) One line for this checklist, from #795 (#686). #795 fixes these three cases in family.py only. Lane 1's re-verification asked for the line before #686 closes (#795 issuecomment-6234322825).

bump-leg.py still has the three twins of family.py bump: a mount with a narrowed fetch refspec is refused member-to-local-only on a false detail, a commit only a tag holds is told "a pin the rest of the world cannot fetch", a mount with no origin is told to fix the network #686's lines (R613 p03, R613 p10, Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459 line 105), which family.py: bump fetches every branch of the member's origin whatever the mount's refspec and drops the origin/ refs no ref of origin backs, says a tag of the remote reaches a commit no branch does instead of "a pin the rest of the world cannot fetch", and tells a mount with no origin it has none instead of to fix the network (#686) #795 fixed in family.py only. (1) p03: a commit only a tag of the leg's remote reaches, which the leg also holds, is refused bump-leg-commit-local-only with "somebody committed inside the leg's mount and never pushed it … a pin the rest of the world cannot fetch is a root the rest of the world cannot bootstrap" (scripts/bump-leg.py:980-985), untrue there: a fresh clone of the remote holds the commit, and a fetch by sha exits 0 (family.py: bump fetches every branch of the member's origin whatever the mount's refspec and drops the origin/ refs no ref of origin backs, says a tag of the remote reaches a commit no branch does instead of "a pin the rest of the world cannot fetch", and tells a mount with no origin it has none instead of to fix the network (#686) #795 built the state, the commit pushed with its tag alone, and measured it). family.py now says "a tag of <repository> reaches it, but no branch of <repository> does" and that the way out is a push to a branch; it asks git ls-remote --tags --refs origin and compares object ids, only when a tag the mount holds contains the commit. (2) p10: a leg with no remote named origin (git remote rename origin upstream) has its fetch fail (:960-967, fetched = False) and is told "fix the network or the credential and re-run before believing it" (:974-977); family.py asks git remote get-url origin once the fetch has failed (exit 2 means none, any other failure is git's) and says the mount has none. (3) Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459 line 105: the leg's fetch, git fetch -q <remote> +refs/heads/*:refs/remotes/origin/* (:960-961), does not prune, so a branch deleted on the remote after the last fetch still counts in on_a_remote_branch (:894); family.py's now carries --prune --no-prune-tags (Brett Heap's word, relayed by lane 5, 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 13:56:50Z), and it keeps the refs the mount's own remote.origin.fetch maintains under refs/remotes/origin/ and skips its negative refspecs (a narrowing refspec never decides reachability), because lane 1's review (family.py: bump fetches every branch of the member's origin whatever the mount's refspec and drops the origin/ refs no ref of origin backs, says a tag of the remote reaches a commit no branch does instead of "a pin the rest of the world cannot fetch", and tells a mount with no origin it has none instead of to fix the network (#686) #795, issuecomment-6233185697, F1) measured that a bare --prune with the explicit refspec drops origin/pr/7 (a +refs/pull/*/head:refs/remotes/origin/pr/* ref) and a hand-fetched origin/kept-by-hand that main's plain fetch kept (main: origin origin/kept-by-hand origin/main origin/pr/7; bare prune: origin origin/main; with the mount's refspecs added: origin origin/main origin/pr/7). The same review measured that git's opportunistic update force-overwrites a local feat through a configured +refs/heads/*:refs/heads/* or mirror refspec when the fetch names refspecs of its own (feat moved from 76d7b0e to b4af330, and stayed with --refmap=), which applies to bump-leg.py's fetch too. Direction: change the three together with family.py's words and tests (tests/test_family_bump_reachability_words.py in family.py: bump fetches every branch of the member's origin whatever the mount's refspec and drops the origin/ refs no ref of origin backs, says a tag of the remote reaches a commit no branch does instead of "a pin the rest of the world cannot fetch", and tells a mount with no origin it has none instead of to fix the network (#686) #795 is the template), and decide --refmap= for both tools.

Corrected at 2026-10-17T20:15:01Z, when #795 landed as 6f64eea: family.py's fetch SKIPS the mount's negative refspecs, since a narrowing refspec never decides reachability. It does not pass them, as this line first said. That follows lane 1's re-verification of #795's round 2, N1. The rest of the line is unchanged.

family.py and shape_materialize.py: the NEXT push line names the bran…

family.py: `bump` fetches every branch of the member's `origin` whate…

family.py, scaffold-project.py and bump-leg.py: `init`'s plan rows, s…

update-shape.py: the `git show <target>:<source>` the remedies print …

(lane openRepoShape-3, 2026-10-18T14:31:02Z) Triage of #458's unchecked items at the v1.1.1 release commit 5017830. This is lane 3's TRIAGE-458, read only.

36 items: 31 FIXED and 5 OPEN.

A, C and E are filed as bootstrap.py: on a disk that folds case, a leg on Main whose tracking branch main is behind the pin is moved under its own HEAD, and bootstrap says it is on main now over an index that undoes the pin #896, update-shape.py: the kept-copy check reads an except ImportError: handler that binds the name and then re-raises as the copy's own fallback, so a copy that cannot start is kept #897 and bump-leg.py: a commit only a tag of the leg's remote reaches is told it was never pushed, a leg with no origin is told to fix the network, and the fetch does not prune: the three cases #795 fixed in family.py #898, in v1.2.0 and unclaimed.
B and D are left unfiled, with the reasons below.
Every pointed-to issue (Printed commands are POSIX-only: quote the bare paste lines in bump-leg.py and update-shape.py, and say in the docs that pasted commands are for a POSIX shell #532-update-shape.py apply --accept-local scripts/repo_shape.py can keep an old helper that a newly copied file imports from, and make bootstrap then fails with ImportError #536, bootstrap.py and AGENTS-shape.md: a leg on another branch is placed when its tracking branch is at the pin and left when it is behind, and the family holder's copy still promises placement unconditionally #603, update-shape.py apply --accept-local: a kept .py copy that imports a name the run's new repo_shape.py dropped passes, and make bootstrap then dies on an ImportError #604, bump-leg.py and setup-project.py: the git switch -c line fails "already exists" when an earlier act left that branch, and nothing says what to do (#607's sentence, in the two tools #607 left) #647, bump-leg.py: a root on +x is told push -u origin +x (forced), a branch named like a tag passes bump-leg-on-tracking-branch, bump-leg-root-dirty prints C1 controls raw, and committed <sha>: lists paths the commit lacks #672, update-shape.py apply: a rollback line fails over a read-only contracts/ unsaid, committed on <branch>: lists a path the commit lacks, --branch v1.0.0 cannot push beside a tag v1.0.0, and a quoted "files": header is refused #674-shape-doctor.py: the pins row says check's apply drops merged-away rows where check says REFUSAL AHEAD (a pinned copy kept as a link), and the shape currency counts leave out five of check's states #676, bootstrap.py: moving a leg off a branch overwrites an ignored file and ends a merge, P9 does not name the branch it leaves, a branch at its upstream's tip is left when HEAD is on a branch, a HEAD outside refs/heads/ is read two ways #704) is closed, and so are v1.0.0's sub-issues (update-shape.py apply overwrites a pinned copy, contracts/shape-pin.yaml and the manifest in place (Rollback.write opens the path r+b), so one kept as a HARD link is rewritten through its other name, a file outside the root (or a cp -al snapshot of the whole root) that no check showed and no pin covers, while the README, the one path guarded with st_nlink > 1, is refused #422, bump-leg.py _ensure_root_clean, scaffold-project.py _shape_revision and family.py _shape_snapshot read git status --porcelain through git_out, which decodes strictly, so a file name that is not UTF-8 under core.quotePath=false ends them in a UnicodeDecodeError traceback, exit 1, where bump-leg owes bump-leg-root-dirty (exit 2) and the other two owe a WARNING that the standard's checkout is dirty #423, update-shape.py Rollback.undo restores each rewritten file with a bare write_bytes and removes what --add made with rmdir and unlink, none under a handler, so an apply that fails after its first write and then cannot put one file back (a copy that became unwritable, a full disk, a lock) ends in an OSError traceback, exit 1, with the refusal that started the rollback lost and the paths after it never attempted, leaving a re-pinned manifest over a restored pin #428, update-shape.py checked_branch runs git check-ref-format --branch <name> with no cwd and no git-dir, so apply --branch shape/update-x started from a directory git cannot open (a .git file naming a missing gitdir, a malformed .git/config, a directory removed under the shell) is refused update-branch-invalid for a good name, git's failure read as the name's fault, where #355 asks the same question of no repository for the scaffold and the family holder #431, update-shape.py rewrite_shape_pin and rewrite_manifest find files: and shape: only as the whole line, so a trailing comment on either, which the reader and both validators accept, is refused as update-pin-unrecognised ("0 files line(s)") or update-manifest-no-shape ("has no shape: block", "add it") after check has sent the person to apply #437, bump-leg.py --dry-run returns before rewrite_pin runs unless nothing moves, so a leg pin the validators accept and the rewrite refuses (digests: {tree_sha256: …}) gets a dry run that prints old -> new and exits 0, and a real run that exits 2 bump-leg-pin-unrecognised #438).
Body edits made now: all 10 body lines ticked. Each is FIXED, rows 1 to 10 below.

Row	Item	Ruling	Evidence at `5017830`
1	#534 `--to` an annotated tag's id	FIXED	`7d9bec9` (#561): `bump-leg.py:884` `peeled_target`
2	#535 branchless `apply` commit line	FIXED	`a35f1be` (#558): `update-shape.py:5642-5646`
3	#532 bump-leg's three bare commands	FIXED	`709eec1` (#588): `bump-leg.py:1271`, `:1942`
4	#533 placement texts and the stale doctor	FIXED	`64fc9a8` (#556), `af01068` (#505), `2e6c6fa` (#559): `bump-leg.py:1929-1931`, `AGENTS.md:359`, `shape-doctor.py:7339-7341`
5	#532 one quoting rule	FIXED by ruling	`709eec1` (#588), on Brett Heap's "README; doctor exempt": `README.md:158-159`
6	#532 update-shape's four unquoted lines	FIXED	`709eec1`: `update-shape.py:2251`, `:2662`, `:3839`, `:3858`
7	#672/#674 N9	FIXED	`fc86720` (#746): `bump-leg.py:1758`; `d17564d` (#810): `update-shape.py:4768-4771`
8-10	#535 N3, N4, N7	FIXED	`a35f1be` (#558): `update-shape.py:3755`, `:2690-2697`, `:5498-5504`
11	#536 kept `repo_shape.py` lacks a name	FIXED	`bbcfd34` (#562): `update-shape.py:4129`
12-13	#533 detached commit stranded; "stays at the pin"	FIXED	`64fc9a8`: `bootstrap.py:805-809`, `:1099-1101`
14-15	#603 family AGENTS-shape.md; T7	FIXED	`77bb5f0` (#615): family-root `AGENTS-shape.md:70-72`; `bootstrap.py:880-887`
16	#674 quoted `"files":` header	FIXED	`d17564d` (#810): `update-shape.py:1478-1483`
17	#672 `--dry-run` over refused validators exits 0	FIXED as a disclosure only, as #672 ruled	`fc86720`: `bump-leg.py:1875-1882`. The behaviour is unchanged and stays a known limit
18	#604 kept `.py` imports a dropped name	FIXED	`b9f65be` (#616): `update-shape.py:3883`, `:4402`
19-20	#674 read-only `contracts/`; mutant test gaps	FIXED	`d17564d`: `update-shape.py:3035-3042`; tests at `test_update_shape_apply_lines_and_headers.py:9-15`; `0d5d2b1`: `test_update_shape_kept_helper.py:920`
21-23	#675 quoting, validators clause, readers	FIXED	`0d5d2b1` (#802): `update-shape.py:3724-3735`, `:4094-4127`, `:4361`, `:4376`. The one-hop check is a v1.1.1 known limit, meant to stay
24-28, 30	#704 L4-74 to L4-78 and the family docstring	FIXED	`24a977c` (#745): `bootstrap.py:568`, `:692`, `:805-809`, `:821-822`, `:1038`; assembly `AGENTS-shape.md:100-101` (wording only); family `bootstrap.py:79-82`
29	L4-79, case-folding `refs/heads/<b>` compare	OPEN, now #896	`bootstrap.py:880-881`, emulated probe in #896
31-33	#672 raw controls, `+x` push, tag-named branch	FIXED	`fc86720`: `bump-leg.py:1245-1249`, `:1942-1944`, `:1127-1137`; `d17564d`: `update-shape.py:4977-4992`
34	`run_validator` starts with `site` on	OPEN, B, not filed	`bump-leg.py:1067-1070`, `update-shape.py:2320-2321`. #672 and #674 both found that no verdict differs. Lane 3 leaves it for Brett Heap: won't-change, or an issue on his word
35	handler binds, then re-raises	OPEN, now #897	`update-shape.py:4328-4337`, probe in #897
36	L2-105, bump-leg prints the root raw	OPEN, D, not filed	`bump-leg.py:1271`, `:1942`, `:188`, `:197`, `:201`, confirmed by probe. Ruling 5: an edge case, taken only if a real user meets it
37	bump-leg's three twins of #686	OPEN, now #898	`bump-leg.py:998`, `:1013-1014`, `:1027-1039`

Rows 11 to 37 are lines in this issue's comments. Those comments are left as their authors wrote them.

Lane: openreposhape-3 (openRepoShape-3)

(lane openRepoShape-5, 2026-10-23T12:05:18Z)

Lane 5 filed one follow-up that belongs to this tracker. It comes from its independent review of #1166 (#1139), findings 3 and 9 (#1166 issuecomment-6352173084), and was re-measured at main 961640c6.

update-shape.py: a shape pin's source_repository: that names a path is refused as --upstream, and with --upstream passed one that ends in a line feed is never asked and reaches the commit subject and the pull request title (#1166 follow-up) #1203: update-shape.py asks a shape pin's source_repository: on neither route:
- a value that names a path is refused as --upstream, a flag nobody passed;
- with --upstream passed, a value that ends in a line feed is never asked, and it reaches the commit subject and the pull request title.

It is a post-tag follow-up, with no milestone.

Lane: openreposhape-5 (openRepoShape-5)

Navigation Menu

Repository navigation

Tracking: update-shape.py and bump-leg.py, keeping a project's shape copies and leg pins current #458

33 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Tracking: update-shape.py and bump-leg.py, keeping a project's shape copies and leg pins current #458

Description

Activity

brettheap commented on Oct 12, 2026

33 remaining items

brettheap commented on Oct 16, 2026

brettheap commented on Oct 16, 2026

brettheap commented on Oct 17, 2026

brettheap commented on Oct 17, 2026

brettheap commented on Oct 17, 2026

brettheap commented on Oct 18, 2026

brettheap commented on Oct 23, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions