commandkit/docs/roadmap/releasekit.md

ReleaseKit v0.3.0 upgrade roadmap

Status: implemented; ReleaseKit v0.3.0, Go 1.26.0 minimum, and Go 1.26.8 release toolchain are in place.

Date: 2026-10-08.

Purpose and authority

Upgrade CommandKit's maintainer publication tool from ReleaseKit v0.2.0 to v0.3.0 and simultaneously raise CommandKit's declared Go consumer minimum to 1.26.0. The user has accepted both changes. Retain the existing root-module Go tool dependency and source-only publication workflow.

This document records the target state, completed upgrade work, and evidence from the reviewed baseline. The release policy, architecture policy, agent policy, testing policy, and documentation policy govern the work. Apply the OSS policy to any changed attribution or incorporated material. The maintainer procedure owns current release operations.

This is a new upgrade roadmap. The completed initial ReleaseKit adoption is available in Git history; its retired assignments are not part of this work. Implementation completion is distinct from publishing a CommandKit release.

Reviewed baseline

CommandKit was reviewed at 7eebe877cf9a21fb4f886f89bbc2089661237fc1 with a clean worktree. ReleaseKit v0.3.0 identifies commit e43df4416e0ed987349b2ea04a2c68c25e552772; the local checkout and published tag matched that revision during review. Its release notes record the compatibility and upgrade guidance.

Area	Reviewed baseline	Target
Module	go 1.25.5; ReleaseKit v0.2.0 selected through a tool directive and module requirement.	go 1.26.0; the same CLI tool dependency selects ReleaseKit v0.3.0.
Release toolchain	Go 1.25.5 selected in the runbook. The review environment has Go 1.26.8.	Go 1.26.8, documented separately from the Go 1.26.0 consumer minimum.
Launcher	scripts/release builds the module-selected native CLI in readonly mode and delegates publication with argument, status, and stream preservation.	The same bootstrap and delegation use v0.3.0 under the selected compatible toolchain.
Profile	releasekit.json specifies product, remote, and expected push endpoint; validation uses the default suite.	The same minimal source-only profile.
Evidence	Deterministic launcher tests and an opt-in publication exercise against disposable local Git repositories exist.	Those boundaries work with the upgraded module selection and toolchain.
Documentation	Policy, runbook, and consumer guide describe v0.2.0 and/or the Go 1.25.5 selection.	Canonical owners describe the implemented upgrade and its consumer impact.

The upstream CLI, profile schema, and public signatures are unchanged. ReleaseKit itself raises its minimum from Go 1.25.0 to 1.26.0; its dependency versions are unchanged from v0.2.0. The original planning review did not run a test suite or publication exercise; completed upgrade validation is recorded below.

Target end state

Module selection and Go compatibility

The root go.mod declares Go 1.26.0 and selects ReleaseKit v0.3.0 for gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit. The corresponding go.sum records the resolved checksums. The existing tool declaration retains the executable through ordinary module tidy.

The tool shares CommandKit's module graph, so the new minimum applies to library consumers as well as maintainers even though production packages do not import ReleaseKit. This is an intentional compatibility change. Go 1.25 consumers need to upgrade before adopting the CommandKit revision containing it.

The consumer minimum remains the initial stable release of the Go 1.26 series. A newer release-validation patch does not raise that floor by itself. The release policy's toolchain rules define the support presumption and compatibility treatment. No additional minimum-version test matrix or promise of identical results across toolchains is introduced.

Ownership and publication behavior

ReleaseKit remains maintainer tooling. The root commandkit facade and internal Cobra adapter keep their existing responsibilities; this upgrade adds no runtime ReleaseKit import, public wrapper, or operator-facing command family.

The existing launcher remains the publication entry point. It builds the native CLI from the committed module selection with readonly metadata and automatic workspace/toolchain switching disabled. The maintainer's selected go on PATH is used for bootstrap and candidate validation. A toolchain directive is not needed to make this launcher select that executable; setup belongs in the runbook.

CommandKit continues to publish an annotated source tag after its candidate is available on the authoritative branch. ReleaseKit owns validation, publication guards, tag creation, and publication outcome reporting. CommandKit owns the candidate, version, note, profile, and runbook. Successful publication remains separate from optional delivery investigations under the existing release policy.

Benefits within the selected scope

ReleaseKit v0.3.0 reduces output-copying and retention during Go command execution, preserving full failure diagnostics and underlying causes. That improvement benefits CommandKit's default candidate suite.

The upstream Git reader, file-check caches, cancellation cleanup, asset hashing, and runtime-version improvements remain upstream responsibilities. Our current profile does not enable optional committed-file checks or hosted artifact delivery. Their improvements are available if those capabilities are deliberately selected later; this upgrade does not enable them. No CommandKit latency or allocation target is part of adoption.

Completed upgrade work

Module and toolchain alignment

• Select Go 1.26.8 under OD-1 and document its installation and PATH setup in the runbook. Use that toolchain for upgrade validation and subsequent release tasks governed by the procedure.
• Upgrade the existing CLI tool dependency to v0.3.0 and set the Go directive to exactly 1.26.0 using ordinary Go module tooling. Review the resulting module and checksum changes, including any automatically generated toolchain metadata. Keep the consumer floor separate from the maintainer patch selection.
• Prepare dependencies before offline validation. The local sibling checkout is review evidence, not a replacement module or build prerequisite. Diagnose any checksum failure using upstream guidance and retain checksum verification.
• Review incidental module changes. ConfigKit, PromptKit, and backend upgrades are separate work; v0.3.0 does not require new versions of its own dependencies.

Launcher and profile verification

