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

Goal: make bootstrap never ends in a traceback over the optional upstream notice, tells a validator's refusal from its findings, sees an operation in progress on either ref backend, and every text that says what it places says the condition #704 now holds it to.

Filed by lane openRepoShape-5, from rv704's checklist candidates C1 to C4 on #704's PR (#745, head 7bdfa3cc, "not taken here as the coordinator ruled"). C5, the strict UTF-8 read in _upstream_holding, is not here: it is the decode #710 changes.

Lands after: lane 5's #704 and #694 (PR #745, fix/704-bootstrap-leg-moves, stacked on #682, fix/648-bootstrap-and-gate-order). _in_progress and the narrowed AGENTS-shape sentence are in #745; the other lines read the same on main. Line numbers are at main 66b230ed unless a line says 7bdfa3cc.

Pinned copies. templates/assembly-root/scripts/bootstrap.py, templates/assembly-root/Makefile and templates/assembly-root/AGENTS-shape.md are pinned in every project, and the family holder's AGENTS-shape.md in every holder. Bundle the edits with #710's (the same bootstrap.py, lands once) so each project takes one upstream-changed row per file.

Lines

• C1, a SHAPE_UPSTREAM_PATH directory nobody may enter ends in a PermissionError traceback, exit 1. shape_upstream_notice (templates/assembly-root/scripts/bootstrap.py:642-678; :854-894 at 7bdfa3cc) runs Path(upstream).is_dir() and _try_git(["rev-parse", "HEAD"], Path(upstream)) (:663-665). _try_git catches Refusal only, so the PermissionError that subprocess raises for a working directory it cannot enter leaves the function, and main ends in the traceback. The docstring says the opposite (:649-650: "silent ... and it never fails the bootstrap"). Measured by rv704 on head and on base, on this host's Python 3.12. 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 (in bootstrap.py and AGENTS-shape.md: a leg with an operation in progress or an ignored file in the way is refused, P9 names the branch it left, and no git is git-not-runnable, so make bootstrap loses nothing (#704) (#694) #745) makes _git_runs skip an OSError that names a directory ("which subprocess raises for a cwd it cannot enter, is not git's, and goes on as it did"), so it leaves exactly this one. 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 sweep of Path.is_dir() guards is the sibling for the other half (3.12 and 3.13 raise PermissionError where 3.14 answers False). Direction: the notice catches OSError around the two reads and says nothing, as an absent answer does; add one test with SHAPE_UPSTREAM_PATH set to a mode-000 directory (skipped under root and on Windows) that asserts exit 0 and no traceback.
• C2, a validator's exit-2 refusal is reported as bootstrap FAILED: pins (exit 2), exit 1. Measured by rv704 with no git on PATH, in a plain clone. _run_neutral_validators (:845-870) puts every non-zero code in failed as "<label> (exit <code>)", and main prints bootstrap FAILED: ... and returns 1 (:906-908). The validators exit 1 for findings and 2 for a refusal (REFUSED ... (exit 2)), and bootstrap's own refusals are exit 2 since 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 (git-not-runnable), so a person reading FAILED and exit 1 is told a finding where the validator refused. This needs a ruling. The shape of a fix is main returning 2 when any validator exited 2 and saying REFUSED for that label, but a script that tests make bootstrap's exit would see a change; the other answer is to leave it and say in AGENTS-shape.md that FAILED (exit 2) is a refusal.
• C3, docs/cli.md:47 says bootstrap "places each leg on its tracking branch AT the pinned commit", with no condition. scripts/render-cli-reference.py:181-184 generates it; docs/cli.md is checked against it by tests/test_cli_reference.py. bootstrap.py and AGENTS-shape.md: a leg with an operation in progress or an ignored file in the way is refused, P9 names the branch it left, and no git is git-not-runnable, so make bootstrap loses nothing (#704) (#694) #745's narrowed sentence in the assembly root's AGENTS-shape.md (:100-101 at 7bdfa3cc, rulings R1 and R2) says it "places a leg on its tracking branch AT the pin only where that loses no commit, and otherwise leaves its checkout where it is, saying why". Three more pinned sentences say "where that loses no commit, or says why not" and R2 left them, because "or says why not" keeps them true: templates/assembly-root/Makefile:34-35, the holder's templates/family-root/AGENTS-shape.md:63-65 and its templates/family-root/README.md:14-17. Direction: the generator's sentence takes the condition, docs/cli.md is regenerated, and the other three take R2's words or are left, in the same re-pin; the author decides and says which.
• C4, on a reftable leg CHERRY_PICK_HEAD and REVERT_HEAD may live in the ref store, not as files, so the in-progress check would not see them. _in_progress (:468-486 at 7bdfa3cc) asks os.path.lexists(gitdir / row[0]) for each of IN_PROGRESS (:117-124), which holds MERGE_HEAD, CHERRY_PICK_HEAD and REVERT_HEAD among the rows. Reasoned only: this host has git 2.43, which has no reftable (rv704; bootstrap.py and AGENTS-shape.md: a leg with an operation in progress or an ignored file in the way is refused, P9 names the branch it left, and no git is git-not-runnable, so make bootstrap loses nothing (#704) (#694) #745's body). Direction: the same as 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's R612 E4, which asks it of family.py's _operation_in_progress (scripts/family.py:942) and gives the first step: build a repository with git init --ref-format=reftable on git 2.45 or later, stop a cherry-pick and a revert, and list .git; if they are files, close this as not a defect; if not, ask the ref store (git rev-parse -q --verify CHERRY_PICK_HEAD, qualified, since it also resolves a branch of that name). One answer decides both tools.

Verify: tests/test_bootstrap_leg_moves.py and tests/test_bootstrap_without_git.py (new in #745), tests/test_bootstrap_after_bump.py, tests/test_cli_reference.py, tests/test_readme_sections.py, tests/test_pinned_copy_text.py and tests/test_repo_hygiene.py pass on Linux. C1: the mode-000 test above. C2, once ruled: a plain clone with no git, asserting the exit and the word. C3: the regenerated docs/cli.md and the one --check run of the generator. C4: the probe's result, in the issue, and a test only if the ref store is where they live. No Windows or macOS run.

Overlaps. fix/704-bootstrap-leg-moves (#745) edits templates/assembly-root/scripts/bootstrap.py and templates/assembly-root/AGENTS-shape.md, so this lands after it. #710 changes git_out's decode and the same bootstrap.py; whichever lands second re-gates against the other. fix/665-four-guards (#724) and l3-563-docs (#630) edit scripts/render-cli-reference.py; #630 also edits docs/cli.md. #684 (lane 4, v1.1.0) holds the family.py half of C4. No open branch edits templates/assembly-root/Makefile.

Parent: #458.

Milestone: v1.1.1. None is a regression and none blocks v1.1.0: C1 needs a hand-set variable and a directory nobody can enter, C2 and C4 change no file a person has, and C3 is a sentence that is true where nothing is lost.

🤖 Generated with Claude Code