ci: gate the two release-drift failures this release actually hit

[padak]

Stacked on #638 — review/merge that first.

Why

Preparing 0.88.0 surfaced two mistakes that no check in this repo could see. Both are mechanical, so both are now gated rather than left to the next person's diligence.

1. make version-gate-check (new, in CI)

Rejects any (since vX.Y.Z) / X.Y.Z+ marker whose version has no CHANGELOG entry.

keboola-expert.md turns those markers into a hard refusal rule — the agent compares the user's installed kbagent version and declines anything newer. A marker naming a version that never ships makes the agent refuse a flag the user actually has. Collapsing the unreleased 0.89.0 into 0.88.0 broke 20 markers across 8 files at once, and only a hand-grep caught them.

Verified it catches the real thing:

$ sed -i '' 's/(since v0.88.0)/(since v0.89.0)/' .../gotchas.md
$ make version-gate-check
ERROR: version gate names a version with no changelog entry.
  0.89.0 is not a CHANGELOG key -- named by:
    plugins/kbagent/skills/kbagent/references/gotchas.md:4103
    ... (5 locations)
exit=1

Scope is deliberately the two explicit gate syntaxes, never a bare version-looking string. Prose carries keboola-mcp-server v1.76.2, manifest v3, RFC 8628 — flagging those makes the check unusable. The cost is that a stale bare mention (# 0.89.0 MCP-parity flags in a test comment) passes silently; those mislead a reader, not the agent's version gate. Documented in the script docstring.

Offline (reads the tree only), so unlike changelog-check it runs per-PR in CI. That splits the existing CI comment's claim that these tags "need judgement": whether a marker names the right version does and stays with /kbagent:review; that the version exists does not.

Covers 418 markers across 71 versions today, all resolving.

2. make changelog-check gains the inverse direction

It verified every release has an entry. Nothing verified every entry has a release.

A version bump rides along with any PR touching pyproject.toml; publishing is a separate manual step. So a merge-train strands a whole block and the next tag absorbs it — notes written from one block, the other shipped unannounced. Exactly what happened here.

It has happened 18 times against 161 published releases:

0.47.0 0.47.2 0.48.0 0.51.1 0.60.1 0.60.2 0.60.3 0.60.4
0.63.3 0.63.4 0.67.0 0.68.0 0.69.0 0.70.0 0.70.1 0.78.0 0.81.0 0.83.0

Frozen in KNOWN_UNRELEASED as a baseline the check stops from growing — publishing those tags retroactively would advertise a wheel nobody can install, and rewriting old notes reaches nobody who already read them.

One correctness note worth reviewing: the audit is bounded to the window gh release list --limit actually returned. Without that floor, a truncated fetch reports every early release as unpublished — the first draft did exactly that (--limit 50 vs 173 changelog keys → 124 false positives). The same truncation is why the orphan count was first measured as 5 rather than 18; the limit is also raised 50 → 500 so the window covers the whole history.

Tests

20 added, all offline. Both helpers are pure, so the audits are unit-testable without network; the live-repo assertions guard the guards — test_the_scan_actually_finds_gates fails if a broken glob would make the version-gate check pass vacuously.

make check green: 5853 passed, 12 skipped.

---

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.