fix(pr-size): require a pinned workflows_ref, guard empty refs, drain the exemption (BE-5858)

[mattmillerai]

STACKED — merging lands on matt/be-5546-require-workflows-ref (PR #103, same author), NOT main. This PR is based on #103's branch because the guard step and the whole .github/workflow-pins/ lint it edits exist only there. Merge #103 first; GitHub then retargets this PR to main. Do not treat this as "ready to merge" into main on its own.

ELI-5

A consumer repo pins our PR-size check by exact commit SHA, which is supposed to mean "run exactly this code, forever." But the check downloads its actual counting tool separately, using a second setting called workflows_ref — and that setting used to quietly default to main. So you could pin the workflow to a frozen SHA and still get a tool built from whatever landed on main five minutes ago. The pin looked airtight and wasn't. This PR removes the default and makes the workflow refuse to run if the setting is missing, so the pin now means what it says.

What changed

pr-size.yml was the last of the four reusable workflows still carrying a workflows_ref default — this closes the BE-5546 pin-integrity sweep.

• Input declaration — required: true, default: main deleted, description rewritten to mirror the wording fix(workflows): make workflows_ref required, guard empty refs, lint the default (BE-5546) #103 used in cursor-review.yml / groom.yml / agents-md-integrity.yml.
• Header caller example — now says the ref is REQUIRED and must match the uses: SHA, instead of "defaults to main".
• Runtime guard — the Require a pinned workflows_ref step, copied byte-for-byte from cursor-review.yml (verified programmatically: both extract to an identical 1425-character block), inserted immediately before the Load check-pr-size tool checkout. It is needed because GitHub does not enforce required: true for workflow_call inputs: an omitted input arrives as '', and actions/checkout with ref: '' silently takes the default branch. The step takes the value via env: (never interpolated into the script body), strips whitespace, hard-fails on empty, and warns when the ref is not a full 40-hex SHA.
• KNOWN_EXEMPT drained — "pr-size.yml" removed along with its rationale block. This is not optional bookkeeping: the lint hard-fails on a stale exemption by design, so leaving it would turn CI red. The frozenset is now empty, with the explanatory comment kept.
• Docs synced — the root README.md usage note and .github/workflow-pins/README.md both named the three fixed workflows / the pr-size exemption and would otherwise have gone stale.

The guard is added only to the pr-size job. The comment job never consumes workflows_ref (it checks out nothing) — verified in this diff, not just inherited from the ticket.

Why this is safe to drop the default

The change denies something that previously worked (omitting the input), so I re-ran the BE-5856 caller audit empirically rather than trusting it:

• vars.PR_SIZE_CALLERS has exactly one entry, and it resolves to a live repo.
• That caller already passes workflows_ref explicitly, SHA-matched to its own uses: pin (same 40-hex SHA on both lines) — so it is unaffected by the removal.
• The pr-size check is not a required status check on that repo's default branch (the branch carries no protection rule at all).
• A global GitHub code search for github-workflows/.github/workflows/pr-size.yml returns 3 hits: this repo's own header example, this repo's bump-callers test fixture, and that one caller. No unenrolled consumer exists — the roster audit holds in both directions.

Caller repo names are withheld here per the public-repo hygiene rule; the evidence above was gathered from vars.PR_SIZE_CALLERS and the code-search API.

No caller change is needed. After this merges, bump-pr-size-callers.yml bumps the caller's uses: SHA and workflows_ref in lockstep — confirmed in bump-callers.sh, whose SHA_ADDR matches /github-workflows|workflows_ref/, so both pins move together.

Verification

• python3 .github/workflow-pins/check_workflow_pins.py → green: "4 workflow(s) declare workflows_ref, none with a default, every ref checkout guarded (0 exempt)."
• python3 -m unittest discover -s .github/workflow-pins/tests -p 'test_*.py' → 71 passed.
• actionlint .github/workflows/*.yml → clean.
• Other suites (cursor-review 40, agents-md-integrity 18, groom 170, bump-callers 123 + shellcheck) → all green.
• Grep sanity: no default: main in pr-size.yml; exactly one Require a pinned workflows_ref step, at line 166, ahead of Load check-pr-size tool at line 190.

Judgment calls

1. Stacked instead of blocked. The ticket's precondition said to hand this back if fix(workflows): make workflows_ref required, guard empty refs, lint the default (BE-5546) #103 had not merged. fix(workflows): make workflows_ref required, guard empty refs, lint the default (BE-5546) #103 is open (CI green, but mergeable: CONFLICTING against main — its author needs to reconcile it). Both reasons the ticket gave for waiting are resolved by stacking rather than waiting: the files to edit exist on fix(workflows): make workflows_ref required, guard empty refs, lint the default (BE-5546) #103's branch, and fix(workflows): make workflows_ref required, guard empty refs, lint the default (BE-5546) #103's own lint CI is untouched because this change lands on a separate branch that can only merge after fix(workflows): make workflows_ref required, guard empty refs, lint the default (BE-5546) #103 does. The standing team directive is to stack on an unmerged blocker that carries buildable branch code rather than gate on it, so I stacked. If you would rather this had waited, closing this PR costs nothing — the branch keeps the work.
2. Two test tweaks beyond the ticket's list. pr-size.yml was added to the two "this repo's own workflows" test loops, and the guarded-checkout count went 12 → 13. Without this the new guard has no direct regression pin.
3. Two doc lines beyond the ticket's list. Removing the exemption made the root README.md sentence ("on cursor-review.yml, groom.yml, and agents-md-integrity.yml…") and the workflow-pins/README.md "today: pr-size.yml" note factually wrong. I rewrote both rather than leave stale docs in the same commit that invalidated them.

No unmet acceptance criteria.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: cb6ca929-138b-4cae-9860-88c34ed3bcbf

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🔍 Cursor Review — Consolidated panel

Triggered by @mattmillerai.

Found 4 finding(s).

Severity	Count
🟠 High	1
🟡 Medium	2
🟢 Low	1

Panel: 8/8 reviewers contributed findings.

[mattmillerai]

🤖 The reviews loop filed Linear follow-up ticket(s) for review thread(s) deferred as out of scope for this PR:

• BE-6505 — Sync docs/callers/ for the workflows_ref required-no-default sweep (BE-5546/BE-5858) — filed as agent-spike (premise unverified)
• BE-6506 — Make the workflows_ref guard hard-fail on a non-40-hex ref across all four reusable workflows — filed as agent-spike (premise unverified)

The following carry agent-spike instead of agent-ok because their reachability claim was not backed by evidence (BE-5378) — the claim is investigated before any code is written, and "the premise does not hold" is a valid, successful outcome:

• Sync docs/callers/ for the workflows_ref required-no-default sweep (BE-5546/BE-5858) — no reachability block in the proposal
• Make the workflows_ref guard hard-fail on a non-40-hex ref across all four reusable workflows — no reachability block in the proposal

[mattmillerai]

Merging unreviewed. Blast radius: check-pr-size reusable only — makes workflows_ref a required pinned input, guards empty refs, and drains the exemption path. Why safe without review: every downstream caller pins this repo by full 40-hex commit SHA, so no consumer changes behavior until a bump PR moves a pin. Full cursor-review panel plus Socket/CodeRabbit green on this head. Note for the follow-ups: #103 and #118 touch the same workflows_ref contract and will need a rebase on top of this — I'll reconcile them rather than land overlapping validation twice.