[brettheap]

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

What

A shape pin whose files: is not a list is now refused or reported by name in all four places that read it, instead of being iterated:

reader	files: 5 / true / 1.5 before	now
update-shape.py read_pin: check, apply, and the doctor's shape-currency row	TypeError: 'int' ('bool', 'float') object is not iterable, exit 1	REFUSED update-pin-row: <pin>: `files:` is 5, not a list of `path:`/`sha256:` rows, so no copied file can be read from it, exit 2, and a remediation about the pin that names git -C <root> log -- contracts/shape-pin.yaml
templates/assembly-root/scripts/validate-pins.py _check_shape_pin (the root's own validator)	the same TypeError, exit 1	one FINDING shape-pin-row: contracts/shape-pin.yaml: `files:` is 5, not a list ..., exit 1
templates/family-root/scripts/validate-family.py _check_shape_pin_files (the holder's own validator)	the same TypeError, exit 1	the same one shape-pin-row finding, exit 1
shape-doctor.py pinned_paths	the same TypeError (masked while read_pin crashed first)	the empty set, as for a pin that is not a mapping

shape-doctor.py therefore prints a report again for such a root. Its shape-currency row carries the refusal, and its pins (or family) row carries the validator's finding. Main now carries #267 (decff87), so the verdict is INVALID, exit 1, and the shape-currency row's NEXT is the git command that puts back the last pin that reads (checkout HEAD for an uncommitted break, checkout '<bad>~1' for a committed one). Before #267 it was CANNOT ANSWER, exit 3. Neither verdict is set here: #267 sets them.

Two choices made in read_pin:

• The falsy values are unchanged. files: 0, false, null and [] keep update-pin-no-files and shape-pin-no-files. The issue left this to the author, and the guard only covers what or [] let through. A control test holds this.
• Both update-pin-row raises carry pin_rows_remediation(root). Since 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 they sit in check_pin, which now takes the root for it (see "Merged main after 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 landed"). It says: put back the pin a tool last wrote, from the root's own history (git -C <root> log -- contracts/shape-pin.yaml names the commit that changed it), and run again. Before this, they printed repo_shape's default trailer, which is about git submodule update and the lockstep invariant. The doctor's row quotes only the refusal's detail, never its remediation.

Another change you can see: a string files: abc used to produce one shape-pin-row finding per character (three). It now produces one finding, and update-shape.py keeps the same id, update-pin-row, with a message that names files:.

Why

Every reader took pin.get("files") or [] and looped over it. or [] catches the falsy values, so they reach the no files refusal or finding. A truthy scalar got through and was iterated. On main 71b58a1, files: 5 committed over a clean scaffold made shape-doctor.py exit 1 with nothing on stdout. The doctor exists to say what is wrong, and here it said nothing.

The two validators are pinned template copies (COPIED_VERBATIM, FAMILY_COPIED_VERBATIM), so this changes their digests. Main has changed both files too since this branch began (#446 validate-pins.py, #406 validate-family.py), so the digests below are named per revision:

• This repository records no digest of either file. git grep -E '\b[0-9a-f]{64}\b' at this head finds only the actionlint download checksum in .github/workflows/tests.yml. A scaffold, an adoption or a family.py init computes the digest of the bytes it copies.
• New projects record the new digest. A scaffold made from main 580d7df records scripts/validate-pins.py as 56c122cd…, and one made from this head, e68a01d, records 5f5b992a…. Each is the sha256 of the template at that revision. For scripts/validate-family.py the two are 94a7b837… and 29f05dbc…. (Before the main merge: 61f13a77… at 71b58a1 and c909bddc… at 9e6caeb for validate-pins.py; 905887a6… and 758a0959… for validate-family.py.)
• Existing projects see one upstream-changed row until they run apply. Checked before the main merge, against 441fedc (whose validators are byte-identical to 9e6caeb's): a project cut at 71b58a1 gets upstream-changed 1 / unchanged 10 (scripts/validate-pins.py), and a holder gets upstream-changed 1 / unchanged 9 (scripts/validate-family.py). apply moves the row to c909bddc…, and the project's validate-pins.py then says pins ok.
• update-shape.py and shape-doctor.py are not pinned copies, and scripts/repo_shape.py is not touched.

Tests

tests/test_shape_pin_files_not_a_list.py (new): 28 tests. Most are parametrised over files: 5, files: true, files: 1.5 and files: abc. Each case commits that value over a clean scaffold (conftest project) or a holder made by family.py init.

• update-shape.py check and apply exit 2 with REFUSED update-pin-row, the value, the pin remediation with its git -C <root> log command, and no submodule. A refused apply leaves the pin's bytes unchanged.
• The command is computed in the test with shlex.join, as update-shape.py spells it, never written as a literal, so it holds on Windows, where a backslash path is quoted.
• One test runs the tool from the openRepoShape checkout (cwd is not the root) against a root whose path holds a space. It takes the printed command out of stderr, checks it is six words, runs it from the checkout, and requires every commit that touched the pin in the root to be in its output.
• One test covers the second update-pin-row raise (a files: list whose row is 5, not path:/sha256:), which had no test before.
• The root's scripts/validate-pins.py exits 1 with exactly one shape-pin-row finding.
• shape-doctor.py --json: the shape-currency row is a FINDING with error: update-pin-row, and the pins row names shape-pin-row. The text report shows the value and ends on a verdict line. The tests check the row, not the verdict.
• shape-doctor.py --json with no AGENTS.md: the agent-files row is reached, with pinned: [].
• pinned_paths on the scalar pin, in process, returns set().
• On a holder: validate-family.py gives one shape-pin-row finding, update-shape.py check refuses update-pin-row, and the doctor's shape-currency row and family row say the same.
• files: abc is the one value in that table that is iterable, so a guard written isinstance(files, (list, str)) lets it through and each reader takes its characters for rows. It is a case of its own in every parametrised test: each validator reports exactly one shape-pin-row finding, and update-shape.py refuses with the whole-files: message (`files:` is 'abc', not a list).
• Control: files: 0 and files: false still get update-pin-no-files and shape-pin-no-files.

Against main's code (origin/main 92e29d9, this test file copied onto it): 25 failed and 3 passed. 19 fail with the TypeError ('int', 'bool' or 'float' object is not iterable), 5 are files: abc (three findings from a validator where one is expected, or the per-row refusal where the whole-files: message is expected), and 1 is the non-mapping-row test, which wants this PR's pin remediation. The 3 that pass are the files: 0 and files: false controls, by design, and pinned_paths on abc, which iterates a string without error. This head merged with main 92e29d9 (no #267): 28 of 28 pass.

Mutants, scratch clones of 9e6caeb, the head before the main merge, run one at a time against the 28-test file (baseline 28 passed). Each isinstance(..., list) guard changed to if False:: read_pin → 17 failed, validate-pins.py → 7 failed, validate-family.py → 4 failed, pinned_paths → 6 failed. Each of those three guards widened to (list, str), which brings back one finding per character: validate-pins.py → 1 failed, read_pin → 4 failed, validate-family.py → 1 failed (all three passed the 22-test file at 039530b). For the remediation: dropping the -C <root> pair from the printed command → 10 failed; the second update-pin-row raise passing the wrong root → 1 failed (the non-mapping-row test, the only one that reaches it); the first raise losing its remediation → 9 failed. All ten are killed.

Targeted runs at 9e6caeb, before the main merge, with git-filter-repo on PATH, one file set per run (the runs at the merge head, e68a01d, are under "Merged main after #267 landed"):

• tests/test_shape_pin_files_not_a_list.py 28, tests/test_update_shape.py 77, tests/test_update_shape_add.py 17, tests/test_update_shape_add_ignored.py 26, tests/test_update_shape_landing.py 33, tests/test_update_shape_pr_base.py 27, tests/test_pin_validator.py 19, tests/test_neutral_pin_validator.py 11, tests/test_cli_reference.py 13, tests/test_repo_hygiene.py 50: 301 passed.
• tests/test_shape_doctor.py: 242 passed, 3 skipped.
• tests/test_family.py 99, tests/test_family_add_excludes.py 23, tests/test_family_add_refusals.py 37: 159 passed. These carry the shape-pin digest checks. A fresh scaffold's validate-pins.py (pins ok in test_pin_validator.py) and a fresh holder's validate-family.py (test_the_family_passes_its_own_gate) recompute every pin row, including the rows for the two changed validators. test_update_shape.py's apply cases leave the project's validators green.
• scripts/render-cli-reference.py --check: [ok]. No --help text changed.

tests/test_scaffold_e2e.py 44, tests/test_validator_child_encoding.py 51 and tests/test_windows_paths.py 38 passed at 441fedc together with test_family.py and test_family_add_refusals.py (269 passed). They were not repeated: git diff 441fedc 9e6caeb -- templates scripts is empty, and the commits since touch update-shape.py and the new test file only.

Composes with

git merge-tree --write-tree e68a01d <head>, run 2026-10-12T20:49Z, against this lane's open heads as the shared store had them at 20:4xZ (gh pr list was not re-read):

• rc 0: scaffold-project.py and family.py: --tracking-branch is asked of git check-ref-format --branch before anything exists, so ~, a..b, x.lock and a/ are refused under --dry-run and no longer die at the first git init -b after gh repo create has made the repositories (#283) #355 16073e2, scaffold-project.py: a leg path the project's own YAML reader would read back as another type (null, ~, true, False, 2026, 1.5) is refused before anything is created, under --dry-run alike, through the one definition adopt-project.py asks, so --spec-path 2026 no longer creates three repositories whose first bootstrap fails manifest-leg-path, and adopt-project.py execute no longer says adoption verified before that bootstrap fails (#225) #266 3410be7, 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 6d4e1e9, 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 d74d862, adopt-project.py: plan --help says what --spec-path and --code-path are, the default and key each records, and the two refusals plan makes on them, so docs/cli.md no longer lists the two flags that choose where a leg is mounted as bare lines (#340) #401 da27e69, 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 11dff7f (stacked on this PR) and 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 9423361.
• adopt-project.py: check finds, and execute refuses before any leg exists, a plan follow_ups: that is not a list of text and an elected_on: that election_date does not read, with or without a reference:, so follow_ups: 5 is no longer a traceback and elected_on: someday is no longer refused under a flag neither command takes (#293, #294) #356 10323a7 and adopt-project.py: check names, and execute refuses before the work directory is made, a plan whose source: or legs: is not a mapping or whose allow_empty_legs: or paths: is not a list of what plan writes, and asks the same first of a pins: that is not a list, so a number or a boolean in any of the four no longer ends both in a traceback and allow_empty_legs: code is no longer read as four legs (#386) #435 3efcc7a: rc 1 in adopt-project.py. Main 580d7df alone gives the same (adopt-project.py: every failure once a leg repository exists flushes stdout, then prints REFUSED <step>., what failed and one notice of what the run left, so a failed git filter-repo no longer exits 2 with an empty stderr (#171, #188, #177) #445), so this change does not cause it.
• 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 ce2ce75: rc 1 in shape-doctor.py, as against main 580d7df alone, and here also in update-shape.py and tests/test_shape_doctor.py. Those two conflicts lie exactly on this merge's composition lines. Both sides carry 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 text from merge base 5678f68, and this side adds root to check_pin and the three files: rows to ROOT_PIN_FAULTS. 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 keeps this side there. In pin_reads_at, which 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 rewrote to take a pin argument, it applies fix1-compose-343-resolution-358.patch (the lane's attachments, impl291-doctor-kinds-pin/tools/) instead of v2's hunk. Before this merge, x358 proved that variant on 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 together with this branch: the new file 28 passed, tests/test_shape_doctor.py 304 passed and 3 skipped, and the six tests/test_update_shape*.py files 223 passed and 3 skipped.
• 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 is no longer open. It landed as decff87, and this merge composes it (below). Before it landed, merge-tree called this branch 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 clean (rc 0) while the merged tree died at run time. A clean merge-tree is not the gate for this pair; CI on the merge head is.

Left out

• The doctor's verdict and NEXT for a root pin read_pin refuses. Those 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 / 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 (unreadable_pin_row and pin_restore), unchanged here. 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 on main the row is INVALID with a restore command, where it used to be CANNOT ANSWER with git -C <standard> fetch --all.
• Moving files: 0 and files: false to update-pin-row. They stay update-pin-no-files, as the issue allows.

Fix round 1

Answers the codex review comment on this PR, #343 (comment) (P2). The remediation printed a bare git log -- contracts/shape-pin.yaml. This tool is run from a checkout of openRepoShape with --root /path/to/project, so that command inspects the checkout, shows no pin history, and the person cannot follow the remediation.

• PIN_ROWS_REMEDIATION is now pin_rows_remediation(root), spelled with the module's own _by_hand(root, "log", "--", "contracts/shape-pin.yaml"), so it prints git -C <root> log -- contracts/shape-pin.yaml with the root quoted (a root holding a space is one argument). Both update-pin-row raises pass root. The rest of the text is unchanged.
• Reproduced first: with cwd outside the root, the old command shows 0 commits and git -C <root> log shows the root's 2. The tests fail at 6e2689a (8 of 22) for that reason and pass at 039530b (22 of 22). Dropping the -C <root> pair fails 8.
• Nothing else prints this remediation or an unqualified git log for this refusal: shape-doctor.py, validate-pins.py and validate-family.py carry none. The validators run inside the root by design.

Fix round 2 (review of 039530b)

• F1, composing 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: proved in this round, applied in the main merge e68a01d (below), after 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 landed as decff87. Where 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 is in the tree, v2's pin_reads_at hunk does not apply and fix1-compose-343-resolution-358.patch is the one to take (see Composes with).
• F2, a string files:, fixed in 7c998ff. files-abc is added to NOT_A_LIST, so the six parametrised tests run it. The three mutants that widen a guard to (list, str) passed all 22 tests at 039530b; at 9e6caeb they fail 1, 4 and 1.
• F3, Sonar S1192, fixed in 9e6caeb. pin_rows_remediation, cmd_apply and _awaits_its_pull_request spell the pin's path by the materializer's SHAPE_PIN, so the literal "contracts/shape-pin.yaml" appeared 0 times in update-shape.py at 9e6caeb (3 at 039530b). After the main merge it appears once, in _refuse_what_head_does_not_commit, which update-shape.py: a --pr re-run finishes the landing only when the working tree holds what HEAD commits at the pin, the manifest and every pinned copy, and is refused as update-rerun-uncommitted otherwise, so an in-place apply --at C left uncommitted on a branch that re-pins B no longer gets B pushed under a pull request titled C (#333) #379 added on main (main 580d7df has 3), so the module stays under S1192's three copies. The two root / "contracts" / "shape-pin.yaml" joins in read_pin and _repin are left alone: 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 rewrites the top of read_pin, and the import is its own line because update-shape.py and bump-leg.py: a pin rewrite keeps each line's own indentation, spacing and trailing comment and reads its result back before writing it, so a digests: child indented four spaces takes the update instead of update-pin-unrecognised / bump-leg-pin-unrecognised, and a # comment on commit: or tree_sha256: survives every pin rewrite, rewrite_manifest included (#323) #380 rewraps the import block.
• Not in this PR. The default git submodule update trailer on update-pin-no-files and read_pin's other refusals goes to repo_shape.py's Refusal gives every refusal built without a remediation the assembly root's own (run git submodule update --init --recursive, then python3 scripts/validate-pins.py ... contracts/<leg>-pin.yaml), so in a family holder family.py add over an unparsable .gitmodules (git-failed), bump on a family.yaml of the wrong kind, and the holder's own validate-family.py on a short pin.commit each tell the operator to run a file no holder carries and to move a leg pin a holder does not have #370. The doctor's NEXT for this refusal is 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 / 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.

Merged main after #267 landed

Merge commit e68a01d (parents 9e6caeb and main 580d7df, the shared store's origin/main at 20:45Z). This is the branch's first merge of main, so it brings everything since its base 71b58a1, #267 (decff87) among it. Since fix round 2's proof on main 92e29d9, the main commits that touch this PR's files are #267 and five more: #446 (245d775, validate-pins.py), #406 (ec8e09a, validate-family.py), #379 (87d2eb7, update-shape.py), and #375 (cd1fc79) and #357 (5678f68), both in shape-doctor.py. The textual merge was clean: merge-tree rc 0, and git merge --no-ff --no-commit stopped with no conflict. git diff --stat 580d7df e68a01d lists only this PR's six files.

Why not update-branch. #267 split read_pin into read_pin(root) and check_pin(pin, pin_path). The update-pin-row raises moved into check_pin, and on this branch they call pin_rows_remediation(root), where root is not a name. Shown on the unpatched merge, a scratch tree holding the same merge without the two patches:

• pyflakes: update-shape.py:468:34: undefined name 'root' and :474:48. The patched head gives no message.
• The new file plus 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 test_a_root_pin_that_does_not_read_is_invalid_not_cannot_answer: 19 failed and 18 passed. The new file has 18 failed and 10 passed, each of the 18 NameError: name 'root' is not defined. 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 own a-row-with-no-path case fails too: the doctor exits 1 with an empty stdout, so it has no report to read.

The resolution is the planned #267 composition from fix round 2 (fix1-compose-267-resolution-v2.patch and root-pin-faults-after-267.patch), applied unchanged. git apply --check was rc 0. Main moved the hunks by offset only: 526 lines in shape-doctor.py, 521 in tests/test_shape_doctor.py and 1 in update-shape.py. No hunk needed adapting, and neither module has changed on main since decff87. The patches make these changes:

• check_pin(pin, pin_path, root), with read_pin passing its root;
• pin_reads_at passes ctx.root, its docstring says files: 5 is an update-pin-row refusal, and TypeError leaves its except tuple;
• 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 ROOT_PIN_FAULTS gains files: 5, true and 1.5.

The only check_pin( callers are read_pin and pin_reads_at, and both pass three arguments.

Targeted runs at e68a01d use /usr/bin/python3 -m pytest -q -p no:cacheprovider -o tmp_path_retention_policy=failed, with git-filter-repo on PATH and a stub gh first:

• Run A: tests/test_shape_pin_files_not_a_list.py 28, tests/test_shape_doctor.py 297 (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 root-pin test now has 12 cases) and tests/test_doctor_validator_rows.py 28: 350 passed, 3 skipped, 0 failed.
• Run B: tests/test_update_shape.py 82, _add 17, _add_ignored 26, _add_symlink 41, _landing 41 and _pr_base 27; tests/test_validate_pins_without_git.py 58, tests/test_pin_validator.py 19 and tests/test_neutral_pin_validator.py 25; tests/test_validate_family_duplicates.py 20, _member_path_glob 21, _unnamed_mounts 39 and _without_git 14; tests/test_family.py 99, tests/test_family_add_excludes.py 23 and tests/test_family_add_refusals.py 65; tests/test_scaffold_e2e.py 44, tests/test_validator_child_encoding.py 55 and tests/test_windows_paths.py 38; tests/test_cli_reference.py 13 and tests/test_repo_hygiene.py 50: 814 passed, 3 skipped, 0 failed.
• scripts/render-cli-reference.py --check: [ok].

The pinned validators' digests move with main's own changes to them (see Why). CI on e68a01d, on all three OSes, is the gate.

Closes #290

🤖 Generated with Claude Code

Summary by Sourcery

Report malformed shape-pin files: values clearly across all readers instead of allowing them to crash validation and diagnostic commands.

Bug Fixes:

• Handle non-list shape-pin files: values consistently across update-shape.py, shape-doctor.py, and both pinned validators by reporting actionable refusals or findings instead of raising TypeError or iterating invalid values.

Enhancements:

• Keep shape-doctor reports available for malformed pins and treat non-list files: values as pinning no paths.
• Provide root-specific remediation that identifies the project history command for restoring malformed shape pins.
• Preserve existing no-files behavior for falsy files: values and report string scalars as a single malformed field.

Tests:

• Add comprehensive coverage for scalar and string files: values in assembly roots, family holders, update-shape commands, validators, and shape-doctor reports.

[brettheap]

@codex review

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

[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:14:34.652310Z	9e6caeb	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.

[sourcery-ai]

Reviewer's Guide

The PR hardens all four shape-pin readers against truthy non-list files: values, replacing iteration crashes with named refusals or validator findings and ensuring shape-doctor produces a complete report. New cross-context regression tests verify diagnostics, remediation, state preservation, and unchanged falsy-value behavior.

Sequence diagram for reporting an invalid shape-pin files value

sequenceDiagram
    participant User
    participant Doctor as shape-doctor.py
    participant Reader as update-shape.py read_pin
    participant Validator as Pinned validator
    participant Pin as shape-pin.yaml

    User->>Doctor: Run shape-doctor.py
    Doctor->>Reader: read_pin(root)
    Reader->>Pin: Read files
    Pin-->>Reader: Truthy non-list value
    Reader-->>Doctor: Refusal update-pin-row
    Doctor->>Validator: Validate shape pin
    Validator->>Pin: Read files
    Pin-->>Validator: Truthy non-list value
    Validator-->>Doctor: Finding shape-pin-row
    Doctor-->>User: Complete report with refusal and finding

Loading

Flow diagram for non-list shape-pin files handling

flowchart TD
    A[Read shape-pin.yaml] --> B{files is a list?}
    B -- Yes --> C[Iterate path and sha256 rows]
    B -- No --> D[Named diagnostic]
    D --> E[update-shape.py: update-pin-row refusal]
    D --> F[Validators: shape-pin-row finding]
    D --> G[shape-doctor.py: pins nothing and reports]
    C --> H[Normal validation or shape update]

Loading

File-Level Changes

Change	Details	Files
Validate shape-pin files: as a list before iterating, converting truthy scalar values into actionable diagnostics instead of TypeErrors.	Refuse malformed pins in update-shape.py with update-pin-row, the offending value, and pin-specific remediation. Report one shape-pin-row finding from both pinned validators for non-list files: values. Preserve existing no-files behavior for falsy values such as 0, false, null, and []. Update shape-doctor.py to treat non-list files as pinning no paths so the doctor can complete and report the underlying refusal/finding.	update-shape.py templates/assembly-root/scripts/validate-pins.py templates/family-root/scripts/validate-family.py shape-doctor.py
Add comprehensive regression coverage for malformed scalar files: values across assembly roots and family holders.	Parameterize tests over integer, boolean, and float values and verify update, validation, and doctor diagnostics. Verify refused applies do not modify the pin and remediation does not incorrectly mention submodules. Cover doctor JSON/text reporting, empty pinned paths, and validator findings for both root and holder contexts. Add controls confirming falsy scalar values retain the existing no-files diagnostics.	tests/test_shape_pin_files_not_a_list.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#290	Make update-shape.py read_pin reject a non-list shape-pin files value with an update-pin-row refusal that identifies the pin and files key, while preserving existing no-files handling for falsy values.	✅
#290	Make the pinned assembly-root validate-pins.py and family-root validate-family.py report a named shape-pin-row finding, rather than raising TypeError, when files is not a list.	✅
#290	Make shape-doctor.py pinned_paths safely return an empty set for a non-list files value so the doctor can produce a report instead of crashing.	✅

Possibly linked issues

• 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: The PR fixes issue 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 by rejecting or reporting non-list files values across every affected reader.

---

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: 6e2689acb8

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

Point the history lookup at the target root

When the documented workflow runs this script from the openRepoShape checkout with --root /path/to/project, this unqualified git log inspects the checkout rather than the target repository, so it usually shows no pin history—or the wrong history—and the user cannot follow the new remediation. Print a properly quoted git -C <root> log -- contracts/shape-pin.yaml command instead.

AGENTS.md reference: AGENTS.md:L250-L255

Useful? React with 👍 / 👎.

[brettheap]

(lane openRepoShape-2) Fixed in 039530b. PIN_ROWS_REMEDIATION is now pin_rows_remediation(root), spelled with the module's own quoter _by_hand, so the remediation prints git -C <root> log -- contracts/shape-pin.yaml quoted for a POSIX shell. Both update-pin-row raises in read_pin pass the root.

tests/test_shape_pin_files_not_a_list.py asserts the command computed with shlex.join, so it holds on Windows too. Two new tests cover the rest. One runs the tool from the checkout against a root path holding a space and executes the printed command; it finds the root's commits, where the unqualified command found none. The other covers the second raise. At 6e2689a, 8 of 22 fail; at 039530b, 22 pass. A mutant dropping -C <root> fails 8.

[brettheap]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Hooray!

Reviewed commit: 039530ba73

ℹ️ 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-12T15:39Z)

This lane reviewed its own PR #343 at 039530b, read-only, in its own detached worktrees. Nothing was authored.

MERGEABLE WITH NITS. Sequencing: whichever of #343 and #267 lands second must take the three-line check_pin(pin, pin_path, root) resolution in its main merge, and run CI on that merge.

Findings:

1. P2, sequencing. git merge-tree 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 8badae0 is clean, but the merged tree dies with NameError: name 'root' is not defined at update-shape.py:464. Both check and the doctor exit 1 with no report, for files: 5 and for the existing a-row-with-no-path case. The planned resolution is right for 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: 523 passed and 6 skipped, the doctor gives INVALID, and its NEXT restores COMPLIANT. Three additions:
   • fix the false pin_reads_at sentence that says files: 5 raises a TypeError (8badae0:shape-doctor.py:1127);
   • 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 needs its own doctor hunk, because the patch does not apply at ebffb08:shape-doctor.py:1174;
   • optionally drop the TypeError in that except tuple (8badae0:1137), which now only hides a caller left at two arguments. 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 do catch such a caller.
2. nit. The PR says files: abc now gives one finding, but no test has a string. Mutants that let a str through at validate-pins.py:342, update-shape.py:446 and validate-family.py:502 pass 22/22. Add abc to NOT_A_LIST (tests/test_shape_pin_files_not_a_list.py:51).
3. nit. Sonar S1192: the literal contracts/shape-pin.yaml appears three times (update-shape.py:399).
4. Follow-up. update-pin-no-files still prints the default git submodule update trailer. repo_shape.py's Refusal gives every refusal built without a remediation the assembly root's own (run git submodule update --init --recursive, then python3 scripts/validate-pins.py ... contracts/<leg>-pin.yaml), so in a family holder family.py add over an unparsable .gitmodules (git-failed), bump on a family.yaml of the wrong kind, and the holder's own validate-family.py on a short pin.commit each tell the operator to run a file no holder carries and to move a leg pin a holder does not have #370 already covers that default.

Main ab623dd reproduces the issue: a TypeError, exit 1, in all five readers. Head refuses update-pin-row, exit 2, and the doctor reports. For roots holding nine kinds of metacharacter, the printed git -C <root> log pastes correctly into bash and zsh.

Tests:

• head: 295 passed;
• head + ab623dd: 538 passed, 6 skipped, plus 281 passed in the family files;
• three-way with the resolution: 523 passed, 6 skipped;
• new file on main's code: 20 failed, 2 passed (controls).

Merges: rc 0 with main and every open head except #358, whose 4 hunks are its own conflict with main. main moved to 161c6c9 during the review, still rc 0.

Report: opensoft/brett-wip handoffs/xFactory/attachments/lane-openRepoShape-2/review343-039530b/final-report.md

[sonarqubecloud]

Quality Gate passed

Issues
0 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-2, 2026-10-12T21:18Z)

This lane re-verified its own PR at e68a01d (the main merge with #267's composition) and at 91a4a4f (update-branch onto main d6df36b; tree e358779), read-only in its own detached worktrees, with nothing authored.

MERGEABLE WITH NITS. CI on 91a4a4f on all three OSes is the gate. #419 and #347 follow this PR.

e68a01d is the clean textual merge of 9e6caeb and 580d7df plus the two planned patches, byte for byte. pyflakes is clean. For files: set to 5, true, 1.5, a string, a mapping, or a list holding a non-mapping item, check, apply, both shipped validators and the doctor each refuse by name with the same reading, on a root and a holder, with no traceback. The doctor's NEXT restores COMPLIANT. The falsy values match main.

Findings:

• nit: tests/test_shape_pin_files_not_a_list.py:152 still accepts exit 3 now that 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 is on main.
• P3, pre-existing, follow-up: the validators read a row with no path: as None is pinned but absent (validate-pins.py:382, validate-family.py:554), while update-shape.py refuses update-pin-row.
• P3, pre-existing, follow-up: repo_shape.py:827 parse_yaml keeps the last of a duplicated key.

Tests on the combined tree (2e85f54, the same tree as 91a4a4f): 862 passed, 6 skipped, 0 failed.

Merges: e68a01d with 1184f67, with 6d4e1e9 and with d6df36b are each rc 0. With #358 ce2ce75 it is rc 1 in three files, on the composition lines.

Report: handoffs/xFactory/attachments/lane-openRepoShape-2/review343-e68a01d/final-report.md in opensoft/brett-wip.