Problem
The README marks the manifest schema as "not yet semver-stable" but there's no CHANGELOG, no migration table, and no statement of which CLI versions read which schema versions. Pairs with the schema_version field issue — that adds the runtime hook; this adds the human-readable contract.
Proposed
- Adopt Keep-a-Changelog format (
CHANGELOG.md at repo root)
- Each release entry:
Added / Changed / Deprecated / Removed / Fixed / Migration (when schema_version bumps)
- New
docs/versioning.md declaring: supported CLI versions, schema-version to CLI-version compatibility matrix, deprecation window policy (e.g., N-1 minor supported)
- Release workflow injects the matching CHANGELOG section into the GH release body
Impact
Adopters get an upgrade contract. Schema breaks become a recognized event with a documented migration, not a runtime puzzle.
Problem
The README marks the manifest schema as "not yet semver-stable" but there's no CHANGELOG, no migration table, and no statement of which CLI versions read which schema versions. Pairs with the
schema_versionfield issue — that adds the runtime hook; this adds the human-readable contract.Proposed
CHANGELOG.mdat repo root)Added/Changed/Deprecated/Removed/Fixed/Migration(whenschema_versionbumps)docs/versioning.mddeclaring: supported CLI versions, schema-version to CLI-version compatibility matrix, deprecation window policy (e.g., N-1 minor supported)Impact
Adopters get an upgrade contract. Schema breaks become a recognized event with a documented migration, not a runtime puzzle.