feat(gates): metamodelVersion must move when the metamodel does — 0.9 → 0.10

[dmealing]

Why

PR #321 made metamodelVersion the METADATA-compatibility axis — a breaking metamodel
change moves ITS major, not the package major. Then I checked whether that number had ever
moved.

It read "0.9" from the day it shipped (PR #145, 2026-07-02) through 57 releases —
including 0.21.0, the deliberate pre-1.0 breaking slot that retired assembly origins from
object.value and shrank @role, and 0.22.0, which added a whole registered type family.

It was a label, not a version. #321 handed the compatibility promise to a number nobody was
maintaining. This is the missing half.

The gate

scripts/check-metamodel-version.mjs, registered in ci-local.sh's gates lane (so
local-ci.yml enforces it on every push to main).

It diffs expected-registry.json — already the byte-exact bill of materials every port is
gated against, so no new artifact — against its content at the last release tag,
classifies every difference, and fails if the declared version did not move by at least
that much. Same shape as buf breaking --against '.git#tag=…' / oasdiff: compare to the
released baseline, classify, require the declared version to match.

Baseline is a release tag, not HEAD~1, deliberately: the version promises against what
adopters actually have, and a per-commit baseline would demand a bump from every PR in a
release cycle rather than the first one.

Change	Required move
type/subtype removed · attr removed, made required, retyped or re-arrayed · enum member removed or an open attr closed · child rule removed, min raised or max lowered · default subtype changed	major
type/subtype added · optional attr added · enum member added · child rule added or relaxed · default subtype added	minor
prose only (description / rules / whenToUse)	none — but read the warning

Pre-1.0 a breaking change moves the MINOR, for the same reason the package line works
that way at 0.x: 0.y makes no compatibility claim there is anything to break. At 1.0
the major becomes real. (This is the one judgement call I made inside the ratified policy —
easy to overrule, it's one function.)

It caught a real one on its first run

Against v0.23.2:

BREAKING (1):
  - attr removed: template.output @promptStyle
ADDITIVE (2):
  - attr added: template.prompt @promptStyle
  - attr added: template.prompt @responseFormat

declared: 0.9 (unchanged since v0.23.2)
required: a MINOR bump

That is ADR-0052, merged yesterday. Hence metamodelVersion 0.9 → 0.10 in this PR,
written by the gate's own --set, which updates the manifest and all four port constants at
once (Kotlin emits through the JVM's).

That a partial edit is caught by registry-conformance is verified, not assumed —
reverting the TS constant alone turns registry-conformance.test.ts red with "TS registry
drifted from the committed manifest."

A missing baseline FAILS

This repo has 90 release tags; the only way to see zero is a checkout that did not fetch them
(fetch-depth: 1), and a baseline-less run would pass unconditionally — a green tick that
checked nothing. So it fails loud and names the likely cause. --allow-no-baseline opts a
genuinely tagless checkout out. (local-ci.yml's gates job already uses fetch-depth: 0.)

The blind spot, stated rather than hidden

A rule can change with no machine-readable footprint. #210 is the proof: retiring
assembly origins from object.value was a breaking metamodel change whose only manifest
edit was the rules PROSE string. The loader enforced the new rule; the structured
vocabulary was untouched.

So prose changes are reported as a warning with a direct question — did the RULE
change, or only its wording? — not classified. A typo fix and a semantics change are
indistinguishable there, and failing on every wording edit would train people to ignore the
gate. Answering it is a human step in every release, and the gate asks every time rather
than pretending it covered it.

Tests for the classifier itself

scripts/test-metamodel-version.mjs — 40 checks driving all 15 rules in both directions
against synthetic manifests, following the test-publish-set.mjs pattern. The gate itself
can only ever prove the happy path once it is green, so a rule silently backwards (a max
comparison inverted, a narrowing read as a widening) would otherwise ship as a gate that
passes breaking changes. Includes 0.9 → 0.10 satisfying numerically where it regresses
lexically — the two-digit-minor trap, and the exact step this gate first demanded.

Prompts + docs

• releasing skill — Phase-0 preflight row, plus a "two numbers, two contracts" section
• docs/RELEASING.md — classification table, the release checklist for a bump, and what
  the gate cannot see
• AGENTS.md / CLAUDE.md — any vocabulary change is also a version edit; use --set
• agent-context/templates/always-on.md.mustache — adopter-facing: which number tells
  you your metadata needs work vs your build (5 byte-gated fixture sets regenerated)
• The design doc + ADR-0035 Am. 2 gain the enforcement half they were missing
• CHANGELOG — the version move, per the rule this PR writes down

Verification

With the bump in place: TS 6573 pass / 38 skip / 0 fail · C# 291 + 53 + 942 + 363
(1 skip), 0 fail · Java + Kotlin reactor BUILD SUCCESS · Python 1825 pass / 0 fail ·
ci-local.sh --only gates green.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DhpswkF1NvwxhFWMmdAT15