[brettheap]

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

Three lines of #543, in one change and one re-pin, because scripts/siblings.py is a pinned copy in every family holder.

Head: 8d3d1cceb30dfc93c7ceec130131038dc4f89e40. The branch's own commits: the change (43d32eb, on bfed143), a merge of main at 9f80939 (8b4fc0b), the review round (2156a01), round 3 (5ce5b68, a family folder reached through a link; 0112dcb, a test skipped on Windows), and round 4 (8d3d1cc, a Windows junction counts as a link, and rv543b's nits).

What changed and why

1. The family folder is asked first (templates/family-root/scripts/siblings.py, _run_placement, parent_folder_warning).

• Before: in a holder whose parent folder is not named after the family, make siblings cloned every member into that folder, then printed the warning and the mv lines, and exited 0. After the move, the re-run cloned every member a second time beside the moved holder. The first clones stayed behind.
• Now: the check runs before any git command runs or any member is cloned. The run prints the same WARNING and mv lines, says NOTHING WAS CLONED and why, ends with siblings: stopped before cloning: the holder is not in a folder named <Family>. Nothing was cloned, fetched or moved., and exits 1 (make siblings exits 2, make's own code). --dry-run stops the same way. After the move, one run clones each member once.
• Why a stop and not a later warning: no flag or documented answer lets a person place siblings outside the family folder. AGENTS.md, README.md, the handbook and the holder's own README and AGENTS-shape.md all describe a warning plus a printed mv, and the warning itself told the person to move the holder and re-run. A stop gives the same outcome without the stray clones. Exit 1 is the file's "finding a human can act on" (exit 2 is kept for "the question could not be asked").
• The printed move runs as typed on every disk (review round, S3). The name test stays exact on Linux, macOS and Windows. So the remedy has to work on each:
  • On a disk that ignores case (macOS, Windows), a holder in inkrouter/ for the family InkRouter used to get mkdir -p <p>/InkRouter and mv <p>/inkrouter/InkRouter <p>/InkRouter/InkRouter. There <p>/InkRouter IS <p>/inkrouter, so that moved the holder onto itself and failed. Now, when <p>/InkRouter exists and os.path.samefile says it is this folder, the FOLDER is renamed through a staging name: mv <p>/inkrouter <p>/InkRouter.folder, then mv <p>/InkRouter.folder <p>/InkRouter.
  • At a filesystem or drive root (/InkRouter, C:\InkRouter), <root>/InkRouter is the holder itself, and the old lines were mv X X/X. Now the holder moves through <root>/InkRouter.holder, the staged move the common case already used. The warning names the root ('/') where it used to say ''.
  • Linux is unchanged: with nothing at <p>/InkRouter the holder moves there through InkRouter.holder; with a separate <p>/InkRouter folder it moves into it.
  • A link named InkRouter beside the folder and leading to it passes the check: the family folder, reached through a link (see "Round 3").
• The header says parent folder until the check passes (C3). It used to print family folder <parent> right above a warning saying the parent is not the family folder. Through a link it names the folder the clones go into, and the link.

2. auF-13: the tracking branch (siblings.py, tracking_branch(), used in place()).

• Before: a plain git clone, so a sibling landed on its remote's default branch.
• Now: the clone passes --branch=<branch>, where <branch> is the tracking_branch: of the member's own project.yaml in the pinned copy under members/. That copy is the holder's record of the member, and the same field the member's own bootstrap reads for its legs.
• Not read: .gitmodules (both templates say it carries no branch=, and nothing writes one) and family.yaml's tracking_branch: (the holder's own branch: family.py add, bump and remove refuse to commit on it).
• No record: when members/<Project> is not checked out, or its project.yaml names no branch, the clone keeps today's behaviour (the remote's default branch) and its line says why.
• A value that is no branch name is not used (review round, N1). A number or a list (5, [main]) now reads declares tracking_branch 5, which is not a branch name, where it used to say it declares none. A string holding a character that does not print (an ESC sequence, a newline) is not handed to git and is shown in its repr, for example declares tracking_branch '\x1b[2Jcleared', which holds a character that does not print, so it is not used as a branch. It used to reach stdout raw. The member's own bootstrap escapes the same field (templates/assembly-root/scripts/bootstrap.py and templates/family-root/scripts/bootstrap.py: main prints the manifest's name with a plain print before any step runs, so name: "a\ud83db" (a lone surrogate) ends make bootstrap in a UnicodeEncodeError traceback, exit 1 (make: 2), and the validator that names the problem is never reached; a valid name the stdout cannot encode ends the same way #391). Each such clone keeps the remote's default branch. No import was added to the pinned file.
• A declared branch the remote does not have is git's own refusal: a CLONE FAILED finding naming it, exit 1, and no directory left behind.

3. auF-14: the holder's pinned copy (scripts/family.py, cmd_siblings).

