feat(release): add a source release verification checklist #25

Summary

The source repository lacks a release verification procedure tying the advertised CLI version, proposed tag, and optimized build together. The version is duplicated in source and a CLI test; the current CI workflow checks debug/test paths, while the tap builds the release configuration.

Code evidence at 5d4987b:

• Sources/Core/BuildInfo.swift:2 hard-codes 0.2.1; Sources/CLI/EntryPoint.swift:38 exposes it as the CLI version.
• Tests/CoreTests/CLISurfaceTests.swift:234 duplicates that version literal.
• CONTRIBUTING.md:7 documents the development loop, without a tag/version or optimized-build release check.
• .github/workflows/ci.yml:3 triggers only for PRs and master pushes; :30 runs swift test, and :38 starts default-configuration CLI smoke checks.
• The tap formula at 16aaf2d builds with -c release.

Use Case

A maintainer preparing a source release needs a repeatable preflight that detects stale version metadata or a release-only build failure before publishing a tag or handing the release to the tap.

Reproduction / current-state verification

Executed at 5d4987b. The current version and repository/formula inventory were executed. An optimized release build and mismatched-tag preflight were not executed: there is no preflight implementation at this revision, and this report does not assert a release-build failure.

Run in Bash after cd "<checkout>" && swift build, replacing <checkout> with the absolute path of the checkout at this revision. Use a fresh reproduction directory. The commands isolate HOME, agent configuration, and XDG_*, and remove their fixture root on exit.

set -eu
checkout="<checkout>"
skill_bin="$checkout/.build/debug/skill"
repro_root="$checkout/.build/issue-repro-release-process"
mkdir -p "$repro_root/home" "$repro_root/tmp" "$repro_root/project"
trap 'rm -rf "$repro_root"' EXIT
isolated() {
  env -i PATH="$PATH" HOME="$repro_root/home" \
    CODEX_HOME="$repro_root/home/.codex" \
    CLAUDE_CONFIG_DIR="$repro_root/home/.claude" \
    XDG_CONFIG_HOME="$repro_root/home/.config" \
    XDG_STATE_HOME="$repro_root/home/.local/state" \
    XDG_CACHE_HOME="$repro_root/home/.cache" TMPDIR="$repro_root/tmp" \
    GIT_CONFIG_NOSYSTEM=1 GIT_CONFIG_GLOBAL=/dev/null \
    GIT_AUTHOR_NAME=Fixture [email protected] \
    GIT_COMMITTER_NAME=Fixture [email protected] \
    "$@"
}
skill() { isolated "$skill_bin" "$@"; }
cd "$repro_root/project"


cd "$checkout"
skill --version
isolated rg -n '0\.2\.1|version:' Sources/Core/BuildInfo.swift Sources/CLI/EntryPoint.swift Tests/CoreTests/CLISurfaceTests.swift
isolated cat .github/workflows/ci.yml
isolated git ls-files '*release*' '*Release*' '*RELEASE*'
isolated curl -fsSL https://raw.githubusercontent.com/skill-cli/homebrew-tap/16aaf2d3e978a76a16599af003e7e2fde1e38299/Formula/skill-cli.rb | \
  isolated grep -n 'swift.*build'

Observed findings (summarized from the command output):

CLI --version: 0.2.1
Sources/Core/BuildInfo.swift:2:  public static let version = "0.2.1"
Sources/CLI/EntryPoint.swift:38:    version: BuildInfo.version,
Tests/CoreTests/CLISurfaceTests.swift:234:      try runSkills(["--version"]).stdout.trimmingCharacters(in: .whitespacesAndNewlines) == "0.2.1"
CI inventory: swift test plus default-configuration swift run smoke checks; no release build or tag/version check.
Tracked release-named files: none.
Tap formula: swift build -c release --disable-sandbox --product skill

Environment: Apple Swift 6.4, macOS 27.0.1 (26A434), arm64; CLI 0.2.1; validation date 2026-10-17.

Proposed Behavior

Add a source-owned release checklist or preflight entry point covering:

• An explicit proposed tag/version and agreement with the built CLI's --version (including the chosen v-prefix convention).
• Updating/checking the current version source and CLI version test without silent drift.
• swift test, swift build -c release --product skill, and release-binary version/help smoke checks.
• The handoff link to tap-owned packaging/release instructions.

Decisions: the procedure is a checklist document at Documentation/Reference/Release.md, linked from CONTRIBUTING.md; tap packaging steps stay in the tap repository's README. BuildInfo.version is the single version source, and the CLI version test compares against it instead of repeating the literal. Still open for the maintainer: whether optimized-build validation runs on every PR or only at release time.

Completion checks: the checklist exists and is linked; the version test reads BuildInfo.version; following the checklist on a matching candidate passes, and its version check catches a deliberately mismatched proposed tag without creating or moving a tag.

Tradeoffs

A release build on every PR costs more CI time; a release-only gate needs a reliably invoked procedure. Deriving a value from a tag must still work for source archives and ordinary development builds. No release failure or current tag/version mismatch was observed or claimed.

Compatibility Notes

Keep formula publishing and tap release instructions in the tap repository, as Documentation/Architecture/Package.md:80 requires. This proposal authorizes no tagging or publication.

Related: PR #11 and PR #12 report debug build/test validation. This proposal adds a source-release gate rather than duplicating their resolver/lock fixes. No duplicate found.