[brettheap]

Lane: openreposhape-2 (openRepoShape-2)
Claim: #237 (comment)

What

shape-doctor.py's check_shape_currency no longer treats a fault in the ROOT's own contracts/shape-pin.yaml as this checkout failing to ask. The row's NEXT is now the git command that puts back the last pin a tool wrote.

• The pin is read first, on its own. The read uses update-shape.py's read_pin, the function prepare calls for it. A refusal from that read becomes the new unreadable_pin_row:
  • a FINDING with no environment;
  • the reason the copies cannot be compared, because contracts/shape-pin.yaml does not read as a pin: REFUSED <code>: <detail>;
  • detail = {error, pin, refusal: {code, detail}, restore}, plus left_for_a_person where a merge left one of the project's files conflicted (below).
• Refusals about this checkout are unchanged. A refusal from anything prepare does after that read (open_upstream, Upstream.resolve) is caught exactly as before. Those cover a pinned commit missing from this standard and a standard that cannot be read. They give CANNOT ANSWER, exit 3, environment: True and the fetch --all NEXT. The split is made by which read raised, not by a list of refusal codes and not by text. A refusal added later to either side therefore lands correctly without this file being told.
• The NEXT comes from the pin's own git state. The new pin_restore reads that state without writing anything: git --no-optional-locks status --porcelain=v1 read as bytes, ls-files -u, rev-list, and cat-file blob read in memory. It records the case as detail.restore, and the first case that applies decides:
  • unmerged: a merge left the pin conflicted. The NEXT is git -C <root> checkout --ours -- <paths>. The paths are every conflicted path the shape writes whole: the pin, the copies and their collision copies. Where only the other side's index stage holds a pin (DU, UA), the NEXT is --theirs.
    • The manifest and README.md are never named. apply writes two lines of the manifest's shape: block and README's Shape: line, and every other line is the project's own, so taking either file whole would drop the other side's edits, hunks git merged cleanly included.
    • Where either is conflicted, the note says a person merges it, keeping the lines update-shape.py writes from the side taken, and detail.left_for_a_person lists it. shape-doctor.py: a project.yaml or family.yaml that is there and does not load is INVALID (manifest) or INVALID (family), exit 1, quoting load_yaml's own refusal and naming the project's own validator, instead of NOT A SHAPE ROOT, exit 2, with an adopt-project.py plan NEXT and a Triad row calling an assembly root a single repository (#205) #232's manifest row says the same of that file.
    • A file of the project's own is never named.
  • uncommitted: HEAD holds a pin that reads, and the tree or the index differs from it. The NEXT is git -C <root> checkout HEAD -- contracts/shape-pin.yaml.
  • hidden: HEAD holds a pin that reads, and git status shows no change to the pin. An index flag hides the copy (a sparse checkout's skip-worktree, or assume-unchanged), or the file itself cannot be read. No commit broke it, so the NEXT names no rollback: it is git -C <root> ls-files -v -- contracts/shape-pin.yaml, which prints the S or h, and its note says clearing that is for a person.
  • committed: a commit broke or removed the pin. The NEXT is git -C <root> checkout <that commit>~1 -- contracts/shape-pin.yaml. The pin's history is walked newest first (at most 50 commits), and the commit named is the first whose parent holds a pin that reads, so two commits in a row that each broke the pin are reached past. This case also covers a bad pin staged where HEAD holds none (A ).
  • none: no history to restore from (a root commit, no git, a walk that meets a parent with no pin). The NEXT stays update-shape.py check --root <root> --upstream <standard>, and its note says that whether the root was ever scaffolded or adopted is for a person to decide.
  • Every pin the NEXT puts back out of history is read first (pin_reads_at): cat-file blob in memory, never a temporary file, decoded and parsed as load_yaml reads a file, then check_pin. That is read_pin's own checks, split out of it in update-shape.py so the two cannot disagree about a pin.
  • No note carries a ;, an apostrophe or a backtick, so a pasted line is one command in any shell (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).
• The verdict ladder is untouched. With no environment, it reaches the gates that are red:
  • INVALID (pins, manifest-kinds) for a conflicted pin;
  • INVALID (pins) for a commit: that is not 40 hex;
  • INVALID (shape-currency), through the catch-all, where this row is the only red one.

The reason follows #232's wording for an unloadable manifest: the loader's own REFUSED <code>: <detail> line without its Remediation: trailer. For yaml-unparsable, that trailer is about submodules. --help is unchanged, so docs/cli.md is too (render-cli-reference.py --check passes). In update-shape.py, the only change is that read_pin's checks move into check_pin(pin, pin_path), which read_pin calls; its behaviour is unchanged.

Why

On main, each of these root-side faults answered CANNOT ANSWER, exit 3, which outranks INVALID, with git -C <standard> fetch --all as its NEXT:

• a merge conflict in a root's contracts/shape-pin.yaml (the realistic merge of two shape updates);
• a commit: that is not 40 hex;
• a deleted pin;
• a non-UTF-8 byte.

AGENTS.md says exit 3 is "THIS CHECKOUT failing to ask, never a statement about their repository". A reader therefore followed it to a fetch that succeeds and changes nothing.

Reproduced on main 39ac59c with the issue's own steps (scaffolded Atlas, two branches rewriting commit:, git merge):

• the verdict is CANNOT ANSWER (shape currency: ... line 30: merge keys are not supported), exit 3;
• stderr carries REFUSED shape-doctor-cannot-answer with the fetch --all remediation;
• the --json detail is {"error": "yaml-unparsable", "environment": true}.

On this head the same tree reads INVALID (pins, manifest-kinds), exit 1, with nothing on stderr.

The NEXT is a git command, not a tool of this standard. validate-pins.py (the issue's suggestion) and update-shape.py check (this PR's first head) both read the pin with the same loader, so run as printed each refuses it again. update-shape.py's remediation for the case is also wrong for it: git submodule update for a conflict, "adopt it" for a deleted pin, and "re-save the file" (a hand edit of a pinned file) for a stray byte. A pin is never mended by hand, so the fix is the last pin a tool wrote, taken from the root's own history. The pins row still names validate-pins.py wherever it is red.

Tests

tests/test_shape_doctor.py gains 26 tests. They sit beside test_a_pin_this_standard_cannot_resolve_is_exit_three, which is untouched and still passes.

• Nine ways the root's pin can fail, in one parametrised test. The faults: a merge conflict, not YAML at all, a non-UTF-8 byte, a list not a mapping, commit: not 40 hex, another digest_definition, files: [], a row with no path, a deleted file. Each case asserts:
  • the refusal code, in detail.error and detail.refusal.code;
  • FINDING, exit 1, an INVALID ( verdict and no environment;
  • the REFUSED line quoted without its remediation;
  • detail.restore uncommitted, and a NEXT of git -C <root> checkout HEAD -- contracts/shape-pin.yaml, with no fetch, no update-shape.py and a plain note;
  • in the text report, no CANNOT ANSWER, and no shape-doctor-cannot-answer or fetch --all on stderr;
  • that the NEXT, run as printed, makes the doctor exit 0 with COMPLIANT. "As printed" means shlex on POSIX and PowerShell's tokens on Windows.
• The conflicted pin's other rows. The pins row still names validate-pins.py, and the verdict is INVALID (pins, manifest-kinds).
• digest_definition: other-v9. The shape-currency row is the one red row: INVALID (shape-currency).
• The control pair. It uses one standard that lacks the scaffold's commit.
  • With a good pin: CANNOT ANSWER, exit 3, fetch --all, and detail.error update-revision-unresolvable with environment.
  • With a conflicted pin on the same root: INVALID, exit 1.
• A family holder's conflicted pin. It is INVALID and uncommitted, and its NEXT, run as printed, makes the pin read again.
• Two faults committed and followed by an unrelated commit. One is a git rm of the pin; the other is a commit: "zzzz". Each gives committed and checkout <breaking commit>~1 -- contracts/shape-pin.yaml, and ends COMPLIANT once that has run.
• Two commits in a row that each broke the pin (commit: "zzzz", then commit: "yyyy"). The NEXT names the first break's ~1, and ends COMPLIANT.
• A further uncommitted change over a committed break. HEAD's pin does not read either, so the NEXT is committed (the pin before the break), not checkout HEAD, and it ends COMPLIANT.
• The issue's own merge. Makefile and a file of the project's own are UU beside the pin. The row gives unmerged and checkout --ours -- Makefile contracts/shape-pin.yaml, with no left_for_a_person. The project's own file is left conflicted. After the NEXT runs, the row reads the pin; with the fixture's made-up commits the row then says update-revision-unresolvable.
• The issue's merge with real re-pins. A copy of the standard gains two commits, and update-shape.py apply re-pins shape/a to the first and shape/b to the second. Shape/a also renames the project in project.yaml and adds a README paragraph; shape/a is merged into shape/b, leaving Makefile, the pin and project.yaml UU. The row (check_shape_currency, asked in process, because without shape-doctor.py: a project.yaml or family.yaml that is there and does not load is INVALID (manifest) or INVALID (family), exit 1, quoting load_yaml's own refusal and naming the project's own validator, instead of NOT A SHAPE ROOT, exit 2, with an adopt-project.py plan NEXT and a Triad row calling an assembly root a single repository (#205) #232 a conflicted project.yaml is NOT A SHAPE ROOT) gives checkout --ours -- Makefile contracts/shape-pin.yaml and left_for_a_person: ["project.yaml"], and its note names project.yaml. Run as printed, it keeps the rename and the README paragraph, and the row reads the pin. A person's merge of project.yaml (git merge-file --ours over git's three stages) and the merge commit keep the rename in HEAD:project.yaml, and the doctor then says COMPLIANT, exit 0.
• README.md conflicted over the project's own first line, with a paragraph the other side added that git merges cleanly. The NEXT takes the pin alone, the note and left_for_a_person name README.md, and after it runs the paragraph is still there and the row reads the pin.
• Assume-unchanged over a broken copy, and a sparse checkout that leaves the pin out, each after a second good commit to the pin. Each gives hidden, names no checkout, and its NEXT, run as printed, prints h contracts/shape-pin.yaml or S contracts/shape-pin.yaml.
• A : a bad pin staged after a commit deleted it. It gives committed and checkout <deleting commit>~1, and ends COMPLIANT.
• DU: this branch deleted the pin, the other side changed it. It gives checkout --theirs, the note says only that side holds a pin, and the pin reads after the NEXT runs.
• A squashed root commit holding a bad pin. It gives none and the update-shape.py check NEXT, with no checkout.
• The doctor never writes the root's index. After a committed break, every tracked file is made stat-dirty. The doctor runs, and .git/index is byte-identical afterwards. A plain git status then rewrites it, as the control.

Counts at head 8badae0:

• tests/test_shape_doctor.py: 207 passed (181 on main 39ac59c);
• tests/test_cli_reference.py and tests/test_repo_hygiene.py: 63 passed;
• tests/test_update_shape.py, test_update_shape_add.py and test_update_shape_add_ignored.py: 120 passed (update-shape.py changed: check_pin);
• render-cli-reference.py --check: ok.

Against older code:

• Main's code (a scratch clone at 39ac59c with the first head's test file): the first 13 tests fail, every one at assert 3 == 1, and the existing control passes.
• The first head's code, 092a5f9 (fix round 1's test file): of the 20 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 tests then, 16 fail, each at KeyError: 'restore'. That head's NEXT, run as printed, exits 2 with the same refusal in all nine uncommitted and both committed cases.
• Fix round 1's code, 9f64bd0 (this head's test file): six of the seven new tests fail, each for the review's reason.
  • The README case names README.md in the argv.
  • The real two-apply merge names project.yaml in the argv.
  • The two breaks name the second break's ~1.
  • The change over a committed break gives uncommitted.
  • Assume-unchanged and the sparse checkout give committed, a rollback of the good pin.
  • The index test passes there: it pins a property that code already has.

Mutants, each in its own scratch tree:

• The first head's five are each caught: the blanket environment: True, every refusal a finding, a fetch --all NEXT, the remediation quoted, and the split removed (which is main).
• Fix round 1's mutants, each run against the 20 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 tests then: the old NEXT restored (15 tests), HEAD in place of <last>~1 (3), every conflicted path named (1), and uncommitted without asking whether HEAD holds a pin (1). A fifth, the status .strip()ed before its two letters are read, cannot be caught, because it is equivalent: every code whose first letter is a space strips to one that takes the same branch, as a run over all 99 letter pairs shows.
• Fix round 2's nine, each run against the 10 tests that reach the merge, hidden and committed classes, are all caught:
  • --no-optional-locks dropped (the review's m7): the index test;
  • README.md or the manifest taken whole again (the review's m9, turned round): the README test, and the real two-apply merge;
  • the note's sentence about a person's merge dropped: both of those;
  • hidden unreachable: the assume-unchanged and sparse tests;
  • HEAD's pin trusted when held, not read: 4 tests;
  • the walk cut to the last commit, or a parent's pin trusted unread: the two breaks;
  • a pin parsed but not run through check_pin: 4 tests.

CI: tests, tests-macos and tests-windows were SUCCESS at 092a5f9 and at 9f64bd0. The new tests run each NEXT through pasted(), which reads it with PowerShell's tokens on Windows. CI must still confirm this head on macOS and Windows.

Composes with

git merge-tree --write-tree of this head (8badae0) with each head below gives rc 0 and no conflicting file:

• origin/main 34ecbc2, which carries shape-doctor.py: a project.yaml or family.yaml that is there and does not load is INVALID (manifest) or INVALID (family), exit 1, quoting load_yaml's own refusal and naming the project's own validator, instead of NOT A SHAPE ROOT, exit 2, with an adopt-project.py plan NEXT and a Triad row calling an assembly root a single repository (#205) #232 (d94d155) and shape-doctor.py: a validator row prints the PYTHONPATH it ran the standard's TEMPLATE copy under, in sh's or PowerShell's dialect, and runs the root's OWN copy under none, so the manifest, pins and family rows' NEXT, pasted anywhere, prints the validator's own finding and exits with detail.exit instead of dying on ModuleNotFoundError: No module named 'repo_shape', and a root that lost its own repo_shape.py is no longer told its gate passes (#238) #287 (ede15ce). Merged tree 2b6fbf6.
  • Composed, tests/test_shape_doctor.py gives 268 passed and 3 skipped. The 3 skipped need a Windows host for PowerShell.
  • The realistic merge of two update-shape.py apply runs leaves Makefile, the pin and project.yaml all UU, and reads INVALID (manifest, manifest-kinds). The shape-currency row gives unmerged with checkout --ours -- Makefile contracts/shape-pin.yaml, and its note names project.yaml as a person's merge.
  • Where shape/a had also renamed the project, the rename is still there after the NEXT runs, and after the merge is finished as git says. The doctor stays INVALID (manifest) until a person merges project.yaml. Once that is done, it says COMPLIANT, exit 0.
  • On this branch alone, without shape-doctor.py: a project.yaml or family.yaml that is there and does not load is INVALID (manifest) or INVALID (family), exit 1, quoting load_yaml's own refusal and naming the project's own validator, instead of NOT A SHAPE ROOT, exit 2, with an adopt-project.py plan NEXT and a Triad row calling an assembly root a single repository (#205) #232, the same tree is NOT A SHAPE ROOT (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), and the row never runs.
• origin/main 87373a6, which main reached while this round ran. It carries shape-doctor.py: a validator's child gets exactly the PYTHONPATH its row's NEXT prints -- the standard's scripts/ alone for the template copy, none at all otherwise -- so an operator whose PYTHONPATH reaches a repo_shape.py is no longer told a root that lost its own scripts/repo_shape.py passes its gate, and the template run no longer keeps the operator's directories behind the standard's (#306) #311 and tests/conftest.py: git() runs git under a default identity given as -c config, never as environment, so the seven tests that commit through it with none of their own no longer die with Author identity unknown where git cannot work one out, and no call site's own -c user.name or exported identity is overridden (#279) #310 (tests/conftest.py's git()). Merged tree 443e329, and the 27 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 tests pass composed.
• shape-doctor.py: a validator's child gets exactly the PYTHONPATH its row's NEXT prints -- the standard's scripts/ alone for the template copy, none at all otherwise -- so an operator whose PYTHONPATH reaches a repo_shape.py is no longer told a root that lost its own scripts/repo_shape.py passes its gate, and the template run no longer keeps the operator's directories behind the standard's (#306) #311 at b30420f (lane openRepoShape-4, shape-doctor.py), since landed on main as 87373a6. It changes the validator rows' code (Context, run_validator, validator_command, validator_row), not the shape-currency row.
• 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 at 441fedc (this lane, update-shape.py read_pin). It refuses a files: that is not a list. Merged, that check sits inside check_pin, so pin_reads_at makes it too.

Left out

• The manifest kinds row's NEXT for the same file (register the kind in MANIFEST_VALIDATORS ... or remove the file from the root). It tells the reader to remove an unreadable pin. It is that row's remedy, and 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 takes it.
• A pin whose files: is a scalar (files: 5). It raises a TypeError in read_pin, in this doctor and in validate-pins.py, as it does on main; 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 refuses it by name. pin_reads_at already counts that TypeError as a pin that does not read.
• Naming the manifest or README.md where the dropped side changed only the lines apply writes. The review offered it as an optional refinement, so a plain two-apply merge would stay one command. It is not taken. The plain merge now needs a person's merge of project.yaml too, and shape-doctor.py: a project.yaml or family.yaml that is there and does not load is INVALID (manifest) or INVALID (family), exit 1, quoting load_yaml's own refusal and naming the project's own validator, instead of NOT A SHAPE ROOT, exit 2, with an adopt-project.py plan NEXT and a Triad row calling an assembly root a single repository (#205) #232's manifest row names that.
• Preferring the side of a merge whose staged pin reads (the review's optional step for unmerged). It is not taken: either side is one tool's output, and a side that was committed broken reaches committed once the merge is finished.
• Leaving the merge. checkout --ours and --theirs leave git's index unmerged, so the note says to finish the merge as git says and run the doctor again.
• README and AGENTS.md are unchanged.
  • AGENTS.md's "THIS CHECKOUT failing to ask, never a statement about their repository" is what the doctor now does.
  • README's "names the exact command that fixes it" is now true of this row wherever the root's history holds a pin to put back. Where it holds none (restore: none), or a person must act first (hidden, a conflicted manifest or README), the note says so.
  • tests/test_repo_hygiene.py caps the README at 1416 lines, which it already has.
• update-shape.py behaves as before. prepare still reads the pin itself, so on a good root the pin is read twice (one small YAML file).

Fix round 1

This round answers lane openRepoShape-2's review of 092a5f9 (CHANGES NEEDED): #267 (comment)

• F1 (P2), fixed in 7c11c62. The NEXT puts back the pin from the root's own history (pin_restore, above), and is no longer the update-shape.py check that refused it again.
• N1, fixed in 7c11c62. The docstring names "shape-doctor.py: a project.yaml or family.yaml that is there and does not load is INVALID (manifest) or INVALID (family), exit 1, quoting load_yaml's own refusal and naming the project's own validator, instead of NOT A SHAPE ROOT, exit 2, with an adopt-project.py plan NEXT and a Triad row calling an assembly root a single repository (#205) #232's unloaded_manifest_row".
• N2, fixed in 7c11c62. No note carries a ;, an apostrophe or a backtick. Every NEXT test asserts it.
• N3, fixed in this body. shape-doctor.py: a project.yaml or family.yaml that is there and does not load is INVALID (manifest) or INVALID (family), exit 1, quoting load_yaml's own refusal and naming the project's own validator, instead of NOT A SHAPE ROOT, exit 2, with an adopt-project.py plan NEXT and a Triad row calling an assembly root a single repository (#205) #232's head is b047658, and it has since landed on main as d94d155. The 092a5f9 CI is green on all three OSes.
• 9f64bd0 adds two tests. They cover the A and DU choices of pin_restore, which the first tests did not reach.
• The follow-ups (files: 5, and the manifest kinds NEXT) are left for separate issues.

Fix round 2

This round answers lane openRepoShape-2's re-verify of 9f64bd0 (CHANGES NEEDED): #267 (comment)

• V1 (P2), fixed in f80179c. The unmerged NEXT takes whole only the files the shape writes whole. A conflicted project.yaml or README.md is left to a person, named in the note and in detail.left_for_a_person, so the other side's own edits to it survive. Tested with the issue's own two-apply merge and the README case.
• V2 (P3), fixed in f80179c. Every pin the NEXT puts back out of history is read first, by read_pin's own checks (check_pin, split out in update-shape.py).
  • A sparse checkout or assume-unchanged over a good pin is the new hidden class, and no rollback is named.
  • Two commits in a row that each broke the pin are reached past, so the NEXT no longer cycles.
  • uncommitted also needs HEAD's pin to read (the review's optional step).
• V3 (nit), fixed in 8badae0. A test pins --no-optional-locks: the doctor leaves a stat-dirty index byte for byte as it found it.
• pin_restore(ctx) still answers (restore, command). It gains an optional detail, which it writes left_for_a_person into. A call written against 9f64bd0, as 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 (stacked there) makes, still works.

Review

Lane openRepoShape-2's own review of 092a5f9 and its re-verify of 9f64bd0 asked for changes, and the two fix rounds above answer them. A review by another lane is welcome. Lane openRepoShape-4's #311 sits in the same file.

Closes #237

🤖 Generated with Claude Code

Summary by Sourcery

Report unreadable root pins as repository-invalid findings and provide safe, state-aware commands to restore the last valid tool-written pin.

New Features:

• Distinguish unreadable root pins from environment-level shape currency failures and report them as invalid findings with actionable recovery commands.
• Determine safe pin restoration commands from the root repository's merge, working-tree, index, and commit history state.

Bug Fixes:

• Prevent malformed, conflicted, deleted, hidden, or otherwise unreadable root pins from incorrectly producing CANNOT ANSWER with a fetch recommendation.
• Avoid restoring a previously broken pin or overwriting project-owned edits during merge recovery.

Enhancements:

• Share pin validation between on-disk reads and in-memory historical Git blobs.
• Keep restoration diagnostics read-only, shell-safe, and explicit about files requiring manual merges.

Tests:

• Add comprehensive coverage for malformed root pins, Git restoration states, merge conflicts, hidden files, historical recovery, shell-pastable commands, and index preservation.

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

[brettheap]

(lane openRepoShape-2, 2026-10-11T22:49:02Z) @codex review

[sourcery-ai]

Reviewer's Guide

The PR makes root-side contracts/shape-pin.yaml read failures explicit repository findings that produce INVALID/exit 1 and an update-shape check remediation, while preserving CANNOT ANSWER/exit 3 for failures encountered while preparing or resolving the upstream standard; extensive tests verify both paths and their verdict/output details.

Sequence diagram for shape doctor refusal handling

sequenceDiagram
    participant Doctor as shape-doctor.py
    participant Update as update-shape.py
    participant Root as Root shape-pin.yaml
    participant Standard as Upstream standard

    Doctor->>Update: read_pin(root)
    Update->>Root: Read contracts/shape-pin.yaml
    alt Root pin refuses
        Update-->>Doctor: Refusal(code, detail)
        Doctor->>Doctor: unreadable_pin_row()
        Doctor-->>Doctor: INVALID, exit 1
        Doctor-->>Doctor: NEXT update-shape.py check
    else Root pin reads
        Doctor->>Update: prepare(args)
        Update->>Standard: open_upstream()
        alt Upstream preparation refuses
            Standard-->>Update: Refusal(code, detail)
            Update-->>Doctor: Refusal
            Doctor-->>Doctor: CANNOT ANSWER, exit 3
            Doctor-->>Doctor: NEXT git fetch --all
        else Preparation succeeds
            Update-->>Doctor: Prepared comparison data
        end
    end

Loading

Flow diagram for shape pin refusal classification

flowchart TD
    A[check_shape_currency] --> B[read_pin root contracts/shape-pin.yaml]
    B -->|Refusal| C[unreadable_pin_row]
    C --> D[INVALID exit 1]
    C --> E[Next: update-shape.py check]
    B -->|Success| F[prepare]
    F -->|Upstream refusal| G[CANNOT ANSWER exit 3]
    G --> H[Next: git fetch --all]
    F -->|Success| I[Compare shape currency]

Loading

File-Level Changes

Change	Details	Files
Classify failures while reading the root checkout's own shape pin as repository-invalid findings instead of environment-level inability to answer.	Read the root pin explicitly before invoking the broader update-shape preparation flow. Convert any root-pin Refusal into a finding without environment metadata, preserving structured refusal details. Keep downstream preparation refusals as CANNOT ANSWER with exit 3 and fetch guidance by separating the two paths based on which read raised. Add a shared pin path and generate an update-shape check NEXT that identifies the faulty file while omitting fetch/remediation wording.	shape-doctor.py
Add regression coverage for root-pin refusal classification, output details, remediation guidance, verdict precedence, and control behavior.	Cover nine malformed, invalid, unsupported, and missing root-pin cases with assertions for exit 1, INVALID, FINDING, refusal details, and no environment/fetch messaging. Verify existing validator rows and verdict combinations remain correct, including the catch-all shape-currency verdict. Retain coverage proving standard-side resolution failures remain CANNOT ANSWER with exit 3 and fetch guidance. Cover family roots and distinguish root-pin failures from an otherwise identical standard-side failure.	tests/test_shape_doctor.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#237	Classify refusals caused by the root's own contracts/shape-pin.yaml as an INVALID finding rather than CANNOT ANSWER, without marking them as environment failures.	✅
#237	Continue classifying refusals caused by the standard or an unresolvable pinned revision as CANNOT ANSWER with exit 3 and the fetch --all remediation.	✅
#237	Provide an appropriate remediation and regression coverage for root-pin failures, including malformed, invalid, missing, conflicted, and non-UTF-8 pins, while preserving the existing validator and control-case behavior.	✅

Possibly linked issues

• 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: The PR exactly addresses issue 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 by separating root pin failures from standard resolution failures and adding comprehensive 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.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 092a5f914d

ℹ️ 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]

Replace the self-refusing NEXT with an actionable repair

For every pin fault routed here—such as a deleted, conflicted, non-UTF-8, or unsupported-digest pin—this advertised NEXT immediately calls read_pin again and exits with the same refusal, without repairing or recovering anything. A user following the report therefore reaches a dead end and must improvise a hand edit, even though repository guidance requires each finding to name the exact fixing command and explicitly prohibits hand-editing a pin to clear a finding. Provide a recovery action tailored to the refusal, or add a safe repair workflow rather than presenting update-shape.py check as the next step.

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

Useful? React with 👍 / 👎.

[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	⚠️ Failed 2026-10-12T12:38:12.749007Z	8badae0	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.

[brettheap]

(lane openRepoShape-2, 2026-10-11T23:50:12Z)

This lane reviewed its own PR #267 at 092a5f9, before any fix round, read-only in its own detached worktrees.

CHANGES NEEDED. Fixes come as commits on this branch.

P2: the new NEXT does not fix anything (shape-doctor.py:1131-1138). update-shape.py check calls read_pin again, so in all 15 probed faults it exits 2 with the same refusal. The remediation it then prints is wrong for the case:

• git submodule update --init --recursive for six codes, the trailer the row's own docstring (:1105-1112) strips as misleading;
• "adopted with adopt-project.py" for a deleted pin (update-shape.py:381-383);
• "re-save the file" (a hand edit) for a non-UTF-8 byte.

An operator following AGENTS.md:207-213 is stuck; README.md:1131-1132 is false here. A git restore makes every class compliant with no hand edit:

• checkout HEAD -- for an uncommitted change (11 fixtures);
• checkout <last>~1 -- for a committed one (4);
• checkout --ours/--theirs for a merge, which on the realistic two-apply merge gives COMPLIANT, SHAPE BEHIND.

The fix round picks the command from git status --porcelain on the pin.

Nits.

• :1111 names unloaded_manifest_row, which only shape-doctor.py: a project.yaml or family.yaml that is there and does not load is INVALID (manifest) or INVALID (family), exit 1, quoting load_yaml's own refusal and naming the project's own validator, instead of NOT A SHAPE ROOT, exit 2, with an adopt-project.py plan NEXT and a Triad row calling an assembly root a single repository (#205) #232 has.
• The NEXT's tail carries a ; and an apostrophe (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's pattern).
• The PR body is stale on shape-doctor.py: a project.yaml or family.yaml that is there and does not load is INVALID (manifest) or INVALID (family), exit 1, quoting load_yaml's own refusal and naming the project's own validator, instead of NOT A SHAPE ROOT, exit 2, with an adopt-project.py plan NEXT and a Triad row calling an assembly root a single repository (#205) #232's head (b047658) and on macOS/Windows CI, which is green.

Follow-ups, pre-existing.

• files: 5 crashes the doctor, update-shape.py and validate-pins.py with a TypeError (update-shape.py:404).
• The manifest kinds row tells the reader to remove an unreadable pin (:997-999).

Also checked.

• No legitimate root lacks a pin: the root's own validator refuses one without it since v0.
• read_pin and prepare cannot disagree on a refusal.
• Windows quoting holds.
• The 13 new tests fail on main at assert 3 == 1, and 3 mutants are killed.

Tests. Head: test_shape_doctor.py, test_cli_reference.py and test_repo_hygiene.py, 257 passed. Merged with main c3f4987: test_shape_doctor.py, 204 passed. render-cli-reference.py --check ok.

Merges. merge-tree with main, #232 b047658, 88c81e0, 2f5cda9, #245 1abe078, #264, #266, #268, #269 and #270: all clean.

Main reached 67a398a mid-review; none of its five new commits touches these files.

The full report is handoffs/xFactory/attachments/lane-openRepoShape-2/review267-092a5f9/final-report.md in opensoft/brett-wip.

[brettheap]

(lane openRepoShape-2, 2026-10-12T11:41:04Z)

This lane re-verified its own PR #267 at 9f64bd0 after fix round 1, read-only in its own detached worktrees.

CHANGES NEEDED.

• V1 (P2), shape-doctor.py:1147: the merge NEXT takes project.yaml and README.md whole. Composed with main, the issue's own two-apply merge loses the other branch's name: edit, which git had merged cleanly. The doctor then says COMPLIANT, and once the merge is committed git merge calls that branch merged. At 9f64bd0 alone, a README conflicted only over project lines is also taken whole. This lane's first-pass fix list asked for both files. Fix: name only the files the shape writes whole, and leave the manifest and README to a person, as the manifest row already does.
• V2 (P3), shape-doctor.py:1181-1188: the committed NEXT never reads the pins it trusts. A pin hidden by a sparse checkout or assume-unchanged rolls back a good re-pin (DRIFTED). Two successive broken commits cycle between checkout <last>~1 and checkout HEAD.
• V3 (nit): no test pins --no-optional-locks. Mutant m7 survives, and a scratch test kills it. m6 is equivalent. m9 is V1's fix direction.

Tests: head, 263 passed (doctor, cli-reference, hygiene). Head merged into main c7c02fa: tests/test_shape_doctor.py 261 passed, 3 skipped (Windows-only). With #311: the 20 #237 tests passed.

CI at 9f64bd0: tests, tests-macos, tests-windows and SonarCloud pass.

Merges: rc 0 with main c7c02fa and all 16 other open PRs.

The report is handoffs/xFactory/attachments/lane-openRepoShape-2/review267-092a5f9/reverify-1.md in opensoft/brett-wip.

[brettheap]

(lane openRepoShape-2, 2026-10-12T12:30Z)

Fix round 2 is pushed: 8badae0 (9f64bd0..8badae0). It answers the re-verify of 9f64bd0 (CHANGES NEEDED, #267 (comment)):

• V1 (P2), fixed in f80179c. The unmerged NEXT takes whole only the pin and the copies. A conflicted project.yaml or README.md is named in the note and in detail.left_for_a_person, so the other side's edits survive.
• V2 (P3), fixed in f80179c. Every pin the NEXT puts back is read first, with read_pin's checks split out as check_pin.
  • A sparse checkout or assume-unchanged over a good pin is a new hidden class.
  • Two breaking commits in a row are reached past.
  • uncommitted needs HEAD's pin to read.
• V3 (nit), fixed in 8badae0. A test pins --no-optional-locks.

Tests:

• At 9f64bd0, the six new behavioural tests fail for the review's reasons.
• At 8badae0: doctor 207, cli + hygiene 63, update-shape 120; render check ok.
• Merged with main 34ecbc2: 268 passed, 3 skipped.
• 9 of 9 mutants are killed.
• git merge-tree is clean against main 87373a6, shape-doctor.py: a validator's child gets exactly the PYTHONPATH its row's NEXT prints -- the standard's scripts/ alone for the template copy, none at all otherwise -- so an operator whose PYTHONPATH reaches a repo_shape.py is no longer told a root that lost its own scripts/repo_shape.py passes its gate, and the template run no longer keeps the operator's directories behind the standard's (#306) #311 b30420f and 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 441fedc.

The PR body is updated, with a "Fix round 2" section. This lane re-verifies 8badae0 after its usage window resets.

@codex review

Lane: openreposhape-2 (openRepoShape-2)

[chatgpt-codex-connector]

Codex Review: Something went wrong. Try again later by commenting “@codex review”.

An unknown error occurred

ℹ️ 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".

[brettheap]

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

Composition note: #343 and this PR conflict semantically, though git merge-tree is rc 0. #343 (039530b) makes update-pin-row's remediation pin_rows_remediation(root), so it prints git -C <root> log. This PR moves those raises into check_pin(pin, pin_path), which has no root. So the merged tree dies with NameError: name 'root' is not defined. #343's test file then fails 14 of 22.

Whichever of #267 and #343 lands second applies three lines:

• check_pin takes root;
• read_pin passes root;
• pin_reads_at passes ctx.root.

On a scratch merge, that gives 22 passed in #343's file and 12 in this PR's doctor tests. The patch is tools/fix1-compose-267-resolution.patch in lane 2's attachments (impl290-pin-files-list), and #343's body, under Composes with, says the same.

Lane: openreposhape-2 (openRepoShape-2)

[sonarqubecloud]

Quality Gate passed

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

[brettheap]

(lane openRepoShape-3, 2026-10-12T19:52:17Z) A v1.0.0 scope notice. Brett Heap scoped openRepoShape's first release today: 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 a full test run to pass on all three OSes on the release commit. This PR closes #237 (P2, parent #460): in scope, in the v1.0.0 milestone. Nothing changes in how it lands. Known-limit issues stay open, without the milestone, under their area's parent.