[brettheap]

Lane: openreposhape-2 (openRepoShape-2)
Claim: #291 (comment)
Targets main. It was stacked on #267, which landed as decff87; this branch merged decff87 (b88aa65), then main at d6df36b (a5563c3), then main at 437a360 after #343 landed (3af2829). The head is 65def40.

What

shape-doctor.py's manifest kinds row no longer gives a file that does not load the unregistered kind's sentence. That sentence was "register the kind in shape-doctor.py's MANIFEST_VALIDATORS, beside the check that validates it, or remove the file from the root".

• What the root declares decides, not the file's name. tool_written admits two kinds of file:

  • The pins declared_pins lists.
    • The shape pin.
    • contracts/<role>-pin.yaml for each leg project.yaml declares, the spelling check_legs, validate-pins.py and bump-leg.py use.
    • contracts/<product lowercased>-pin.yaml for each neutral_product_pins: entry, which is neutral_pin_path.
  • The copies pinned_copies lists. These are the paths the root's own contracts/shape-pin.yaml has files: rows for, read by update-shape.py's read_pin. A file with no row is not a copy, though this standard's copy lists name its path. That covers the file an adopted project made its own by dropping the row, and the source's own file beside a shape/ collision copy. Where the shape pin does not read, nothing is a copy.

  Anything else is the project's own, whatever it is called. A contracts/release-pin.yaml that no leg and no product names is the project's file.

  Where project.yaml does not load, it declares nothing. A leg or neutral product pin that does not load either is then the project's for that run. That is the safe side: a file wrongly called a tool's loses a person's edit, and one wrongly called the project's costs a run.

• The shape pin and a leg pin are put back from git. pin_restore(ctx, detail=None, pin=SHAPE_PIN), shape-doctor.py: a root's own contracts/shape-pin.yaml that does not read as a pin (a merge conflict, a non-UTF-8 byte, a commit: that is not 40 hex, a deleted file) is INVALID, exit 1, with the git command that puts back the last pin a tool wrote as its NEXT, instead of CANNOT ANSWER, exit 3, sending the reader to git fetch --all in the standard (#237) #267's helper, chooses the command from the file's own git state:

  • unmerged: git -C <root> checkout --ours -- <file>, or --theirs.
  • uncommitted: checkout HEAD -- <file>, where HEAD's copy reads.
  • hidden: ls-files -v, where HEAD's copy reads and status shows no change.
  • committed: checkout <breaking>~1 -- <file>, the newest copy in the history walk that reads.

  "Reads" is pin_reads_at: check_pin for the shape pin, and for any other file, loading as a mapping. Only the shape pin takes copies with it in a merge, and it names a conflicted manifest or README.md for a person. The copies it takes are the ones the taken side's pin has rows for (pin_at on the index stage). Any other file is named alone. A leg pin's gitlink is left out, because git checkout --ours on a conflicted gitlink exits 0 and changes nothing (tools/gitlink-ours-probe.log).

• A copy and a neutral product pin are shown, never put back (edited_by_hand). A copy can hold the project's own edit, above all the merge by hand that update-shape.py's both exit asks for. No tool writes a neutral product pin after the scaffold. So in every state the NEXT is a read-only git diff, and the note leaves the merge or the mend to a person:

  • unmerged: git -C <root> diff -- <file>, which shows the hunks git could not merge. The note: merge it by hand, keeping the hunks git merged, then finish the merge. That is what the shape currency row's --accept-local and AGENTS.md's "both is a merge" say too.
  • uncommitted: diff HEAD -- <file>.
  • committed: diff <breaking>~1 -- <file>, every change since the newest copy that reads.

• A file of the project's own is not put back from git. Its restore is project. Where no file has a command, the NEXT is this doctor again, and its note says what the file should say is for a person to decide. That covers a file of the project's own, and a declared pin with no good copy in its history (none). It matches shape-doctor.py calls an assembly root whose project.yaml does not parse (a merge conflict) NOT A SHAPE ROOT, exit 2, and its NEXT line tells the reader to adopt that assembly root in place while the Triad row calls it a single repository #205's answer for a project.yaml that does not load.

• The shape pin's command comes first, and it is the same command the shape currency row prints. Then each other file follows in the row's order. A row prints one command, and the next run names the next file.

