[brettheap]

Lane: openreposhape-5 (openRepoShape-5)
Claim: #441 (comment)
Claim: #442 (comment)

README change. This PR edits one README paragraph. #551 is on main and this branch has merged it, so the handbook step follows #551's rule: the three page parts that read the README section "The three legs" record its new hash. No page text changes.

What changed and why

#441: one bare tree answered for two links

link_pins_from_trees passed its default_source to every link of a recorded chain. That value is the naming gate's bare --link-source PATH, and the scaffold's --pin-source. In the chain openXdox → openYdox → openInk, with one bare tree that is openXdox's, openYdox was read from the same project.yaml. That file declares openYdox, not openInk, so the gate said "openYdox declares openYdox, not openInk". For codexInk, which holds no direct pin on its referent, that was a FINDING, exit 1, for a chain that holds. The scaffold refused the same chain as chain-not-declared.

Now:

• Which links read a bare value (for --pin-source in scaffold-project.py and adopt-project.py: accepted without --pin, and committed into digest_source as typed #540 and anyone else relying on it): only the FIRST link of each chain, links[0], the pin the project holds. That is true for a chain of any length, one link included: a chain of one link has only its first link, and that link reads the bare tree as before. A later link is never offered the bare value. It is read from its own LINK=PATH, its SHAPE_PIN_SOURCE_<LINK> or a checkout beside the project; otherwise it is declared-unverified (a warning, exit 0). For the first link the order is unchanged: keyed, variable, checkout beside the project, then the bare value.
• link_pins_from_trees and resolve_link_source keep their signatures and return shapes. The only code change in repo_shape.py is None if index else default_source in the loop.
• The two-link case (openXdox → openDox with a bare path) reads exactly as before and prints the same lines. The one difference is inside the returned mapping, and only for a chain of two or more links: the chain's END link no longer gets an entry read from the bare tree. Nothing reads that entry; only holders' declarations are read. In a chain of one link the only link is both the first and the end, and it still reads the bare tree, as before.
• In the naming gate, LinkSources finds the first link of every chain a name will READ before any chain is read. _first_links_read uses the same reads_link_declarations test the lookup uses, and counts a chain only if it has two or more links: a chain of one link has no holder, reads no declaration, and so has no first link to count. The bare value is offered only while there is at most one first link: with a lone one-link chain there are none, and the bare tree is still returned for that chain's link to read, as before (nothing reads what it finds, so the output is unchanged). If a run reads two chains that begin at different links (a name on the command line plus --project, or one project with two legs), the bare value is read for neither. Before, one tree answered both, and used counted it once.
• A bare value no link took is a NOTE saying why. In a two-link run the sentence is the one it always was. In a longer chain it reads "a bare PATH is the tree of a chain's first link alone, openXdox, which had a more specific source (...)". With two first links it reads "the chains read here begin at openXdox, openYdox: name the link it is, as --link-source =PATH".

#442: an empty path was the current directory

--link-source openXdox= and --pin-source openXdox= became Path(""), which is .. From a project root, the naming gate read the project's own manifest as openXdox's and called the chain broken. validate-pins.py asked the project root for the pinned commit, and its finding blamed ..

Now both tools refuse, exit 2, naming the key:

REFUSED link-source-no-path: `--link-source openXdox=` names no path for openXdox. An empty path would be read as the directory this runs in. Give the tree's path (`--link-source <link>=<path>`), or `.` to mean this directory.
REFUSED pin-source-no-path: `--pin-source openXdox=` names no path for openXdox. An empty path would be read as the directory this runs in.
Remediation: give the checkout's path (`--pin-source <product>=<path>`), or `.` to mean this directory.

• An empty bare value (--link-source '', --pin-source '') is refused the same way.
• A typed . still means the current directory.
• A value whose key is NOT a chain link or a declared pin (openZdox=) is still the bare PATH openZdox=, as scripts/validate-repository-naming.py: _link_sources_from_args splits every --link-source value at its first = and nothing reports a value no chain link used, so a link tree under a directory named a=b, or behind a mistyped key, is silently skipped (declared-unverified, exit 0), and repo_shape.link_manifest_path lets a source this user cannot enter (keyed, SHAPE_PIN_SOURCE_<LINK> or a sibling checkout) end the naming gate in a PermissionError traceback before Python 3.14 #338 and templates/assembly-root/scripts/validate-pins.py: a bare --pin-source <path> whose path holds an = is read as <product>=<path> (raw.partition("=")), so a stand-in clone under a directory named a=b is never consulted and the pin's digest silently goes to gh api and a skip (pins ok, exit 0), or, when the text before the = is a declared pin's name, to a FileNotFoundError traceback #295 decided. It is not empty, so it is not refused.
• Behaviour change: an empty value is refused even when a later value replaces it. --link-source openXdox= --link-source openXdox=<tree> was a NOTE ("the later --link-source ... replaced it"), exit 0. It is now REFUSED link-source-no-path, exit 2. validate-pins.py changes the same way: --pin-source openXdox= --pin-source openXdox=<clone> was pins ok, exit 0, and is now REFUSED pin-source-no-path, exit 2. A typo is a typo, and the refusal names it when it is typed; a script that passed an empty value first and the real one after must drop the empty one.
• The naming gate refuses in main, right after the values are read and before stdin is read or any name is classified, like its own REFUSED naming-no-target.
• validate-pins.py raises a Refusal from PinSources. It reaches main's existing handler with its own remedy, not the lockstep one. It is raised late: PinSources is built inside _check_neutral_product_pins, which _run_all_checks calls after _check_leg and _check_shape_pin. So an earlier refusal wins: a damaged contracts/spec-pin.yaml plus --pin-source openXdox= prints REFUSED pin-tag-only, and the empty path is named on the run after that is fixed. The hunk stays inside PinSources on purpose, to stay clear of the lines Pinned validators: THE LOCKSTEP RULE only where it applies, and remedies that name the git switch -c step (one shape bump) #539 edits in _run_all_checks. The refusal also has to wait for the declared pins, because they decide whether openXdox= is keyed or a bare PATH. Nothing is printed before the refusal, and the exit is 2 as in every other refusal of that tool.

Docs

• --help for --link-source, the naming validator's module docstring (exit code 2 included), resolve_link_source's rule 4, link_pins_from_trees's docstring and the scaffold's _declaration docstring say what a bare value means in a longer chain.
• The --link-source help also says that a bare PATH is read for neither link when the chains read begin at two different links, and that a later link is read from its own PRODUCT=PATH, its SHAPE_PIN_SOURCE_<PRODUCT> or a checkout beside the project (it said "needs its own PRODUCT=PATH").
• docs/cli.md is regenerated.
• README's lookup-order sentence now reads "then a bare --link-source <path>, for the first link's tree only: the order validate-pins.py uses below for the same checkout." The paragraph keeps its 12 lines, and README stays at 1422 lines.
• The handbook names no --link-source. The three parts that read "The three legs" (the masthead, "Reading private legs in CI", "The three legs, and naming") move to that section's new hash, 6ebed796 → 39ec2c23. No other README section changed.
• validate-pins.py's --help and EXIT CODES docstring do not name pin-source-no-path. Nothing in them is false: the exit-2 list gives examples. I left them, because the module docstring sits near lines Pinned validators: THE LOCKSTEP RULE only where it applies, and remedies that name the git switch -c step (one shape bump) #539 edits.

Fix round (commit 31a6f21, one commit on the head 04c9d77)

The review of 04c9d77 (APPROVE WITH NITS) found five nits. Each, and what this commit does:

1. A chain of one link counted as a first link. --referent-chain openInk beside a project whose leg records openXdox → openQuill, with a bare openXdox tree, gave two first links, so the bare tree went to neither. codexQuill, verified through it on bfed143, was declared-unverified, with a NOTE naming openInk as a first link. Both places now count chain[0] only when the chain has more than one link: _first_links_read, and the firsts update in LinkSources.link_pins. The run is verified again, with no WARNING and no NOTE, as on bfed143. New test test_a_chain_of_one_link_is_no_first_link_read.
2. A test gap: the project half of _first_links_read. Reverting if data is not None: to if False: (mutation M14) left all 20 tests passing, yet it changes the output for one project whose two legs begin at different links: the first classification pass counted the bare value used, and the NOTE went missing. New test test_a_project_whose_legs_begin_at_two_links_reads_a_bare_tree_for_neither: openXdox → openInk and openYdox → openQuill in one project, a bare openXdox tree, two WARNINGs and the two-first-links NOTE. M14 now fails it (see the mutation probes).
3. pin-source-no-path is raised late in validate-pins.py. No code change. The behaviour and the reason are written above, under scripts/validate-repository-naming.py _link_sources_from_args (:406) and templates/assembly-root/scripts/validate-pins.py PinSources (:409): a key with an empty path (--link-source openXdox=, --pin-source openXdox=) is Path(""), which is the current directory, so run from a project root the naming gate reads the project's OWN project.yaml as the link's declaration and reports a chain that holds as broken, a FINDING (exit 1) for a name with no direct pin #442.
4. The --link-source help. It now says a bare PATH is read for neither link when the chains read begin at two different links, and "needs its own PRODUCT=PATH" now names the variable and the checkout beside the project too. docs/cli.md is regenerated, and render-cli-reference.py --check is ok.
5. This body. It now says: Pinned validators: THE LOCKSTEP RULE only where it applies, and remedies that name the git switch -c step (one shape bump) #539 is on origin and merges clean (see the merge checks); an empty value is refused even when a later one replaces it; the END-link sentence holds for chains of two or more links; and the checklist candidate below.

The commit changes scripts/validate-repository-naming.py, docs/cli.md and tests/test_link_source_chain_defaults.py only.

Fix round 3 (commit a707d4b, one commit on 31a6f21)

The re-review of 31a6f21 (APPROVE WITH NITS) found that all five nits are fixed, and two new ones. This commit changes tests/test_link_source_chain_defaults.py only.

• A test gap at the two-link boundary of link_pins. Changing if len(target.chain) > 1: there to > 2 passed the whole new file and tests/test_naming_policy.py (264 passed), yet it changes the output for a name read from stdin whose chain has two links: the first-link list is empty, and the NOTE for an unused bare value reads "a bare PATH is the tree of a chain's first link alone, , which had a more specific source". New test test_a_two_link_chain_read_from_stdin_counts_its_first_link: stdin codexInk, --referent-chain openXdox,openInk, openXdox=<tree> keyed and a second tree bare, asserting the whole stderr, the one NOTE "each link whose own declaration is read had a more specific source (...)". The > 2 mutant fails it (see the mutation probes). The existing three-link stdin test and the new one share a helper, stdin_naming.
• This body. "exactly one first link" now reads "at most one", and the merge paragraph names the current main.

Decisions and evidence

• First link only, not a refusal. The coordinator recommended this rule. Nothing documented or tested depended on a bare value answering a later link: no test passes default_source to link_pins_from_trees, and every scaffold test with a three-link chain sets SHAPE_PIN_SOURCE_<LINK> for each link. A refusal "when more than one link would take it" would depend on what is on the disk (checkouts beside the project, variables). scripts/validate-repository-naming.py: _link_sources_from_args splits every --link-source value at its first = and nothing reports a value no chain link used, so a link tree under a directory named a=b, or behind a mistyped key, is silently skipped (declared-unverified, exit 0), and repo_shape.link_manifest_path lets a source this user cannot enter (keyed, SHAPE_PIN_SOURCE_<LINK> or a sibling checkout) end the naming gate in a PermissionError traceback before Python 3.14 #338 ruled that the reading is decided by the chains, never by the disk.
• Refuse scripts/validate-repository-naming.py _link_sources_from_args (:406) and templates/assembly-root/scripts/validate-pins.py PinSources (:409): a key with an empty path (--link-source openXdox=, --pin-source openXdox=) is Path(""), which is the current directory, so run from a project root the naming gate reads the project's OWN project.yaml as the link's declaration and reports a chain that holds as broken, a FINDING (exit 1) for a name with no direct pin #442, not note it. A note would still have to stop the value reading .. A refusal names the typo when it is typed, and both tools already exit 2 for a question they cannot ask.
• The scaffold is fixed too. It reads its --pin-source through the same function, so its three-link refusal goes away (see the reproduction). Its --pin-source is the pinned product's checkout, which is the first link's tree.

Tests

New file tests/test_link_source_chain_defaults.py: 23 tests (22 until round 3). On bfed143, 17 fail and 5 pass (the controls: the one-link rows and the rows that already worked). On 04c9d77, the one-link test fails and the other 21 pass.

Targeted runs (each run9.sh: gh stub, bogus token, empty GH_CONFIG_DIR, git-filter-repo 2.47.0), on the head 31a6f21 unless a row says otherwise. Round 3 (head a707d4b) changes the new test file only, and its own run is the last row:

set	result
new file, naming policy, referent-chain links, pin-source env collisions, pin-source unreadable, CLI reference, repo hygiene, README sections, AGENTS.md codes, validate-pins without git, unreadable workflow	774 passed in 117.48s
manifest validator, scaffold pin and reuse, YAML flow quotes, neutral pin validator	205 passed in 91.75s
CLI reference alone	22 passed in 26.08s
template text placeholders, adopt plan leg-path help	187 passed in 87.54s
predicted merge with origin/main 7d9bec9 (tree 908b3214): repo hygiene, README sections, CLI reference, new file, naming policy	415 passed in 53.10s
round 3, head a707d4b: new file, naming policy, CLI reference	287 passed in 95.29s

Round 1 (head 73c4c255, before the merge of #551 and this commit; docs/handbook.html, README.md and the validators are unchanged by this commit apart from validate-repository-naming.py):

set	result
doctor, doctor validator rows, scaffold e2e, setup-project.py, setup.sh, adopt e2e, adopt pins, adopt spec-only, adopt submodules, adopt ignored shape files, adopt plan YAML quoting, adopt root symlinks, scaffold leg-path collisions, update-shape landing	27 failed, 1796 passed, 3 skipped in 1433.51s; every failure the same UnicodeDecodeError from a bytecode file my own py_compile probe had left in templates/assembly-root/scripts/__pycache__. With it removed, the two files that held all 27 (test_adopt_root_symlinks.py, test_scaffold_leg_path_collisions.py) gave 253 passed in 140.50s

The three skips are test_shape_doctor.py:9119, which runs only on a Windows host. None of those files passes --link-source, and the one-link change and the help text cannot change a run that gives no bare value.

The 27 failures. template_values() and its twin in test_scaffold_leg_path_collisions.py read every file under templates/assembly-root as UTF-8. A validate-pins.cpython-312.pyc had appeared there the second I ran python3 -m py_compile over the changed files. Its first byte is 0xcb, the 3.12 bytecode magic, which is the byte every failure names. CI never runs py_compile.

Reproductions (bfed143, then this head; local trees and remotes, gh stub first on PATH)

row	bfed143	this head
#441: one bare --link-source <openXdox tree>, chain openXdox → openYdox → openInk, codexInk	FINDING ... is broken (openYdox declares openYdox, not openInk), exit 1	domain-descendant/assembly, one declared-unverified WARNING for openYdox naming --link-source openYdox=<path>, exit 0
#441: each link keyed	exit 0	exit 0, unchanged
#441: no --link-source	two WARNINGs, exit 0	unchanged
#441, scaffold --dry-run, same chain, --pin-source <openXdox clone>	REFUSED chain-not-declared, exit 2	WARNING declared-unverified for openYdox, plan printed, exit 0
#441, one link: --referent-chain openInk beside a leg openXdox → openQuill, bare openXdox tree	no warnings, exit 0	the same: no warnings, exit 0 (04c9d77 printed a WARNING and a NOTE)
#441, one project, legs openXdox → openInk and openYdox → openQuill, bare openXdox tree	FINDING codexQuill: the declared chain openYdox → openQuill is broken (openYdox declares openInk, not openQuill), exit 1: the bare tree answered both first links	two WARNINGs and the two-first-links NOTE, exit 0
#442: --link-source openXdox= from the project root	FINDING ... (openXdox declares openXdox, not openInk), exit 1	REFUSED link-source-no-path, exit 2
#442: the same from another directory	WARNING about ., exit 0	REFUSED link-source-no-path, exit 2
#442: --link-source '' from the project root	FINDING, exit 1	REFUSED link-source-no-path, exit 2
#442: --link-source openXdox= --link-source openXdox=<tree>	NOTE "the later ... replaced it", exit 0	REFUSED link-source-no-path, exit 2 (the behaviour change above)
#442: --link-source openXdox=. from the project root	FINDING (reads the project's own manifest, as typed)	unchanged: a typed . is read
#442: --pin-source openXdox= (scaffolded codexDox)	FINDING neutral-pin-source-unreadable: ... . (--pin-source openXdox=...), exit 1	REFUSED pin-source-no-path, exit 2
#442: --pin-source ''	the same FINDING, exit 1	REFUSED pin-source-no-path, exit 2
#442: --pin-source openXdox= --pin-source openXdox=<clone>	pins ok, exit 0	REFUSED pin-source-no-path, exit 2
control: --pin-source openXdox=<clone>	pins ok, exit 0	unchanged

No row needs real GitHub. Round 1 ran every row except the two new ones and the two "a later value replaces it" rows. The one-link and two-legs rows are the new tests: on bfed143 the one-link test passes and the two-legs test fails; on 04c9d77 the one-link test fails and the two-legs test passes. The two "a later value replaces it" rows are the review's reproductions of bfed143 against 04c9d77; this commit does not change them.

Mutation probes

Each hunk was reverted alone in a throwaway worktree, and the new file run against it.

Round 1 (20 tests), every hunk fails at least one test:

hunk reverted	tests that fail
repo_shape.py: offer default_source to every link again	6: the long-chain row, the later-link NOTE, the stdin NOTE, the lookup [two] and [three], the scaffold
LinkSources._bare_path: drop the two-first-links gate	1: two chains beginning at two links
_not_asked_why: drop the two-first-links sentence	1: the same test
_not_asked_why: always the old two-link sentence	2: the later-link NOTE and the stdin NOTE
main: drop the link-source-no-path refusal	6: every --link-source no-path row
PinSources: drop the pin-source-no-path refusal	3: every --pin-source no-path row
link_pins: drop firsts.setdefault (stdin names)	1: the stdin NOTE
_first_links_read: return nothing	1: two chains beginning at two links
naming no_path: keyed values only	2: the two empty bare rows
pins no_path: keyed values only	1: the empty bare row

Round 2 (22 tests, head 31a6f21):

hunk reverted	tests that fail
_first_links_read: if data is not None: → if False: (the project's legs; the review's M14, which survived 04c9d77)	1: test_a_project_whose_legs_begin_at_two_links_reads_a_bare_tree_for_neither; stderr has the two WARNINGs and no NOTE
LinkSources.link_pins: count a one-link chain's first link again	1: test_a_chain_of_one_link_is_no_first_link_read
_first_links_read: count a one-link chain again	1: test_a_chain_of_one_link_is_no_first_link_read

Round 3 (23 tests, head a707d4b):

hunk changed	tests that fail
LinkSources.link_pins: if len(target.chain) > 1: → > 2 (the re-review's boundary mutant, which survived 31a6f21)	1: test_a_two_link_chain_read_from_stdin_counts_its_first_link (1 failed, 22 passed in 10.59s); stderr has "first link alone, , which had" where the test expects "each link whose own declaration is read had"

The existing test_a_link_source_no_link_used_is_a_note_and_changes_no_exit in tests/test_naming_policy.py holds the two-link NOTE sentence byte for byte, and it passes.

Merge checks (git merge-tree --write-tree, after git fetch)

• origin/main 9f80939 (it holds the README, handbook and tests/readme-cap.d/550.txt of f6eaab7): clean. The re-review found it clean at 31a6f21 (tree 71ea0d30), and test_repo_hygiene.py, test_readme_sections.py and test_cli_reference.py gave 151 passed in 58.81s on that merged tree, with render-cli-reference.py --check ok. The README cap there is 1427 = 1422 + 5 from main's tests/readme-cap.d/550.txt, and this PR adds 0 README lines; its three handbook markers for "The three legs" are 39ec2c23 on the merged tree. a707d4b changes the test file only: merge-tree of it with 9f80939 is clean (tree dfc650f9). Earlier mains were clean too: 7d9bec9 (after shape-doctor.py: the machine row of a machine that is not ready names the preflight checks that failed, in the [!!] lines the preflight printed, so its reason no longer ends on this machine is not ready yet (see above). with nothing above it (#549) #552, shape-doctor.py: a git repository is told of both ways in, the adoption and the scaffold, and the adoption line ends --org <your-org> where its origin names no organisation plan can read, so pasting it is no longer refused adopt-no-org (#545) #553, 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, bump-leg.py: --dry-run gives the real run's answer, so --to an annotated tag's own id is peeled to the commit it names in both runs, and a pin layout the rewrite refuses is refused by the dry run too (#534, #438) #561 and update-shape.py: apply refuses to keep an --accept-local copy of 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; 415 passed on the merged tree) and bbcfd34 (tree 10acc9c0). The two docs/cli.md regenerations (this PR's --link-source help, bump-leg.py: --dry-run gives the real run's answer, so --to an annotated tag's own id is peeled to the commit it names in both runs, and a pin layout the rewrite refuses is refused by the dry run too (#534, #438) #561's bump-leg.py) touch different tools' sections.
• Lane 2's fix/539-validators-lockstep-remedies (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, 93b68f6), now on origin: clean. The reviewer ran the lockstep-lines test, the new file, test_validate_pins_without_git.py and test_validate_pins_unreadable_workflow.py on the merge with 04c9d77: 103 passed in 48.45s. This commit does not touch validate-pins.py or any of those tests. The validate-pins.py hunk stays inside PinSources, away from Pinned validators: THE LOCKSTEP RULE only where it applies, and remedies that name the git switch -c step (one shape bump) #539's regions (:99-544 and :1109-1143).
• Lane 2's fix/540-pin-source-unread (scaffold-project.py and adopt-project.py: a pin records digest_source: local-clone and never the --pin-source path, so no committed pin file holds a local directory, and a --pin-source nothing reads is pin-source-unused (#540) #570, 79dfd33): clean. On a merge with 04c9d77, the new file, test_pin_source_unreadable.py, test_scaffold_referent_chain_links.py, test_scaffold_leg_path_collisions.py, test_cli_reference.py and test_adopt_pins.py gave 371 passed. --pin-source in scaffold-project.py and adopt-project.py: accepted without --pin, and committed into digest_source as typed #540 counts any --referent-chain as a reader of --pin-source; that stays true, because every chain's first link reads it. One sentence of --pin-source in scaffold-project.py and adopt-project.py: accepted without --pin, and committed into digest_source as typed #540 needs a word once both are in: pin-source-unused says the clone is read for "each --referent-chain link's declaration" (scripts/shape_materialize.py:2706-2707 and the docstring at :2681-2683, and tests/test_pin_source_unreadable.py:445, the UNUSED text at :455-457 and :498). After this PR it is the FIRST link's alone. Whichever lands second should change "each" to "the first".
• The other PR heads bootstrap.py: a leg detached off the pin is left where it is and said, so a commit made there is no longer stranded when its branch is already at the pin, the not moving an existing branch line names where the checkout is, and bump-leg.py and AGENTS-shape.md say "or says why not" (#533) #556 to adopt-project.py: what plan, execute and AGENTS.md say around a run is what the run does: the plan's last follow-up is a review of the pull request execute opens itself, a failed verification names the pull request and the topic it left in place, AGENTS.md says check passes an answer with no resolution:, NEXT under --local-remote-dir names the split's branch, and the ruleset hint no longer calls a seed branch and a pull request the scaffold's other exit (#523) #582 that git still serves (23 heads; bump-leg.py: --dry-run gives the real run's answer, so --to an annotated tag's own id is peeled to the commit it names in both runs, and a pin layout the rewrite refuses is refused by the dry run too (#534, #438) #561 is on main): all clean, except install.sh and openRepoShape --install: one line, curl -fsSL https://github.com/opensoft/openRepoShape/releases/latest/download/install.sh | bash, installs the newest release pinned to it, with git-filter-repo, and ends with the preflight, and the installed command stays on its release (#564) #577 (install.sh, d0cdbf4). install.sh and openRepoShape --install: one line, curl -fsSL https://github.com/opensoft/openRepoShape/releases/latest/download/install.sh | bash, installs the newest release pinned to it, with git-filter-repo, and ends with the preflight, and the installed command stays on its release (#564) #577 conflicts with main itself, in docs/handbook.html and tests/test_repo_hygiene.py; against this head the same two files conflict. This PR is not the cause. Both edit README.md and the handbook's hash markers, so they land one at a time. Only 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 touches a file this PR changes (validate-pins.py, clean).
• Lane 5's other branches: family.py: bump --to asks add's duplicate-id question, peels an annotated tag's own id as add --at does, and says to push first a commit the member does not hold after its fetch (#541) #568 fix/family-bump-to-checks 8024f9c, family.py: remove and add refuse a .gitmodules the work tree does not have as the index has it (missing, unstaged, untracked, or behind assume-unchanged or a sparse checkout), so neither commits a change to it nobody staged (#407) #571 fix/family-remove-gitmodules-missing b1120c3, family.py: add refuses, before the member is read and on every disk, any path under another spelling of members/, in its index, in HEAD or on disk, and names a remedy per entry that never moves the members' checkouts (#362, #363, #364) #574 fix/family-members-case-variants 40eda84 and siblings.py and family.py: make siblings asks about the family folder before it clones, clones each member on its tracking branch, and family.py siblings runs the holder's own copy (#543) #578 fix/family-siblings-tracking-branch 43d32eb: clean.

Left out

• The scaffold's and adopt-project.py's own --pin-source '' (see the checklist candidates).
• validate-pins.py's --help and module docstring: nothing in them became false, and the module docstring sits near lines Pinned validators: THE LOCKSTEP RULE only where it applies, and remedies that name the git switch -c step (one shape bump) #539 edits.
• Making validate-pins.py refuse the empty path before its leg and shape-pin checks: it would put the hunk in _run_all_checks, where Pinned validators: THE LOCKSTEP RULE only where it applies, and remedies that name the git switch -c step (one shape bump) #539 edits.
• The v1.0.0 release notes keep scripts/repo_shape.py resolve_link_source (:2401-2402) and scripts/validate-repository-naming.py _link_sources_from_args (:408): a bare --link-source <path> answers for EVERY chain link that has no more specific source, so in a chain of three or more links one tree is read as two links' declarations and a correct chain is reported broken, a FINDING (exit 1) for a name that holds no direct pin on its referent #441 and scripts/validate-repository-naming.py _link_sources_from_args (:406) and templates/assembly-root/scripts/validate-pins.py PinSources (:409): a key with an empty path (--link-source openXdox=, --pin-source openXdox=) is Path(""), which is the current directory, so run from a project root the naming gate reads the project's OWN project.yaml as the link's declaration and reports a chain that holds as broken, a FINDING (exit 1) for a name with no direct pin #442 as known limits of 1.0.0, which they are.

Checklist candidates

• scaffold-project.py and adopt-project.py: --pin-source '' is Path(""), so the current directory is read as the pinned product's clone. Both take --pin-source as type=Path, and shape_materialize.declared_pin_values computes the digest from it. The scaffold also hands it to link_pins_from_trees as the first link's tree. Run from the product's own clone, scaffold-project.py --pin openXdox@<sha> --pin-source '' --referent-chain openXdox,openDox --dry-run plans with local-clone (.), exit 0; run from anywhere else it reads whatever directory it stands in. This is scripts/validate-repository-naming.py _link_sources_from_args (:406) and templates/assembly-root/scripts/validate-pins.py PinSources (:409): a key with an empty path (--link-source openXdox=, --pin-source openXdox=) is Path(""), which is the current directory, so run from a project root the naming gate reads the project's OWN project.yaml as the link's declaration and reports a chain that holds as broken, a FINDING (exit 1) for a name with no direct pin #442's shape in the two tools that create a project, and neither was in scripts/validate-repository-naming.py _link_sources_from_args (:406) and templates/assembly-root/scripts/validate-pins.py PinSources (:409): a key with an empty path (--link-source openXdox=, --pin-source openXdox=) is Path(""), which is the current directory, so run from a project root the naming gate reads the project's OWN project.yaml as the link's declaration and reports a chain that holds as broken, a FINDING (exit 1) for a name with no direct pin #442. (The review confirmed it for the scaffold on the head; adopt-project.py was not re-run.)
• The scaffold's declared-unverified warning names remedies the scaffold does not have. It says "(a sibling checkout, SHAPE_PIN_SOURCE_, or --link-source = would let it be read)". scaffold-project.py has no --link-source (none in its --help) and reads no sibling checkout: link_pins_from_trees(chain, None, ...) at scaffold-project.py:799 passes no root. The text is _chain_link_findings' (scripts/repo_shape.py:1419). It was already printed on bfed143 for a two-link scaffold with no manifest. Since this PR, every chain of three or more links scaffolded with --pin-source alone prints it for the second link, where only SHAPE_PIN_SOURCE_<LINK> helps. The wording should name only the remedies the caller has.
• tests/test_cli_reference.py alone writes templates/family-root/scripts/__pycache__/bootstrap.cpython-312.pyc (proved on 04c9d77 and on two merged trees: 22 passed, then the file is there). A .pyc under templates/ breaks template_values() and its twin in test_scaffold_leg_path_collisions.py in any later adoption run in the same tree: round 1's 27 failures were the same kind of break, from a .pyc under templates/assembly-root. 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. It is outside scripts/repo_shape.py resolve_link_source (:2401-2402) and scripts/validate-repository-naming.py _link_sources_from_args (:408): a bare --link-source <path> answers for EVERY chain link that has no more specific source, so in a chain of three or more links one tree is read as two links' declarations and a correct chain is reported broken, a FINDING (exit 1) for a name that holds no direct pin on its referent #441 and scripts/validate-repository-naming.py _link_sources_from_args (:406) and templates/assembly-root/scripts/validate-pins.py PinSources (:409): a key with an empty path (--link-source openXdox=, --pin-source openXdox=) is Path(""), which is the current directory, so run from a project root the naming gate reads the project's OWN project.yaml as the link's declaration and reports a chain that holds as broken, a FINDING (exit 1) for a name with no direct pin #442, and is named here only.

Closes #441
Closes #442

🤖 Generated with Claude Code

Summary by Sourcery

Correct chain source resolution so bare paths validate only the first link and reject source values that do not name a path.

New Features:

• Define bare source paths as applying only to the first link of a referent chain, while requiring later links to use their own sources or remain declared-unverified.
• Refuse empty link-source and pin-source values with actionable exit-2 diagnostics.

Bug Fixes:

• Prevent a single bare source tree from being incorrectly reused to validate multiple chain links or chains beginning at different links.
• Prevent empty source values from being interpreted as the current directory.

Enhancements:

• Update source lookup documentation, scaffold guidance, CLI reference, and README guidance to describe first-link-only behavior and no-path refusals.

Documentation:

• Regenerate the CLI documentation and update handbook references for the revised README section.

Tests:

• Add comprehensive coverage for long, multi-link, stdin, project, scaffold, and empty-source scenarios, including boundary and mutation cases.

[brettheap]

(lane openRepoShape-5, 2026-10-14T23:34Z) @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 changes chain source resolution so a bare path can verify only a chain’s first link, avoids ambiguous reuse across chains with different first links, and explicitly refuses empty link/pin source values instead of reading the current directory; documentation and regression tests are updated accordingly.

Sequence diagram for first-link-only source resolution

sequenceDiagram
    participant Validator as NamingValidator
    participant Resolver as link_pins_from_trees
    participant Source as resolve_link_source
    participant Tree as FirstLinkTree
    participant LaterTree as LaterLinkSources

    Validator->>Resolver: link_pins_from_trees(chain, default_source)
    loop Each chain link
        Resolver->>Source: resolve_link_source(link, default_source)
        alt First link
            Source->>Tree: Read bare source as first link tree
            Tree-->>Source: Declaration or unreadable
        else Later link
            Source->>LaterTree: Read keyed, environment, or adjacent source
            LaterTree-->>Source: Declaration or unavailable
        end
        Source-->>Resolver: Source result
    end
    Resolver-->>Validator: Link declarations and warnings

Loading

Sequence diagram for refusing empty source paths

sequenceDiagram
    actor User
    participant Tool as NamingValidatorOrValidatePins
    participant Sources as LinkSourcesOrPinSources
    participant Main as ExistingMainHandler

    User->>Tool: --link-source LINK= or --pin-source LINK=
    Tool->>Sources: Parse source values
    Sources->>Sources: Detect empty path
    Sources-->>Main: Refusal link-source-no-path or pin-source-no-path
    Main-->>User: Exit 2 with remediation

Loading

Flow diagram for ambiguous bare source handling

flowchart TD
    A[Read chains used by this run] --> B[Find first link of each chain]
    B --> C{One distinct first link?}
    C -->|Yes| D[Offer bare PATH to that first link only]
    C -->|No| E[Do not offer bare PATH]
    D --> F[Record unused-source note if a specific source wins]
    E --> G[Ask for --link-source LINK=PATH]

Loading

File-Level Changes

Change	Details	Files
Restrict a bare source path to the first link in each referent chain, with deterministic handling when a run contains multiple chain starts.	Pass the default source only for index zero in shared chain lookup. Track chain first links before lookup and suppress bare-source use when multiple first links are read. Update unused-source NOTE explanations and scaffold documentation for the new lookup semantics.	scripts/repo_shape.py scripts/validate-repository-naming.py scaffold-project.py README.md docs/cli.md
Reject empty keyed and bare link or pin source values before they are interpreted as the current directory.	Add naming-validator refusal code and remediation for empty --link-source values. Raise validate-pins refusal with a product-specific remedy for empty --pin-source values. Preserve explicit . behavior and existing treatment of unknown keys.	scripts/validate-repository-naming.py templates/assembly-root/scripts/validate-pins.py docs/cli.md
Add focused regression coverage for long chains, multi-chain source selection, scaffold behavior, and empty-source refusals.	Cover first-link-only lookup across one-, two-, and three-link chains. Verify naming and pin validators' exit codes, diagnostics, controls, and stdin behavior. Exercise scaffold dry-run behavior and source-use NOTE output.	tests/test_link_source_chain_defaults.py
Regenerate and synchronize documentation references after clarifying bare-source semantics.	Update README lookup-order wording and generated CLI help. Refresh handbook README section hashes without changing handbook prose.	README.md docs/cli.md docs/handbook.html

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#441	Prevent a bare --link-source PATH from being used to read declarations for multiple links in a chain, so a valid three-or-more-link chain is not falsely reported as broken.	✅
#441	Ensure a bare source is not counted as the answer for multiple distinct chain starts, and document the bare-path rule for longer chains.	✅
#441	Add regression coverage for the reported long-chain case and confirm that explicit keyed sources still verify the chain.	✅
#442	Refuse empty keyed and bare --link-source and --pin-source values instead of converting them to the current directory, while preserving an explicitly typed . as a path.	✅
#442	Ensure a bare link-source path is used only for the first link of a chain, so it cannot be mistaken for a later link’s declaration and cause a false broken-chain result.	✅

---

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
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud