[brettheap]

Lane: openreposhape-2 (openRepoShape-2)
Claim: #661 (comment)

Lands after #634 (on main as 30676c9). This branch is cut from it. It must land before the v1.1.0 tag: DB8 option 3 and DB9 option b of the checklist triage of 2026-10-16, which Brett Heap approved at 12:14:51Z, and D6, one re-pin for v1.1.0.

A chain link whose own tree nothing could read is declared-unverified, and its WARNING offers what would let that tree be read. Since #634 the scaffold offers its own sources (link_pins_from_trees(..., remedies=)). The two other callers still printed the naming gate's words, "a sibling checkout, SHAPE_PIN_SOURCE_, or --link-source =", and neither of them takes --link-source:

• L2-68. The root's own validate-manifest.py, on every make validate, bootstrap and CI validate run of a root that records a chain. Typed as printed, the offer gives unrecognized arguments.
• L2-75. Setup's step (4), through the gate. It also labelled the --pin-source it hands the gate (--link-source). Typed after --, the offer ends step (5) in the scaffold's unrecognized arguments, exit 2.

Each caller now offers the sources it reads. The gate also names every --link-source value and path it prints as _shown names one (L2-69).

What changed

templates/assembly-root/scripts/validate-manifest.py (L2-68; a shape copy).

