[brettheap]

Closes #909.

scripts/repo_shape.py, scripts/validate-repository-naming.py and templates/assembly-root/scripts/validate-manifest.py are pinned copies, so this change re-pins every project once. scripts/repo_shape.py is a family holder's pinned copy too, so every family holder re-pins it once as well.

What changed, by section

validate-manifest.py asks no reasons (U172)

• _chain_and_links now asks the lookup what it tried (tried=) and why a tree it reached could not be read (with_reasons=), as the naming gate asks. Both sit behind the guard remedies= already has (_library_takes_remedies): every library that takes remedies= (v1.1.0 and later) also takes tried= and with_reasons=. A v1.0.x library still gets the plain call and its own words.
• A source that is there is said, not offered. A set SHAPE_PIN_SOURCE_<LINK>, or a checkout beside the root (anything at that path), is named in the declared-unverified WARNING with the lookup's reason. Only a source that is not there is offered. Lane 2's three measurements now read differently:
  • an empty openXdox/ beside the root: (the openXdox beside this root, <path>, could not answer: it holds no project.yaml; SHAPE_PIN_SOURCE_OPENXDOX would let it be read);
  • the variable naming no folder: (SHAPE_PIN_SOURCE_OPENXDOX, <path>, could not answer: no such file or directory; a checkout of openXdox beside this root would let it be read);
  • nothing there: the words the chain WARNING offers --link-source to callers that do not take it (validate-manifest.py, setup's step (4)), and the naming gate prints --link-source values raw #661 gave, unchanged.
• A manifest beside the root that is not a declaration was "not reachable here". It is now "reached but could not be read as a declaration (/project.yaml: ...)", the library's own sentence (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).
• Decided here: the offer is filled in after the lookup. The words depend on what the lookup tried, so _link_remedies takes the lookup's tried and is written onto the answer's remedies once the lookup returns.
• Decided here: the copy imports nothing new. tests/test_pinned_copy_text.py::test_no_pinned_script_imports_what_an_older_library_lacks holds the rule that a root's copy imports nothing a kept library may lack. So validate-manifest spells _shown (as validate-pins.py and the naming gate already do) and SOURCE_ABSENT for itself. The existing _shown parity test now covers validate-manifest, and a new test holds SOURCE_ABSENT equal to repo_shape.LINK_SOURCE_ABSENT.
• One existing test changed. tests/test_naming_policy.py::test_the_projects_own_manifest_gate_keeps_its_warning_for_a_tree_it_reached held 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's scoping ("this change reaches the scaffold alone"). validate-manifest.py, repo_shape.py and scaffold-project.py: a chain source that is there and cannot answer is still offered, one SHAPE_PIN_SOURCE_* can answer for two chains, and a Kelvin-sign link is recorded as typed #909's Direction supersedes that, so the test is renamed ..._says_why_a_tree_it_reached_was_unread and asserts the reason.

The SHAPE_PIN_SOURCE_* guard is asked per chain (U113, U145)

• link_pins_from_trees takes a new keyword, run_products: every product the caller's run reads. It asks scripts/repo_shape.py: pin_source_env_name turns every character outside [A-Z0-9_] into _, so the neutral products open-glass, open_glass and open.glass share one SHAPE_PIN_SOURCE_OPEN_GLASS, and a project that pins two of them gets a neutral-pin-source-unreadable FINDING (exit 1) for whichever one the variable does not name #275's guard over those products as well as over the chain's links. A variable that two products of the run share is read for no chain. The answer is a LinkPins whose new env_shared attribute names those links, and _chain_link_findings offers the variable to none of them.
• The naming gate passes [*target.pins, *self.links] at :352. validate-manifest passes _run_products(pins, legs), built once in _findings and handed down through _leg_findings. Each passes the keyword only where its library takes it (_library_takes("run_products")), by the skew rule.
• R444's project now gives the same answer with the variable set and unset: exit 0, and each leg gets a declared-unverified WARNING that does not offer SHAPE_PIN_SOURCE_OPENSS. Before, the gate said FINDING codexQuill: the declared chain openss -> openQuill is broken (openss declares openInk, not openQuill), exit 1.
• Decided here: the scope is the Direction's second option, the declared pins plus every chain's links. The first option, every chain alone, leaves scripts/repo_shape.py: pin_source_env_name turns every character outside [A-Z0-9_] into _, so the neutral products open-glass, open_glass and open.glass share one SHAPE_PIN_SOURCE_OPEN_GLASS, and a project that pins two of them gets a neutral-pin-source-unreadable FINDING (exit 1) for whichever one the variable does not name #275's own rule ("a variable two declared products share answers for NEITHER, wherever it is read") broken for a chain: in a project pinning open + sharp s and openss, the chain beginning at openss still read the variable while the other pin sits on no chain. A test holds that row.
• Decided here: "every chain" means every chain a leg records (and --referent-chain's), not only the chains a classification consults. This matches what the gate's LinkSources.links already holds and what validate-manifest reads, so the two gates make validate runs give one answer. A test holds a spec leg's chain sharing the variable.
• Decided here: callers pass the products, not a precomputed set. Both copies can then pass the keyword without importing pin_source_env_shared (the gate does not import it, and its import block is setup-project.py and validate-repository-naming.py: step (4) reads and names what step (5) does, --link-remedy reads a link holding =, strips its words and notes an unused one, and the Windows hand clone passes -c core.autocrlf=false (#907, #926) #949's neighbour). The guard is asked at each lookup over the same products, so every chain of a run gets the same answer.
• The scaffold passes no run_products. It reads one chain. Its first link is a --pin, and its later links are open<Product> names, ASCII letters and digits, which share a variable with a --pin only where they are the same pin file. _refuse_colliding_pins already refuses two --pins that share one.

A Kelvin-sign link is recorded as typed (U114, U146)

• referent_chain_links(raw, pins=()) spells a first link that equals a --pin under pin_product_key in that pin's spelling, keeping an owner typed before it. --pin openKdox@<sha> --referent-chain 'open<U+212A>dox,openInk' now plans and records openKdox -> openInk. A first link that differs from its pin by ASCII case alone is spelled as the pin too.
• Decided here: only _declaration passes the pins. That is the reading that is checked, printed and recorded. The two readings before it (refuse_an_unread_pin_source, which asks only whether there is a chain, and _refuse_malformed_chain_links, which judges the middle links) keep the typed spelling, so those refusals quote the flag as typed.
• pin_product_key is imported inside referent_chain_links, beside its one use, so the module's import block stays untouched for scaffold-project.py, family.py init and shape_materialize.py: the plan names the tracking branch, and on disk the visibility; an unread root or reused leg is said to be unread, the root before the plan; every holder gets the members' NOTE (#913) #969, scaffold-project.py: a first scaffold's pushes and a --reuse-empty-repo re-run's pushes and seed fetch no longer ask at the terminal: a push git has no login for fails naming the fix, and a leg git reaches over ssh is refused with ssh's reason (#915) #971 and scaffold-project.py and family.py init: a flag passed empty is refused by name, a passed --id is told what an id may hold once the name passes, and an empty folder this user cannot list is told the permission (#911, #930) #972, which edit this file.

Where the diff goes past the brief's line ranges

• validate-manifest.py: besides :178-250 (_chain_and_links, _link_remedies, _library_takes_remedies and the new helpers beside them), _leg_findings takes run_products (:832-866), and _findings builds it once before its loop (:1067-1070). The run's products cannot be known inside _chain_and_links, which sees one leg. Lane 5's slice D (:86-115, :396-406, :1085-1101) is untouched, and the merge with the assembly root's validate-manifest.py and bootstrap.py: a path this user cannot read is named, never read as absent, so a scripts/ nobody may search no longer SKIPs every validator into bootstrap ok (#430, slice D) #958 is clean (below).
• scaffold-project.py: :1071-1075, and one line at :1164, where _declaration passes the pins.
• validate-repository-naming.py: the call at :352, and a _library_takes(keyword) helper placed between Target and LinkSources, away from setup-project.py and validate-repository-naming.py: step (4) reads and names what step (5) does, --link-remedy reads a link holding =, strips its words and notes an unused one, and the Windows hand clone passes -c core.autocrlf=false (#907, #926) #949's hunks.

Out of scope

• validate-manifest.py, repo_shape.py and scaffold-project.py: a chain source that is there and cannot answer is still offered, one SHAPE_PIN_SOURCE_* can answer for two chains, and a Kelvin-sign link is recorded as typed #909 has no "Needs a ruling" or "Documented limit" section.
• validate-manifest says a source only in the WARNING for a link it could not verify, so it adds no line and no code. A variable that could not answer while a checkout beside the root did is said by the naming gate's link-source-unreadable WARNING, which make validate runs first.
• The naming gate still treats a checkout beside the project that holds no project.yaml as the ordinary case. U172 is validate-manifest's line.
• scripts/shape_materialize.py (scaffold_link_remedies) is not in this change's files and is unchanged. It cites _library_takes_remedies, which keeps its name.

Tests

Each run used a stub gh first on PATH (exit 97), GH_TOKEN=bogus and an empty GH_CONFIG_DIR: /usr/bin/python3 -m pytest -q -p no:cacheprovider --basetemp=<scratch>/bt-<run> -o tmp_path_retention_policy=failed <files>, one process at a time. Every run but the doctor's was on this head.

• New and core chain files: tests/test_chain_pin_sources.py tests/test_chain_remedy_callers.py tests/test_chain_link_fold.py tests/test_link_source_chain_defaults.py tests/test_pin_source_env_collisions.py tests/test_pin_source_unreadable.py tests/test_naming_policy.py tests/test_scaffold_referent_chain_links.py tests/test_pinned_copy_text.py tests/test_manifest_validator.py: 798 passed in 141.82s (0:02:21)
• Docs guards: tests/test_agents_md_codes.py tests/test_cli_reference.py tests/test_update_add_codes_documented.py tests/test_repo_hygiene.py tests/test_no_auto_maintenance.py: 217 passed in 43.50s
• Other files that run the changed readers: tests/test_legs_not_a_list.py tests/test_non_list_project_fields.py tests/test_reader_refusals_named.py tests/test_yaml_flow_quotes.py tests/test_scaffold_pin_and_reuse.py tests/test_scaffold_e2e.py tests/test_template_text_placeholders.py tests/test_update_shape_kept_helper.py tests/test_doctor_validator_verdicts.py tests/test_setup_project_py.py: 919 passed in 516.14s (0:08:36)
• Adopt files that run the naming gate: tests/test_adopt_e2e.py tests/test_adopt_nested_attributes.py tests/test_adopt_pins.py tests/test_adopt_reencoded_files.py tests/test_adopt_spec_only.py tests/test_adopt_submodules.py: 486 passed in 528.58s (0:08:48)
• tests/test_shape_doctor.py, run once, as the brief allows, on the pre-rebase commit cd4eaba7: 445 passed, 3 skipped in 714.12s (0:11:54). The rebase brought main's 2f5cabf5, which touches repo_shape.py only in tree_digest_from_gh and next to find_repo_root, nowhere near the chain readers.

Mutants

Each one breaks a fixed line, runs the named tests, and restores the file. All 21 were killed.

#	File	Mutation	Killed by
M1	validate-manifest	drop tried=tried	test_a_source_that_is_there_is_said_and_not_offered (4 rows)
M2	validate-manifest	drop with_reasons=True	test_a_manifest_beside_the_root_that_is_not_a_declaration_says_why
M3	validate-manifest	an absent checkout counted as there	test_with_nothing_there_both_sources_are_offered
M4	validate-manifest	path not spelled (_shown)	test_a_variable_holding_a_control_character_is_spelled
M5	validate-manifest	a set variable still offered	test_a_source_that_is_there_is_said_and_not_offered (3 rows)
M6	validate-manifest	a checkout that is there still offered	test_a_source_that_is_there_is_said_and_not_offered (2 rows)
M7	validate-manifest	offer's guard over the chain alone	test_the_manifest_gate_reads_a_shared_variable_for_no_chain (4 rows)
M8	validate-manifest	_run_products without the pins	test_the_manifest_gate_reads_a_shared_variable_for_no_chain[pin-*]
M9	validate-manifest	run_products never passed	test_the_manifest_gate_reads_a_shared_variable_for_no_chain[*-set]
M10	validate-manifest	run_products passed without the guard	test_both_copies_run_beside_a_library_with_no_run_products
M11	validate-manifest	offer not written onto remedies	test_a_source_that_is_there_is_said_and_not_offered (4 rows)
M12	repo_shape	guard over links alone	gate [set]/[unset], declared-pins, other-chain, manifest [*-set], library tests (7)
M13	repo_shape	_chain_link_findings ignores env_shared	test_the_gate_reads_a_shared_variable_for_no_chain[set,unset]
M14	repo_shape	plain dict returned for run_products	the gate test (2 rows), test_the_library_asks_the_guard_over_the_run
M15	repo_shape	LinkPins built without env_shared	the gate test (2 rows), test_the_library_asks_the_guard_over_the_run
M16	naming gate	products without target.pins	test_a_variable_two_declared_pins_share_is_read_for_no_chain
M17	naming gate	products without the chains' links	test_a_variable_a_link_of_another_chain_shares_is_read_for_no_chain
M18	scaffold	no re-spelling	test_a_first_link_that_is_a_pin_is_spelled_as_the_pin (3 rows), plan and record tests
M19	scaffold	the owner prefix dropped	test_a_first_link_that_is_a_pin_is_spelled_as_the_pin[owner-kept]
M20	scaffold	_declaration passes no pins	test_the_plan_names_the_chain_in_the_pins_spelling, test_the_manifest_records_the_chain_in_the_pins_spelling
M21	scaffold	compared as typed, not by pin_product_key	test_a_first_link_that_is_a_pin_is_spelled_as_the_pin (3 rows)

Merges

git merge-tree --write-tree of this head with each:

• origin/main 66177b62: clean. The head is one commit behind; main's newest commit touches only tests/test_repo_hygiene.py.
• the assembly root's validate-manifest.py and bootstrap.py: a path this user cannot read is named, never read as absent, so a scripts/ nobody may search no longer SKIPs every validator into bootstrap ok (#430, slice D) #958 (lane 5, slice D, 0ef875c0, validate-manifest.py): clean
• setup-project.py and validate-repository-naming.py: step (4) reads and names what step (5) does, --link-remedy reads a link holding =, strips its words and notes an unused one, and the Windows hand clone passes -c core.autocrlf=false (#907, #926) #949 (8c5d6051, validate-repository-naming.py): clean
• scripts/repo_shape.py: the YAML reader refuses a key written twice in one mapping, block or flow, by the line of the second, and a block scalar line indented less than its first by its line, where it kept the last key and cut the line's first characters; such a line opening # ends the block as a comment (#917) #974 (W917, e63ca75c, repo_shape.py): clean
• scaffold-project.py and family.py init: a flag passed empty is refused by name, a passed --id is told what an id may hold once the name passes, and an empty folder this user cannot list is told the permission (#911, #930) #972 (W911, 0094731b, scaffold-project.py): clean
• scaffold-project.py: a first scaffold's pushes and a --reuse-empty-repo re-run's pushes and seed fetch no longer ask at the terminal: a push git has no login for fails naming the fix, and a leg git reaches over ssh is refused with ssh's reason (#915) #971 (W915, e40af32d, scaffold-project.py): clean
• scaffold-project.py, family.py init and shape_materialize.py: the plan names the tracking branch, and on disk the visibility; an unread root or reused leg is said to be unread, the root before the plan; every holder gets the members' NOTE (#913) #969 (W913, f3802d6f, scaffold-project.py): clean

Fix round 1

On RV981's review (issuecomment-6254819059), head 499f7baa, one commit on ac5b5307.

• S1. The Kelvin fix changes which variable is read for the first link, and a test now holds it. As typed, open<U+212A>dox was read through SHAPE_PIN_SOURCE_OPEN_DOX. The Kelvin sign is upper case and outside [A-Z0-9_], so pin_source_env_name turns it into _, and that is the variable of open-dox, open_dox and open.dox. On main, that variable set to a tree declaring openQuill refused a chain that holds (chain-not-declared, exit 2), and the WARNING offered that variable. The link is the pin openKdox now, so SHAPE_PIN_SOURCE_OPENKDOX is read for it, before --pin-source. U114 was therefore not only cosmetic. Two dry-run rows in tests/test_chain_pin_sources.py hold both directions:
  • SHAPE_PIN_SOURCE_OPEN_DOX set to that tree: exit 0, no Kelvin sign in the output;
  • SHAPE_PIN_SOURCE_OPENKDOX set to it: chain-not-declared.
• S2. test_the_manifest_gate_reads_a_shared_variable_for_no_chain has a qualified-chain row: the spec leg's chain begins at opensoft/ + open + U+00DF. validate-manifest hands its products over as the manifest spells them, so the library's repo_basename on run_products is now held.
• N1. SOURCE_ABSENT's comment says every tagged library has LINK_SOURCE_ABSENT and the naming gate imports it. The local copy keeps validate-manifest's import block clear of the assembly root's validate-manifest.py and bootstrap.py: a path this user cannot read is named, never read as absent, so a scripts/ nobody may search no longer SKIPs every validator into bootstrap ok (#430, slice D) #958.
• N2. The re-pin line above now says every family holder re-pins repo_shape.py once too.
• N3. _run_products' docstring says it counts the chain of a leg whose repository: is bad or missing, which the gate's _project_chain_links leaves out. Such a leg is a finding in both gates.
• N4 is lane 3's follow-up, and N5 is not in this round.

Tests

Same command and stub gh as above, plus GIT_SSH_COMMAND=false. All runs are on 499f7baa.

• tests/test_chain_pin_sources.py (the one test file changed): 32 passed in 8.54s
• The same file with the core chain files (tests/test_chain_remedy_callers.py tests/test_chain_link_fold.py tests/test_link_source_chain_defaults.py tests/test_pin_source_env_collisions.py tests/test_pin_source_unreadable.py tests/test_naming_policy.py tests/test_scaffold_referent_chain_links.py tests/test_pinned_copy_text.py tests/test_manifest_validator.py): 802 passed in 133.08s (0:02:13)
• Docs guards and tests/test_no_auto_maintenance.py: 217 passed in 49.73s

Mutants

All are now killed:

#	Mutation	Killed by
A1	the library drops repo_basename on run_products	test_the_manifest_gate_reads_a_shared_variable_for_no_chain[qualified-chain-set]
A2	the scaffold records the pin's spelling but reads the typed chain	test_the_kelvin_link_is_not_read_through_another_products_variable, test_the_kelvin_link_is_read_through_its_pins_variable
M5 (re-made)	a set variable still offered	test_a_source_that_is_there_is_said_and_not_offered (3 rows)
M12 (re-made)	the guard asked over links alone	8 rows: the gate's set/unset, declared-pins and other-chain tests, the manifest gate's three *-set rows, and the library test

Merges

git merge-tree --write-tree of 499f7baa:

• origin/main cf66102f: clean
• scripts/repo_shape.py: the YAML reader refuses a key written twice in one mapping, block or flow, by the line of the second, and a block scalar line indented less than its first by its line, where it kept the last key and cut the line's first characters; such a line opening # ends the block as a comment (#917) #974 e63ca75c: clean
• setup-project.py and validate-repository-naming.py: step (4) reads and names what step (5) does, --link-remedy reads a link holding =, strips its words and notes an unused one, and the Windows hand clone passes -c core.autocrlf=false (#907, #926) #949 ced3d7c2: clean
• scaffold-project.py: a first scaffold's pushes and a --reuse-empty-repo re-run's pushes and seed fetch no longer ask at the terminal: a push git has no login for fails naming the fix, and a leg git reaches over ssh is refused with ssh's reason (#915) #971 155fcd2d: clean
• scaffold-project.py and family.py init: a flag passed empty is refused by name, a passed --id is told what an id may hold once the name passes, and an empty folder this user cannot list is told the permission (#911, #930) #972 0094731b: clean

Summary by Sourcery

Improve chain-source diagnostics and scope pin-source reads per validation run while preserving declared-pin spelling in scaffolded chains.

New Features:

• Make manifest validation explain why reachable chain sources could not be read and offer only sources that are genuinely absent.
• Coordinate pin-source environment handling across all products and recorded chains in a validation run.
• Record scaffolded referent-chain first links using the spelling of their matching declared pins.

Bug Fixes:

• Prevent shared SHAPE_PIN_SOURCE_* variables from being consumed by multiple products or chains.
• Preserve correct pin spelling for case-insensitive and Kelvin-sign referent-chain matches.

Enhancements:

• Keep pinned validator copies compatible with older repo_shape libraries while adopting the new lookup metadata.

Tests:

• Add comprehensive coverage for source diagnostics, run-wide environment collisions, library-version skew, and pin-spelling behavior.

Chores:

• Re-pin the affected project validator copies.

Lane: openreposhape-3 (openRepoShape-3)
🤖 Generated with Claude Code

[sourcery-ai]

Reviewer's Guide

Updates the pinned chain readers and scaffold to provide reasoned source diagnostics, apply SHAPE_PIN_SOURCE collision rules across all products in a run, remain compatible with older repo_shape libraries, and record first chain links in their --pin spelling.

Sequence diagram for run-wide chain source lookup

sequenceDiagram
    participant Caller
    participant ChainReader as link_pins_from_trees
    participant Guard as pin_source_env_shared
    participant Findings as _chain_link_findings

    Caller->>ChainReader: link_pins_from_trees(links, run_products)
    ChainReader->>Guard: pin_source_env_shared(links + run_products)
    Guard-->>ChainReader: env_shared
    ChainReader-->>Caller: LinkPins(found, unreadable, remedies, env_shared)
    Caller->>Findings: _chain_link_findings(chain, link_pins)
    Findings->>Findings: omit shared SHAPE_PIN_SOURCE_* offers
    Findings-->>Caller: declared-unverified warnings

Loading

Sequence diagram for reasoned manifest source diagnostics

sequenceDiagram
    participant Validator as validate-manifest.py
    participant Lookup as link_pins_from_trees
    participant Remedies as _link_remedies
    participant Findings as _chain_link_findings

    Validator->>Lookup: link_pins_from_trees(chain, tried, with_reasons, run_products)
    Lookup-->>Validator: tried and unreadable source reasons
    Validator->>Remedies: _link_remedies(chain, tried, run_products)
    Remedies-->>Validator: say sources that exist, offer only absent sources
    Validator->>Findings: classify(chain, link_pins)
    Findings-->>Validator: declared-unverified warning with reasoned remedy

Loading

Flow diagram for pin spelling of the first referent link

flowchart LR
    Raw["--referent-chain first link"] --> Split[referent_chain_links]
    Split --> Key[pin_product_key comparison]
    Key -->|matches --pin| Spelling[Use --pin spelling and keep owner prefix]
    Key -->|no match| Typed[Keep typed link]
    Spelling --> Declaration[_declaration records chain]
    Typed --> Declaration

Loading

File-Level Changes

Change	Details	Files
Improves manifest chain diagnostics so sources that exist are reported with lookup reasons instead of being offered as remedies.	Passes lookup-tracking and unreadable-tree reason data when supported by the pinned library. Builds remedies after lookup completion, offering only sources that are absent. Adds printable path handling and keeps absence wording synchronized with the library. Propagates run-wide product information through manifest leg processing.	templates/assembly-root/scripts/validate-manifest.py tests/test_chain_pin_sources.py tests/test_naming_policy.py tests/test_pinned_copy_text.py
Makes pin-source environment collision handling consistent across all products read by a validation run.	Adds run_products support to link_pins_from_trees and records shared variables in LinkPins.env_shared. Suppresses warnings' offers for variables shared by declared pins or links from any recorded chain in the run. Adds compatibility checks so naming and manifest pinned copies only pass newer keywords when supported. Keeps scaffold behavior unchanged by omitting run_products for its single-chain lookup.	scripts/repo_shape.py scripts/validate-repository-naming.py templates/assembly-root/scripts/validate-manifest.py tests/test_chain_pin_sources.py
Normalizes a scaffold referent chain's first link to the spelling used by its matching --pin.	Matches the first link by pin_product_key, including case folding and Kelvin-sign normalization. Preserves any owner prefix while replacing only the product spelling. Passes declared pins into the declaration-time chain parsing so planning and manifest recording use the normalized spelling.	scaffold-project.py tests/test_chain_pin_sources.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#909	Have validate-manifest.py retain and report why a pin source that is present could not answer, offering only sources that are absent, while remaining compatible with older repo_shape.py copies.	✅
#909	Evaluate SHAPE_PIN_SOURCE_* collisions across all products read in a run, so a shared variable is not used or offered for any chain it could ambiguously answer.	✅
#909	When a scaffolded chain’s first link matches a --pin under pin_product_key, record and display it using the pin’s spelling.	✅

---

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.

[brettheap]

(lane openRepoShape-3, 2026-10-18T20:33:50Z) RV981, independent review of #981 at head ac5b530 (opus, lane 3).

Verdict: READY. No MUST.

SHOULD
S1. The Kelvin fix also changes which variable the scaffold reads, and no test holds it. On main the first link open[U+212A]dox was read through SHAPE_PIN_SOURCE_OPEN_DOX, the variable of open-dox/open_dox/open.dox: with it naming a tree that declares openQuill, main refused a holding chain (chain-not-declared, exit 2), and the warning offered SHAPE_PIN_SOURCE_OPEN_DOX. The head reads and offers SHAPE_PIN_SOURCE_OPENKDOX. So U114's "cosmetic" was not true on main. Mutant "record the pin spelling but read the typed chain" in _declaration (scaffold-project.py:1181-1184) survives: 89 passed across test_chain_pin_sources.py, test_scaffold_referent_chain_links.py and test_chain_link_fold.py. Fix: a dry-run row with SHAPE_PIN_SOURCE_OPEN_DOX set to a tree declaring openQuill, expecting exit 0, and a line in the PR body.
S2. Nothing tests the run guard with an owner-qualified link. Mutant "drop repo_basename on run_products" (repo_shape.py:3321-3322) survives: 218 passed. In validate-manifest.py, whose _run_products passes links raw, it brings R444 back: a spec-leg chain [opensoft/open[U+00DF], openQuill] beside openss -> openDox goes from exit 0 to exit 1. Fix: add an opensoft/open[U+00DF] row to test_the_manifest_gate_reads_a_shared_variable_for_no_chain.

NIT
N1. validate-manifest.py:238-242: LINK_SOURCE_ABSENT is in every tagged library (cac6bb2, before v1.0.0) and the gate imports it. The local copy keeps the import block clear of #958; say that instead of #610.
N2. The PR body says every project re-pins once. repo_shape.py is a family holder's pinned copy too, so every holder does as well.
N3. _run_products counts chains of legs with a bad or missing repository:, which the gate's _project_chain_links leaves out. Harmless (both exit 1 there); reword the docstring.
N4. A set variable the guard passes over is named by no line. #275's existing behaviour; follow-up, not this PR.
N5. Later: the gate's _library_takes_remedies can call _library_takes once #949 lands, and pin_product_key's import in referent_chain_links can move to module level after #969/#971/#972.

Check 4: the _leg_findings/_findings plumbing is needed. Without it the root's own gate still reads the shared variable per chain (main: exit 1 with 4 FINDINGs; head: exit 0). Keep it.

Probes (stub gh, main vs head): an unreadable variable tree, a variable under a locked parent, an empty checkout beside the root and a locked one are each named with the system's reason, and only what is absent is offered. Absent, empty and dangling sources keep #661's words. Beside v1.0.1 / v1.1.0 / v1.1.1 libraries, no traceback. An ASCII pair, open-glass and open_glass, is fixed in both shapes. The reverse Kelvin --pin is refused pin-malformed on main and head.

Tests on the head: 364 passed (new and changed files), 434 passed (core chain files), 211 passed (docs guards), 445 passed and 3 skipped (test_shape_doctor.py). Merged with main: 215 passed. With #958: 263 passed. With #949: 414 passed, plus 33 setup step-four tests passed.
Mutants M5, M10, M12, M13, M17, M21: each killed. Mine, A1 and A2: survive (S2, S1).
merge-tree clean with main ebbd9fa, #958, lane 5 WIP b49f34e, #974, #949 ced3d7c, #969, #971 and #972.
Not done: pytest on the merges with #974/#969/#971/#972 and the lane 5 WIP; the writer's adopt and other-reader batches; Windows.

Lane 3: READY by ruling 8. S1 and S2 (two test gaps, mutants A2 and A1 survive) and N1 to N3 go into one fix round after lane 3's account swap, before #981 lands. N4 goes to a follow-up issue. RV981 stopped before running its last checks for the swap; the list above says which.

Lane: openreposhape-3 (openRepoShape-3)

[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

[brettheap]

(lane openRepoShape-3, 2026-10-19T11:58:44Z) RV981 round 2, independent review of #981 at head 499f7ba (one commit on ac5b530).

Verdict: READY.

Round-1 items:

• S1 fixed. The two dry-run rows hold both directions: SHAPE_PIN_SOURCE_OPEN_DOX set gives exit 0 and no Kelvin sign; SHAPE_PIN_SOURCE_OPENKDOX set gives chain-not-declared. Passing env by monkeypatching test_chain_link_fold.run_script is sound: scaffold_pinning looks the name up when it runs, the default import mode makes it the same module object pytest collected, and monkeypatch undoes it at teardown (precedent: test_github_limits_init_check_org.py:697). One process ran test_chain_pin_sources.py and then test_chain_link_fold.py: 802 passed, no leak.
• S2 fixed by the qualified-chain row.
• N1 and N2 fixed. N3 fixed, but see NIT 1. N4 and N5 deferred, accepted.

New:

• NIT 1. validate-manifest.py:228-231 says the gate's _project_chain_links leaves out a leg whose repository: is "bad or missing". It leaves out only a missing one ("repository" in leg, validate-repository-naming.py:934-936). Say "missing". Harmless.
• NIT 2, optional. The body's U172 bullet "the copy imports nothing new" still gives the Pinned shape copies: AGENTS-shape.md's CONTRACTS_DIR sentence is false for every scaffolded root, and the chain WARNING offers remedies the scaffold lacks (one shape bump before the v1.1.0 tag) #610 reason for SOURCE_ABSENT; the fix-round section corrects it.
• For scripts/repo_shape.py: the YAML reader refuses a key written twice in one mapping, block or flow, by the line of the second, and a block scalar line indented less than its first by its line, where it kept the last key and cut the line's first characters; such a line opening # ends the block as a comment (#917) #974, not this PR: tests/test_manifest_validator.py::test_a_missing_role_is_a_finding fails on scripts/repo_shape.py: the YAML reader refuses a key written twice in one mapping, block or flow, by the line of the second, and a block scalar line indented less than its first by its line, where it kept the last key and cut the line's first characters; such a line opening # ends the block as a comment (#917) #974's own head e63ca75 (exit 2, "key 'naming' is written twice", expected 1), and so on the merge with validate-manifest.py, validate-repository-naming.py, repo_shape.py and scaffold-project.py: a chain source that is there and cannot answer is named with why instead of offered, a SHAPE_PIN_SOURCE_* two products of one run share answers for no chain, and a first chain link that is a --pin is recorded in the pin's spelling (#909) #981 too.

Tests on 499f7ba (stub gh, one at a time): new file then the core chain files, 802 passed in 150.99s; docs guards including test_update_add_codes_documented.py, 217 passed in 48.76s. Merged with main cf66102: 180 passed. Merged with #974: 1 failed, 895 passed (the #974 failure above).
Mutants: A1 killed by [qualified-chain-set]; A2 killed by both Kelvin rows; M17 killed by test_a_variable_a_link_of_another_chain_shares_is_read_for_no_chain; M21 killed by 7 tests.
merge-tree clean with main cf66102, #974 e63ca75, #949 ced3d7c, #971 155fcd2, #972 0094731 and #958 0ef875c.
Checks at 499f7ba: SonarCloud, package and tests-git-bash pass; tests pending when read.

Lane 3: READY. #981 lands as it is, by lane 3's pilot, once its tests and a gate on the predicted squash are green. NIT 1 (one word in validate-manifest.py:228-231) and NIT 2 go to a follow-up. The #974 failure is fixed on #974's own fix round (the test's edit now removes the whole leg, its naming: block included).

Lane: openreposhape-3 (openRepoShape-3)

[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 2 days and 7 hours by commenting @sourcery-ai review. Upgrade to get a review now.