commandkit/docs/roadmap/releasekit-v0.9.0.md

ReleaseKit v0.9.0 adoption

Status: R1 and R2 remediation is complete in separate commits. ReleaseKit v0.9.0 adoption and the completion assertion repair remain planned; the root tool still selects v0.8.0. This document does not authorize source or hosted publication.

Purpose and authority

Adopt ReleaseKit v0.9.0's improved recovery behavior while preserving CommandKit's existing release-tooling architecture. Update current dependency and maintainer documentation together, and make the validation evidence clear about existing local defects.

The agent policy, release policy, testing policy, and documentation policy govern the work. Current behavior remains owned by the release procedure, Go declarations, and owning package tests until implementation updates them.

Current baseline and review evidence

Current CommandKit baseline: 4d92ee4ee6a8403b22a4172e0f04face802b9499. The original upgrade review used 98e7e9933353cf43f2be4a96cb0436a0bce068d2; its findings and validation history are retained below.

• The root module selects go.maximumdirect.net/releasekit v0.8.0 as a Go tool. Its selected version serves core, ckconfig, and ckprompt operations.
• The shared helper already normalizes the Go host, disables workspace discovery, selects the local toolchain, retains read-only metadata, and invokes the full executable package path. The legacy entry point delegates publication to it.
• All three profiles already select the agreed generic file checks, forbidden token path, and page-only Gitea destination. Source publication and hosted delivery are separate operations. The local token directory remains ignored.
• R1 and R2 are complete. Commit 7eac3fe rejects invalid legacy selectors before invoking Go; commit 4d92ee4 restores explicit, optional POSIX-shell invocation in launcher tests. The remediation record owns their acceptance evidence, including passing focused tests, shell syntax checks, and profile assertions running when no shell is available.
• Both integrations still require older published CommandKit dependencies than their current source needs. The completed implementation record distinguishes workspace-backed tests from independent release readiness.

The upstream v0.9.0 tag identifies commit 2180aa868ec2caa95fc8279fd59d5f0ebac41bd4. The tag and direct Go-module resolution were verified. The default proxy initially returned v0.8.0 for @latest; select v0.9.0 explicitly rather than changing repository-wide proxy settings to work around that observation.

Upstream release notes describe host-safe launchers and generated recovery commands, full package-path tool selection, preservation of wildcard and version-specific replacements in API-only recovery, and safer manual hosted-page retries. Public Go APIs, profiles, record formats, and the Go 1.26.0 consumer minimum remain unchanged. The v0.8.0-to-v0.9.0 comparison also left upstream module requirements, checksums, copyright, and license texts unchanged.

A disposable CommandKit upgrade changed only the selected ReleaseKit version in go.mod. With Go 1.26.8, the root suite passed on a subsequent run, both workspace-backed integration suites passed, and the real helper reported v0.9.0 under foreign target settings. No production publication or delivery was run.

A later disposable review at 7eac3fe confirmed that downloading and tidying v0.9.0 changed only the ReleaseKit requirement and its checksum entries. The offline root suite and both workspace-backed integration suites passed with Go 1.26.8, and the helper reported v0.9.0 under Windows/ARM64 target settings. That snapshot excluded the then-uncommitted R2 change; it does not replace validation of the eventual adoption commit.

The initial upgrade run failed in TestCompletionCommandContext. The same alias-order failure reproduced four times in 30 focused repetitions on the unchanged v0.8.0 baseline. A single passing rerun therefore does not establish stable validation. The test compares an internal alias slice in a fixed order; commit 0acbbf4 deliberately changed completion to use unsorted lookup records before this upgrade review.

Targeted end state

Tool adoption and retained architecture

The root module selects ReleaseKit v0.9.0 with authentic downloaded checksums. Its existing tool declaration and root-owned selection remain. No integration dependency version, library import path, Go minimum, or selected Go 1.26.8 maintainer toolchain changes as part of adoption.

Keep host normalization and full-package invocation in the existing helper: upgrading a dependency does not update or replace local shell scripts. Keep one module/profile mapping and the established wrapper forms. Retain the selected profiles, token-file handling, credential-directory ignore rule, and separation of source and hosted outcomes. No new validator, binary target, CI workflow, publication channel, credential preflight gate, or runtime API is needed.

The new generated Go recovery commands complement the helper's existing host handling. Recovery continues to use saved publication evidence and the upstream record formats; CommandKit does not acquire a parallel recovery implementation.

Release-code simplification review

The v0.9.0 review identified no additional local release implementation to remove. The earlier simplification already delegated generic validation, publication, delivery, and recovery to ReleaseKit. This release improves launcher examples and generated recovery commands without adding validation options that replace the remaining CommandKit code.

Retain the shared helper's module/profile selection and execution environment. Host normalization must happen before Go compiles and runs ReleaseKit. Retain the legacy publication wrapper to preserve the established maintainer interface. The upstream multi-module launcher example adds a module map and temporary metadata preparation for a different tool-selection model; replacing our root-owned registered-tool helper with it would add machinery.

