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

# ReleaseKit v0.9.0 adoption

Status: R1 and R2 remediation, ReleaseKit v0.9.0 adoption, and the completion
assertion repair are complete. The [completed implementation record](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/c8d659dfe5ae3e834b3aeabdfd0fe29b736dc05a/docs/roadmap/implementation.md)
records stage order, tasks, and validation evidence. This document owns the
target and selected choices; it 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](../policy/agents.md),
[release policy](../policy/release.md#candidate-validation),
[testing policy](../policy/testing.md#upstream-integration-testing-ownership),
and [documentation policy](../policy/documentation.md) govern the work. Current
behavior remains owned by the [release procedure](../release.md), Go declarations,
and owning package tests until implementation updates them.

## Current baseline and review evidence

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

- The root [module](../../go.mod) selects
  `go.maximumdirect.net/releasekit v0.8.0` as a Go tool. Its selected version
  serves core, ckconfig, and ckprompt operations.
- The [shared helper](../../scripts/releasekit) 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](../../scripts/release) 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](remediation.md) 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 [release-tooling implementation record](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/87eb84ccb462bf54e6250c8b287ac217efe90883/docs/roadmap/implementation.md#stage-5-verify-the-final-source-and-record-validation-boundaries)
  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](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.9.0/docs/releases/v0.9.0.md)
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`](../../completion_context_test.go). 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](../../scripts/release_test.go) 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](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 assertion compares the expected alias source/target records
without depending on their iteration order, while detecting missing, unexpected,
or duplicate records. Its routing and visible-completion assertions remain.
Production alias ordering and public contracts are unchanged. This correction
was completed as part of the maintenance scope, separate from R1/R2 remediation;
the implementation plan records the test changes and focused verification.

Ordinary releases retain their single selected-module publication suite and
separate hosted-delivery outcome. One-time upgrade diagnostics are maintenance
evidence, with no new recurring release gate. Credentials and live publication
are unnecessary for this adoption.

## 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.

## Resolved choices

R1 and R2 were corrected in separate commits before adoption, resolving the
former OD-1 scheduling question. Their acceptance evidence remains in
[remediation.md](remediation.md).

The selected maintenance scope is the completion assertion repair, root tool
upgrade, aligned current documentation and attribution, and validation of the
resulting source. The older integration dependency-version mismatch remains
separate release-preparation work. The implementation plan defines execution
and commit sequencing.