Releases and Changelogs

Feature	Feature status	claude	codex	cursor
`releases`	`implemented`	`metadata_only`	`metadata_only`	`metadata_only`

Support vocabulary: Feature Reference

A workspace release turns accepted source-change reasons into stable source-unit versions, generated changelogs, append-only release evidence, updated locks, and refreshed provider output. It does not publish a package, sync a distribution, install output, or prove activation.

Plan Before Applying

skillset release plan
skillset release apply
skillset release apply --yes

plan and an unconfirmed apply write nothing. The plan shows selected pending reasons, ignored audit entries, release scopes, version changes, and source hashes. Confirmed apply consumes all eligible pending reasons; release commands reject build --scope because scoped release selection does not exist.

The publishing guide owns the end-to-end workflow. The generated release reference owns exact command syntax.

What Apply Writes

A confirmed release with at least one entry to apply:

folds pending event files from .skillset/changes/events/ into .skillset/changes/ledger.jsonl and removes them;
appends release.applied evidence to .skillset/changes/ledger.jsonl;
moves applied reasons into append-only history and appends release records;
advances source-unit version authority and records deletion tombstones;
regenerates entity-local CHANGELOG.md projections;
refreshes generated provider versions, output, and locks.

With no entry to apply, release apply writes nothing. Events that lifecycle commands such as draft record without a change entry stay in their pending files, where readers still fold them, until the next release that has an entry folds them in.

Release state wins over inline source versions when a release scope exists. Otherwise inline metadata remains the import/read fallback. Pending reasons never appear as a pending section in committed changelogs. Cached .skillset/changes/state.json is published atomically so readers observe a complete previous document or a complete replacement.

Correct Wording Without Editing Generated Changelogs

Timing	Intent	Command
Before release	Change pending changelog wording	`skillset change reason <@ref> --reason "…"`
After release	Correct an applied source-change reason	`skillset change amend <@ref> --reason "…"`
After release	Correct release-event notes	`skillset release amend <@ref> --reason "…"`

Amendments append evidence and leave original history auditable. Rebuild after the correction to refresh the generated changelog.

Errors and Recovery

Problem	Result	Recovery
No pending eligible reasons	Plan reports no release	Add or correct change coverage
Stale source evidence	Apply refuses	Run `change check` and review `change refresh`
Invalid or corrupt release state	Validation fails before output writes	Repair source-side state from trusted ledger/history evidence
Generated changelog was edited	Output checks refuse to treat it as source	Use the correction table above
`--scope` is supplied	Command rejects it	Apply the complete release or defer it
Output collision or target-side edit	Build safety creates a backup or refuses	Follow Output Safety

An ignored change stays auditable but contributes no version bump or changelog entry. Its source hash is still recorded at apply so status does not repeatedly report the dispositioned edit.

Separate Release Authorities

Skillset workspace releases own .skillset/changes/, source-unit versions, and entity changelogs. Changesets owns versions and changelogs for the public npm packages. Distribution plans and marketplace indexes are separate delivery evidence. Completing one lane does not authorize another; see Package Releases.

Provenance

Release records include selected change ids, resolved versions, source hashes, and baseline metadata. Deleted scopes become tombstones. skillset change status uses ledger-derived release state as its durable baseline, even before the release commit exists.

Release records are append-only and derived release state resolves per scope in file order, so keep .skillset/changes/*.jsonl on the merge=union strategy described in Merging Change Streams.

See Source Change, Release, and Dependency Provenance, Changelog and Version Bump Workflow, and Reason-Only Change Ledger and Derived State.