fix(distribution): cut GitHub Releases on tag push (Glama tracking gap)

[SoapyRED]

Summary

Closes the Release-gap leg of the distribution cascade. Chrome verification on Glama (2026-05-17, ~24 hours after Sprint 1's cascade-fix landed) showed Glama still on "Latest release: v1.0.0" with the Tool Definition cache stuck at 11 tools (current is 19) and Maintenance grade C. Diagnosed that Glama scrapes the GitHub Releases API specifically — and freightutils-mcp had zero Releases ever cut.

Companion: SoapyRED/freightutils-mcp#3 (workflow update) MERGED. Audit amendment at docs/audit/distribution-cascade-2026-05-16.md — 2026-05-17 section.

Phase 1 — Diagnosis (committed before any fix)

$ gh api repos/SoapyRED/freightutils-mcp/git/refs/tags --jq '.[] | .ref'
refs/tags/v1.0.4
refs/tags/v1.0.5
refs/tags/v1.1.0
refs/tags/v2.0.0
refs/tags/v2.1.0

$ gh release list -R SoapyRED/freightutils-mcp --limit 50
(empty)

$ gh api repos/SoapyRED/freightutils-mcp/releases
[]

5 tags, 0 Releases. Plus: v2.1.1 (current npm latest, current MCP Registry isLatest) had no git tag — Sprint 1's catch-up used workflow_dispatch + package.json read, bypassing tag creation.

Sprint 1 corrected the "GH Action cascades to Smithery + Glama auto-sync" myth (they scrape independently) but didn't draw the corollary that Glama scrapes the GitHub Releases API specifically. A tag push without a Release publish is invisible to Glama. That's why Glama remained on its first-ever-scrape value (v1.0.0) even after Sprint 1 made the Registry catch up.

Phase 2 — Backfill (in-sprint)

Created the missing v2.1.1 tag at commit 7236c42 (the npm-publish snapshot), then ran workflow_dispatch per version. Workflow's new idempotent guard correctly skipped the MCP Registry publish step on all four runs (versions already in Registry history) and fell through to the new Release-cut step.

$ gh release list --repo SoapyRED/freightutils-mcp --limit 10
v2.1.1    Latest    v2.1.1    2026-05-17T05:14:42Z
v2.1.0              v2.1.0    2026-05-17T05:15:30Z
v2.0.0              v2.0.0    2026-05-17T05:15:35Z
v1.1.0              v1.1.0    2026-05-17T05:15:43Z

v1.0.5 / v1.0.4 historical tags deferred — no CHANGELOG entries; backfill is Soap-manual if ever wanted.

Phase 3 — Workflow extension (companion PR, MERGED)

SoapyRED/freightutils-mcp#3 adds two things:

1. "Cut GitHub Release if missing" step at the end of the job. Pulls notes from freightutils-mcp/CHANGELOG.md via awk (between ## VERSION and the next ## heading). Falls back to a pointer line when no entry exists. --latest=true when version matches MCP Registry isLatest; --latest=false for historical backfills. Idempotent — skips if Release already exists.
2. "Check if version is already on MCP Registry" idempotency guard. Surrounds the existing publish / auth / server.json-commit steps with if: registry_check.outputs.already_published != 'true'. Without this, re-runs on already-published versions would error at mcp-publisher publish. This made the Phase 2 backfill possible without manual hacks.

Walkthrough — next routine release

npm version patch                  # bumps package.json, creates v2.1.2 tag
npm publish                        # canonical event, npm now has 2.1.2
git push --follow-tags             # tag push fires publish-registry.yml
  ├─ Resolve version: 2.1.2 (from tag)
  ├─ Sanity-check npm: v2.1.2 present ✓
  ├─ Update server.json to 2.1.2
  ├─ Check Registry: 2.1.2 NOT in history → publish runs
  ├─ Authenticate via GitHub OIDC
  ├─ Publish to MCP Registry → isLatest=2.1.2 ✓
  ├─ Commit server.json bump [skip ci]
  ├─ Verify Registry isLatest=2.1.2 ✓
  └─ Cut Release: no v2.1.2 Release exists → create with CHANGELOG
     notes, --latest=true ✓ → Glama picks up on its next scrape

Phase 4 — Encode forward (this PR)

• CLAUDE.md "Distribution cascade" section:
  • MCP Registry bullet: notes the publish step is now idempotent.
  • NEW GitHub Releases bullet explains the workflow's final step cuts Releases on tag push with CHANGELOG notes + --latest flag.
  • Glama bullet: corrected to specify Glama scrapes the GitHub Releases API specifically.
  • "Things that DO NOT cascade" bullet: a git tag without a Release is invisible to Glama.
• STATE.md distribution surfaces table refreshed (17 May, post-sprint):
  • NEW GitHub Releases row capturing the backfill state.
  • Glama row updated.
  • Sprint cadence bumped 19 → 20 with PR fix(distribution): cut GitHub Releases on tag push (Glama tracking gap) #45 entry.
• Skills-Claude/freightutils-distribution.md (external skill) amended in two sections — "Active surfaces" table and "When a surface looks out of date" troubleshooting.
• CHANGELOG.md + lib/changelog-data.ts carry a 2026-05-17 entry.

Test plan

• gh release list --repo SoapyRED/freightutils-mcp shows 4 Releases — v2.1.1 Latest + v2.1.0/v2.0.0/v1.1.0
• gh release view v2.1.1 --repo SoapyRED/freightutils-mcp confirms notes pulled from CHANGELOG.md (Smithery serverInfo fix + tighter Zod + .strict() — verified body preview matches CHANGELOG content)
• Workflow walkthrough above covers normal release path
• Phase 2 backfill exercised the dual-trigger / re-run path with the new idempotent guard — all 4 workflow runs SUCCESS in 16–24s
• npm run lint:seo-titles passes (103 title literals scanned, no double-brand)
• Smoke test against prod: 40/40 PASS
• Glama re-scrape: days-of-lag — Chrome re-verify 2026-05-20 to 2026-05-22 expected window
• Post-merge: prod /changelog renders the new entry; Sentry 5xx proxy quiet for 10 min

Exit criteria

• Audit doc amendment committed (commit 68abca3)
• v2.1.1 GitHub Release exists, marked latest, with CHANGELOG notes
• Workflow updated to cut Releases on tag push — verified via walkthrough above (companion PR Prealert MVP Lite (Heathrow-only, form-based) #3 MERGED)
• CLAUDE.md "Distribution cascade" section amended
• STATE.md distribution surfaces table refreshed
• FAULT 5 checklist applied (CI/docs sprint — most items N/A; see below)
• Smoke test green on prod (40/40)
• Sentry-quiet 5xx proxy: 0/5 5xx in 10 min post-merge

FAULT 5

CI/docs sprint, most items N/A:

• CHANGELOG.md entry added
• /changelog page (lib/changelog-data.ts) — entry added, Rule A still passes
• SoapyRED/freightutils-mcp README — n/a (tool count unchanged)
• All other items — n/a

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
freighttools	Ready	Preview, Comment	May 17, 2026 5:22am