• Before: family.py siblings used runpy to run this checkout's templates/family-root/scripts/siblings.py, inside family.py's own process. A holder pinned at another shape ran different code than make siblings. With no holder copy at all it still ran, and its siblings-script-missing remedy said it "runs the holder's own copy".
• Now: it runs <holder>/scripts/siblings.py with the same interpreter, in its own process, from the holder, as the Makefile's siblings target does, and returns that exit code unchanged. The command is scripts/siblings.py --root . (plus --dry-run). Every word of it is a constant, so no command-line value reaches its argv (the case SonarCloud's pythonsecurity:S8705 flags).
• The child keeps family.py's escaped stdout (review round, S1). family.py escapes what its stdout cannot encode (adopt-project.py plan raises UnicodeEncodeError in its terminal report, after the plan file is written, for a printable name stdout cannot encode (日本.md under cp1252, as on a redirected Windows stdout), so plan exits 1 before plan written to #214), but a child takes its stdout settings from its environment. So the child now gets inherited_child_environment(), the helper update-shape.py already uses for the validators it runs (bump-leg.py (a real bump) and update-shape.py apply run the project's own validators as children that cannot print its display name on a cp1252 stdout, so a project named 日本 is refused and rolled back as bump-leg-validators-red or update-validators-red under PYTHONIOENCODING=cp1252:surrogateescape, and the refusal blames the validators #254): this stdout's own encoding and a handler that cannot raise. Under PYTHONIOENCODING=ascii the child used to die on the em dash of its first line, UnicodeEncodeError, exit 1. Now it prints \u2014 and goes on. The helper already guards a stdout with no encoding, and it never passes on the handler only family.py registers, which a child cannot look up.
• A holder without the file is refused: siblings-script-missing, exit 2, before anything is cloned, in the words the holder's Makefile refuses with since 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.

4. init --work-dir no longer promises clones (scripts/family.py, _print_next_steps; review round, S2). --work-dir <dir> makes no family folder. Where <dir> is not named after the family, the NEXT STEPS used to say make siblings "then puts each member's WORKING clone beside the holder, in the family folder", and family folder <dir>. That make siblings now stops. The block now says --work-dir made no family folder, so make siblings clones nothing: it prints the mv that puts the holder in a folder named <Family>, and stops until it is there, and family folder none: <dir> is not named <Family>. The --into output is byte for byte what it was.

The half of #461 that #543 names. The sibling clone is --no-local. A member url that is a path on disk is then read through git, not copied file by file, so a repack in the remote cannot break it halfway (#440).

Docs.

• AGENTS.md family item 5 and the holder's AGENTS-shape.md said the stop "exits 1"; make siblings itself exits 2, make's own code. Both now say exit 1 (make: 2), rewrapped within the same lines. AGENTS.md stays at 490 lines.
• The holder's README.md says the run stops before cloning, and which tracking branch it clones on.
• templates/family-root/family.yaml's tracking_branch: comment said the family bootstrap places each member on that branch. It now says what it is: the holder's own branch, which family.py refuses to commit on. The family bootstrap leaves each member detached, and make siblings reads the member's own project.yaml. No test or pin compares those bytes.
• README.md and docs/handbook.html are untouched (see "Left out").

The review round, point by point (rv543)

point	what was found	what this head does
S1	the child process lost family.py's escaped stdout (#214)	env=inherited_child_environment(); test with PYTHONIOENCODING=ascii
S2	init --work-dir's NEXT STEPS promised a make siblings that stops	the folder is None branch says there is no family folder; test on the fixture's own init stdout
S3	on a disk that ignores case, and at a root, the printed move cannot run	the exact name test is kept on every disk; the folder rename and the staged holder move; tests by simulation on all three systems
N1	a tracking_branch: holding control characters reached stdout raw; 5 and [main] said "declares no tracking_branch"	not used, shown in its repr; "is not a branch name"; three tests
N2	"before any credential is resolved" was unguarded	the claim is now "before any git command runs", pinned with GIT_TRACE; reading the environment had nothing a test could observe
N3	a symlinked family folder now stops, and its printed move cannot run	round 3: a link named after the family, beside the folder and leading to it, passes; see "Round 3"
N4	AGENTS.md:409 said "exits 1" for make siblings	exit 1 (make: 2), within the same lines; the same fix in the holder's AGENTS-shape.md
N5	the merge section was stale	rewritten below
C2	the family.yaml comment was false	fixed
C3	family folder printed above a stop	parent folder until the check passes

S3, the decision: keep the strict name test on every OS. Brett Heap's rule for the case variants of members/ (#362-#364, "Refuse on every disk") is one answer on every disk. The same spirit applies here. Accepting os.path.samefile(folder, wanted) instead would pass a holder on macOS that Linux stops. So every printed remedy now has to work as typed. The evidence:

• Tests, on all three systems. The template's siblings.py is loaded in-process with load_without_bytecode, so nothing is written under templates/. Path.exists and os.path.samefile are patched to answer as a disk that ignores case does. The case-only test then does the printed moves with os.rename and checks that the next check passes. A case-sensitive disk is simulated with nothing or a separate folder at <p>/InkRouter (the separate folder skipped on Windows, see "Round 3"), and a link there, which now passes. The roots are asked as PurePosixPath("/InkRouter"), PureWindowsPath("C:\InkRouter") and PureWindowsPath("C:\inkrouter").
• Run as typed (a throwaway probe, not committed). Each printed line went to sh -c as printed. A disk that ignores case was emulated with a symlink that spells the folder in the family's case, and that exists only while the folder does (a step that leaves it dangling removes it). Then a real siblings.py ran in the moved holder:

