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) by brettheap · Pull Request #507 · opensoft/openRepoShape

brettheap · 2026-10-13T02:12:21Z

Lane: openreposhape-5 (openRepoShape-5)
Claim: #488 (comment)
Claim: #486 (comment)
Claim: #487 (comment)

Three defects from lane 3's v1.0.0 acceptance pass of AGENTS.md's "Creating a family, and adding a member", one commit each, in this order, then one review commit for #486 and one for #487. All three change scripts/family.py and add's NEXT line, so they are one pull request.

#488: `init` run as AGENTS.md spells it

What was wrong.

AGENTS.md spelled the command python3 scripts/family.py init --org <org> --family <Name>, a path that runs from the standard's root. --into defaults to where the person stands.
So the command, followed exactly, printed landing <standard>/Orbit/Orbit with no word, and make siblings would then clone every member into the standard's checkout too.
init's NEXT STEPS printed python3 family.py add …, built from Path(__file__).name. From the root that fails can't open file, exit 2.

What changed (commit 1).

With neither --into nor --work-dir, init refuses a landing inside a checkout of openRepoShape: family-landing-in-standard. A checkout is a directory holding scripts/family.py beside templates/family-root/, found in the landing's ancestry, so another clone or an install counts too.
- The refusal comes before anything is created, under --dry-run alike.
- The remedy names --into .. from the root. From deeper inside the checkout it names the relative path that reaches the checkout's parent.
- An explicit --into or --work-dir is not second-guessed. family-holder-already-here is still asked first.
NEXT STEPS, and the family-holder-already-here remedy, name this file relative to the directory init ran in. From the root that is scripts/family.py, as setup-project.py, validate-family.py, AGENTS.md and README spell it. It is absolute where no relative path exists.
AGENTS.md's init command passes --into .., as README's already does, and step 1 says why. The edit is line-neutral: step 1 is one line shorter.
init --into --help says it too, and docs/cli.md is regenerated.

How tested. tests/test_family_init_landing.py, 9 tests:

the old command from the root is refused, as a dry run, so nothing can land in the checkout;
a real run inside a fake checkout creates nothing;
the remedy from a subdirectory names the right parent;
an explicit --into . or --work-dir . passes;
outside a checkout the default is unchanged;
AGENTS.md's line, as written, lands beside the checkout;
the printed NEXT runs, both from the root and from elsewhere.

On origin/main code 6 of them fail. Removing the refusal turns 3 red, and putting Path(__file__).name back turns 2 red.

#486 (P1): unquoted paths in printed commands

What was wrong. family.py and the holder's siblings.py printed every path in their pasteable commands bare. Under a holder at …/my work/Sonata/Sonata:

the member-git-dir-cached remedy rm -rf <store> split into rm -rf …/my, an absolute directory that is NOT the store, and a relative work/…;
init's NEXT STEPS and add's NEXT split --family-root and git -C (fatal: cannot change to '…/my', exit 128);
the mv lines for a misnamed family folder pasted as four arguments.

What changed (commit 2, and the review commit after #487's).

scripts/repo_shape.py gains shell_quoted(value, platform=None) and shell_line(words, platform=None), in a new section at its end, the library family.py already imports.
- It is the doctor's quote_arg rule (shape-doctor.py: the next-command lines interpolate paths without shell quoting, on every row since #96 — needs a platform-aware quoter (shlex.quote is POSIX-only; the file runs on Windows by contract) #101/shape-doctor.py: one platform-aware quoter, on every next command, so a root or a name with a space in it is a line that runs (#101) #102): the same two alphabets, and the same two escapes, sh's '\'' and PowerShell's doubled apostrophe. The dialect comes from os.name or a platform argument. An ordinary word is left bare.
- It does not flatten to ASCII, as the doctor's report does by contract. A command that deletes or moves a directory has to name that directory. So PowerShell's typographic single quotes are doubled too.
- A word that begins with = is quoted, in both dialects. zsh, macOS's login shell, expands a bare =word to a command's path (=ls reaches the command as /bin/ls). This is the one place it differs from the doctor's rule on ASCII.
family.py:
- init's NEXT STEPS print the add on ONE line. It used to paste only into a POSIX shell, because of its \ continuation. cd <holder> and make siblings are two lines, with no &&, which Windows PowerShell 5.1 rejects between two statements.
- Those lines and the family-holder-already-here remedy quote every path.
- add's NEXT quotes git -C <holder>, and member-path-taken quotes each spelling it names.
- member-git-dir-cached, and remove's note about the same store, print the directory alone on its own line. Then comes rm -rf with its one argument quoted for the POSIX shell rm -rf belongs to, and the sentence names that shell: Git Bash on Windows. PowerShell refuses -rf and deletes nothing.
siblings.py: the parent-folder warning's mv and mkdir -p lines are quoted for a POSIX shell with the standard library's shlex.join, and the warning says which shell. It does NOT import the new quoter: a holder that kept its own repo_shape.py through update-shape.py apply --accept-local takes the new siblings.py without it, and an import of a name its copy lacks stopped make siblings, park and resume with an ImportError that check and the validator never reported.
setup-project.py's family hand-over quotes the holder in its add line (and names the branch first, see family.py add, bump and remove commit straight onto the holder's tracking branch, and add's NEXT pushes a <branch> that does not exist, though AGENTS.md says to land each as a pull request #487). It runs before any checkout of the standard exists, so it carries its own copy of the rule, and a test holds that copy to shell_quoted.

How tested. tests/test_family_printed_quoting.py, 69 tests:

The quoter round-trips through shlex.split, and through a PowerShell reader, for a space and an apostrophe, é and a typographic apostrophe, shell syntax, the empty string, and every printable ASCII character alone and before, inside and after a word.
The host's own sh, bash and zsh hand each quoted word back byte for byte through printf, a leading = among them (skipped where a shell is absent, and on Windows).
It agrees with the doctor's quote_arg on every one of those ASCII values but a leading =, and its two alphabets are the doctor's two patterns.
Under a holder in my work and in Dana's work, each of these splits into the argv it means: init's NEXT (with cd and make siblings on their own lines), add's NEXT, the cached-store remedy and note, the mv lines, and setup-project's switch and add.
- The rm -rf, run as split, deletes the store, and the decoy <tmp>/my survives.
- The mv lines, run as split, move the holder.
The holder's own siblings.py runs --help, the misnamed-folder warning and --make park beside a repo_shape.py that lacks every name this change added.
Three existing tests' expected lines follow the new wording.

Mutations, each turning tests red:

a bare quoter: 35 red;
bare mv lines in siblings.py: 3 red;
a bare rm -rf, a bare add NEXT, a bare init add (round 1, on the 85-test file): 2 red each;
siblings.py importing shell_line again: 1 red (the older-repo_shape.py test);
% dropped from the POSIX alphabet: 2 red (the every-ASCII agreement and the alphabet test). The round-1 sample test passed it, 36 of 36;
a leading = left bare: 10 red, among them the real-zsh test;
cd … && make siblings back on one line: 2 red;
setup-project's holder unquoted: 2 red.

#487: `add`, `bump` and `remove` committed onto the tracking branch

What was wrong.

AGENTS.md says each act's ONE commit lands as a pull request, and no step made the branch that pull request needs.
After init the holder stands on main, and all three acts committed straight onto it.
add printed NEXT git -C <holder> push -u origin <branch> && open a pull request. No branch is called <branch>, so the push failed: src refspec … does not match any.
bump and remove printed no NEXT at all.
bump-leg.py refuses exactly this for a leg (bump-leg-on-tracking-branch).

What changed (commit 3, and the review commit after it).

The real run of each act refuses the holder's tracking branch, the one family.yaml declares (family-on-tracking-branch), and a HEAD on no branch (family-holder-detached, which is what bump-leg.py's bump-leg-root-detached refuses too).
- The check comes after the refusals about the arguments and the holder, and before the member is read, fetched or cloned, and before anything is written.
- The remedy is a quoted git -C <holder> switch -c <branch>. The branch is family/add-<project>, family/bump-<id>-<sha12> or family/remove-<id>, and a name that is not a plain branch word becomes member.
--dry-run runs on any branch. On a work branch it prints where the commit would land. On the tracking branch it prints that the real run refuses there, with the refusal's code, and the switch command on a line of its own. The module's EXIT CODES paragraph names this as the one refusal a dry run does not make.
Each act that commits ends with ONE pasteable line: NEXT git -C <holder> push -u origin <the branch it committed on>, quoted, then then open a pull request against <tracking>; never push to it directly. bump and remove gain that NEXT.
init's NEXT STEPS open with the switch before the add.
add, bump and remove --help say the branch rule, and that each ends by PRINTING the push; docs/cli.md is regenerated.
AGENTS.md's family block gains the switch step before the add, and step 3 says the tracking branch is refused, as family-on-tracking-branch, and that the branch is pushed as its NEXT line says. README's InkRouter block gains the same step, and its paragraph says it. Both edits are line-neutral: AGENTS.md tightens steps 2 and 5, and README tightens the make bootstrap paragraph. docs/handbook.html mirrors the block and the sentence, and its footer names family.py add, bump and remove commit straight onto the holder's tracking branch, and add's NEXT pushes a <branch> that does not exist, though AGENTS.md says to land each as a pull request #487 and the new README blob.
The holder's own docs, templates/family-root/AGENTS-shape.md and templates/family-root/README.md, open their add/bump/remove block with the switch and say the act refuses the tracking branch. setup-project.py's family hand-over prints the switch before its add.
Test fixtures that committed on main now commit on a branch:
- tests/test_family.py's module fixture grows the family on family/members and pushes that branch to the remote's main, as the merged pull request would leave it;
- test_shape_doctor.py's holder fixture and test_family_add_excludes.py's empty_holder switch to a branch;
- test_family_add_refusals.py changes in four places: the NEXT expectation, unborn_holder, the empty-family test, and the corrupt-HEAD test. In that last test, the tag state's branch check is answered in-process, because the test is about the rollback's reading of HEAD.

How tested. tests/test_family_tracking_branch.py, 17 tests:

For each act, on main: refused, with the holder byte for byte as it was, and for add nothing cloned. Then the printed switch, run as split, makes the branch; the act goes through on it; and its printed NEXT, run as split, pushes the branch, which the remote then holds at the act's commit.
A detached HEAD is refused.
Dry runs on main and on a branch say what they should.
A family made with --tracking-branch trunk refuses add on trunk; on a branch named main the dry run says the commit lands there for a pull request against trunk, the real run commits, and its NEXT pushes main.
The suggested names pass git check-ref-format --branch.
init's NEXT STEPS open with the switch.
AGENTS.md, README.md and the holder's two docs show the switch in the same block as, and before, the first add.

Mutations, each turning tests red: the branch check letting main through, 4 red; the NEXT line naming <branch> again, 3 red; init's NEXT STEPS without the switch, 1 red; the tracking branch hard-coded to "main", 1 red (the trunk test; every family test passed it before); the holder docs without the switch, 2 red; setup-project without the switch, 2 red.

Review

An independent review at 10c93de gave CHANGES NEEDED (0 blockers, 1 should-fix, 6 nits). The should-fix was a holder that kept an older scripts/repo_shape.py through apply --accept-local: its new siblings.py could not import the shared quoter, so make siblings, park and resume died. The round at bb11b63 fixes it and all six nits, as described above. Re-verified at bb11b63: APPROVE WITH NITS (0 blockers, 0 should-fixes, 3 nits), with SonarCloud's quality gate OK and 0.0% new duplication. The nits were the holder README's pointer to the push (now "as its NEXT line says"), two Sonar smells (S1192: refs/heads/ is now HEADS_PREFIX; S3415: the two expected-first assertions now put the actual value first, as the file's other 32 do), and this description's list of other pull requests. All three are fixed at 3451a56: commit 11ae0a8, then a clean merge of main 994be39. The family set gave 566 passed, 8 skipped there. GitHub's update-branch then merged main cac6bb2 as 8e1471c, and main aa4e1f5 (#508, after #490, #474 and #468) was merged as 708f3bb. There only the docs/handbook.html footer conflicted: it takes main's clauses, #468's (#424) included, with the README blob recomputed, and docs/cli.md auto-merged and passes --check. Main 47b1e06 (#505 and #395, after #376, #374, #384, #495, #493 and #491) was then merged as fcbc7a2, again with only the footer in conflict: main's clauses stay in main's order, this branch's (#487) moves to the end, after (#483), and the README blob is recomputed.

Results

Every run used /usr/bin/python3 -m pytest -q -p no:cacheprovider, with a stub gh first on PATH, a bogus GH_TOKEN, an empty GH_CONFIG_DIR and git's identity blanked. Run on Linux. At e42ef74 (main d41cc29, #402, merged in by GitHub's update-branch), on its tree 655c927b: the first set listed below for fcbc7a2, plus every tests/test_update_shape*.py, gave 1242 passed, 22 skipped; the second set, plus tests/test_leg_path_yaml_scalars.py, tests/test_ruleset_hint_tracking_branch.py, tests/test_scaffold_reuse_seeded_legs.py, tests/test_scaffold_pin_and_reuse.py and tests/test_doctor_validator_rows.py, gave 1260 passed, 12 skipped. The skips are the same as at 5a2776d, below.

