[brettheap]

Lane: openreposhape-3 (openRepoShape-3)
Claim: #739 (comment)

Closes #739.

Lands after the v1.1.0 tag. It is a v1.1.1 fix: draft only, never update-branch, never merge before the tag. The issue's own "Lands after: #702" is met: #702 landed as 20c8873, and this branch is cut from main e313701, which holds it.

What was wrong (re-measured on main e313701)

A scaffolded Atlas with local bare remotes and a stub gh, with a committed .github/workflows/legs.yml naming testorg/Atlas-code:

• One reference off its gitlink: the gate printed FINDING pin-workflow-ref-mismatch: legs.yml: ...Atlas-code@0123... != the gitlink ... and, on stdout, ok testorg/Atlas-code: 1 workflow @<sha> reference(s) agree with the gitlink, for the same reference.
• Two references, one at the gitlink and one off: the same finding, and ok testorg/Atlas-code: 2 workflow @<sha> reference(s) agree with the gitlink.

_check_workflow_refs_for_leg incremented seen for every reference naming the repository before it compared the sha. The issue's claims hold on e313701; only the line numbers moved (:888-911 now, :776-800 on de92614).

One part of the issue's wording did not hold. It says the doctor's pins row "relays the gate's lines". The row quotes the gate's first FINDING or REFUSED line on a finding, and only skip, WARNING and note blocks on a pass (shape-doctor.py's PASS_REPORTS). It never relays an ok line, so this note never reached the row. Measured before and after the change in all three states: the pins row reads the same, quoting the pin-workflow-ref-mismatch finding where one stands and "passes" where none does.

What changed

templates/assembly-root/scripts/validate-pins.py, _check_workflow_refs_for_leg (:888):

• :901 counts agree, the references equal to the gitlink, beside seen.
• :915-916: a reference at the gitlink adds to agree; one off it is still its finding, unchanged.
• :917-920: the note is printed only when agree is above zero, as N where every reference agrees and N of M where some do not: ok testorg/Atlas-code: 1 of 2 workflow @<sha> reference(s) agree with the gitlink.
• The docstring says why (validate-pins.py: the <repository>: N workflow @<sha> reference(s) agree with the gitlink note counts the references that do NOT agree, so it is printed beside the pin-workflow-ref-mismatch finding for the same reference #739).

Tests

tests/test_pin_validator.py:

• :170 code_workflow, a workflow naming the code leg once per sha.
• :184 test_the_agree_note_counts_only_the_references_at_the_gitlink[one-off|one-of-two-off|both-at]. One off: no note. One of two off: 1 of 2. Both at the gitlink: 2. The first two fail on main e313701 and pass here.

Each run had 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 -o tmp_path_retention_policy=failed tests/test_pin_validator.py tests/test_validate_pins_lockstep_lines.py tests/test_neutral_pin_validator.py tests/test_validate_pins_unreadable_workflow.py tests/test_validate_pins_unreadable_workflows_dir.py tests/test_validate_pins_without_git.py tests/test_repo_hygiene.py tests/test_cli_reference.py: 264 passed in 80.89s
• the same with tests/test_doctor_gitlink_repairs.py tests/test_doctor_validator_rows.py, which run this gate under the doctor: 72 passed in 83.39s

No doctor suite quotes this note (git grep "agree with the gitlink" finds only the template and tests/test_pin_validator.py), and no doc quotes it.

Pinned copy

templates/assembly-root/scripts/validate-pins.py is a PINNED SHAPE COPY: every assembly root carries scripts/validate-pins.py as a row of contracts/shape-pin.yaml. It is not in FAMILY_COPIED_VERBATIM, so no family holder carries it. A change to it shows each project an upstream-changed row for scripts/validate-pins.py. Released at v1.1.1, it adds that row for projects at v1.1.0.

🤖 Generated with Claude Code

Summary by Sourcery

Fix workflow pin agreement reporting to accurately reflect references that match the repository gitlink.

Bug Fixes:

• Correct workflow pin validation notes so they count only references matching the gitlink, report partial agreement as N of M, and omit the note when no references agree.

Tests:

• Add parameterized coverage for mismatched, partially matching, and fully matching workflow references.

[sourcery-ai]

Reviewer's Guide

Fixes validate-pins.py so workflow agreement notes count only gitlink-matching references, report partial matches as N of M, and are omitted when none agree; adds focused parameterized regression tests for mismatch, partial-match, and all-match cases.

Flow diagram for workflow reference agreement reporting

flowchart TD
    A[Workflow reference names the leg repository] --> B{Reference SHA matches gitlink?}
    B -->|Yes| C[Increment agree]
    B -->|No| D[Record pin-workflow-ref-mismatch finding]
    C --> E{agree > 0?}
    D --> E
    E -->|No| F[No agreement note]
    E -->|Yes| G{agree equals seen?}
    G -->|Yes| H[Report N workflow references agree]
    G -->|No| I[Report N of M workflow references agree]

Loading

File-Level Changes

Change	Details	Files
Correct workflow-reference agreement accounting so the note reflects only references matching the gitlink and distinguishes partial agreement.	Track matching references separately from all references naming the repository. Keep mismatches as findings while incrementing the agreement count only for matching SHAs. Suppress the note when no references agree; otherwise report either the total or N of M. Document the corrected behavior and issue context in the function docstring.	templates/assembly-root/scripts/validate-pins.py
Add parameterized regression coverage for all agreement-counting states.	Add a helper that generates workflows with configurable matching and mismatching SHAs. Verify no note for an entirely mismatched reference, 1 of 2 for a partial match, and the total for all matches. Add pytest parametrization and preserve assertions on the exact emitted note.	tests/test_pin_validator.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#739	Count only workflow references whose SHA matches the gitlink, omit the agreement note when none match, and report “N of M” when only some match.	✅
#739	Ensure the doctor’s pins row remains consistent with the validator’s output.	✅

Possibly linked issues

• validate-pins.py: the <repository>: N workflow @<sha> reference(s) agree with the gitlink note counts the references that do NOT agree, so it is printed beside the pin-workflow-ref-mismatch finding for the same reference #739: The PR implements the issue’s requested counting, mixed-reference wording, and suppression when no references agree.

---

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-17T01:09:07Z) Independent review of #769 by RV-b (opus), on head 787d7e1e: READY. No MUST and no SHOULD; one optional NIT. It lands only after the v1.1.0 tag.