case	lines printed	run as typed	then siblings.py in the moved holder
a disk that ignores case, holder in inkrouter/: 43d32eb	mkdir -p <t>/InkRouter, then mv <t>/inkrouter/InkRouter <t>/InkRouter/InkRouter	the mv fails, rc 1: cannot move ... to a subdirectory of itself	the holder is not placed
the same, this head	mv <t>/inkrouter <t>/InkRouter.folder, then mv <t>/InkRouter.folder <t>/InkRouter	both rc 0	rc 0, no WARNING, IRRS and IRSS cloned beside the holder
the holder at /InkRouter: 43d32eb	mkdir -p /InkRouter, then mv /InkRouter /InkRouter/InkRouter	the mv fails the same way	the holder is not placed
the same, this head	mv /InkRouter /InkRouter.holder, mkdir -p /InkRouter, mv /InkRouter.holder /InkRouter/InkRouter	all rc 0	rc 0, no WARNING, both cloned
Linux, nothing at <t>/InkRouter	the three staged lines, the same on both heads	all rc 0	rc 0, both cloned
Linux, a separate <t>/InkRouter folder	mkdir -p and one mv, the same on both heads	both rc 0	rc 0, both cloned

The filesystem root ran with / mapped to a scratch folder, because this machine has no root access and no user namespaces. C:\InkRouter and C:\inkrouter were asked of the function only. Both print WARNING the holder's parent folder is 'C:\\', not 'InkRouter'., then mv 'C:\InkRouter' 'C:\InkRouter.holder' (or 'C:\inkrouter'), mkdir -p 'C:\InkRouter' and mv 'C:\InkRouter.holder' 'C:\InkRouter\InkRouter'. Nothing here ran on a real macOS or Windows disk. CI's macOS and Windows jobs do run the case-only test's two renames on their own disks.

Tests

New file: tests/test_family_siblings_placement.py, 29 tests: 10 from the first round, 13 from the review round, 2 from round 3, 4 from round 4. The runs below are the review round's, at 2156a01; round 3's are in its own section.

All runs used a stub gh first on PATH, a bogus token, an empty GH_CONFIG_DIR, a blanked git identity, /usr/bin/python3 -m pytest:

