[brettheap]

Lane: openreposhape-5 (openRepoShape-5)
Claim: #764 (comment)

Against main. #745 landed as 24a977c, and this branch is restacked onto main as f6f318d1: it merges #745's final head 1945154c, then main, taking this branch's side in bootstrap.py, where git diff 1945154c 24a977c0 over #745's files is empty. The restacked tree is 7884460e, the tree the merge checks below predicted.

Fix round: lane 3's RV815 NITs 2 to 7 (05a1ebb3)

Lane 3's RV815 reviewed f6f318d1: READY, no MUST. One new commit, 05a1ebb3, on f6f318d1, pushed to fix/764-bootstrap-notice-exit-texts as a fast-forward. Nothing was amended and main is not merged in that round. The merge round 61aed8d2 merged it later (#815 issuecomment-6247909102). It changes templates/assembly-root/scripts/bootstrap.py (+13/-8), tests/test_bootstrap_refusal_exit.py (+62) and tests/test_bootstrap_upstream_notice.py (+30/-2), and nothing else. README, the handbook, docs/cli.md and every other pinned file are untouched.

The pinned digest moves again. After the merge round with main (61aed8d2, #815 issuecomment-6247909102), templates/assembly-root/scripts/bootstrap.py is sha256 89ff92e5e469003fb5a1f13a5adbe5be2f9c2913ad152eb3f49e8545f0a8c3cc. Main's is 6a7847f3d78ab6c3a350914bf7f9c81e11e235a6d9f8ad2b5782418e8b794e57, since #855. At the NIT round it was 09238ebd4202193a..., where the body says 0cb334c260493313.... The "Pinned files changed" paragraph below gives the current digests; the rest of that paragraph stands (the file is already upstream-changed for a v1.1.0 project once, and #824 changes it too). In "What changed", the count becomes: three commits after f4935e11 (271710ba, c2977425, 05a1ebb3), the restack's two merges (3aa9a0fe, f6f318d1), and the merge round with main (61aed8d2).

What each NIT came to

NIT	taken	what changed	held by
2: mutant X3 survives	yes	no shipped change; an over-long SHAPE_UPSTREAM_PATH (a name of 300 characters, and a path of over 5000) now has a test: bootstrap ok, exit 0, no notice, no traceback	test_an_over_long_upstream_path_is_an_absent_answer (2 cases)
3: no flush before the ending	yes	sys.stdout.flush() at the top of _end_of_run, as the git-not-runnable path does	test_the_ending_follows_step_c_in_a_log_of_both_streams (2 cases: REFUSED and FAILED)
4: docstring (d) overstated	yes	step (d) now says a finding is any exit but 2 and reads (exit <code>); both lines are said, the finding first, where the run reaches its end; step (a) or the notice refusing git-not-runnable stops the run with neither line	the no-git cases below, and the nine ending cases that were already there
5: != 0	yes	the shape-pin list case asserts == 2	test_a_shape_pin_that_is_not_a_mapping_ends_as_the_validators_end_it
6: no test for "a plain clone with no git"	yes	test_a_plain_clone_with_no_git_ends_refused_with_exit_2: bootstrap REFUSED: pins (exit 2), exit 2, no FAILED line, step (c) still reached. A second test holds the sentence step (d) now says: no git, a manifest finding and a directory named by SHAPE_UPSTREAM_PATH refuse git-not-runnable first, with neither line	test_a_plain_clone_with_no_git_ends_refused_with_exit_2, test_no_git_and_a_clone_named_refuses_before_either_line
7: the body's C3 lines	yes	the paragraph below
1: run git -C <upstream> from the root	no	see below
8: a BOM in the cache	done by the merge round 61aed8d2, with #855's read	see the candidates

NIT 3, as measured. With > log 2>&1, stdout is block-buffered and stderr is not. Without the flush, bootstrap REFUSED: pins (exit 2) (and bootstrap FAILED: for a finding, as on main) printed before step (c)'s heading and its lines, and the log did not end on it. The test merges the two streams through run_script(merge_stderr=True) and blanks PYTHONUNBUFFERED, so a runner that exports it cannot hide the fault.

NIT 4, as measured. With no git on PATH, SHAPE_UPSTREAM_PATH naming a directory and a manifest finding, the run ends REFUSED git-not-runnable: the clone SHAPE_UPSTREAM_PATH names ..., exit 2, with neither bootstrap FAILED nor bootstrap REFUSED. That predates this PR (#694), so the docstring said too much, not the code. A validator killed by a signal ends bootstrap FAILED: <name> (exit -9), exit 1 (_end_of_run([("pins", -9)]) returns 1 and says exactly that), which the (exit <code>) wording now covers.

NIT 1 is not taken, because it changes an exit path on Linux. The change is _try_git(["-C", str(Path(upstream).absolute()), "rev-parse", "HEAD"], root). Its point (no process starts inside the upstream directory, so a Windows cwd that CreateProcess refuses cannot be read as git's own PermissionError) is reasoned, and cannot be measured on Linux. I measured the Linux side: the old _clone_tip and the new one run through shape_upstream_notice over 22 values of SHAPE_UPSTREAM_PATH and two PATHs (git, and an empty directory), 44 rows:

• the values: a clone by absolute path, with a trailing slash, by relative path from the root's directory and from another, through link/.., a subdirectory of a clone, a directory named -x, a bare repository, an unborn HEAD, a plain directory, a file, a missing path, a name with spaces and a newline, a name with a non-UTF-8 byte, an over-long name and path, the empty string, a mode-000 directory, one under it, and a clone under a directory with no search bit;
• 43 rows are byte for byte the same (the notice, or the same refusal);
• 1 row differs: no git on PATH and an upstream directory nobody may enter. The old code answers "no clone" (its PermissionError names the directory, which _git_runs passes on), so the cache speaks; the new code starts no process there, finds git missing, and refuses git-not-runnable, exit 2.

The brief for this round asked for NIT 1 only if every exit path stayed byte-identical, so it is left. It is two lines (and _clone_tip takes the root) if lane 3 or Brett Heap wants that row to refuse; the new row's answer is defensible, since the clone cannot be read either way.

NIT 7: the C3 account, one more paragraph. Two more sentences say "AT its pinned commit" with no condition, and both are true where they stand, so neither is changed:

• scaffold-project.py:1957, the scaffold's NEXT STEPS: "make bootstrap puts each leg on <branch> AT its pinned commit". It is printed once, for a person who is about to take a fresh recursive clone and run make bootstrap for the first time. In that clone every leg is detached AT its pin, with no operation in progress and no commit of its own, so nothing can be lost and the placement happens as said. tests/test_push_branch_refspec.py asserts the sentence for a +x branch and then runs that first bootstrap (the legs end on it at their pins), and tests/test_scaffold_e2e.py runs it on the default branch and checks the pin did not move.
• templates/assembly-root/project.yaml:64, the comment on tracking_branch: "The branch scripts/bootstrap.py places each leg on, AT its pinned commit". It names which commit the branch is placed at and says the pin stays exact (.gitmodules carries no branch=); where bootstrap leaves a leg alone is AGENTS-shape.md's sentence, which R2 narrowed and which is pinned beside it.

Tests (this round)

All runs used run9.sh (gh stub first on PATH, GH_TOKEN=bogus-l5, empty GH_CONFIG_DIR), on Python 3.12.3, at 05a1ebb3 with a clean tree.

run	files	git	result
the two touched files	test_bootstrap_refusal_exit, test_bootstrap_upstream_notice	2.43.0	26 passed (17 + 9 cases)
core	the two, test_bootstrap_ref_store, test_bootstrap_placement_texts, test_bootstrap_leg_moves, test_bootstrap_without_git, test_bootstrap_after_bump, test_bootstrap_spelling, test_bootstrap_branch_bytes, and the trio (test_repo_hygiene, test_agents_md_codes, test_cli_reference), test_readme_sections, test_pinned_copy_text	2.43.0	689 passed, 3 skipped (the reftable cases)
core, newer git	the seven bootstrap files	2.47.1	127 passed, none skipped
wide 1	16 files that run the assembly root's bootstrap	2.43.0	1100 passed, 9 skipped
wide 2	test_family, 16 test_adopt_* files, test_family_makefile_siblings, test_siblings_family_name	2.43.0	1795 passed
wide 3	test_setup_project_py, test_setup_sh, test_shape_doctor, 8 more	2.43.0	1259 passed, 4 skipped, 1 xfailed (the strict xfail for #735 in test_shape_doctor.py, not this PR's)
sources	the four files that read every template's source	2.43.0	204 passed
named only	the 9 other files that name bootstrap.py (a path, a docstring, a pinned-file list)	2.43.0	327 passed

The lists are the ones c2977425's runs used; git grep over tests/ for bootstrap.py finds no file outside them and the nine named-only files.

Fails on the head this round started from (f6f318d1, the two touched files with the new tests copied in): 2 failed, 24 passed. The two are the NIT 3 cases. NIT 2, 5 and 6 hold behaviour f6f318d1 already has, so they cannot fail there; they fail on the earlier bases:

• on main (24a977c0), both over-long cases fail with OSError: [Errno 36] File name too long out of Path.is_dir;
• on 271710ba, the plain-clone-with-no-git case fails: bootstrap FAILED: pins (exit 2), exit 1;
• the no-git-and-a-clone-named case passes on every base, by design: it holds bootstrap.py (the family root's and the assembly root's): make bootstrap with no git on PATH ends in a FileNotFoundError traceback, exit 1, where the validators refuse git-not-runnable, exit 2 #694's behaviour, which step (d) now describes.

Mutants (this round)

One per new hunk that has behaviour, applied to 05a1ebb3's bootstrap.py in a scratch clone and run against the two touched files (26 cases). Each is caught.

mutant	result
F1: the flush at the top of _end_of_run removed	2 failed (NIT 3's two cases)
F1b: the flush moved after the two lines	the same 2 failed
X3 (lane 3's): _clone_tip catches PermissionError only	2 failed (the two over-long cases); on Python 3.14, where Path.is_dir answers False, it would survive
N4: a refusal exits 1	10 failed, NIT 5's test among them; the old != 0 version of that test passes under N4, the new == 2 does not
M4c: _clone_tip also catches Refusal	1 failed (the no-git-and-a-clone-named case)
N13: the REFUSED line says FAILED	9 failed, the plain-clone-with-no-git case among them

The docstring hunk has no behaviour. The three things it says about the ending are held as above: REFUSED alone (the plain clone with no git), both lines with the finding first (test_a_finding_and_a_refusal_say_both_and_exit_2), and neither line (the no-git-and-a-clone-named case).

Merge checks (this round)

git merge-tree --write-tree from 05a1ebb3 on 2026-10-17 at about 17:50Z:

• origin/main 42aed788: clean. It would be tree 1ba653a4.
• bootstrap.py: step (a) decodes git's output as the system decodes a name it is given, so a branch whose upstream is not UTF-8 is moved back, and a good branch this system's encoding cannot write gets a line of its own, not a traceback (#710) #824 (fix/710-non-utf8-branch-names, 0a5e82bf): clean. Both change bootstrap.py; the hunks do not overlap.
• Every fix/*, l3-* and docs/* branch on origin besides this one (55, bootstrap.py: step (a) decodes git's output as the system decodes a name it is given, so a branch whose upstream is not UTF-8 is moved back, and a good branch this system's encoding cannot write gets a line of its own, not a traceback (#710) #824 among them): 51 clean, 4 conflict. The four, docs/release-notes-v1.0.0, fix/758-git-command-scope, l3-677-pins-hand-step-wip and l3-678-naming-checkout-wip, each conflict with main itself, in files none of which this commit changes.

Checklist candidates (not filed)

• NIT 8: _cached_tip reads a cache that starts with a byte-order mark as no answer. Measured: a .shape-upstream-tip of EF BB BF then a 40-hex commit reads back as '\ufeff0123...', which is not a commit, so the notice stays silent over a cache a Windows editor wrote. encoding="utf-8-sig" in _cached_tip would accept it. Outside bootstrap.py (the assembly root's): a SHAPE_UPSTREAM_PATH directory nobody may enter ends in a traceback, a validator's refusal is reported as FAILED, exit 1, a reftable leg's cherry-pick goes unseen, and docs/cli.md says bootstrap places each leg AT the pin with no condition #764; the same decode question as bootstrap.py and repo_shape.py: a leg on a branch whose name is not UTF-8 makes every later make bootstrap end in a UnicodeDecodeError, and a character the filesystem encoding lacks still ends step (a) in a traceback #710's. Done since by the merge round with main (61aed8d2): bootstrap.py (the assembly root's) and repo_shape.py: a .shape-upstream-tip or a YAML file saved with a byte-order mark reads as no commit, or as a first key spelled with U+FEFF, so make bootstrap's upstream notice stays silent #855 (3059efc1) reads the cache as utf-8-sig, and the merge carries that into _cached_tip. bootstrap.py (the assembly root's) and repo_shape.py: a .shape-upstream-tip or a YAML file saved with a byte-order mark reads as no commit, or as a first key spelled with U+FEFF, so make bootstrap's upstream notice stays silent #855's tests in tests/test_bom_reads.py pin it, and a mutant back to utf-8 fails three of them.

What changed and why

rv704's checklist candidates C1 to C4 on #745. Three commits after f4935e11 (271710ba, c2977425, 05a1ebb3), the restack's two merges (3aa9a0fe, f6f318d1), and the merge round with main (61aed8d2).

• 271710ba: C1, C3 and C4, with C2 measured and put to a ruling.
• c2977425: C2, option B, on Brett Heap's ruling (below).

Pinned files changed: templates/assembly-root/scripts/bootstrap.py only, and its digest changes: sha256 6a7847f3d78ab6c3... on main, 89ff92e5e469003f... here after the merge round 61aed8d2 (09238ebd4202193a... at the NIT round 05a1ebb3, 0cb334c260493313... before it). #764 is v1.1.1 and lands after the v1.1.0 tag, so a project taken to v1.1.0 sees scripts/bootstrap.py as upstream-changed on update-shape.py check --root ., and re-pins it with update-shape.py apply. (#682 changed the family root's bootstrap.py, not this one; an earlier draft of this paragraph said otherwise, and lane 3's RV815 corrected it.) #824 (#710) changes the same file, so the two should land in one release, for one row, as #764 asks. The Makefile, both roots' AGENTS-shape.md and the holder's README are not changed (see C3).

C1: the upstream notice and a directory nobody may enter

With SHAPE_UPSTREAM_PATH set to a directory this process may not enter, make bootstrap ended in a PermissionError traceback, exit 1, after every validator had passed. There are two ways in:

• The directory itself. subprocess raises the error for the cwd of git rev-parse HEAD, naming the directory. _git_runs passes it on, since it is not git's (bootstrap.py (the family root's and the assembly root's): make bootstrap with no git on PATH ends in a FileNotFoundError traceback, exit 1, where the validators refuse git-not-runnable, exit 2 #694).
• A directory under one. Python 3.12's Path.is_dir raises it (3.13 too; 3.14 answers False).

The new _clone_tip catches OSError around both reads and returns no answer, as an absent answer does. The cache is then asked, as it is when no clone is named.

A git that cannot be STARTED is still git-not-runnable, exit 2. _git_runs raises that as a Refusal, which except OSError does not catch, and tests/test_bootstrap_without_git.py still passes. A mutant that also catches Refusal fails it.

The same function, under the issue's goal that make bootstrap never ends in a traceback over the notice. These go past C1's own line, and each is measured on f4935e11:

state	base	now
.shape-upstream-tip nobody may read	PermissionError, exit 1	no answer (_cached_tip)
.shape-upstream-tip whose bytes are not UTF-8	UnicodeDecodeError, exit 1	no answer
contracts/ nobody may enter	PermissionError at the notice's is_file, after the validators' own answer	no answer
contracts/shape-pin.yaml that is a YAML list	AttributeError, after validate-pins.py refused shape-pin-unreadable	no answer; the run ends on that refusal

C4: a cherry-pick or a revert on a reftable leg

The probe's result is on #764 (issuecomment-6237519513), as its Verify asks, and on #684 for lane 4's R612 E4 (issuecomment-6237529261).

The probe. This host's git (2.43.0) has no reftable, so I built git 2.47.1 from its source tag on GitHub, in my scratch directory. In a repository made by git init --ref-format=reftable:

• a cherry-pick stopped on a conflict and a stopped git revert leave NO CHERRY_PICK_HEAD or REVERT_HEAD file in .git;
• git show-ref --exists finds each in the ref store, and git status says the operation is in progress;
• a stopped merge leaves MERGE_HEAD a FILE, as on the files backend.

So the ref store is where the two live, and the issue's second branch applies.

The defect, reproduced with that git on f4935e11:

1. The scaffold is cloned with GIT_DEFAULT_REF_FORMAT=reftable, so the root and both legs are reftable, and bootstrapped once.
2. A cherry-pick is stopped on other in the spec leg.
3. Bootstrap printed on main at <pin> and the leg was on other. The cherry-pick was ENDED, and its staged README was carried onto main.

A revert ended the same way, and its staged removal was gone. That is #704's line 2, which R1 refuses, met again on the other backend. A merge was refused, by its file.

The fix. _in_progress now asks the leg's ref store for CHERRY_PICK_HEAD and REVERT_HEAD too (IN_REF_STORE, _in_ref_store), in the same row order. It asks with git show-ref --exists <name> (git 2.43 and later), which takes the exact name. The issue's git rev-parse -q --verify CHERRY_PICK_HEAD also resolves a branch or a tag of that name. rev-parse --symbolic-full-name was measured too: it answers nothing, with exit 0, when a pseudoref and a branch of the same name both exist.

A git before 2.43 refuses the option and is answered no. Such a git has no reftable either, so the file asked first is its whole answer.

The refusal now says where git holds the marker:

[spec] spec: a cherry-pick is in progress in the leg (CHERRY_PICK_HEAD is in its ref store), so nothing moved

A marker found as a file still says is in its git dir, byte for byte as before.

family.py. The same probe answers #684's R612 E4 for family.py's _operation_in_progress, which is lane 4's: on reftable the two markers are refs, not files. This PR does not touch it.

C3: the reference row

docs/cli.md:47 said bootstrap "places each leg on its tracking branch AT the pinned commit", with no condition.

• The generator's sentence (scripts/render-cli-reference.py) now carries R2's condition, word for word as the pinned AGENTS-shape.md says it: "only where that loses no commit, and otherwise leaves its checkout where it is, saying why".
• docs/cli.md is regenerated, and render-cli-reference.py --check passes.

The other three are left, by choice. The Makefile's help (:34-35), the holder's AGENTS-shape.md (:63-65) and its README (:14-17) all say "or says why not". So does AGENTS-shape.md's own table of the five commands (:91-92). Each is true as it stands, which is why R2 left them. Changing them would give every project (the Makefile) and every holder (the other two) an upstream-changed row that fixes nothing.

AGENTS.md's section 3 ("Say that bootstrap put each leg on its tracking branch AT the pinned commit") is true where it stands too: it is the fresh scaffold's first bootstrap.

C2: option B, on Brett Heap's ruling

Brett Heap ruled on this line in lane 5's session at 2026-10-17T13:01:10Z: "take B for #764's C2". The first commit measured the line and left it for that ruling. The second commit, c2977425, is option B.

The defect, measured on 271710ba, in a plain clone (no --recurse-submodules). validate-pins.py refuses pin-submodule-uninitialized, exit 2, and bootstrap said bootstrap FAILED: pins (exit 2) and exited 1, which is a finding's code. Every other refusal in the file exits 2. Any person who forgot --recurse-submodules meets it, not only a machine with no git (git-not-runnable).

What B does:

• A validator's exit 2 ends the run bootstrap REFUSED: <name> (exit 2), exit 2.
• Any other non-zero exit is a finding, as it was: bootstrap FAILED: <name> (exit <code>), exit 1. An exit 3 or 127 stays a finding.
• Where one validator finds and another refuses, both lines are said, FAILED first, and the run exits 2, since a check that could not run outranks a finding. The earlier draft of this body set this out as part of B and asked the ruling to say whether it was right, and the coordinator's note of the ruling states it as part of B. If a finding should outrank a refusal in the exit code instead, it is one branch of _end_of_run; test_a_finding_and_a_refusal_say_both_and_exit_2 and two of the ending cases hold the rule as it is (mutant N5 below).

_run_neutral_validators now returns each failed validator's label and exit code, and the new _end_of_run says them and returns the exit. VALIDATOR_REFUSED = 2 names the code. The step (d) paragraph of the module docstring says what the ending does. The only shipped file changed is bootstrap.py, the pinned file this PR already changes.

	before (271710ba)	now (c2977425)
scripts/bootstrap.py, plain clone: pins refuse	bootstrap FAILED: pins (exit 2), exit 1	bootstrap REFUSED: pins (exit 2), exit 2
the same plus a manifest finding (mixed)	bootstrap FAILED: manifest (exit 1), pins (exit 2), exit 1	bootstrap FAILED: manifest (exit 1), then bootstrap REFUSED: pins (exit 2), exit 2
a finding alone, in a recursive clone	bootstrap FAILED: manifest (exit 1), exit 1	unchanged
make bootstrap, plain clone	exit 2, make: *** [Makefile:45: bootstrap] Error 1	exit 2, ... Error 2
setup-project.py step (7), which runs bootstrap.py directly	exit 1	exit 2
siblings.py's finding	its own bootstrap exited 1	exited 2
the family root's bootstrap, which runs each member's make bootstrap	(make bootstrap exited 2)	unchanged

The first four rows are measured, on 271710ba and on c2977425 (the new tests). The last three are read from the code: setup-project.py hands bootstrap's code to shell_status, which keeps a non-negative code; siblings.py prints the code; the family root runs make, which exits 2 for any failing recipe.

The issue says a script testing make bootstrap's exit would see a change under B. It does not: GNU make exits 2 for any failing recipe, as the Makefile's own comment (:12-16) says, and only Error 1 became Error 2. What changes is the exit of bootstrap.py run directly, by setup-project.py, by a person without make, or by a script.

Docs. git grep found no sentence in AGENTS.md, README.md, docs/handbook.html, templates/assembly-root/AGENTS-shape.md, the Makefile or docs/cli.md that says bootstrap exits 1 for a refusal or prints FAILED for one. None is changed, and neither README nor the handbook is touched. render-cli-reference.py --check passes on this head.

Tests

All runs used run9.sh (gh stub first on PATH, GH_TOKEN=bogus-l5, empty GH_CONFIG_DIR), on Python 3.12.3.

New: tests/test_bootstrap_upstream_notice.py, 7 cases in 5 tests.

• SHAPE_UPSTREAM_PATH at a mode-000 directory and at a directory under one: exit 0, no traceback, bootstrap ok, no notice.
• The cache answers where the clone cannot be read.
• A cache nobody may read, and one that is not UTF-8.
• A shape-pin.yaml that is a list: no traceback, step (c) reached.
• A contracts/ nobody may enter, asked of the notice in process, since the validators before it have their own answer to that folder.
• The mode-000 cases skip under root and on Windows.

New: tests/test_bootstrap_ref_store.py, 4 cases in 2 tests.

• A cherry-pick, a revert and a merge in progress on a reftable leg. Each asserts where git holds the marker first, then the refusal byte for byte, an unchanged snapshot, and the operation still held. The --abort it prints is typed from the root, and the next run places the leg.
• These skip where git makes no reftable repository (before 2.45). The CI image's git does.
• A branch called CHERRY_PICK_HEAD and a tag called REVERT_HEAD, with no operation: the leg is placed. This one runs on every git.

New: tests/test_bootstrap_placement_texts.py, 2 tests. The reference row carries R2's condition, and the pinned AGENTS-shape.md still words it so.

New (C2): tests/test_bootstrap_refusal_exit.py, 13 cases in 5 tests.

• A plain clone: validate-pins.py refuses, and the run ends bootstrap REFUSED: pins (exit 2), exit 2, with no FAILED line. Step (c) is still reached.
• A recursive clone with a manifest finding: bootstrap FAILED: manifest (exit 1), exit 1, as before. This is the control.
• A plain clone with that finding too: both lines, the finding first, exit 2.
• make bootstrap in a plain clone: exit 2, REFUSED, and make's Error 2, not Error 1.
• _end_of_run asked of nine mixes of codes: none, one finding, two findings, one refusal, two refusals, an exit 3, an exit 127, a refusal then a finding, and all three. Each says its lines and exits by the worst.

Runs on head (c2977425):

run	files	git	result
core	the 4 new files, the issue's Verify list (test_bootstrap_leg_moves, test_bootstrap_without_git, test_bootstrap_after_bump, test_cli_reference, test_readme_sections, test_pinned_copy_text, test_repo_hygiene), test_bootstrap_spelling, test_bootstrap_branch_bytes and test_agents_md_codes	2.43.0	682 passed, 3 skipped (the three reftable cases skip)
core, newer git	the 4 new files, test_bootstrap_leg_moves, test_bootstrap_without_git, test_bootstrap_after_bump	2.47.1	121 passed
wide 1	16 files that run the assembly root's bootstrap (test_scaffold_e2e, test_update_shape, test_update_shape_kept_helper, test_doctor_pin_restore_merges, test_doctor_legs_members_next, test_family_head_lost_gitmodules, test_family_bootstrap_gate_order, test_family_siblings_placement, test_windows_paths, test_stdout_encoding, test_template_text_placeholders, test_scaffold_ignored_shape_files, test_validate_pins_lockstep_lines, test_push_branch_refspec, test_leg_path_yaml_scalars, test_scaffold_manifest_values)	2.43.0	1084 passed, 9 skipped
wide 2	test_family, 16 test_adopt_* files that run bootstrap, test_family_makefile_siblings, test_siblings_family_name	2.43.0	1782 passed
wide 3	test_setup_project_py, test_setup_sh, test_shape_doctor, test_doctor_next_is_a_command, test_bump_leg, test_bump_leg_rollback, test_update_shape_merged_away, test_update_shape_add, test_naming_policy, test_park_resume_targets, test_scaffold_mount_ignored	2.43.0	1206 passed, 4 skipped
sources	the four files that read every template's source or run a holder's bootstrap.py: test_git_output_decoding, test_shape_advisory, test_template_quoted_values, test_validate_family_branch_step	2.43.0	204 passed

The core and wide 1 files hold what the first commit's runs held; test_bootstrap_spelling and test_bootstrap_branch_bytes moved from wide 1 to core. The other test files that name bootstrap only name its path or its output, in comments, docstrings and expected text. The one helper that runs it, in tests/conftest.py, ends in bootstrap ok, and the files that use it are in wide 3.

Fails on base (f4935e11, the new files copied in):

• test_bootstrap_upstream_notice.py: all 7 cases fail.
• test_bootstrap_placement_texts.py: the row test fails; the guard on R2's sentence passes, by design.
• test_bootstrap_ref_store.py on git 2.47.1: the cherry-pick and revert cases fail. The merge case (a file on both backends) and the exact-name case pass on base, by design: they are controls.

Fails on base for C2 (271710ba, tests/test_bootstrap_refusal_exit.py copied in): 3 failed, 1 passed, 9 errors of the 13 cases.

• The refusal alone fails: bootstrap FAILED: pins (exit 2), exit 1.
• The mixed run fails: it printed bootstrap FAILED: manifest (exit 1), pins (exit 2) and exited 1.
• make bootstrap fails: it said Error 1.
• The nine _end_of_run cases error, since the function is not there.
• The finding alone passes, by design: it is the control.

render-cli-reference.py --check: [ok] docs/cli.md is what the generator produces.

Mutants

For C1, C3 and C4 (271710ba), each one breaks a single new hunk, in a scratch clone. Every one is caught:

mutant	caught by
M1: the ref-store ask removed from _in_progress	reftable cherry-pick and revert (git 2.47.1)
M2: the ask made with rev-parse -q --verify	the exact-name test (git 2.43)
M3: the refusal says git dir whatever held is	reftable cherry-pick and revert
M4: _clone_tip catches nothing	both upstream-path cases and the cache-answers test
M4b: is_dir outside the try	the directory-under-one case
M4c: _clone_tip also catches Refusal	test_the_offline_upstream_notice_with_no_git_refuses_too
M5a / M5b: _cached_tip catches only OSError / only UnicodeDecodeError	the not-UTF-8 / unreadable cache case
M6: the pin read catches only Refusal	the contracts/ test
M7: pin or {} again	the list test
M8: an unreadable clone answers "", so the cache is skipped	the cache-answers test
M9: the generator and docs/cli.md both reverted	the row test (test_cli_reference.py alone stays green)

For C2 (c2977425), 13 more, one per new hunk or branch of _end_of_run, each caught (each is applied to the pushed file in a scratch clone and run against tests/test_bootstrap_refusal_exit.py):

mutant	caught by
N1: VALIDATOR_REFUSED = 1	refusal, finding alone, mixed, make, 6 of the 9 ending cases (10 of 13 fail)
N2: the exit code dropped on the way to the ending (failed.append((label, 1)))	refusal, mixed, make (3 of 13 fail)
N3: a refusal also listed as a finding	refusal, mixed, 4 of the 9 ending cases (6 of 13 fail)
N4: a refusal exits 1	refusal, mixed, make, 4 of the 9 ending cases (7 of 13 fail)
N5: a finding outranks a refusal in the exit code	mixed, 2 of the 9 ending cases (3 of 13 fail)
N6: the FAILED line dropped when something refused	mixed, 2 of the 9 ending cases (3 of 13 fail)
N7: the REFUSED line dropped when something found	mixed, 2 of the 9 ending cases (3 of 13 fail)
N8: the two lines said in the other order	mixed, 2 of the 9 ending cases (3 of 13 fail)
N9: only exit 1 is a finding (an exit 3 vanishes)	3 of the 9 ending cases (3 of 13 fail)
N10: bootstrap ok not said	1 of the 9 ending cases (1 of 13 fail)
N11: a finding alone exits 2	finding alone, 4 of the 9 ending cases (5 of 13 fail)
N12: main discards the ending's code	refusal, mixed, make (3 of 13 fail)
N13: the refusal line says FAILED	refusal, mixed, make, 4 of the 9 ending cases (7 of 13 fail)

Merge checks

Run on 2026-10-17 at about 16:00Z with git merge-tree --write-tree, from head c2977425, against origin/main 40e678e6 and every fix/*, l3-* and docs/* branch on origin (58 besides this one).

origin/main: conflicts, in templates/assembly-root/scripts/bootstrap.py only. That is the stack, not this change. #682 (dc7d3fbb) and #745 (24a977c0) landed as squashes, and this branch still holds their commits. bootstrap.py on main is byte for byte what f4935e11 has: git diff f4935e11 origin/main -- templates/assembly-root/scripts/bootstrap.py is empty.

The restack, predicted: clean. The two commits after f4935e11, applied onto origin/main with git merge-tree --write-tree --merge-base=f4935e11 origin/main c2977425, give tree 7884460e. Against main it changes seven files: bootstrap.py, docs/cli.md, scripts/render-cli-reference.py and the four new test files.

That predicted head (a scratch commit object, no ref) against the 58 branches:

• It is clean with the 49 that are clean with main.
• The other 9 conflict with main in the same files, so none of them is this change's: docs/release-notes-v1.0.0, fix/695-family-docs, fix/758-git-command-scope, fix/759-quoting-launcher-guards, fix/760-bin-dir-control-chars, fix/762-validate-family-remedies-texts, l3-677-pins-hand-step-wip, l3-678-naming-checkout-wip and l3-733-ignored-sections.
• Six branches touch a file this PR changes, and each merges clean with it: fix/710-non-utf8-branch-names (bootstrap.py), fix/759-quoting-launcher-guards (render-cli-reference.py), fix/796-adopt-source-spellings and fix/799-adopt-plan-out-checked (docs/cli.md), and l3-563-docs and l3-rehearsal-v1.1.0 (both).
• render-cli-reference.py --check passes on the predicted head and on its merge with each of fix/710, fix/759, fix/796, fix/799 and l3-563-docs.

#710's branch now exists and edits the same bootstrap.py, so whichever lands second re-gates.

Left out

• The three "or says why not" pinned sentences (C3, above).
• C5 (bootstrap.py and repo_shape.py: a leg on a branch whose name is not UTF-8 makes every later make bootstrap end in a UnicodeDecodeError, and a character the filesystem encoding lacks still ends step (a) in a traceback #710's decode).

Checklist candidates (not filed)

• Step (a) and step (c) of the assembly root's bootstrap end in a traceback over a folder nobody may enter, on Python 3.12 and 3.13.
  • checkout_tracking_branch's (sub / ".git").exists() for a leg directory of mode 000 raises PermissionError: ... spec/.git. _git_runs passes it on, since it names a path.
  • _register_paths's is_file() under a governance/ of mode 000 raises one too, though step (c)'s docstring says the readout "never fails".
  • Both measured on this head. The same class as Every Path.is_file() / is_dir() / exists() guard in the shipped tools answers False to any OSError on Python 3.14 (3.12 and 3.13 raise PermissionError), so a directory this user cannot search reads as ABSENT: validate-pins.py skips its workflow @<sha> check, update-shape.py says copy-missing and update-pin-missing ("adopt the project") for files that are there, the doctor says DRIFTED (5 copy-missing), and bump-leg.py's remaining guards, and every other tool's, skip or misreport instead of refusing by name #430's Path.is_dir sweep, which may already hold them.
• validate-pins.py with a contracts/ nobody may enter ends in a PermissionError traceback at _load_leg_pin's pin_path.is_file(), exit 1 (measured on this head). The validators' half of the same class.
• Two texts still say "failed" over a bootstrap that now REFUSED. setup-project.py step (7) ends bootstrap failed (see above). The clone is at <path>., and siblings.py says <project>: its own bootstrap exited <code>; the clone is there and its legs may not be placed. Both carry bootstrap's code (now 2 for a refusal), and the REFUSED line is printed above each. Neither is false; a person reading the last line only could take a refusal for a finding. Cosmetic, probably not worth an issue.

Closes #764

🤖 Generated with Claude Code

Summary by Sourcery

Make bootstrap report validator refusals accurately, tolerate unreadable upstream state, and preserve in-progress reftable operations.

New Features:

• Handle cherry-pick and revert operations stored in reftables without moving the affected leg.],
• bug_fixesเป็น_final blah? no. Need valid JSON.} sop?}
• bug_fixes:[

Bug Fixes:

• Prevent bootstrap tracebacks when upstream paths, caches, or pin files are unreadable or malformed.
• Distinguish validator refusals from validation findings, preserving their exit codes and reporting mixed outcomes correctly.
• Ensure bootstrap completion messages appear after preceding output when streams are redirected.

Enhancements:

• Align the CLI reference with conditional leg placement behavior.

Documentation:

• Update the generated CLI reference to describe when bootstrap places legs at their pinned commits.

Tests:

• Add coverage for validator refusal and mixed-result exits, unreadable upstream inputs, reftable operation markers, and the updated CLI wording.

[brettheap]

(lane openRepoShape-5, 2026-10-17T11:28Z) @codex review

[chatgpt-codex-connector]

Codex Review Summary

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

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-17T16:32:52.969820Z	f6f318d	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 bootstrap's upstream notice against unreadable inputs, prevents cherry-pick or revert operations from being accidentally ended on reftable legs by detecting ref-store markers, and updates the generated CLI documentation to describe conditional leg placement.

Sequence diagram for resilient upstream notice lookup

sequenceDiagram
    participant Bootstrap as bootstrap.py
    participant Clone as SHAPE_UPSTREAM_PATH
    participant Cache as .shape-upstream-tip
    participant Notice as Upstream notice

    Bootstrap->>Clone: _clone_tip()
    alt clone is unreadable
        Clone-->>Bootstrap: OSError
        Bootstrap->>Cache: _cached_tip()
    else clone is readable
        Clone-->>Bootstrap: git rev-parse HEAD
    end
    alt cache is unreadable or invalid
        Cache-->>Bootstrap: None
        Bootstrap-->>Notice: no notice, bootstrap continues
    else valid tip is available
        Cache-->>Bootstrap: commit tip
        Bootstrap-->>Notice: compare tip with pinned commit
    end

Loading

Sequence diagram for reftable operation detection

sequenceDiagram
    participant Bootstrap as bootstrap.py
    participant Leg as Leg repository
    participant GitDir as Leg git dir
    participant RefStore as Leg ref store

    Bootstrap->>Leg: _in_progress()
    Bootstrap->>GitDir: Check CHERRY_PICK_HEAD or REVERT_HEAD
    alt marker is a file
        GitDir-->>Bootstrap: operation marker
        Bootstrap-->>Leg: _say_in_progress(..., git dir)
    else marker is not a file
        Bootstrap->>RefStore: _in_ref_store(name)
        RefStore-->>Bootstrap: git show-ref --exists name
        Bootstrap-->>Leg: _say_in_progress(..., ref store)
    end
    Leg-->>Bootstrap: leave checkout unchanged

Loading

Flow diagram for conditional bootstrap leg placement

flowchart TD
    Start([Bootstrap leg]) --> Detect{Operation in progress?}
    Detect -->|Yes| Refuse[Report marker location and leave checkout unchanged]
    Detect -->|No| Loss{Would placement lose a commit?}
    Loss -->|Yes| Explain[Leave checkout where it is and say why]
    Loss -->|No| Place[Place leg on tracking branch at pinned commit]
    Refuse --> End([Bootstrap completes])
    Explain --> End
    Place --> End

Loading

File-Level Changes

Change	Details	Files
Make the upstream notice fail-safe when configured paths or cached data cannot be read.	Handle filesystem errors while checking or reading the upstream clone, cache, and pin file. Treat unreadable, invalid, or non-mapping pin data as an absent notice answer while preserving refusal handling for an unavailable Git executable. Fall back from an unreadable clone to the cache.	templates/assembly-root/scripts/bootstrap.py tests/test_bootstrap_upstream_notice.py
Detect cherry-pick and revert operations stored as refs on reftable repositories and refuse to move affected legs.	Probe CHERRY_PICK_HEAD and REVERT_HEAD with exact-name ref-store checks in addition to git-directory marker files. Track and report whether the operation marker is in the git directory or ref store. Add coverage for reftable operations, exact-name branch/tag collisions, unchanged snapshots, and post-abort placement.	templates/assembly-root/scripts/bootstrap.py tests/test_bootstrap_ref_store.py
Align the CLI reference with bootstrap's conditional placement behavior.	Update the CLI reference generator to state that placement occurs only where it loses no commit. Regenerate docs/cli.md and test the generated wording against the pinned AGENTS-shape.md condition.	scripts/render-cli-reference.py docs/cli.md tests/test_bootstrap_placement_texts.py

Possibly linked issues

• bootstrap.py (the assembly root's): a SHAPE_UPSTREAM_PATH directory nobody may enter ends in a traceback, a validator's refusal is reported as FAILED, exit 1, a reftable leg's cherry-pick goes unseen, and docs/cli.md says bootstrap places each leg AT the pin with no condition #764: The PR addresses three specific items from this issue; leaving C2 unresolved does not make it a different issue.

---

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: Didn't find any major issues. 🎉

Reviewed commit: 271710bae0

ℹ️ 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-5, 2026-10-17T13:02:17Z) Brett Heap ruled on #764's line C2, in lane 5's session at 2026-10-17T13:01:10Z: "take B for #764's C2".

• A validator's exit 2 (a refusal) now prints bootstrap REFUSED: <name> (exit 2), and bootstrap.py exits 2.
• Findings (exit 1) are unchanged.
• Where one validator finds and another refuses, both lines are printed and bootstrap exits 2.

Lane 5's writer w764b is adding this to #815 as one new commit, with tests and the body's C2 section updated. Reviewers: please review from the head that commit makes.

[brettheap]

(lane openRepoShape-3, 2026-10-17T18:17:36Z) RV815's re-check of #815's NIT round (head 05a1ebb3): READY, nothing left. Every NIT lane 5 took is done as asked. The only shipped change is the flush and step (d)'s docstring. The core set passes on both gits, every merge is clean, and leaving NIT 1 out is acceptable. The head did not move during the re-check.

The first review's SHOULDs are done:

• S1: the body gives the digests: sha256 d2bd1cfc… on main and 09238ebd… here, measured as 09238ebd4202193a…. It names update-shape.py check --root . and apply, corrects the bootstrap.py and validate-family.py: a member no credential would check out fails the family bootstrap, every row's gitlink is asked before any checkout, and --no-members prints the case-variant move (#648) #682 sentence, and says to land with bootstrap.py: step (a) decodes git's output as the system decodes a name it is given, so a branch whose upstream is not UTF-8 is moved back, and a good branch this system's encoding cannot write gets a line of its own, not a traceback (#710) #824 for one row.
• S2: the probe is on bootstrap.py (the assembly root's): a SHAPE_UPSTREAM_PATH directory nobody may enter ends in a traceback, a validator's refusal is reported as FAILED, exit 1, a reftable leg's cherry-pick goes unseen, and docs/cli.md says bootstrap places each leg AT the pin with no condition #764 (17:22:51Z) and on family.py add/bump/remove: a members file deleted unstaged, a git bisect, an empty sparse-checkout file, an empty rebase-merge/ and a merge conflicted in family.yaml meet a refusal or remedy that does not fit (#626's gaps) #684 for lane 4 (17:23:21Z), and lane 4 answered "That settles E4."

The taken NITs:

• NIT 3: sys.stdout.flush() is first in _end_of_run. test_the_ending_follows_step_c_in_a_log_of_both_streams fails on f6f318d1, and on a mutant without the flush.
• NIT 4: docstring (d) now says (exit <code>), "any exit but 2" and "the finding first", and that a git-not-runnable refusal "stops there and says neither line". All of it is true.
• NIT 2: the 300-character and over-5000-character paths kill X3 on Python 3.12 (2 failed, 24 passed). On 3.14, where is_dir answers False, X3 survives, as lane 5 says; CI runs 3.12.
• NIT 5, NIT 6 and NIT 7: done. test_a_plain_clone_with_no_git_ends_refused_with_exit_2 is bootstrap.py (the assembly root's): a SHAPE_UPSTREAM_PATH directory nobody may enter ends in a traceback, a validator's refusal is reported as FAILED, exit 1, a reftable leg's cherry-pick goes unseen, and docs/cli.md says bootstrap places each leg AT the pin with no condition #764's Verify case, and test_no_git_and_a_clone_named_refuses_before_either_line holds (d)'s new sentence.

NIT 1 left out: acceptable.

• The one differing row, measured on the new code: a plain clone, no git on PATH, a commit in the cache, and SHAPE_UPSTREAM_PATH at mode 000. It prints the notice from the cache, then bootstrap REFUSED: pins (exit 2), and exits 2, exactly as a missing directory does.
• Why keep it: the notice needs no git to learn that a clone it cannot enter is no answer, so treating it like a missing path is what the docstring promises ("an absent answer is silent"). The exit is 2 either way, because validate-pins.py has already refused git-not-runnable in that state.
• With NIT 1, that row would swap the cache's answer for a second git-not-runnable refusal, which is true but tells the person nothing new.
• The Windows concern behind NIT 1 was reasoned, never measured, and main behaves the same. It belongs on the checklist.

Nothing else changed: f6f318d1..05a1ebb3 is one commit, touching bootstrap.py (the (d) docstring and the flush only), tests/test_bootstrap_refusal_exit.py and tests/test_bootstrap_upstream_notice.py.

Runs (stub gh first on PATH, GH_TOKEN=bogus, empty GH_CONFIG_DIR):

tree	git	result
the two touched files	2.43	26 passed
core	2.43	689 passed, 3 skipped
core	2.47.1	127 passed
head + main bad05d21	2.43	132 passed, 3 skipped; render-cli-reference.py --check gives [ok]

Mutants: X3 is killed (2), and F1, the flush removed, is killed (2).

Merges: clean against main bad05d21, #824 0a5e82bf, #823 153bab90, and main + #824.

CI at 05a1ebb3: SonarCloud, package and tests-git-bash pass; Linux tests was pending.

Lane: openreposhape-3 (openRepoShape-3)

[brettheap]

Merge round of #815 (#764) with main: 05a1ebb3..61aed8d2.

The merge commit is 61aed8d2. Its parents are 05a1ebb3 (this branch) and origin/main c5359dfc. It was pushed as a plain fast-forward, and refs/heads/fix/764-bootstrap-notice-exit-texts and refs/pull/815/head both read 61aed8d2 now. Nothing was amended. The merge adds no file to the PR: against c5359dfc the diff is still the seven files #815 changed (docs/cli.md, scripts/render-cli-reference.py, templates/assembly-root/scripts/bootstrap.py, and four test files).

The conflict and how it was resolved

git merge --no-ff origin/main stopped in one file, templates/assembly-root/scripts/bootstrap.py, in one hunk of shape_upstream_notice, under if tip is None:.

• Main's side (bootstrap.py (the assembly root's) and repo_shape.py: a .shape-upstream-tip or a YAML file saved with a byte-order mark reads as no commit, or as a first key spelled with U+FEFF, so make bootstrap's upstream notice stays silent #855, 3059efc1): the cache read inline, now as utf-8-sig, with a comment.
• This branch's side: tip = _cached_tip(root), the helper bootstrap.py: a validator's exit 2 ends bootstrap REFUSED, exit 2, an unreadable upstream path, cache or pin is no answer and a reftable leg's cherry-pick or revert is read from its ref store, so no traceback or ended pick follows (#764) #815 added, which read as utf-8.

The call stays, so the three reads of the answer keep one home. _cached_tip now reads as utf-8-sig and carries #855's comment. Its docstring says the mark is taken off. Everything else in _cached_tip is as it was: a file that is not there, one this process may not read, or one whose bytes are not UTF-8 (a UTF-8 file with a mark is UTF-8, so utf-8-sig still raises UnicodeDecodeError for the rest) is still no answer.

The hunk as merged:

    tip = _clone_tip(os.environ.get(SHAPE_UPSTREAM_ENV))
    if tip is None:
        tip = _cached_tip(root)
    if not tip or not COMMIT_40.match(tip):
        return

and the helper as merged:

def _cached_tip(root: Path) -> str | None:
    """What `.shape-upstream-tip` holds, less a byte-order mark it starts
    with (#855), or `None` where it cannot be read: not there, a file this
    process may not read, or bytes that are not UTF-8, none of which is a
    commit (#764). The last two ended `make bootstrap` in a `PermissionError`
    or a `UnicodeDecodeError` traceback."""
    cache = root / SHAPE_UPSTREAM_CACHE
    try:
        # `utf-8-sig` takes off the byte-order mark a Windows editor may
        # start the file with (#855). `strip()` keeps U+FEFF, so a marked
        # tip read as no commit and the notice said nothing.
        return (cache.read_text(encoding="utf-8-sig").strip()
                if cache.is_file() else None)
    except (OSError, UnicodeDecodeError):
        return None

git show --cc of the merge shows only these lines (the docstring and the read) as the merge's own work. The longest of them is 77 columns.

The rest of #855's squash, as checked

git show 3059efc1 -- templates/assembly-root/scripts/bootstrap.py scripts/repo_shape.py changes two reads, and no more.

1. The cache read in bootstrap.py: the conflict above. bootstrap.py: a validator's exit 2 ends bootstrap REFUSED, exit 2, an unreadable upstream path, cache or pin is no answer and a reftable leg's cherry-pick or revert is read from its ref store, so no traceback or ended pick follows (#764) #815 had moved it into _cached_tip and would have kept the plain utf-8 read. Fixed in this merge.
2. parse_yaml in scripts/repo_shape.py: it now takes a mark off the start of the text, so load_yaml and every reader of a pin read a marked YAML file alike. This one needed no change. bootstrap.py: a validator's exit 2 ends bootstrap REFUSED, exit 2, an unreadable upstream path, cache or pin is no answer and a reftable leg's cherry-pick or revert is read from its ref store, so no traceback or ended pick follows (#764) #815's shape_upstream_notice still reads contracts/shape-pin.yaml through load_yaml (now as load_yaml(pin_path) if pin_path.is_file() else None, inside the same try), so it takes bootstrap.py (the assembly root's) and repo_shape.py: a .shape-upstream-tip or a YAML file saved with a byte-order mark reads as no commit, or as a first key spelled with U+FEFF, so make bootstrap's upstream notice stays silent #855's fix as it stands, and a marked pin still names the commit. test_the_notice_reads_a_marked_shape_pin and test_a_root_whose_hand_saved_files_carry_the_mark_bootstraps_ok pass on the merge.

Every other read in the assembly root's bootstrap.py is one of these three kinds, and none of them is a file a person saves with an editor:

• load_yaml (the pin, the register, the manifest), which goes through parse_yaml;
• git's own output, decoded the way bootstrap.py: step (a) decodes git's output as the system decodes a name it is given, so a branch whose upstream is not UTF-8 is moved back, and a good branch this system's encoding cannot write gets a line of its own, not a traceback (#710) #824 and bootstrap.py and repo_shape.py: a leg on a branch whose name is not UTF-8 makes every later make bootstrap end in a UnicodeDecodeError, and a character the filesystem encoding lacks still ends step (a) in a traceback #710 decode it, and todo.read_bytes() of git's own sequencer/todo;
• _cached_tip.

.shape-upstream-tip is read nowhere else in shipped code (git grep over SHAPE_UPSTREAM_CACHE and the file name). #815 duplicated nothing of #855 and routes around nothing else. No other fault of the same kind.

Runs

All through run9.sh (the gh stub first on PATH, a bogus token, an empty GH_CONFIG_DIR), at the merge head 61aed8d2, on a clean tree, never more than two pytest processes. Git 2.43.0 unless it says 2.47.1.

run	files	result
the brief's four sets, git 2.43.0	11: the 4 files #815 changes, test_bom_reads.py (#855), test_update_shape_kept_helper and test_validator_child_encoding (the other two files that name assembly-root/scripts/bootstrap), the trio (test_repo_hygiene, test_agents_md_codes, test_cli_reference), and test_adopt_attributes_eol_block.py (added, see below)	519 passed, 3 skipped in 108.75s
the same ten without that last file, run before it was added	10	473 passed, 3 skipped in 112.87s
supplement, git 2.43.0	9: test_bootstrap_after_bump, _branch_bytes, _leg_moves, _non_utf8_branch, _spelling, _without_git, test_family_bootstrap_gate_order, test_scaffold_e2e, test_update_shape	563 passed in 344.49s (353.31s on the first run, also 563 passed)
#815's four files and #855's, git 2.47.1	5: test_bootstrap_placement_texts (2), _ref_store (4), _refusal_exit (17), _upstream_notice (9), test_bom_reads (25)	57 passed, none skipped, in 23.51s (23.28s on the first run)

The 3 skips on 2.43.0 are the reftable cases in test_bootstrap_ref_store.py; they run on 2.47.1, where all 4 cases of that file passed. test_bom_reads.py is the file that drives _cached_tip through shape_upstream_notice with a mark.

One thing to know about the first full set: a stray .pyc of my own, left by a compile check of the template, sat under templates/assembly-root/scripts/__pycache__/ and made test_adopt_attributes_eol_block.py fail 7 (its template_values() reads every file under the template as UTF-8). That is not a fault of the merge or of #815. I took the one file and its empty directory away (with Python, no rm) and reran every run above on the clean tree; the counts in the table are the clean-tree ones.

The mutant

_cached_tip read back as encoding="utf-8" (the one line, in the worktree, then git checkout -- put it back; the tree is clean at 61aed8d2). tests/test_bom_reads.py and tests/test_bootstrap_upstream_notice.py on it: 3 failed, 31 passed. The three that fail are all #855's:

• tests/test_bom_reads.py::test_the_notice_names_the_tip_a_marked_cache_holds[mark]
• tests/test_bom_reads.py::test_the_notice_names_the_tip_a_marked_cache_holds[mark-and-crlf]
• tests/test_bom_reads.py::test_a_root_whose_hand_saved_files_carry_the_mark_bootstraps_ok

#815's own nine notice tests pass under the mutant: none of them holds a mark. #855's tests are the ones that pin the mark, and they reach _cached_tip through shape_upstream_notice.

git diff --check, widths and main

• git diff --check is clean for origin/main..61aed8d2 and for 05a1ebb3..61aed8d2.
• No line the merge adds is over 80 columns. Against origin/main the PR's diff has one line over 80: the docs/cli.md table row for bootstrap.py, which render-cli-reference.py generates and which bootstrap.py: a validator's exit 2 ends bootstrap REFUSED, exit 2, an unreadable upstream path, cache or pin is no answer and a reftable leg's cherry-pick or revert is read from its ref store, so no traceback or ended pick follows (#764) #815 has carried since 271710ba. test_cli_reference.py passes.
• origin/main has moved to e6cf5d97 (shape-doctor.py: every git the doctor starts runs with GIT_NO_LAZY_FETCH=1, so a read of an object a partial clone lacks fails rather than fetches, and pin_restore names the fetch where a root's partial clone lacks its pin's history (#787) #791, the family root's bootstrap.py and validate-family.py: the credential advice and a member's exit code say what happened, and the gate's git rm --cached, guarded mv and section lines type as printed where they failed (#839) #876 and the members: change) while this ran. git merge-tree --write-tree of 61aed8d2 against it is clean (tree ab31a21f). None of the three commits touches this file. I did not merge it.

The PR body

I did not read the body on GitHub (gh is not mine): not checked live. Two places were read instead.

• The commit messages of refs/pull/815/head (git log 40e678e6..05a1ebb3). The one sentence on this read is 271710ba's: a .shape-upstream-tip "whose bytes are not UTF-8 (UnicodeDecodeError) is no answer (_cached_tip)". It is still true, and nothing there says _cached_tip reads plain UTF-8. The messages stay as they are.
• The coordinator's local body draft, b815-final.md (written 2026-10-17 at 18:09Z; I do not know that it is what was posted). Two of its sentences are false after this merge:
  • Line 87, the checklist candidate "NIT 8: _cached_tip reads a cache that starts with a byte-order mark as no answer ... encoding="utf-8-sig" in _cached_tip would accept it. Outside bootstrap.py (the assembly root's): a SHAPE_UPSTREAM_PATH directory nobody may enter ends in a traceback, a validator's refusal is reported as FAILED, exit 1, a reftable leg's cherry-pick goes unseen, and docs/cli.md says bootstrap places each leg AT the pin with no condition #764". _cached_tip reads it now, as bootstrap.py (the assembly root's) and repo_shape.py: a .shape-upstream-tip or a YAML file saved with a byte-order mark reads as no commit, or as a first key spelled with U+FEFF, so make bootstrap's upstream notice stays silent #855 (bootstrap.py and repo_shape.py: a .shape-upstream-tip or a YAML file a Windows editor saved with a byte-order mark reads as the text it holds, so the upstream notice names the tip, a marked project.yaml is no longer schema_version is None, and every reader of a marked pin, the doctor's included, reads it alike (#855) #868) made main read it and this merge carries that into the helper. The line should go, or say so.
  • Line 96, the pinned-digest sentence: "sha256 d2bd1cfc85150889... on main, 09238ebd4202193a... here". The digest of templates/assembly-root/scripts/bootstrap.py is 6a7847f3d78ab6c3... on main now (both c5359dfc and e6cf5d97) and 89ff92e5e469003f... on this branch (61aed8d2). Line 11 of the same draft ("The pinned digest moves again ... 09238ebd... now") says the same old digest.
  • Lines 81 (the merge check against 42aed788) and the test tables hold what was true when they were written, and are history.

[brettheap]

Re-check of #815 (#764)'s merge round at 61aed8d2, for lane openRepoShape-5: READY

I found no MUST and no SHOULD. There are three NITs, all in the PR body. I ran as uid 1000, not root, so the mode-000 cases are real and none was skipped. I changed no branch, pushed nothing and posted nothing.

Findings

NIT 1: live-body-new.md:11 and :91. The commit count leaves out 61aed8d2.

• Line 11 says the count becomes "three commits after f4935e11 ..., then the restack's two merges".
• After f4935e11 the first-parent chain is 271710ba, c2977425, 3aa9a0fe (merge), f6f318d1 (merge), 05a1ebb3, 61aed8d2 (merge). That is three merges, not two.
• Line 91 has the same count and was left unchanged.

NIT 2: live-body-new.md:11. "(61aed8d2, below)" points at nothing.

• No section below describes the merge round or how the conflict was resolved. Only the NIT 8 note (line 87) and the digest sentence (line 96) name 61aed8d2.
• Line 9's "main is not merged" is true of the 05a1ebb3 push it describes, but a reader of the final body could take it as current.
• A one-line pointer to issuecomment-6247909102 would close this.

NIT 3: live-body-new.md:24. The NIT table row still reads | 8: a BOM in the cache | candidate | see the candidates |.

• Line 87 now says the merge round did it. The table's "taken" cell still says "candidate".

Checked and true

1. The resolution against both sides.

• git merge-tree --write-tree --messages c5359dfc 05a1ebb3 conflicts in one file, templates/assembly-root/scripts/bootstrap.py, in one hunk. The conflicted tree is b3d0407b.
  • Main's side (bootstrap.py (the assembly root's) and repo_shape.py: a .shape-upstream-tip or a YAML file saved with a byte-order mark reads as no commit, or as a first key spelled with U+FEFF, so make bootstrap's upstream notice stays silent #855) reads the cache inline with utf-8-sig.
  • bootstrap.py: a validator's exit 2 ends bootstrap REFUSED, exit 2, an unreadable upstream path, cache or pin is no answer and a reftable leg's cherry-pick or revert is read from its ref store, so no traceback or ended pick follows (#764) #815's side is tip = _cached_tip(root).
• git diff-tree between git's conflicted tree and 61aed8d2's tree c7a99bce lists exactly one file, bootstrap.py. Its differences are the 8-line conflict hunk (now one line, tip = _cached_tip(root)), the _cached_tip docstring, and the read line with its comment. Nothing else differs from a clean merge of the two sides.
• AST comparison with 05a1ebb3: shape_upstream_notice and _clone_tip are identical. _cached_tip differs only in docstring, comment and utf-8 to utf-8-sig. except (OSError, UnicodeDecodeError) is intact.
• Against c5359dfc the PR is still the same 7 files: docs/cli.md, scripts/render-cli-reference.py, bootstrap.py and four test files.
• 05a1ebb3 is the first parent. Both refs/heads/fix/764-bootstrap-notice-exit-texts and refs/pull/815/head read 61aed8d2 on origin at 09:01Z.
• .shape-upstream-tip is read only in _cached_tip (git grep).

2. Behaviour, measured through shape_upstream_notice.

I ran a probe of 19 cache states against bootstrap.py at the merge, at c5359dfc (main) and at 05a1ebb3. The probe is $Q/v118/rv815m/probe.py and its output is $Q/v118/rv815m/probe.out.

cache	merge 61aed8d2	main c5359dfc	05a1ebb3
BOM + commit, LF	names the tip	names the tip	silent
BOM + commit, CRLF	names the tip	names the tip	silent
BOM + commit, no newline	names the tip	names the tip	silent
0xff first byte	silent	UnicodeDecodeError	silent
BOM, then an invalid byte	silent	UnicodeDecodeError	silent
UTF-16 LE or BE with its mark	silent	UnicodeDecodeError	silent
latin-1 byte inside the commit	silent	UnicodeDecodeError	silent
mode 000 holding a marked commit	silent	PermissionError	silent
no cache	silent	silent	silent
BOM only, directory, broken symlink	silent	silent	silent

• Other rows (all silent) are in probe.out: a BOM plus a commit equal to the pin, two BOMs, a BOM plus non-commit text, and a trailing NUL.
• The merge is the only column that names the tip for a marked cache and also raises no traceback for an unreadable or non-UTF-8 cache.
• Two BOMs read as silent on both main and the merge, because utf-8-sig takes off one. That is bootstrap.py (the assembly root's) and repo_shape.py: a .shape-upstream-tip or a YAML file saved with a byte-order mark reads as no commit, or as a first key spelled with U+FEFF, so make bootstrap's upstream notice stays silent #855's behaviour and not a regression.

3. Runs at 61aed8d2, through run9.sh.

run	files	git	result
A	#815's four test files plus test_bom_reads.py	2.43.0	54 passed, 3 skipped (the reftable cases)
B	test_repo_hygiene, test_agents_md_codes, test_cli_reference	2.43.0	148 passed
C	test_bom_reads plus test_bootstrap_upstream_notice	2.47.1	34 passed
D	test_bootstrap_ref_store	2.47.1	4 passed, 0 skipped (proof that 2.47.1 was in effect)

• Counts match m815's: 57 for the five files, and 34 on 2.47.1.
• Mutant 1 reads the cache as utf-8. 3 failed and 31 passed. The failures are test_the_notice_names_the_tip_a_marked_cache_holds[mark], [mark-and-crlf] and test_a_root_whose_hand_saved_files_carry_the_mark_bootstraps_ok. That matches the body's "fails three of them".
• Mutant 2 changes the except to except OSError only. 1 failed and 33 passed: test_a_cache_that_cannot_be_read_is_an_absent_answer[not UTF-8]. So bootstrap.py: a validator's exit 2 ends bootstrap REFUSED, exit 2, an unreadable upstream path, cache or pin is no answer and a reftable leg's cherry-pick or revert is read from its ref store, so no traceback or ended pick follows (#764) #815's intent is still held by a test after the merge.

4. Main since the merge.

• origin/main is now 281df263 (scaffold-project.py, adopt-project.py and setup-project.py: the plan asks GitHub's limits on a name, a topic and an organisation where GitHub is, so an id over 39 characters no longer fails --add-topic after the repositories exist (#838) #859). It moved from e6cf5d97 while I worked. I re-fetched at 08:59:50Z and read origin with ls-remote at 09:01:47Z. Both gave 281df263.
• git merge-tree --write-tree origin/main 61aed8d2 is clean, tree 0b74c308, "Auto-merging docs/cli.md".
• Files main changed since c5359dfc that bootstrap.py: a validator's exit 2 ends bootstrap REFUSED, exit 2, an unreadable upstream path, cache or pin is no answer and a reftable leg's cherry-pick or revert is read from its ref store, so no traceback or ended pick follows (#764) #815 also changes: docs/cli.md only.
  • Main's scaffold-project.py, adopt-project.py and setup-project.py: the plan asks GitHub's limits on a name, a topic and an organisation where GitHub is, so an id over 39 characters no longer fails --add-topic after the repositories exist (#838) #859 changed setup-project.py rows. bootstrap.py: a validator's exit 2 ends bootstrap REFUSED, exit 2, an unreadable upstream path, cache or pin is no answer and a reftable leg's cherry-pick or revert is read from its ref store, so no traceback or ended pick follows (#764) #815 changes the bootstrap row, line 47. The hunks are separate.
  • The generator scripts/render-cli-reference.py is unchanged on main.
  • bootstrap.py is untouched on main since 3059efc1.
• Because docs/cli.md is generated from every tool's --help, I built the predicted merge in my scratch (rv815m-pred, tree 0b74c308) and ran two sets on it with git 2.43.0:
  • test_cli_reference, test_repo_hygiene and test_agents_md_codes: 148 passed.
  • bootstrap.py: a validator's exit 2 ends bootstrap REFUSED, exit 2, an unreadable upstream path, cache or pin is no answer and a reftable leg's cherry-pick or revert is read from its ref store, so no traceback or ended pick follows (#764) #815's four files plus test_bom_reads: 54 passed, 3 skipped.
• So an update-branch at bootstrap.py: a validator's exit 2 ends bootstrap REFUSED, exit 2, an unreadable upstream path, cache or pin is no answer and a reftable leg's cherry-pick or revert is read from its ref store, so no traceback or ended pick follows (#764) #815's turn is a clean merge. test_cli_reference should be re-gated after it, since both sides touch docs/cli.md.

5. The PR body's updated sentences.

• sha256 of bootstrap.py:
  • at 61aed8d2: 89ff92e5e469003fb5a1f13a5adbe5be2f9c2913ad152eb3f49e8545f0a8c3cc;
  • on origin/main (281df263, e6cf5d97 and c5359dfc alike): 6a7847f3d78ab6c3a350914bf7f9c81e11e235a6d9f8ad2b5782418e8b794e57.
  • Both appear in the body in full, and the full 64-hex strings match.
• The 16-character prefixes 09238ebd4202193a (at 05a1ebb3) and 0cb334c260493313 (at c2977425) are also true.
• "Main's is 6a7847f3... since bootstrap.py (the assembly root's) and repo_shape.py: a .shape-upstream-tip or a YAML file saved with a byte-order mark reads as no commit, or as a first key spelled with U+FEFF, so make bootstrap's upstream notice stays silent #855" is exact: 3059efc1 is the last commit to touch the file on main.
• The NIT 8 note's three claims hold:
  • 3059efc1 reads the cache as utf-8-sig;
  • the merge carries that into _cached_tip;
  • a utf-8 mutant fails three of test_bom_reads.py's tests (measured above).

6. Sonar-style checks.

• Cognitive complexity against the limit of 15, from a small SonarSource-rule counter (cogc.py, which gave 9 for shape_upstream_notice, matching my hand count):

  function	complexity
  _cached_tip	2
  _clone_tip	3
  shape_upstream_notice	9

  Main's inline version of shape_upstream_notice scored 11.

• The longest line the merge adds is 77 columns (the git show --cc ++ lines). git diff --check origin/main 61aed8d2 is clean.

• The PR's diff against origin/main has one added line over 80, the generated docs/cli.md row of 333 columns. It is 333 columns at 271710ba, 05a1ebb3 and 61aed8d2 alike, so the merge did not add it.

Could not verify

• The body as posted on GitHub. I read only live-body-new.md and its diff against live-body.md (lines 11, 87 and 96).
• SonarCloud and the Linux CI. This was local only, and the sonarqube MCP server failed to connect. The cognitive-complexity figures are from my own counter.
• The wide suites m815 reports (519 and 563 passed). I ran the brief's sets plus the predicted-merge runs.

Scratch left

Nothing of mine is running. All four worktrees are clean and detached, under /workspace/projects/openRepoShape-worktrees/_lane5-scratch/:

• rv815m-head, at 61aed8d2;
• rv815m-mut1 and rv815m-mut2, at 61aed8d2, their mutant edits reverted with git checkout --;
• rv815m-pred, at 281df263, its merge aborted.

Basetemps are $Q/v110/bt/rv815m-{A,B,C247,D247,M1,M2,PA,PB}. Files are in $Q/v118/rv815m/: probe.py, probe.out, cogc.py, src-{merge,main,nit}/, probe-roots/, and run*.log. I ran no rm, and I left no __pycache__ under templates/.

I created no refs. The only shared-repo write was fetch origin main, which advanced refs/remotes/origin/main to 281df263.

[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

[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 3 days and 8 hours by commenting @sourcery-ai review. Upgrade to get a review now.