Tracking: shape-doctor.py, reporting a repository's compliance #460

Lane: openreposhape-3 (openRepoShape-3)

The parent issue for one area of openRepoShape: answering whether one repository is compliant and naming each fix (shape-doctor.py, openRepoShape --doctor). 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:

• shape-doctor.py check_shape_currency takes every refusal update-shape.py prepare raises over the ROOT's own contracts/shape-pin.yaml (a merge conflict, a commit: that is not 40 hex, a deleted file) for this checkout failing to ask, so the verdict is CANNOT ANSWER, exit 3, outranking INVALID, and its NEXT git -C <standard> fetch --all blames the standard for a fault in the repository #237 (P2): A conflicted shape-pin.yaml (two shape-update merges) reads CANNOT ANSWER, exit 3, with a useless fetch --all NEXT, instead of INVALID, exit 1.
• 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 (P1): Pasting any doctor NEXT into macOS's default interactive zsh hands the # comment to the command as arguments (exit 127) and runs the backticked make bootstrap of legs/members.
• shape-doctor.py: the manifest kinds row's NEXT for a file that does not load (a conflicted or non-UTF-8 contracts/shape-pin.yaml) is "register the kind in shape-doctor.py's MANIFEST_VALIDATORS ... or remove the file from the root", so the one fix the doctor prints for a damaged pin is to delete it #291 (P2): A conflicted or damaged shape or leg pin gets the manifest-kinds NEXT "remove the file from the root"; an agent that obeys deletes the pin.
• shape-doctor.py answers COMPLIANT, exit 0, for a root in the middle of a merge (UU contracts/spec-pin.yaml, UU spec, a MERGE_HEAD, git commit refusing), because no row asks git for unmerged paths and recorded_gitlink answers an unmerged gitlink from HEAD, so a root an agent cannot commit is reported compliant, including after the git checkout --ours that a conflicted pin's NEXT names #424 (P2): A root mid-merge (UU pin, MERGE_HEAD) reads COMPLIANT, exit 0, though git commit refuses; anyone merging two bump or shape-update branches hits it.

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

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

• → shape-doctor.py, NOT A SHAPE ROOT on a git repository: print both ways in, as AGENTS.md says, and add --org to the adopt line when there is no origin #545 AT-adopt N8: on an ordinary git repository NOT A SHAPE ROOT prints one NEXT, the adopt-project.py plan command, though AGENTS.md:254-259 says to "report the verdict and both commands" and check_the_way_in's own docstring says "both are named and the human chooses" (shape-doctor.py:5265-5322; a directory that is not a repository gets only the scaffold line).
• → shape-doctor.py machine row quotes "[!!] this machine is not ready yet (see above)." with nothing above it #549 AT-scaffold N5: the machine row's reason quotes [!!] this machine is not ready yet (see above). with nothing above it, because the preflight's lines are kept only in --json (check_machine, shape-doctor.py:5072-5135, reason += ... at :5118).
• Closed 2026-10-14, fixed by 173c00e (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): --help and docs/cli.md list all seven verdicts. AT-scaffold N10: openRepoShape --help lists five verdicts (openRepoShape:93-94; docs/cli.md:159-160, which is generated from it), with no MISPLACED and no CANNOT ANSWER, and spells COMPLIANT SHAPE BEHIND without the comma the doctor prints (shape-doctor.py:410-421); its "3 usage" exit is also the doctor's CANNOT ANSWER (:219-229).

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

