GitHub Actions workflow: tag + release check after plugin-version bump

[michael-wojcik]

Problem

The standing CLAUDE.md pin "Tag + GitHub release after every plugin-version bump" requires:

• Annotated git tag v{version} pushed to origin.
• GitHub release at gh release create v{version} --title "..." --notes "..." with structured notes covering the fix/feature, key implementation notes, test cardinality delta, follow-up issues filed during the session, and calibration corpus data.

The rule is prose-only, governed by operator discipline at PR-merge time. Past version-bump cycles have generally followed it, but there's no mechanical defense against a version-bump merge that ships without a corresponding tag + release.

Failure mode

Plugin version bumped from 4.1.4 to 4.1.5 in a merged PR. Operator forgets to tag/release post-merge. Users discover the version increment via plugin.json but have no GitHub release page documenting what changed; they have to trawl git log to figure it out. The release page is the user-facing artifact for plugin distribution; missing it degrades the distribution surface.

This has happened at least once in the recent history per the standing pin's existence (the pin was filed because it was a recurring discipline failure).

Proposed enforcement

A GitHub Actions workflow at .github/workflows/version-bump-release-check.yml that:

1. Triggers on push to main (post-merge).
2. Detects whether the merge commit modified pact-plugin/.claude-plugin/plugin.json AND specifically the version field.
3. If yes:
   • Read the new version value from the commit's tree.
   • Check whether a tag v{version} exists in the repo at this point.
   • Check whether a GitHub release for tag v{version} exists via gh release view.
   • If either is missing N hours after the merge (N=24 or so), open a GitHub issue OR fail a CI status check that the operator must address.

Failure-mode design choice

Two options for what the workflow does when the tag/release is missing:

Option F-a (soft, recommended): file a GitHub issue titled "Missing tag + release for v{version}" assigned to the merge author. Non-blocking. Reminds without being heavy-handed.

Option F-b (strict): fail a status check on the merge commit. The check goes red until tag+release land. Blocks any subsequent PR that requires a green main if branch protection is set that way.

Lean toward F-a for v1; F-b is too aggressive given the workflow can't distinguish "operator forgot" from "operator deliberately deferred" from "release tooling temporarily down."

Optional extension: validate release notes

If the release exists, validate its notes contain the structured sections per the standing pin (the fix/feature in plain prose, key implementation notes, test cardinality delta, follow-up issues, calibration corpus). Skip for v1 — too judgment-heavy for an automated check.

Acceptance

• New .github/workflows/version-bump-release-check.yml.
• Triggers on push to main when plugin.json version field changes.
• Checks for tag v{version} and GitHub release at v{version} within the configured grace window (default 24 hours).
• On missing tag/release: file an issue (F-a) assigned to the merge author. Issue body should reference the merge commit + provide the standard tag/release commands per the standing pin.
• Workflow is idempotent: doesn't file duplicate issues if it runs multiple times for the same merge.
• Tests / dry-run validation: simulated merge of a version-bump commit triggers the issue creation; simulated merge of a non-version-bump commit is a no-op.
• Documented in SHARED_CONVENTIONS.md (Phase 4 of Umbrella: merge guard end-to-end + hook contract documentation + governance meta-pattern #677) under "version-bump correctness."

Bundling

Recommended bundle target: PR-Version alongside the plugin-version 4-file dance hook (separate issue). Both deliverables are about plugin-version-bump lifecycle correctness:

• The 4-file dance hook catches drift at edit time (pre-merge protective).
• This workflow catches missing release artifacts post-merge.

Ships together as "version-bump lifecycle hardening" — variety 7-8 combined, coherent concern.

Background

Surfaced during Phase 5 governance audit on umbrella #677 (Category B row 4). The "tag + release after version bump" rule is a CLAUDE.md pin filed during PR #663 cycle. The mechanical complement to the standing prose pin closes the discipline-drift gap.

Out of scope

• Auto-creating the tag and release on the operator's behalf. The release notes are content that requires human curation per the standing pin's structured-sections requirement; auto-generating them would land low-quality release pages.
• Semantic version validation (patch vs minor classification). Same reason as the 4-file dance hook's scope: too judgment-heavy.
• Cross-repo or fork-aware tag detection. Single-repo workflow is sufficient.