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

L2-68 (P3; templates/assembly-root/scripts/validate-manifest.py, #634 review): the root's validate-manifest.py prints a WARNING that offers --link-source, a flag it does not take, and any fix has to work beside an older repo_shape.py.

• At 4cf5fb0 _chain_and_links calls link_pins_from_trees(chain, root) (templates/assembly-root/scripts/validate-manifest.py:128-141), and _naming_classification_findings prints each text in found.referent.warnings as WARNING naming-referent-chain: ... (:173-174). The text is built in scripts/repo_shape.py:1458-1463 and ends "or --link-source <link>=<path> would let it be read" (:1461-1462). The validator's parser takes --root, --policy and --quiet and nothing else (:869-871). The wording is right for the naming gate, which takes the flag.
• Measured on a scratch export of main: a scaffolded root whose manifest records the chain [openXdox, openDox] (the chain as_a_descendant_by_chain writes, tests/test_manifest_validator.py:418) makes scripts/validate-manifest.py exit 0 and print "... openXdox declaring a pin on openDox is a fact in openXdox's own tree, which is not reachable here (a sibling checkout, SHAPE_PIN_SOURCE_OPENXDOX, or --link-source openXdox=<path> would let it be read)." Typing the offer, validate-manifest.py --link-source openXdox=/nowhere, gives validate-manifest.py: error: unrecognized arguments: --link-source openXdox=/nowhere.
• 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 (head 030fde0) gives link_pins_from_trees a remedies= argument so the scaffold offers only the sources it reads (scripts/repo_shape.py:1461-1465 and :2902 at 030fde0). It does not touch validate-manifest.py, which passes none, so the validator still gets the naming gate's default text. rv610 saw that and noted that a fix which passes remedies= must still work where the root's repo_shape.py is older. Measured on a scratch export of main, which has no remedies=: link_pins_from_trees(['openXdox', 'openDox'], None, remedies={}) raises TypeError: link_pins_from_trees() got an unexpected keyword argument 'remedies'. A root's validate-manifest.py can be newer than its scripts/repo_shape.py (a half-applied update, --accept-local), and then an unguarded remedies= would end the validator in a traceback.
• Direction: a skew-safe form. For example, pass remedies= only where link_pins_from_trees takes it, or word the validator's own sentence after the call, and test it beside an older repo_shape.py. validate-manifest.py is a pinned copy, so a change re-pins every project, and it should ride with this file's next change. rv610 names adopt-project.py, shape-doctor.py, validate-manifest.py: execute records the plan's answers under answered_paths: and a moved submodule names its row, so an answered examples/ is not asked again and a deliberate move names no plan (#525) #617 (on main) and validate-repository-naming.py, validate-manifest.py and validate-pins.py: a project's own neutral_product_pins: or a leg's naming.referent_chain: that is not a list is validate-manifest.py's finding for that field in every gate that reads it, so 5 no longer ends make validate in a TypeError and a scalar openXdox is no longer read as its characters (#443) #631 as other edits to it. Landing it before the v1.1.0 tag keeps that release's re-pin one.

— #459, comment

L2-75 (P3; setup-project.py, #623 review): setup's step (4) shows the naming validator's own --link-source wording for a value the person typed as --pin-source after --, and setup takes no --link-source.

• On main. At 4cf5fb0 naming_declarations passes the validator --pins and --referent-chain and no source (setup-project.py:1936-1957), and check_names runs it and nothing else (:1964-1975). run hands the child's output straight to the terminal (:275-278). So a chain the validator cannot read shows [declared-unverified] and one WARNING for each holder it cannot read. Each WARNING offers --link-source <link>=<path> as the way to let that tree be read (scripts/repo_shape.py:1459-1463, in the loop at :1440). The person never typed that flag, and setup does not take it.
• Measured on a detached checkout of main, with -- --pin openXdox@<commit> --referent-chain openXdox,openDox --pin-source '': step (4) prints CHAIN openXdox → openDox [declared-unverified] and WARNING declared-unverified: openXdox declaring a pin on openDox is a fact in openXdox's own tree, which is not reachable here (a sibling checkout, SHAPE_PIN_SOURCE_OPENXDOX, or --link-source openXdox=<path> would let it be read). A tree that does declare openDox, given as --pin-source, prints the same, though step (5) reads that tree (its pin line ends (local-clone)). A three-link chain, openXdox,openYdox,openDox, prints that WARNING once for openXdox and once for openYdox. Typing the offer, -- ... --link-source openYdox=<tree>, ends step (5) with scaffold-project.py: error: unrecognized arguments: --link-source openYdox=<tree> and REFUSED: the plan could not be produced (see above)., exit 2.
• The plan speaks in --pin-source's own words. For --pin-source '' it says REFUSED pin-source-no-path: `--pin-source ''` names no path. An empty path would be read as the directory this runs in. (scripts/shape_materialize.py:2727-2731). For a source that cannot answer it says REFUSED pin-source-unreadable: <path> could not answer for opensoft/openXdox @ <commit>: no such directory, with a Remediation that begins "point --pin-source at a clone of that repository that HAS the pinned commit" (:2512-2519).
• On 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 head (400965b, not on main). The PR passes the last non-empty --pin-source to the validator as a bare --link-source= (setup-project.py:2036-2085: names_a_source at :2081, the append at :2084-2085). That is L2-25's fix, so a tree that verifies the chain shows [verified] (rv623g measured it). A source the validator cannot read now also names the flag in a label. The sentence is built at scripts/validate-repository-naming.py:330 and its (--link-source) label comes from scripts/repo_shape.py:2826. 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 changes neither file.
• Measured on a detached checkout of 400965b: --pin-source ' ' (blank) prints on stderr WARNING link-source-unreadable: (--link-source) could not answer for openXdox: no such file or directory, and a --pin-source folder that is not there prints the same line with that path. Step (5) then refuses pin-source-unreadable in --pin-source's words. With the three-link chain and the first tree given, one hint is left, for openYdox, or --link-source openYdox=<path> would let it be read. Setup has no flag for a later link at all: --pin-source is the first link's tree alone (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 only SHAPE_PIN_SOURCE_OPENYDOX reaches the others. Typing the offer fails as on main.
• rv623g saw the blank case and judged it no action: "a blank value goes as typed" is the 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 L2-25 design, and it is identical at be44452. f623g saw the hint and left it, because it is the validator's text and outside that task's files. Its test helper strips that one spelling (assert_an_empty_pin_source_is_the_plans_to_refuse, tests/conftest.py:1789-1790 at 400965b).
• 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 (head 6dad64b) shows what the right words are. The scaffold's own _link_remedies offers only the sources the scaffold reads (scaffold-project.py:931-965 at 6dad64b, issue 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). Measured on a detached checkout of 6dad64b, which has no 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: the plan's WARNING for openYdox ends "(SHAPE_PIN_SOURCE_OPENYDOX would let it be read)", while step (4) of the same run still says --link-source openYdox=<path> for the same holder. After 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 one run says one fact two ways.
• Severity is P3 for the reason L2-68 is: an offer, typed as printed, is refused. The (--link-source) label alone would be a nit. The hint is advice, and every refusal in these runs comes at step (5), before anything is created, with the right exit.
• Direction: one of two. (a) Setup re-words step (4)'s report: it captures the validator's output (run(..., capture=True)) and prints it with --link-source replaced by --pin-source. A plain swap is right for the first link only, and a later link needs the scaffold's words (SHAPE_PIN_SOURCE_<LINK>, as _link_remedies says it). Swapping text in a pinned tool's output also breaks without a sound when the gate's wording moves. (b) The naming gate takes a label for the flag it was given, and its hint takes the caller's remedy, as 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 does for the scaffold (remedies=, issue 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). That touches scripts/validate-repository-naming.py:330 and scripts/repo_shape.py:1459-1463 and :2826, all pinned copies, so a change re-pins every project and should ride with the gate's next change, repo_shape.py and validate-repository-naming.py: a chain link, a declared pin and a --link-source key are one product by pin_product_key, the pin file's own fold, so a tree declaring openss no longer verifies a chain that says openß, a chain naming both is two links and not a cycle, and --link-source openss= no longer answers for openß (#444) #638 (L2-69). It must still work beside an older repo_shape.py (L2-68's rule). (b) is the cleaner one: it is one place, and the test helper's re.sub goes.

— #459, comment

L2-69 (P3; scripts/validate-repository-naming.py, #634 review): the naming gate prints --link-source values as typed, so an ESC in a value or a path reaches the terminal, in the "not used" NOTE, the unreadable-source WARNING and the "read as a PATH" line.

• At 4cf5fb0 the raw prints are typed in the NOTE (scripts/validate-repository-naming.py:395-397, unused_lines), key in the "read as a PATH" sentence (:303-306, read_as_path), typed twice in _also_a_directory (:315), path in the unreadable-source WARNING (:330, and :336 for a source the gate did not take from the command line), and typed in the no-path refusal (:345-349).
• Measured on a scratch export of main with a value holding ESC [31m (cat -v shows the raw byte as ^[): --link-source x^[[31m with no chain recorded prints NOTE --link-source x^[[31m: not used. With a chain, --link-source a^[[31m=b/openXdox prints "It was read as a PATH: a^[[31m is not a link of a referent chain here (links: openXdox, openDox)." A tree directory named tree^[[31m that this user cannot read prints WARNING link-source-unreadable: .../tree^[[31m (--link-source openXdox=...) could not answer for openXdox: its project.yaml: Permission denied. A directory openXdox=y^[[31m passed whole prints "openXdox=y^[[31m is also a directory; --link-source ./openXdox=y^[[31m reads it as one." Each of those four runs exits 0. The :336 and :345-349 prints were read, not run.
• 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 (head 030fde0) spells the {path} at :330 with a local _shown (rv610's F6) and leaves the rest. It writes _shown into this file rather than importing shown_path, because a root's older repo_shape.py has none. L2-30 and L2-31 above are the same class in the scaffold's repo_shape.py text and in validate-pins.py, which 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 also spells.
• Direction: spell the other prints with that _shown, one test row per print with an ESC in it. The naming gate is a pinned copy, so a change re-pins every project. rv610 notes that repo_shape.py and validate-repository-naming.py: a chain link, a declared pin and a --link-source key are one product by pin_product_key, the pin file's own fold, so a tree declaring openss no longer verifies a chain that says openß, a chain naming both is two links and not a cycle, and --link-source openss= no longer answers for openß (#444) #638 edits the neighbouring LinkSources hunks, so do it after repo_shape.py and validate-repository-naming.py: a chain link, a declared pin and a --link-source key are one product by pin_product_key, the pin file's own fold, so a tree declaring openss no longer verifies a chain that says openß, a chain naming both is two links and not a cycle, and --link-source openss= no longer answers for openß (#444) #638 lands and before the v1.1.0 tag, and with 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 _shown already in the file.

— #459, comment