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

# ReleaseKit v0.9.0 adoption

Status: proposed maintenance roadmap; no implementation has started. Upgrade
scope is defined below. The scheduling of existing local corrections remains
open under OD-1. 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](../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

CommandKit baseline: `98e7e9933353cf43f2be4a96cb0436a0bce068d2`.

- 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) remain open: legacy selector/raw-command collisions
  and loss of optional POSIX-shell handling in launcher tests.
- Both integrations still require older published CommandKit dependencies than
  their current source needs. The completed [implementation record](implementation.md)
  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.

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.

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

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.

### Local correctness work

R1 and R2 keep their scope and acceptance evidence in [remediation.md](remediation.md).
The dependency upgrade does not close either finding. Subject to OD-1, address
them in the same maintenance effort while retaining the simplified test boundary
and the legitimate raw helper commands.

Also correct the completion test's incidental ordering assumption. 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

- [ ] Record the chosen maintenance scope for OD-1. Keep the upgrade and each local
  correction reviewable, whether delivered together or separately.
- [ ] 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.
- [ ] For bundled correctness work, implement R1 and R2 and the completion
  assertion repair, with focused verification of the defects. Close existing
  remediation findings only when their stated behavior has been verified.
- [ ] 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.

If local corrections are bundled, completion also includes R1/R2 acceptance
evidence and a stable, order-independent completion assertion. If delivered
separately, report those items as outstanding rather than implying that adoption
resolved them. Independent integration dependency alignment remains separate
release-preparation work; this roadmap selects no future versions or sums.

## Open Decisions

### OD-1: Bundle the existing local corrections with the upgrade?

**Recommendation:** Deliver v0.9.0 adoption, R1, R2, and the completion assertion
repair as one focused maintenance effort, using separate reviewable commits as
appropriate. The existing issues are small, directly affect maintainer tooling
or the default suite, and otherwise leave misleading validation after a passing
upgrade run. Fixing the assertion without changing runtime ordering restores
useful evidence while keeping the requested contracts intact.

This is a scheduling recommendation, not a requirement that every dependency
upgrade include unrelated repository repairs. It does not fold the older
integration dependency-version mismatch into this scope.

**Viable alternative:** Land the tool and current-documentation updates first,
then deliver the three local corrections as separately tracked units. This
keeps the dependency change especially easy to review or revert and makes the
new recovery behavior available sooner. It leaves the known routing and test
issues active, so a passing upgrade run cannot be reported as resolution of
those issues or as proof of a consistently passing baseline. Keep their
follow-up explicit and apply existing candidate-validation requirements before
any actual source publication.