RV-b measured every count case on a real scaffold, comparing main's gate with this PR's. The note now counts only the references at the gitlink, and no path prints it for a reference that does not agree. All four mutants fail the new test, and every merge is clean.

The issue's claims, on main e3137010 and on the head:

• One reference off: main prints the pin-workflow-ref-mismatch finding and 1 … agree with the gitlink for the same reference. The head prints the finding and no note.
• One at and one off: main says 2 … agree; the head says 1 of 2 … agree.
• The doctor's pins row does not relay the gate's ok lines. The writer was right, against the issue: PASS_REPORTS (shape-doctor.py:1487-1491) relays only skip, WARNING and note blocks, and the word "agree" appears in no row in any of the three states measured. No doctor change is needed.

Count cases (main → PR). M is the number of 40-hex references to that leg's repository, the only kind the gate's regex (validate-pins.py:90-93) sees.

case	main	PR
no references	no note	no note
one off	1 agree + finding	no note + finding
two, both off	2 agree + 2 findings	no note + 2 findings
one at, one off	2 agree + finding	1 of 2 + finding
both at	2	2
code at, spec off	spec 1 agree + spec finding	spec finding, no spec note
at, plus a 12-hex short sha and @v1	1	1
upper-case sha at the gitlink	1	1
UTF-16 workflow file	REFUSED workflow-unreadable, exit 2	same
at in a.yml, off in b.yml	2 agree	1 of 2
at, plus a commented-out # uses: off	2 agree	1 of 2, as on main the comment is still counted

Pinned copy and docs.

• templates/assembly-root/scripts/validate-pins.py is a pinned assembly-root copy, so projects will see one upstream-changed row. The PR body says so.
• There is no other copy of this function.
• Outside tests/test_pin_validator.py, nothing quotes the note's wording: no README, AGENTS.md, docs/cli.md or handbook text.

N1 (NIT, optional). tests/test_pin_validator.py:170, code_workflow, has the same lane.yml body that the two neighbouring tests (:147-153, :157-163) write inline. Those two tests could call it instead. SonarCloud passed, so this is optional.

Pre-existing, not #739's. A reference by a short sha or by a tag (@v1) is invisible to the lockstep gate, and a commented-out uses: line is counted and flagged. Main behaves the same.

Mutants (tests/test_pin_validator.py):

mutant	result
count every reference again	2 failed: [one-off], [one-of-two-off]
note when agree == 0	1 failed: [one-off]
drop " of M"	1 failed: [one-of-two-off]
denominator = references that do not agree	1 failed: [one-of-two-off]

Tests:

tree	result
the head, 13 files (the validate-pins suites, the doctor's gitlink and validator-row suites, test_update_shape_kept_helper, hygiene, cli-reference, agents-md-codes)	628 passed in 225.70s
the PR's tests over main's gate	2 failed, 20 passed
the merge with #770, #771 and #772	177 passed

Merges. git merge-tree --write-tree is clean with e3137010, #770 (837920c2), #771 (c90a137c), #772 (1d149933), and all three together.

CI at 01:08Z: SonarCloud, package and tests-git-bash passed. The Linux tests job was pending.

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

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