• Confirm the existing launcher builds the upgraded native executable from the module-selected package and preserves publication arguments, streams, and statuses. Confirm that the executable identifies ReleaseKit v0.3.0.
• Retain the current profile and launcher design. Change implementation only if a demonstrated compatibility issue requires it; no migration is indicated by the reviewed upstream CLI or schema.
• Reuse existing launcher tests. Adjust fixtures only where the selected version or Go requirement actually affects their behavior. An older version string used to test rejection of an independent package pin need not be replaced just because the adopted version changes.

Canonical documentation and provenance

• Update docs/policy/release.md to identify the selected ReleaseKit version while retaining its v1.6 upstream provenance and local source-only rules. This tooling upgrade is not another policy-template adoption.
• Update docs/release.md with the selected Go 1.26 patch, executable setup commands, and v0.3.0 source-pinned upstream references. Keep versioning rules in the policy and operations in the runbook.
• Update the consumer guide to explain the Go 1.26.0 minimum and shared tool-module reason. The current attribution of the floor to PromptKit's Go 1.25.5 requirement becomes obsolete.
• Check contributor navigation and current references affected by the upgrade. Historical planning records and immutable release notes retain their original facts; avoid replacing every historical version string.
• Apply the OSS policy to the actual material scope. Tool use alone does not require a new attribution entry. Update entries or license links if incorporated material or dependency selection changes require it.

Validation and completion evidence

Use the existing validation boundaries rather than adding recurring release gates:

• Run the deterministic offline default suite under the selected toolchain, covering the public library and native launcher behavior.
• Exercise the existing opt-in local publication test with the upgraded module selection after cache preparation. It covers a real native bootstrap, exact candidate tag publication to a disposable bare repository, one candidate suite, clean fixture state, and endpoint-mismatch preflight. Keep it opt-in in normal development and publication; this is upgrade evidence, not a new release gate.
• Inspect production package dependencies to confirm ReleaseKit remains outside the root library and internal adapter import closures. Review module selection and CLI version evidence separately from that runtime boundary.
• Review canonical-document changes, local links/fragments, provenance, and whitespace. Record the actual toolchain, resolved module revision, checks run, outcomes, and any qualifications when marking this roadmap implemented.

The developer guide owns the existing local exercise commands. Reuse successful evidence for unchanged content; adding a benchmark requirement, platform matrix, or upstream suite rerun is not necessary to establish this upgrade's selected behavior.

Completion criteria

The upgrade is implemented when the root module selects v0.3.0 with Go 1.26.0, the documented release toolchain can bootstrap and validate it, existing launcher/publication behavior has the stated evidence, and current documentation accurately describes the minimum and ownership boundaries. Release notes carry the compatibility explanation when a release containing the change is prepared.

This work does not publish CommandKit, add hosted delivery, split tooling into a second module, or change standard CLI/API semantics. Actual publication and its fresh version-matched note remain a separate release-preparation task.

Completion evidence

Implemented from efc5065 using Go 1.26.8 on Linux/amd64. The module now contains go 1.26.0, the retained CLI tool declaration, and the ReleaseKit v0.3.0 requirement/checksums. Module tidy retained that selection. No other dependency versions changed and no toolchain directive was added. The downloaded module's origin identifies the reviewed e43df4416e0ed987349b2ea04a2c68c25e552772 tag revision; dependency preparation required no checksum repair.

Validation completed:

• Default suite: go test -mod=readonly -count=1 ./... passed with GOWORK=off, GOTOOLCHAIN=local, GOPROXY=off, GONOPROXY=none, and GOSUMDB=off. This includes public library and deterministic launcher tests; existing test sources were sufficient and unchanged.
• The existing local publication exercise passed with COMMANDKIT_RELEASE_INTEGRATION=1 and the same offline settings: go test -mod=readonly -count=1 ./scripts -run '^TestReleaseIntegration$' -v. It published only within disposable repositories and proved the candidate, single suite execution, clean fixture, and endpoint-mismatch behaviors above.
• A native CLI was built in ignored .releasekit/bin/ storage with the launcher's host-target and readonly settings. Its version output was releasekit v0.3.0; go version -m identified Go 1.26.8 and the module-selected v0.3.0 build.
• go list -mod=readonly -deps for the root package and internal/cobra found no ReleaseKit, Goldmark, or golang.org/x/mod runtime imports. The launcher and profile were unchanged. ReleaseKit remains tool-only material; no attribution entry or copied source was added under the existing OSS policy.
• The runbook, release policy's local tool selection, consumer compatibility explanation, and contributor navigation now describe the upgrade. The release policy remains based on v1.6 at its existing upstream revision. Local documentation destinations/fragments, shell snippet syntax, and whitespace checks passed.

This verifies the upgrade without publishing CommandKit or establishing an additional recurring release check. No upstream benchmark or test suite was rerun; the evidence concerns CommandKit's selected integration.

Release preparation follow-up

The next CommandKit release note must explain the Go minimum increase and required consumer action. Its CommandKit version is selected during release preparation under policy, with the matching note and footer. That separate publication task was not performed or authorized by this upgrade; the current consumer guide already explains the compatibility change.

Selected decisions

OD-1: release-validation patch version

Resolved: Go 1.26.8, accepted by the user and implemented. It is the toolchain available in the review environment and used by ReleaseKit v0.3.0's maintainers. Using it avoids an additional installation in that environment and benefits from later patch updates within the selected Go series. Declare go 1.26.0 for consumers and document 1.26.8 as the runbook's release-toolchain selection. The adopted policy permits same-series support to be presumed from this validation; a second mandatory run on 1.26.0 is unnecessary absent a concrete concern.

Alternative considered: Go 1.26.0. It validates directly at the consumer floor and makes the minimum and release toolchain identical initially. It requires installing that patch in the reviewed environment and forgoes subsequent patch updates. It is viable if direct minimum-toolchain validation is preferred, but the current policy does not require that extra alignment.