versions.json: describe what the code really does, or build what the spec promises?

[nlebovits]

The problem. Our versioning spec describes automatic breaking-change detection: the tool is supposed to fingerprint the data schema on every update and bump the major version when something breaks. None of that was ever built. In reality, every add bumps the patch version and records "not breaking," unconditionally.

Where we're leaning: rewrite the spec to describe the current, honest behavior (always a patch bump), and treat real breaking-change detection as a separately scoped follow-up feature. The sprint's whole purpose is to make the spec truthful; shipping a spec that describes imaginary behavior is the thing we're trying to stop doing.

Also in this bucket: the catalog-level versions.json file currently exists only as a JSON schema — there's no prose documentation explaining what it is or what the fields mean. That needs writing. (The related bug where the writer produces files its own schema rejects is already ticketed as #561.)

---

Part of the July 2026 spec sprint. Hub: discussion #570 · work tracker: epic #564 · everything here carries the spec-sprint label.

[nlebovits]

Defer, hash out properly. Takes some work over time.