[brettheap]

Lane: openreposhape-5 (openRepoShape-5)
Claim: #273 (comment)
Claim: #339 (comment)

After #409 (#275)

Brought up to date after #409 squash-landed by merging origin/main (9736424, #409's squash) as f9ed46f. Its scaffold-project.py conflict was resolved to this branch's side once git diff b70a07d 9736424 -- scaffold-project.py (#409's final head against its squash) came out empty. So the file is the one tested on this branch plus main's own later changes to it, and holds nothing of #409's; details below.

This branch carries #275's adopt half. It was built on fix/pin-source-env-collisions, PR #409 (#275's scaffold half and its fix round), merged at 6494714 as 583f647, over the earlier 5690235 (34dbd86). After 6494714, #409 only merged main, five times, up to its final head b70a07d, and none of those merges has a hand edit (git show --remerge-diff is empty for each). Adopt's refusal of two products that share a source variable goes through #409's function, so this branch lands after #409. It was never rebased.

git diff b70a07d 9736424 is empty for each file #409 touched: scaffold-project.py, scripts/repo_shape.py, templates/assembly-root/scripts/validate-pins.py and tests/test_pin_source_env_collisions.py. What f9ed46f resolves, four files with one hunk each:

• scaffold-project.py.
  • The conflict hunk is main's block from PIN_COLLISION_REMEDIATION through _pin_collision_remediation, which scaffold-project.py, validate-pins.py, repo_shape.py: open-glass and open_glass share one SHAPE_PIN_SOURCE_<PRODUCT>, so --pin refuses the pair and validate-pins.py notes a declared one and reads the variable for neither (#275) #409's squash edits: it adds PIN_VARIABLE_REMEDIATION, _colliding_pin_variables and _pin_collision_remediation and changes _refuse_colliding_pins. This branch moved all of that to scripts/shape_materialize.py. The hunk takes this branch's side. (The merge commit's message says "re-adds"; this is the exact account.)
  • scaffold-project.py, validate-pins.py, repo_shape.py: open-glass and open_glass share one SHAPE_PIN_SOURCE_<PRODUCT>, so --pin refuses the pair and validate-pins.py notes a declared one and reads the variable for neither (#275) #409's auto-merged import of PIN_SOURCE_ENV_PREFIX, pin_source_env_collisions is dropped, because nothing in the file uses either name any more.
  • It is not git checkout --ours of the whole file. Main changed the file beyond scaffold-project.py, validate-pins.py, repo_shape.py: open-glass and open_glass share one SHAPE_PIN_SOURCE_<PRODUCT>, so --pin refuses the pair and validate-pins.py notes a declared one and reads the variable for neither (#275) #409 since this branch last merged it: scaffold-project.py and family.py: --tracking-branch is asked of git check-ref-format --branch before anything exists, so ~, a..b, x.lock and a/ are refused under --dry-run and no longer die at the first git init -b after gh repo create has made the repositories (#283) #355's --tracking-branch check (6c2a371) and a73b4e9's RULESET_HINT. Those lines stay.
  • The result is the file git merge-tree gives for this branch with main before the squash (518010b). Its diff from the file tested here has the same patch-id as main's own 3ef059c..518010b change to it.
• templates/assembly-root/scripts/validate-pins.py. Main's side, which is scaffold-project.py, validate-pins.py, repo_shape.py: open-glass and open_glass share one SHAPE_PIN_SOURCE_<PRODUCT>, so --pin refuses the pair and validate-pins.py notes a declared one and reads the variable for neither (#275) #409's final blob, with main's templates/assembly-root/scripts/validate-pins.py: a workflow file under .github/workflows/ that is not UTF-8 ends the run in a UnicodeDecodeError traceback, exit 1, with no refusal naming the file, so the project's pins gate (make validate, the validate workflow) dies on a Latin-1 comment where a non-UTF-8 pin is a clean REFUSED yaml-unreadable, exit 2 #359 workflow reader in it. This branch had no change of its own to the file beyond scaffold-project.py, validate-pins.py, repo_shape.py: open-glass and open_glass share one SHAPE_PIN_SOURCE_<PRODUCT>, so --pin refuses the pair and validate-pins.py notes a declared one and reads the variable for neither (#275) #409.
• adopt-project.py, _commit_the_split.
  • Main: adopt-project.py: every failure once a leg repository exists flushes stdout, then prints REFUSED <step>., what failed and one notice of what the run left, so a failed git filter-repo no longer exits 2 with an empty stderr (#171, #188, #177) #445 wraps the function in its late-failure try, and adopt-project.py: execute records in project.yaml which leg the plan gave each submodule a leg keeps, and shape-doctor.py holds the submodule to that row, so one in the other leg is MISPLACED and a real adoption's placement reads ok (#189) #394 builds an append with the plan's submodule record.
  • This branch: its only edits there were a comment and neutral_pins=_recorded_pins(plan) on the materializer call.
  • Both now sit on main's call inside the try: append=append, neutral_pins=_recorded_pins(plan).
• docs/cli.md. It is regenerated with scripts/render-cli-reference.py, and --check is ok. It differs from main's only in the --pin, --pin-owner and --pin-source help of adopt-project.py plan.

scripts/repo_shape.py, templates/assembly-root/scripts/validate-pins.py and tests/test_pin_source_env_collisions.py are main's blobs, which are #409's: this branch adds nothing to them. Nothing of #409 is lost. Its scaffold behaviour is shape_materialize.refuse_colliding_pins and pin_variable_collisions, keyed by #409's pin_product_key.

73d65c6, after the merge.

• The change. _read_pins reads plan.get("pins") where it read plan.data.get("pins").
• Why. adopt-project.py: every failure once a leg repository exists flushes stdout, then prints REFUSED <step>., what failed and one notice of what the run left, so a failed git filter-repo no longer exits 2 with an empty stderr (#171, #188, #177) #445's tests/test_adopt_late_failure.py hands _commit_the_split a SplitPlan as its plan, a dict that adds entries. On f9ed46f, three of its tests stopped at "committing the split" with AttributeError: 'SplitPlan' object has no attribute 'data' (3 failed, 83 passed in that file).
• Nothing else changes. Plan.get with no default returns plan.data.get(key) exactly, so a loaded plan reads as before.

What was wrong (#273)

adopt-project.py plan --pin took a NAME only (--pin openGlass) and refused a trailing @<commit>. plan, check and execute each exited 0, and execute printed adoption verified. The manifest then listed the name in neutral_product_pins: with no contracts/<product>-pin.yaml beside it, and on its first run the adopted root's own validate-pins.py refused it as neutral-pin-missing.

#273's table, reproduced on c7c02fa with the issue's own commands (local bare remotes, and a stub gh that exits 97):

--pin	c7c02fa	this branch
openGlass	execute exit 0, - openGlass; clone's validate-pins.py exit 2 neutral-pin-missing	plan exit 2 pin-malformed, with the scaffold's remediation (--pin openGlass@<40 hex>); no plan is written
opensoft/openGlass	exit 0, - opensoft/openGlass; exit 2 neutral-pin-missing for contracts/opensoft/openglass-pin.yaml	plan exit 2 pin-malformed
spec	exit 0; validate-pins.py exit 0, reading the leg's contracts/spec-pin.yaml as the neutral pin	spec@<sha> is adopt-pin-collides at plan
shape	exit 0; contracts/shape-pin.yaml read as the neutral pin	shape@<sha> is adopt-pin-collides at plan
openGlass@<sha>, opensoft/openGlass@<sha>	plan exit 2 adopt-pin-malformed	plan, check and execute exit 0, and gh is called 0 times. contracts/openglass-pin.yaml is written and the manifest lists - openGlass. In the clone, validate-manifest.py exits 0, and validate-pins.py exits 0 with openGlass: pin commit … digest recomputes

What changed (#273)

Brett ruled for decision 1's first option ("go with your recommendation on #273"): adopt takes the scaffold's pin and writes the scaffold's pin file. That reverses the NAME-only --pin from #6, and the comment that described it is replaced with the new contract.

• One implementation. The scaffold's pin code moved into scripts/shape_materialize.py, next to neutral_pin_path and the materializer that writes the file. What moved:

  • PIN_ARG_RE, parse_pin, pin_digest_from_source and pin_digest_from_gh;
  • declared_pin_values, declared_pin_products and PIN_COLLISION_REMEDIATION (in 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's wording);
  • from scripts/repo_shape.py: pin_source_env_name turns every character outside [A-Z0-9_] into _, so the neutral products open-glass, open_glass and open.glass share one SHAPE_PIN_SOURCE_OPEN_GLASS, and a project that pins two of them gets a neutral-pin-source-unreadable FINDING (exit 1) for whichever one the variable does not name #275's branch, PIN_VARIABLE_REMEDIATION and the variable check;
  • _refuse_colliding_pins, split into the pure pin_collisions and pin_variable_collisions, and refuse_colliding_pins(refusal=...), which raises one refusal for both.

  The code did not move verbatim. _refuse_colliding_pins became the three functions above; pin_digest_from_source was rewritten for scaffold-project.py: pin_digest_from_source catches only Refusal, so a --pin-source that does not exist, is a file, or sits under a parent this user cannot enter ends --dry-run and the real run alike in a FileNotFoundError, NotADirectoryError or PermissionError traceback (exit 1), where a directory that is not a clone is the pin-source-unreadable refusal (exit 2) with its remediation #339 (below); and fix round 1 changed three of them (below): pin_variable_collisions keys each pin by scripts/repo_shape.py: pin_source_env_name turns every character outside [A-Z0-9_] into _, so the neutral products open-glass, open_glass and open.glass share one SHAPE_PIN_SOURCE_OPEN_GLASS, and a project that pins two of them gets a neutral-pin-source-unreadable FINDING (exit 1) for whichever one the variable does not name #275's pin_product_key, pin_digest_from_source spells a path that is not printable, and pin_digest_from_gh refuses a missing gh. The scaffold's behaviour is otherwise unchanged. scaffold-project.py imports what it calls under its old names. Lane 5's review ran 34 scaffold cases (every pin refusal, the gh stub's four modes, dry and real successes) on 34dbd86 and on this branch at 7a94b6b. rc, stdout, stderr, the gh log and the files made were identical, apart from the shape's own commit and digest and scaffold-project.py: pin_digest_from_source catches only Refusal, so a --pin-source that does not exist, is a file, or sits under a parent this user cannot enter ends --dry-run and the real run alike in a FileNotFoundError, NotADirectoryError or PermissionError traceback (exit 1), where a directory that is not a clone is the pin-source-unreadable refusal (exit 2) with its remediation #339's row. Its pin tests and scripts/repo_shape.py: pin_source_env_name turns every character outside [A-Z0-9_] into _, so the neutral products open-glass, open_glass and open.glass share one SHAPE_PIN_SOURCE_OPEN_GLASS, and a project that pins two of them gets a neutral-pin-source-unreadable FINDING (exit 1) for whichever one the variable does not name #275's pass as they are. tests/test_git_output_decoding.py's exemption for pin_digest_from_gh follows the function to its new file.

• plan. --pin, --pin-owner and --pin-source mean what they mean for the scaffold. plan reads the digest from --pin-source or gh api, and records product, repository, commit, digest and digest_source in the plan, so check and execute read no network for a pin. plan refuses:

  • a name with no @<commit>, as pin-malformed. That includes an empty --pin '', which adopt used to drop and now refuses, as the scaffold always has;
  • spec, code and shape, in any case, as adopt-pin-collides (adopt-project.py --pin <name> is accepted by plan, check and execute ("adoption verified"), but writes only the name into neutral_product_pins: and no contracts/<name>-pin.yaml, so the adopted root's own validate-pins.py (and its validate.yml) refuses with neutral-pin-missing from the first run #273 decision 4), in the scaffold's sentence and remediation (scaffold-project.py --pin spec@<sha> (or code@, shape@, or two --pins whose products differ only by case) passes --dry-run, then creates all three repositories, pushes both legs and dies with REFUSED materialize-collision, because the pin's contracts/<product>-pin.yaml is a file the shape already writes #241, 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);
  • one product given twice, the same way, whether it is a repeat or two names that share one file (decision 5);
  • two products that one SHAPE_PIN_SOURCE_<PRODUCT> names, such as open-glass and open_glass, the same way, through scripts/repo_shape.py: pin_source_env_name turns every character outside [A-Z0-9_] into _, so the neutral products open-glass, open_glass and open.glass share one SHAPE_PIN_SOURCE_OPEN_GLASS, and a project that pins two of them gets a neutral-pin-source-unreadable FINDING (exit 1) for whichever one the variable does not name #275's check;
  • a leg path over a pin's file, as adopt-leg-path-collides;
  • a --pin-source path that check would refuse in digest_source: (fix round 1), as adopt-unwritable-value. It is asked only when a --pin records the path;
  • with no gh on PATH and no --pin-source, gh-not-found (fix round 1).

• check and execute. These are new check findings, and execute refuses each one before any leg exists. They come from _leg_findings, the list check and _refuse_what_check_finds share:

  • plan-pin-unrecorded: a name alone (an old plan's pins: [openGlass], or a hand edit), or an entry missing its commit or digest;
  • plan-pin-malformed;
  • plan-pin-collides, which covers two pins at one file, a pin at a file the shape writes, and two products that share one source variable;
  • plan-root-holds-pin: a source path kept in the root at the pin's file. The materializer would write the shape's pin beside it under shape/, and validate-pins.py would read the source's file instead.

  How each finding ends:

  • plan-pin-unrecorded and plan-pin-malformed end with the plan --pin <product>@<40 hex commit> that records the pin whole.
  • plan-pin-collides ends with re-running plan with each product once, or, for two products that share a source variable, with one product of each such group.
  • plan-root-holds-pin ends with the kept path's own remedy: send that entry to a leg, drop it, or rename it in the source and re-run plan.

  A leg moved over a pin's file in the plan is plan-leg-path-collides.

• Also part of adopt-project.py: Plan.__init__, allowed_empty_legs, names and open_source iterate or call .get on a hand-edited plan's pins:, allow_empty_legs:, paths:, legs: and source: without asking their type, so a scalar ends check and execute in a TypeError or AttributeError traceback, exit 1, and pins: openGlass passes check, adopts, and writes eight one-letter neutral-product pins that the project's own validate-pins.py refuses #386: its pins: row. A hand-edited pins: that is not a list (a name such as pins: openGlass, a number, a mapping, a quoted string) is now plan-pin-malformed in check (`pins:` is 'openGlass', not a list of pins), and execute refuses it before any leg exists.

  • Where: _read_pins in adopt-project.py; the test row is plan-pin-malformed-not-a-list in tests/test_adopt_pins.py.
  • Before: on main, check said plan ok for the name, the mapping and the string, and gave a traceback for the number (reproduced by lane 5's review on cb7063f). adopt-project.py: Plan.__init__, allowed_empty_legs, names and open_source iterate or call .get on a hand-edited plan's pins:, allow_empty_legs:, paths:, legs: and source: without asking their type, so a scalar ends check and execute in a TypeError or AttributeError traceback, exit 1, and pins: openGlass passes check, adopts, and writes eight one-letter neutral-product pins that the project's own validate-pins.py refuses #386 records that execute then wrote the name as eight one-letter pins.
  • Not fixed here: adopt-project.py: Plan.__init__, allowed_empty_legs, names and open_source iterate or call .get on a hand-edited plan's pins:, allow_empty_legs:, paths:, legs: and source: without asking their type, so a scalar ends check and execute in a TypeError or AttributeError traceback, exit 1, and pins: openGlass passes check, adopts, and writes eight one-letter neutral-product pins that the project's own validate-pins.py refuses #386's other keys, allow_empty_legs:, paths:, legs: and source:, so adopt-project.py: Plan.__init__, allowed_empty_legs, names and open_source iterate or call .get on a hand-edited plan's pins:, allow_empty_legs:, paths:, legs: and source: without asking their type, so a scalar ends check and execute in a TypeError or AttributeError traceback, exit 1, and pins: openGlass passes check, adopts, and writes eight one-letter neutral-product pins that the project's own validate-pins.py refuses #386 stays open. Lane 2's adopt-project.py: check names, and execute refuses before the work directory is made, a plan whose source: or legs: is not a mapping or whose allow_empty_legs: or paths: is not a list of what plan writes, and asks the same first of a pins: that is not a list, so a number or a boolean in any of the four no longer ends both in a traceback and allow_empty_legs: code is no longer read as four legs (#386) #435 takes all of adopt-project.py: Plan.__init__, allowed_empty_legs, names and open_source iterate or call .get on a hand-edited plan's pins:, allow_empty_legs:, paths:, legs: and source: without asking their type, so a scalar ends check and execute in a TypeError or AttributeError traceback, exit 1, and pins: openGlass passes check, adopts, and writes eight one-letter neutral-product pins that the project's own validate-pins.py refuses #386, pins: included, and its pins: rule keeps only text items where this branch writes mappings; whichever lands second reconciles them (adopt-project.py: check names, and execute refuses before the work directory is made, a plan whose source: or legs: is not a mapping or whose allow_empty_legs: or paths: is not a list of what plan writes, and asks the same first of a pins: that is not a list, so a number or a boolean in any of the four no longer ends both in a traceback and allow_empty_legs: code is no longer read as four legs (#386) #435 (comment), and "Where the meaning meets" below).

• execute. It writes each pin through materialize_assembly_root(neutral_pins=...). The manifest lists the product with the owner stripped (decision 3), so the entry and the file agree.

• Docs. --help is updated and docs/cli.md regenerated (render-cli-reference.py --check ok).

A --pin-source that cannot answer (#339)

pin_digest_from_source caught only Refusal. A directory that is no clone is git's own failure, so it was always pin-source-unreadable, exit 2. A path subprocess.run cannot enter never reaches git: it is a FileNotFoundError, NotADirectoryError or PermissionError out of cwd=, and nothing caught it. scaffold-project.py --pin ... --pin-source <that> ended --dry-run and the real run alike in a traceback, exit 1. Since the move above, adopt-project.py plan --pin reads its digest through the same function and ended the same way. Both reach it through declared_pin_values, and check and execute read no source, so that call is the only reader.

The issue's table, run on ab623dd for the scaffold and on d806e8f for adopt-project.py plan (adopt has no --pin-source on ab623dd), then on this head. gh is a stub that logs and exits 97, with GH_TOKEN bogus and an empty GH_CONFIG_DIR; it was called 0 times in every run:

--pin-source	before	this branch
a directory that is not a clone	pin-source-unreadable, exit 2	unchanged
a path that does not exist	FileNotFoundError traceback, exit 1	pin-source-unreadable, exit 2: <path> could not answer for opensoft/openGlass @ <40 hex>: no such directory
a file	NotADirectoryError, exit 1	exit 2, ... it is a file, not a directory
under a parent this user cannot enter	PermissionError, exit 1	exit 2, ... Permission denied
a symlink loop (not in the issue)	RuntimeError out of Path.resolve() on 3.12, exit 1	exit 2, ... Too many levels of symbolic links

The real run and --dry-run give the same stdout and stderr, and nothing exists afterwards (no remote directory, no work directory; for adopt, no plan file).

What changed, in scripts/shape_materialize.py only:

• pin_digest_from_source catches OSError as well as Refusal and raises the existing pin-source-unreadable with its remediation unchanged. The message names the path and the reason.
• stat() judges the source inside the guard, as validate-pins.py: a --pin-source value is PRODUCT=PATH only when the text before its first = names a declared neutral-product pin, so a bare stand-in under a=b/ recomputes the digest instead of falling to gh api and a skip, an explicit source that does not exist or is not a directory is the neutral-pin-source-unreadable finding instead of a FileNotFoundError traceback, and a value no pin used is noted (#295) #312 does in validate-pins.py, and the sentences are that file's: a missing path, or one beneath a file, is "no such directory"; a file is "it is a file, not a directory"; any other OSError, from stat() or from git's cwd=, is the system's own reason (strerror). It is not exists()/is_dir(), which before 3.14 swallow only a missing path. A source stat() can read but cwd= cannot enter, a directory with no search bit, fails in tree_digest and the same guard answers it.
• declared_pin_values resolves the path through a guarded _resolved_pin_source. Path.resolve() raises a RuntimeError on a symlink loop before 3.13 (an OSError since), before the digest was asked for. As typed, stat() meets the loop and says so.
• A source that answers is read exactly as before: a relative path resolves against the working directory, a symlink to a clone is followed, digest_source reads local-clone (<path as typed>), and the digest is tree_digest's.

tests/test_pin_source_unreadable.py (46 tests in the #339 commit; fix round 1 adds 17 for S1 and moves one, below) runs each case through scaffold-project.py --dry-run, its real run and adopt-project.py plan: missing, a file, beneath a file, relative and missing, a parent and a source with no search bit (skipped on Windows and as root, by a mark, so before any fixture builds a directory), a 300-character name, a symlink loop (skipped on Windows) and a directory that is no clone. Each asserts exit 2, the refusal naming the path and the reason, its remediation, no traceback and nothing created. It also holds --dry-run and the real run to the same stdout and stderr, checks the path is printed escaped under an ASCII stderr and as a surrogate when it is not UTF-8, and checks that a relative source and a symlink to a clone read as before. The session gh guard fails any test whose run called gh.

Main, and validate-pins.py

origin/main ab623dd reached this branch through implQ's branch: 34dbd86 is a30091f merged with ab623dd. One file conflicted there, templates/assembly-root/scripts/validate-pins.py, in seven hunks, because #312 (8cdca5e) replaced keyed_sources and default_source with PinSources and #275 added env_shared and shared. #312's blob is the same at its PR head, at the squash and at ab623dd, so it landed the file implQ resolved against. The resolution keeps #312's side in all seven and adds #275's on top:

#	hunk	resolution
1	resolve_neutral_pin_source signature	#312's sources: PinSources and 3-tuple return, plus #275's env_shared: bool = False
2	its docstring tail	#312's Returns (path, how, typed) text, plus #275's "Rule 2 is skipped when env_shared" paragraph
3	_recompute_neutral_pin_digest signature	#312's sources, plus #275's shared: frozenset[str] after report
4	the resolve_neutral_pin_source(...) call inside it	#312's 3-tuple unpack, plus env_shared = product.casefold() in shared and the extra argument
5	_check_one_neutral_product_pin signature	#312's sources, plus #275's shared
6	its call of _recompute_neutral_pin_digest	sources, report, shared
7	_check_neutral_product_pins docstring and body	#312's PinSources(...) and _note_unused_pin_sources, plus #275's paragraph, _report_pin_source_collisions(products, report) and shared = frozenset(pin_source_env_shared(products))

This branch's own merge of 34dbd86 (5690235) had no conflict, and neither had its merge of #409's fix round, 6494714 (583f647). That fix round made neutral-pin-source-collides a note and keyed "one product" by repo_shape.pin_product_key. At 421e4e5, templates/assembly-root/scripts/validate-pins.py, scripts/repo_shape.py and tests/test_pin_source_env_collisions.py were byte-identical to the tree git merge-tree gives for 6494714 with origin/main 3ef059c (blobs 5604007, 091966b, 5220787), so this branch added nothing to those three files beyond #409. The 34dbd86 merge brought in #335, #312, #317, #270 (f795cf7), #344 and #349 with no conflict. Earlier merges of origin/main (87373a6, for #309's reworded constant, and e43fa95) are unchanged.

Fix round 1 merged origin/main three more times:

• cd1fc79 (2bcfa69). It brought adopt-project.py: a relative .gitmodules url the plan keeps in a leg is resolved from the source's remote and from the leg's, and where the two differ check finds it and execute refuses before any leg exists, so a recursive clone no longer fails after adoption verified (#190) #245, scaffold-project.py: --elected-by, --reference, --name and the elector's fallback are refused before anything exists when no file can hold them, so a byte that is not UTF-8 no longer creates repositories before a traceback (#282) #351, validate-family.py: member-duplicate is decided from members: alone before the --no-members return and compares project: case-folded, so a family.yaml that names one row twice no longer passes the run a private family's CI falls back to, and rows IRRS and irrs are one finding naming both, since members/IRRS and members/irrs are one directory on macOS and Windows (#331) #350, family.py: bump --dry-run fetches the member, resolves --to and prints the old -> new row and its trailers without checking the member out or rewriting family.yaml, and remove --dry-run prints the row, gitlink, .gitmodules section and directory it would remove and changes nothing, so the module's EXIT CODES line is true of both (#326) #345, single-repository.yaml: openRepoShape records that it stays a single repository, as Brett Heap decided on 2026-10-11, so the Triad advisory is no longer said here (#337) #372, adopt-project.py, AGENTS.md: execute verifies before it exits on a refused gh pr create, and step 7 keys its way out to the exit it prints, so an IS pushed exit 2 is finished by hand, not re-run into a second pair of legs (#304) #371, shape-doctor.py: the legs and members NEXT is a script-free git submodule update --init --recursive over what a checkout cures, and the lockstep gate for what none does, so a root that lost scripts/bootstrap.py no longer pastes can't open file, and an empty mount or a leg committed past its pin on its tracking branch no longer pastes a bootstrap that leaves the row red (#276) #354, update-shape.py and bump-leg.py: a pin rewrite keeps each line's own indentation, spacing and trailing comment and reads its result back before writing it, so a digests: child indented four spaces takes the update instead of update-pin-unrecognised / bump-leg-pin-unrecognised, and a # comment on commit: or tree_sha256: survives every pin rewrite, rewrite_manifest included (#323) #380, adopt-project.py: plan asks about every source path execute will not extract as it is named, with the reason and root or drop as its only answers, so -notes.md is no longer planned leg: spec for check to refuse, and #166's split question says the same of such an entry (#319) #377 and the rest since ab623dd, with no conflict.
• 45e01f4 (4098b61). It brought tests/test_agents_md_codes.py: every backticked code-shaped name in AGENTS.md must be an exact string constant in a shipped tool, so a misspelt scaffold-pin-collides, or the code renamed in scaffold-project.py while AGENTS.md keeps its old spelling, fails naming the token and the document instead of leaving an assistant to relay a code no tool prints (#348) #396's tests/test_agents_md_codes.py. That test finds scaffold-pin-collides as a string constant of scripts/shape_materialize.py, which SHIPPED lists.
• 3ef059c (421e4e5), scaffold-project.py and adopt-project.py ask the project's YAML reader and validate-manifest.py about the manifest's values before anything exists, so --id null, --tracking-branch true and a blank --elected-by are refused (#258, #261) #314. One conflict, one hunk in adopt-project.py. This branch's _refuse_an_unrecordable_pin_source and scaffold-project.py and adopt-project.py ask the project's YAML reader and validate-manifest.py about the manifest's values before anything exists, so --id null, --tracking-branch true and a blank --elected-by are refused (#258, #261) #314's section "The project must be able to hold what execute writes into it (adopt-project.py and scaffold-project.py accept values the new project's own validate-manifest.py refuses (a blank --elected-by or --reference, --elected-on 2026-W41-6 or 20261011 on Python 3.11+, --org test+org, a plan's visibility: secret), so adoption verified or a scaffold exit 0 is followed by a failed first bootstrap; and plan admits a 251-255-character --project that check refuses #261)" were added at the same place; both are kept. Where the two meet, lane 5's earlier recipe applies:
  • _flag_plan builds each pin as the PIN_FIELDS mapping plan writes, not list(pins) of products. So the plan plan asks the validator about is the plan it writes.
  • scaffold-project.py and adopt-project.py ask the project's YAML reader and validate-manifest.py about the manifest's values before anything exists, so --id null, --tracking-branch true and a blank --elected-by are refused (#258, #261) #314's test_plan_asks_what_check_asks_of_the_same_keys plans --pin openGlass@<commit> --pin-source <stand-in> where it planned the name alone, which plan now refuses.

Then f9ed46f, after #409 squash-landed, and 73d65c6 after it (top of this description).

#270's pins-surrogate case

On the merged tree exactly one test failed: tests/test_adopt_template_values.py::test_check_finds_and_execute_refuses_a_hand_edited_value[pins-surrogate]. It plans, then hand-edits the plan to pins: ["openX\ud800"], a name-only pin with a lone surrogate. Before this branch the refusal's headline was REFUSED plan-unwritable-value. A name-only pin in a plan is now plan-pin-unrecorded (#273), so check has a second, independent finding for that very plan, and the headline is the first finding's:

REFUSED plan-pin-unrecorded: 2 finding(s) ...
FINDING plan-pin-unrecorded: `pins:` entry 1, 'openX\ud800', is a name with no commit and no digest ...
FINDING plan-unwritable-value: a `pins:` item is 'openX\ud800', which `execute` writes into the assembly root's `project.yaml`, and it holds a lone surrogate ...

Nothing about #270's contract changed. The lone surrogate is still found as plan-unwritable-value, listed under the refusal, and execute still refuses before any leg exists. check builds _leg_findings, where _pin_findings sits, before it calls _value_findings, so the pin finding comes first. d806e8f changes one assertion for that row, pins only: the headline is REFUSED plan-pin-unrecorded: where it was PLAN_REFUSED. The other 15 rows and the finding assertions, including the plan-unwritable-value line, are untouched.

Fix round 1

Lane 5's review of 7a94b6b found 3 should-fix and 5 nits. Each is answered here:

• scaffold-project.py, validate-pins.py, repo_shape.py: open-glass and open_glass share one SHAPE_PIN_SOURCE_<PRODUCT>, so --pin refuses the pair and validate-pins.py notes a declared one and reads the variable for neither (#275) #409's pin_product_key (review N1). The merge of scaffold-project.py, validate-pins.py, repo_shape.py: open-glass and open_glass share one SHAPE_PIN_SOURCE_<PRODUCT>, so --pin refuses the pair and validate-pins.py notes a declared one and reads the variable for neither (#275) #409's fix round could not carry it, because this branch had moved the function that used it out of scaffold-project.py. pin_variable_collisions now keys each pin by that function, where it casefolded. openß and openss are two pin files and one SHAPE_PIN_SOURCE_OPENSS, and a casefold named each of the two pins twice. No --pin or recorded pins: entry PIN_ARG_RE admits can spell either, so the test asks the function directly. refuse_colliding_pins' docstring now says, in scaffold-project.py, validate-pins.py, repo_shape.py: open-glass and open_glass share one SHAPE_PIN_SOURCE_<PRODUCT>, so --pin refuses the pair and validate-pins.py notes a declared one and reads the variable for neither (#275) #409's words, that the root's validate-pins.py only notes such a pair.
• S1, a --pin-source path that is not printable. pin_digest_from_source names the path as typed unless it is not printable (str.isprintable), and then as Python's repr spells it (shown_source). That covers the refusal's head and git's own reason, which names the directory it ran in. Printed raw, an ESC reached the terminal, and a line break or a carriage return began a line of the path's choosing, a forged REFUSED line among them, from the scaffold and from adopt. The traceback scaffold-project.py: pin_digest_from_source catches only Refusal, so a --pin-source that does not exist, is a file, or sits under a parent this user cannot enter ends --dry-run and the real run alike in a FileNotFoundError, NotADirectoryError or PermissionError traceback (exit 1), where a directory that is not a clone is the pin-source-unreadable refusal (exit 2) with its remediation #339 replaced had shown a repr. A printable path is named byte for byte as before.
• S2, no gh on PATH. pin_digest_from_gh refuses as gh-not-found, exit 2, as repo_shape.tree_digest_from_gh names it, and offers --pin-source. It was a FileNotFoundError traceback, exit 1, from the scaffold and, new with this branch, from adopt-project.py plan --pin.
• S3, a hand-edited commit: or tree_sha256:. The lane's decision is to accept it and document it (option (c)); no behaviour changed. A pair that disagrees passes check and execute (adoption verified), because neither reads a network for a pin, by design. The adopted root's own validate-pins.py then exits 1 with neutral-pin-digest-mismatch wherever it can read the product. check now says so once, after the pins it will write: "each pin as plan read it, not read again here: the root's own validate-pins.py recomputes its digest wherever it can read the product". Options (a), execute recomputes before it creates the legs, and (b), check recomputes from a clone still on the machine, are filed as adopt-project.py check and execute write a neutral pin's commit: and tree_sha256: exactly as the adoption plan records them and read neither again, so a hand edit that makes the two disagree is plan ok and adoption verified, and the adopted root's own validate-pins.py then exits 1 with neutral-pin-digest-mismatch on its first run #449.
• N2, a --pin-source that plan cannot record. plan asks check's question (one_printable_line) of the path it records in each pin's digest_source:, before any digest is read. It refuses one that fails as adopt-unwritable-value, in adopt-project.py: a value execute writes into a file is asked whether a file can hold it, in plan, in check and in execute before any leg exists, so a byte that is not UTF-8 in --elected-by, --reference or a local --source directory no longer pushes both legs before write_lf raises (#255) #270's words (unwritable_reason), or as "an invisible formatting character" where those name nothing. Before, it was planned, exit 0, and printed raw in the report. check then refused it as plan-pin-malformed and said to re-run the same plan. The report's pin line and check's write line now spell the digest's source with _shown. The scaffold half is pre-existing (a line break in the path is written into the pin file; a byte that is not UTF-8 dies after all three repositories exist) and is filed as scaffold-project.py --pin-source <path>: the path is written as it stands into the new root's contracts/<product>-pin.yaml (digest_source: local-clone (<path>), a bare placeholder) and is asked nothing first, so a clone at a path holding a line break scaffolds, exit 0, a pin file with a line of the path's choosing, and one at a path that is not UTF-8 creates all three repositories and then dies in write_lf with a UnicodeEncodeError traceback, exit 1 #450.
• N3, six hunks no test guarded. Each now has a test that fails when it alone is reverted:
  • the two name guards (a pins: name holding an ESC and a forged line);
  • the lower-casing of the commit and the digest (an upper-cased hand edit);
  • the digest_source printability check;
  • the not-text check (commit: 1234567 unquoted);
  • the gitlink filter (a submodule kept where the pin is written is plan-submodule-root alone).
• N4. This body.
• N5, scaffold-project.py: pin_digest_from_source catches only Refusal, so a --pin-source that does not exist, is a file, or sits under a parent this user cannot enter ends --dry-run and the real run alike in a FileNotFoundError, NotADirectoryError or PermissionError traceback (exit 1), where a directory that is not a clone is the pin-source-unreadable refusal (exit 2) with its remediation #339's third decision. A --pin-source that nothing reads is still silent, now in adopt too. This PR does not decide it. scaffold-project.py and adopt-project.py plan: a --pin-source that nothing reads (no --pin, and for the scaffold no --referent-chain link) is accepted in silence, even a path that does not exist, so --dry-run says nothing was created. and plan writes a plan, each exit 0 with no word that the flag changed nothing, where the root's own validate-pins.py notes such a value since #295 #451, filed, lays out refuse, note and leave, so closing scaffold-project.py: pin_digest_from_source catches only Refusal, so a --pin-source that does not exist, is a file, or sits under a parent this user cannot enter ends --dry-run and the real run alike in a FileNotFoundError, NotADirectoryError or PermissionError traceback (exit 1), where a directory that is not a clone is the pin-source-unreadable refusal (exit 2) with its remediation #339 loses nothing.

Fix round 2

Lane 5's second review, of 421e4e5, found no blocking item, 2 should-fix items and 3 nits. The two should-fix items are this body: the landing after #409 (above) and #386 (above). The code needed no change for them. f63d1ed adds two tests and no code:

• n1. plan asks nothing of a --pin-source no --pin records. With the args.pin and guard dropped, such a path holding an ESC or a zero-width joiner was refused in a sentence naming no file ("execute writes into , and ..."), and every test still passed. test_a_pin_source_no_pin_records_is_not_asked_about holds the plan to exit 0 and pins: [], with the path named nowhere in the plan or the report. The ESC row is POSIX-only by the file's POSIX_NAMES mark; the zero-width joiner row runs everywhere. It holds scaffold-project.py and adopt-project.py plan: a --pin-source that nothing reads (no --pin, and for the scaffold no --referent-chain link) is accepted in silence, even a path that does not exist, so --dry-run says nothing was created. and plan writes a plan, each exit 0 with no word that the flag changed nothing, where the root's own validate-pins.py notes such a value since #295 #451's answer today, silence, so a decision there changes this test on purpose.
• n2. A printable --pin-source is printed as it is. With _spelled in place of _shown in plan's pin line, every test still passed. test_a_printable_pin_source_is_printed_as_it_is holds plan's pin line, and check's write line for the plan plan wrote, to their exact text, ending (local-clone (<path>)) with no backtick.
• n3 needs a code change and is left out (below).

Evidence

Fix round 2, on f63d1ed. Each run had a gh stub first on PATH (it logs and exits 97), GH_TOKEN bogus, an empty GH_CONFIG_DIR, git-filter-repo 2.47.0 next on PATH, and the identity blanked with GIT_CONFIG_COUNT; the session gh guard came first inside each run.

• The pin set: 812 passed, 2 skipped. It covers adopt pins, adopt plan, scaffold-project.py: pin_digest_from_source catches only Refusal, so a --pin-source that does not exist, is a file, or sits under a parent this user cannot enter ends --dry-run and the real run alike in a FileNotFoundError, NotADirectoryError or PermissionError traceback (exit 1), where a directory that is not a clone is the pin-source-unreadable refusal (exit 2) with its remediation #339's file, scripts/repo_shape.py: pin_source_env_name turns every character outside [A-Z0-9_] into _, so the neutral products open-glass, open_glass and open.glass share one SHAPE_PIN_SOURCE_OPEN_GLASS, and a project that pins two of them gets a neutral-pin-source-unreadable FINDING (exit 1) for whichever one the variable does not name #275's tests, the pin and neutral-pin validators, git output decoding, adopt template values, CLI reference, scaffold pin and reuse, scaffold pin collisions, scaffold-project.py and adopt-project.py ask the project's YAML reader and validate-manifest.py about the manifest's values before anything exists, so --id null, --tracking-branch true and a blank --elected-by are refused (#258, #261) #314's two files and tests/test_agents_md_codes.py: every backticked code-shaped name in AGENTS.md must be an exact string constant in a shipped tool, so a misspelt scaffold-pin-collides, or the code renamed in scaffold-project.py while AGENTS.md keeps its old spelling, fails naming the token and the document instead of leaving an assistant to relay a code no tool prints (#348) #396's file. The skips are test_adopt_plan.py:403 (no MedxEHR clone) and test_adopt_template_values.py:223 (this host reads git config user.name from the repository, not from GIT_CONFIG_GLOBAL). That is fix round 1's 809 passed, plus the three new rows.
• Shape doctor and scaffold leg-path collisions: 369 passed, 3 skipped (the PowerShell line exists only on a Windows host).
• Mutation probes, each one line changed in a throwaway worktree, over tests/test_adopt_pins.py and tests/test_pin_source_unreadable.py less the five end-to-end adoptions:
  • the args.pin and guard dropped: 2 failed, both n1 rows;
  • plan's pin line _spelled: 1 failed, the n2 test;
  • check's write line _spelled: 2 failed, the n2 test and test_an_upper_cased_hand_edit_is_written_lower_cased;
  • plan's pin line raw: 1 failed, the no-break-space test that already guarded that hunk.

On the merged tree, 73d65c6 (the merge f9ed46f and the _read_pins commit), with the same harness:

• The pin set above, with adopt-project.py: every failure once a leg repository exists flushes stdout, then prints REFUSED <step>., what failed and one notice of what the run left, so a failed git filter-repo no longer exits 2 with an empty stderr (#171, #188, #177) #445's test_adopt_late_failure.py, test_adopt_git_reads.py and test_adopt_filter_repo_failure.py and adopt-project.py: check finds, and execute refuses before any leg exists, a source symlink with an empty target and the source's own project.yaml kept in the root, and plan no longer offers root for that file (#303, #305) #387's test_adopt_empty_symlinks.py and test_adopt_root_manifest.py: 988 passed, 2 skipped. The skips are the two above.
• Shape doctor, scaffold leg-path collisions and the adopt suites: 967 passed, 3 skipped (the PowerShell line). The adopt suites are e2e, execute refusals, verify, root shape paths (adopt-project.py: check finds, and execute refuses before any leg exists, a source symlink with an empty target and the source's own project.yaml kept in the root, and plan no longer offers root for that file (#303, #305) #387's too), leg-path collisions, clone template, ignored shape files and submodules.
• On the merge alone, f9ed46f (the same tree as before the _read_pins commit): tests/test_adopt_late_failure.py gave 3 failed, 83 passed, the three AttributeError rows above.
• render-cli-reference.py --check is ok on the merged tree. pyflakes reports the same four warnings on adopt-project.py, scaffold-project.py and scripts/shape_materialize.py as before the merge.

Fix round 1, on 421e4e5. Each run had git-filter-repo 2.47.0 on PATH and the identity blanked with GIT_CONFIG_COUNT. A gh stub that logs and exits 97 was first on PATH, with GH_TOKEN bogus and an empty GH_CONFIG_DIR, and the session gh guard came first inside each run.

• The pin set: 809 passed, 2 skipped (the same files and skips as above).
• Doctor and scaffold: 782 passed, 3 skipped (the PowerShell line exists only on a Windows host). It covers shape doctor, scaffold leg-path collisions, scaffold e2e, referent chain links, naming policy, repo hygiene and scaffold-project.py: --elected-by, --reference, --name and the elector's fallback are refused before anything exists when no file can hold them, so a byte that is not UTF-8 no longer creates repositories before a traceback (#282) #351's free-text values.
• The adopt suites: 882 passed. It covers e2e, execute refusals, verify, spec-only, leg paths, root shape paths, plan escapes, leg-path collisions, clone template and submodules.
• Before the scaffold-project.py and adopt-project.py ask the project's YAML reader and validate-manifest.py about the manifest's values before anything exists, so --id null, --tracking-branch true and a blank --elected-by are refused (#258, #261) #314 merge, on 74ce4d9's tree: the first two sets gave 577 passed, 2 skipped and 782 passed, 3 skipped. On 2bcfa69's tree (the merges alone, before the fix) they gave 542 passed, 2 skipped and 782 passed, 3 skipped. After the 45e01f4 merge, tests/test_agents_md_codes.py, repo hygiene and CLI reference: 110 passed.
• Lane 5's second review also ran 421e4e5 merged with main cb7063f and with 53bee5b: the pin set, the manifest-value set, and the doctor set with shape-doctor.py: a validator that crashed says it crashed instead of "reports a finding", and is CANNOT ANSWER when it is the standard's template, which a standard whose path holds the PYTHONPATH separator no longer runs at all; a neutral product's digest validate-pins.py skipped is a note naming the product, from a child that can no longer reach gh or a proxy; and a root whose manifest does not load and whose scripts/repo_shape.py is gone is told to restore that file before its gate (#278, #297, #298) #357's tests/test_doctor_validator_rows.py. All passed, with only the skips above.

Proof that fix round 1's tests test something:

• On 2bcfa69's tree, with this head's two test files laid over it, 31 of the new rows fail:

  • S1: 17;
  • N2 and its report spelling: 7;
  • S2: 3;
  • the pin_product_key port: 2;
  • check's S3 line: 1;
  • the not-UTF-8 adopt plan row: 1.

  The N3 rows pass there, as they must: they guard hunks this branch already had.

• Mutation probes. Each hunk was reverted alone, in a throwaway worktree, and both test files were run: 18 of 18 were caught.

  • The port: the casefold keying (2 fail); the casefold lookup alone (2).
  • S1: the path named raw (13); git's reason named raw (2); every path repr'd, printable or not (27).
  • S2: no except (3).
  • N2: no plan check (11); only adopt-project.py: a value execute writes into a file is asked whether a file can hold it, in plan, in check and in execute before any leg exists, so a byte that is not UTF-8 in --elected-by, --reference or a local --source directory no longer pushes both legs before write_lf raises (#255) #270's question asked (1); the formatting-character reason said otherwise (1); the report's pin line raw (1); check's write line raw (1).
  • S3: the line dropped (1).
  • N3: the _pin_fix name guard (1); the _read_pins path guard (1); the lower-casing (1); the digest_source check (1); the not-text check (1); the gitlink filter (1).

• The issue rows reproduced. S1, S2 and N2 were reproduced on 2bcfa69's tree and shown gone on the fix (a probe driving both tools; gh was called 0 times).

Before fix round 1. Runs were on 7a94b6b, with git-filter-repo 2.47.0 first on PATH and the repository-local user.name blanked with GIT_CONFIG_COUNT (a workstation whose standard checkout sets one fails test_the_scaffold_refuses_with_no_elector on main itself; CI sets none). 7a94b6b differs from ffd1297 in tests/test_pin_source_unreadable.py only, so the three suites that do not read that file ran on ffd1297:

• the new file: 46 passed;
• adopt pins, adopt plan, git output decoding: 172 passed, 1 skipped (the MedxEHR clone is absent);
• scaffold pin and reuse, pin collisions, e2e, referent chain links, neutral pin and pin validators, scripts/repo_shape.py: pin_source_env_name turns every character outside [A-Z0-9_] into _, so the neutral products open-glass, open_glass and open.glass share one SHAPE_PIN_SOURCE_OPEN_GLASS, and a project that pins two of them gets a neutral-pin-source-unreadable FINDING (exit 1) for whichever one the variable does not name #275's tests, naming policy, repo hygiene, CLI reference, scaffold leg-path collisions: 571 passed;
• shape doctor: 254 passed, 3 skipped (the PowerShell line exists only on a Windows host);
• the new file with repo hygiene, git output decoding and CLI reference, once more after the last edit: 176 passed.

Earlier on 5690235 and d806e8f, before the #339 commit: the adopt suites (e2e, execute refusals, verify, spec-only, leg paths, root shape paths, plan escapes, leg-path collisions, clone template) 740 passed, and tests/test_adopt_template_values.py with #273's other adopt tests 489 passed, 2 skipped. They were not re-run on 7a94b6b: the #339 diff touches pin_digest_from_source and the call in declared_pin_values, which those suites reach through test_adopt_pins.py only. Nothing was run on macOS or Windows.

Proof the new tests test something:

• On d806e8f. 38 of the 46 fail, each on the traceback and its exit 1. The 8 that pass are the unchanged behaviour: the not-a-clone refusal (4 rows) and the valid-source rows (4).
• Mutation probes. Ten hunks reverted one at a time, each failing at least one new test: the OSError catch (16 fail), the catch narrowed to OSError only (21), the missing-path clause (9), the clause narrowed to FileNotFoundError (3), the S_ISDIR judgement (3), the loop guard (4), no resolve at all (3), the old .resolve() call (4), the reason as str(exc) (12), and the file sentence as the OS's (3).
• adopt-project.py --pin <name> is accepted by plan, check and execute ("adoption verified"), but writes only the name into neutral_product_pins: and no contracts/<name>-pin.yaml, so the adopted root's own validate-pins.py (and its validate.yml) refuses with neutral-pin-missing from the first run #273's own 52 tests still fail on c7c02fa (51 fail or error; the one that passes checks the test's own table), and its 18 mutation probes were each caught.

Re-verified after the merge. An independent re-verification of f9ed46f and 73d65c6 found the code correct:

• scaffold-project.py, validate-pins.py, repo_shape.py: open-glass and open_glass share one SHAPE_PIN_SOURCE_<PRODUCT>, so --pin refuses the pair and validate-pins.py notes a declared one and reads the variable for neither (#275) #409 is carried whole. A 30,000-case fuzz of --pin lists through scaffold-project.py, validate-pins.py, repo_shape.py: open-glass and open_glass share one SHAPE_PIN_SOURCE_<PRODUCT>, so --pin refuses the pair and validate-pins.py notes a declared one and reads the variable for neither (#275) #409's final refusal and this branch's port differed in 0 cases.
• scaffold-project.py equals the tested file plus main's own changes that are not scaffold-project.py, validate-pins.py, repo_shape.py: open-glass and open_glass share one SHAPE_PIN_SOURCE_<PRODUCT>, so --pin refuses the pair and validate-pins.py notes a declared one and reads the variable for neither (#275) #409's (same patch-id).
• _commit_the_split keeps adopt-project.py: every failure once a leg repository exists flushes stdout, then prints REFUSED <step>., what failed and one notice of what the run left, so a failed git filter-repo no longer exits 2 with an empty stderr (#171, #188, #177) #445's try and adopt-project.py: execute records in project.yaml which leg the plan gave each submodule a leg keeps, and shape-doctor.py holds the submodule to that row, so one in the other leg is MISPLACED and a real adoption's placement reads ok (#189) #394's append.
• _read_pins reads a loaded plan as before.

Its findings were all in this description (the #506 bullet and three stale facts), now fixed. Runs on the head and on its merge with main 48585e6: 988 passed, 2 skipped; and 967 passed, 3 skipped.

Composition with open branches

git merge-tree --write-tree was run at 01:48Z on 2026-10-13, comparing hunks per file. Each PR head, fetched from refs/pull/<n>/head with no gh, was merged with 73d65c6 and with origin/main 9736424 alone. Two sets were asked about:

• every PR this description listed before that main does not now contain;
• every PR numbered above shape-doctor.py: a root whose index holds an unmerged path gets a merge FINDING naming the paths, with git -C <root> status as its NEXT, and the verdict INVALID (merge), exit 1, on a rung above every other but CANNOT ANSWER, so a merge git commit refuses no longer reads COMPLIANT, exit 0, once checkout --ours takes the markers out, or DRIFTED about a leg that never moved (#424) #468 whose head main does not contain: docs/release-notes/v1.0.0.md: the v1.0.0 release notes, a draft for Brett to amend before he tags, saying what 1.0 contains and promises, how to pin it by commit, what changed on the way grouped by the five tracking areas, and every known limit as the input that triggers it and what the person sees (#472) #473, update-shape.py: apply --branch compares the pin, the manifest and every pinned copy with HEAD before its first write and refuses a difference as update-branch-uncommitted, so an in-place apply left uncommitted no longer ends in a commit its own validate-pins.py refuses, in git's "nothing to commit", or in "nothing to do" with no branch made (#436) #474, templates/assembly-root/scripts/bootstrap.py: a tracking branch behind the pin is fast-forwarded to it, and a fresh clone's branch past the pin with no commit of its own is moved back to it, so bump-leg.py then make bootstrap, and git clone --recurse-submodules then make bootstrap, leave the leg on its branch AT the pin, no longer detached under not moving an existing branch (#475) #490, setup-project.py: every question - the yes, each install offer, the project name - is asked at the person's own terminal, read from the controlling terminal when stdin is the pipe the script arrived down, and a run with no terminal at all refuses naming that terminal as the way on and --yes only as the person's own answer, so the README's curl ... | bash -s -- asks in the person's terminal instead of refusing, and an assistant's shell is no longer sent to re-run with the flag its first rule forbids it (#476, #492) #491, adopt-project.py: the tracking branch defaults to the source's default branch, topics are set before the pull request, and NEXT names scripts/bootstrap.py when the shape's Makefile went aside (#479, #480, #481) #493, repo_shape.py, validate-pins.py, family.py: a refusal built without a remedy prints its REFUSED line alone, the assembly root's validate-pins.py still adds the lockstep remedy to its own, and add refuses a .gitmodules git cannot rea (#370) #494, shape-doctor.py and validate-pins.py: a gitlink that is not its pin is offered both repairs, bump-leg.py --to the gitlink's commit to keep the move and --to the pin's to undo it, so a gitlink committed by hand no longer ends at a gate t (#478) #495, shape-doctor.py: a conflicted shape pin's NEXT takes the pin alone and gives a copy conflicted beside it to a person to merge by hand, so pasting it no longer drops an edit kept with --accept-local and then says COMPLIANT (#485) #496, tests.yml: the Windows job installs git-filter-repo 2.47.0, so the 23 test files that skip without it run there and an adoption is executed on Windows for the first time, and the comments and docstrings that said that job installs none now say why it does (#471) #497, family Makefile: siblings, park and resume refuse by name when scripts/siblings.py is absent, and update-shape.py says the Makefile it copies calls it, so a holder updated without --add no longer fails on can't open file (#489) #503, adopt-project.py: check follows each symlink the plan keeps where the shape writes its files, and execute refuses one the shape cannot write through, or one it writes beneath that git checks out as a file, before any leg exists, so such a link no longer breaks the run after both legs are pushed or has the shape's files written outside the assembly (#183, #178) #504 and README.md and AGENTS.md: 28 statements the v1.0.0 accuracy pass found false are corrected to what the tools do on main (#483) #505.

Open state, read with gh by the coordinator at 02:00Z and refreshed at 02:25Z after a re-verification on main 48585e6. Every pull request named below is open. #184, #94, #96, #98, #100 and #161 are closed, and #465 landed as 48585e6. fix/adopt-plan-quote-yaml-keywords has no pull request. #506 (fix/scaffold-reuse-seeded-legs) opened after this list was made, and the re-verification reads it.

• Landed since the last draft of this list: update-shape.py read_pin refuses update-pin-row, and the pinned validate-pins.py and validate-family.py report shape-pin-row, when a shape pin's files: is not a list, so files: 5, true or 1.5 no longer ends check, apply, shape-doctor.py and the project's own validator in TypeError: ... is not iterable (#290) #343, update-shape.py: apply --add refuses a path under a file the root keeps as update-add-not-a-directory before it writes anything, and a write that fails after the copies is update-write-failed, rolled back, so neither leaves a rewritten copy and an unmoved pin behind a traceback (#285) #346, scaffold-project.py and family.py: --tracking-branch is asked of git check-ref-format --branch before anything exists, so ~, a..b, x.lock and a/ are refused under --dry-run and no longer die at the first git init -b after gh repo create has made the repositories (#283) #355, shape-doctor.py: the manifest kinds row puts back a shape or leg pin under contracts/ that does not load with the git command pin_restore picks from its own state, shows a copy the shape pin has a row for or a neutral product pin with a read-only git diff, and leaves any other file to a person whatever it is called, so its NEXT no longer tells the reader to delete the pin (#291) #358, shape_materialize.py: RULESET_HINT names the run's tracking branch where it named main, as the pull request's base and the ref the scaffold and the family holder pushed (#324) #373, adopt-project.py: _spelled writes a raw byte that is not UTF-8 as \udcNN and a character as \xNN, as the plan's own path: does, so the byte 0x85 and the character U+0085 no longer both read \x85, and 34 pairs of different names no longer read as one in a question or a finding (#329) #378, adopt-project.py: check reports the split branch an earlier run left as execute's adopt-branch-exists, and a branch in git's way of it as plan-split-branch-taken, which execute now refuses before any leg exists, so a source branch adopt no longer has both legs made before git filter-repo fails (#320) #382, adopt-project.py: check finds, and execute refuses before any leg exists, a source symlink with an empty target and the source's own project.yaml kept in the root, and plan no longer offers root for that file (#303, #305) #387, adopt-project.py: execute records in project.yaml which leg the plan gave each submodule a leg keeps, and shape-doctor.py holds the submodule to that row, so one in the other leg is MISPLACED and a real adoption's placement reads ok (#189) #394, family.py: init asks the holder's reader and validate-family.py about family.yaml before creating anything, --dry-run too, so --id null, --tracking-branch true, a blank --created-by and --created-on 20261011 are refused (#307) #397, adopt-project.py: plan --help says what --spec-path and --code-path are, the default and key each records, and the two refusals plan makes on them, so docs/cli.md no longer lists the two flags that choose where a leg is mounted as bare lines (#340) #401, shape_advisory.py and shape-doctor.py: an origin URL that is not UTF-8 names nothing, and the members row reads it as make siblings does, so a single repository is still advised, a leg clone is still sent to its root, and shape-doctor.py --root no longer ends in a UnicodeDecodeError traceback (#385) #404, scaffold-project.py, validate-pins.py, repo_shape.py: open-glass and open_glass share one SHAPE_PIN_SOURCE_<PRODUCT>, so --pin refuses the pair and validate-pins.py notes a declared one and reads the variable for neither (#275) #409, validate-pins.py (assembly-root template): a workflow file under .github/workflows/ that is not UTF-8, or that this user cannot open, is ONE workflow-unreadable refusal naming every such file, exit 2, so the project's pins gate no longer ends in a UnicodeDecodeError traceback, exit 1, with no line naming the file (#359) #419, setup.sh: --help from anywhere but a checkout is the shim's own few lines and clones nothing, and render-cli-reference.py refuses a tree that is not a checkout, so asking a download for help is no longer a clone of GitHub (#341) #452, Both roots' scripts/bootstrap.py: main escapes what stdout cannot encode and spells each value it prints, so name: "a\ud83db" or 日本 under PYTHONIOENCODING=ascii no longer ends make bootstrap in a traceback (#391) #456, README.md, docs/handbook.html and the comments in bump-leg.py and update-shape.py say when a project's own gate reaches a network: validate-pins.py asks gh api for a neutral product's pin with the operator's gh credentials, and make bootstrap, bump-leg.py and update-shape.py apply run it in the operator's environment, so none of them says any more that a project runs its own gate offline or that apply is otherwise offline (#411) #465, family.py: bump refuses a --to that names an annotated tag, a tree or a blob as member-to-not-a-commit before the checkout, naming the commit a tag names, and its dry run refuses alike, so a release tag's own id no longer exits 0 with a commit pinning the tag over a gitlink at its commit, which the holder's validate-family.py refused as member-gitlink-mismatch (#405) #466 and bump-leg.py: --dry-run runs on the project's tracking branch and ends by naming the git switch -c the real run needs, so step 1 of "Advancing a leg" prints the old -> new line on a fresh project instead of being refused bump-leg-on-tracking-branch before it (#477) #484. adopt-project.py: execute records in project.yaml which leg the plan gave each submodule a leg keeps, and shape-doctor.py holds the submodule to that row, so one in the other leg is MISPLACED and a real adoption's placement reads ok (#189) #394's _commit_the_split conflict and adopt-project.py: plan --help says what --spec-path and --code-path are, the default and key each records, and the two refusals plan makes on them, so docs/cli.md no longer lists the two flags that choose where a leg is mounted as bare lines (#340) #401's docs/cli.md conflict are both resolved in f9ed46f, above.
• Clean, 20: scaffold-project.py: a leg path the project's own YAML reader would read back as another type (null, ~, true, False, 2026, 1.5) is refused before anything is created, under --dry-run alike, through the one definition adopt-project.py asks, so --spec-path 2026 no longer creates three repositories whose first bootstrap fails manifest-leg-path, and adopt-project.py execute no longer says adoption verified before that bootstrap fails (#225) #266, update-shape.py: a pinned copy, contracts/shape-pin.yaml or the manifest kept as a symlink, or under one, is refused as update-rewrite-symlink before anything is written, and check calls such a copy copy-is-link, so apply no longer writes the standard's bytes at the link's end and reports a commit that does not hold them (#286) #347, adopt-project.py: check finds, and execute refuses before any leg exists, a plan follow_ups: that is not a list of text and an elected_on: that election_date does not read, with or without a reference:, so follow_ups: 5 is no longer a traceback and elected_on: someday is no longer refused under a flag neither command takes (#293, #294) #356, update-shape.py: every NEXT line a run prints quotes its root, upstream, --accept-local paths, branch and lane trailer with shlex.quote, so check's apply, apply --branch's git -C <root> push && gh pr create and apply's own git -C <root> checkout -b && git -C <root> commit paste whole from a root under my projects/, it's here/ or $HOME/ (#325) #374, update-shape.py, bump-leg.py and family.py: --trailer carries a non-ASCII value into the commit as typed under any locale and on a git without commit --trailer, and refuses one whose bytes are not UTF-8 by name before anything is staged, so Co-Authored-By: José under LC_ALL=C PYTHONUTF8=0 is no longer refused as "not a trailer" and a direct caller's is no longer committed as Jos?? (#322) #376, adopt-project.py: check and execute spell a plan's hand-edited question: in plan-unresolved, its source: commit: in plan-stale and a submodule name in missing value for '<key>' with _spelled, so a line feed in any of them no longer forges a FINDING line and an ESC no longer reaches the terminal (#328) #384, templates: project.yaml, the leg pins and family.yaml quote their text placeholders, so --id 007, --tracking-branch 2026, --spec-path true or --org null read back as typed, and family.py add quotes a member id alike (#259) #395, validate-repository-naming.py, repo_shape.py: a --link-source value is PRODUCT=PATH only when its key names a chain link, and a link source that cannot be entered is a WARNING with the system's reason, not a traceback (#338) #453, setup-project.py: the root clone of --local-remote-dir is --no-local and its two leg clones are rewritten to file://, and the two session fixtures that clone a scaffold do the same, so a maintenance run packing the just-pushed objects mid-walk no longer dies failed to copy file to ... No such file or directory (#440) #467, shape-doctor.py: a root whose index holds an unmerged path gets a merge FINDING naming the paths, with git -C <root> status as its NEXT, and the verdict INVALID (merge), exit 1, on a rung above every other but CANNOT ANSWER, so a merge git commit refuses no longer reads COMPLIANT, exit 0, once checkout --ours takes the markers out, or DRIFTED about a leg that never moved (#424) #468, docs/release-notes/v1.0.0.md: the v1.0.0 release notes, a draft for Brett to amend before he tags, saying what 1.0 contains and promises, how to pin it by commit, what changed on the way grouped by the five tracking areas, and every known limit as the input that triggers it and what the person sees (#472) #473, update-shape.py: apply --branch compares the pin, the manifest and every pinned copy with HEAD before its first write and refuses a difference as update-branch-uncommitted, so an in-place apply left uncommitted no longer ends in a commit its own validate-pins.py refuses, in git's "nothing to commit", or in "nothing to do" with no branch made (#436) #474, templates/assembly-root/scripts/bootstrap.py: a tracking branch behind the pin is fast-forwarded to it, and a fresh clone's branch past the pin with no commit of its own is moved back to it, so bump-leg.py then make bootstrap, and git clone --recurse-submodules then make bootstrap, leave the leg on its branch AT the pin, no longer detached under not moving an existing branch (#475) #490, setup-project.py: every question - the yes, each install offer, the project name - is asked at the person's own terminal, read from the controlling terminal when stdin is the pipe the script arrived down, and a run with no terminal at all refuses naming that terminal as the way on and --yes only as the person's own answer, so the README's curl ... | bash -s -- asks in the person's terminal instead of refusing, and an assistant's shell is no longer sent to re-run with the flag its first rule forbids it (#476, #492) #491, adopt-project.py: the tracking branch defaults to the source's default branch, topics are set before the pull request, and NEXT names scripts/bootstrap.py when the shape's Makefile went aside (#479, #480, #481) #493, repo_shape.py, validate-pins.py, family.py: a refusal built without a remedy prints its REFUSED line alone, the assembly root's validate-pins.py still adds the lockstep remedy to its own, and add refuses a .gitmodules git cannot rea (#370) #494, shape-doctor.py and validate-pins.py: a gitlink that is not its pin is offered both repairs, bump-leg.py --to the gitlink's commit to keep the move and --to the pin's to undo it, so a gitlink committed by hand no longer ends at a gate t (#478) #495, tests.yml: the Windows job installs git-filter-repo 2.47.0, so the 23 test files that skip without it run there and an adoption is executed on Windows for the first time, and the comments and docstrings that said that job installs none now say why it does (#471) #497, family Makefile: siblings, park and resume refuse by name when scripts/siblings.py is absent, and update-shape.py says the Makefile it copies calls it, so a holder updated without --add no longer fails on can't open file (#489) #503 and README.md and AGENTS.md: 28 statements the v1.0.0 accuracy pass found false are corrected to what the tools do on main (#483) #505. validate-repository-naming.py, repo_shape.py: a --link-source value is PRODUCT=PATH only when its key names a chain link, and a link source that cannot be entered is a WARNING with the system's reason, not a traceback (#338) #453, shape-doctor.py: a root whose index holds an unmerged path gets a merge FINDING naming the paths, with git -C <root> status as its NEXT, and the verdict INVALID (merge), exit 1, on a rung above every other but CANNOT ANSWER, so a merge git commit refuses no longer reads COMPLIANT, exit 0, once checkout --ours takes the markers out, or DRIFTED about a leg that never moved (#424) #468 and setup-project.py: every question - the yes, each install offer, the project name - is asked at the person's own terminal, read from the controlling terminal when stdin is the pipe the script arrived down, and a run with no terminal at all refuses naming that terminal as the way on and --yes only as the person's own answer, so the README's curl ... | bash -s -- asks in the person's terminal instead of refusing, and an assistant's shell is no longer sent to re-run with the flag its first rule forbids it (#476, #492) #491 were updated onto main since the first read and now merge clean. family.py: init refuses to land in the standard's checkout and names a runnable scripts/family.py, printed commands quote paths, and add, bump and remove refuse the tracking branch and print their branch's push (#488, #486, #487) #507 (lane 5's family.py and siblings.py print commands with unquoted paths, so under a folder with a space the member-git-dir-cached remedy's rm -rf would delete the wrong directory, and add's push line fails #486-family.py init: AGENTS.md's own command lands the holder inside the openRepoShape checkout, and init's NEXT prints python3 family.py add, which cannot run #488) shares only the generated docs/cli.md with this branch and merges clean with it.
• Conflicting with main alone, and this branch adds no hunk:
  • shape-doctor.py: a NEXT is only the command, and the sentence that ended twenty-five of them after # is the row's why, on a WHY line of its own and "why" in --json, so a NEXT pasted into an interactive zsh -- which reads that # as a word -- no longer hands the comment to the command as arguments, runs what follows its ;, or runs the make bootstrap in its backticks, and the template validator's line is env PYTHONPATH=... python3 ... (#277) #402: shape-doctor.py 5;
  • shape-doctor.py: a conflicted shape pin's NEXT takes the pin alone and gives a copy conflicted beside it to a person to merge by hand, so pasting it no longer drops an edit kept with --accept-local and then says COMPLIANT (#485) #496: shape-doctor.py 10 and tests/test_shape_doctor.py 1.

Conflicts this branch adds:

• adopt-project.py: check names, and execute refuses before the work directory is made, a plan whose source: or legs: is not a mapping or whose allow_empty_legs: or paths: is not a list of what plan writes, and asks the same first of a pins: that is not a list, so a number or a boolean in any of the four no longer ends both in a traceback and allow_empty_legs: code is no longer read as four legs (#386) #435 (3efcc7a, lane 2's fix/adopt-plan-field-types, for adopt-project.py: Plan.__init__, allowed_empty_legs, names and open_source iterate or call .get on a hand-edited plan's pins:, allow_empty_legs:, paths:, legs: and source: without asking their type, so a scalar ends check and execute in a TypeError or AttributeError traceback, exit 1, and pins: openGlass passes check, adopts, and writes eight one-letter neutral-product pins that the project's own validate-pins.py refuses #386).
  • It adds 2 hunks in adopt-project.py: 5 here, against 3 with main alone. They are render_plan's pins: line and Plan.pins.
  • Keep this branch's _pin_lines and _pin_products. The rest is under "Where the meaning meets".
• adopt-project.py: check follows each symlink the plan keeps where the shape writes its files, and execute refuses one the shape cannot write through, or one it writes beneath that git checks out as a file, before any leg exists, so such a link no longer breaks the run after both legs are pushed or has the shape's files written outside the assembly (#183, #178) #504 (37ef29a, fix/adopt-root-kept-symlinks).
  • It adds 1 hunk in adopt-project.py: 2 here, against 1 with main alone. It is the materializer call in _commit_the_split.
  • Keep both arguments and both comments: append=append, neutral_pins=_recorded_pins(plan), spell=_spelled.
• scaffold-project.py and family.py init: --reuse-empty-repo reuses a leg that is empty or whose one commit is the scaffold's own seed, and the ruleset hint offers that re-run, by an operator holding the bypass right, as its one exit, so a project a ruleset refused part-way is finished by one re-run, not refused scaffold-remote-exists for its own legs or sent to a pull request with no base (#462) #506 (119d8c4, fix/scaffold-reuse-seeded-legs).
  • It adds 1 hunk in scaffold-project.py. With main alone, scaffold-project.py and family.py init: --reuse-empty-repo reuses a leg that is empty or whose one commit is the scaffold's own seed, and the ruleset hint offers that re-run, by an operator holding the bypass right, as its one exit, so a project a ruleset refused part-way is finished by one re-run, not refused scaffold-remote-exists for its own legs or sent to a pull request with no base (#462) #506 conflicts only in docs/handbook.html.
  • scaffold-project.py and family.py init: --reuse-empty-repo reuses a leg that is empty or whose one commit is the scaffold's own seed, and the ruleset hint offers that re-run, by an operator holding the bypass right, as its one exit, so a project a ruleset refused part-way is finished by one re-run, not refused scaffold-remote-exists for its own legs or sent to a pull request with no base (#462) #506 inserts LEG_TEMPLATES right after declared_pin_products, which this branch moved out, and rewrites _reusable_remotes further down. Keeping both sides breaks the file with an unterminated string literal.
  • Keep only scaffold-project.py and family.py init: --reuse-empty-repo reuses a leg that is empty or whose one commit is the scaffold's own seed, and the ruleset hint offers that re-run, by an operator holding the bypass right, as its one exit, so a project a ruleset refused part-way is finished by one re-run, not refused scaffold-remote-exists for its own legs or sent to a pull request with no base (#462) #506's LEG_TEMPLATES block. Drop scaffold-project.py and family.py init: --reuse-empty-repo reuses a leg that is empty or whose one commit is the scaffold's own seed, and the ruleset hint offers that re-run, by an operator holding the bypass right, as its one exit, so a project a ruleset refused part-way is finished by one re-run, not refused scaffold-remote-exists for its own legs or sent to a pull request with no base (#462) #506's declared_pin_values/declared_pin_products, which moved here, and this branch's three-line _reusable_remotes opener, which scaffold-project.py and family.py init: --reuse-empty-repo reuses a leg that is empty or whose one commit is the scaffold's own seed, and the ruleset hint offers that re-run, by an operator holding the bypass right, as its one exit, so a project a ruleset refused part-way is finished by one re-run, not refused scaffold-remote-exists for its own legs or sent to a pull request with no base (#462) #506 rewrites below. Resolved that way, pyflakes is clean and scaffold-project.py and family.py init: --reuse-empty-repo reuses a leg that is empty or whose one commit is the scaffold's own seed, and the ruleset hint offers that re-run, by an operator holding the bypass right, as its one exit, so a project a ruleset refused part-way is finished by one re-run, not refused scaffold-remote-exists for its own legs or sent to a pull request with no base (#462) #506's scaffold tests pass (88).
• fix/adopt-plan-quote-yaml-keywords (ed9968f; a branch with no pull request).
  • It adds 2 hunks in adopt-project.py: 3 here, against 1 with main alone.
  • One is render_plan's pins: line. Keep _pin_lines, which already sends product, repository and digest_source through y.
  • The other is _refuse_unholdable_values' signature. Keep pins: dict, with that branch's _validator_judged and _named_as_read above it.
• fix/adopt-late-failure-notice is no longer on origin. adopt-project.py: every failure once a leg repository exists flushes stdout, then prints REFUSED <step>., what failed and one notice of what the run left, so a failed git filter-repo no longer exits 2 with an empty stderr (#171, #188, #177) #445, the late-failure notice, is on main and merged here.

Where the meaning meets:

• adopt-project.py: check names, and execute refuses before the work directory is made, a plan whose source: or legs: is not a mapping or whose allow_empty_legs: or paths: is not a list of what plan writes, and asks the same first of a pins: that is not a list, so a number or a boolean in any of the four no longer ends both in a traceback and allow_empty_legs: code is no longer read as four legs (#386) #435 and adopt-project.py: Plan.__init__, allowed_empty_legs, names and open_source iterate or call .get on a hand-edited plan's pins:, allow_empty_legs:, paths:, legs: and source: without asking their type, so a scalar ends check and execute in a TypeError or AttributeError traceback, exit 1, and pins: openGlass passes check, adopts, and writes eight one-letter neutral-product pins that the project's own validate-pins.py refuses #386. The coordinator has said this on adopt-project.py: check names, and execute refuses before the work directory is made, a plan whose source: or legs: is not a mapping or whose allow_empty_legs: or paths: is not a list of what plan writes, and asks the same first of a pins: that is not a list, so a number or a boolean in any of the four no longer ends both in a traceback and allow_empty_legs: code is no longer read as four legs (#386) #435: adopt-project.py: check names, and execute refuses before the work directory is made, a plan whose source: or legs: is not a mapping or whose allow_empty_legs: or paths: is not a list of what plan writes, and asks the same first of a pins: that is not a list, so a number or a boolean in any of the four no longer ends both in a traceback and allow_empty_legs: code is no longer read as four legs (#386) #435 (comment)
  • adopt-project.py: check names, and execute refuses before the work directory is made, a plan whose source: or legs: is not a mapping or whose allow_empty_legs: or paths: is not a list of what plan writes, and asks the same first of a pins: that is not a list, so a number or a boolean in any of the four no longer ends both in a traceback and allow_empty_legs: code is no longer read as four legs (#386) #435's _plan_key_findings (plan-bad-pins) keeps only text items in pins:, and its PINS_REMEDIATION tells a person to write pins: [openGlass].
  • This branch writes each pin as a mapping, and it makes a name alone plan-pin-unrecorded.
  • Read from adopt-project.py: check names, and execute refuses before the work directory is made, a plan whose source: or legs: is not a mapping or whose allow_empty_legs: or paths: is not a list of what plan writes, and asks the same first of a pins: that is not a list, so a number or a boolean in any of the four no longer ends both in a traceback and allow_empty_legs: code is no longer read as four legs (#386) #435's code, not run: on a tree with both, the plan plan --pin writes is plan-bad-pins in check.
  • Whichever lands second reconciles them, with three changes:
    • _plan_key_findings takes this branch's mappings, or leaves pins: items to _read_pins;
    • a pins: that is not a list gives one finding, not both plan-bad-pins and plan-pin-malformed;
    • PINS_REMEDIATION says the mapping plan writes.
  • Until that is done, tests/test_adopt_pins.py::test_a_plan_with_a_whole_pin_checks_ok fails.
• scaffold-project.py and adopt-project.py ask the project's YAML reader and validate-manifest.py about the manifest's values before anything exists, so --id null, --tracking-branch true and a blank --elected-by are refused (#258, #261) #314. It landed, and it is merged here (above).
• fix/adopt-plan-quote-yaml-keywords. Its pin tests are written against the name-only --pin. They need the name@commit form, and their expected pins: [...] line becomes _pin_lines's mapping.

Left out

• Two unwritable values are refused in two runs (lane 5's second review, n3). plan --elected-by 'A<LF>B' --pin openGlass@<sha> --pin-source <a path holding an ESC> refuses the elector alone, exit 2. Re-run with the elector retyped, it refuses the source; adopt-project.py: a value execute writes into a file is asked whether a file can hold it, in plan, in check and in execute before any leg exists, so a byte that is not UTF-8 in --elected-by, --reference or a local --source directory no longer pushes both legs before write_lf raises (#255) #270's refusal names every unwritable value at once. Reproduced on 421e4e5, with gh called 0 times. One refusal would need a code change, not made here:

  • _refuse_an_unrecordable_pin_source would split into a function that returns the sentence;
  • _checked_plan_inputs would ask it before adopt-project.py: a value execute writes into a file is asked whether a file can hold it, in plan, in check and in execute before any leg exists, so a byte that is not UTF-8 in --elected-by, --reference or a local --source directory no longer pushes both legs before write_lf raises (#255) #270's unwritable_values raise, and raise one adopt-unwritable-value that names both, with both remediations;
  • a test would add the two-value row.

  N2's question is one_printable_line, not unwritable_reason, so it cannot simply join adopt-project.py: a value execute writes into a file is asked whether a file can hold it, in plan, in check and in execute before any leg exists, so a byte that is not UTF-8 in --elected-by, --reference or a local --source directory no longer pushes both legs before write_lf raises (#255) #270's list.

• Docs. The README, AGENTS.md and docs/handbook.html are unchanged, because none of them calls adopt's --pin a name. A sentence saying adopt now takes the scaffold's --pin is a follow-up. It costs an AGENTS.md line-cap raise, and a README edit forces the handbook's README blob to change.

• A product spelled null, true or false. The scaffold already accepts --pin null@<sha>: it exits 0 and builds a root whose validate-pins.py exits 1 neutral-pin-entry-malformed. Adopt's plan writes product: null through y, and check then finds plan-pin-malformed and refuses it before any leg exists. The one fix for both tools is in parse_pin, and it would change the scaffold's behaviour.

• Wording shared with the scaffold. digest_source is written bare into the pin file, so a --pin-source path holding # is cut short there. templates/assembly-root/contracts/neutral-product-pin.yaml and validate-pins.py's neutral-pin-missing remediation name only the scaffold as the writer. Two comments in scripts/repo_shape.py still name the scaffold's pin_digest_from_gh, in a digest-pinned shipped copy.

• Filed as follow-ups:

  • adopt-project.py check and execute write a neutral pin's commit: and tree_sha256: exactly as the adoption plan records them and read neither again, so a hand edit that makes the two disagree is plan ok and adoption verified, and the adopted root's own validate-pins.py then exits 1 with neutral-pin-digest-mismatch on its first run #449: S3, a hand-edited commit: or tree_sha256: that disagrees, with options (a) and (b);
  • scaffold-project.py --pin-source <path>: the path is written as it stands into the new root's contracts/<product>-pin.yaml (digest_source: local-clone (<path>), a bare placeholder) and is asked nothing first, so a clone at a path holding a line break scaffolds, exit 0, a pin file with a line of the path's choosing, and one at a path that is not UTF-8 creates all three repositories and then dies in write_lf with a UnicodeEncodeError traceback, exit 1 #450: the scaffold half of N2, a --pin-source path no file can hold;
  • scaffold-project.py and adopt-project.py plan: a --pin-source that nothing reads (no --pin, and for the scaffold no --referent-chain link) is accepted in silence, even a path that does not exist, so --dry-run says nothing was created. and plan writes a plan, each exit 0 with no word that the flag changed nothing, where the root's own validate-pins.py notes such a value since #295 #451: scaffold-project.py: pin_digest_from_source catches only Refusal, so a --pin-source that does not exist, is a file, or sits under a parent this user cannot enter ends --dry-run and the real run alike in a FileNotFoundError, NotADirectoryError or PermissionError traceback (exit 1), where a directory that is not a clone is the pin-source-unreadable refusal (exit 2) with its remediation #339's third decision (N5), a --pin-source that nothing reads.

• validate-pins.py prints a --pin-source path raw in neutral-pin-source-unreadable, the twin of S1. It is a shipped template that scaffold-project.py, validate-pins.py, repo_shape.py: open-glass and open_glass share one SHAPE_PIN_SOURCE_<PRODUCT>, so --pin refuses the pair and validate-pins.py notes a declared one and reads the variable for neither (#275) #409 and other open PRs edit, so it is left for its own change. No issue is filed for it yet.

• Windows and macOS were not run. Two assertions that depend on what Windows answers for a path (a name past the filesystem's limit, a path beneath a file) check only the refusal and its remediation there. Fix round 1's rows that need a control character or a byte that is not UTF-8 in a path, or a symlink to git, are skipped on Windows by a mark, and so is fix round 2's ESC row. The rows for a no-break space and a zero-width joiner run everywhere, and so does the in-process gh-not-found test.

Closes #273
Closes #339

🤖 Generated with Claude Code

[brettheap]

(lane openRepoShape-5, 2026-10-13T02:23Z) @codex review

[sourcery-ai]

Sorry @brettheap, your pull request is larger than the review limit of 150,000 diff characters

[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.

[sonarqubecloud]

Quality Gate passed

Issues
4 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
1.1% Duplication on New Code

See analysis details on SonarQube Cloud