• tests/test_family_siblings_placement.py on the working tree, before the commit: 23 passed in 50.77s.
• Set A at 2156a01: every tests/test_family*.py (15 files), test_park_resume_targets.py, test_windows_paths.py, test_doctor_legs_members_next.py, test_commit_trailers.py, test_free_plan_hint.py, test_refusal_default_remediation.py and test_stdout_encoding.py: 1007 passed, 20 skipped in 983.34s (0:16:23). The skips are test_family_init_values.py:219 (16) and :291 (3), which the file documents, and test_stdout_encoding.py:286 (Windows only).
• Set B at 2156a01: test_cli_reference.py, test_repo_hygiene.py, test_agents_md_codes.py, the three test_template_* files, the four test_validate_family_*.py, the ten test_update_shape*.py of the first round, test_shape_doctor.py, and now test_update_shape_kept_helper.py (main's check of the template's imports) and test_validator_child_encoding.py (the helper S1 uses): 1478 passed, 6 skipped in 1658.89s (0:27:38). The skips are NTFS junctions (3) and the doctor's PowerShell line (3), both Windows only.
• The merge commit 8b4fc0b on its own, before the fix: the new file, test_family.py, test_family_printed_quoting.py, test_family_makefile_siblings.py, test_park_resume_targets.py, test_windows_paths.py, test_clone_just_pushed.py and test_doctor_legs_members_next.py: 375 passed in 686.29s (0:11:26). And test_cli_reference.py, test_repo_hygiene.py, test_agents_md_codes.py, test_update_shape_kept_helper.py and test_template_text_placeholders.py: 340 passed in 245.06s (0:04:05).
• Nothing is written under templates/: after the mutation baseline run (the new file's 23 tests, the in-process ones included, plus four more) a clean tree had no __pycache__ under templates/.

Reproduction (first round; local bare remotes, stub gh)

The script builds two scaffolded members (Atlas on main; Borealis on trunk, with its remote's default branch set to main) and a holder made with init --work-dir, so its parent folder is fam, not Orbit.

	bfed143	this branch
first make siblings in fam/Orbit	exit 0; Atlas and Borealis cloned into fam/; WARNING after	exit 1 (make: 2); nothing cloned; NOTHING WAS CLONED
clones on disk after move + re-run	4: fam/Atlas, fam/Borealis, Orbit/Atlas, Orbit/Borealis	2: Orbit/Atlas, Orbit/Borealis
Borealis sibling branch	main (remote default)	trunk (its tracking branch)
family.py siblings marker from the holder's copy	0 lines (ran the standard's)	1 line
family.py siblings, holder without scripts/siblings.py	exit 0, ran the standard's copy	exit 2, REFUSED siblings-script-missing, the Makefile's words
make siblings, same holder	exit 2, the Makefile's refusal	same

The review round's reproductions are rv543's probes: PYTHONIOENCODING=ascii through family.py siblings (rc 1 with a traceback at 43d32eb; the new S1 test holds rc 0), the --work-dir NEXT STEPS, and the printed moves above.

Mutation probes

Each probe reverts one hunk in a throwaway worktree. Every one is caught.

First round (at 43d32eb; the new file plus the four changed existing tests, 15 tests):

probe	what it puts back	result	caught by
M1	no --branch= on the clone	3 failed	tracking branch, branch the remote lacks, the issue's flow
M2	no --no-local	1 failed	no shared object file
M3	the warning no longer stops the run	6 failed	both new misplaced tests, and the four changed existing tests
M3b	the folder check back after the placement, as on main	6 failed	the same six
M4	tracking_branch() never finds a branch	4 failed	tracking branch, branch the remote lacks, dry-run line, the issue's flow
M5	the clone line names no branch	3 failed	tracking branch, not-checked-out words, dry-run line
M6	the warning no longer says NOTHING WAS CLONED	2 failed	both new misplaced tests
M7	scripts/family.py as on bfed143	2 failed	holder's copy and its imports; the refusal
M8	runpy of the HOLDER's file inside family.py	1 failed	holder's copy and its imports
M9	one word of the refusal differs from the Makefile's	1 failed	the refusal
M10	no refusal for a holder without its copy	1 failed	the refusal

Review round (at 2156a01; the new file plus the same four, 28 tests; the unmutated baseline is 28 passed):

probe	what it puts back	result	caught by
S1	no env= on the child process	1 failed	the ASCII stdout test
S2	--work-dir prints the old promise	1 failed	the --work-dir NEXT STEPS test
S3a	a root is not taken for the holder itself	3 failed	the three root cases
S3b	no rename of the folder	1 failed	the case-only test
S3c	a link named after the family is renamed through	1 failed (at 2156a01; equivalent since round 3)	case-sensitive disk, a link
S3d	same_directory asks the disk before comparing the paths	3 failed	the three root cases
S3e	the warning names a root ''	3 failed	the three root cases
N1a	a control character is used as a branch	1 failed	escape-sequence
N1b	5 and [main] "declare no tracking_branch"	2 failed	a-number, a-list
N2	the credential and .gitmodules read before the stop (rv543's mutation B, which nothing caught before)	1 failed	the GIT_TRACE test
C3	the header always says family folder	1 failed	the misplaced dry run

The doc and comment hunks have no test: AGENTS.md, the holder's AGENTS-shape.md, the family.yaml comment, the docstrings, and the tests/conftest.py comment. Round 3's mutants are in its own section.

Round 3: a family folder reached through a link (N3)

What was wrong. Take <t>/InkRouter, a link to <t>/real-x, which holds the holder. Both entry points resolve the holder to <t>/real-x/InkRouter and saw a parent named real-x. On bfed143 that was a warning, and the members were cloned into real-x. This PR turned the warning into a stop. The printed mkdir -p <t>/InkRouter passes, then mv <t>/real-x/InkRouter <t>/InkRouter/InkRouter fails with cannot move ... to a subdirectory of itself, rc 1 (rv543 had read it as working). So the PR made a dead end.

The rule (siblings.py, new family_link). Let R be the resolved holder, P its parent and G P's parent. The check also passes when G/<Family> is a link (os.path.islink) and is the same directory as P (os.path.samefile). The holder is then reachable as G/<Family>/<R.name>. The members are cloned into P, the link's own target, so the family layout holds through the link.

• Both entry points give the same answer, because both resolve R: make siblings through find_repo_root, and family.py siblings by running the child in the resolved holder.
• The header then reads family folder <P> (through the link G/<Family>). It names the folder the clones go into.
• A link named after the family that leads to another folder is not accepted. Its printed move runs as typed: the holder moves into the link's target, and there the link passes.
• A link elsewhere (~/InkRouter leading to /data/real-x) still stops. Its printed move runs as typed.
• The case-only rename of S3 is unchanged and stays strict. On a disk that ignores case, a case-only alias is one directory entry and never a link, so it gets the rename. The two disks differ at one edge only: a link spelled in another case stops on Linux, with a staged move that runs, and passes on a disk that ignores case (round 4 corrected this sentence).

Run as typed (a throwaway probe; each printed line went to sh -c as printed, then a real siblings.py ran where the holder ended):

layout	2156a01	this head
<t>/InkRouter links to <t>/real-x, which holds the holder	stops; mkdir -p <t>/InkRouter rc 0, then the mv fails, rc 1, cannot move ... to a subdirectory of itself; the next run stops again	passes, rc 0, no WARNING; header family folder <t>/real-x (through the link <t>/InkRouter); IRRS and IRSS cloned into <t>/real-x
<t>/home/InkRouter links to <t>/data/real-x (a link elsewhere)	stops; the three staged lines (mv <t>/data/real-x/InkRouter <t>/data/InkRouter.holder, mkdir -p <t>/data/InkRouter, mv <t>/data/InkRouter.holder <t>/data/InkRouter/InkRouter) all rc 0; the next run passes and clones both	the same
<t>/InkRouter links to <t>/other; the holder is in <t>/real-x	(not run)	stops; mkdir -p <t>/InkRouter and mv <t>/real-x/InkRouter <t>/InkRouter/InkRouter both rc 0; the next run passes through the link, header family folder <t>/other (through the link <t>/InkRouter), both cloned into <t>/other

Tests (tests/test_family_siblings_placement.py, two new; links made with os.symlink, each test skipping first where the system refuses one; none under templates/):

• the link layout passes through family.py siblings --dry-run and through make siblings' own script, which clones each member into the link's target;
• a link named after the family to another folder stops, and its move done as written leads to a run that passes;
• the case-only test still prints the two-line rename;
• the simulated a link case of the case-sensitive disk test now patches os.path.islink too, and expects no warning.

Windows (rv543b). [a folder] of the simulated case-sensitive disk test is skipped on Windows, before any call. A WindowsPath compares without case, so same_directory() calls <p>/InkRouter and <p>/inkrouter one path there, and the case-only rename is printed. That answer is right for Windows, whose disk cannot hold the two folders, but it is not the disk the parameter simulates. Emulated on Linux with rv543b's mechanism (pathlib._is_case_sensitive returning False during each test's call): 1 failed, 24 passed in 31.32s with the parameter collected (only [a folder], since os.name is posix here), and 24 passed, 1 deselected in 31.49s without it.

Mutants (at 0112dcb, the new file, 25 tests; the baseline is 25 passed, and no __pycache__ appeared under templates/):

probe	what it changes	result	caught by
R3a	family_link never finds a link	3 failed	the link layout; the link to another folder (its moved holder no longer passes); the simulated a link
R3b	any same directory counts, link or not	5 failed	the case-only rename (a case-only alias would pass); the three roots; the placed dry run's header
R3c	any link named after the family counts, wherever it leads	1 failed	the link to another folder
R3d	the folder check does not ask family_link	3 failed	the link layout; the link to another folder; the simulated a link
R3e	the header does not name the link	1 failed	the link layout

Round 2's S3c (the is_symlink test inside the case-only branch) is now an equivalent mutant: every link is answered by family_link first, so that test can no longer decide anything (25 passed with it removed). It is kept, as the S3 branch is kept as it was.

Docs. siblings.py's module docstring (FIRST, EXIT CODES) and parent_folder_warning's, and the holder's README.md and AGENTS-shape.md, say a link of the family's name beside the folder, leading to it, counts. AGENTS.md's family item 5 was left as it was in this round, on the belief that the clause needed a ninth line; rv543b showed it fits, and round 4 adds it.

Runs at 5ce5b68 (0112dcb changes only the test file; see round 4 for where 25 passed was run):

• the new file, test_family_makefile_siblings.py, test_family_printed_quoting.py, the whole of test_family.py and test_family_tracking_branch.py: 248 passed in 196.84s (0:03:16);
• test_template_text_placeholders.py, test_update_shape_kept_helper.py, test_cli_reference.py, test_repo_hygiene.py, test_free_plan_hint.py and test_update_shape.py: 397 passed in 213.21s (0:03:33).

Round 4 (rv543b's review of 0112dcb)

point	what was found	what this head does
S-1	family_link asked only os.path.islink, which is False for an NTFS directory junction, the link Windows makes without privilege. Path.resolve() follows a junction, so that layout stopped and its printed mv failed, where bfed143 warned and cloned	os.path.isjunction counts too (Python 3.12 and later, False off Windows; read with getattr, so an older Python still runs the file, and there the junction case stays as it was). Not an "any alias" rule, which would make a link spelled in another case a dead end on macOS. A simulated junction test runs on every system
F2	AGENTS.md item 5 lacked the link clause the holder's README and AGENTS-shape.md have; this body said it could not fit	it fits: "(nor linked as it)", rewrapped within the same eight lines by dropping one "yourself"; AGENTS.md stays at 490. README.md:883 and docs/handbook.html:1306 make the same claim and are left to a later README change (see "Left out")
F3(a)	the comment and this body said the case-only rename and the link rule "never meet"	corrected: a link spelled in another case (inkrouter leading to real-x) stops on Linux, with a staged move that runs, and passes as the family's link on a disk that ignores case. No dead end either way
F3(b)	0112dcb's skip reason said a Windows disk cannot hold the two folders	it says the simulation assumes Windows' default path equality, which ignores case; an NTFS folder made case-sensitive can hold them
F4	three conditions no test guarded	one test each: init --work-dir into a folder named after the family keeps the promise (S2c); a blank tracking_branch: " " is not a branch name (N1s); a second path to the folder under another name, neither link nor junction, is not answered by the case-only folder rename (S3f)
F5, F6	the staging names are not checked; a dangling link named after the family breaks the staged move halfway	checklist candidates, below

Also corrected: round 3's 25 passed in 34.28s ran on the working tree at 5ce5b68 with 0112dcb's change not yet committed. At 0112dcb itself, the round-3 mutant baseline gave 25 passed in 32.69s.

Mutants (at 8d3d1cc, the new file, 29 tests):

probe	what it changes	result	caught by
R4a	a junction no longer counts (isjunction dropped)	1 failed, 28 passed	the simulated junction
S2c	init --work-dir always says there is no family folder	1 failed, 28 passed	--work-dir named after the family
N1s	a blank tracking_branch is used as a branch	1 failed, 28 passed	[blank]
S3f	the case-only folder rename for any second path to the folder	1 failed, 28 passed	the rename only for a difference of case

The unmutated baseline is 29 passed, and no __pycache__ appeared under templates/ after it.

Runs at 8d3d1cc:

• the new file on the working tree, before the commit: 29 passed in 21.84s;
• the new file, test_family_makefile_siblings.py, test_repo_hygiene.py, test_agents_md_codes.py, and test_family.py -k "siblings or init": 195 passed, 71 deselected in 66.86s (0:01:06).

Merge

Main merged at 8b4fc0b (git merge --no-ff origin/main, main at 9f80939: #551, #552, #554, #553, #561, #562, #579, #567). One hunk conflicted, in tests/test_family_printed_quoting.py: #554 added env=NO_BYTECODE to the run_script(FAMILY, "siblings", ...) call, and this branch changed the next line from returncode == 0 to == 1. The resolution keeps both lines whole:

    result = run_script(FAMILY, "siblings", "--family-root", str(holder),
                        "--dry-run", env=NO_BYTECODE)
    assert result.returncode == 1, result.stdout + result.stderr  # #543

tests/conftest.py's comment above NO_BYTECODE said family.py siblings runs the template's copy through runpy, which this branch makes false. It now says what the constant guards and why it stays on those two calls (lane 3 agreed to the wording on #554). NO_BYTECODE stays at both call sites; dropping it is a later cleanup. The merged tree differs from main only in this branch's files and that comment.

merge-tree at 8d3d1cc: origin/main f5fc705 is clean and not merged (one more commit since dd3f23a, update-shape.py's refusal of a hard-linked file); AGENTS.md is 490 lines in the merged tree. Lane 5's fix/family-bump-to-checks (8024f9c), fix/family-members-case-variants (e5aac93), fix/family-remove-gitmodules-missing (ebe6b51) and fix/link-source-chain-defaults (a707d4b): clean. #573 and #575 were not re-checked at this head: round 4 changes siblings.py, AGENTS.md and the new test file, none of which they touch.

merge-tree at 0112dcb (git merge-tree --write-tree, after a fresh fetch):

• origin/main dd3f23a: clean, and not merged; this PR is behind it by three commits. AGENTS.md is 490 lines in the merged tree and keeps this branch's line 409.
• family.py and scaffold-project.py: --dry-run asks the real run's own question about existing remotes, so family-remote-exists and scaffold-remote-exists come at the plan, and a missing gh is gh-not-found, not a traceback (#537) #573 fix/537-dry-run-asks-remotes (69c58aa) and validate-pins.py and validate-family.py: THE LOCKSTEP RULE closes the count only where a leg or member is out of step, a lone digest or workflow-reference mismatch names its bump-leg.py line, and holder remedies branch first (#539) #575 fix/539-validators-lockstep-remedies (0680799): clean.
• Lane 5's fix/family-bump-to-checks (8024f9c), fix/family-members-case-variants (8a95345), fix/family-remove-gitmodules-missing (ebe6b51) and fix/link-source-chain-defaults (a707d4b): clean.

At 2156a01, for the record:

• origin/main 64fc9a8: clean. Main moved after the merge, by a35f1be (update-shape.py) and 64fc9a8 (the assembly root's bootstrap.py). Neither touches a family file. A scratch merge of this head with 64fc9a8 (no ref, since removed) ran the new file, test_family_makefile_siblings.py, test_family_printed_quoting.py, and main's new test_update_shape_messages.py, test_update_shape_header_comments.py, test_update_shape_branch_any_directory.py and test_bootstrap_after_bump.py: 269 passed in 156.48s. Then test_update_shape.py, _landing, _next_quoting, _pr_base, _kept_helper, _add, test_cli_reference.py and test_repo_hygiene.py: 411 passed in 322.52s (0:05:22).
• origin/main dd3f23a (openRepoShape --doctor wording; shape-doctor.py, render-cli-reference.py, AGENTS.md, README.md, the handbook, docs/cli.md): clean, not merged, not test-run.
• family.py and scaffold-project.py: --dry-run asks the real run's own question about existing remotes, so family-remote-exists and scaffold-remote-exists come at the plan, and a missing gh is gh-not-found, not a traceback (#537) #573 fix/537-dry-run-asks-remotes (69c58aa) and validate-pins.py and validate-family.py: THE LOCKSTEP RULE closes the count only where a leg or member is out of step, a lone digest or workflow-reference mismatch names its bump-leg.py line, and holder remedies branch first (#539) #575 fix/539-validators-lockstep-remedies (93b68f6): clean.
• Lane 5's fix/family-bump-to-checks (8024f9c), fix/family-members-case-variants (40eda84), fix/family-remove-gitmodules-missing (b1120c3) and fix/link-source-chain-defaults (a707d4b): clean.

Left out, and why

• README.md and docs/handbook.html. README:882-884 and the handbook at :1305 say make siblings "WARNS and prints the exact mv". That stays true: the output still opens with WARNING and prints the mv. README:871-872 ("the same file through the other entry point") becomes true with this change. Neither says the run now stops; that is incomplete, not false, so this PR does not touch README.md. Adding "and clones nothing until it is moved" could be a later README change. That change should also add the link clause round 3 gave the holder's README and AGENTS-shape.md and round 4 gave AGENTS.md: README.md:883 and the handbook at :1306 say the run warns whenever the parent folder is not named after the family, which a family folder reached through a link no longer does. They are left alone here because a README change needs the hash step and README PRs land one at a time.
• scripts/shape_materialize.py:519: its comment says siblings "warns about the parent folder without moving anything", which is still true. It is left alone because PRs that touch that file meet SonarCloud's S8705 finding at run().
• templates/family-root/scripts/validate-family.py: not touched (lane 2's Pinned validators: THE LOCKSTEP RULE only where it applies, and remedies that name the git switch -c step (one shape bump) #539).
• The --make dispatch header still prints family folder. The dispatch runs no folder check (it is the placement's business), so it was left as it is.

Checklist candidates

• make siblings crashes on a stdout that cannot encode its em dash or a path. Pre-existing on bfed143. The holder's siblings.py never escapes its own stdout, so under PYTHONIOENCODING=ascii, or a Windows code page without a character in the holder path or a member name, make siblings dies with a UnicodeEncodeError on its first line, before any clone. family.py siblings no longer does (S1), because it hands the child its own escaped settings. The family bootstrap.py already calls repo_shape.escape_unencodable_stdout(); a holder that kept an older repo_shape.py may not have it, which main's kept-helper check now looks at.
• shape-doctor.py:5640: the members row's note says "make siblings places them", a command that now stops, clones nothing, in a holder whose parent folder is not named after the family.
• A family name a disk cannot hold exactly never passes the folder test on that disk. Windows drops a trailing . or space from a folder name and reserves names like CON and NUL. --family goes through SAFE_ARG_RE (scripts/repo_shape.py:106), which allows a trailing .. Such a holder stops on every run there.
• A tracking_branch: that names only a tag gives a detached clone. git clone --branch=<name> takes a tag too, so a member that declares v1 where its remote has only a tag v1 is cloned detached at the tag, rc 0, and the line calls it "its tracking branch".
• tests/test_cli_reference.py writes templates/family-root/scripts/__pycache__/bootstrap.cpython-312.pyc (found by rv441b on validate-repository-naming.py, repo_shape.py, validate-pins.py: a bare --link-source is the first chain link's tree alone, and a source that names no path is refused (#441, #442) #576 and here). scripts/render-cli-reference.py runs the template's siblings.py --help with PYTHONPATH=scripts, and that file imports bootstrap from beside it. Shown in clean trees: no __pycache__ before, the file after tests/test_cli_reference.py alone (22 passed), on 04c9d77, on two merged trees, and on this branch's merge. .gitignore hides it. A .pyc under templates/ breaks template_values() and its twin in test_scaffold_leg_path_collisions.py in a later run in the same tree, which read every template file as UTF-8. tests: every test that clones a just-pushed local remote by its plain path now clones it with clone_just_pushed, so the macOS failed to copy file race of #440 cannot reach it; load_without_bytecode keeps the doctor's and the Windows-path tests' loads of the family root's scripts from writing .pyc into the templates; the not-a-list doctor cases hold INVALID, exit 1; and GOOD_KEYS holds th #554's load_without_bytecode does not cover it; PYTHONDONTWRITEBYTECODE=1 in the renderer's child environment would.
• A staging name that already exists sends the moves astray (F5). Neither <Family>.folder (round 2) nor the older <Family>.holder is checked before it is printed. With <t>/InkRouter.folder already a folder, on an emulated disk that ignores case, both printed lines exit 0 and leave the holder at InkRouter/inkrouter/InkRouter (rv543b's probe). The next run stops again with a rename that works, so it is recoverable. The move text predates this PR; the stop is what makes it the only way forward.
• A dangling link named after the family breaks the staged move halfway (F6). not wanted.exists() follows the link, so a dangling <t>/InkRouter reads as nothing there: mv <t>/real-x/InkRouter <t>/InkRouter.holder exits 0, then mkdir -p <t>/InkRouter fails, File exists, and the holder is left at <t>/InkRouter.holder (rv543b's probe). os.path.lexists would send it to the two-line move, whose mkdir -p fails before anything moves. The move text predates this PR; the stop is what makes it the only way forward.
• tests/test_validator_child_encoding.py's launcher guard does not see family.py. It looks for subprocess.run([sys.executable, ...]), and family.py runs [sys.executable or PYTHON, ...], so the guard would not notice if env= were dropped again. The new S1 test catches that by behaviour (probe S1), but the static guard could list family.py too.

Closes #543

🤖 Generated with Claude Code

Summary by Sourcery

Make sibling placement safe and consistent by validating the family layout before cloning, selecting each member’s tracking branch, and running the holder’s pinned utility.

New Features:

• Make sibling placement validate the holder’s family-folder layout before cloning and support family folders reached through links or junctions.
• Clone new siblings on each member’s declared tracking branch when available, while safely falling back to the remote default branch for missing or invalid declarations.
• Run family.py siblings using the holder’s pinned sibling utility and reject holders missing that script.

Bug Fixes:

• Prevent misplaced-holder runs from creating stray clones that would be duplicated after relocation.
• Ensure printed relocation commands work for case-insensitive filesystems and filesystem or drive roots.
• Preserve escaped stdout behavior when the holder utility runs as a child process.
• Correct init --work-dir guidance so it no longer promises clones when no valid family folder exists.

Enhancements:

• Use non-local cloning to avoid sharing object files with path-based remotes.
• Expand sibling placement diagnostics for invalid tracking-branch values and link-based layouts.

Documentation:

• Update family guidance, generated holder documentation, and configuration comments to describe pre-clone validation, tracking branches, link-based layouts, and exit codes.

Tests:

• Add comprehensive coverage for placement validation, tracking-branch selection, safe relocation commands, link and junction handling, child-process behavior, and holder-script execution.

[brettheap]

(lane openRepoShape-5, 2026-10-14T23:37Z) @codex review

[chatgpt-codex-connector]

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

[sourcery-ai]

Reviewer's Guide

The PR updates sibling placement to validate the holder's folder before any side effects, clones new members on their pinned tracking branches with --no-local isolation, and makes family.py siblings run the holder's own pinned script in a subprocess; documentation and regression tests are updated for the new contracts.

Sequence diagram for sibling placement validation and cloning

sequenceDiagram
    participant User
    participant Siblings as siblings.py
    participant Git as git
    participant Member as members/Project/project.yaml

    User->>Siblings: main(--root, --dry-run?)
    Siblings->>Siblings: parent_folder_warning(root, family)
    alt parent folder is not named after family
        Siblings-->>User: WARNING, mv command, NOTHING WAS CLONED
        Siblings-->>User: exit 1
    else valid family folder
        Siblings->>Member: tracking_branch(root, row)
        alt tracking branch declared
            Member-->>Siblings: branch, project.yaml path
            Siblings->>Git: clone --no-local --branch=branch
        else branch unavailable locally
            Member-->>Siblings: default-branch reason
            Siblings->>Git: clone --no-local
        end
        Git-->>Siblings: clone result
        Siblings-->>User: placement result and exit code
    end

Loading

Sequence diagram for family.py siblings using the holder copy

sequenceDiagram
    participant User
    participant Family as family.py
    participant Holder as Holder
    participant Script as Holder/scripts/siblings.py

    User->>Family: cmd_siblings(--family-root, --dry-run?)
    Family->>Holder: check scripts/siblings.py
    alt script missing
        Family-->>User: Refusal siblings-script-missing
        Family-->>User: exit 2
    else script exists
        Family->>Script: subprocess.run(scripts/siblings.py, --root ., cwd=holder)
        Script-->>Family: exit code
        Family-->>User: return unchanged exit code
    end

Loading

Flow diagram for safe sibling placement

flowchart TD
    A[Start make siblings] --> B[Check holder parent folder]
    B -->|Not named after family| C[Print WARNING and mv command]
    C --> D[Print NOTHING WAS CLONED]
    D --> E[Exit 1]
    B -->|Named after family| F[Resolve credentials and member URLs]
    F --> G[Read member tracking_branch]
    G --> H[Clone with --no-local and --branch when known]
    H --> I[Run member bootstrap]
    I --> J[Report placement result]

Loading

File-Level Changes

Change	Details	Files
Prevent misplaced-holder runs from performing any placement work before the holder is moved into a correctly named family folder.	Run the parent-folder validation before credential resolution, URL discovery, cloning, or fetching, including for dry runs. Emit the existing warning and move commands with explicit no-clone messaging, then return exit code 1. Update the placement contract and documentation to describe the stop-before-cloning behavior.	templates/family-root/scripts/siblings.py AGENTS.md templates/family-root/AGENTS-shape.md templates/family-root/README.md tests/test_family.py tests/test_family_printed_quoting.py tests/test_family_makefile_siblings.py tests/test_family_siblings_placement.py
Clone absent siblings on each member's declared tracking branch while preserving a documented default-branch fallback and preventing local-object sharing.	Read tracking_branch from the pinned member project.yaml and pass it to git clone when available. Report the source of the branch decision and fall back to the remote default branch when the pinned manifest is unavailable or lacks a branch. Use --no-local for path-based remotes and report missing remote branches as clone findings without leaving partial directories.	templates/family-root/scripts/siblings.py templates/family-root/README.md tests/test_family_siblings_placement.py
Make family.py siblings execute the holder's pinned utility copy as a separate subprocess, matching the Makefile entry point and preserving its exit status.	Replace runpy execution of the standard template with the holder-relative scripts/siblings.py. Run with the holder as cwd, --root ., the selected interpreter, and optional --dry-run; return the subprocess status unchanged. Refuse holders missing their pinned siblings script with exit 2 and Makefile-compatible remediation text.	scripts/family.py tests/test_family.py tests/test_family_siblings_placement.py
Expand regression coverage for folder placement, branch selection, clone isolation, and holder-copy dispatch.	Add tests for tracking/upstream branches, fallback wording, nonexistent branches, dry-run output, and --no-local inode separation. Test the misplaced-holder stop and move-then-clone-once workflow, including dry runs. Test holder-specific imports and exact refusal behavior when the pinned script is absent.	tests/test_family_siblings_placement.py tests/test_family.py tests/test_family_printed_quoting.py tests/test_family_makefile_siblings.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#543	Check whether the holder is in a folder named after the family before cloning or fetching members; if not, warn, print the move instructions, and stop so moving the holder and rerunning does not leave duplicate clones.	✅
#543	Clone each new member on the tracking branch declared by its pinned project configuration, explain the default-branch fallback when that declaration is unavailable, and avoid unsafe local-path clone behavior.	✅
#543	Make family.py siblings run the holder’s pinned scripts/siblings.py copy, refusing clearly when that file is missing.	✅

Possibly linked issues

• make siblings and family.py siblings: clone each member on its tracking branch, warn before cloning outside a <Family> folder, and run the holder's pinned siblings.py #543: The PR addresses make siblings and family.py siblings: clone each member on its tracking branch, warn before cloning outside a <Family> folder, and run the holder's pinned siblings.py #543’s misplaced-folder duplicate-clone problem, tracking-branch selection, and holder-pinned script execution.
• Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459: Link: the PR directly fixes all three Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459 items—stopping before misplaced-folder clones, using member tracking branches, and running the holder’s pinned script.

---

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.

[sourcery-ai]

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

You can request another review in 1 day and 8 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[sonarqubecloud]

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