• → Publish openRepoShape to TestPyPI and PyPI as openreposhape, so one pipx install puts the tools and git-filter-repo on any machine (design first) #563 (rides in README, AGENTS.md, docs/cli.md and the handbook: pipx install openreposhape is the second way in and the first on native Windows, git-filter-repo is installed in install.sh's order and never with a bare pip install, and a first draft of the v1.1.0 release notes (#563) #630) README.md's validate-pins.py paragraph no longer says what a digest that recomputes differently does: README.md, docs/handbook.html and the comments in bump-leg.py and update-shape.py say when a project's own gate reaches a network: validate-pins.py asks gh api for a neutral product's pin with the operator's gh credentials, and make bootstrap, bump-leg.py and update-shape.py apply run it in the operator's environment, so none of them says any more that a project runs its own gate offline or that apply is otherwise offline (#411) #465 removed a sentence whose other half was false (a pin file the declaration names but that is not there is the refusal neutral-pin-missing, exit 2, not drift) and with it the true half, that such a digest is the finding neutral-pin-digest-mismatch, exit 1 (templates/assembly-root/scripts/validate-pins.py, report.finding). Lane openRepoShape-5's suggested words: "A digest that recomputes differently is the finding neutral-pin-digest-mismatch (exit 1); a pin file the declaration names but that is not there is the refusal neutral-pin-missing (exit 2)." From lane openRepoShape-5's read of README.md, docs/handbook.html and the comments in bump-leg.py and update-shape.py say when a project's own gate reaches a network: validate-pins.py asks gh api for a neutral product's pin with the operator's gh credentials, and make bootstrap, bump-leg.py and update-shape.py apply run it in the operator's environment, so none of them says any more that a project runs its own gate offline or that apply is otherwise offline (#411) #465.
• Closed 2026-10-14, obsolete: d41cc29 (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) made the NEXT update-shape.py check, and 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) dropped --accept-local. The shape currency row's NEXT (shape-doctor.py:2815-2830 on main 8109d7a) pastes apply --at <sha> --yes [--accept-local <path>] --branch shape/update-<sha> for a pinned copy a person edited and left uncommitted, but since 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 apply --branch refuses that difference as update-branch-uncommitted, so the NEXT should say to commit the edit first (or revert it) before the apply; 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 would take the --accept-local out of the same line. From the review of 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.
• Kept as a known limit (2026-10-14): deliberate, per check_merge's docstring. A merge left unfinished INSIDE a leg is not reported by the doctor's merge row (shape-doctor.py: a root whose index holds an unmerged path gets a merge FINDING naming the paths, with git -C <root> status as its NEXT, and the verdict INVALID (merge), exit 1, on a rung above every other but CANNOT ANSWER, so a merge git commit refuses no longer reads COMPLIANT, exit 0, once checkout --ours takes the markers out, or DRIFTED about a leg that never moved (#424) #468): the root records the leg's commit and never its index, and only the root's own index is read. From shape-doctor.py: a root whose index holds an unmerged path gets a merge FINDING naming the paths, with git -C <root> status as its NEXT, and the verdict INVALID (merge), exit 1, on a rung above every other but CANNOT ANSWER, so a merge git commit refuses no longer reads COMPLIANT, exit 0, once checkout --ours takes the markers out, or DRIFTED about a leg that never moved (#424) #468's "Left out".
• → shape-doctor.py: a checkout of the standard whose own contracts/repository-naming.yaml does not load makes a compliant project INVALID (naming), exit 1, "the naming policy is not satisfied (exit 2)", so a person is failed for the checkout's fault, and the module's EXIT CODES list leaves out an unfinished merge #678 shape-doctor.py's module docstring EXIT CODES list (shape-doctor.py:235-246 on main 57c85e9) does not name INVALID (merge) or an unmerged index among exit 1's findings; shape-doctor.py: a root whose index holds an unmerged path gets a merge FINDING naming the paths, with git -C <root> status as its NEXT, and the verdict INVALID (merge), exit 1, on a rung above every other but CANNOT ANSWER, so a merge git commit refuses no longer reads COMPLIANT, exit 0, once checkout --ours takes the markers out, or DRIFTED about a leg that never moved (#424) #468's paragraph above it (:120) does. From shape-doctor.py: a root whose index holds an unmerged path gets a merge FINDING naming the paths, with git -C <root> status as its NEXT, and the verdict INVALID (merge), exit 1, on a rung above every other but CANNOT ANSWER, so a merge git commit refuses no longer reads COMPLIANT, exit 0, once checkout --ours takes the markers out, or DRIFTED about a leg that never moved (#424) #468's "Left out".
• → Pinned validators: THE LOCKSTEP RULE only where it applies, and remedies that name the git switch -c step (one shape bump) #539 bump-leg.py --to <the gitlink's or the pin's commit> also cures pin-workflow-ref-mismatch (a hand-edited @<sha> in a workflow) and pin-digest-mismatch, but the shipped validate-pins.py still ends both findings at THE LOCKSTEP RULE with no command (templates/assembly-root/scripts/validate-pins.py:513 and :538, the rule at :92, on main 5e02abe), and test_every_other_pins_row_is_the_gates_own holds that output in place; only a project's own workflows meet the first, since scaffolded workflows carry no leg reference. Outside 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. From the review 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 (finding 6; the cure is the reviewer's, not re-probed here).
• → 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 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 is quoted for a POSIX shell, so a Windows root whose path holds an apostrophe prints a line PowerShell does not read as one argument; the one rule for every printed command is decided on Tracking: update-shape.py and bump-leg.py, keeping a project's shape copies and leg pins current #458's checklist (PowerShell quoting). From the review 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).