[brettheap]

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

What

scripts/bump-leg.py reads contracts/<role>-pin.yaml and every .yml and .yaml file under .github/workflows/ as UTF-8. A committed file that is not (a Latin-1 # caf\xe9, a UTF-16 file with a byte-order mark) now ends in a refusal, exit 2, naming the file, and not in a UnicodeDecodeError traceback, exit 1. --dry-run refuses the same way. Nothing in the working tree, the index or the leg's checkout moves.

• bump-leg-workflow-unreadable: one refusal naming EVERY workflow file that is not UTF-8, by its path in the repository, the first bad byte and the reason, in the words load_yaml uses (.github/workflows/legs.yml: not UTF-8 at byte 236 (invalid continuation byte)). The file is refused whether or not it names the leg. A file git does not track, untracked or ignored, is refused too (validate-pins.py reads it all the same) and its line ends (untracked or ignored).
• bump-leg-pin-unreadable: the same for contracts/<role>-pin.yaml, the leg's own pin.
• The remediation says to re-save the file as UTF-8 (a UTF-16 file needs converting) and run the same command again, and says which advice applies: commit each file git tracks; a file marked (untracked or ignored) needs no commit, only the re-save, because committing it would put a draft on the bump branch. It can also be moved out of .github/workflows/ until the bump has landed.

Code: three small functions in scripts/bump-leg.py: _not_utf8 (the one spelling of the finding), _leg_pin_text (the pin read, called from cmd_bump) and _workflow_texts (the directory walk and read that plan_workflows now loops over; it takes the tracked and listed sets plan_workflows already holds, and asks _tracked_spelling of each file it refuses). The --help text is unchanged, so docs/cli.md is unchanged; the module docstring's "WHAT IT REFUSES" list gains the bullet, and docs/handbook.html's refusal list and change line gain the clause (#289).

Why

main() catches Refusal and CommandFailed only, and UnicodeDecodeError is a ValueError, so nothing on the path caught it. The reads come before the --dry-run early return, so a dry run died too. Reproduced first on #264's head, 5269aac, before it landed (tools/repro.sh, local bare remotes, no network; the reads are the same on main): six rows, bump and --dry-run for a Latin-1 workflow, a UTF-16 workflow naming no leg, and a Latin-1 pin, all exit 1 with the traceback and a clean tree; the OTHER leg's non-UTF-8 pin was already a clean bump-leg-validators-red (exit 2, rolled back) and still is.

• Refused, not read lossily. errors="replace" would let the run go on, but write_lf writes the rewritten text back, so the lockstep commit would carry U+FFFD where the operator's byte was.
• Refused, not skipped. validate-pins.py reads every workflow file on disk and cannot read it either, so a skip only moves the failure to CI. And the read must not become a filter: the UTF-16 row names no leg and stops the bump (the issue's point 3). That holds for a file git does not track too: skipped, it would reach the validator, which dies on it in a traceback inside bump-leg-validators-red.
• Before the leg moves, so bump-leg.py _apply_rewrite rolls back only on Refusal and CommandFailed, so a PermissionError on a workflow file it rewrites, or the UnicodeEncodeError that #230's errors="replace" moves the decode crash to, leaves the pin rewritten and the leg on the new commit, with a traceback and no rollback #253's rollback (bump-leg.py: a bump that fails for any reason once the leg has moved, a commit git refuses included, rolls the pin, the workflow files, the leg's checkout and the index back and says whether all of it went back, so a workflow file it cannot write, a validator line the stdout cannot encode, a signer that cannot sign or an interrupt no longer leaves the pin rewritten and the leg on the new commit (#253) #264, landed) is not involved and none of its promises (ROLLED_BACK, _head_guard, _roll_back) are touched; the reads sit before _apply_rewrite. The remediation says what is true: the working tree, the index and the leg's checkout are as they were (the leg's object store was fetched into, as a dry run documents).
• The pin gets its own id (bump-leg-pin-unreadable), rather than load_yaml's yaml-unreadable, because the tool rewrites the pin's lines and cannot go through load_yaml, and an id that says "bump-leg" tells the operator which tool stopped.
• Each line says whether git tracks the file, because the cure differs. A tracked file is committed after the re-save. For an untracked one, re-saving alone lets the bump through and the draft is not in the lockstep commit, so "commit it" would put a draft workflow on the bump branch, which bump-leg.py rewrites and commits every workflow file it finds on disk, so an untracked draft workflow that names the leg is added whole to the lockstep commit, though the clean-root check skips untracked files because they "cannot reach a commit made with explicit pathspecs" #207's bump-leg-workflow-untracked exists to prevent; for an ignored one git add refuses. The question is _tracked_spelling's, the one bump-leg.py: a tracked workflow the disk spells another way is rewritten and committed under git's spelling, so a legs.yml renamed Legs.yml by case alone outside git on macOS or Windows is no longer refused as bump-leg-workflow-untracked while git status is clean, with an exit that could not clear it (#332) #344 settled, so a tracked file the disk spells another way is not marked untracked. It is asked only of a file already refused and reads no file, so every read still comes before anything is written, --dry-run included.

Tests

New tests/test_bump_leg_unreadable.py, 19 tests (13, and 6 added by the fix round below). Every refusal test asserts exit 2, the refusal id, each file named by relative path, the byte offset and reason, no Traceback and no UnicodeDecodeError in the output, and the WHOLE tree unchanged (the rollback file's snapshot and assert_nothing_changed: root HEAD, pin and workflow bytes, the gitlink, git status, git diff --cached, the leg's HEAD and branch). Bytes are written with write_bytes.

• a committed workflow naming the leg with # caf\xe9, bump and --dry-run (2);
• a UTF-16 workflow with a BOM that names no leg, .yml and .yaml, bump and --dry-run (4);
• two bad workflows are both named in ONE refusal (1);
• --to the commit already pinned, with a bad workflow: exit 2, not "nothing to do" exit 1 (1);
• a committed contracts/spec-pin.yaml with a Latin-1 byte, bump and --dry-run (2);
• controls (3): the OTHER leg's pin stays bump-leg-validators-red; a UTF-8 workflow with non-ASCII comments, and a UTF-8-with-BOM one, still bump and the bytes survive; a non-UTF-8 notes.txt and NOTES.md, which the validator never reads, do not stop it;
• added by the fix round (6):
  • an untracked and an ignored (through info/exclude) draft holding # caf\xe9, bump and --dry-run (4): exit 2, the line ends (untracked or ignored), the remediation says "needs no commit" and not "commit it"; then the file re-saved as UTF-8 and still untracked bumps (exit 0), is not in the lockstep commit, and the validator is green over it;
  • a tracked and an untracked unreadable file in one refusal (1): the tracked line unmarked, the untracked one marked, each kind's advice given;
  • a tracked legs.yml holding a Latin-1 byte, renamed outside git to Legs.yml, through bump-leg.py: a tracked workflow the disk spells another way is rewritten and committed under git's spelling, so a legs.yml renamed Legs.yml by case alone outside git on macOS or Windows is no longer refused as bump-leg-workflow-untracked while git status is clean, with an exit that could not clear it (#332) #344's _same_file seam, so it runs on every OS (1): plan_workflows refuses bump-leg-workflow-unreadable under the disk's spelling (.github/workflows/Legs.yml: not UTF-8 at byte 236 ...), the line is not marked untracked, and the file's bytes are unchanged.

Run against main's scripts/bump-leg.py (ab623dd; tools/x352-tests-at-main-code.log): 16 failed, 3 passed. The 15 that go through the CLI fail on assert 1 == 2 (the run exits 1) with the output holding UnicodeDecodeError: 'utf-8' codec can't decode byte 0xe9 in position 245 (a workflow), 0xe9 in position 16 (the drafts), 0xff in position 0 (the UTF-16 file) or 0xe9 in position 1880 (the pin); the seam test calls plan_workflows and gets the UnicodeDecodeError itself. The 3 that pass are the controls, which hold on both. (The original 13 gave 10 failed and 3 passed against 86da808 and against #264's head 5269aac, tools/new-tests-main-base.log.gz and tools/new-tests-base.log.gz.) Run against this branch's previous head, 107242d (tools/x352-tests-at-107242d-code.log): 7 failed, 12 passed: the 4 draft tests and the mixed test fail on the unmarked line and on "commit it", the tracked-file test on the new "Commit each file git tracks" sentence, and the seam test passes, because the head was right and nothing pinned it. At this head: 19 passed.

Mutants of the decisive lines, each killed. The original five (tools/mutant-*.log.gz): the pin read with errors="replace" (2 fail); _workflow_texts collecting the files and not raising (8 fail); the workflow read with errors="replace" (8 fail); refusing only files that hold an @ (5 fail: the UTF-16 file naming no leg); cmd_bump back on the raw pin read (2 fail). The marking, this round (tools/x352-mutants.log): an unreadable file git does not track skipped (5 fail; the one that survived the review), every line marked tracked (5), every line marked untracked (4), the exact-spelling comparison in place of _tracked_spelling (1: the seam test), the refusal naming git's spelling in place of the disk's (1: the seam test), the untracked advice dropped (5), the tracked advice dropped (3).

Targeted, at head 3416283 (797c96b plus the Windows fix below, a one-line change to one test; the counts are the same at both), git-filter-repo 2.47.0 on PATH, never the whole suite:

files	tests
tests/test_bump_leg_unreadable.py	19
tests/test_bump_leg.py	39 passed, 1 skipped
tests/test_bump_leg_rollback.py	24
tests/test_git_output_decoding.py	67
tests/test_commit_trailers.py	125
tests/test_cli_reference.py + tests/test_repo_hygiene.py	13 + 50

82 passed, 1 skipped in the first three, which hold #344's tests as well as this PR's (tools/x352-run1-bump-leg.log; the skip reason is in it); 130 in test_git_output_decoding.py + test_cli_reference.py + test_repo_hygiene.py (tools/x352-run2-decoding-cli-hygiene.log); 212 passed, 1 skipped in all six files but test_commit_trailers.py, together, at 797c96b (tools/x352-run-final-797c96b.log); 125 in test_commit_trailers.py (tools/x352-run-trailers.log); all seven files together at 3416283: 337 passed, 1 skipped (tools/w352-run-targeted-3416283.log); scripts/render-cli-reference.py --check ok. The handbook's check, that it follows the README's outline and names the README's blob, is in test_repo_hygiene.py; README.md is not touched, so the blob the footer names still holds. The one skip is #344's test_a_tracked_workflow_respelled_by_case_moves_under_gits_spelling, which needs a disk that ignores case and runs on the macOS and Windows jobs. tests/test_shape_doctor.py is not run: neither adopt-project.py nor update-shape.py is touched.

Fix round (review of 107242d)

Lane openRepoShape-2's own review of 107242d found one P3 and three nits; this round takes all four.

• P3, the remediation told the operator to commit a file git does not track. Fixed in 8828bfd: each unreadable line git does not track ends (untracked or ignored), and the remediation gives a tracked file's operator "Commit each file git tracks." and an untracked one's "needs no commit, only the re-save". _workflow_texts takes tracked and listed from plan_workflows. Four tests, plus the mixed one; the mutant that skips an unreadable untracked file, which survived the review, is killed.
• Nit, no test of the bump-leg.py: a tracked workflow the disk spells another way is rewritten and committed under git's spelling, so a legs.yml renamed Legs.yml by case alone outside git on macOS or Windows is no longer refused as bump-leg-workflow-untracked while git status is clean, with an exit that could not clear it (#332) #344 composition. Fixed in 8828bfd: the seam test above. It pins what the review showed by probe: a tracked, non-UTF-8 workflow respelled by case is refused under the disk's spelling, before any spelling question is asked.
• Nit, this body. The README cap is 1419 lines, not 1416, and README.md is 1419 lines; the open-PR line below has been re-checked.
• Nit, the handbook's refusal list. Fixed in 797c96b: the "Refuses" list for bump-leg.py in docs/handbook.html names the refusal, and the page's change line records it (bump-leg.py: a committed workflow file under .github/workflows/ or a contracts/<role>-pin.yaml that is not UTF-8 ends in a UnicodeDecodeError traceback, exit 1, with no refusal naming the file, so the operator reads Python's decode error and --dry-run dies the same way #289). README.md is left alone, at its cap.

Windows fix (3416283)

tests-windows was red at 797c96b (1 failed, 3635 passed): test_the_other_legs_pin_stays_the_validators_refusal asserted contracts/code-pin.yaml, and the Windows job prints contracts\code-pin.yaml. The file is named by the project's own validate-pins.py, whose repo_shape.load_yaml prints the Path it was given, absolute and in the platform's spelling (D:\a\_temp\t\...\Atlas\contracts\code-pin.yaml: not UTF-8 at byte 1880), and this tool echoes the validator's output under bump-leg-validators-red. The behaviour was right (that refusal, every byte rolled back), and the same test had failed Windows at b5f1ef2.

The test changed, not the tool. This tool's refusals name a repository path with as_posix() (_not_utf8, pin_rel) and every other assertion in the file reads that text; load_yaml's native spelling is pinned by other tests (f"REFUSED yaml-unreadable: {path}" in test_manifest_validator.py, test_adopt_execute_refusals.py, test_load_yaml_refusals.py), and changing it would move a pinned template copy in every project. The assertion is now str(Path("contracts") / "code-pin.yaml"): the same text on POSIX, and a substring of the validator's path on Windows. It is the one assertion in the file that reads validator text.

Checked on Linux by making this tool echo the validator's paths in Windows spelling (D:\a\_temp\t\Atlas\contracts\code-pin.yaml, tools/w352-win-shim.py): the old assertion fails exactly as CI's did (tools/w352-probe-old-assertion-win-shim.log), the Windows-spelled one passes (tools/w352-probe-native-assertion-win-shim.log), and the whole file, 19 tests, passes under it (tools/w352-probe-whole-file-win-shim.log). The mutants of the fix round were not re-run: the only line changed is in a control test, and on POSIX its assertion text is the one the mutants ran against.

Left alone, for follow-up issues: a file this tool cannot OPEN (below), and _ensure_root_clean's strict decoding of git status --porcelain for a dirty tracked workflow whose NAME is not UTF-8 under core.quotePath=false, which is a traceback on main and here alike.

Merged main after #344 landed

Merge commit 107242d merges origin/main ab623dd, which holds #344 as a2cb7d3 (closes #332), into this branch. One file conflicted, scripts/bump-leg.py, in the two add-vs-add hunks named below, and both resolved by keeping both sides. The net diff against ab623dd at 107242d was scripts/bump-leg.py and tests/test_bump_leg_unreadable.py and nothing else (the fix round adds docs/handbook.html); git merge-tree --write-tree origin/main HEAD is rc 0 at the current head too, and py_compile passes. The merge adds no code or test of its own beyond the resolution.

Composes with

This branch is main 86da808 (#264's squash) merged into the branch, one merge commit, b5f1ef2; the net diff against 86da808 is scripts/bump-leg.py and tests/test_bump_leg_unreadable.py and nothing else. git merge-tree --write-tree b5f1ef2 <head>, nothing fetched:

against	rc	conflict
origin/main 86da808	0	none (the merge is this commit)
origin/main 6f4ce47 (one family.py commit newer, seen after the merge)	0	none
#344 (landed on main as a2cb7d3, closes #332; was 7013335 on fix/bump-leg-case-only-rename)	1 at b5f1ef2, resolved in 107242d	scripts/bump-leg.py, TWO hunks, both add-vs-add in plan_workflows' neighbourhood
origin/main ab623dd (holds #344), at 107242d and at 797c96b	0	none (the merge is 107242d)
origin/main 92e29d9, at 3416283	0	none

The merge itself conflicted in three hunks against #222's tracked-files change (#207) in plan_workflows, and resolved this way: (1) the helper block keeps main's _tracked_workflows and this change's _not_utf8, _leg_pin_text and _workflow_texts; (2) the docstring keeps both paragraphs; (3) the loop head reads tracked, untracked, then for path, text in _workflow_texts(root, workflows), main's own text = path.read_text(...) line going with the walk it belonged to. (The loop head now passes tracked, listed too.)

#344 landed as a2cb7d3, and its two hunks resolved by keeping both sides in the merge 107242d. (1) The helper block: this change's _not_utf8, _leg_pin_text, _workflow_texts, and #344's _same_file and _tracked_spelling, ours first. (2) The plan_workflows docstring: #344's "A TRACKED FILE THE DISK SPELLS ANOTHER WAY" paragraph, and this change's one sentence after it. The loop merges clean: #344 adds listed = {child.name for child in workflows.iterdir()} and resolves each row through _tracked_spelling(root, path, tracked, listed), and _workflow_texts yields the same paths, so a case-renamed Legs.yml that is not UTF-8 is refused as bump-leg-workflow-unreadable under the disk's spelling, before any spelling question is asked for a plan row (by construction, _workflow_texts runs first, and the fix round's seam test pins that exact case). Every workflow is still read as UTF-8 before anything is written, and a tracked file respelled by case is still planned under git's spelling. At 107242d, test_bump_leg_unreadable.py, test_bump_leg.py (with #344's tests) and test_bump_leg_rollback.py gave 76 passed, 1 skipped (tools/merge2-a.log), the numbers the scratch resolution gave beforehand (tools/with344.log); at 797c96b, 82 passed, 1 skipped, the six added tests being the difference.

Open PRs touching scripts/bump-leg.py or tests/test_bump_leg*: none. #344 landed (a2cb7d3), and the lane's review of 107242d re-checked the list at 14:28Z and 14:42Z, with origin/main at ab623dd both times. At 797c96b, git merge-tree --write-tree against each of the 18 other open heads the review listed (nothing fetched): 15 rc 0, and #358, #356 and #314 rc 1, in shape-doctor.py, adopt-project.py and adopt-project.py + scaffold-project.py, files this PR does not touch (the review found each already conflicts with ab623dd alone). docs/handbook.html conflicts with none of them (tools/x352-merge-tree-all-797c96b.txt).

Left out

• scripts/validate-pins.py still raises the same traceback. The issue's "Not in this issue". Reproduced again at this head: on a tree whose workflow holds # caf\xe9, python3 scripts/validate-pins.py --root . exits 1 with UnicodeDecodeError from _workflow_refs (templates/assembly-root/scripts/validate-pins.py:111). The file is a pinned template copy: a fix moves the sha256 that contracts/shape-pin.yaml records for scripts/validate-pins.py in every project, which every project already cut then sees as upstream-changed. A separate change with its own cost, and worth filing; bump-leg.py no longer reaches it, since it refuses the file first, but CI and a hand run still do.
• A file this tool cannot OPEN is the same crash, a different cause. A mode-000 pin or workflow file raises PermissionError out of the same two reads (_leg_pin_text, _workflow_texts), a traceback with no refusal, exit 1, the tree unchanged; on main too. It is not an encoding failure, and the refusal's "re-save as UTF-8" would be the wrong cure for it, so it is not folded in. On POSIX it needs core.trustctime=false: under the default config the chmod makes the root read dirty (bump-leg-root-dirty). Left for a follow-up issue.
• One refusal names every bad WORKFLOW, not every bad file. cmd_bump reads the pin first, so a root with a bad pin AND a bad workflow names the pin alone on the first run, bump and --dry-run, and the workflows on the second. The reads were not reordered: no promise covers the order.
• README.md is untouched. It sits at its 1419-line cap (tests/test_repo_hygiene.py; AGENTS.md, README and scaffold-project.py --help: say that a --spec-path or --code-path that is, holds or lies inside a file the shape writes, and a --pin of spec, code or shape or of one product twice, are refused before anything is created, and name those three in the pin refusal's remediation, so an agent briefed from AGENTS.md can say so before it runs the scaffold (#288) #309 raised it from 1416) and main has rewrapped the "It REFUSES ..." paragraph since this branch's base. The new refusals are in the module docstring's list, which is where the existing ones are spelled out, and in the handbook's.
• The reads are not moved before fetch_leg. They stay where they were, after the fetch and the digest, so the object store is fetched into first, as the issue notes and --dry-run already says. Reordering would change which refusal wins for a root that has two faults.

Closes #289

🤖 Generated with Claude Code

Summary by Sourcery

Make bump-leg.py reject unreadable workflow and pin files clearly and safely before modifying the repository.

New Features:

• Refuse non-UTF-8 workflow files and the target leg pin by name, including the first invalid byte and decoding reason, before any repository changes occur.
• Report whether unreadable workflow files are tracked and provide matching remediation for tracked and untracked or ignored files.

Bug Fixes:

• Replace uncaught UnicodeDecodeError tracebacks with controlled exit-2 refusals for bump and dry-run operations.
• Refuse every unreadable YAML workflow, including files that do not reference the selected leg, so validation does not fail later.

Documentation:

• Document the new unreadable workflow and pin refusals in the handbook and bump-leg refusal documentation.

Tests:

• Add comprehensive coverage for unreadable workflows and pins, dry runs, multiple and untracked files, case-respelled tracked files, tree immutability, valid UTF-8 controls, and platform-specific output.

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

[brettheap]

@codex review

[sourcery-ai]

Reviewer's Guide

The PR prevents bump-leg.py from leaking UnicodeDecodeError tracebacks by validating the leg pin and every workflow as UTF-8 before any rewrite or dry-run decision, reporting named exit-2 refusals with actionable byte diagnostics, and adds regression tests covering failure aggregation, ordering, immutability, and valid-input controls.

Sequence diagram for UTF-8 validation before bump-leg changes

sequenceDiagram
    participant Operator
    participant BumpLeg as bump-leg.py
    participant Pin as LegPin
    participant Workflows as WorkflowFiles
    participant Refusal

    Operator->>BumpLeg: cmd_bump(args)
    BumpLeg->>Pin: _leg_pin_text(root, pin_path)
    Pin-->>BumpLeg: UTF-8 pin text
    BumpLeg->>Workflows: _workflow_texts(root, workflows)
    Workflows-->>BumpLeg: UTF-8 workflow texts
    BumpLeg->>BumpLeg: plan_workflows(root, repository, commit)
    BumpLeg-->>Operator: Apply or --dry-run result

    alt Pin is not UTF-8
        Pin-->>Refusal: bump-leg-pin-unreadable
        Refusal-->>Operator: Exit 2 with path, byte, and reason
    else Any workflow is not UTF-8
        Workflows-->>Refusal: bump-leg-workflow-unreadable
        Refusal-->>Operator: Exit 2 naming every bad workflow
    end

Loading

Flow diagram for unreadable bump-leg refusal

flowchart TD
    A[Start bump-leg command] --> B[_leg_pin_text]
    B -->|Invalid UTF-8| C[bump-leg-pin-unreadable]
    B -->|Valid UTF-8| D[_workflow_texts]
    D -->|One or more invalid files| E[bump-leg-workflow-unreadable]
    D -->|All workflows valid| F[plan_workflows and possible rewrite]
    C --> G[Exit 2 with byte diagnostics and remediation]
    E --> G
    G --> H[Working tree, index, and leg checkout unchanged]
    F --> I[Apply changes or complete --dry-run]

Loading

File-Level Changes

Change	Details	Files
Add explicit UTF-8 validation and named refusals before bump planning or file rewrites.	Centralize decode-error formatting with repository-relative path, byte offset, and reason. Read the leg pin through a helper that raises bump-leg-pin-unreadable with remediation details. Read all .yml and .yaml workflows up front, aggregate every unreadable file, and raise bump-leg-workflow-unreadable even when a file does not reference the leg. Keep validation before the dry-run and rewrite stages, preserving the no-working-tree/index/checkout-change guarantee.	scripts/bump-leg.py
Add comprehensive regression coverage for unreadable inputs, ordering, preservation, and untouched repository state.	Cover Latin-1 and UTF-16 workflow failures for normal and dry-run commands, including aggregation of multiple bad files and precedence over “nothing to do.” Cover unreadable leg pins with distinct refusal IDs and verify unrelated-leg behavior remains unchanged. Verify exit 2, file paths, byte diagnostics, remediation text, absence of tracebacks, and complete tree/index/submodule immutability. Verify valid UTF-8, UTF-8 BOM, non-ASCII workflow content, and ignored non-workflow files continue to work byte-for-byte.	tests/test_bump_leg_unreadable.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#289	Make bump-leg.py refuse non-UTF-8 workflow files and the selected leg pin by name, including the relative path, byte offset, and decoding reason, with exit 2 and no UnicodeDecodeError traceback.	✅
#289	Ensure the refusal applies during --dry-run and occurs before any working-tree, index, pin, workflow, or leg checkout changes, without lossily replacing bytes or silently skipping unreadable workflow files.	✅
#289	Add regression coverage for unreadable Latin-1 and UTF-16 workflow and pin files, including files that do not reference the selected leg, while preserving valid UTF-8 workflows and unrelated non-UTF-8 files.	✅

Possibly linked issues

• bump-leg.py: a committed workflow file under .github/workflows/ or a contracts/<role>-pin.yaml that is not UTF-8 ends in a UnicodeDecodeError traceback, exit 1, with no refusal naming the file, so the operator reads Python's decode error and --dry-run dies the same way #289: PR directly implements issue bump-leg.py: a committed workflow file under .github/workflows/ or a contracts/<role>-pin.yaml that is not UTF-8 ends in a UnicodeDecodeError traceback, exit 1, with no refusal naming the file, so the operator reads Python's decode error and --dry-run dies the same way #289 with named exit-2 refusals, remediation, dry-run handling, and comprehensive unchanged-tree 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 Summary

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

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-12T16:51:06.639969Z	3416283	Manual request

ℹ️ About Codex in GitHub

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

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

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

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. More of your lovely PRs please.

Reviewed commit: b5f1ef2930

ℹ️ 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-12T14:46Z)

This lane reviewed its own PR #352 at 107242d, read-only in its own detached worktrees, with nothing authored.

MERGEABLE WITH NITS. Merge only after tests-macos and tests-windows pass at 107242d; both were pending, and Linux tests had passed.

Findings:

• P3, fix here. The bump-leg-workflow-unreadable remediation (scripts/bump-leg.py:355-358) tells the operator to "commit it" for every file it names. For an untracked draft holding # caf\xe9, re-saving it is enough: the bump then exits 0 without it. Committing it would put a draft on the bump branch, which bump-leg.py rewrites and commits every workflow file it finds on disk, so an untracked draft workflow that names the leg is added whole to the lockstep commit, though the clean-root check skips untracked files because they "cannot reach a commit made with explicit pathspecs" #207 exists to prevent. For an ignored file, git add refuses. No test covers an untracked unreadable file, so a mutant that skips one survives all 13 tests.
• Nit, fix here. Add a seam test for the composition with bump-leg.py: a tracked workflow the disk spells another way is rewritten and committed under git's spelling, so a legs.yml renamed Legs.yml by case alone outside git on macOS or Windows is no longer refused as bump-leg-workflow-untracked while git status is clean, with an exit that could not clear it (#332) #344. Through _same_file, a Latin-1 legs.yml respelled Legs.yml is refused under the disk's spelling, before the spelling question, which is the right order.
• Nit. The body's README cap is now 1419, not 1416. The handbook's refusal list omits the new refusals.
• Follow-up, not this PR. A mode-000 pin or workflow (:302, :341) ends in a PermissionError traceback under core.trustctime=false, the same as main. It is out of bump-leg.py: a committed workflow file under .github/workflows/ or a contracts/<role>-pin.yaml that is not UTF-8 ends in a UnicodeDecodeError traceback, exit 1, with no refusal naming the file, so the operator reads Python's decode error and --dry-run dies the same way #289's scope, because the remediation says to re-save as UTF-8.
• Follow-up, not this PR. _ensure_root_clean (:731) decodes git status strictly, so a dirty non-UTF-8 name under core.quotePath=false gives a traceback.

Tests:

• 107242d, which equals itself merged with ab623dd:
  • the three bump-leg test files: 76 passed, 1 skipped;
  • the decoding, CLI reference, hygiene and trailer tests: 255 passed;
  • render-cli-reference.py --check ok.
• ab623dd with the new file: 10 failed and 3 passed, each failure the issue's traceback.
• The issue's six rows exit 1 on main and exit 2 here, with the tree unchanged.
• Mutants: 6 of 9 killed.

Merges: no other open head touches scripts/bump-leg.py or tests/test_bump_leg*. Against 18 open heads, 15 merge with rc 0. #358, #356 and #314 conflict only where they already conflict with main.

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

[brettheap]

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

Fix round pushed: 797c96b (107242d..797c96b), answering this lane's review (#352 (comment)):

• Item 1 (P3), fixed in 8828bfd. _workflow_texts now asks _tracked_spelling of each file it refuses. A line git does not track ends (untracked or ignored), and the remediation says a tracked file is committed after the re-save, while an untracked one needs only the re-save. Untracked and ignored cases, under bump and --dry-run, are tested, and the review's surviving untracked-skipped mutant is now killed.
• Item 2 (nit), fixed in 8828bfd. test_a_respelled_unreadable_workflow_is_refused_as_the_disk_spells_it pins the composition with bump-leg.py: a tracked workflow the disk spells another way is rewritten and committed under git's spelling, so a legs.yml renamed Legs.yml by case alone outside git on macOS or Windows is no longer refused as bump-leg-workflow-untracked while git status is clean, with an exit that could not clear it (#332) #344 through _same_file.
• Item 3 (nit), fixed. The body is v3: the README cap is 1419, and the open-PR list was re-checked at 797c96b.
• Item 4 (nit), fixed in 797c96b. The handbook's refusal list names the new refusals.

Targeted at 797c96b:

• test_bump_leg_unreadable.py: 19 passed.
• test_bump_leg.py: 39 passed, 1 skipped.
• test_bump_leg_rollback.py: 24 passed.
• test_git_output_decoding.py: 67 passed.
• test_cli_reference.py: 13 passed.
• test_repo_hygiene.py: 50 passed.
• test_commit_trailers.py: 125 passed.
• render-cli-reference.py --check ok.

The two follow-ups stay out of this PR: #383 (PermissionError), and the strict git status decode, still to file. This lane's reviewer re-verifies this head next.

Lane: openreposhape-2 (openRepoShape-2)

[brettheap]

@codex review

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[brettheap]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Another round soon, please!

Reviewed commit: 3416283779

ℹ️ 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-12T17:41Z)

Re-verify of PR #352's fix round (797c96b), and the Windows fix at 3416283.

MERGEABLE. CI at 3416283 is green on all three OSes: tests, tests-macos and tests-windows passed (17:40Z).

• Items 1 to 4 are fixed at 797c96b: the P3 remediation, the bump-leg.py: a tracked workflow the disk spells another way is rewritten and committed under git's spelling, so a legs.yml renamed Legs.yml by case alone outside git on macOS or Windows is no longer refused as bump-leg-workflow-untracked while git status is clean, with an exit that could not clear it (#332) #344 seam test, the body and the handbook list.
• The one blocker was tests-windows at 797c96b. test_the_other_legs_pin_stays_the_validators_refusal asserted contracts/code-pin.yaml. The project's validator names that file by its absolute native path, ...\Atlas\contracts\code-pin.yaml, and this tool echoes it. The behaviour was right.
• 3416283 changes the test, not the tool. It asserts str(Path("contracts") / "code-pin.yaml"), the same text on POSIX. This tool's own refusals print repository paths as POSIX, and no other assertion reads validator text.
• Checked on Linux with the echo rewritten to Windows spelling: the old assertion fails as CI's did, the new one passes, and the whole file (19) passes.
• Targeted at 3416283: 337 passed, 1 skipped (test_bump_leg*, decoding, CLI reference, hygiene, trailers). git merge-tree with main 92e29d9: rc 0.
• Optional nit, unchanged: "needs no commit, only the re-save" is too absolute for an untracked draft that names this leg (scripts/bump-leg.py:365-366).

[sonarqubecloud]

Quality Gate passed

Issues
2 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-12T17:48:41Z) An identity notice for lane openRepoShape-2. Brett has set the estate's git identity to the service address in every container: the host's ~/.gitconfig is now that, and the repository-local user.email overrides under the projects folder are gone. Three commits from 2026-10-11 carry a profile address as author and committer: 3c499c5, a8d31ee and f73feec (bump-leg.py). They are on fix/bump-leg-unreadable-files (this PR, #352) and fix/bump-leg-unreadable-oserror (#403), and in merged #264.

Land #352 and #403 only by squash with an explicit subject and body. GitHub's default squash message adds a Co-authored-by: line for every commit author other than the PR's, which would copy that address onto main. Do not use a merge commit or a rebase merge either: both keep the commits themselves. Brett is deciding with GitHub Support what happens to the copies GitHub keeps under each PR.