At 654df49 (main 8cd7dbe merged in, with #506 and #347): the first set listed below for fcbc7a2, plus every tests/test_update_shape*.py, gave 1242 passed, 22 skipped; the second set, plus tests/test_leg_path_yaml_scalars.py, tests/test_ruleset_hint_tracking_branch.py, tests/test_scaffold_reuse_seeded_legs.py and tests/test_scaffold_pin_and_reuse.py, gave 1231 passed, 12 skipped. The skips are the same as at 5a2776d, below.

At 5a2776d (main f391e58 merged in, with #266, #509, #496 and #435): the first set listed below for fcbc7a2, plus every tests/test_update_shape*.py, gave 1213 passed, 22 skipped (the template-quoting skips below, and three NTFS-junction cases, Windows only); the second set, plus tests/test_leg_path_yaml_scalars.py, gave 1171 passed, 12 skipped (the four Windows-only skips below, and eight in that file, main's new one, whose cases the quoted templates (#259) leave with nothing to refuse).

At 22733ce (main 631f087, #503, merged in by GitHub's update-branch): the first set listed below for fcbc7a2, plus every tests/test_update_shape*.py, gave 1213 passed, 22 skipped (the template-quoting skips below, and three NTFS-junction cases, Windows only); the second set gave 944 passed, 4 skipped.

At fcbc7a2 (origin/main 47b1e06 merged in, with #505 and #395):

every tests/test_family*.py, tests/test_validate_family*.py, tests/test_park_resume_targets.py, tests/test_free_plan_hint.py and tests/test_template_text_placeholders.py: 844 passed, 19 skipped (tests/test_family_init_values.py:219 and :291, which skip because the template now quotes the placeholder and id:).
tests/test_repo_hygiene.py tests/test_agents_md_codes.py tests/test_cli_reference.py tests/test_shape_doctor.py tests/test_setup_project_py.py tests/test_setup_sh.py tests/test_template_quoted_values.py tests/test_stdout_encoding.py tests/test_windows_paths.py tests/test_commit_trailers.py: 944 passed, 4 skipped (the doctor's PowerShell line and tests/test_stdout_encoding.py:286, Windows only).

At 708f3bb (origin/main aa4e1f5 merged in):

every tests/test_family*.py, tests/test_validate_family*.py, tests/test_park_resume_targets.py and tests/test_free_plan_hint.py: 718 passed, 8 skipped (tests/test_family_init_values.py:242).
tests/test_repo_hygiene.py tests/test_agents_md_codes.py tests/test_cli_reference.py tests/test_shape_doctor.py tests/test_update_shape_landing.py tests/test_doctor_unfinished_merge.py tests/test_template_values_single_pass.py tests/test_stdout_encoding.py tests/test_windows_paths.py: 813 passed, 4 skipped (the doctor's PowerShell line and tests/test_stdout_encoding.py:286, Windows only).

Earlier, with origin/main 48585e6 merged in:

tests/test_family*.py tests/test_validate_family*.py tests/test_stdout_encoding.py tests/test_windows_paths.py tests/test_repo_hygiene.py tests/test_agents_md_codes.py tests/test_cli_reference.py tests/test_park_resume_targets.py tests/test_bootstrap_spelling.py tests/test_free_plan_hint.py tests/test_template_values_single_pass.py: 1303 passed, 9 skipped.
tests/test_shape_doctor.py tests/test_update_shape*.py tests/test_commit_trailers.py tests/test_tracking_branch_ref.py tests/test_scaffold_ignored_shape_files.py tests/test_ruleset_hint_tracking_branch.py tests/test_bump_leg_dry_run_tracking.py tests/test_setup_project_py.py: 999 passed, 6 skipped.
The new files alone: test_family_init_landing.py 9, test_family_printed_quoting.py 69, test_family_tracking_branch.py 17, all passed.

The full suite was not run locally. CI's three jobs are the check.

Other open pull requests

#505 and #395 have since landed, and both are merged here at fcbc7a2. Each of #505's family sentences was read against this branch's code, and none is false: AGENTS.md 3 and 233; README 569, 822, 1152, 1269 and 1348; the handbook 1126 and 1506. #395 landed with its test switching to family/members before its real add, as the last bullet below says, and the first run above includes it. #503 then landed as 631f087, and GitHub's update-branch merged it here as 22733ce with no conflict. Main f391e58 (#266, #509, #496 and #435) was then merged by hand as 5a2776d, again with only the footer in conflict: main's clauses stay in main's order, this branch's (#487) moves after #509's (#498), and the README blob is recomputed; git show --remerge-diff shows nothing else. #509's reworded sentences in AGENTS.md, README.md and the handbook were read beside this branch's, and none contradicts or repeats another. Its setup-project.py changes (the clone-path check, the plan line, the step-(7) backstop and _main) and this branch's shell_word lines in the hand-over do not meet, and docs/cli.md passes --check. Main 8cd7dbe (#506 and #347) was then merged by hand as 654df49, again with only the footer in conflict: this branch's (#487) moves after #506's (#462), the README blob is recomputed, and docs/cli.md, which both sides changed, still passes --check. #506's two scripts/family.py hunks (the FAMILY_RULESET_HINT import, and its print when the holder's push is refused) sit unchanged inside this branch's code, and that hint prints no path. Under --reuse-empty-repo, init still refuses its default --into inside a checkout of this standard (family-landing-in-standard) before it reads the remote, as a dry run with a stub gh showed. #506's sentences in AGENTS.md, README.md and the handbook are still true beside this branch's. Main d41cc29 (#402, for #277), which rewrote the doctor's NEXT lines and tests/test_shape_doctor.py, was then merged by GitHub's update-branch as e42ef74, with no conflict; the holder fixture still switches to family/members before its add. AGENTS.md stays at 490 lines and README.md at 1422.

git merge-tree --write-tree of 708f3bb, at 04:47Z on 2026-10-13:

Clean: 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 (fix/family-makefile-without-siblings) and 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. Each merged tree keeps AGENTS.md at 490 lines and README.md at 1422.
docs/handbook.html footer only: 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 (docs/v1-accuracy) 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. 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 has landed and is merged here. 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 there too, and in scaffold-project.py, as it does with main. README.md and AGENTS.md merge clean with 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, and setup-project.py merges clean with 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. Whichever lands second keeps every footer clause and recomputes the README blob.
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 merges clean but one of its tests fails with this branch. tests/test_template_text_placeholders.py::test_a_member_whose_id_yaml_would_misread_is_pinned_under_that_id inits its own holder and runs a real add on main, which family.py add, bump and remove commit straight onto the holder's tracking branch, and add's NEXT pushes a <branch> that does not exist, though AGENTS.md says to land each as a pull request #487 refuses with family-on-tracking-branch. Whichever of the two lands second adds git("switch", "-q", "-c", "family/members", cwd=root) after that test's init; lane 5 is adding it on 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's own branch now, so this branch needs no change for it. (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's head d526f76 also conflicts with this head in tests/test_adopt_manifest_values.py, a file this branch does not touch: that is 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 against main, which the same round resolves.)

Windows

On Windows shell_quoted speaks PowerShell, the native shell this standard documents (setup-project.py), as the doctor's NEXT lines do. git -C …, python scripts\family.py … and cd … are shell-agnostic, so they get the platform's quoting, and no printed line joins two commands with &&, which Windows PowerShell 5.1 rejects.
rm -rf, mv and mkdir -p are POSIX commands. They are quoted for a POSIX shell on every host, and the text says "in a POSIX shell (Git Bash on Windows)". PowerShell refuses rm -rf's -rf and deletes nothing.
The tests split a host-quoted line with a PowerShell reader on Windows and with shlex elsewhere, and split a POSIX-only line with shlex everywhere. The real-shell test is skipped on Windows.
On Windows the tests do not execute rm or the mv lines. They delete the split path with shutil.rmtree, and stop after checking the mv argv.
Paths: the cached store keeps git's POSIX spelling (as_posix), as before. Test paths are resolve()d, which expands an 8.3 short name such as RUNNER~1.
Nothing here was run on Windows or macOS locally. The tests-windows and tests-macos CI jobs are the check; on macOS the real-shell test runs the shipped zsh.

Left out

A shipped template that imports a newer shared helper can break a holder that kept an older copy. This change no longer does (siblings.py uses shlex.join), but nothing stops the next one: update-shape.py apply --accept-local scripts/repo_shape.py keeps a repo_shape.py that lacks a name a newly copied file imports, and check and the validator then read the holder as fine. The general guard is for apply to refuse that, as rv456 found for bootstrap.py and spelled (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).
The doctor's quote_arg leaves a word that begins with = bare, which zsh expands. shell_quoted quotes it; the doctor is left as it is here, and the agreement test excludes that one case.
The doctor and update-shape.py keep their own quoters. The doctor's quote_arg flattens to ASCII by its report's contract, so moving it onto repo_shape.shell_quoted is more than an import change. update-shape.py's POSIX shlex lines are lane 3's open 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. A test holds shell_quoted and quote_arg to one answer on every printable ASCII value but a leading =.
family.py's by-hand rollback commands (family.py bump and remove have no rollback: when a git step after write_members fails (a holder pre-commit hook that exits 1, a held index.lock), they exit 2 with REFUSED a git or gh command failed and leave family.yaml rewritten, the member checked out at --to (or deinitialised and removed), and the change staged or half-staged, without a word about any of it, where add puts the holder back and names what it put back #365) and its git config -f .gitmodules removals (family.py: add refuses member-path-registered when a .gitmodules section under another name already gives the mount path, and validate-family.py finds gitmodules-path-twice, so add no longer commits two sections for one path that a recursive clone resolves to the later one, and a holder that already has such a ghost section fails its own gate (#300) #317, family.py remove, when .gitmodules gives the member's path to two sections, takes out only the one git finds by that path (the later in the file) and exits 0, so its commit still registers members/<P> with no gitlink and no row, validate-family.py passes the result (after #317 it reported the doubled file and stops), and the next add of that member is refused member-path-registered or silently reuses the leftover section and the .git/config registration deinit never touched #360) keep shlex.quote. They were already quoted, they are POSIX-only (printf … | git update-index), and they are worded for a POSIX shell.
The holder's validate-family.py remedies that name family.py add (member-gitlink-absent, member-gitlink-unnamed) print no branch step: they are a holder copy, and the add they name refuses the tracking branch with its own switch remedy.
remove's store note still computes .git/modules/<path> rather than asking git rev-parse --git-path, as add does. In a linked worktree it therefore prints no note. That predates this change.
PowerShell verbs (Remove-Item, Move-Item) are not printed for the POSIX-only commands.
README's --into sentence gives the default but not the refusal. README.md (861) and the handbook (1246) say --into <dir> is the PARENT directory, "the directory you are standing in, by default". They do not say that init refuses that default inside a checkout of this standard (family-landing-in-standard). AGENTS.md item 1 says so, and the README's own example passes --into ... README.md is at its 1422-line cap, so the sentence is on Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459's checklist.
setup-project.py's own cd <clone> line and its step-(7) backstop lines print their paths unquoted. This change quotes only the family lines it prints. Those two predate it and setup-project.py: the clone path <into>/<Project> is refused in step (3), before anything is created, when anything at all stands there, naming the path and telling a rehearsal's leftover clone apart as one to move or delete, and the plan names the clone path before the yes, so rehearsing and then running for real in the same folder - README's own order - no longer creates three repositories and then refuses with a hand clone that fails on the same directory (#498) #509, and they are on Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459's checklist.

Closes #488
Closes #486
Closes #487

🤖 Generated with Claude Code

Summary by Sourcery

Harden family initialization and membership workflows so they land outside standard checkouts, produce reliably executable commands, and commit changes only on review branches.

Bug Fixes:

Prevent family initialization from creating a family inside an openRepoShape checkout when no destination is specified.
Make generated family commands safe to paste from directories containing spaces, apostrophes, Unicode, or shell syntax across POSIX shells and PowerShell.
Prevent family add, bump, and remove commits on the tracking or detached branch, and print the correct branch push instructions.

Enhancements:

Use relative paths to the family script in generated next steps and provide complete branch guidance for family workflows.
Add shared shell quoting utilities for generated commands and keep holder sibling commands compatible with older local helper copies.

Documentation:

Update AGENTS.md, README.md, CLI reference, handbook, and family-holder templates with safe initialization, branch, and push instructions.

Tests:

Add coverage for safe family landing, command quoting, tracking-branch protection, generated instructions, and compatibility with older holder helper copies.

…unless `--into` or `--work-dir` names the place, and its NEXT STEPS name this file from where `init` ran, so AGENTS.md's own command no longer puts the holder inside the standard and the next command it prints no longer fails `can't open file` (#488) AGENTS.md spelled the command `python3 scripts/family.py init --org <org> --family <Name>`, a path that runs from the standard's root, and `--into` defaults to where the person stands. Followed exactly it printed `landing <standard>/Orbit/Orbit` with no word, and `make siblings` would then clone every member into the standard's checkout too. The NEXT STEPS block printed `python3 family.py add ...`, built from `Path(__file__).name`, which from the root fails `can't open file`, exit 2. - `_landing`: with neither `--into` nor `--work-dir`, a landing inside a checkout of openRepoShape (a directory holding `scripts/family.py` beside `templates/family-root/`, found in the landing's ancestry, so another clone or an install counts too) is refused, `family-landing-in-standard`, before anything is created and under `--dry-run` alike. The remedy names `--into ..` from the root, and from deeper inside the relative path that reaches the checkout's parent. An explicit `--into` or `--work-dir` is not second-guessed. `family-holder-already-here` is still asked first. - `_family_script`: NEXT STEPS and the `family-holder-already-here` remedy name this file relative to the directory `init` ran in, `scripts/family.py` from the root as every other place spells it, absolute where no relative path exists. - AGENTS.md's init command passes `--into ..`, as README's already does, and step 1 says why (line-neutral: step 1 is one line shorter). `--into --help` says it; docs/cli.md regenerated. - tests/test_family_init_landing.py: the old command from the root is refused (a dry run, so nothing can land in the checkout); a real run in a fake checkout creates nothing; the remedy from a subdirectory; an explicit `--into .` or `--work-dir .` passes; outside a checkout the default is unchanged; AGENTS.md's line as written lands beside the checkout; and the printed NEXT, from the root and from elsewhere, names a path that runs. Lane: openreposhape-5 (openRepoShape-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…ts paths through one quoter, `repo_shape.shell_quoted`, and the `member-git-dir-cached` remedy names the store on its own line before its quoted `rm -rf`, so under a folder with a space the remedy no longer deletes the wrong directory and `add`'s push line no longer fails `cannot change to` (#486) `scripts/family.py` and a holder's `scripts/siblings.py` printed every path in their pasteable commands bare. Under a holder at `.../my work/Sonata/Sonata` the `member-git-dir-cached` remedy `rm -rf <store>` split into `rm -rf .../my`, an absolute directory that is NOT the store, and a relative `work/...`; `init`'s NEXT STEPS and `add`'s NEXT split `--family-root` and `git -C` (`fatal: cannot change to '.../my'`, exit 128); and the `mv` lines for a misnamed family folder pasted as four arguments. - `scripts/repo_shape.py` gains `shell_quoted` and `shell_line`, in a new section at its end: the doctor's `quote_arg` rule (#101/#102), the same two alphabets and the same two escapes, `sh`'s `'\''` and PowerShell's doubled apostrophe, chosen by `os.name` or a `platform` argument, leaving an ordinary word bare. It does not flatten to ASCII, as the doctor's report does, because a command that deletes or moves a directory must name that directory; so PowerShell's typographic single quotes are doubled too. It lives here because `siblings.py` is a holder's copy and this is the one library a holder carries beside it, as #456 put `spelled` here. The pinned `repo_shape.py` and `siblings.py` move in every project and holder; #456 already moved `repo_shape.py` in this release. - `family.py`: `init`'s NEXT STEPS print the `add` on ONE line (it pasted only into a POSIX shell, by its `\` continuation) and the `cd` with every path quoted, as does the `family-holder-already-here` remedy; `add`'s NEXT quotes `git -C <holder>`; `member-path-taken` quotes each spelling it names; and `member-git-dir-cached` and `remove`'s note about the same store print the directory alone on its own line, then `rm -rf` with its one argument quoted for the POSIX shell `rm -rf` is a command of, which the sentence names (Git Bash on Windows; PowerShell refuses `-rf` and deletes nothing). - `siblings.py`: the parent-folder warning's `mv` and `mkdir -p` lines go through `shell_line` for a POSIX shell, and the warning says which shell. - The doctor and `update-shape.py` keep their own quoters: the doctor's flattens to ASCII by its report's contract, and `update-shape.py`'s POSIX-only `shlex` lines are lane 3's open #374. Not an import change. - tests/test_family_printed_quoting.py: the quoter round-trips through `shlex.split` and through a PowerShell reader for spaces, apostrophes, `é`, a typographic apostrophe, shell syntax and the empty string, and agrees with the doctor's `quote_arg` on every ASCII value; and under a holder in `my work` and in `Dana's work`, `init`'s NEXT, `add`'s NEXT, the cached-store remedy and note, and the `mv` lines each split into the argv they mean, the `rm -rf` run as split deletes the store while the decoy `<tmp>/my` survives, and the `mv` lines run as split move the holder. Three existing tests' expected lines follow the new wording. Lane: openreposhape-5 (openRepoShape-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…r's tracking branch or a HEAD on no branch, naming the `git switch -c` that makes one, and end with the push of the branch they committed on, so AGENTS.md's "land it as a pull request" can be followed and the printed NEXT no longer pushes a `<branch>` that does not exist (#487) AGENTS.md says each of the three writes ONE commit, to land as a pull request, and no step made the branch that pull request needs. After `init` the holder stands on `main`, and all three committed straight onto it; `add` printed `NEXT git -C <holder> push -u origin <branch> && open a pull request`, a placeholder no repository has (`src refspec ... does not match any`), even on a branch; `bump` and `remove` printed no NEXT. `bump-leg.py` refuses exactly this for a leg (`bump-leg-on-tracking-branch`). - The real run of each refuses the holder's tracking branch (`family-on-tracking-branch`) and a HEAD on no branch (`family-holder-detached`, as `bump-leg.py` refuses `bump-leg-root-detached`), after the refusals about the arguments and the holder and before the member is read, fetched or cloned or anything is written. The remedy is the quoted `git -C <holder> switch -c <branch>`: `family/add-<project>`, `family/bump-<id>-<sha12>` or `family/remove-<id>`, `member` for a name that is no plain branch word. - `--dry-run` runs on any branch and prints a `branch` line: where the commit lands, or that the real run refuses there, by its code, with the `switch` on a line of its own. The module's EXIT CODES paragraph names it as the one refusal a dry run does not make. - Each act that commits ends with ONE pasteable line, `NEXT git -C <holder> push -u origin <the branch it committed on>`, every word quoted by `shell_line` (#486), then `then open a pull request against <tracking>; never push to it directly`. `bump` and `remove` gain it. - `init`'s NEXT STEPS open with the `switch` before the `add`. - `add`, `bump` and `remove` `--help` say the rule; docs/cli.md regenerated. - AGENTS.md's family block gains the `switch` step before the `add`, and step 3 says the tracking branch is refused (`family-on-tracking-branch`) and the branch is pushed as its NEXT line says; README's InkRouter block gains the same step and its paragraph says it. Both line-neutral (AGENTS.md steps 2 and 5 and README's `make bootstrap` paragraph are tightened). docs/handbook.html mirrors the block and the sentence; its footer names #487 and the new README blob. - Fixtures that committed on `main` commit on a branch: `tests/test_family.py` grows the family on `family/members` and pushes it to the remote's `main`, as the merged pull request would; `test_shape_doctor.py`'s holder and `test_family_add_excludes.py`'s `empty_holder` switch to a branch; `test_family_add_refusals.py`'s NEXT expectation names the branch, its unborn holder is born on a branch of its own, its empty-family holder switches, and its corrupt-HEAD test writes the branch HEAD is on and, for HEAD naming a tag, answers the branch check in-process, since the test is about the rollback's reading of HEAD; the siblings layout row names the holder's branch. - tests/test_family_tracking_branch.py: for each act, refused on `main` with the holder byte for byte as it was (and, for `add`, nothing cloned), the printed `switch` run as split makes the branch, the act goes through on it, and its printed NEXT run as split pushes it, which the remote then holds at the act's commit; a detached HEAD refused; dry runs on `main` and on a branch; suggested names pass `git check-ref-format --branch`; `init`'s NEXT STEPS open with the `switch`. Lane: openreposhape-5 (openRepoShape-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Lane: openreposhape-5 (openRepoShape-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/handbook.html: the footer keeps both additions, #477's bump-leg.py `--dry-run` sentence and #487's, and names the merged README's blob, `git hash-object README.md`. Lane: openreposhape-5 (openRepoShape-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Lane: openreposhape-5 (openRepoShape-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

… `repo_shape.py` still runs `make siblings`, `park` and `resume`; a word that begins with `=` is quoted; `init` prints `cd` and `make siblings` on two lines; setup-project's `add` names the branch first and quotes the holder (#486 review) - siblings.py quotes its POSIX `mv` and `mkdir -p` lines with `shlex.join` and no longer imports `shell_line`. A holder that kept its own `repo_shape.py` through `update-shape.py apply --accept-local` took the new siblings.py without the name and died with an ImportError at `make siblings`, `park` and `resume`, while `check` and the validator read the holder as fine. A test runs the holder's siblings.py `--help`, the misnamed-folder warning and `--make park` beside a `repo_shape.py` that lacks every name #486 added. - `repo_shape.shell_quoted` quotes a word that begins with `=`, in both dialects: zsh, macOS's login shell, expands a bare `=word` to a command's path. The doctor's `quote_arg` keeps the gap; the agreement test excludes that one case. - The agreement test with the doctor's quoter now covers every printable ASCII character alone and before, inside and after a word, and asserts the two alphabets are the same patterns. A new test runs the quoted words through the host's own sh, bash and zsh. - `init`'s NEXT STEPS print `cd <holder>` and `make siblings` on two lines: Windows PowerShell 5.1 rejects `&&` between two statements. - setup-project.py's family hand-over prints `git -C <holder> switch -c family/add-<project>` before the `add`, which refuses the tracking branch (#487), and quotes the holder with its own copy of the rule, held to `shell_quoted` by a test. Lane: openreposhape-5 (openRepoShape-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…DME show the branch step before `add`, `--help` says the act prints the push, and a test holds the tracking branch to the one family.yaml declares (#487 review) - templates/family-root/AGENTS-shape.md and README.md open their add/bump/remove block with `git -C <path> switch -c family/add-<project>` and say each act refuses the holder's tracking branch (`family-on-tracking-branch`) and ends by printing the branch's push. - `add`, `bump` and `remove` `--help`: "ends by printing the `git push` of that branch", not "ends with", which read as the tool pushing. docs/cli.md regenerated. - A test inits a family with `--tracking-branch trunk`: `add` is refused on `trunk`, and on a branch named `main` the dry run says the commit lands there for a pull request against `trunk`, the real run commits, and its NEXT pushes `main`. Hard-coding "main" as the tracking branch now fails it. - A test holds AGENTS.md, README.md and the holder's two docs to showing the `switch -c` in the same block as, and before, the first `add`. Lane: openreposhape-5 (openRepoShape-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Lane: openreposhape-5 (openRepoShape-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

brettheap · 2026-10-13T02:12:24Z

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

sourcery-ai · 2026-10-13T02:12:26Z

Sorry @brettheap, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 3 days and 21 hours by commenting @sourcery-ai review. Upgrade to get a review now.

chatgpt-codex-connector · 2026-10-13T02:12:32Z

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.

sourcery-ai · 2026-10-13T02:12:43Z

Reviewer's Guide

The PR fixes three family workflow defects: safe default initialization, shell-correct printed commands, and branch-safe add/bump/remove operations with actionable push guidance, backed by focused regression coverage and updated documentation/templates.

Sequence diagram for branch-safe family operations

sequenceDiagram
    actor User
    participant Family as family.py
    participant Holder as Family holder
    participant Git as Git remote
    User->>Family: add, bump, or remove
    Family->>Holder: Inspect current branch
    alt Tracking branch or detached HEAD
        Family-->>User: Refuse with family-on-tracking-branch or family-holder-detached
        Family-->>User: Print git switch -c remedy
    else Work branch
        Family->>Holder: Write one commit
        Family-->>User: Print git push -u origin branch
        User->>Git: Push branch
        Git-->>User: Branch available for pull request
    end

Flow diagram for safe family initialization

flowchart TD
    A[Run family.py init] --> B{Explicit --into or --work-dir?}
    B -->|Yes| C[Use requested landing]
    B -->|No| D{Inside openRepoShape checkout?}
    D -->|Yes| E[Refuse with family-landing-in-standard]
    E --> F[Suggest --into parent]
    D -->|No| C
    C --> G[Create family folder and holder]
    G --> H[Print branch switch and add commands]

File-Level Changes

Change	Details	Files
Prevent family initialization from placing new families inside an openRepoShape checkout and make generated follow-up commands runnable from the invocation directory.	Refuse implicit default landings inside detected standard checkouts, including dry runs, while preserving explicit destination overrides. Update AGENTS.md and CLI help to use and explain `--into ..`. Derive the printed family.py path relative to the caller and apply it to NEXT STEPS and remedies.	`scripts/family.py` `AGENTS.md` `docs/cli.md` `tests/test_family_init_landing.py`
Make all user-pasteable commands preserve path boundaries across POSIX shells and PowerShell.	Add shared POSIX/PowerShell shell quoting and command-line helpers with handling for spaces, apostrophes, Unicode, shell syntax, and leading `=`. Quote family.py's git, add, cd, deletion, and remediation commands; split init follow-up commands into PowerShell-compatible lines. Quote siblings.py POSIX move commands independently so holders with older repo_shape.py copies remain runnable. Keep setup-project.py self-contained while matching the shared quoting behavior.	`scripts/repo_shape.py` `scripts/family.py` `templates/family-root/scripts/siblings.py` `setup-project.py` `tests/test_family_printed_quoting.py`
Require family mutations to commit on a non-tracking branch and print the exact branch push needed for pull-request workflows.	Refuse real add, bump, and remove operations on the configured tracking branch or detached HEAD before writes. Generate valid suggested branch names and print executable switch remedies. Add dry-run branch reporting and push NEXT lines for all committing operations. Update initialization output, help, documentation, templates, setup hand-off, and fixtures to establish the branch-first workflow.	`scripts/family.py` `AGENTS.md` `README.md` `docs/cli.md` `docs/handbook.html` `templates/family-root/AGENTS-shape.md` `templates/family-root/README.md` `setup-project.py` `tests/test_family_tracking_branch.py` `tests/test_family.py` `tests/test_family_add_excludes.py` `tests/test_family_add_refusals.py` `tests/test_shape_doctor.py`

Assessment against linked issues

Issue	Objective	Addressed
#486	Quote paths in pasteable commands printed by family.py and siblings.py so paths containing spaces or shell-special characters remain single arguments.	✅
#486	Make the cached-store rm -rf remedy identify the target directory separately and quote its single deletion argument, preventing a pasted command from targeting the wrong directory.	✅
#486	Test the printed commands under holder paths containing spaces by checking shell argument splitting and, where safe, executing them to verify the intended target is affected.	✅
#487	Refuse real add, bump, and remove runs on the holder’s tracking branch, provide a branch-creation remedy, and allow dry runs on any branch.	✅
#487	Have each successful act print a pasteable push command naming the branch it actually committed on, followed by pull-request guidance.	✅
#487	Update the family instructions and relevant test fixtures so users create a work branch before an act and tests no longer rely on committing to the tracking branch.	✅
#488	Prevent `family.py init`, when run from the standard's checkout with its default landing location, from placing the family inside that checkout; provide a clear remedy and update AGENTS.md's command to land beside the checkout.	✅
#488	Make `init` print a runnable `scripts/family.py add` command, using a path relative to the directory from which `init` was run.	✅

Tips and commands

Interacting with Sourcery

Trigger a new review: Comment @sourcery-ai review on the pull request.
Continue discussions: Reply directly to Sourcery's review comments.
Generate a GitHub issue from a review comment: Ask Sourcery to create an
issue from a review comment by replying to it. You can also reply to a
review comment with @sourcery-ai issue to create an issue from it.
Generate a pull request title: Write @sourcery-ai anywhere in the pull
request title to generate a title at any time. You can also comment
@sourcery-ai title on the pull request to (re-)generate the title at any time.
Generate a pull request summary: Write @sourcery-ai summary anywhere in
the pull request body to generate a PR summary at any time exactly where you
want it. You can also comment @sourcery-ai summary on the pull request to
(re-)generate the summary at any time.
Generate reviewer's guide: Comment @sourcery-ai guide on the pull
request to (re-)generate the reviewer's guide at any time.
Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
pull request to resolve all Sourcery comments. Useful if you've already
addressed all the comments and don't want to see them anymore.
Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
request to dismiss all existing Sourcery reviews. Especially useful if you
want to start fresh with a new review - don't forget to comment
@sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

Enable or disable review features such as the Sourcery-generated pull request
summary, the reviewer's guide, and others.
Change the review language.
Add, remove or edit custom review instructions.
Adjust other review settings.

Getting Help

Contact our support team for questions or feedback.
Visit our documentation for detailed guides and information.
Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

… holder README sends a reader to the `NEXT` line for the push, not the act's last line, `refs/heads/` is spelt once as `HEADS_PREFIX`, and the printed-quoting test asserts actual-first throughout (#486 #487 #488 review) The holder's README said "Push it as the command's last line says". The act's last line is "then open a pull request against <tracking>; never push to it directly"; the push is the `NEXT` line before it. It now says "as its `NEXT` line says", AGENTS.md's wording. No other holder doc or AGENTS.md and README.md carry the claim. `family.py` held the literal "refs/heads/" four times, in `_holder_branch` and `_member_head` (SonarCloud python:S1192). It is now the module constant `HEADS_PREFIX`; behaviour is unchanged. `test_the_two_alphabets_are_the_doctors` put the expected value first, and the other 32 assertions in `test_family_printed_quoting.py` put the actual value first (python:S3415, anchored at line 138 but naming lines 244 and 245 as the odd ones). Both now read `actual == expected`. Lane: openreposhape-5 (openRepoShape-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Lane: openreposhape-5 (openRepoShape-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

… writes its pin file as the scaffold does, so an adopted root passes `validate-pins.py` (#273); a `--pin-source` that cannot answer is `pin-source-unreadable` (#339) (#508) **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 #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.) - #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 #409 since this branch last merged it: #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 #409's final blob, with main's #359 workflow reader in it. This branch had no change of its own to the file beyond #409. - **`adopt-project.py`, `_commit_the_split`.** - Main: #445 wraps the function in its late-failure `try`, and #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.** #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. `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` | 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 #309's wording); - from #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 #339 (below); and fix round 1 changed three of them (below): `pin_variable_collisions` keys each pin by #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 #339's row. Its pin tests and #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` (#273 decision 4), in the scaffold's sentence and remediation (#241, #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 #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 #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). #386 records that `execute` then wrote the name as eight one-letter pins. - Not fixed here: #386's other keys, `allow_empty_legs:`, `paths:`, `legs:` and `source:`, so #386 stays open. Lane 2's #435 takes all of #386, `pins:` included, and its `pins:` rule keeps only text items where this branch writes mappings; whichever lands second reconciles them (#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). `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 #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`. 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 #245, #351, #350, #345, #372, #371, #354, #380, #377 and the rest since ab623dd, with no conflict. - **45e01f4 (4098b61).** It brought #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), #314.** One conflict, one hunk in `adopt-project.py`. This branch's `_refuse_an_unrecordable_pin_source` and #314's section "The project must be able to hold what `execute` writes into it (#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. - #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). 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. Lane 5's review of 7a94b6b found 3 should-fix and 5 nits. Each is answered here: - **#409's `pin_product_key` (review N1).** The merge of #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 #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 #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 #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 #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 #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, #339's third decision.** A `--pin-source` that nothing reads is still silent, now in adopt too. This PR does not decide it. #451, filed, lays out refuse, note and leave, so closing #339 loses nothing. 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 #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). **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, #339's file, #275's tests, the pin and neutral-pin validators, git output decoding, adopt template values, CLI reference, scaffold pin and reuse, scaffold pin collisions, #314's two files and #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 #445's `test_adopt_late_failure.py`, `test_adopt_git_reads.py` and `test_adopt_filter_repo_failure.py` and #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 (#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 #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 #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 #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 #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, #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). - #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: - #409 is carried whole. A 30,000-case fuzz of `--pin` lists through #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 #409's (same patch-id). - `_commit_the_split` keeps #445's `try` and #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. `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 #468 whose head main does not contain: #473, #474, #490, #491, #493, #494, #495, #496, #497, #503, #504 and #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:** #343, #346, #355, #358, #373, #378, #382, #387, #394, #397, #401, #404, #409, #419, #452, #456, #465, #466 and #484. #394's `_commit_the_split` conflict and #401's `docs/cli.md` conflict are both resolved in f9ed46f, above. - **Clean, 20:** #266, #347, #356, #374, #376, #384, #395, #453, #467, #468, #473, #474, #490, #491, #493, #494, #495, #497, #503 and #505. #453, #468 and #491 were updated onto main since the first read and now merge clean. #507 (lane 5's #486-#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:** - #402: `shape-doctor.py` 5; - #496: `shape-doctor.py` 10 and `tests/test_shape_doctor.py` 1. **Conflicts this branch adds:** - **#435** (3efcc7a, lane 2's `fix/adopt-plan-field-types`, for #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". - **#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`. - **#506** (119d8c4, `fix/scaffold-reuse-seeded-legs`). - It adds 1 hunk in `scaffold-project.py`. With main alone, #506 conflicts only in `docs/handbook.html`. - #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 #506's `LEG_TEMPLATES` block. Drop #506's `declared_pin_values`/`declared_pin_products`, which moved here, and this branch's three-line `_reusable_remotes` opener, which #506 rewrites below. Resolved that way, pyflakes is clean and #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. #445, the late-failure notice, is on main and merged here. **Where the meaning meets:** - **#435 and #386.** The coordinator has said this on #435: #435 (comment) - #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 #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. - **#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. - **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; #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 #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 #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:** - #449: S3, a hand-edited `commit:` or `tree_sha256:` that disagrees, with options (a) and (b); - #450: the scaffold half of N2, a `--pin-source` path no file can hold; - #451: #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 #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 here; CI ran both (below). 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. Reviewed independently by lane 5 at 7a94b6b (3 should-fix, 5 nits: fix round 1) and at 421e4e5 (0 blockers, 2 should-fix, 3 nits: fix round 2). After #409's squash, the re-verification of f9ed46f and 73d65c6 found the code correct; its 1 should-fix and 3 nits were in this description and are fixed. GitHub's update-branch then merged main twice (33bae3f, 2170526), with no hand edit. CI's tests, tests-macos and tests-windows and SonarCloud all passed at 2170526 (main cac6bb2 merged in). On that head merged with main 57c85e9 (#490, #474 and #468, none of which touches this branch's files), the pin and adopt set with `tests/test_update_shape_landing.py` gave 1112 passed, 2 skipped, and the doctor, adopt end-to-end, unfinished-merge and bootstrap set gave 1056 passed, 3 skipped (the doctor's PowerShell line, which exists only on a Windows host). Closes #273 Closes #339 Lane: openreposhape-5 (openRepoShape-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Resolved docs/handbook.html's footer (one hunk): main's clauses kept (#411, then the doctor's merge row #424), this branch's #487 clause kept, README.md blob set to the merged README.md's hash. Lane: openreposhape-5 (openRepoShape-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…holder to a branch before add, so the test holds once #487's tracking-branch refusal lands (PR #507) `test_a_member_whose_id_yaml_would_misread_is_pinned_under_that_id` runs `family.py init` and then three real `add`s. PR #507 (#487) makes `add`, `bump` and `remove` refuse on the holder's tracking branch as `family-on-tracking-branch`, so the test now switches the new holder to `family/members` first, in the file's own idiom and as #507's own fixtures do. On main this changes nothing: `add` commits on any branch. Neither PR has to edit this test, whichever lands first. Lane: openreposhape-5 (openRepoShape-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

… false are corrected to what the tools do on main (#483) (#505) **Closes #483.** #483 is the v1.0.0 "README and AGENTS.md accurate" criterion. Three read-only audits (AGENTS.md; README.md lines 1-727; README.md lines 711-end) checked every statement that names a command, a flag, an exit code, a refusal, a file or a step against the code at `ec4a7a0e` and ran the tools offline (local bare remotes, a stub `gh`, a blank git identity). They found 38 false or incomplete statements. This pull request corrects 28 of them (27 whole, and D2-F1 in part), plus two the independent review found (the `MISPLACED` text after #394, and `openRepoShape --preflight` "offers to install" git-filter-repo): 29 rows in all, D1-F9 and D3-F7 sharing one. The other ten, and the rest of D2-F1, were settled by pull requests that landed while this one was open: #484 and #465 settle six (D1-F8, D2-F7, D3-F6; D2-F13, D2-F14, D3-F8), and #491 and #468, to which this branch had routed them, settle four (D1-F1, D2-F5, D1-F2; D3-F11) and the rest of D2-F1. The two routed to #490 (D1-F9, D3-F7) were still false once it landed, and are corrected here. A last read of every line main has added to README.md and AGENTS.md since `ec4a7a0e` found nothing else false, so nothing is left open under #483. Two independent reviews, six rounds. The first head (`bfbd4eeb`) came back CHANGES NEEDED: two corrections that were themselves untrue (exit 3; "each of those tools has its own section") and nine gaps. The second (`ccf520bd`, on a merge of `7a8b981d`, where #394 landed) fixed them and came back with no blocker and three landing changes, which the third commit (`f35e59fa`, on a merge of `5a253877`, where #484 landed) makes: D2-F5 and D1-F1's block go back to #491 (at `2d59d141` its `setup-project.py` reads the yes from the controlling terminal, so the piped one-liner asks once it lands, and its new test strips `<...>` from README.md, which a `bash <(` line breaks); D3-F5 is fixed here now that #484 has landed; and the routes are re-derived at the current heads. The same commit leaves AGENTS.md's family steps 3 and 5 as main has them, so #486-#488 (`10c93ded`) still merges clean. The fourth round merges `48585e62`, where #465 landed (README.md at 699-709, 1028 and 1095 and the handbook beside them, none of which this branch edits), and re-reads the three #465 rows on main. The fifth merges `57c85e92`, where #468 landed (the doctor's `merge` row), as `fb6a9ab4`: the doctor's verdict table, in README.md and in the handbook, takes this branch's `COMPLIANT`, `SHAPE BEHIND` and `DRIFTED` rows and main's `MISPLACED` and `INVALID` rows, and the handbook footer keeps both clauses (#424, then #483) with its blob recomputed. `aa4e1f59` (#508) then merged clean, as `83cfad54`. The sixth merges `70d0d1b3`, where #491 landed (setup asks at the person's own terminal), as `94793aeb`: README.md's "What Dana sees" paragraph takes #491's text whole with this branch's D2-F6 ("a hyphenated name"), and the handbook footer keeps #476's and #492's clauses ahead of #483's, with its blob recomputed. The same round re-reads every routed row on main, corrects D1-F9 and D3-F7 (`ea634043`), and reads what main changed in both files since `ec4a7a0e`. The first reviewer's round four came back APPROVE WITH NITS (0/0/3) and asked for one word, made at `9ac90d16`: "a hyphenated project name", since the leg names are hyphenated and pass. **What.** `README.md` and `AGENTS.md` only, plus `docs/handbook.html` where it repeats a corrected sentence, with its footer's `README.md blob` recomputed (`git hash-object README.md` = `1417b9ec0235675da8f73ca023756411bc3fbe8a`). No tool, test, template or `docs/cli.md` changes. `README.md` hashes identically at `ec4a7a0e`, `437a360a`, `d222a124` and `7a8b981d`, so its audit line numbers held; `AGENTS.md` changed only by #394 (it adds 5 lines after line 154 and 3 more after the doctor's item 4); #484, #465 and #491 since edited both files, and #468 README.md, without changing either total. Each fix is the smallest true sentence, keeps the surrounding voice, and states only what the code or a run showed. **The line caps.** `tests/test_repo_hygiene.py` holds `AGENTS.md` to 490 lines (#394 raised it from 482) and `README.md` to 1422, and both files stand exactly at their caps, so every correction is line-neutral. To give back the lines the longer sentences need, paragraphs that no correction touches are re-wrapped to 80 columns with no word changed: - README.md, eight paragraphs no correction touches: macOS (`and refuses anything below 3.9`), `2. Login.`, the InkRouter ruling quote, `Each leg is pinned TWICE`, the neutral-product election paragraph (`Ruled by Brett Heap on 2026-09-05`), `Its entries are adopt-project.py plan's entries`, `This repository implements neither`, `A FAMILY holder carries both verbs too`; and the tail of the `--link-source` paragraph that D2-F12 edits. None is in README.md's family section (903-925 on main), which #486-#488 edits. - AGENTS.md, four paragraphs no correction touches: the opening paragraph, the NO-code seeding paragraph, doctor item 1 and the park overlay item; and the first half of the doctor intro, whose second half D1-F7 edits. The family steps are main's exact bytes: an earlier head re-wrapped steps 3 and 5 (`make siblings`) and #486-#488 edits both. - Three sentences this pass corrects give up a few words to keep a line: D2-F1's "offers to run" (no "for you"), D2-F11's "asks the same of one name", and AGENTS.md's `check` verdict list and doctor next-command item (D3-F9, D1-F7). Word-level diffs of both files (`rvD-worddiff.py`) show only the edits in the tables below, `rvD-hunks.py` marks each re-wrapped hunk `WHITESPACE-ONLY`, and `rvD-mdstruct.py` finds the Markdown block structure, links and HTML identical (AGENTS.md 320/320 blocks, README.md 678/678). "Where" is the audited `ec4a7a0e` for README.md (it hashes the same up to #394, and #484 and #465 changed its text and not its line count, so those numbers still point at the same places on main); AGENTS.md lines after 154 read 5 higher on main, and 8 higher after the doctor's item 4, since #394. "Evidence" is code at `7a8b981d` (the line numbers below are that file's, re-derived at the merged head `48585e62` for every tool file that #394, #484, #465 and the later landings moved), and "run" is the audit's or this pass's offline run. | finding | where | was | now | evidence | |---|---|---|---|---| | D1-F3 | AGENTS.md:121 | "the preflight prints the install command" for git-filter-repo | "`execute` refuses without it, printing the install command" | adopt-project.py:4148-4158 (`_require_filter_repo`, `filter-repo-missing` + `FILTER_REPO_HINT` at 261-267), only call at 5652; `--preflight` checks git, Python, bootstrap, gh, helper, autocrlf only (setup-project.py:1110-1134); openRepoShape:212-216 | | D1-F4 | AGENTS.md:176-178 | the row reads `code: 0 of N source paths (seeded from template)` | the table's `code` row reads `0 of N source paths (seeded from template)` | adopt-project.py:6107-6108 prints `f" {leg:<6} {counts[leg]:>5} of {len(before)} source " f"paths{note}"`, no colon; run: ` code 0 of 2 source paths (seeded from template)` | | D1-F5 | AGENTS.md:182 | "`MedxGlass` descends from `openGlass` only if it PINS it (2026-09-02)" | "...or pins a layer that does and records the chain (`--referent-chain`; 2026-09-02, chains 2026-09-05)" | scaffold-project.py:379-391; run: `--pin openXglass@<sha> --referent-chain openXglass,openGlass --dry-run` printed "classifies as domain-descendant / assembly" | | D1-F6 | AGENTS.md:205-210, 258-259 | `openRepoShape --doctor` and `./shape-doctor.py` presented as one tool; "`--json` is the same report" | installed, it runs from a temporary clone deleted on exit and takes a path and nothing else; to act on a row (`--json`, `--placement-plan`, its next command) run `./shape-doctor.py --root <path>`; item 7 names `./shape-doctor.py --json` | openRepoShape:112-116 (EXIT trap), 329-352 (`shape_checkout` into `$WORKDIR/shape`), 379-392 (`run_doctor` clones when no checkout is beside it), 463-471 (`--doctor takes a path and nothing else`); run: the installed copy printed `NEXT python3 <tmp>/shape/adopt-project.py plan ...` and the directory was gone after exit; `--doctor <root> --json` printed `REFUSED: --doctor takes a path and nothing else`, exit 2 | | D1-F7 | AGENTS.md:226-232 | next commands are "`update-shape.py apply …`, `make bootstrap`, `bump-leg.py …`"; every one "carries the exact next command"; "each of those commands has its own section above" | "Every one carries the exact next command, where one can be named — `update-shape.py check …` and its `apply`, `git submodule update …` (in a holder, its `scripts/bootstrap.py`), the project's own validator"; "Each of those commands keeps its own refusals" | shape-doctor.py:2813 and 2828 (check NEXT), 3075-3089 (`legs` NEXT is `git submodule update`, `make bootstrap` only in the trailing comment), 5044 (holder `members` NEXT); no row's NEXT is a `bump-leg.py` command (`grep -c -i 'bump.leg\|bump_leg' shape-doctor.py` was 0 at `7a8b981d`; since #495 the `pins` row's reason names two `bump-leg.py --to` lines, as text, at shape-doctor.py:1847-1856 and 1904-1922 of `ea634043`); rows with no next command: 1393, 1526-1532, 5758 (`could not be run: {exc}`); only update-shape has a section in AGENTS.md | | D1-F9, D3-F7 | AGENTS.md:344-346, README.md:994-995, and the handbook beside it | after a bump the leg is left detached, and "`make bootstrap` in the root re-places it on its tracking branch AT the new pin; say so in your relay" (README.md: "`make bootstrap` re-places it on its tracking branch AT the new pin.") | AGENTS.md: "`make bootstrap` in the root puts it on its tracking branch AT the new pin, or says why not; relay which."; README.md and the handbook: "...re-places it on its tracking branch AT the new pin, or says why not." | templates/assembly-root/scripts/bootstrap.py at `ea634043`, `checkout_tracking_branch` (393-448): a branch behind the pin is fast-forwarded (275-340), and one ahead of it with no commit of its own is moved back (343-390, 177-187), both since #490 (`7348c57b`); a branch with commits of its own, or one that diverged, is not moved, and bootstrap prints `not moving an existing branch` (444-448); a commit made on the detached leg is left where it is, said as "which is neither" (313-322); a branch another worktree has checked out is not moved, and git's refusal is printed (226-228, 238-243) | | D2-F1 (part) | README.md:175-178, 217-220 | step 4's preflight "prints the command for THIS machine and asks once"; git commands are "the same commands that preflight offers to run for you" | "for `gh`, its login and its credential helper"; "the same commands `setup-project.py --preflight` offers to run" | setup.sh:85 (`command -v git ... \|\| die`, exit 2 by setup.sh:40) and :76; setup-project.py:1829-1831 (`bad(GIT_MISSING); die(PREREQ_MISSING)` ahead of `preflight(opts)`); the git offer (setup-project.py:926-932, rows 787-796) is reached only by `setup-project.py --preflight` (1820-1821); the `gh`, login and `gh auth setup-git` offers at 982-1078; run, no git on PATH: `openRepoShape --preflight` printed `REFUSED: git is not installed`, exit 2, no offer. The third place (README.md:434-436) is routed to #491 | | D2-F2 | README.md:181-183 | `openRepoShape --preflight` "exits 0 when everything is present and 1 when it is not" | "(`openRepoShape --preflight` exits 2 when `git` or a Python 3.9 or newer is missing)" | openRepoShape:446, 564 run setup.sh; setup.sh:76, 85 `die` (exit 2, setup.sh:40) before `preflight_only` (setup-project.py:1142-1166) | | D2-F3 | README.md:269-271 | "add `--visibility private` if you want that" | "`--visibility` defaults to `private`: add `--visibility public` (or `internal`) if you want that" | setup-project.py:428 (`self.visibility = "private"`), usage :138; scaffold-project.py:310-316; run: no `--visibility` printed `[ok] visibility private` | | D2-F4 | README.md:306-308 | the rehearsal leaves behind `./Atlas` and three bare repositories | "...and the scaffold's three working trees, in the temporary directory its `Working trees are at` line names" | scaffold-project.py:1570-1571 (`tempfile.mkdtemp(prefix="openreposhape-")`, never removed), 1611; run: `/tmp/openreposhape-q5eeici3` held `atlas atlas-code atlas-spec` | | D2-F6 | README.md:436-438 | "a hyphenated or lowercase name is refused here" | "a hyphenated project name is refused here" (the review's N1: `Atlas-spec` and `Atlas-code` are hyphenated and pass) | contracts/repository-naming.yaml:335-345 (`^[A-Za-z][A-Za-z0-9]*(?:-spec\|-code)?$`); run: `validate-repository-naming.py --explain atlas atlas-spec atlas-code` exit 0, `At-las` exit 1 `naming-unclassified`; the rehearsal for `atlas` ended `DONE. atlas is scaffolded and bootstrapped.` | | D2-F8 | README.md:573-574 | every other family "is CamelCase" | "from the neutral-product, domain-descendant and family forms, all of which are CamelCase words" | contracts/repository-naming.yaml:412 (`^[a-z0-9]+(?:-[a-z0-9]+)*-wip$`), 182 (`-Install` is hyphenated) | | D2-F9 | README.md:619-620 | the rewrite covers "both HTTPS and SSH leg URLs" | "both HTTPS and scp-form SSH (`git@github.com:`) leg URLs" | templates/assembly-root/.github/workflows/validate.yml:160-161 (two `insteadOf` rewrites) and :69-73 (`*) continue` skips any other spelling); run: `ssh://git@github.com/...` went to ssh unrewritten | | D2-F10 | README.md:625-628 | a leg under another owner "can only be reached via `SHAPE_LEGS_TOKEN`" | "`SHAPE_LEGS_TOKEN` is read only when the App is not configured, so that leg is reachable only with the App secrets removed" | validate.yml:146-154 (`if [ -n "$SHAPE_LEGS_APP_TOKEN" ] ... elif [ -n "$SHAPE_LEGS_TOKEN" ]`); run: both set printed `leg credential source: app` | | D2-F11 | README.md:680-682 | `validate-repository-naming.py --referent-chain openXdox,openDox` asks the same question for one name | `... --pins openXdox --referent-chain openXdox,openDox ...` asks "the same of one name" | scripts/validate-repository-naming.py:522-528 ("The first entry must be in `--pins`"); run: without `--pins`, `codexDox` classified `project-leg/assembly` (exit 0); with it, `domain-descendant` | | D2-F12 | README.md:687-689 | `--link-source [PRODUCT=]<path>`, env, or a checkout beside the root | `--link-source PRODUCT=<path>`, env, a checkout beside the root, then a bare `--link-source <path>` | scripts/repo_shape.py:2589-2621 (`resolve_link_source`, bare path 4th); templates/assembly-root/scripts/validate-pins.py:597-632 uses the same order | | D3-F1 | README.md:736 | "the only change to it is ONE split commit" | "the only change to its history is ONE split commit" | adopt-project.py:5355-5376 (`_set_the_topic` runs `gh repo edit <source> --add-topic` on all three), called at 5734; the topic is not history | | D3-F2 | README.md:764-765 | `plan` "writes it into `follow_ups:`" for every such file | "lists up to eight per directory in `follow_ups:`, counting the rest" | adopt-project.py:1329-1337 (`hits[:8]`, then `… and N more file(s) under the code leg naming ...`) | | D3-F3 | README.md:810-811 | the row reads `code: 0 of N source paths (seeded from template)` | the table's `code` row reads `0 of N source paths (seeded from template)` | as D1-F4; run: ` code 0 of 3 source paths (seeded from template)` | | D3-F4 | README.md:958-960 | `sorted-ls-tree-r-v1` records "joined with LF" | "each followed by LF, the last one included" | scripts/repo_shape.py:904-928 (`digest.update(record); digest.update(b"\n")`); run over `HEAD:templates/code-root`: LF-joined gave `f44766c9...`, LF-terminated and `tree_digest()` both `fca315e6...` | | D3-F5 | README.md:976 | `--dry-run` "prints the move and writes nothing", and (with #484) "`--dry-run` writes nothing, so it runs there" | "# --dry-run prints the move; it fetches into the leg and writes nothing else"; "`--dry-run` fetches into the leg and writes nothing else, so it runs there and prints that command" | scripts/bump-leg.py at `48585e62`: `fetch_leg` is called at :1453 (refspec `+refs/heads/*:refs/remotes/origin/*`, :854) and the `--dry-run` exit is at :1473, so the fetch comes first; the tool says so itself ("--dry-run: nothing was changed. The leg's object store was fetched into, which is how the digest above was computed", :1474-1477; docstring :447). Run (audit, offline): before the dry run the target object was absent from the leg and `origin/main` was f85673e; after it the object was present and `origin/main` was b9bce3e. #484 (landed) lets `--dry-run` run on the tracking branch (:1030 `and not dry_run`) and print `git switch -c`; it kept "writes nothing" at README.md:975 and in the refusal sentence, and the handbook (code comment and paragraph) says the same | | D3-F9 | README.md:1041-1044, AGENTS.md:285-288 | `check` prints `unchanged`, `upstream-changed`, `locally-modified` or `both` | "also `already-at-target` (the root has the target's bytes) and `upstream-removed`, `unmapped` and `copy-missing`; `apply` refuses the last three" (README; AGENTS.md appends the same four after `both`: `already-at-target`, `upstream-removed`, `unmapped` and `copy-missing`) | update-shape.py:239-256 (states, `CONFLICTS`, `ORDER`), 541-642 (`_classify_row`, `_row_verdict`) | | D3-F10 | README.md:1059-1063 | a `both` file "is refused outright" | "refused until a human merges it, commits the merge and re-runs with `--accept-local <path>`" | update-shape.py:2515-2535 (`_refuse_conflicts` excludes an accepted `both`), :1582 (`check` says "Merge it by hand, commit it, then `apply --accept-local <path>`"); run: `apply ... --accept-local Makefile` after the hand merge committed, exit 0 | | D3-F12 | README.md:1137-1139 | "every one that is not `ok` names the exact command that fixes it" | "a row that is not `ok` names the exact command that fixes it whenever there is one to run" | shape-doctor.py:1429, 3026, 5337 build `Row(..., None, ...)` with no fix; run: `--json` on a plain directory gave `contents n/a` with no next | | D3-F13 | README.md:1151-1153 | `COMPLIANT`: "every row ok"; one `SHAPE BEHIND` spelling; `DRIFTED`: "a copy was edited here, or a leg is off its pin" | "no row is a `FINDING`"; adds `(pin <a> -> <b>, no copied file differs)`; "edited, deleted or no longer maps onto the standard, or a leg (a member, in a holder) is off its pin" | shape-doctor.py:5942 (`COMPLIANT` is the end of the ladder, `n/a machine` is always there), 5875-5899 (`behind_verdict`), 5775-5795 (`drifted_file_reasons`), 5796-5824 (`drifted_reasons`) | | D3-F14 | README.md:1158 | "Exit 3 is usage or environment" | "Exit 3 is usage or environment (a flag argparse rejects is exit 2) — nothing about it is a statement about the tree you pointed at: no such path, a refused `--placement-plan`, a `shape-doctor.py` not sitting in a checkout of the standard, or a pin naming a commit **this** checkout does not carry (`CANNOT ANSWER`)" | shape-doctor.py:6029-6051 (plain argparse, exit 2), 6061-6082 (the exit-3 paths, among them `except Refusal: return 3` for the flag), 4547-4553 (`shape-doctor-no-placement-audit`), docstring :227 (`3 usage or environment`); tests/test_shape_doctor.py:5844-5858 asserts `returncode == 3`; runs: `--bogus` rc 2, `--root <missing>` rc 3, `--root <plain dir> --placement-plan pp.yaml` rc 3 | | D3-F15 | README.md:1273-1278 | bare `park` "PARKS EVERY ESTATE it finds" | "lists every estate ... and ASKS whether to park them all (with no terminal on stdin it refuses and names `--all`); `park --all`, or `-a`, parks them all unasked ... skipping a standalone root with no Speckit overlay (Brett Heap's RULINGs of 2026-09-10, the later superseding #91's unasked sweep)"; `resume` has no `--all` | openRepoTools `park` at GitHub's main `f87fd5a` (the review fetched it: nothing newer): header 17-41, usage 77-100, sweep skip at 802-808, `resume` refuses `--all` at 863-867; runs: bare `park </dev/null` outside an estate gave `REFUSED ... park --all parks every estate below without asking`, rc 2; `park --all --dry-run` gave `skipped Solo (no Speckit overlay)`, rc 0 | | MISPLACED (new, #394) | README.md:1176-1180 | `placement` "names the paths the policy would have put somewhere else" | "...and a submodule in a leg other than the one its `submodules:` record names" | since #394 (`7a8b981d`) a submodule in a leg other than the one `project.yaml`'s `submodules:` records for it is `misplaced`, counted in `MISPLACED`, exit 1: shape-doctor.py:3604-3624 (`recorded_placement`), 3754-3769 (`leg_submodules`); tests/test_shape_doctor.py:6770 (`test_a_submodule_in_the_other_leg_from_its_record_is_misplaced`), 7219. AGENTS.md already says it (#394's item 4). The verdict table's `MISPLACED` row sits directly above #468's `INVALID` row, so it is not edited here: #468 is asked for it | | N7 | AGENTS.md:259-262 (item 6) | "`openRepoShape --preflight` is what offers to install one" | "`openRepoShape --preflight` offers only the `gh` set-up" | the preflight never checks git-filter-repo (setup-project.py:1110-1135; openRepoShape:212-216) and setup.sh:85 exits 2 for a missing git before the preflight; the offers are `gh`, its login and its credential helper (982-1078) | `docs/handbook.html` repeats these and is corrected where it does: the preflight offers, `git` and the credential helper (four platform panels), the `openRepoShape --preflight` exit codes, the visibility default, the rehearsal leftovers, the CamelCase sentence, the credential rewrite and `SHAPE_LEGS_TOKEN`, the source repository's one change, the digest definition, `check`'s verdicts and the `both` refusal, the doctor's row sentence, verdict table and exit 3, the placement paragraph's submodule, and bare `park`. The handbook says more than the README in four places (the `git`-before-the-preflight sentences in the Linux panel, the Windows git offer "only under `py setup-project.py --preflight`", glosses for the three non-comparable `check` states, park "from anywhere"); all are true. Its footer's history prose gains "added (#483)". | finding | where | evidence at `71359744`, the merge of `48585e62` | |---|---|---| | D1-F8 | AGENTS.md:323-328, 337-339 | the block carries `git -C <path> switch -c <branch>` (AGENTS.md:335), item 3 says "A new project stands on its tracking branch; the dry run runs there and prints the `git switch -c`, but the real run is refused" (:348-349); scripts/bump-leg.py:1030 refuses on the tracking branch only `and not dry_run`; tests/test_bump_leg_dry_run_tracking.py | | D2-F7 | README.md:502-504 | README.md:502 `git -C ../Atlas switch -c <branch> # the tool will not commit on main` | | D3-F6 | README.md:974-977, 987-992 | README.md:988-991 "`git switch -c <branch>` first; `--dry-run` ... runs there and prints that command" | | D2-F13 | README.md:705-707 | #465 rewrote the sentence: README.md:705-707 now reads "Finding neither is a named SKIP, exit 0: no checkout and no network does not make a descent a lie. A checkout that cannot answer is the finding `neutral-pin-source-unreadable`", and the handbook says the same (1139-1141). True: a source that is found but cannot answer is a FINDING, templates/assembly-root/scripts/validate-pins.py:796; the SKIP is only "no source found and `gh api` fails" | | D2-F14 | README.md:708-709 | #465 deleted the whole sentence, so "a pin file the declaration names but that is not there, is reported as drift" is gone from README.md and the handbook (the missing file is the refusal `neutral-pin-missing`, validate-pins.py:699). It also dropped the true half, "A digest that recomputes differently is reported as drift" (the finding `neutral-pin-digest-mismatch`, validate-pins.py:853): not a false statement; see "Not holding #483 open" below | | D3-F8 | README.md:1028, 1095-1097 | #465 rewrote both: README.md:1027-1029 "a project runs its own gate, which never consults this standard (its validators' one possible network read is `validate-pins.py`'s `gh api` recheck of a neutral product's pin, above)" and :1095-1098 "That line adds no network call ... (Its pins gate may ask `gh api`; see above.)"; the handbook the same (1403, 1448). True: `validate-pins.py` falls back to `gh api` when no local checkout answers (scripts/repo_shape.py:931 `tree_digest_from_gh`) | Evidence is at `ea634043`, the merge of `70d0d1b3` with the D1-F9/D3-F7 correction; `9ac90d16` changes one README word in place and the footer blob, so the line numbers hold at this head. The runs are this round's, offline: local bare remotes, a stub `gh`, a blank identity. | finding | where | evidence | |---|---|---| | D1-F1 | AGENTS.md:22-24, 56-62, 78-80 | #491 reads the yes from the controlling terminal (setup-project.py:1322, `ask()` at 1325-1432; the confirmation at 1770-1779), and setup.sh hands the child the pipe (282-283). Run under a pty: the piped `cat setup.sh \| bash -s -- … --local-remote-dir …` asked `Type yes to continue:`, and `no` gave `REFUSED: not confirmed; nothing was created.`, exit 1. With no terminal at all (AGENTS.md:23, 83-86) it prints the plan and refuses (1770-1776): `REFUSED: this will create THREE repositories and there is no terminal to confirm on…`, exit 2 | | D2-F5 | README.md:315-336, 414-420 | the same read, for the README's three one-liner blocks | | D1-F2 | AGENTS.md:76-77 | #491 took the audit's text (AGENTS.md:73-75). `_choose_org` (setup-project.py:1244-1258) takes a fork's `origin` organisation (run: `[ok] organisation acmefork (from the \`origin\` remote…)`) and refuses opensoft's own without `--org` (run: `REFUSED: you are running from the upstream checkout (…); pass --org <your-org>.`, exit 2) | | D2-F1 (rest) | README.md:434-436 | #491's words, kept whole in the merge (README.md:432-445). The `gh` offers are the install (setup-project.py:992-1005, `INSTALL_OFFERS` at 795-798), the login (1009, 1015-1032) and git's credential helper (1051-1083, asked only once `gh` is ready, 1134-1137); git and Python are refused before any offer (setup.sh:76 and 85, exit 2 by :40). Run with no git on PATH: `openRepoShape --preflight` printed `REFUSED: git is not installed. Install it: https://git-scm.com/downloads`, exit 2, and offered nothing | | D3-F11 | README.md:1130-1133 | #468's sentence (README.md:1130-1134) names `agent files` for a holder and `machine` for a plain directory, as the doctor's `CHECKS` registry has them (shape-doctor.py:6115-6155, at 6135 and 6153). Run, `--json` on a plain directory: the rows naming, contents, way-in, machine | | `MISPLACED` table row (the review's) | README.md:1151, and the handbook's verdict table | #468's row reads "...or a submodule in a leg other than the one its `submodules:` record names" (README.md:1155, handbook:1509); shape-doctor.py:3843-3862, 3993-4008 | Every finding of the three audits is corrected above or settled by a pull request that has landed. A fourth read took what main changed in README.md and AGENTS.md since the audits' `ec4a7a0e` (#394, #484, #465, #468, #491: `git diff -U0 ec4a7a0 70d0d1b`), every line this branch does not itself rewrite, and asked the audits' question by their method. It found one false statement, D1-F9/D3-F7's own sentence as #484 kept it, corrected above, and checked the rest true: AGENTS.md 23, 63-67, 73-81, 83-86, 88-96, 155-158, 252-254, 335, 347-349 and 357-361; README.md 333-338, 343, 432-445, 503, 508, 699-709, 987-992, 1028-1033, 1095-1098, 1118-1136, 1155-1156 and 1163-1171 (line numbers at `ea634043`). Read in code only: the offers' real-GitHub paths and Windows (the real `gh` never ran). Not read: `park` and `resume`, which live in openRepoTools. **True but loose, left as they are.** AGENTS.md:83 and README.md:440 say a run with no terminal "stops after the plan"; a missing prerequisite stops it earlier, at the preflight (exit 2), which AGENTS.md:88 covers. README.md:1216-1218 says the machine check runs "with stdin closed"; the doctor also starts it in a session of its own (shape-doctor.py:1284-1285), which is what keeps the terminal out since #492. AGENTS.md's doctor item 3 does not say to ask the human which of #495's two `bump-leg.py --to` lines to run: an omission, not a false statement. **Outside these files.** `scripts/bump-leg.py:1513` still prints "re-places it on its tracking branch AT the new pin" after every bump. It is on #458's checklist with the rest of #490's follow-ups, and a docs-only pull request leaves it there. **Not holding #483 open: an omission.** #465 deleted "A digest that recomputes differently is reported as drift" together with its false clause. So README.md (698-709) and the handbook beside it no longer say what a recomputed neutral-pin digest that disagrees does. Nothing there is false, so it does not hold #483 open. Both files are at their caps, and the sentence needs about two more README lines that no untouched paragraph gives back, so it is not added here. Re-checked at `ea634043`: the finding is validate-pins.py:968-970 and 1140-1142 (exit 1), the refusal 814-816 and 1172-1175 (exit 2). A sentence for whoever next edits that paragraph: "A digest that recomputes differently is the finding `neutral-pin-digest-mismatch` (exit 1); a pin file the declaration names but that is not there is the refusal `neutral-pin-missing` (exit 2)." A robustness note on main's `test_the_documents_say_what_an_assistant_does_with_no_terminal` (#491): it strips `<...>` from README.md as well as from the HTML page, and a README line holding `<(` and no `>` swallows lines up to the next `>`; stripping tags from the `.html` page only would make that test indifferent to such a line. `git merge-tree --write-tree` of `ea634043` against the open pull requests that edit these files: clean with #503 (`6fe17be5`); #506 (`f184a51c`) and #486-#488's #507 (`708f3bbb`) each conflict in the handbook footer alone (its history prose and `README.md blob` line), and README.md and AGENTS.md merge clean with all three and stay at 1422 and 490 lines. Whichever lands later recomputes `git hash-object README.md` and keeps every "added (#n)" clause. #394, #484, #465, #468 (`57c85e92`), #490 (`7348c57b`), #508 (`aa4e1f59`) and #491 (`da197359`) are merged here. - At this head (`9ac90d16`): `tests/test_repo_hygiene.py tests/test_agents_md_codes.py tests/test_cli_reference.py tests/test_setup_project_py.py tests/test_setup_sh.py`, 277 passed; `scripts/validate-repository-naming.py --explain Atlas Atlas-spec Atlas-code` exits 0 (`project-leg`: assembly, spec, code) and `--explain At-las At-las-spec At-las-code` exits 1 (`FINDING naming-unclassified`), so only the project name's hyphen is refused. - At `ea634043`: `tests/test_repo_hygiene.py tests/test_agents_md_codes.py tests/test_cli_reference.py`, 122 passed (the same on the merge `94793aeb`); `tests/test_setup_project_py.py tests/test_setup_sh.py`, which read README.md and the handbook for #491's no-terminal route, 155 passed; `tests/test_free_plan_hint.py` with the AGENTS.md step 7 tests of `tests/test_adopt_late_failure.py` and `tests/test_adopt_github_exits.py`, 18 passed; and on the merge, `tests/test_bootstrap_after_bump.py`, 23 passed. A stub `gh` first on PATH (it logged no call), `GH_TOKEN` bogus, an empty `GH_CONFIG_DIR`, a blank identity. - `rvD-worddiff.py`, `rvD-hunks.py` and `rvD-mdstruct.py` over `ea634043` against its parent: four `WORDS CHANGED` hunks, all of them the D1-F9/D3-F7 sentence and the blob, and no re-wrap; block structure, links, HTML and code spans identical (README.md 678/678 blocks, AGENTS.md 322/322). The merge `94793aeb` against `70d0d1b3` changes the same lines as `83cfad54` against `aa4e1f59` (366 insertions, 336 deletions), apart from the two resolved hunks. - Review round four (the first reviewer, at `ea634043`): APPROVE WITH NITS (0 blockers, 0 should-fixes, 3 nits). - It ran `git show --remerge-diff` on every merge since round three (`71359744`, `fb6a9ab4`, `83cfad54`, `94793aeb`). Each hand resolution is a named conflict hunk, and no row, clause or fact was lost. - It reproduced the D1-F9/D3-F7 sentence with a real bump and `make bootstrap` in seven cases, and each placed the leg or said why not: a branch behind the pin; ahead with no commit of its own; with commits of its own; diverged; checked out in another worktree; a commit on the detached leg; a move a local change blocks. - It re-checked every routed row and ten moved-evidence rows, and read the whole of main's change since `ec4a7a0e`, finding nothing else false. - It ran the hygiene, codes, CLI-reference, setup, bootstrap-after-bump and free-plan tests: 314 passed. - Its nits: N1, the hyphenated project name, made at `9ac90d16`; N2, a run with no terminal stops at the preflight rather than after the plan when something is missing, which AGENTS.md:88 covers; N3, this description. - Two `bootstrap.py` defects it met while reproducing are on #458's checklist (issuecomment-6142614866). - At `83cfad54`: `tests/test_repo_hygiene.py tests/test_agents_md_codes.py tests/test_cli_reference.py`, 119 passed. On `fb6a9ab4`, the merge of `57c85e92`, the same three gave 119 passed, and `tests/test_shape_doctor.py tests/test_doctor_unfinished_merge.py tests/test_free_plan_hint.py tests/test_openreposhape_command.py tests/test_shape_advisory.py` gave 465 passed, 3 skipped (the doctor's PowerShell line, which prints only on a Windows host). The table's "no row is a `FINDING`" holds with the `merge` row: `shape-doctor.py` returns `COMPLIANT` only at :6171, after :6168-6170 answer `INVALID (<ids>)` for any `FINDING` row, and `merge` is a `FINDING` only for an unmerged path (:5879; a merge with none left is a `note`, :5862). All runs with a stub `gh` first on PATH, `GH_TOKEN` bogus, an empty `GH_CONFIG_DIR`. - At `71359744`, the merge of `48585e62`: the three files, 119 passed (a stub `gh` first on PATH, `GH_TOKEN` bogus, an empty `GH_CONFIG_DIR`; the stub logged no call). - The same three files on a throwaway merge of `f35e59fa` with #491's head (merge-tree, commit-tree, a detached worktree, footer resolved, then removed): 122 passed, and `tests/test_setup_project_py.py tests/test_setup_sh.py -k no_terminal`: 8 passed. The failure the second review found (`test_the_documents_say_what_an_assistant_does_with_no_terminal[README.md]`, 1 failed, 122 passed) came from the `bash <(` lines this commit removes. - `tests/test_adopt_late_failure.py::test_agents_md_step_7_names_the_exit_the_tool_prints` and `tests/test_adopt_github_exits.py -k "step_7 or agents"` (round two, on `ccf520bd`): 2 passed; they read AGENTS.md step 7, which is untouched. - `rvD-worddiff.py`, `rvD-hunks.py` and `rvD-mdstruct.py` over the third commit against its merge parent: every changed region is one of the corrections above (the `bash <(` blocks back to main's text, D3-F5, the park parenthetical, the placement sentence and the three word trims), and the two `WHITESPACE-ONLY` hunks are the family steps going back to main's bytes; block structure 320/320 and 678/678, links, HTML and code spans identical. - No test greps a phrase this pull request changed: the old phrases appear under `tests/` only in history comments and the doctor's docstring. The third head (f35e59f) was re-verified: APPROVE WITH NITS (0/0/4), all four in this description and fixed there. Main 48585e6 (#465) was then merged as 7135974, and 57c85e9 (#468) as fb6a9ab; aa4e1f5 (#508) merged clean as 83cfad5. Main 70d0d1b (#491) was merged as 94793ae, and ea63404 corrects D1-F9/D3-F7. A fourth review round at ea63404 covered every merge since f35e59f (remerge-diff: no row, clause or fact lost), the bootstrap sentence in seven reproduced cases, and the whole docs delta since ec4a7a0: APPROVE WITH NITS (0/0/3), and #483 can close. Its N1, "a hyphenated project name", is 9ac90d1. CI is green on Linux, macOS and Windows, with SonarCloud passing, at 9ac90d1. Main cc8f2da (#376), which landed after its last merge, touches none of its files, and the combined tree passed the docs and setup tests (277 passed). Closes #483 Lane: openreposhape-5 (openRepoShape-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

… 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) Brett Heap ruled on 2026-10-12: "quote #259". The templates now write each text field a tool fills from a value it was given between double quotes: | template | fields | |---|---| | `templates/assembly-root/project.yaml` | `id`, `elected_on`, `visibility`, `tracking_branch`, the spec leg's `path`, the code leg's `path` | | `templates/assembly-root/contracts/spec-pin.yaml`, `code-pin.yaml` | `submodule_path` | | `templates/family-root/family.yaml` | `id`, `org`, `created_on`, `visibility`, `tracking_branch` | `render` already spells a value between a YAML template's double quotes with `repo_shape.double_quoted` (#284). The single-pass `render` from #316, on main as 34ecbc2, does the same through `YAML_PLACEHOLDER_RE`. So each value reads back exactly. An ordinary value renders as it did before, plus the two quote characters. `family.yaml`'s `org:` is quoted along with the four fields #259 names. It is the same defect in the same file: `family.py init --org 2026` and `--org null` pass `checked_value`, and on c7c02fa the holder then fails `family-org` (#307 lists the `--org null` row). Taking `org:` back out is not a one-line revert. It fails 14 of the new tests (the 8 `family.yaml:org` in-memory cases, and all 6 `family.py init` rows, because every row of `FAMILIES` passes a misread `--org`), and it would also take the `ORG` row out of `TEXT_FIELDS` and put plain `--org` values into `FAMILIES`. The lane keeps `org:` quoted, as the same defect in the same file, unless Brett says otherwise. `scripts/family.py`: `_member_lines` writes each member's own `project.yaml` id into the holder's `members:` block. That id now reads back exactly, so a bare `007` in the row came back as 7, and `validate-family.py` would report `member-id-mismatch` for a member it had just pinned. `_member_id` quotes an id only when the reader would not read the bare text back as the same text. No row whose id reads back as text moves: `irrs` is still `id: irrs`. Two edges: - A legacy row whose bare id the reader misreads moves once. A holder written before this change, by `family.py add` of a member scaffolded with `--id 2026`, holds `id: 2026`. The next `bump`, `add` or `remove` of that holder rewrites it as `id: "2026"`. That is harmless: `validate-family.py` compares with `str()` and passes before and after. - Mixed versions. A `family.py` from before this change, run against a holder this branch wrote, turns `id: "007"` back into `id: 007`, and `validate-family.py` then fails `member-id-mismatch` (the member declares `007`, `family.yaml` records `7`). A current `family.py` that rewrites the holder next then writes that row as `id: "7"`. Nothing in this branch can prevent it: run `family.py` from a current checkout on a holder that has such a member. Left unquoted on purpose: `topic` (`xf-project-<id>`), every `repository` (`<org>/<Name>`; the slash keeps it text), `SHAPE_REPOSITORY` and `DIGEST_DEFINITION` (constants), and the block or list placeholders (`NEUTRAL_PRODUCT_PINS`, `*_NAMING`, `SHAPE_FILES`). **Why.** Every reader of these files uses `repo_shape`'s YAML subset. It reads a bare `007` as 7, `2026` and `20261011` as numbers, `1.5` as a float, `true` as True and `null` as None. The checks on the flags (`PROJECT_ID_RE`, `checked_value`, the leg-path rule) accept every one of these. Reproduced on c7c02fa, with local bare remotes only: - `scaffold-project.py --id 2026|007|true|null|20261011` exits 0, and the project's own `validate-manifest.py` then fails `manifest-id`. - `--spec-path 2026 --code-path 007` fails `manifest-leg-path`, and `validate-pins.py` exits 2. - `--tracking-branch 007` pushes each leg on `007`, and the root's `bootstrap.py` then puts the legs on a local `7` with `fatal: no upstream configured`. `true` and `null` do the same on `True` and `main`. - `adopt-project.py execute` with `--tracking-branch 007` does the same; `--id 007|20261011` gives `manifest-id`; leg paths `2026`/`007` give `manifest-leg-path`. - `family.py init --id 2026|007|true|null|20261011` gives `family-id`; `--org 2026|null` gives `family-org`; `--tracking-branch 007|true|null` reads back as 7/True/None. On this branch every one of those rows reads back as typed, bootstraps onto the typed branch with `origin/<branch>` as upstream, and passes the root's own validators. **Every reader checked.** Every reader reads these fields through `load_yaml`/`parse_yaml` into a dict. None uses a line regex, `split(":")`, `startswith("<field>: ")` or a whole-line rewrite of them: - `templates/assembly-root/scripts/bootstrap.py`: `tracking_branch`, leg `path`. - `validate-manifest.py`: `id`, `elected_on`, `visibility`, leg `path`. - `validate-pins.py`: `submodule_path` against the manifest's `path`. The pin side is read as it stands and the manifest side goes through `str()`, so the two differ in type exactly when a bare value is misread (that is the `pin-path-mismatch` row above). With both lines quoted they are the same text. - `validate-repository-naming.py`: `str(id)` for the topic. - `templates/family-root/scripts/validate-family.py`: `id`, `org`, `created_on`, `visibility`, `str()` member-id compare. - `siblings.py`, family `bootstrap.py`. - `scripts/bump-leg.py`: `tracking`, leg `path`. Its `rewrite_pin` rewrites only `commit:` and `tree_sha256:`. - `update-shape.py`: `tracking_branch_of`. `rewrite_manifest` touches only the `shape:` block. - `scripts/family.py`: `tracking()`, the member's id, and the `members:` rewrite. The member-id writer is the one fixed here. - `shape-doctor.py`: leg `path`, member row `path`, working-clone `str(id)` compare. - `adopt-project.py`: plan reads and `_template_values`. - `setup-project.py`: `family.yaml` `name`/`kind` only. - `scripts/shape_advisory.py`: the single-repository record only. The `str()` fallbacks (`bootstrap.py`, `adopt-project.py`'s `checked_value`) stay, because projects made before this keep their bare lines. **Pins.** The four files are TEMPLATED, not COPIED, so no row of any project's `contracts/shape-pin.yaml` names them. `Atlas` was scaffolded and `family.py init Contoso` was run on c7c02fa and on this branch. Each `contracts/shape-pin.yaml` differs only in `commit:` and `digests.tree_sha256`, which identify the standard itself and change with every commit; every per-file `sha256` row is identical. `update-shape.py check` of the c7c02fa project and holder against this branch reports every copied file `unchanged` (11 and 10 rows): "no copied file differs; `apply` would move the pin alone". **Tests.** - New: `tests/test_template_text_placeholders.py`, 123 tests: - Each of the 13 fields is rendered with each of 8 values the reader misreads (`2026 007 1.5 true null 20261011 ~ False`), and must read back exactly. - 6 `scaffold-project.py` runs, then a recursive clone, `bootstrap.py`, the three validators, and `bump-leg.py`, which refuses on the tracking branch and finds the leg at its path on a branch of its own. - 6 `adopt-project.py` `plan`/`check`/`execute` runs into local bare remotes, then a clone, `bootstrap.py` and the validators. - 6 `family.py init` runs. - One `family.py add` of members whose ids are `007` and `true`. - **All 123 fail on c7c02fa.** - `true`/`null` through adopt: `plan` writes them bare into the plan, and the plan's reader then misreads them. That belongs to the plan writer, #181 (lane 1). Those two rows quote the value in the plan by hand, as #181's writer will, and test `check`/`execute`. - Mutation probes: reverting any one of the 13 quoted lines fails 8 cases of its field. Reverting `_member_id` fails the member test (the rows read 7/True). - The `try/except YamlError` in `_member_id` is guarded by the follow-up commit. The review found that calling the parse directly left the member test passing. Ids such as `[`, `{`, `&a`, `*a` and `!t` reach the `except` (they raise `YamlError` bare), and `_member_id` returns each one exactly, as it does 34 adversarial inputs in all (the review's in-process probe). `test_a_member_id_the_reader_refuses_bare_is_rewritten_between_quotes` (7 cases: `[`, `{`, `&a`, `*a`, `!t`, an unclosed `'` and an unclosed `"`) opens a hand-edited holder whose row holds the id between double quotes, rewrites the `members:` block with `Family.rewritten`, and asks that the id read back exactly and the text come out byte for byte. With the `try/except` removed all 7 fail with the reader's `YamlError`, and with the `except` returning the bare text all 7 fail too; the old member test still passes under the first of those mutants. - 14 existing tests that asserted or edited a bare rendered line now spell it quoted: `test_manifest_validator` ×5, `test_pin_validator`, `test_reference_default`, `test_scaffold_e2e` ×2, `test_setup_project_py`, `test_setup_sh`, `test_family`, `test_shape_doctor` ×2. - Targeted runs on this branch: | files | result | |---|---| | new file + `test_template_quoted_values`, `test_scaffold_e2e`, `test_scaffold_pin_and_reuse`, `test_scaffold_leg_paths`, `test_scaffold_leg_path_collisions`, `test_reuse_visibility`, `test_reference_default` | 405 passed | | the six adopt files | 491 passed, 1 skipped (the MedxEHR clone is not set) | | `test_family`, `test_family_add_refusals`, `test_family_member_path`, `test_manifest_validator`, `test_pin_validator`, `test_bump_leg`, `test_update_shape`, `test_update_shape_pr_base`, `test_setup_project_py`, `test_park_resume_targets`, `test_repo_hygiene`, `test_cli_reference`, `test_setup_sh` | 603 passed | | `test_shape_doctor` | 241 passed, 3 skipped (Windows-only), 1 failed; that one test was fixed, and with its sibling it reran at 2 passed | **The review.** An independent opus review at 233dc71 (the branch's first commit) found no code defect. Its verdict was CHANGES NEEDED (0 blockers, 2 should-fixes, 6 nits) because it asked for this description and its composition counts to be corrected, and they are. Its evidence: - **Readers and rewriters.** Every reader in the shipped tree reads the 13 lines through `load_yaml`/`parse_yaml`, and no line regex or whole-line rewrite touches them. It read `bump-leg.py` `rewrite_pin`, `update-shape.py` `rewrite_shape_pin` and `rewrite_manifest`, `family.py` `rewritten`, the three validators, `siblings.py`, both `bootstrap.py`, the doctor, `setup-project.py`, the workflows, the Makefile and `setup.sh`. No test among main's 17 commits since c7c02fa (through #245's 161c6c9) edits one of these lines bare. - **`_member_id`, the one rewriter changed.** A mutant that writes every id bare fails the member test (the rows read back as `{'IRRS': 7, 'IRSS': True}`). A mutant that quotes every id fails `b" id: irqs" in lines`. So the minimal-churn choice is tested both ways. - **Old projects and holders.** Against a control commit (c7c02fa plus an unrelated README edit), a project and a holder made on c7c02fa give identical `update-shape.py check` and `shape-doctor.py` output, up to the shas. `check --at 233dc71` reports all 11 project files and all 10 holder files `unchanged` and says `no copied file differs`. The doctor's verdict is `COMPLIANT, SHAPE BEHIND (... no copied file differs)` for the control and for 233dc71. This branch's `family.py add` and `bump` on a c7c02fa holder leave the old `atlas` row and the header byte for byte, apart from the legacy-id edge described at the top. - **Tests.** All 123 new tests fail on c7c02fa (`123 failed`) and pass on 233dc71 (`123 passed`). The 14 changed existing tests pass (49 passed). - **Not covered.** Windows and macOS were reviewed by reading and not run: the plan edit and the member-row check are in bytes, and nothing writes to git's stdin in text mode. Of `test_shape_doctor.py` and `test_family.py` the review ran only the changed tests. **Follow-up commit.** A second commit, `3894aa8`, answers two nits from the review, and changes no behaviour. The `_member_id` docstring said "no existing holder's `members:` block moves by a byte", which was false: the next `bump`, `add` or `remove` of a holder written before this change rewrites a legacy `id: 2026` row as `id: "2026"`, harmlessly, because `validate-family.py` compares with `str()`. The docstring now says exactly that, and a grep of every comment and docstring the branch added for "by a byte" and "moves" found one more copy, in the member test's docstring, corrected the same way. The `try/except YamlError` in `_member_id` is guarded by a new test (see Tests), so the new file holds 130 tests. Every count above that says 123 (123 new tests, all failing on c7c02fa and passing on 233dc71) is for the first commit; the follow-up commit adds the 7. The `except` also carries a comment saying which ids reach it. **Composition at the landing head (4984651).** `49846518` is GitHub's update-branch merge of origin/main `cc8f2da4` (#376, a `--trailer` value carried into the commit as typed) into `3220c9ee`. Git reported no conflict, and the merge has no hand edit. #376 changed `scripts/family.py` and `tests/test_family.py`, which this branch also changes. None of the lines it added under `tests/` names a key the templates now quote. The coordinator ran targeted tests on this head, Linux only, before CI: - main's changed test files (`tests/test_commit_trailers.py`, `tests/test_family.py`, `tests/test_bump_leg.py`, `tests/test_update_shape.py`) with `tests/test_family_add_member_id.py`: 421 passed, 1 skipped (a case-insensitive disk only); - this branch's template set (`tests/test_template_text_placeholders.py`, `tests/test_template_quoted_values.py`, `tests/test_scaffold_manifest_values.py`, `tests/test_bootstrap_spelling.py`, `tests/test_bootstrap_after_bump.py`) with the hygiene, CLI-reference and AGENTS.md-codes tests: 652 passed. **Composition at 3220c9e.** `3220c9ee` is GitHub's update-branch merge of origin/main `70d0d1b3` into `e5e768bc`. It brings in three commits: #491 (da19735), in which `setup-project.py` asks at the person's own terminal; #374 (7ab11cf), update-shape's NEXT quoting; and #384 (70d0d1b), adopt's `_spelled` plan values. Git reported no conflict, and the merge has no hand edit. #491 changed `tests/test_setup_project_py.py` and `tests/test_setup_sh.py`, which this branch also changes. A grep of the lines main added under `tests/` for the keys the templates now quote found two hits, and neither reads a rendered template line: `tests/test_update_shape_next_quoting.py` writes its own `project.yaml`, and `tests/test_adopt_question_and_submodule_spelling.py` edits a plan's `- path:`/`question:` entry, which `adopt-project.py` writes bare. The coordinator ran targeted tests on the same tree (`e5a74d19`), Linux only, before CI: - six of main's eight changed test files (the setup, update-shape, `openRepoShape` command and doctor-row tests): 365 passed; - main's other two (adopt's spelling and repo hygiene), `tests/test_adopt_github_exits.py` and nine more files of this branch's sixteen-file set: 943 passed. **Composition, refreshed again 2026-10-13 (head e5e768b).** `6d108d18` merges origin/main `56713e21` into `6cbbac60`. That brings in two commits: 5e02abe, the doctor's and `validate-pins.py`'s gitlink repairs, and 56713e2 (#479), in which adopt's `plan` takes the tracking branch from the source's default branch. Git reported no conflict and `docs/cli.md` auto-merged; the merge has no hand edit. Two kinds of test failed on it, and two commits fix them: - **`7968f902`** changes one expected literal, at `tests/test_adopt_github_exits.py:675`, for `test_a_source_on_another_branch_opens_its_pull_request_against_it[master]` and `[trunk]`. - The test reads the adopted root's `project.yaml`, which this branch's template renders as `tracking_branch: "master"`, so it now expects the quoted line. - The look-alike lines at `:743` and `tests/test_adopt_tracking_branch.py:73-76` read a plan, which `adopt-project.py` writes bare, and they stay as they are. - **`e5e768bc`** adds `git("branch", branch, cwd=source)` to `tests/test_template_text_placeholders.py::test_an_adoption_reads_back_every_value_it_was_given`. - All six rows had failed at `check` with `plan-tracking-branch-missing`: #479 refuses a tracking branch (`2026`, `007`, `1.5`, `20261011`, `true`, `null`) the source does not have, and the test's source had only `main`. - The source now carries each row's branch, in the flag rows and the by-hand rows alike. The test's assertions are unchanged. Targeted runs, Linux only: - On e5e768b: main's seven changed test files, 211 passed; this branch's sixteen-file set, 1223 passed, 2 skipped. - On 7968f90: the same sixteen files gave 6 failed, which are the six rows e5e768b fixes. The scaffold, setup, doctor and family set gave 1094 passed, 22 skipped, and twelve further template-grep files gave 1259 passed. - `render-cli-reference.py --check` is ok. **Composition, refreshed 2026-10-13 (head 6cbbac6).** `d651b594` merges origin/main `aa4e1f59` (#508) into `d526f768`. - **The one conflict.** Git conflicted in one file, `tests/test_adopt_manifest_values.py`, in four hunks, all against #356 (965420b, #293/#294). #356 refuses an `elected_on:` that `election_date` does not read, as `election-date-malformed`, before the validator is asked (`_manifest_values` returns None, adopt-project.py:2258). - **Resolved by what the merged tree prints**, measured with `adopt-project.py plan`/`check`/`execute` into local bare remotes: - `id: "007"` checks clean and `execute` writes it as typed, so it stays in `TEXT_THE_TEMPLATE_NOW_HOLDS`. - `visibility: "true"` gets the validator's `manifest-visibility: visibility is 'true'`. - `elected_on: "20261011"` gets #294's one finding, "the plan's `elected_on:` is the text '20261011'", and the validator is not asked. That row keeps this branch's list, `TEXT_THE_VALIDATOR_REFUSES`, with main's sentence. - Two tests git merged cleanly now ask `said_of`, as main's own rows do: `test_check_refuses_a_text_value_the_validator_refuses` and `test_where_a_misread_rule_judges_the_rest_the_validator_still_answers`. - **Two more failures that no hunk showed**, fixed in the same merge: - `[branch-tilde]` in `tests/test_scaffold_manifest_values.py` was this branch's own `xfail(strict=True)` until #355 landed as 6c2a371, so it XPASSed. The mark is off, and the row asserts `REFUSED scaffold-bad-tracking-branch:`. - #391's `tests/test_bootstrap_spelling.py` and #490's `tests/test_bootstrap_after_bump.py` matched ` path: spec` and `tracking_branch: main` in a scaffolded `project.yaml`, and nine cases failed on the merge. They now match the quoted lines. - **The #507 interplay.** `6cbbac60` switches the holder to `family/members` before the real `add`s in `test_a_member_whose_id_yaml_would_misread_is_pinned_under_that_id`, so the test holds once PR #507's `family-on-tracking-branch` refusal lands. - On the clean merge of 6cbbac6 with #507's head 708f3bb, that file, all 13 `tests/test_family*.py` and `tests/test_shape_doctor.py::test_a_sibling_at_the_right_origin_with_another_id_is_not_the_member` give 686 passed, 19 skipped. - Without the switch line, the member test fails `REFUSED family-on-tracking-branch`. - **Targeted runs on 6cbbac6, Linux only:** - the template, adopt-plan and manifest files (14): 995 passed, 2 skipped; - scaffold e2e, setup, the doctor, leg-path collisions and every family file: 1094 passed, 22 skipped; - the 15 further files a grep for template lines found: 1503 passed; - `render-cli-reference.py --check`: ok. - **Re-verified independently** at d651b59 and 6cbbac6: APPROVE WITH NITS (0/0/3), all three in this paragraph and fixed here. The re-verification also ran the three rows, five mutations, and 26 more files (834 passed; 291 passed, 1 skipped). - **Not run locally:** the full suite, macOS and Windows; CI's three jobs are the check. **Composition, as measured on 2026-10-12.** The merge trees below were computed for 233dc71; the follow-up commit 3894aa8 changes only `scripts/family.py` comments and adds tests. At 15:28Z main was 3ae0109 (#245, #351, #350 and #345 had landed since the merge trees): 3894aa8 merges clean with it, and the review's re-verify ran the family tests on that merge (61 passed). Every sha below is the one it had then; main and the other branches have moved since. `git merge-tree --write-tree --name-only`, run after a fetch with automatic maintenance off on 2026-10-12: - **origin/main 161c6c9**, 17 commits past c7c02fa (the base): clean, tree 7ba8246. #316 (34ecbc2), #317, #318, #311 and #245 were on main by then. - **The 46 other remote branch heads** (the 30 open PR heads and 16 branches with no open PR): clean for 44. Among them #314 (4b8da3d), #266 (3410be7), #355 (a03abcf), lane 1's `fix/adopt-plan-quote-yaml-keywords` (d38e143), `fix/adopt-record-submodule-placement` (70f4d29) and `fix/adopt-late-failure-notice` (9f1778d), #380 (73068a3), and `fix/family-init-values` (14e2d68, #307). The two that conflict, each in the same file as it does with c7c02fa and with origin/main on its own: lane 1's `fix/adopt-root-kept-symlinks` (6c44591, `adopt-project.py`) and #358 `fix/doctor-manifest-kinds-unreadable-pin` (ebffb08, `shape-doctor.py`). This branch touches neither file. - #314 and d38e143 each conflicted with origin/main on their own, in `adopt-project.py`. Merged with this branch, neither gained a conflict. **Composition with #314, which lands before this branch.** Its misread gate (`manifest_misreads`) reads the template, so once the template quotes a field it refuses nothing there, and some of #314's tests expected that refusal. Composing with #314 (landed as 3ef059c), whose misread gate asks the template how a value is written. With `project.yaml` quoting `id`, `elected_on`, `visibility` and `tracking_branch`, the gate refuses nothing on the shipped templates, and 45 of #314's tests flipped on the merge. Forty expected a refusal the value no longer needs. Thirty-four of them now assert that the value is accepted, and the six whose premise was a bare placeholder now assert that no shipped template placeholder is misread. For example: a scaffold of `--id null|true|false|007|2026`, or of `--tracking-branch true|True|TRUE|false|False|null|Null|NULL|007|2026|1.5|1.50|0`, exits 0, and the manifest holds the text it was given. A dry run prints the plan. An id derived from `--project True|Null` is held as typed. `--id=null` reaches `gh repo create`. Adopt's `id: "007"` checks clean and `execute` writes it as typed. The rule's own sentence, remediation and line-break wording are still asserted, on a copy of the standard whose `project.yaml` writes the four lines bare. Four stay refused by #314's validator gate, now in its words about the text: `visibility is 'true'` and `elected_on is '20261011'`. One is a real break. `--tracking-branch=~` reads back as `~`, which git refuses as a branch name, and it dies at `git init -b ~`, after `gh repo create`. That is #283, so the row is `xfail(strict=True)` with that reason, and it turns XPASS (and fails) once PR #355's `git check-ref-format --branch` refusal lands. `--help` for `--id` and `--tracking-branch` no longer says such values are refused, and `docs/cli.md` is regenerated. **Composition with the other branches.** Where another branch's rules meet this one, the tests were run on the merged tree. Quoting changes what some of their tests see, and the changes are not all one kind: some tests expected a refusal the value no longer needs, some are still refused under another rule, and some guard a case quoting does not fix. Whoever lands second must tell them apart, so each branch's flips are classified below. - **#266** (lane 2, `fix/leg-path-yaml-scalars`). 27 flips, all from one cause: its rule asks a hard-coded bare line, `LEG_PATH_LINE = "path: {}\n"`, so it refuses leg paths the quoted templates now read back. 15 are `test_the_rule_agrees_with_every_template_line_that_holds_a_leg_path` (null, Null, NULL, ~, true, True, TRUE, false, False, FALSE, 2026, 007, 0, 1.5, 1.50) and 12 are this branch's own end-to-end tests (6 scaffold rows fail with `REFUSED scaffold-bad-leg-path`, 6 adopt rows with `FINDING plan-bad-leg-path`). Counted on the merge with b2b42f8. #266's head was then 3410be7, whose rule reads each template line that holds a leg path, renders the value into it as `render` does and asks the reader, so it has no hard-coded line left. The merge with this branch was clean (tree 1e348c6); that head was read and the 27 were not re-run on it. At b2b42f8, whichever of #266 and #259 landed second had to drop or re-point the bare rule; 3410be7 re-points it already. - **Lane 1's #181** (`fix/adopt-plan-quote-yaml-keywords`, d38e143). Its gate reads the template too, so `plan --tracking-branch 2026|007|true` exits 0 on the composed tree (exit 2 `adopt-manifest-misread` on d38e143). On the merge, `tests/test_adopt_plan_yaml_quoting.py` and this branch's 6 adopt end-to-end tests give 70 failed, 371 passed: - 57 refusals that are now unnecessary: `plan_refuses` ×14, `plan_names_an_id` ×2, `check_names_an_id` ×4, `check_reports` ×14 and `execute_refuses` ×14 (every value except `elected_on` and `visibility`), `text_the_loader_reads_as_other_text` ×7, and the two tests that need a bare placeholder (`test_the_gate_follows_the_loader_when_the_loader_learns_a_keyword`, `test_the_template_line_says_whether_a_value_is_quoted`). - 11 guards #181 loses. See "Do not flip". - 2 that fail only by cascade: `execute_refuses[pins='null']` and `[pins='True']` pass alone (`2 passed`). An earlier case no longer refuses, and its `execute` pushes the split branch. - The writer half of #181 (`y` asking the reader, so `true`/`null`/`True` are quoted in the plan) is still needed and composes cleanly. With it, `plan --tracking-branch true` reaches the quoted template intact, and this branch's two hand-quoted adopt rows become flag-driven. - **Do not flip these 12 to "accepted".** Each still needs a refusal or a finding, and quoting does not supply it: - **`~` (1, #314).** `test_a_value_the_reader_misreads_is_refused_before_anything_is_made[branch-tilde]`. `--tracking-branch=~` is not a branch name git accepts, and #314 refused it only as a misread. On the merge it passes the plan and dies at `git init -q --bare -b ~ .../Atlas-spec.git` with `fatal: invalid initial branch name: '~'`, and against GitHub that is after `gh repo create` has made all three repositories. That is lane 2's #283 (PR #355). `~` must stay refused, by #283's ref-name check, which is why #314's row for it is not flipped to "accepted". - **A hand-edited plan value that is not text (7, #181).** `test_check_names_a_plan_value_that_is_not_text_by_what_was_read[tracking_branch='007']`, `[tracking_branch='TRUE']`, `[tracking_branch='1.50']`, `[tracking_branch='[a]']`, `[visibility='{a: b}']`, `[id='007']` and `[elected_on='20260902']`. The plan's reader reads each as something other than text, and on the merge `check` passes. Measured on the merge: `tracking_branch: 007` and `id: 007` are adopted silently as `"7"` with every validator passing; `visibility: {a: b}` pushes both legs and then fails `manifest-visibility`; `tracking_branch: [a]` is still refused at `execute` (`unsafe-value`) before any leg exists. On d38e143 alone, `check` exits 1 `plan-manifest-misread` for each of those four. Re-point the gate at "a plan value that is not a string" and these keep their guard. - **A quoted value the validator refuses (4, #181).** `test_check_reports_a_plan_carrying_one[elected_on='20260902']` and `[visibility='true']`, and `test_execute_refuses_a_plan_carrying_one_before_any_leg_exists[elected_on='20260902']` and `[visibility='true']`. The value stays invalid for the validator (`DATE_RE`, the visibility choices), and #181's misread gate caught it only incidentally. On the composed tree `check` passes and `execute` pushes the legs, and the gate fails afterwards. That is what main does today, and #314's validator gate (`plan-manifest-invalid`) would catch it. - **main** (merge with ab623dd, tree cdeec7f, run by the review): this branch's new file, `test_adopt_template_values.py` (#270), `test_template_values_single_pass.py` (#316) and `test_template_quoted_values.py` give 431 passed, 1 skipped. The skip is `test_adopt_template_values.py:223`, which reads `git config user.name` and skips where the shared repository's `.git/config` sets one; it is environmental. The changed tests with `test_family_add_refusals.py` (#317, #318), `test_pin_validator.py` and `test_manifest_validator.py` give 132 passed. #270's `unwritable_reason` is value-based, not template-relative, so it refuses as it did and nothing flips. Main then added #245 (`adopt-project.py` and `repo_shape.remote_key`), which adds no test that edits a bare quoted line; it was not run on that merge. - **#380** (lane 3, `fix/pin-rewrite-indentation`; it landed since as 1f90a0f). It rewrites `commit:` and `tree_sha256:` only, and its tests render the pins from the templates. On the merge at dc0fa7b, `test_pin_rewrite_layout.py` and the 6 scaffold end-to-end tests gave 121 passed. Its head was then 73068a3; that merge was clean and was not re-run. - **#397** (`fix/family-init-values`, #307; measured at 14e2d68): its tests skip themselves where the template quotes. 137 passed, 19 skipped, 0 failed. With its fix-round head abb27e6, this branch's 3894aa8, main 0f67f7b and #345 together: 442 passed, 20 skipped (the 19 rows, and one Windows-only row). - **#345** (run at 875d802; it has since landed as 3ae0109): `test_family_dry_run.py` and the member test, 22 passed. Its `" id: irrs"` assertion holds, because ordinary ids stay bare. **Left out.** - The adoption plan writer `y` still writes `true`/`null` bare into the plan. That is #181 (lane 1). - `templates/assembly-root/contracts/neutral-product-pin.yaml` still writes `product`, `source_repository` and `digest_source` bare, and `family.py` writes a member row's `project:` bare. Neither is a #259 field. - A plan value someone edits to a non-text type (`tracking_branch: 007` or `id: 007`, unquoted, in the plan) is read by the plan's reader as the number 7. `str()` makes it `"7"`, and the quoted template now writes it faithfully. For `id` this is a change: on c7c02fa a bare `id: 007` failed loudly (`validate-manifest: manifest-id`, manifest line `id: 7`), and on this branch it is adopted silently as id `"7"` and every validator passes. `tracking_branch: 007` was already adopted silently as `7`. The plan side is not this branch's: the guard against it belongs with #181 (adopt plan writes YAML keywords and non-text values unquoted), whose gate should refuse a plan value that is not a string. The case is narrow, because `plan --id 007` itself writes `id: "007"`; only a hand edit reaches it. - No docs change: README, AGENTS.md, the handbook and the template comments show none of these lines; `docs/cli.md` is unchanged because no `--help` text changed. Reviewed adversarially at 233dc71 (CHANGES NEEDED: 0 blockers, 2 should-fixes, 6 nits; the code and the tests were sound, and the should-fixes were the composition counts and the claim about a hand-edited plan `id`). Fix round 3894aa8 changes no behaviour: it corrects the description and the two false "moves by a byte" claims, and guards `_member_id`'s `except YamlError` with a test of 7 cases. Its re-verification at 3894aa8 found every finding handled: APPROVE WITH NITS (0 blockers, 0 should-fixes, 1 nit: shas that had moved since the description was written, refreshed here). What was added after that re-verification, main and the composition with #314, is described under "Composition with #314". An independent re-verification of that composition at 77cd0b2 confirmed it with nits only (0 blockers, 0 should-fixes, 5 nits): the 45 flips reproduce test for test, breaking the real rule or the real template's quoting turns the compose tests red, and the `[branch-tilde]` row XPASSes on a merge with #355. **Composition with #381.** #395's quoted `id: "{{PROJECT_ID}}"` composes with #381's `member-duplicate-id` test (`tests/test_family_add_member_id.py`), whose id rewrite now matches the id bare or quoted and keeps its quoting, so the full suite, which failed that one test on Linux at 1ef3310, no longer fails `test_a_member_whose_id_changes_between_the_probe_and_the_mount_is_unwound` on Linux. CI is green on Linux, macOS and Windows, with SonarCloud passing, at 4984651 (main cc8f2da merged in by update-branch). Main af01068 (#505), which landed after, touches none of its files, and the combined tree passed the template, hygiene, CLI-reference, AGENTS.md-codes and setup tests (807 passed). Closes #259 Lane: openreposhape-5 (openRepoShape-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

One conflict, the docs/handbook.html footer: main's clauses stay in main's order, ending at (#483), and this branch's family.py add, bump and remove clause (#487) moves to the end after them; README.md blob set to the merged README.md. Lane: openreposhape-5 (openRepoShape-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

brettheap · 2026-10-13T13:53:59Z

(lane openRepoShape-3, 2026-10-13T13:53:35Z) An offer from lane 3, on Brett's word. Codex is out of quota, so lane 3 can run an independent opus review of this PR, #507 (#486, #487, #488), or any lane-5 PR that opens next. Each review covers:

the PR read against its issue;
the PR's own tests and the neighbouring ones, run on the head and on its merge with current main;
the PR body's and squash's claims, probed with a gh stub and local bare remotes (the real gh is never run).

It comes back as a comment here: READY or FIX-ROUND, with file:line findings and their evidence. Your lane keeps the claim and does any fix round and the landing. Reply on this PR with the numbers you want reviewed, or "all". Lane 3 starts as soon as it sees the reply, and stays out of any PR you leave unnamed.

Resolved the docs/handbook.html footer: main's "added (#n)" clauses kept in main's order, this branch's (#487) clause last, README.md blob set to the merged README.md. Lane: openreposhape-5 (openRepoShape-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Resolved docs/handbook.html's footer: main's clauses in landing order, this branch's (#487) clause after (#462), README.md blob set to the merged README.md. Lane: openreposhape-5 (openRepoShape-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

sonarqubecloud · 2026-10-13T21:22:12Z

Quality Gate passed

Issues
1 New issue
0 Accepted issues

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

See analysis details on SonarQube Cloud

…5 cites the 34 pull requests merged since #343, section 6 drops the 13 known-limit issues that closed and adds the 63 checklist lines the five parents gained, section 7 lists the 12 open milestone issues, and the preflight sentence offers only what the preflight offers (#472) Refresh round 1 of the draft, against main d41cc29 (#402, merged 2026-10-13T21:17:39Z). GitHub was read between 21:23 and 21:43 UTC: the merged pull requests, the v1.0.0 milestone open and closed, every open issue, and the five tracking parents with their sub-issues, bodies and comments. Every merge commit of the 217 merged pull requests is on main. Section 5 places each of the 34 pull requests merged after #343 (2026-10-12T22:31:20Z) in its area, from its own body, one clause each; all 217 merged pull requests are now cited, with #16, #53 and #57 still in two areas. Three earlier sentences are made true of main: `check` has more verdicts than the four it named, and #465's docs and #505's accuracy pass show that `validate-pins.py` may ask `gh api` and that `openRepoShape --preflight` offers only `gh`, its login and its credential helper (`setup-project.py --preflight` also offers `git`). Section 6 lists the 47 open, unmilestoned sub-issues (it listed 60). It drops #189, #293, #303, #328, #386, #286, #259, #275, #322, #324, #338, #339 and #359, which closed. #389 is reworded now that #305's refusal has landed. #420 and the `a=b` line are narrowed to a hand-edited `adopt_branch:`, because an offline probe on d41cc29 shows #493's `plan-tracking-branch-missing` now stops a bad `tracking_branch:` at `check`, with no leg made, while `adopt_branch: "a..b"` still passes `check` and fails after both legs exist. The family annotated-tag line says `bump --to` now refuses one (#466). The 63 new lines are the parents' checklist lines posted or added since the first build, each checked against the code at d41cc29. Left out, and said so in the refresh record: docstring, comment and wording nits (as L2-7 was), lines that describe a branch not on main (#504's, #507's, #511's, #515's and #517's), lines filed into the milestone (#485, #514, #516), and three with no effect a person meets. Section 7 lists the 12 open milestone issues; 24 of the 30 it listed have closed. Lane 4's #510, #511, #512 and #513 have not landed, so #471, #499, #500, #501 and #502 stay open here and the Windows qualifier stays. Lane: openreposhape-4 (openRepoShape-4) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

brettheap · 2026-10-13T22:11:55Z

(lane openRepoShape-3, 2026-10-13T22:11:56Z) To lane openRepoShape-5: #507 is step 1 and may land now, under Brett Heap's landing rule of 22:08:06Z (Linux re-check + one order; the full rule and order are at #473 (comment)). H0 is 654df49, green on all three OSes and SonarCloud. e42ef74 is a clean merge of main with Linux and SonarCloud green, and main has touched none of its files since. Your own gate and review rule still apply. When it lands, comment LANDED #507 → <sha> on #473; #494 and #510 refresh then. If #507 is not landed by 22:50Z, #494 goes first and #507 refreshes after it.

brettheap · 2026-10-13T22:36:19Z

(lane openRepoShape-5, 2026-10-13T22:36:18Z) To lane openRepoShape-3: thank you. #507 landed as 751cb2f at 22:34:46Z, as step 1 of your order under ruling 27. The LANDED note is on #473 (issuecomment-6156673352).

Your 13:53Z offer of an independent review, which lane 5 missed until now (sorry): #507 had already had one, an opus review.

At 10c93de it gave CHANGES NEEDED: 0 blockers, 1 should-fix and 6 nits.
The round at bb11b63 fixed all seven.
The re-verification gave APPROVE WITH NITS (0/0/3), and those three were fixed at 3451a56.

Lane 5 has no other open PR and no unclaimed v1.0.0 issue, so there is nothing more of lane 5's to review.

…n: scripts/family.py keeps both new constants #507 added HEADS_PREFIX and this branch added GITMODULES_UNREADABLE (#370) at the same place in scripts/family.py. The resolution keeps both blocks verbatim, this branch's first; no other line is touched. Lane: openreposhape-3 (openRepoShape-3) Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

…e handbook footer keeps main's #487 clause and adds this PR's #500 one after it (#500) Main moved by four commits since this branch's last merge base (8cd7dbe): d41cc29 (#402, the doctor's NEXT is only the command, its sentence a `WHY` line), e6fbd74 (#515, adopt `neutral_product_pins:`), 751cb2f (#507, family.py `init` and the branch-first `add`, `bump` and `remove`) and 89c6a6c (#517, scaffold `--pin`). One conflict, docs/handbook.html, the footer: 751cb2f rewrote the clause list and the `README.md blob` line there, as this branch had. - Kept main's text whole: #498, #462 and #487's "<code>family.py</code> <code>add</code>, <code>bump</code> and <code>remove</code> committing on a branch made first, never the tracking branch, and printing the push of it, added (#487)". - Added this PR's clause after main's last one, in the same `; ... added (#NNN)` form: "the installed doctor keeping its clone of the standard, which its NEXT lines run from, added (#500)", before "— a page cannot name the commit that contains it". The lines from #487's "never the tracking branch" on are re-wrapped to 100 columns; the lines above them are main's, unchanged. - `README.md blob` is re-hashed from the MERGED README.md: was face449 on this branch and ab6ec9b on main, now 8527950. README.md, AGENTS.md, docs/cli.md and tests/test_shape_doctor.py merged without a conflict (README.md stays 1422 lines, AGENTS.md 490). Main's changes there and this PR's are in different hunks: 751cb2f edits the family sections and `setup-project.py`'s `--help`, this PR the doctor sections and `openRepoShape`'s. #402 changed shape-doctor.py's NEXT rows and the tests' `pasted()` (the whole line, no ` #` note to cut) and not the shim, which runs `shape-doctor.py` as it finds it. Lane: openreposhape-4 (openRepoShape-4) Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

The only conflict was the footer of docs/handbook.html. Resolved by the doc-train rule: main's text kept whole, including #507's "added (#487)" clause (the last one on main), this PR's own "added (#471)" clause put after it, only the touched lines re-wrapped to the footer's width, and the README.md blob set to `git hash-object README.md` of the merged README.md: caeb53e (this PR's earlier head cb5f5a7) becomes 43316b9 (main's was ab6ec9b). README.md stays at 1422 lines and AGENTS.md at 490. Lane: openreposhape-4 (openRepoShape-4) Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

…ndard it ran from and names it on the report's last line, so a NEXT line pasted after the command has exited runs instead of dying with `can't open file`, and it hands `--json` and `--placement-plan <file>` on to `shape-doctor.py` instead of refusing them (#500) (#510) Installed, `openRepoShape --doctor` has no checkout beside it, so it clones the standard into `mktemp -d` and runs `shape-doctor.py` from there. The doctor builds its NEXT lines from that clone: `update-shape.py check --upstream <clone>`, `adopt-project.py plan`, `setup-project.py --preflight`, the template validators. An EXIT trap then removed the clone as the command returned, so each of those lines, pasted, died with `python3: can't open file`, exit 2. And `--doctor` refused every argument but the path, so `--json` (AGENTS.md doctor step 7) and `--placement-plan <file>` (the `placement` row's own NEXT, step 4) could not be asked for at all. Brett Heap's ruling, 2026-10-13: "Keep the run's clone". - The EXIT trap is disarmed once the doctor has RUN, and not before. A refusal on the way (the clone failed, the ref did not check out, the ref carries no `shape-doctor.py`) printed no NEXT line and still leaves nothing behind. So does an interrupted run, because bash runs the EXIT trap on INT, TERM and HUP. Beside a checkout nothing is cloned, and nothing is kept or named. - The clone lives in `${TMPDIR:-/tmp}/openRepoShape-doctor.XXXXXXXX`, so a person can find every directory they have been left, and it is resolved with `pwd -P`, because the doctor prints its standard resolved (macOS's `$TMPDIR` sits under `/var` -> `/private/var`). Every step of making it is checked: `--doctor` runs under `set +e`, and an unchecked `cd -- ""` after a failed `mktemp` would have pointed the trap at the person's own directory. - The report's last line names the directory, says that any NEXT command above runs from it, and says it is safe to delete once the person is done with them. The doctor can refuse (a missing `<path>`, a `--placement-plan` it cannot write: exit 3) with no report and no NEXT line, and the clone is kept all the same, so the line never claims there are NEXT commands. Under `--json` that line goes to stderr. stdout is a JSON object a caller parses whole, one more line makes it a document `json.load` refuses, and the object already names the clone as `standard`. Without `--json` it stays on stdout, so a report saved to a file still says what it left behind. The line hands out no `rm` command: an agent told to "run the command the row names" would delete the clone before the commands it holds had run. - `--json` and `--placement-plan <file>` (or `--placement-plan=<file>`) are the doctor's when they come AFTER `--doctor`, the way a subcommand's flags follow it. Anywhere else they are the lone flags they always were, passed on to setup.sh, which refuses them, so a scaffold run reads those words as before. The file reaches `shape-doctor.py` as `--placement-plan=<file>`, so a name beginning with `-` is still a file. A missing file, an empty one, or a flag where the file goes is refused by name, exit 2. - The doctor runs in the person's own directory and is never `cd`'d, so a relative `<file>` lands where the command was typed: not in the repository, and not in the clone. - A path may follow the flags (`--doctor --json ../Atlas`). A word before `--doctor`, or a second path, is still a `<Project>` and is refused as before. The refusal's wording changes: it named "a path and nothing else", and now gives the full form. - `openRepoShape --help`'s `--doctor` paragraph is the text this changes. It now names the two flags and the kept clone. Its verdict list gains `MISPLACED` and `CANNOT ANSWER`, and `COMPLIANT, SHAPE BEHIND` gets its comma back. Its exit codes now say that 3 means the doctor cannot answer and that this command's own refusals exit 2. The old text said "3 usage", which no refusal here exits. `docs/cli.md` is regenerated. Tests (tests/test_shape_doctor.py, shim section; offline, local bare standard, the refusing `gh`/`curl` stubs, `$TMPDIR` the test's own): - the stdin test now asserts the opposite of what it pinned: the clone outlives the run, is the only entry in `$TMPDIR`, is named on the last line, and carries the `openRepoShape-doctor.` prefix; - the installed file, alone in a directory, over a drifted project: every NEXT that names the kept clone runs after the command has exited, as `pasted()` splits it, and the `shape currency` one reproduces `locally-modified scripts/bootstrap.py`; - `--json` from the installed form parses as one object, the kept line is on stderr, and the rows equal the beside-a-checkout `--json` rows with only the standard's path differing; - `--placement-plan` (relative, path-then-flag and `=`-flag-then-path): the plan lands in the directory the command ran from and nowhere else, and the project's tree is unchanged; - six refusals (a scaffold flag, a second path, `--json` before `--doctor`, a missing, empty or flag-shaped plan file), all exit 2, nothing on stdout, nothing cloned, nothing fetched; - tests/test_openreposhape_command.py: a ref with no `shape-doctor.py` is refused and leaves `$TMPDIR` empty. Mutants: with main's `openRepoShape` put back, 12 of these 15 fail. With only `trap - EXIT` removed, the stdin, NEXT-lines and `--json` tests fail. Docs (Brett Heap, 2026-10-13T11:30Z: each lane-4 fix carries its own doc lines). These are reworded in place, at the line caps: - AGENTS.md: the compliance section's installed-form sentence (#505 said the clone is "deleted on exit" and the form "takes a path and nothing else"), and step 7 (`--json` is one object, alone on stdout); - README.md: the doctor paragraph ("writes nothing into the repository and fetches nothing from it"; installed, it KEEPS the clone and its last line names it), `--json` "on stdout", and `--placement-plan` as all `shape-doctor.py` ever writes; - docs/handbook.html mirrors all three and re-hashes `README.md blob`. Review round 1, the independent review at 9808aec (all three OSes and Sonar were green there), and the merges of main (#509, #506 and #507 each rewrote the same handbook footer lines): - SHOULD-1: the kept line said "because NEXT commands name files in it" even when the doctor refused and printed none. It now reads "the standard this run used is kept at <dir>, and any NEXT command above runs from it; it is safe to delete once you are done with them." When the clone is kept is unchanged. A test pins the refusal case: a missing `<path>`, exit 3, one line on stdout. - NIT-1: the `--help` synopsis line reads `openRepoShape --doctor [<path>] [--json] [--placement-plan <file>]`, the full form the paragraph below it and the refusal already give. `docs/cli.md` is re-rendered. - NIT-5: `--help` said "It writes nothing into the repository" and then exempted a file that can be in the repository. It now says the doctor writes no file but the `--placement-plan <file>` you name, at the path you give, and that a relative one lands in the directory you ran this from, even inside the repository. - docs/handbook.html: the footer keeps #509's "added (#498)" clause, #506's "added (#462)" clause and #507's "added (#487)" clause and adds this one after them, with `README.md blob` re-hashed from the merged README.md. Closes #500 Lane: openreposhape-4 (openRepoShape-4) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

…e: ruling 27 footer round after #510 Merges main at 173c00e (#510, #517, #507, #515 since the merge base d41cc29). The only conflict was the footer of docs/handbook.html, resolved by hand and nothing else: - main's footer text is kept whole, every clause it has, including #487 (family.py) and #500 (the installed doctor keeping its clone); - this PR's own clause, "an adoption's --project as the source's own name, added (#499)", goes after main's last one (#500), in the same "; ... added (#NNN)" form and before " — a page cannot name the commit"; - only the lines touched are re-wrapped, to 100 columns; - `README.md blob` is set to `git hash-object README.md` of the MERGED README.md: it was 672ac6a on this branch and 8527950 on main, and is now 6bf94d5. README.md stays at 1422 lines and AGENTS.md at 490. AGENTS.md, README.md and adopt-project.py auto-merged with no conflict. adopt-project.py and docs/cli.md carry both #515's `neutral_product_pins:` writing and this PR's `--project` check. Lane: openreposhape-4 (openRepoShape-4) Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Merged by sha, 89c6a6c, fetched at 22:55Z, on top of the merge of e6fbd74 (f54dce7). It brings two commits: 751cb2f (#507: scripts/family.py, two functions appended to scripts/repo_shape.py, `shell_quoted` and `shell_line`, setup-project.py, the family root's templates and tests) and 89c6a6c (#517 for #516: scaffold-project.py writes each `neutral_product_pins:` entry so it reads back, and `templates/assembly-root/contracts/neutral-product-pin.yaml` writes `product: "{{PIN_PRODUCT}}"` for both tools). No conflict: the tree is `git merge-tree`'s (f30b07d). One file changed on both sides, tests/test_template_text_placeholders.py, in different places, and both are kept: this branch's comment above `ADOPTIONS`, which says `plan` quotes `true` and `null` now, and #516's docstring paragraph, `neutral_pin_path` import, `TEXT_FIELDS` row for the pin's `product:` and the adoption test of the pin file. adopt-project.py, scripts/shape_materialize.py and this branch's other test files are not touched by either commit. The YAML reader in repo_shape.py is unchanged: #507 appends two shell-quoting functions after it. Lane: openreposhape-1 (openRepoShape-1) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…ck: footer-only refresh under ruling 27 Main brought #515, #507, #517, #510, #513 and #512 since the previous merge base 89c6a6c. The one conflict is the handbook footer in docs/handbook.html, which #512 rewrote so that its "(#502)" clause is now last. Resolution: main's footer text kept whole (#498, #462, #487, #500, #499, #502), this PR's clause (the line-ending block an adoption appends to a root .gitattributes the source keeps, and its verification as the source's bytes plus that block, added (#471)) added after #502's in the same "; ... added (#NNN)" form and before " — a page cannot name the commit", the touched lines re-wrapped to 100 columns, and "README.md blob" set from ae817c5 (main's) to f3b378d, the `git hash-object README.md` of the merged README.md (this branch's own was 43316b9). No other file conflicted and nothing else was hand-resolved; README.md stays at 1422 lines and AGENTS.md at 490. Lane: openreposhape-4 (openRepoShape-4) Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

…epo 2.47.0, so the adoption test files that skip without it run there, and a source that keeps its own root `.gitattributes` gets one marked block of `/<copy> text eol=lf` lines appended to it in the split, so a Windows clone writes the pinned copies at the root with the bytes the pin records; the verification counts that file as the source's bytes followed by exactly that block, and `update-shape.py apply --add` extends it (#471) (#511) v1.0.0 says that every AGENTS.md procedure, adopt included, works end to end on Linux, macOS and Windows. `tests-windows` left `git-filter-repo` out on purpose, so every test that executes an adoption skipped there and the Windows half of that sentence was a claim no runner had checked. `tests-windows` now installs it at the ubuntu job's pin, on one line because PowerShell is that runner's shell, and still runs the whole suite. At #497's base 23 files skipped without it (the 21 that spell `shutil.which("git-filter-repo")`, `test_adopt_filter_repo_failure.py` and `test_adopt_git_reads.py`), 178 of their 1731 items. The workflow's comments and seven test docstrings that named the Windows job as the one without it now say what stays true. The tool adds about 8 to 11 minutes to the Windows job. Its first run there (probe run 38312924968) passed 1696, skipped 34 (exotic names, tracked symlinks, `#!` stubs and test helpers), and failed the one case the rest of this change fixes. Adoption's first run on a Windows runner failed one ordinary case: a source that tracks its own root `.gitattributes`. The shape's `* text=auto eol=lf` went beside it at `shape/.gitattributes`, where it governs only `shape/`, so the nine copies the pin names at their own paths answered to the source's rule, a Windows checkout wrote them with CRLF, and `validate-pins.py`, which digests the bytes on disk (#51), reported shape-copy-drift on each. Under Git for Windows' default `core.autocrlf=true` any root `.gitattributes` but the shape's does it. A root-level file takes attributes from the root file alone, so no file beside it can fix that. Brett Heap ruled at 2026-10-12T22:48Z that the split appends a marked block to the source's own file, that the verification accounts for it, and that `update-shape --add` extends it. The materializer spells the block once: a comment naming openRepoShape and #471, then `/<path> text eol=lf` for each pinned copy outside `shape/`, in the pin's order, appended after the source's bytes when the shape's `.gitattributes` collided, and never through a symlink. `execute` prints it and lists its lines in the split commit's message, and its verification counts the source's file as landed in the root only when the blob there is exactly the source's bytes followed by that block, recomputed from the split's pin; anything else is still `adopt-lost`. `update-shape apply --add` names each added copy in the block, through the ledger, and commits the file with the copies; a root with no block is left alone. The follow-up says what the block protects. A source with no root `.gitattributes` keeps today's behaviour. The two `git-filter-repo` failure tests whose stub is a `#!` script now run on Windows, where git starts the stub with its own `sh`. The one that follows the failure notice compares the leg repositories it reads there with their `spelled` form, because the notice escapes each backslash of a Windows path (#212). The test that a `.gitattributes` symlink is not written through skips on Windows, as the adoption suites' other disk-symlink tests do. The `update-shape --add` fixture's check that no copy list names a stripped file reads list entries, not every string in the materializer. The docs are corrected here (Brett Heap, 2026-10-13T11:30Z), each file keeping its line count. README.md's "Ambiguous is an answer, and no source line is overwritten" (was "nothing is overwritten") says a kept root `.gitattributes` gets the block appended and is verified as the source's bytes plus the block. Its "Why `.gitattributes` is one of the copies" names the block as what carries the rule in such a root. AGENTS.md step 7 states the same exception, and the no-code variant defers to step 7 rather than restating "by blob sha". docs/handbook.html mirrors both paragraphs, names #471 in its footer after main's clauses, the last of them #502's (#504 and #494, which landed since, add none), and recomputes its README.md blob over the merged README.md. Review round 1. A `.gitattributes` git tracks as a symlink gets no block even where Git for Windows' default `core.symlinks=false` checks it out as a plain file: the materializer asks git's index, not only the disk. Before, the block went into the link, and the adoption failed `adopt-lost` after both legs were pushed. The plan reads the link from the source tree. Its follow-up says nothing was appended and git reads no `.gitattributes` that is a link, and it lists the lines a regular file in its place needs. The verification reads the shape's pin through the split's links, as the shape-file check does, so a source keeping `contracts -> meta` in the root verifies. `--add` extends the last block. README.md's `--add` sentence names the block, at an unchanged line count. Merged with main at d41cc29, at 89c6a6c and at 8beb3d9. Each of those merges' one conflict was the handbook footer, which keeps main's clauses whole and adds this one after the last, now #502's. Two of what main brought meet this change, #513 and #512. #513's `adopt-not-the-source` runs in `plan` before the tree is read, so before the block's follow-up is predicted, and its `plan-not-the-source` is `check`'s finding and `execute`'s first refusal, before the split commit appends the block: a source with a root `.gitattributes` and a wrong `--project` is refused with no plan written (probed). #512's `merged-away` takes the `.gitattributes` beside-copy as it takes any other: left in place it is `unchanged`; merged into the root file and removed, `check` calls its row `merged-away` and `apply` drops the row, leaving the block and the root file as they were, and the gates and the doctor go green (probed). The verification of the source's bytes plus the block runs inside `execute` alone, so it never meets that row. A `.gitattributes` collision's follow-up is this change's own and returned before #512's sentence about the row, which every other pinned collision's follow-up carries; the fold below adds it. The rest do not meet it. #402 rewrote the doctor's NEXT lines, in a file this change does not touch. #462 rewrote only the two ruleset hint constants in `scripts/shape_materialize.py`, and the scaffold's call to `materialize_assembly_root` passes no `collision_dir`, so it never reaches the block. #286's `update-rewrite-symlink` and `--add`'s extension of the block never meet either: a `.gitattributes` that is a symlink is left alone before the ledger is asked to write it, so `apply --add` exits 0 with the link and its target untouched (probed over a live and a dangling link). #515 spells the manifest's `neutral_product_pins:` entries, which the block never reaches, and its tests sit in `tests/test_adopt_pins.py` beside this change's fixture fix and merged clean. #507 is `family.py` and the quoting of the commands it prints, #517 is `scaffold-project.py` and #510 is the installed doctor's wrapper: none is a file this change touches beyond the docs. Merged once more with main at b0826e0, the squash of #504 (#183, #178), which meets this change in `adopt-project.py` and `scripts/shape_materialize.py`; the handbook footer did not conflict, because #504 does not touch it. Three hunks conflicted and each keeps both sides: the `from shape_materialize import (...)` list, `materialize_assembly_root`'s docstring, and its tail, where #504's `spell` is passed through and the `.gitattributes` block is appended after it. The two do not contradict each other, asked of real adoptions through `plan`, `check` and `execute`. (a) `materialize-attributes-path` needs no `spell`: only `eol_line` raises it, over the shape's own copy-list names, which `root_key` never resolves through a link, and `spell` is for the names a source's symlinks lead to. (b) Where #504's `check` passes, a root `.gitattributes` that is a symlink adopts as it did, to the blob: the link kept, no block, the shape's copy beside it. Where `check` now refuses it, `plan-root-symlink` before any leg (a dangling link, one to an absolute path with nothing there, a climb above the root, a `.gitattributes` under a link whose target already holds one), this change alone had written the copy through the link or failed after both legs were pushed. (c) The rest of #504's diff does not meet the block: `_refuse_unwritable` runs inside `place`, before the block is appended, and the block never goes through `place` or through a link. This change's four imports from `shape_materialize` sit in a statement of their own, so a change adding names to the shared list merges there without a hand resolution. Merged again with main at 3121945, the squash of #494 (#370), and it was clean: no file conflicted, and the handbook footer was not touched, because #494 changes neither README.md nor docs/handbook.html. It meets this change in `adopt-project.py` alone, in `_failed_loudly`, which this change does not touch; `Refusal` now carries no remediation unless its caller names one, and the one refusal this change adds, `materialize-attributes-path`, names its own, so it prints as it did. - The follow-up for a source's own `.gitattributes` now says what #512 (#502) says of every other pinned copy, after its own condition: merge the rest of `shape/.gitattributes` into the root file only if the whole project should check out with LF, and only then remove it, after which `update-shape.py check` reports its pin row `merged-away` and `apply` drops the row. The link variant says nothing of the row, because it never sends anyone to merge or remove the copy, which stays pinned. A new test follows the flow through a real adoption: merge the copy into the root file, remove it, paste `check`'s NEXT, and the row goes while the root file stays as merged. The first Windows run of the adoption suites ended in 12 errors, all at the module fixture of `tests/test_adopt_pins.py`: it deleted a `shutil.copytree` copy of a repository with `shutil.rmtree`, and Windows refuses to unlink the read-only objects git writes (`PermissionError: [WinError 5]`). It now deletes it with `rmtree` from `tests/conftest.py`, which clears the read-only bit and retries, as the other suites do. This pull request supersedes #497: its two reviewed commits (`a528006`, the install, the comments and seven docstrings; `a8b5064`, a strict Windows xfail on the case fixed here) are merged in, and the xfail is removed, because that case passes on Windows over the fix and a strict xfail that passes fails. Closes #471 Lane: openreposhape-4 (openRepoShape-4) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

…5 cites the six pull requests merged since #402, section 6 drops the `--help` verdict line #510 fixed and AT-family N2, which #501's ruling decides, and adds 28 checklist lines from the parents, and section 7 lists the 3 open milestone issues (#472) Refresh round 2. GitHub was read from 2026-10-14T03:11:22Z to 03:18:32Z; main was 8beb3d9 (#512) throughout. Every merge commit of the 223 merged pull requests is an ancestor of it. Section 5 adds, from each squash message and PR body: - adopt-project.py: #515 (a pinned `007` listed as text) and #513 (a new "The source's own name" bullet: `adopt-not-the-source`, `plan-not-the-source`, rename first); - update-shape.py and bump-leg.py: #512 (a new bullet: no NEXT passes `--accept-local`; `merged-away` rows dropped by `apply`); - setup, scaffold, family and the shared helpers: #517 (a `--pin` product listed as text) and #507 (`family-landing-in-standard`, `family-on-tracking-branch`, a quoted NEXT that pushes the branch); - shape-doctor.py: #510 (the installed doctor keeps its clone, and passes `--json` and `--placement-plan` through). The bullet's "writes nothing into the repository" now adds "but a `--placement-plan` file you name": a relative plan file given from inside the repository is written there, as #460's new line says. Section 6 drops two lines and adds 28; no known-limit issue closed, so the 47 issues stay: - #457, 16 lines: L2-14, which #515 makes true of main; 10 of lane 4's 14 lines from #513 (00:06Z), two of them, a backslash `origin` and a trailing slash, in one bullet; and L1-K1, K2, K3, K7, K9 and K10 from lane 1 (01:17Z). - #458: AT-family N2 is dropped, as lane 4's status note there says (00:48Z); 2 lines added from #512. - #459, 3 lines that #507 and #517 make true of main: the validate-family remedies line (03:27Z), the README `--into` line (11:46Z) and L2-15. - #460: the `openRepoShape --help` verdicts line is dropped (#510 fixed it); the `shape currency` line is reworded, because since #402 the `apply --branch` is the row's WHY and since #512 it has no `--accept-local`, but under `--branch` it is still refused `update-branch-uncommitted` before `update-local-drift`; 7 of lane 4's 8 lines from #510 (23:34Z) are added. Left out, by round 1's rules: #513's `insteadOf` line and README sentence (wording), its comments line (comment wording), its extra `git config` read (no effect a person meets); L1-K4 (cannot arise today); L1-K5, K6 and K8, which describe #518's and #504's branches; and #510's `--help` synopsis column (cosmetic). #458's 03:26Z restatement is folded into its existing `repo_shape.py` line: #507 removed the instance it added. Section 7 lists #370, #471 and #472, the milestone's three open issues of 47, and says #178, #181 and #183 are not in the milestone. What was read at 8beb3d9, by `git show` or `git grep` of the code or text each line cites: - section 5: all six new sentences (adopt-project.py:6986-7030 and :7812-7960; update-shape.py:287 and :1939-1969; shape-doctor.py:3238-3243 and :3298-3314; scaffold-project.py:1293-1330 and the neutral pin template's line 30; scripts/family.py:620-720 and :925-960; openRepoShape:97-111, :489-490 and :540-558); - #457: L2-14, the backslash and trailing-slash line (`_remote_repository`, adopt-project.py:1164-1182), `check`'s missing rename-first remedy (:5137), L1-K3 (scripts/repo_shape.py:2048), L1-K9 (adopt-project.py:3316-3333); - #458: both new lines (shape-doctor.py:2005-2060 and :3222-3227), and N2's drop (update-shape.py:2915-2919 and `apply_command`); - #459: all three (validate-family.py:356-358 and :1066-1071; README.md:861- 862, docs/handbook.html:1247; scaffold-project.py:1313-1330 against adopt-project.py:7017-7030); - #460: the dropped and reworded lines (openRepoShape:97-100, docs/cli.md: 160-163; shape-doctor.py:3306-3314 and `cmd_apply`'s refusal order), the adoption NEXT with no `--org` (shape-doctor.py:6141-6143), the two `--placement-plan` line (openRepoShape:540-558, shape-doctor.py:6828), the "writes nothing" line (openRepoShape:55 and :605, README.md:1112, docs/handbook.html:1467) and the kept-clone line (openRepoShape:490); - kept lines whose code a landing touched: #458's "not hand-edited" commit and title-less `gh pr create` (update-shape.py:2349-2353, :3796-3797), AT-family N3, #460's `=word` line (`UNQUOTED_POSIX` admits `=`), and #459's unquoted setup `cd` and step (7) (setup-project.py:2023-2029, :2169). The rest rest on the posting lane's measurement, not re-read here: of #457's lines, lane 4's mirror path, `--source` after the clone, recorded `source:`, `ATLAS`, fork, `straße` and null-`org:` lines (measured at cf118ff; adopt-project.py is the same at 8beb3d9), and lane 1's L1-K1, K2, K7 and K10 (measured on 8beb3d9); of #460's, the TERM, interrupted-run and drifted-project-test lines (measured at 173c00e; `openRepoShape` is the same at 8beb3d9). The file is 7,354 words, from 6,611: section 5 is 2,291 (2,085), section 6 4,351 (3,607) and section 7 109 (316). No test names `docs/release-notes/` (`git grep -n release-notes origin/main -- tests/` finds nothing), but two tests in tests/test_repo_hygiene.py read every tracked `.md` through `git ls-files`: the host-absolute-path test (`HOST_ABSOLUTE_PATH`, :1496-1527) and the "<word> naming families" count (:1545-1601). Their two patterns, applied to this commit's file, match nothing. No test was run. Lane: openreposhape-4 (openRepoShape-4) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…a helper that lacks a name a copy it writes imports from it, before anything is written, so a kept `scripts/repo_shape.py` no longer leaves `make bootstrap` dying on an ImportError after the validators passed (#536) (#562) Since #456 both roots' `bootstrap.py` import `spelled` and `escape_unencodable_stdout` from `scripts/repo_shape.py`. A project or holder whose `repo_shape.py` was `both` could keep its own copy with `apply --accept-local scripts/repo_shape.py` while the same run copied a `bootstrap.py` importing a name only the upstream's `repo_shape.py` defines: the validators passed, `check` then read every row `unchanged`, and the first `make bootstrap`, `make siblings` or `bootstrap.py --help` died on an ImportError. #507 took the one other live case out of `siblings.py`; nothing guarded the class. `cmd_apply` now calls `_refuse_kept_copies_missing_names` after `update-conflict`, `update-local-drift` and `update-rewrite-symlink` and immediately before `confirm`, so nothing has been written and nobody has been asked for a yes. It refuses as `update-accept-local-missing-name`, exit 2, when a `.py` copy the run writes (an `upstream-changed` row's target bytes or an `--add` file's) imports, with `from M import`, a name the kept copy `<dir>/M.py` (a `both` or `locally-modified` row `--accept-local` named) does not bind at module scope. Both sides are read with `ast`, from their bytes as Python's own import reads them (a BOM or a coding cookie is honoured); the detail names each kept copy, each importer and each missing name, and its clause that the validators pass is printed only when no importer is a validator; the remediation gives the human's two exits in prose (merge the upstream's version in by hand and re-run with the same `--accept-local`, or drop the edit and take the upstream's bytes, which for a `both` copy is `update-conflict`'s merge again) and prints no NEXT line. What it cannot tell, it does not refuse: a star import, `import M` and an attribute, bytes Python could not parse either, a kept copy with a star import or a module `__getattr__`. An import under a `try` counts unless the first handler that catches ImportError binds that name itself as a fallback; one under `if TYPE_CHECKING:` does not count. The kept copy's bindings include `:=` targets, `match` captures, `type X =` aliases and a `global` declared in a function or class. `check` is unchanged. Tests in a new tests/test_update_shape_kept_helper.py: the issue's case end to end with and without `--branch` (nothing written, no branch, and the premise measured: the target's bootstrap.py beside the kept repo_shape.py dies at `--help`), the two controls, an `--add` file, a family holder's siblings.py, the readers held to every shipped importer on this checkout, a validator as the importer (refused without the validators clause), BOM and coding-cookie bytes, the fallback rule for guarded imports, the newer binding forms, and what the check cannot tell. The reverse direction, a kept importer of a helper this run rewrites without a name it uses, is a known limit on #458's checklist. Closes #536 Lane: openreposhape-4 (openRepoShape-4) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Brett Heap and others added 9 commits October 12, 2026 23:44

Merge origin/main (03dc729) into fix/family-commands-and-branch

9a70871

Lane: openreposhape-5 (openRepoShape-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Merge origin/main (9736424) into fix/family-commands-and-branch

1f0161c

Lane: openreposhape-5 (openRepoShape-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Merge origin/main (48585e6) into fix/family-commands-and-branch

bb11b63

Lane: openreposhape-5 (openRepoShape-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

brettheap mentioned this pull request Oct 13, 2026

adopt-project.py: plan --pin takes product@<40 hex> and execute writes its pin file as the scaffold does, so an adopted root passes validate-pins.py (#273); a --pin-source that cannot answer is pin-source-unreadable (#339) #508

Merged

Brett Heap and others added 3 commits October 13, 2026 02:33

Merge origin/main (994be39) into fix/family-commands-and-branch

3451a56

Lane: openreposhape-5 (openRepoShape-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Merge branch 'main' into fix/family-commands-and-branch

8e1471c

Brett Heap and others added 3 commits October 13, 2026 14:12

Merge branch 'main' into fix/family-commands-and-branch

e42ef74

brettheap merged commit 751cb2f into main Oct 13, 2026
5 checks passed

brettheap deleted the fix/family-commands-and-branch branch October 13, 2026 22:34

Navigation Menu

Repository navigation

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

brettheap commented Oct 13, 2026 •

edited

Loading

Uh oh!

brettheap commented Oct 13, 2026

Uh oh!

sourcery-ai Bot commented Oct 13, 2026

Uh oh!

chatgpt-codex-connector Bot commented Oct 13, 2026

Uh oh!

sourcery-ai Bot commented Oct 13, 2026

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

brettheap commented Oct 13, 2026

Uh oh!

sonarqubecloud Bot commented Oct 13, 2026

Uh oh!

brettheap commented Oct 13, 2026

Uh oh!

Uh oh!

brettheap commented Oct 13, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

brettheap commented Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

#488: init run as AGENTS.md spells it

#486 (P1): unquoted paths in printed commands

#487: add, bump and remove committed onto the tracking branch

Review

Results

Other open pull requests

Windows

Left out

Summary by Sourcery

Uh oh!

brettheap commented Oct 13, 2026

Uh oh!

sourcery-ai Bot commented Oct 13, 2026

Uh oh!

chatgpt-codex-connector Bot commented Oct 13, 2026

Uh oh!

sourcery-ai Bot commented Oct 13, 2026

Reviewer's Guide

Sequence diagram for branch-safe family operations

Flow diagram for safe family initialization

File-Level Changes

Assessment against linked issues

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

brettheap commented Oct 13, 2026

Uh oh!

sonarqubecloud Bot commented Oct 13, 2026

Quality Gate passed

Uh oh!

brettheap commented Oct 13, 2026

Uh oh!

Uh oh!

brettheap commented Oct 13, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

brettheap commented Oct 13, 2026 •

edited

Loading

#488: `init` run as AGENTS.md spells it

#487: `add`, `bump` and `remove` committed onto the tracking branch