a gitlink committed by hand: the doctor's pins row and validate-pins.py name no command, though AGENTS.md says a finding names its fix; neither bump-leg.py (keep the move) nor the restore (undo it) is offered #478

Lane: openreposhape-3 (openRepoShape-3)

(lane openRepoShape-3, 2026-10-12T21:54Z) Found by lane 3's v1.0.0 acceptance pass: an assistant following AGENTS.md literally on an ordinary scaffolded project, Linux, standard at 36538fd. Lane 3 claims it.

What is wrong. AGENTS.md's doctor section, point 3, says: "A FINDING names its fix, and you run THAT. Every one carries the exact next command — update-shape.py apply …, make bootstrap, bump-leg.py …, the project's own validator" (AGENTS.md:226-228). But no row of the doctor, and no line of validate-pins.py, ever names bump-leg.py. So the most ordinary way a person breaks the leg invariant dead-ends: they move a leg by hand and commit the gitlink.

Reproduction:

1. On a scaffolded, bootstrapped project, run git -C spec pull (the leg's remote has a new commit).
2. In the root: git add spec && git commit -m 'take the new spec'.
3. shape-doctor.py --root . exits 1 with DRIFTED. The pins row is FINDING pin-gitlink-mismatch, and its next line is "run validate-pins.py; it names the repair".
4. validate-pins.py prints the finding and THE LOCKSTEP RULE, and no command.

The repair exists and works: bump-leg.py --root . --leg spec --to <the gitlink's commit>, after which the doctor says COMPLIANT. The alternative repair is to put the gitlink back to the pin, git -C <root> submodule update --init --checkout -- spec followed by committing the old gitlink. Which of the two is wanted is the person's call: keep the move, or undo it.

Proposed fix.

• For pin-gitlink-mismatch, the doctor's pins row names both commands, exactly as they would be pasted:
  • keep the move: the bump-leg.py … --to <gitlink commit> command, which also moves the pin and the workflow @<sha> in one commit;
  • undo it: the commands that restore the pinned gitlink.
• validate-pins.py's lockstep message names the same two.
• Every command goes through the same quoting the other NEXT lines use (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: 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).
• Tests: the doctor row and the validator name both commands for a hand-committed gitlink; running the bump command turns the doctor COMPLIANT; byte-identical output elsewhere.

Why v1.0.0. A core procedure's documented promise ("a finding names its fix") fails on the most ordinary drift a leg can have. Proposed P2.

Parent: #460 (doctor).