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

Goal: update-shape.py says what it did and what a person must do next without a line that fails as printed, and finds the pin's files: and the manifest's shape: headers wherever the reader finds them.

Filed by lane openRepoShape-5 on Brett Heap's word of 2026-10-16T12:17:02Z ("#458's update-shape/bump-leg (~22)"), from lines on #458: the body (AT-scaffold N9) with 6172776355, 6175499929 (the header finder), 6192496098 (the rollback line and its test gap), 6214576643 (the branch that shares a tag's name) and 6214653267 (the validator's environment). Lane 4 judged all but N9 OPEN or DOUBTFUL on main 95780dd (#473 comment 6215386495); lane 5 re-measured each on main 879d804.

Lands after: nothing. update-shape.py is not a pinned copy, so no project re-pins. No open PR touches it.

Lines (path:line at main 879d804; measured on that tree, git 2.43.0, a scaffolded project with local bare remotes unless a line says otherwise)

• A rollback's by-hand line fails over a read-only directory and does not say so. Rollback._restore (update-shape.py:2806-2857) words an absent file's line as the command alone (:2851-2855), and _restore_by_hand (:2897-2950) asks os.access(self._nearest_directory(path.parent), os.W_OK) only for the git checkout HEAD form (:2932-2936); the cat-file blob <id> > <path> form (:2937-2947) is given whatever the directory is. Measured with the ledger in a harness: a validator that deleted contracts/shape-pin.yaml and left contracts/ at 0555 gives ...its bytes before this run are kept as blob d0556e470b5e in this repository, then: git -C <root> cat-file blob d0556e47... > <root>/contracts/shape-pin.yaml, and pasted it exits 1 permission denied. (Tracking: update-shape.py and bump-leg.py, keeping a project's shape copies and leg pins current #458's 6192496098, first line.)
• committed on <branch>: lists a path the commit lacks. cmd_apply always puts {SHAPE_PIN, kind.manifest} in paths (:3359) and _land prints every one (:4408). Measured: an apply --branch that drops a merged-away row (the pin's shape/Makefile row with the file at the root's Makefile) prints committed on shape/update-x: contracts/shape-pin.yaml, project.yaml, and git show --name-only HEAD lists only contracts/shape-pin.yaml: project.yaml was rewritten with the same bytes. (The body's AT-scaffold N9, and 6172776355; bump-leg.py's half is in the issue for bump-leg.py.)
• A branch that shares a name with a tag cannot be pushed, and is read as heads/<b>. push_branch (:4607-4620) runs git push -q -u -- origin <branch> with the name bare, and the landing NEXT lines do too (:4582, :5218). Measured: in a root holding a tag v1.0.0, apply --yes --branch v1.0.0 --push commits, then REFUSED pushing v1.0.0 (exit 2, error: src refspec v1.0.0 matches more than one), and the NEXT line it prints, git -C <root> push -u -- origin v1.0.0 && gh pr create ..., fails the same way when pasted. current_branch (:2223-2231) uses symbolic-ref --short, which prints heads/<b> in that state (measured at git level), and here (:2471) and _awaits_its_pull_request (:4640) compare it with the bare name; read from the code, not run. The line's other half, a branch starting with +, is REFUTED for this tool: BRANCH_RE (:201) demands a letter or a digit first, and apply --branch +x is refused update-branch-invalid (R421 O4). (Tracking: update-shape.py and bump-leg.py, keeping a project's shape copies and leg pins current #458's 6214576643, second line, update-shape.py half.)
• The header finder misses a quoted key or a space before the colon. _is_block_header (:1378-1384) is _strip_comment(line) == f"{key}:", used for the pin's files: (:1444) and the manifest's shape: (:1584-1585); 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's docstrings say "a quoted key or a space before the colon is read as the key by the reader and is not found here, as before" (:1422-1423, :1571-1573). Measured with rewrite_shape_pin on a pin whose header is "files":, 'files': or files :: the reader (load_yaml) reads the key files in each, and the rewrite refuses all three update-pin-unrecognised ("has 0 files line(s)"), while files: and files: # c rewrite. For shape: the refusal is update-manifest-no-shape, whose "has no shape: block" is false of a manifest the reader gives a shape key (by the same reading; the manifest side was not run). The validators and check pass such a file, and check sends the person to the apply that refuses. (Tracking: update-shape.py and bump-leg.py, keeping a project's shape copies and leg pins current #458's 6175499929, third line.)