Retain the focused wiring tests for profile selections, argument forwarding, environment, streams, status, and optional-shell handling. ReleaseKit owns validation and recovery semantics; CommandKit's tests continue to cover its own adapter. The adoption work therefore preserves the release-code structure while updating the dependency and documentation, alongside the separately planned completion assertion repair.

Current documentation and history

Current release procedure, project-specific release policy, consumer Go-tool selection summary, and root attribution describe v0.9.0. Upstream contract and notice links use the corresponding immutable source revision. Record that the host-safe launcher request has shipped upstream instead of describing it as pending in the earlier feature roadmap.

Continue linking to upstream recovery and delivery contracts from the maintainer procedure. Use ReleaseKit's generated recovery commands and keep local guidance focused on CommandKit's entry points and selections.

Preserve the baseline and validation history in completed implementation and review records. Do not mechanically replace every historical v0.8.0 reference. Integration attribution describes its own selected published dependency graph; update it only if that actual selection changes. No license-text replacement is needed for the unchanged upstream texts.

Completed remediation and remaining correctness work

R1 and R2 were delivered before the dependency upgrade, with their completion markers and acceptance evidence in remediation.md. Preserve their selector rejection, legitimate raw helper forms, and optional-shell test boundary during adoption; no further implementation of those findings remains.

The completion test's incidental ordering assumption remains unresolved and is separate from the completed remediation findings. Correct it in its own reviewable commit within the remaining maintenance work. Compare the expected alias source/target records without depending on their iteration order, while still detecting missing, unexpected, or duplicate records. Sorting test-owned copies is one straightforward approach. Preserve the other routing and visible-completion assertions. Do not restore production sorting or promise a new internal alias order merely to make this assertion pass.

Work needed

• Complete R1 in its own commit (7eac3fe), recording verification in remediation.md.
• Complete R2 in its own commit (4d92ee4), recording verification in remediation.md. R1/R2 scheduling is resolved by their delivery before adoption.
• Review remaining release code against v0.9.0. Retain the helper, legacy wrapper, profiles, and focused wiring tests for the reasons above.
• Repair the completion assertion's ordering assumption and verify the correction with focused repetitions. Preserve production ordering behavior and the remaining routing assertions.
• Select the root tool at v0.9.0, tidy module metadata, and inspect the actual go.mod/go.sum diff. Investigate unexpected version changes rather than accepting unrelated upgrades. Use normal cache preparation; direct retrieval can diagnose proxy lag without becoming permanent configuration.
• Update current owners: docs/release.md, the local selection in docs/policy/release.md, docs/consumers/guide.md, and the root ReleaseKit entry in docs/oss/attribution.md. Check affected source links and fragments at the v0.9.0 commit. Update the earlier feature roadmap's pending-request statement while retaining its historical evidence.
• Validate the actual upgraded helper with inherited foreign target values, and run the owning offline suites with Go 1.26.8. During development, use focused repetitions to check the completion repair; do not treat rerunning until green as a substitute for fixing it.
• Exercise selected ReleaseKit checks on the final committed candidate inputs using disposable source snapshots where appropriate. Reuse the completed implementation record's one-time procedure for workspace-backed integration diagnostics; do not add it to ordinary publication or claim it proves independent published-dependency alignment.
• Review whitespace, affected documentation links, and the final diff; record what passed, what remains open, and the reviewed source revision. Commit completed units under the local commit policy.

No live token, model call, hosted write, or authoritative tag push is needed to verify this maintenance work. Do not read the credential file as part of the upgrade. Ordinary releases still use their single selected-module publication suite, with hosted delivery reported separately. Focused repetitions and disposable-copy diagnostics here are maintenance evidence, not permanent extra release gates.

Completion evidence

Adoption is demonstrated by authentic module metadata, the real helper reporting v0.9.0 for the host, aligned current documentation and attribution, and recorded validation of the final source. The reviewed upgrade introduced no other module version change; verify rather than assume that result during implementation.

R1/R2 acceptance evidence is complete in the remediation record. Completion of the remaining maintenance work also includes a stable, order-independent completion assertion and validation that the adopted helper retains the corrected launcher behavior. Independent integration dependency alignment remains separate release-preparation work; this roadmap selects no future versions or sums.

Sequencing after remediation

The former OD-1 question about bundling R1/R2 with adoption is resolved: both findings were corrected and committed separately before the upgrade. They are neither open decisions nor remaining adoption tasks.

For the remaining work, repair the completion assertion, then adopt v0.9.0 and align current documentation and attribution, keeping the test repair and tool adoption reviewable as separate commits. Validate the resulting source and record the actual evidence before marking adoption complete. A passing rerun alone does not resolve the known nondeterministic assertion. The older integration dependency-version mismatch remains outside this maintenance scope.