gabrielmoreira Version Management
The Edition has a version. Heirs depend on it. Bumping it wrong breaks the fleet.
When to Use
- Cutting a new release of
Alex_ACT_Edition(template repo) - Classifying an incoming PR as patch / minor / major
- Reviewing whether an Edition change is breaking for deployed heirs
- Coordinating a phased rollout when a major version ships
Semver Rules for the ACT-Edition
The Edition is a template that heirs copy. The contract is therefore:
| Bump | What it means | Examples |
|---|---|---|
Patch (x.y.Z) |
Internal-only fixes; no heir-visible behavior change | typo in a SKILL.md, internal script refactor that produces identical output |
Minor (x.Y.0) |
Additive changes; heirs that ignore the new artifact still work | new skill, new instruction, new prompt, new optional config field |
Major (X.0.0) |
Breaking changes; heirs must update or stay pinned | renaming a skill, deleting a skill heirs reference, frontmatter schema change, mandatory new config field, behavior change of an existing skill |
The "would a heir notice?" test
For every PR you're reviewing for release, ask: if a heir is on the previous version and never updates, does this change break them?
- No, completely invisible → patch
- No, they just don't get the new thing → minor
- Yes, something they depend on is gone or changed → major
Breaking-Change Classification
Five categories of breaking change. All require a major bump:
| Category | Example | Required action |
|---|---|---|
| Removal | Deleting a skill | Add to deprecation log, ship in N-1 with deprecation notice first |
| Rename | feedback-triage → submission-triage |
Provide alias in N-1, remove alias in N+1 |
| Frontmatter schema | New required field on all SKILL.md | Migration script in release notes |
| Behavior change | Same skill name now does X instead of Y | Major bump only — do not silently change |
| Required config | New mandatory key in .github/config/*.json |
Migration script + clear error if absent |
Deprecation Protocol
Never delete in one release. Always two-step:
- Deprecate (minor bump) — add
lifecycle: deprecatedto the artifact's frontmatter, add a## Deprecatedsection explaining the replacement, keep it functional. Add todecisions/deprecations.md. - Remove (major bump) — at least one full release later, delete the artifact. The major version signals heirs to update.
A heir running N-1 should always have a working brain. The only path to "this no longer works" is a deliberate major upgrade.
Release Sequencing
For a major release with breaking changes:
- Run
release-preflightskill for mechanical gates - Run
coherence-auditto verify Edition ↔ Mall consistency - Cut the release on Edition repo (tag, CHANGELOG, GitHub release)
- Post fleet announcement (when fleet announcement infra exists)
- Wait observation window (2 weeks for major, 1 week for minor)
- Triage feedback that arrives in
feedback/inbox/
For patch and minor: steps 1–3 only, no announcement, no observation window.
Visible Markers
Every release decision records these in decisions/curation-log.md:
| Marker | When |
|---|---|
Bump: patch|minor|major |
Every release |
Breaks: <list of categories> |
Every major bump |
Deprecated: <list> |
Every minor that introduces deprecations |
Removed: <list> |
Every major that completes a deprecation |
Anti-Patterns
| Anti-pattern | Correction |
|---|---|
| Silent rename to "improve discoverability" | Major bump with alias path |
| Patch bump that ships a new skill | Minor bump — additive but not invisible |
| Major bump for typo fix | Patch bump — heirs don't notice |
| One-shot deletion without deprecation step | Two-step: deprecate in N, remove in N+1 |
| Calling a behavior change "a fix" | Behavior changes are always major, regardless of intent |
Falsifiability
This skill has failed if any of these occur within 90 days of any Edition release:
- A heir reports breakage from an N-1 → N upgrade we classified as patch or minor
- A removal lands without a deprecation notice in the prior release
- The curation-log lacks the required
Bump:marker for any release
Track in decisions/curation-log.md. If two failures occur in 90 days, retire this skill and re-author from observed evidence.