design(release): moving v2 floating tag is breaking for consumers pinned to older v2.x.x reusable-workflow tags

[cbeaulieu-gt]

Symptom

After moving v2 from e92a334 (v2.5.1) to a3d11c4 (v2.6.0), glitchwerks/mom-bot (pinned to claude-pr-review.yml@v2.5.1) immediately broke with:

::error::No authentication token provided. Set app_id + app_private_key inputs.

Run: https://github.com/glitchwerks/mom-bot/actions/runs/25603534852. The mom-bot caller workflow was unchanged. Only the floating v2 tag moved.

Root cause

This repo's reusable-workflow stubs at any given v2.x.x reference internal composite actions via the floating @v2 tag, per the convention documented in CLAUDE.md ("Why absolute refs, not relative paths"):

# .github/workflows/claude-pr-review.yml @ v2.5.1
- uses: glitchwerks/github-actions/pr-review@v2  # ← floating!

So a consumer pinned to claude-pr-review.yml@v2.5.1 actually gets:

• Reusable workflow body: frozen at v2.5.1 (correct, as expected)
• Composite action it calls: whatever @v2 points to right now (not frozen!)

When @v2 was moved to a3d11c4, the consumer's frozen wrapper started calling the new pr-review/action.yml which requires app_id / app_private_key inputs that the v2.5.1 wrapper does not pass through. Result: every consumer pinned to v2.5.1 is broken until they bump to v2.6.0 AND add the App secrets.

The repo's release process (CLAUDE.md: "move both v2 and the new v2.x.x tag") does not surface this risk — the implicit assumption is that v2 floating = additive-only. That assumption was violated by #250 (App-token requirement is breaking).

Two distinct problems

1. The release-process docs do not flag breaking-change scenarios. A change to a composite action that adds a required input is a breaking change for every reusable-workflow consumer, regardless of whether they update their workflow pin. The v2 tag move is the silent breaker.
2. The internal @v2 floating self-reference means consumers cannot freeze their version. Even pinning to a specific v2.5.1 reusable workflow does not freeze the implementation. The only way to truly freeze is to fork or change the convention.

Fix options

For (1) — release-process documentation

• Add a "breaking change" section to CLAUDE.md Versioning. Define what counts as breaking (new required inputs, removed inputs, output schema changes, identity changes).
• Add a release checklist: before moving v2, audit git diff v2.5.1..main for breaking signals.
• For breaking changes: bump major (v3), retire v2, force consumer migration. Or: do not move v2, only the v2.x.x tag, and document that consumers must explicitly opt in.

For (2) — internal self-reference convention

• Pin the internal pr-review@v2 reference inside claude-pr-review.yml to the same SHA the reusable workflow itself ships at. Each v2.x.x tag of claude-pr-review.yml would point internally to the matching v2.x.x tag of pr-review/action.yml. True version freezing.
• Trade-off: couples reusable-workflow versioning to composite-action versioning. A release of one requires re-tagging the other.

Recommended

• Short term: unblock mom-bot by bumping its pin to @v2.6.0 and adding App-secret inputs.
• Medium term: option (1) — release-process docs that flag breaking changes and the v2-tag-move review gate.
• Long term: option (2) — tighten the internal ref so a consumer pinned to v2.5.1 actually gets v2.5.1 behavior.

Acceptance

• Release process docs describe how to detect breaking changes before moving v2.
• A breaking change requires either a major bump or an explicit opt-in tag (no auto-deploy via v2 move).
• Internal-ref design either pins to matching version, or is documented as deliberately floating with the consumer-impact callout.
• mom-bot PR feat: add Claude PR review workflow to this repo (dogfood) #21 is unblocked separately (immediate fix; not gated on this issue).

Related

• feat(pr-review): switch to App-token identity (revisit #114 carve-out) #250 (PR feat(pr-review): switch to App-token identity (#250) #252) — the breaking change that exposed this
• fix(pr-review): author_association check is blind to private org membership — self-PRs get blocked as external #253 (PR fix(pr-review): API-fallback collaborator check + authorized_users input (#253) #254) — the second change shipped in v2.6.0
• fix(pr-review): API-fallback collaborator check fails with github.token — cannot enumerate collaborators without push #255 — companion bug: API fallback failure with github.token
• v2.6.0 release: https://github.com/glitchwerks/github-actions/releases/tag/v2.6.0

🤖 Generated by Claude Code on behalf of @cbeaulieu-gt