• The reason quotes the loader for each file, without the path it starts with: unreadable as YAML: contracts/shape-pin.yaml (yaml-unparsable: line 30: merge keys are not supported). A file that loads but is not a mapping says what it loaded as (it loads as a list, not a mapping).

• detail gains two keys, only when a file does not load: restore ({file: unmerged|uncommitted|hidden|committed|none|project}) and refusals ({file: {code, detail}}). Every other root reports the row it always did, keys included.

• Another fault in the same row (an unregistered kind, a kind registered elsewhere (shape-doctor.py: manifest kinds counts a contracts/*.yaml that declares a registered kind as validated though that kind's validator never runs on this kind of root, so a contracts/family.yaml in an assembly root, or a contracts/project.yaml in a family holder, is ok and COMPLIANT where the same bytes at the root are a FINDING #327), or a family.yaml beside project.yaml): the reason names every fault, and the NEXT is the restore alone. The next run names the rest.

Every new note avoids ;, apostrophes and backticks (#277). Each command runs as printed through shlex on POSIX, and through the file's powershell_tokens on Windows (pasted).

Why

The sentence was written for a file that loads and declares a kind nothing validates. A file that does not load has no kind: to register, so the only half a reader could follow was "remove the file from the root". For a conflicted or non-UTF-8 contracts/shape-pin.yaml, that means deleting the pin. AGENTS.md tells an agent to run the NEXT a FINDING names. That NEXT was not even a command: the apostrophe in "shape-doctor.py's" stops shlex.split with "No closing quotation".

The reproduction at 9f64bd0 is in tools/repro-base-9f64bd0.log. It covers a conflicted shape pin, a committed non-UTF-8 byte in it, a conflicted contracts/spec-pin.yaml and a conflicted project contract. All four gave the sentence.

Fix round (review of ebffb08)

Item	Outcome	Commit
F1 (P1, codex discussion_r4248225898): a project's own contracts/<x>-pin.yaml was put back from git by its suffix, and the NEXT discarded the person's edit	fixed: ownership from what the root declares (declared_pins); a project.yaml that does not load declares nothing (the safe side)	2745890
F1, optional point: a copy's uncommitted NEXT discarded a hand merge	taken: shown by git diff HEAD -- <copy> and kept	2745890
F2 (P3): no test put back a file other than the shape pin from history	fixed: four history cases, mutants mu1-mu3 killed	2745890
N1: the words for a file that loads as a list were not pinned	fixed: the literal is asserted	2745890
N2: this body	fixed	-

F3 (a leg pin's history restore ignores the gitlink lockstep) and F4 (the doctor says COMPLIANT in the middle of a merge, as main does, now #424) are follow-ups.

Fix round 8165 (re-verify of 2745890, and codex on 2745890)

Item	Outcome	Commit
P1, codex r4250578605 (rv358 P10, P10b, P12). A copy conflicted on its own got checkout --ours, and the project's merged hunk was lost. A committed hand merge got checkout <sha>~1. The shape currency row said --accept-local for the same file.	fixed. A copy's unmerged and committed states get what its uncommitted state got: a read-only git diff and a merge by hand. The two rows and AGENTS.md now describe one path.	30c963c
P1, codex r4250578619 (rv358 P11a, P11b). Copies came from the static copy lists, so a file with no row, or the source's file in an adoption collision, was put back from git.	fixed. A copy is what the shape pin's files: rows name (pinned_copies), and the pin's own merge names the copies the taken side's rows list.	30c963c
P3 (rv358 P13). A declared neutral pin re-pinned by hand got checkout HEAD, which discarded the re-pin.	fixed. No tool writes a neutral pin after the scaffold, so it gets the same read-only commands in every state.	30c963c

New tests, one per probe, each red at ce2ce75 (tools/f358-red-ce2ce75.log.gz: 10 failed, 13 passed of the 23 selected):

• test_a_copy_conflicted_on_its_own_is_shown_and_merged_by_a_person (P10).
• test_a_conflicted_copys_next_agrees_with_shape_currency_and_agents_md (P10b). It follows the merge by hand, then the shape currency row's own apply --accept-local, to COMPLIANT, with every line of both sides in the copy.
• test_a_file_the_shape_pin_has_no_row_for_is_the_projects (P11a).
• test_the_sources_own_file_at_a_collided_copy_path_is_the_projects (P11b).
• test_a_conflicted_shape_pin_takes_only_the_copies_its_side_has_rows_for (the pin's own merge in the collision layout).
• test_a_committed_hand_merge_of_a_copy_is_shown_not_rolled_back (P12).
• test_a_neutral_product_pin_is_shown_never_put_back, with cases uncommitted (P13), committed and conflicted.

test_a_pin_is_what_the_root_declares_not_what_it_is_called now expects diff HEAD for the declared neutral pin. The naming-copy case of test_a_file_a_tool_wrote_that_does_not_load_is_put_back_from_git moved to P12's test, because a copy is no longer put back.

Mutants at a5563c3: 6 of 6 killed (tools/f358-mutants.log):

Mutant	Failed	Which
mA: nothing is edited by hand (r4250578605 and P3 undone)	8	P10, P10b, P12, the three neutral pin cases, the declared neutral pin, the uncommitted copy
mB: copies from this standard's copy lists again (r4250578619 undone)	2	P11a, P11b
mC: the shape pin's merge names the copy lists again, not the taken side's rows	1	the pin's own merge in the collision layout
mD: a neutral product pin is not edited by hand (P3 undone)	4	the three neutral pin cases, the declared neutral pin
mE: a copy's unmerged state takes a side again	3	P10, P10b, the conflicted neutral pin
mF: a copy's committed state rolls back again	2	P12, the committed neutral pin

Merged main

• b88aa65 merges decff87, shape-doctor.py: a root's own contracts/shape-pin.yaml that does not read as a pin (a merge conflict, a non-UTF-8 byte, a commit: that is not 40 hex, a deleted file) is INVALID, exit 1, with the git command that puts back the last pin a tool wrote as its NEXT, instead of CANNOT ANSWER, exit 3, sending the reader to git fetch --all in the standard (#237) #267's squash.
  • git diff f6dd11a decff87 on shape-doctor.py, update-shape.py and tests/test_shape_doctor.py is empty.
  • Those three files are taken from this branch, which already held f6dd11a.
  • Every other path is main's at decff87.
• a5563c3 merges main d6df36b, which carries shape_advisory.py and shape-doctor.py: an origin URL that is not UTF-8 names nothing, and the members row reads it as make siblings does, so a single repository is still advised, a leg clone is still sent to its root, and shape-doctor.py --root no longer ends in a UnicodeDecodeError traceback (#385) #404 (1184f67, origin_url/origin_name) and update-shape.py: apply --add refuses a path under a file the root keeps as update-add-not-a-directory before it writes anything, and a write that fails after the copies is update-write-failed, rolled back, so neither leaves a rewritten copy and an unmoved pin behind a traceback (#285) #346 (d6df36b, update-shape.py apply --add).
  • Git merged both without a conflict, and each one's lines are its own commit's, one for one.
  • git diff --stat d6df36b a5563c3 lists shape-doctor.py and tests/test_shape_doctor.py only.
  • git merge-tree --write-tree d6df36b a5563c3 is rc 0.

Merged main after #343 landed

• 3af2829 merges main 437a360, update-shape.py read_pin refuses update-pin-row, and the pinned validate-pins.py and validate-family.py report shape-pin-row, when a shape pin's files: is not a list, so files: 5, true or 1.5 no longer ends check, apply, shape-doctor.py and the project's own validator in TypeError: ... is not iterable (#290) #343's squash (update-shape.py read_pin and the pinned validate-pins.py and validate-family.py: iterate pin.get("files") or [] without asking for a list, so a shape pin with files: 5 or files: true ends shape-doctor.py, update-shape.py check and apply and the project's own validator in TypeError: ... is not iterable, exit 1, with no refusal naming the pin #290: check_pin(pin, pin_path, root) refuses a files: that is not a list as update-pin-row, so pin_reads_at passed ctx.root and stopped catching TypeError). 437a360 equals update-shape.py read_pin refuses update-pin-row, and the pinned validate-pins.py and validate-family.py report shape-pin-row, when a shape pin's files: is not a list, so files: 5, true or 1.5 no longer ends check, apply, shape-doctor.py and the project's own validator in TypeError: ... is not iterable (#290) #343's final head 91a4a4f on all six of its files.
  • The conflict. Git conflicted in pin_at alone (the body of the old pin_reads_at, which this branch moved there), in the two hunks this body predicted under "Composes with". tests/test_shape_doctor.py merged without a conflict.
  • The resolution. The docstring keeps update-shape.py read_pin refuses update-pin-row, and the pinned validate-pins.py and validate-family.py report shape-pin-row, when a shape pin's files: is not a list, so files: 5, true or 1.5 no longer ends check, apply, shape-doctor.py and the project's own validator in TypeError: ... is not iterable (#290) #343's two sentences (check_pin refuses files: 5 as update-pin-row; a TypeError is not caught), then this branch's paragraphs on any other file and on the rows. The body keeps this branch's (a file other than the shape pin reads as its mapping, the shape pin as its rows' paths) with us.check_pin(data, f"{rev}:{SHAPE_PIN}", ctx.root) and except (Refusal, us.YamlError, ValueError).
  • Checked line for line. The merge's change over a5563c3 is 437a360's own lines in both files, with ctx.root landing on this branch's form of the check_pin line. Its change over main is this branch's lines over d6df36b, with that same ctx.root.
  • git diff --stat 437a360 65def40 lists shape-doctor.py and tests/test_shape_doctor.py only, and git merge-tree --write-tree 437a360 65def40 is rc 0.
• 65def40, two nits from the re-verify of a5563c3:
  • N1. A neutral product pin's reason ended "..., so every change to one was made by a person", and the unmerged and committed notes add ", so neither side is taken whole" and ", so nothing is rolled back". The reason now reads "..., and every change to one since was made by a person". test_a_neutral_product_pin_is_shown_never_put_back also asserts that no sentence of the note holds two ", so " clauses. With the old words put back, its committed and conflicted cases fail (2 failed, 1 passed, tools/m358c-red-n1.log).
  • N2. pinned_copies no longer catches TypeError, by update-shape.py read_pin refuses update-pin-row, and the pinned validate-pins.py and validate-family.py report shape-pin-row, when a shape pin's files: is not a list, so files: 5, true or 1.5 no longer ends check, apply, shape-doctor.py and the project's own validator in TypeError: ... is not iterable (#290) #343's reasoning for pin_at: nothing in a pin's bytes raises one now, so one means a caller out of step with check_pin. A pin that does not read still gives the empty set.

Tests at 65def40 (tools/m358c-final-summary.log):

• tests/test_shape_doctor.py: 329 passed, 3 skipped (326 at a5563c3, plus update-shape.py read_pin refuses update-pin-row, and the pinned validate-pins.py and validate-family.py report shape-pin-row, when a shape pin's files: is not a list, so files: 5, true or 1.5 no longer ends check, apply, shape-doctor.py and the project's own validator in TypeError: ... is not iterable (#290) #343's three files: cases in ROOT_PIN_FAULTS) (tools/m358c-final-doctor.log.gz). The skips need a Windows host for PowerShell.
• tests/test_doctor_validator_rows.py, tests/test_shape_advisory.py, tests/test_shape_pin_files_not_a_list.py, every tests/test_update_shape*.py (7 files), tests/test_cli_reference.py, tests/test_repo_hygiene.py: 419 passed, 3 skipped (tools/m358c-final-rest.log). The skips are the NTFS-junction test's three cases.
• scripts/render-cli-reference.py --check: ok. No --help text changed.

Tests at a5563c3

• tests/test_shape_doctor.py: 326 passed, 3 skipped (tools/f358-final-a5563c3-doctor.log.gz). The skips need a Windows host for PowerShell.
• tests/test_doctor_validator_rows.py, tests/test_cli_reference.py, tests/test_repo_hygiene.py, tests/test_shape_advisory.py: 138 passed (tools/f358-final-a5563c3-rows-cli-hygiene-advisory.log).
• scripts/render-cli-reference.py --check: ok. No --help text changed.

The #291 tests:

• test_a_file_a_tool_wrote_that_does_not_load_is_put_back_from_git, 7 cases. The shape pin conflicted, not UTF-8 and committed, and a list. A leg pin conflicted (with Makefile and README.md conflicted beside it, neither named), not UTF-8, not UTF-8 and committed, and past a list in its history. Each case checks the restore, the loader's code, the reason, the argv and the note. It runs the NEXT as printed, and the row is ok.
• test_a_file_git_cannot_put_back_is_left_to_a_person, 6 cases. A conflicted contract of the project's own. A committed contracts/release-pin.yaml nothing declares, edited, conflicted and committed (project each). A leg pin in a squashed root commit, and one added back after its deletion (none each). The NEXT is this doctor, and the file's bytes are left alone.
• test_an_unregistered_kind_beside_a_file_that_does_not_load, test_the_shape_pin_goes_first_and_each_run_names_the_next_file, test_a_pin_is_what_the_root_declares_not_what_it_is_called, test_a_leg_pin_is_left_to_a_person_while_project_yaml_does_not_load, test_an_uncommitted_change_to_a_copy_is_shown_and_kept, and the two compose tests with shape-doctor.py reads only project.yaml at a root that also carries a family.yaml, so an assembly root whose family.yaml declares two unmounted members is COMPLIANT, and its manifest kinds row says that kind has a registered validator, which is never run #211 and shape-doctor.py: manifest kinds counts a contracts/*.yaml that declares a registered kind as validated though that kind's validator never runs on this kind of root, so a contracts/family.yaml in an assembly root, or a contracts/project.yaml in a family holder, is ok and COMPLIANT where the same bytes at the root are a FINDING #327.
• The fix-round-8165 tests above.

The earlier rounds' mutants were killed at 462baf1, ebffb08 and 2745890 (tools/mutants-462baf1.log, tools/mutant-left-guard.log, tools/x358-mutants-2745890.log).

Composes with

• update-shape.py read_pin refuses update-pin-row, and the pinned validate-pins.py and validate-family.py report shape-pin-row, when a shape pin's files: is not a list, so files: 5, true or 1.5 no longer ends check, apply, shape-doctor.py and the project's own validator in TypeError: ... is not iterable (#290) #343 landed as 437a360, and 3af2829 composes it (above).
• 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 (978ca3e) and validate-pins.py (assembly-root template): a workflow file under .github/workflows/ that is not UTF-8, or that this user cannot open, is ONE workflow-unreadable refusal naming every such file, exit 2, so the project's pins gate no longer ends in a UnicodeDecodeError traceback, exit 1, with no line naming the file (#359) #419 (7e8bb26) each merge with 65def40 without a conflict (git merge-tree --write-tree, rc 0).
• 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 is worked on a branch stacked on a5563c3 (see "Left out").

Left out

• When the shape pin is conflicted too, its merge still takes the conflicted copies its side lists whole with it. That is shape-doctor.py: a root's own contracts/shape-pin.yaml that does not read as a pin (a merge conflict, a non-UTF-8 byte, a commit: that is not 40 hex, a deleted file) is INVALID, exit 1, with the git command that puts back the last pin a tool wrote as its NEXT, instead of CANNOT ANSWER, exit 3, sending the reader to git fetch --all in the standard (#237) #267's design for a merge of two apply runs, and shape-doctor.py: a root's own contracts/shape-pin.yaml that does not read as a pin (a merge conflict, a non-UTF-8 byte, a commit: that is not 40 hex, a deleted file) is INVALID, exit 1, with the git command that puts back the last pin a tool wrote as its NEXT, instead of CANNOT ANSWER, exit 3, sending the reader to git fetch --all in the standard (#237) #267's tests assert it. This PR changes only which copies it names. A copy that one side kept with --accept-local can therefore lose to the other side in that merge. That is now 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 (v1.0.0), worked on a branch stacked on this one.
• This row's detail has no left_for_a_person. The manifest kinds row passes no detail to pin_restore. Where the shape pin's merge leaves a manifest or README.md to a person, the note names it, and the shape currency row's detail lists it.
• A file that loads as a list, or holds no YAML document, is still listed unreadable. That is pre-existing, and the row now says what the file loaded as.
• A leg pin put back from history is not checked against its gitlink (F3). A root in the middle of a merge can still be COMPLIANT (F4, 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). Both are follow-ups.

Closes #291

🤖 Generated with Claude Code

Summary by Sourcery

Make manifest-kind diagnostics preserve project edits and guide recovery of unreadable tool-managed files without destructive commands.

New Features:

• Improve the manifest kinds diagnostic to explain why files fail to load and provide an actionable, shell-safe next command.

Bug Fixes:

• Prevent the doctor from recommending deletion or incorrectly restoring unreadable project-owned files.
• Restore unreadable tool-managed pins from the appropriate Git state while preserving hand-edited copies and neutral product pins.
• Determine file ownership from root declarations and shape-pin rows rather than filenames or static copy lists.
• Keep restore behavior consistent with the shape currency diagnostic and handle multiple simultaneous findings safely.

Enhancements:

• Extend diagnostic details with per-file restore states and loader refusal information.
• Support read-only diffs for hand-edited files and history-aware restoration for leg pins and other tool-written files.

Tests:

• Add comprehensive coverage for unreadable pins, project-owned contracts, neutral pins, shape copies, merge conflicts, Git history cases, ownership collisions, and composed diagnostics.

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

[sourcery-ai]

Reviewer's Guide

Updates the manifest-kinds check to diagnose unreadable files separately from unregistered kinds and issue a single safe remediation command: restore tool-written pins or copies from Git, or rerun the doctor for project-owned files requiring human repair. The implementation generalizes pin restoration and adds focused regression tests covering Git states, ordering, notes, detail output, and composed behavior.

Sequence diagram for manifest-kinds restoration

sequenceDiagram
    participant Doctor as shape-doctor.py
    participant Loader as load_yaml
    participant Git as Git state
    participant Restore as pin_restore
    participant Person as Person

    Doctor->>Loader: load_yaml(path)
    Loader-->>Doctor: Refusal or non-mapping
    Doctor->>Doctor: tool_written(ctx, rel)
    alt tool-written pin or copy
        Doctor->>Restore: pin_restore(ctx, pin=rel)
        Restore->>Git: inspect status and readable history
        Git-->>Restore: restore state and command
        Restore-->>Doctor: restore and command
        Doctor-->>Person: print one restoration command
    else project-owned file or no readable copy
        Doctor-->>Person: print doctor command for manual repair
    end
    Person->>Doctor: run NEXT
    Doctor->>Loader: load_yaml(path)
    Loader-->>Doctor: readable mapping

Loading

Flow diagram for unreadable manifest remediation

flowchart TD
    A[check_manifest_kinds] --> B[load_yaml for each manifest]
    B -->|mapping| C[Classify declared kind]
    B -->|Refusal or non-mapping| D[Record unreadable reason]
    D --> E{tool_written file?}
    E -->|yes| F[unreadable_next]
    E -->|no| G[restore project]
    F --> H[pin_restore for the file]
    H -->|Git copy available| I[Print one checkout or ls-files command]
    H -->|No readable Git copy| G
    G --> J[Print doctor command for human repair]
    C --> K[Report validated or unregistered kind]
    D --> L[Add restore and refusals detail]

Loading

File-Level Changes

Change	Details	Files
Distinguish unreadable manifest files from unregistered kinds and provide loader-specific diagnostics.	Switch manifest inspection to load_yaml so refusal codes and non-mapping results are captured. Include path-free refusal details in the reason and add conditional restore/refusals detail fields. Preserve the existing unregistered-kind guidance, including when both issue types occur.	shape-doctor.py
Restore unreadable tool-generated contract files using their own Git history while leaving project-owned files for manual repair.	Generalize pin history checks and restoration commands to arbitrary pins or copies. Recognize contract pins and shape-generated copies as tool-written, with distinct pin/copy notes and merge handling. Select one ordered NEXT command, prioritizing the shape pin and falling back to rerunning the doctor when no safe Git restore exists.	shape-doctor.py
Add comprehensive regression coverage for restoration, diagnostics, ordering, and command execution.	Test conflicted, invalid-encoding, list-valued, committed, and manually broken tool-written files. Test project-owned and history-without-good-copy cases remain untouched and require a person. Verify unregistered-kind precedence, shape-currency command parity, sequential remediation, shell portability, and resulting compliance.	tests/test_shape_doctor.py

Possibly linked issues

• 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: The PR implements the issue’s requested fix by replacing deletion/registration guidance with appropriate restoration commands and tests.

---

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.

[brettheap]

@codex review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-12T17:12:43.873929Z	2745890	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ebffb08280

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Restrict automatic restores to declared shape pins

When an adopted project owns a contract such as contracts/release-pin.yaml, this suffix check classifies it as tool-written even if no leg or neutral_product_pins entry declares it. If that file then has an uncommitted syntax error or merge conflict, manifest-kinds emits git checkout HEAD/--ours as its prescribed fix, discarding project-owned edits instead of leaving them for a person as intended. Determine tool ownership from the shape pin, manifest-declared leg/product pins, and copy_source, rather than every *-pin.yaml; this is especially important because the documented doctor procedure tells users to run the exact command in a finding.

AGENTS.md reference: AGENTS.md:L208-L214

Useful? React with 👍 / 👎.

[brettheap]

(lane openRepoShape-2, 2026-10-12T17:08Z)

Fixed in 2745890. What the root declares now decides ownership, not a file's name. tool_written admits only declared_pins and the root kind's shape copies. declared_pins is the shape pin, contracts/<role>-pin.yaml for each leg project.yaml declares, and contracts/<product lowercased>-pin.yaml for each neutral_product_pins: entry. Anything else, such as an undeclared contracts/release-pin.yaml, gets restore: project. Its NEXT is this doctor again, and the file's bytes are never touched. A project.yaml that does not load declares nothing, so for that run a leg pin is left to a person. A copy's uncommitted change is shown with git diff HEAD, not discarded.

Tests: test_a_file_git_cannot_put_back_is_left_to_a_person (the a-file-of-the-projects-own-named-like-a-pin- cases edited, conflicted and committed), test_a_pin_is_what_the_root_declares_not_what_it_is_called, and test_a_leg_pin_is_left_to_a_person_while_project_yaml_does_not_load. All 8 of this round's mutants were killed. Restoring the suffix rule failed 5 tests.

[brettheap]

(lane openRepoShape-2, 2026-10-12T14:51Z)

This lane reviewed its own PR #358 at ebffb08 (the increment over #267's 8badae0, and its merge with main ab623dd), read-only in its own detached worktrees, with nothing authored.

CHANGES NEEDED. Take main or #267's pre-squash final head before #267 squash-lands. After the squash, even the resolved merge meets 10 both-added hunks in pin_reads_at and pin_restore.

Findings:

1. P1, fix here (codex discussion_r4248225898, confirmed). tool_written (shape-doctor.py:1346) admits any contracts/*-pin.yaml. For a project's own contracts/release-pin.yaml, the NEXT loses the person's edit when run:

   • an uncommitted slip gives checkout HEAD --;
   • a conflict gives checkout --ours --, dropping the other side's cleanly merged line;
   • a committed slip gives checkout <sha>~1 --.

   Ownership should come from what the root declares: the shape pin, ctx.legs() roles, neutral_product_pins and copy_source.

2. P3, fix here. No test restores a non-shape file from history. Three mutants of that walk (:1173, :1317, :1320) pass all 10 new tests.

3. P3, follow-up. Restoring a leg pin from history ignores the gitlink. After a pin broken in its bump commit is put back, pins reports pin-gitlink-mismatch, and the note says "Commit that" (:1324-1329).

4. P3, follow-up, also on main. After the unmerged NEXT, the doctor says COMPLIANT, exit 0, while the pin and the gitlink are still unmerged.

5. nits. The non-mapping wording is untested. The PR body leaves out hidden, and its merge table is stale.

Tests:

• head:
  • tests/test_shape_doctor.py: 217 passed;
  • test_cli_reference, test_repo_hygiene, test_windows_paths and test_shape_advisory: 141 passed;
  • the 10 new tests on 8badae0's code: 10 failed, for the issue's reason.
• head merged with ab623dd, with the planned resolution:
  • tests/test_shape_doctor.py: 291 passed, 3 skipped;
  • the same four files: 141 passed.
• render-cli-reference.py --check: ok on both.

Merges:

• Against main, shape-doctor.py: a validator that crashed says it crashed instead of "reports a finding", and is CANNOT ANSWER when it is the standard's template, which a standard whose path holds the PYTHONPATH separator no longer runs at all; a neutral product's digest validate-pins.py skipped is a note naming the product, from a child that can no longer reach gh or a proxy; and a root whose manifest does not load and whose scripts/repo_shape.py is gone is told to restore that file before its gate (#278, #297, #298) #357, shape-doctor.py: the legs and members NEXT is a script-free git submodule update --init --recursive over what a checkout cures, and the lockstep gate for what none does, so a root that lost scripts/bootstrap.py no longer pastes can't open file, and an empty mount or a leg committed past its pin on its tracking branch no longer pastes a bootstrap that leaves the row red (#276) #354, 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, update-shape.py read_pin refuses update-pin-row, and the pinned validate-pins.py and validate-family.py report shape-pin-row, when a shape pin's files: is not a list, so files: 5, true or 1.5 no longer ends check, apply, shape-doctor.py and the project's own validator in TypeError: ... is not iterable (#290) #343 and adopt-project.py: a relative .gitmodules url the plan keeps in a leg is resolved from the source's remote and from the leg's, and where the two differ check finds it and execute refuses before any leg exists, so a recursive clone no longer fails after adoption verified (#190) #245: rc 1, the same 4 check_manifest_kinds hunks.
• The planned resolution is right. The resolved tree merges rc 0 with all of them and with shape-doctor.py: a root's own contracts/shape-pin.yaml that does not read as a pin (a merge conflict, a non-UTF-8 byte, a commit: that is not 40 hex, a deleted file) is INVALID, exit 1, with the git command that puts back the last pin a tool wrote as its NEXT, instead of CANNOT ANSWER, exit 3, sending the reader to git fetch --all in the standard (#237) #267.

The full report is in opensoft/brett-wip at handoffs/xFactory/attachments/lane-openRepoShape-2/review358-ebffb08/final-report.md.

[brettheap]

(lane openRepoShape-2, 2026-10-12T22:15Z)

This lane re-verified its own PR #358 at a5563c3, read-only in its own detached worktrees, with nothing authored.

MERGEABLE WITH NITS, to land after Brett rules on F1.

rv358's three findings are fixed: every NEXT for P10 to P13 ran as pasted and left the person's edit byte for byte.

• F1, P1-class, pre-existing on main (shape-doctor.py: a root's own contracts/shape-pin.yaml that does not read as a pin (a merge conflict, a non-UTF-8 byte, a commit: that is not 40 hex, a deleted file) is INVALID, exit 1, with the git command that puts back the last pin a tool wrote as its NEXT, instead of CANNOT ANSWER, exit 3, sending the reader to git fetch --all in the standard (#237) #267). When the shape pin is conflicted too, shape-doctor.py:2364-2407 still takes the copies of the side it keeps whole. With the update side as ours, an --accept-local edit of the naming copy or the Makefile is dropped, and the doctor then says COMPLIANT. Main 36538fd does the same, and this PR narrows it. Fixing it here (f358's small change) or next on Tracking: shape-doctor.py, reporting a repository's compliance #460 is Brett's call.
• F2, P3: in that state the manifest kinds detail calls the copy project while its NEXT overwrites it.
• N1, nit: a doubled "so" in the neutral pin's notes (shape-doctor.py:2361, 2445).
• N2, nit: pinned_copies still catches TypeError (shape-doctor.py:2502), for whichever of update-shape.py read_pin refuses update-pin-row, and the pinned validate-pins.py and validate-family.py report shape-pin-row, when a shape pin's files: is not a list, so files: 5, true or 1.5 no longer ends check, apply, shape-doctor.py and the project's own validator in TypeError: ... is not iterable (#290) #343 and shape-doctor.py: the manifest kinds row puts back a shape or leg pin under contracts/ that does not load with the git command pin_restore picks from its own state, shows a copy the shape pin has a row for or a neutral product pin with a read-only git diff, and leaves any other file to a person whatever it is called, so its NEXT no longer tells the reader to delete the pin (#291) #358 lands second.

Tests:

• at a5563c3, the update-shape, rows, advisory, cli and hygiene files: 382 passed, 3 skipped;
• with update-shape.py read_pin refuses update-pin-row, and the pinned validate-pins.py and validate-family.py report shape-pin-row, when a shape pin's files: is not a list, so files: 5, true or 1.5 no longer ends check, apply, shape-doctor.py and the project's own validator in TypeError: ... is not iterable (#290) #343 91a4a4f and the documented resolution: 357 passed, 3 skipped;
• with 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: 60 passed.

Merges: b88aa65 and a5563c3 keep #267's, #404's and #346's lines one for one. merge-tree is rc 0 with main d6df36b, with 36538fd and with #347, and rc 1 with #343 in pin_at only.

The full report is handoffs/xFactory/attachments/lane-openRepoShape-2/review358-a5563c3/final-report.md in opensoft/brett-wip.

[sonarqubecloud]

Quality Gate passed

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