• _link_remedies(chain) builds this validator's own words. It reads SHAPE_PIN_SOURCE_<LINK> (rule 2 of resolve_link_source, unless two links share the variable, 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) and a checkout beside the root (rule 3). So each holder is offered SHAPE_PIN_SOURCE_OPENXDOX, or a checkout of openXdox beside this root, would let it be read, or, where another link shares the variable, the checkout alone: a checkout of open-x beside this root would let it be read. Its docstring says both. The links are read as _chain_link_findings reads them, by repo_basename, so a link recorded opensoft/openXdox is offered as openXdox. The entries are keyed by pin_product_key, the key _chain_link_findings looks a holder up by (scripts/repo_shape.py: the chain readers identify a link, a declared pin and a --link-source key by casefold() (twelve calls, :1207 to :2428), where #275's fix (PR #409, 6494714) makes a product's identity pin_product_key (lower(), the pin file's own fold), so openß and openss are two products to the pin validator and one link to the chain: a holder's tree that declares openss verifies a chain that says openß, a project that pins openss verifies a chain that begins at openß, a --link-source openss= answers for the link openß, link_pins_from_trees keeps one entry for the pair, and a chain that names both is refused as a cycle #444).
• The skew rule. A root may run this file beside an older scripts/repo_shape.py (a half-applied update, update-shape.py apply --accept-local). Before 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, link_pins_from_trees had no remedies= and raised TypeError (measured on de926142 and on v1.0.1). So _library_takes_remedies() asks the function's own signature (inspect.signature), and remedies= is passed only where the signature names it. Beside an older library the WARNING keeps that library's words, with exit 0 and no traceback.
• The new names it imports (pin_product_key, pin_source_env_name, pin_source_env_shared) are all in v1.0.0's library, so 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's kept-helper check still lets an older one stay.

scripts/validate-repository-naming.py (L2-75, L2-69; a shape copy).

• --link-source-label=FLAG is the caller's own name for the bare --link-source it passes. Setup passes --pin-source. The value starts with -, so it is given after an =. With a label:
  • link-source-unreadable says (FLAG), not (--link-source). The gate replaces the library's label, so an older library needs nothing.
  • The "not used" NOTE, and its "the later … replaced it", name the value FLAG <value>.
  • Neither line says a value holding = "was read as a PATH". The caller's flag is always a path, and setup spells a <word>= value ./<word>=.
  • The NOTE's list of more specific sources leaves out "a keyed --link-source".
  • The help says exactly that: "the link-source-unreadable WARNING and the not-used NOTE name that value by FLAG, and neither says a value holding = was read as a PATH". Two lines keep the gate's own flag, and the module docstring names them: the link-source-no-path REFUSED line, and the NOTE's advice name the link it is, as --link-source <link>=PATH where the chains begin at more than one link. Setup reaches neither (see Not changed).
• --link-remedy LINK=TEXT (repeatable) gives the caller's words for what would let LINK's tree be read.
  • The value is split at its first =. A value with no =, no link or no words is refused by argparse, exit 2.
  • The words are kept by pin_product_key(link); the last value for a link wins.
  • They are passed as remedies= only when some were given and the library's signature takes them, so a project's own run calls the library exactly as before, beside any library.
  • _chain_link_findings is unchanged. It already looks a holder's entry up by pin_product_key, and a holder with no entry keeps the gate's own words.
• L2-69. These are now spelled by the gate's own _shown (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): read_as_path's key, _also_a_directory's value (in the sentence and in the ./ command), the path of a SHAPE_PIN_SOURCE_<LINK> or a checkout beside the project that could not answer, and the path inside that checkout's (sibling checkout (…)), no_path_refusal's value, and the "not used" NOTE's value and its replacement. A printable value is named byte for byte as before.
• The module docstring says which prints are _shown. Every --link-source value and path the gate prints, and the path of a SHAPE_PIN_SOURCE_<PRODUCT> or of a checkout beside the project it names, is _shown. A caller's FLAG and the words it offers for a link, a chain link's name, and the --project and --policy paths are printed as given (see Not changed).

setup-project.py (L2-75).

• naming_declarations(passthrough, link_remedies=None): for a chain of two links or more, step (4) also hands the gate --link-source-label=--pin-source and one --link-remedy=<link>=<words> per holder. This happens whether or not a source was named, because --pin-source '' still needs the offer.
• The words are the scaffold's own, so step (4) and step (5) say one fact one way.
• The chain is read as the scaffold reads it (referent_chain_links).
• With no link_remedies the output is exactly setup-project.py: step (3) refuses a parent nobody can write in and a drive that is not there, step (4) verifies a chain from --pin-source, --pin no longer takes a flag as its value, and step (5) says a printed plan was refused (#608) #623's.
• _main passes scaffold_link_remedies(shape_root), a deferred import of the checkout's scripts/shape_materialize.py, as shape_scripts does for repo_shape.

scripts/shape_materialize.py, scaffold-project.py.

• The scaffold's _link_remedies (Pinned shape copies: one bump, so AGENTS-shape.md is true of every root, the scaffold's chain WARNING offers only its own sources and spells --pin-source, the root's not-used note spells it too, and THE LOCKSTEP RULE's bump runs (#610) #634) moves, unchanged, to shape_materialize.scaffold_link_remedies. The comment above shape_materialize.py's repo_shape import now names it as the reader of pin_source_env_name, pin_source_env_shared and repo_basename.
• The scaffold imports it under its old name, so its call and Pinned shape copies: one bump, so AGENTS-shape.md is true of every root, the scaffold's chain WARNING offers only its own sources and spells --pin-source, the root's not-used note spells it too, and THE LOCKSTEP RULE's bump runs (#610) #634's three tests stay as they are. Its now-unused pin_product_key, pin_source_env_name, pin_source_env_shared import goes.
• shape_materialize.py is in no copy list. Its own rule keeps a helper only the tools call out of the pinned repo_shape.py.

docs/cli.md is regenerated: the gate's two new options. validate-manifest.py's and setup's --help are unchanged.

What step (4) says now, measured through setup-project.py:

run, after --	before	after
--pin-source '', 2 links	(a sibling checkout, SHAPE_PIN_SOURCE_OPENXDOX, or --link-source openXdox=<path> would let it be read)	(SHAPE_PIN_SOURCE_OPENXDOX, or a --pin-source clone of openXdox that holds its project.yaml, would let it be read)
--pin-source ' '	WARNING link-source-unreadable: (--link-source) could not answer for openXdox: …	… (--pin-source) could not answer…
--pin-source openXdox=layer, absent	(--link-source), then "It was read as a PATH: ./openXdox is not a link…"	openXdox=layer (--pin-source) could not answer…, and no "read as a PATH"
3 links, the first tree given	… or --link-source openYdox=<path> would let it be read	(SHAPE_PIN_SOURCE_OPENYDOX would let it be read), the plan's own line byte for byte
3 links, --pin-source ''	two offers of --link-source	one offer per holder, each in the plan's words
the first link's variable set, and --pin-source <tree>	NOTE --link-source <tree>: not used — … (a keyed --link-source, SHAPE_PIN_SOURCE_<PRODUCT>, …)	NOTE --pin-source <tree>: not used — … (SHAPE_PIN_SOURCE_<PRODUCT>, or a checkout beside the project).

Decisions the issue left open

• The skew form. The issue names three. This PR takes "pass remedies= only where the function takes it", checked with inspect.signature.
  • It is the library's documented keyword (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). A library that lacks the keyword is called exactly as before.
  • It is not try/except TypeError, which would swallow an unrelated TypeError from inside the call and call it again.
  • Wording the remedy after the call rewrites library text, and breaks without a sound when that text moves. It would also have to repeat the 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 rule.
  • A mapping that carries remedies as an attribute rests on _chain_link_findings' private getattr, which only LinkPins is promised.
  • Beside an older library, all three can do no better than that library's words.
• One definition of the scaffold's words. Setup could not import the scaffold's private _link_remedies, and a second copy of it would drift. So the function moved to the one module both the scaffold and setup can load, and a test holds the three names (scaffold-project.py's, setup's and shape_materialize's) to one function.
• The words go with any chain of two links or more, not only with a source. Without them, --pin-source '' (the plan refuses it as pin-source-no-path) and a run with no --pin-source kept the gate's offer. setup-project.py: step (3) refuses a parent nobody can write in and a drive that is not there, step (4) verifies a chain from --pin-source, --pin no longer takes a flag as its value, and step (5) says a printed plan was refused (#608) #623's 13 --link-source= rows in test_the_declarations_are_read_as_the_scaffold_reads_them are unchanged, because the label goes with the words, not with the source.
• The options are visible. This repository hides no option from --help (no argparse.SUPPRESS anywhere), so docs/cli.md gains them.

Tests

New file tests/test_chain_remedy_callers.py, 30 tests:

test	what it pins
test_the_manifest_gate_offers_the_sources_it_reads (two-links, three-links, qualified)	the root's own validate-manifest.py: exit 0, each holder's WARNING exactly, in its own words, no --link-source. qualified records [opensoft/openXdox, openDox], which is offered by the name openXdox
test_each_source_the_manifest_gate_offers_reads_the_link (variable, beside-the-root)	each offered source, given the link's tree, verifies the chain
test_a_shared_variable_is_not_offered_by_the_manifest_gate (lowercase, mixed-case)	_link_remedies for two holders sharing a variable, keyed by pin_product_key
test_the_new_copies_run_beside_an_older_library (pre-634 de926142, v1.0.1)	the skew rule: the root's validator, and its gate with --link-remedy, beside each older repo_shape.py (read with git show, asserted to hold no remedies): exit 0, no traceback, the older words
test_the_gate_offers_each_holder_the_callers_words	three links, one offer per holder, each its own words (one typed OPENYDOX=)
test_a_holder_given_no_words_keeps_the_gates_own, test_the_last_words_for_a_link_win	fall-back and last-wins
test_words_that_are_not_link_equals_text_are_refused (no-equals, no-link, no-words)	exit 2, argument --link-remedy: … is not LINK=TEXT
test_a_labelled_bare_source_is_named_by_its_label, test_a_labelled_source_holding_an_equals_is_not_said_to_be_a_path, test_an_unused_labelled_source_is_noted_by_its_label	the label in the unreadable line, no "read as a PATH", the NOTE's head and its list
seven L2-69 rows, each with an ESC and a forged line where the system can hold one: test_a_key_read_as_a_path_is_spelled, test_a_keyed_value_that_is_also_a_directory_is_spelled, test_a_variable_the_gate_could_not_read_is_spelled, test_a_checkout_beside_the_project_the_gate_could_not_read_is_spelled, test_a_value_that_names_no_path_is_spelled, test_an_unused_link_source_and_its_replacement_are_spelled; and the control test_a_printable_value_is_named_as_typed	every print site; no raw ESC and no forged line on the terminal

Setup's tests (shared helpers in tests/conftest.py, one-call wrappers in both setup files):

file	test	what it pins
tests/conftest.py	assert_step_four_speaks_in_the_plans_words (5 cases: three-links-first-tree, three-links-no-source, blank, holds-an-equals, variable-first)	no --link-source in step (4) or on stderr; the plan's words; the --pin-source label; the plan's own WARNING line byte for byte. One assert per condition (S9073)
tests/conftest.py	assert_an_empty_pin_source_is_the_plans_to_refuse	changed. Its re.sub of the gate's offer is gone: it now asserts no --link-source at all, and the plan's words in step (4)
tests/test_setup_project_py.py, tests/test_setup_sh.py	test_step_four_speaks_in_the_plans_words	the helper through setup-project.py and through setup.sh
tests/test_setup_project_py.py	test_each_holder_is_given_the_plans_words (6)	the argv: label and one --link-remedy per holder, the chain read as the scaffold reads it, nothing for one link
tests/test_setup_project_py.py	test_step_four_and_the_plan_share_one_set_of_words	setup's, the scaffold's and shape_materialize's names are one function
tests/test_naming_policy.py	test_the_projects_own_manifest_gate_keeps_its_warning_for_a_tree_it_reached	changed. It expects the validator's own words now, and no --link-source

• Red at the base (main 30676c90 with only the tests): 46 failed and 3 passed. The 3 are the controls: test_each_source_…[variable, beside-the-root] and test_a_printable_value_is_named_as_typed.
• Mutants: 27 of 27 killed on round 1's head f5e1867d, each by a named test, and the files restored byte for byte afterwards (sha256 checked).
  • validate-manifest.py:
    • V1, no remedies passed;
    • V2, remedies passed unguarded. It dies by the TypeError beside both older libraries.
    • V3, keyed by the raw link;
    • V4, a shared variable offered;
    • V5, shared asked of the raw link;
    • V6, the chain's end given an entry.
  • The gate:
    • G1, --link-remedy not passed on;
    • G2, keyed by the raw link;
    • G3, the first words win;
    • G4, remedies passed unguarded;
    • G5, the label ignored in the unreadable line;
    • G6, "read as a PATH" under a label;
    • G7, the NOTE ignores the label;
    • G8, "a keyed --link-source" kept under a label;
    • G9, malformed --link-remedy values taken.
  • Setup:
    • S1, no words passed;
    • S2, no label;
    • S3, the chain read unstripped;
    • S4, words of its own.
  • L2-69:
    • E1-E7, each print site raw again;
    • E8, _shown always repr.
• Targeted, on Linux, at round 1's head: 36 files, one process, 2595 passed, 6 skipped and 0 failed in 1973 s. The files are:
  • the new file;
  • test_naming_policy, test_link_source_chain_defaults, test_pinned_copy_text, test_pin_source_env_collisions and test_chain_link_fold;
  • test_manifest_validator and test_doctor_validator_verdicts;
  • test_cli_reference;
  • test_setup_project_py and test_setup_sh;
  • test_scaffold_manifest_values, test_neutral_pin_validator and test_template_text_placeholders;
  • test_repo_hygiene;
  • test_branch_left_bump_leg_setup (bump-leg.py and setup-project.py: the git switch -c line says under it what to do where an earlier act left that branch, so already exists is no dead end (#607's sentence, in the two tools it left) #657's) and test_doctor_next_is_a_command;
  • test_scaffold_leg_path_collisions;
  • the 17 test_update_shape*.py files and test_shape_doctor.
    After that run, an unused import shutil was dropped from the new file (29 passed again).
  • Main moved during the run, to 6e37d0e. git merge-tree of this head with it is clean. The predicted merge was committed in a scratch tree and passed 532 tests in 7 files: the new file, test_naming_policy, test_pinned_copy_text, test_link_source_chain_defaults, test_derived_id_refusals, test_scaffold_manifest_values and test_cli_reference.
• scripts/render-cli-reference.py --check: ok.
• pyflakes: the same warnings as main in the changed files, and none in the new test file.

Round 2 (rv661), at 657cb233:

• M4 is killed. M4 reads the chain in validate-manifest.py's _link_remedies without repo_basename (rv661: 373 tests let it live). Against the two rows f5e1867d shipped it still lives (2 passed, the control). Against the new qualified row it fails on the WARNING list (test_chain_remedy_callers.py:107), and against the whole new file it fails too. V2, G5 and E3 from round 1 are killed again, each on its assertion. Files restored byte for byte (sha256 checked).
• Targeted, on Linux, one process at a time: 18 files, 1525 passed, 0 failed, 0 skipped.
  • 821 in 372 s: the new file (30), test_naming_policy, test_pinned_copy_text, test_link_source_chain_defaults, test_manifest_validator, test_cli_reference, test_setup_project_py and test_setup_sh.
  • 704 in 412 s: test_repo_hygiene, test_template_text_placeholders, test_scaffold_manifest_values, test_neutral_pin_validator, test_doctor_validator_verdicts, test_pin_source_env_collisions, test_chain_link_fold, test_scaffold_leg_path_collisions, test_doctor_next_is_a_command and test_branch_left_bump_leg_setup.
• scripts/render-cli-reference.py --check: ok at this head, and ok on the predicted merge with main 3726ada2 (git merge-tree --write-tree, clean).
• pyflakes: no warning that f5e1867d did not have (main's two in shape_materialize.py).

The re-pin

Because of this PR, assembly roots re-pin scripts/validate-manifest.py and scripts/validate-repository-naming.py; family holders re-pin nothing new; against v1.0.1 both already differ at main.

• Both are in an assembly root's copy list (COPIED_VERBATIM holds MANIFEST_VALIDATOR, COPIED_FROM_SHAPE holds VALIDATE_NAMING). A family holder's lists (FAMILY_COPIED_VERBATIM, FAMILY_COPIED_FROM_SHAPE) hold neither.
• git diff --quiet v1.0.1 origin/main -- templates/assembly-root/scripts/validate-manifest.py and -- scripts/validate-repository-naming.py both exit 1 (re-measured at 55c6ba7d). So this adds no file to a project's v1.1.0 update.
• scripts/repo_shape.py is untouched.

Not changed (known limits)

• Chain-link names, and the gate's --project and --policy paths, are printed as given.
  • The link names come from --referent-chain or a manifest, not from --link-source. They appear in "could not answer for ", in the keyed (--link-source <link>=...), after "names no path for", in read_as_path's list of links, and in the library's <holder> in every chain WARNING.
  • The --project and --policy paths are not --link-source values either.
  • L2-69 is about --link-source values and paths only, and the gate's module docstring now says so.
• Two lines keep --link-source under a label. The link-source-no-path REFUSED line (--link-source ''` names no path) and the NOTE's advice where the chains begin at more than one link (name the link it is, as --link-source <link>=PATH). Setup reaches neither: it gives step (4) no --link-source for an empty last --pin-source (setup-project.py: step (3) passes an unwritable parent or a missing drive, and step (4) shows a chain the plan verifies as [declared-unverified] #608), and it passes one --referent-chain, so the chains begin at one link. A label in those two lines would need words of its own, because the caller's flag cannot name a link. The help and the docstring say which lines take the label. rv661's mutant M3, under which the label also replaces a keyed value's (--link-source <link>=...), still lives: setup passes no keyed --link-source, so no test gives a label and a keyed value together.
• validate-manifest.py asks for no reasons (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 kept it so). A checkout beside the root that is there but cannot be read as a declaration is still "not reachable here", and is now offered "a checkout of openXdox beside this root" while one is there. with_reasons=True is in every library since v1.0.0, so a change would be skew-safe. It is 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 decision and test_the_projects_own_manifest_gate_keeps_its_warning_for_a_tree_it_reached pins it.
• Setup's step (4) runs the gate from the standard's checkout. So the gate's rule 3 reads a checkout beside the STANDARD (<shape parent>/<link>), which step (5)'s scaffold never reads (link_pins_from_trees(chain, None, ...)). Read, not run.
• A NOTE the plan does not print. With the first link's variable set, step (4) notes the --pin-source as not used, a NOTE the plan does not print. It now speaks setup's words. Whether setup should pass the bare source then is setup-project.py: step (3) passes an unwritable parent or a missing drive, and step (4) shows a chain the plan verifies as [declared-unverified] #608's design question.
• README.md and the templates' other files: nothing. README.md:707-712 describes the gate's sources and stays true.

Closes #661

🤖 Generated with Claude Code

Summary by Sourcery

Align chain-link remediation messages across manifest validation, naming checks, and setup planning with the sources each caller actually reads.

New Features:

• Allow the naming validator to accept caller-specific link-source labels and per-link remediation text.
• Make setup planning and manifest validation report only the link sources available to the caller.],
• bug_fixes:[
• ],
• enhancements:[
• ],
• build as? cannot
• ci as? cannot
• deployment as? cannot
• docs as? cannot
• tests as? cannot
• chores as? cannot
• overview as? cannot raise JSON invalid.
• overview unclear but required one sentence imperative.
• docs as? cannot
• tests as? cannot
• build as? cannot
• ci as? cannot
• deployment as? cannot
• chores as? cannot
• enhancements as? cannot
• bug_fixes as? cannot
• new_features as? cannot
• overview as? cannot

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

[sourcery-ai]

Reviewer's Guide

The PR aligns chain-link warnings across the root validator, naming gate, scaffold, and setup by supplying caller-specific remedies and labels, safely rendering every link-source value/path, and conditionally supporting older repo-shape libraries without changing their call contract.

Sequence diagram for caller-specific chain-link remedies

sequenceDiagram
    participant Setup as setup-project.py
    participant Gate as validate-repository-naming.py
    participant Library as repo_shape.py
    participant Scaffold as shape_materialize.py

    Setup->>Scaffold: scaffold_link_remedies(chain)
    Scaffold-->>Setup: remedies keyed by pin_product_key
    Setup->>Gate: naming_declarations(..., --link-source-label=--pin-source, --link-remedy=LINK=TEXT)
    Gate->>Gate: _link_remedy(value)
    Gate->>Gate: _library_takes_remedies()
    alt library accepts remedies
        Gate->>Library: link_pins_from_trees(..., remedies=remedies)
    else older library
        Gate->>Library: link_pins_from_trees(...)
    end
    Library-->>Gate: chain findings and warnings
    Gate-->>Setup: caller-labelled warnings using supplied remedies

Loading

File-Level Changes

Change	Details	Files
Make each chain-link caller describe only sources it actually reads, while preserving compatibility with older repo-shape libraries.	Added validator-local remedies for environment and sibling-checkout sources, keyed by normalized product identity. Added signature-based detection so remedies= is passed only to libraries that support it. Moved shared scaffold remedy generation into shape_materialize.py and reused it from the scaffold and setup.	templates/assembly-root/scripts/validate-manifest.py scripts/shape_materialize.py scaffold-project.py setup-project.py
Allow the naming gate to accept caller-specific source labels and per-link remedy text, and make all emitted source values and paths safely printable.	Added repeatable --link-remedy LINK=TEXT with validation, normalized keys, fallback behavior, and last-value-wins semantics. Added --link-source-label so setup warnings identify --pin-source rather than the gate's internal flag. Removed misleading PATH diagnostics and keyed-source suggestions when a caller supplies its own label. Applied _shown consistently to link-source values and paths across warnings, notes, refusals, and replacement messages.	scripts/validate-repository-naming.py docs/cli.md
Pass setup's scaffold wording and source label into the naming check so plan step (4) matches what step (5) can perform.	Derive the chain using the scaffold's trimming and ordering rules. Pass one remedy per chain-link holder for chains with at least two links, even when no source was supplied. Preserve existing output for callers that do not provide remedies.	setup-project.py tests/conftest.py
Add regression coverage for caller-specific remedies, library skew, setup output, and safe value/path rendering.	Added end-to-end tests for root validation, naming-gate overrides, malformed remedy arguments, source labels, shared variables, and older pinned libraries. Covered every link-source print site with printable and control-character inputs. Updated setup and naming-policy expectations and verified CLI-reference regeneration.	tests/test_chain_remedy_callers.py tests/test_naming_policy.py tests/test_setup_project_py.py tests/test_setup_sh.py tests/conftest.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#661	Make the root's validate-manifest.py offer only link sources it actually reads, while remaining compatible with older repo_shape.py copies.	✅
#661	Make setup's naming-gate output use setup's --pin-source label and offer remedies that match the scaffold's readable sources, rather than suggesting unsupported --link-source options.	✅
#661	Spell every --link-source value and path printed by the naming gate so non-printable characters cannot reach the terminal raw.	✅

Possibly linked issues

• 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: The PR fixes all three requested lines: caller-specific remedies, setup’s source label, and escaped-value-safe naming-gate output.

---

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-2, 2026-10-16T19:14:28Z)

#744 round 2: rv661's findings, fixed at 657cb233 (one commit on f5e1867d, six files, +36/−15; main not merged).

1. Should-fix, S9073, tests/conftest.py. assert offered and offered[0].endswith(...) in assert_step_four_speaks_in_the_plans_words is now two asserts, one per condition: assert offered, step_four, then the endswith with offered as its message. I grepped every assert the branch adds for an and or or that joins conditions: this was the only one.
2. Should-fix, pinned copy, scripts/validate-repository-naming.py docstring. The sentence now covers only what _shown spells: "Every --link-source value and path this prints, and the path of a SHAPE_PIN_SOURCE_<PRODUCT> or of a checkout beside the project it names, is named as it is, or as Python's repr spells it where a character in it is not printable (_shown)." A second sentence names what is printed as given: "A caller's FLAG and the words it offers for a link, a chain link's name, and the --project and --policy paths are printed as given."
3. Nit, pinned copy, the --link-source-label help. I narrowed it and left the code as it was. The help now says: "the link-source-unreadable WARNING and the not-used NOTE name that value by FLAG, and neither says a value holding = was read as a PATH".
   • The docstring names the two lines that keep the gate's own flag: the link-source-no-path REFUSED line, and the NOTE's --link-source <link>=PATH where the chains begin at more than one link.
   • I did not honour the label in either line. A caller's bare flag cannot name a link, so the second line would need words of its own, and that is not plainly right.
   • Setup reaches neither line. It gives step (4) no --link-source for an empty last --pin-source (naming_declarations' names_a_source), and it passes one --referent-chain.
   • docs/cli.md is regenerated, and render-cli-reference.py --check is ok.
4. Nit, pinned copy, validate-manifest.py's _link_remedies docstring. It now reads "Every holder is offered both, or the checkout alone where another link shares its variable; the chain's end holds no pin and has no entry." That is the code's shared branch, which gives (a checkout of open-x beside this root would let it be read) on open-x, open_x, openDox.
5. Nit, test gap, M4. test_the_manifest_gate_offers_the_sources_it_reads has a third row, qualified. It records referent_chain: [opensoft/openXdox, openDox] and expects each holder by its basename.
   • M4 is links = [str(link) for link in chain if str(link).strip()] in _link_remedies. Against the two rows round 1 shipped it still lives (2 passed: that run is the control).
   • Against [qualified] it is killed, on the WARNING list at test_chain_remedy_callers.py:107, and against the whole new file it is killed too.
   • M3 is left as you said: setup passes no keyed --link-source.
6. Nit, scripts/shape_materialize.py. The comment above the repo_shape import now names its new reader: "scaffold_link_remedies reads a chain with the same names: each link's variable (pin_source_env_name), whether another link shares it (pin_source_env_shared), and the link's name (repo_basename) (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)."

Nothing else changed. E1-E5 are held for #459.

Verification at 657cb233 (Linux, stub gh, one process at a time):

• 18 files, 1525 passed, 0 failed, 0 skipped.
  • 821 passed: the new file (30), test_naming_policy, test_pinned_copy_text, test_link_source_chain_defaults, test_manifest_validator, test_cli_reference, test_setup_project_py and test_setup_sh.
  • 704 passed: test_repo_hygiene, test_template_text_placeholders, test_scaffold_manifest_values, test_neutral_pin_validator, test_doctor_validator_verdicts, test_pin_source_env_collisions, test_chain_link_fold, test_scaffold_leg_path_collisions, test_doctor_next_is_a_command and test_branch_left_bump_leg_setup.
• Mutants: M4 killed, and its control lives as expected. Round 1's V2, G5 and E3 are killed again, each on its assertion. Each file was restored byte for byte (sha256 checked).
• render-cli-reference.py --check is ok at the head and on the predicted merge with main 3726ada2, whose git merge-tree is clean.
• pyflakes shows no warning that f5e1867d did not have.

The re-pin is unchanged: assembly roots re-pin scripts/validate-manifest.py and scripts/validate-repository-naming.py, family holders re-pin nothing new, and against v1.0.1 both already differ at main.

[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