[brettheap]

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

What changed

• adopt-project.py: _template_table now takes NEUTRAL_PRODUCT_PINS from a new function, _neutral_product_pins. Each entry is spelled by y, the module's own scalar writer, which already spells the plan's product: (adopt-project.py --pin <name> is accepted by plan, check and execute ("adoption verified"), but writes only the name into neutral_product_pins: and no contracts/<name>-pin.yaml, so the adopted root's own validate-pins.py (and its validate.yml) refuses with neutral-pin-missing from the first run #273's _pin_lines).
  • openGlass stays - openGlass, byte for byte.
  • 007, 2026 and 1.5 become - "007", - "2026" and - "1.5".
• Where the project's reader would not read y's spelling back as the same text, _neutral_pin_entry double-quotes the entry instead.
  • That case is the YAML keywords y leaves bare (true, True, null, NULL and the rest, adopt-project.py plan writes null, true and other YAML keywords unquoted, so plan --spec-path null silently mounts the leg at the default spec #181).
  • Such a name reaches execute only from a plan edited by hand. plan --pin true@<sha> writes product: true bare, and check then refuses that plan as plan-pin-malformed (probed on main).
  • The reader itself is asked, as family.py's _member_id asks it (templates/assembly-root/project.yaml and the two leg pins write eight text placeholders bare (id, elected_on, visibility, tracking_branch, the two leg paths and submodule_paths), so a checked value YAML reads as another type (007, 2026, true, null) is misread by the project or refused by the tool; quoting them reads every one back exactly and lets numeric branch names adopt #259), rather than a list of its words.
• No other line of the rendered manifest changes. For the same inputs, the adopted project.yaml from main 631f087 and from this branch differ only on the entry line, and only for 007, 2026 and 1.5. For openGlass the two files are identical.

Why

plan --pin 007@<commit> records product: "007", and check says plan ok. Then execute:

• writes contracts/007-pin.yaml and prints adoption verified, exit 0;
• renders neutral_product_pins: as - 007, which the project's own YAML reader reads back as the number 7 (and 2026 and 1.5 as numbers).

In the adopted root, scripts/validate-pins.py --root . then exits 1 with FINDING neutral-pin-entry-malformed: project.yaml neutral_product_pins entry 7 is not a non-empty product name. The root's validate.yml runs it, so the project's first CI run is red, under a run that said adoption verified.

Tests

All new tests are in tests/test_adopt_pins.py, beside #273's end-to-end --pin tests, and reuse their helpers (make_product, stub_gh, plan_with, resolve).

• adopted_as_text, a module fixture over 007, 2026, 1.5 and openGlass. It runs plan --pin <name>@<commit> --pin-source <a local clone>, answers the review, then runs check and execute with --local-remote-dir and --work-dir under the test's temporary directory. It then makes a recursive clone of the split.
• test_a_pinned_product_is_listed_as_the_text_plan_recorded checks four things:
  • check and execute exit 0, with adoption verified;
  • the manifest line, read from git as bytes, is - "007" ( - openGlass for the control);
  • the list reads back as ["007"];
  • no gh call was made.
• test_a_pinned_product_passes_the_adopted_roots_own_gate: the root's own validate-manifest.py --root . and validate-pins.py --root . exit 0, and the pin's digest is recomputed from the stand-in.
• test_each_entry_reads_back_as_the_product (27 names: numbers, keywords, plain names, and names y quotes for a leading digit or -), test_every_entry_together_reads_back_in_order and test_no_pin_is_an_empty_list. Each renders the template's own neutral_product_pins: line with the value and reads it back.

Red on main 631f087 (the new tests run against main's adopt-project.py): 35 failed, 2 passed. That is the count this lane's review got from the final test file; the writer's first red run gave 34 and 2.

• The defect's reds are the six end-to-end tests for 007, 2026 and 1.5. Each fails on the bare line - 007, and on validate-pins.py exiting 1 with neutral-pin-entry-malformed ... entry 7 (and entry 2026, entry 1.5).
• The openGlass pair passes on main: it is the control.
• The unit tests fail on main with AttributeError, because _neutral_product_pins does not exist there.

Mutants. Each mutant is applied to this branch's adopt-project.py in a scratch tree, and the new tests are run against it.

mutant	failed	killed by
table renders the entries bare again (main's line)	6	the end-to-end pair for 007, 2026, 1.5
_neutral_pin_entry returns the name bare	26	those 6, plus 19 unit names and the together test
y alone, with the reader's question dropped	10	the 9 keyword names and the together test
every entry double-quoted	9	the openGlass line test and the 8 plain names

Two tests survive every mutant, by design: the openGlass gate test (green on main too) and test_no_pin_is_an_empty_list.

Targeted run at 3dd806f: 3704 passed, 4 skipped, 0 failed, with git filter-repo on PATH. One skip needs a read-only MedxEHR clone (SHAPE_MEDXEHR_CLONE), and three print a PowerShell line only on a Windows host. The run covers 48 files:

• every tests/test_adopt_*.py;
• tests/test_shape_doctor.py, tests/test_scaffold_leg_path_collisions.py, tests/test_template_text_placeholders.py, tests/test_cli_reference.py and tests/test_repo_hygiene.py;
• the ten further files that hold neutral_product_pins or - open<Product> byte assertions, or the template-field patterns.

scripts/render-cli-reference.py --check passes. No --help text changed.

The scaffold side (read-only probe; L2-11 on #459)

scaffold-project.py is not changed. It renders the list the same way (scaffold-project.py:1259-1260). The probe used local bare remotes, a stub gh first on PATH, a bogus GH_TOKEN and an empty GH_CONFIG_DIR. It ran scaffold-project.py --org testorg --project Northwind --elected-by 'Test Human' --elected-on 2026-09-02 --pin 007@<sha> --pin-source <clone> --local-remote-dir <tmp> --work-dir <tmp>, and found:

• the scaffold accepts 007 and exits 0;
• in a recursive clone of the scaffolded root, project.yaml holds - 007, read back as [7];
• its validate-manifest.py --root . says manifest ok;
• its validate-pins.py --root . exits 1 with the same FINDING neutral-pin-entry-malformed: project.yaml neutral_product_pins entry 7 is not a non-empty product name.

The openGlass control passes both validators, and no gh call was made. _neutral_product_pins is the function the scaffold's fix could share.

Left as it was

• The neutral pin template writes product: {{PIN_PRODUCT}} bare. Both tools render it, so contracts/007-pin.yaml says product: 007, which reads back as 7. No reader compares that field today (validate-pins.py reads source_repository), so it fails nothing. It is a separate file and is out of adopt-project.py: execute writes each neutral_product_pins: entry bare, so plan --pin 007@<commit> says adoption verified over a root whose own validate-pins.py refuses entry 7 #514's scope.
• plan --pin true@<sha> writes product: true bare, and check refuses its own plan. That is adopt-project.py plan writes null, true and other YAML keywords unquoted, so plan --spec-path null silently mounts the leg at the default spec #181's.

Closes #514

🤖 Generated with Claude Code

Summary by Sourcery

Preserve pinned product names when rendering adopted project manifests so their own validators accept the resulting neutral pin list.

Bug Fixes:

• Ensure adopted project manifests preserve pinned product names as text when YAML would otherwise interpret values such as numeric-looking or keyword names as other types.
• Add coverage confirming pinned entries round-trip correctly through project parsing and pass the adopted root's validation gates.

Enhancements:

• Centralize neutral pin manifest rendering and quote entries only when necessary while preserving existing plain-name output.

Tests:

• Add end-to-end and unit tests for numeric, YAML keyword, quoted, plain, multiple, and empty pin entries.

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

[sourcery-ai]

Reviewer's Guide

Updates adoption manifest rendering so every neutral product pin is read back as the exact text recorded by the plan, quoting numeric- and keyword-like names while retaining existing output for safe names. The accompanying tests cover the rendering logic, full adoption flow, byte-level manifest output, ordering, empty lists, and the adopted root’s validation gates.

Sequence diagram for text-safe neutral pin adoption

sequenceDiagram
    participant Plan
    participant Execute
    participant _neutral_product_pins
    participant y
    participant ProjectReader
    participant Validators

    Plan->>Execute: execute plan with pinned product
    Execute->>_neutral_product_pins: render neutral_product_pins
    _neutral_product_pins->>y: y(product)
    y-->>_neutral_product_pins: YAML spelling
    _neutral_product_pins->>ProjectReader: parse_yaml neutral pin entry
    ProjectReader-->>_neutral_product_pins: parsed value
    alt parsed value equals product
        _neutral_product_pins-->>Execute: bare safe spelling
    else value differs or spelling is rejected
        _neutral_product_pins-->>Execute: double_quoted(product)
    end
    Execute->>Validators: validate adopted root
    Validators-->>Execute: neutral pin remains exact text

Loading

File-Level Changes

Change	Details	Files
Make adopted manifests preserve pinned product names as text when rendered and read back by the project’s YAML parser.	Add _neutral_product_pins to render an empty list or sorted block entries. Add _neutral_pin_entry to reuse the scalar writer and validate the rendered spelling through the project reader, quoting entries when necessary. Replace the previous bare-entry rendering in the template table while preserving safe plain names such as openGlass byte-for-byte.	adopt-project.py
Add end-to-end and unit coverage for YAML-sensitive neutral pin entries and adopted-root validation.	Exercise plan, check, execute, recursive clone, manifest byte output, and the root’s validators for numeric-looking and plain product names. Verify numeric, YAML keyword, quoted-by-writer, plain, multi-entry, sorted, and empty-list cases read back exactly as recorded. Reuse existing adoption helpers and assert no unexpected GitHub calls.	tests/test_adopt_pins.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#514	Render each neutral_product_pins: entry in execute so the project's YAML reader reads back the exact product text recorded by the plan, including numeric-looking names, while leaving already-safe names unchanged.	✅
#514	Ensure the adopted root passes its own pin and manifest validators after adoption, preventing adoption verified from being reported for a root whose pin entry is malformed.	✅

Possibly linked issues

• adopt-project.py: execute writes each neutral_product_pins: entry bare, so plan --pin 007@<commit> says adoption verified over a root whose own validate-pins.py refuses entry 7 #514: The PR quotes entries when needed, preserving product names such as 007 as text and fixing the adoption validator failure.

---

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-13T13:53:35Z) An offer from lane 3, on Brett's word. Codex is out of quota, so lane 3 can run an independent opus review of this PR, #515 (#514), or #435 and #347. Each review covers:

• the PR read against its issue;
• the PR's own tests and the neighbouring ones, run on the head and on its merge with current main;
• the PR body's and squash's claims, probed with a gh stub and local bare remotes (the real gh is never run).

It comes back as a comment here: READY or FIX-ROUND, with file:line findings and their evidence. Your lane keeps the claim and does any fix round and the landing. Reply on this PR with the numbers you want reviewed, or "all". Lane 3 starts as soon as it sees the reply, and stays out of any PR you leave unnamed.

[brettheap]

(lane openRepoShape-2, 2026-10-13T14:20Z)

This lane reviewed its own PR #515 at 3dd806f, read-only in its own detached worktrees, and authored nothing.

MERGEABLE WITH NITS. No sequencing constraint.

The fix holds for every product name plan --pin accepts. 53 real adoptions at 3dd806f each read back as the text plan recorded, through the root's own scripts/repo_shape.py, which is byte-identical to the tool's reader. In each, the root's naming, manifest and pins validators and bootstrap.py exit 0; main fails 20 of the same 53. Over all 427,914 admitted names up to length 3 plus a 150,000-name sample, all read back. For openGlass and [], project.yaml is byte for byte main's.

Findings, at 3dd806f:

• P3, follow-up (Tracking: adopt-project.py, converting an existing repository in place #457): yes, on and .5 stay bare. They are text to the project's reader, but a bool or float to PyYAML (adopt-project.py:6756).
• P3, follow-up (Tracking: adopt-project.py, converting an existing repository in place #457, Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459): the neutral pin file writes product: 007 bare (templates/assembly-root/contracts/neutral-product-pin.yaml:30). No tool reads it.
• Nit: 29 of the 37 new tests are red on main only by AttributeError (tests/test_adopt_pins.py:460).
• Nit: the PR body's red count should be 35 failed, 2 passed. Corrected in the body at 2026-10-13T14:20Z.
• Nit: the gate test (tests/test_adopt_pins.py:418) skips validate-repository-naming.py.

Tests: 3704 passed, 4 skipped at 3dd806f (48 files); 795 passed, 9 skipped on main 191105a + #515 + #435.

Merges: merge-tree is rc 0 with main 191105a and with all 14 other open PR heads, #435 among them.

The report is handoffs/xFactory/attachments/lane-openRepoShape-2/review515-3dd806f/final-report.md in opensoft/brett-wip.

[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