Version tags: deferred items from issue #56

Version tags: deferred items from issue #56

Follow-up work that was explicitly out of scope during the initial muse tag + muse label implementation. Each item below is a discrete deliverable that can be picked up independently.

Background

Issue #56 shipped muse tag add/list/read/delete/latest/push, muse label, full SemVer 2.0 ordering, push/pull integration, and muse describe using version tags as reference points. The following were deferred to keep #56 focused.

Deferred items

1. MuseHub GUI display of version tags

Version tags pushed to MuseHub are stored in musehub_version_tags but have no dedicated UI surface. A repo's version tag history should be visible on the hub similar to how GitHub shows tags on the releases page.

Covered in part by existing GUI release tickets. This item tracks surfacing .muse/version-tags/ specifically in the repo detail view.

2. muse release integration

muse release add v1.0.0 currently creates a MuseHub release record independently of muse tag. The two should be linked: creating a release should optionally stamp a local version tag at the same commit, and creating a version tag should optionally create a draft release on the hub.

Proposed CLI:

muse release add v1.0.0 --tag          # creates release AND local version tag
muse tag add v1.0.0 --release          # creates version tag AND draft hub release

3. muse tag sign — cryptographic signing of version tags

Version tags should optionally carry an Ed25519 signature over (repo_id, tag, commit_id) so downstream consumers can verify the tag was created by an authorized identity.

Proposed:

muse tag add v1.0.0 --sign             # sign with identity from ~/.muse/identity.toml
muse tag verify v1.0.0                 # verify signature against stored public key

Wire format addition to VersionTagRecord:

signer_public_key: str   # "ed25519:<base64url>" or "" when unsigned
signature:         str   # "ed25519:<base64url>" or "" when unsigned

4. Tag listing on the remote without fetching

Currently, seeing what version tags exist on a remote requires muse pull first. A read-only query endpoint on the hub would allow:

muse tag list --remote local           # query remote without modifying local state
muse tag list --remote staging --pre   # list pre-release tags on staging

Requires a new hub API endpoint: GET /{owner}/{slug}/version-tags.

5. Relative version resolution (v0.2.0-rc14~3)

Git-style tilde notation for navigating relative to a version tag:

muse describe v0.2.0-rc14~3           # 3 commits before v0.2.0-rc14
muse checkout v0.2.0-rc14~1           # check out the commit just before the tag
muse log v0.2.0..v0.2.0-rc14          # commits between two version tags

6. Non-SemVer version strings

muse tag currently requires strict SemVer (vMAJOR.MINOR.PATCH[-pre][+build]). Some workflows use freeform version names (nightly-20260628, 2026.06.28, train-42). Decide whether to support these under a separate storage path or keep the strict boundary and direct users to muse label for freeform annotations.

Acceptance criteria

Each item above should be tracked as its own issue when ready to implement. This issue serves as the holding area and cross-reference from #56.