Rides along (backlog; tick it on #458 if the same change covers it)

• Untested: the os.path.lexists choice for "so make it writable" (:2851-2852). tests/test_update_shape_partial_rollback.py holds the file-present, unwritable cases (head_line, :217-223, and the 0555 contracts/ with the pin at 0444, :567-606) and the directory-deleted cases (:609-650, which asserts make it writable is absent, and :654-700), and nothing for a directory that exists at 0555 over an ABSENT file, which is the case in the first line. Its test closes this gap; R560v's mutant MN7c is the measurement (not re-run; the test file is unchanged since update-shape.py: apply refuses to rewrite a file that has a second, hard-linked name, and a rollback that cannot put a byte back names it with the line that finishes it and puts back the rest (#422, #428) #560). (Tracking: update-shape.py and bump-leg.py, keeping a project's shape copies and leg pins current #458's 6192496098, second line, first item; the second item, the try/else/finally imports, is in the issue for the kept-copy check.)
• run_validator starts the root's own validator with site on and the whole environment. update-shape.py:2206-2220 runs [sys.executable, script] with inherited_child_environment(), where the doctor's children start with -S and without PYTHONPATH (shape-doctor.py:1622-1627, 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). Measured, so it is not a verdict bug here: with the root's scripts/repo_shape.py lost, apply is refused update-conflict (the row is copy-missing) before any validator starts, so no gate runs without the copy. (Tracking: update-shape.py and bump-leg.py, keeping a project's shape copies and leg pins current #458's 6214653267; bump-leg.py's half, where the gate is reached and still red, is in the issue for bump-leg.py.)

Direction

• Rollback line: when the file is absent and _nearest_directory's answer is not writable, the line says make <that directory> writable, then: before the command, as it says "make it writable" of a present file; test it with the directory present and 0555 (WINDOWS_SKIP, as its neighbours).
• committed: after the commit, name the paths git reports (git show --name-only --format= HEAD, through the tool's own git helper) and not paths.
• Branch names: read HEAD's branch without --short (symbolic-ref --quiet HEAD, strip refs/heads/), and print and run the push with a name no tag can take: refs/heads/<branch> (measured: git push -u origin refs/heads/v1 pushes beside a tag v1, and refs/heads/+x pushes unforced), the same form as the one in the issue for bump-leg.py and on Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459 for family.py, in push_branch and both NEXT lines. The tests that hold today's form change with it (tests/test_update_shape_landing.py:293,416, tests/test_update_shape_next_quoting.py:264,376), and AGENTS.md:283 and :339 and README.md:525 show push -u origin <branch> as a placeholder line, to be kept or matched.
• Headers: _split_key(_strip_comment(line)) == (key, "") at column 0 (R558's suggestion; _split_key is scripts/repo_shape.py:322), writing the header back as the line was (_header_as_it_was), and update both docstrings' "not found here" sentences with it. Both validators' own finders are the reader's, so nothing else moves.
• Validator environment (rides along): no change here is needed for a verdict; a one-rule match with the doctor is optional.

Overlaps: none with open PRs (#634's files are scaffold-project.py, scripts/repo_shape.py, scripts/shape_materialize.py, scripts/validate-repository-naming.py, templates/*). The issue for the kept-copy check also edits update-shape.py, at merge_by_hand (:3495) and the _names_* readers (:3837-4186), regions apart from these (the nearest, run_validator at :2206-2220 and current_branch at :2223, are in this issue). The push-line form is shared with the issue for bump-leg.py: whichever lands second matches the first.

Mark each line → this issue on #458, and tick it there when this closes. The body's AT-scaffold N9, the --short line and the validator-environment line each have a second half in the issue for bump-leg.py: tick them when both close.

🤖 Generated with Claude Code