From 12a6fa66fad8928a17e8eee12fc364c5ad6770a8 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 4 Nov 2026 02:26:33 +0000 Subject: [PATCH] Plan ReleaseKit v0.9.0 adoption --- docs/roadmap/releasekit-v0.9.0.md | 187 ++++++++++++++++++++++++++++++ 1 file changed, 187 insertions(+) create mode 100644 docs/roadmap/releasekit-v0.9.0.md diff --git a/docs/roadmap/releasekit-v0.9.0.md b/docs/roadmap/releasekit-v0.9.0.md new file mode 100644 index 0000000..96740f7 --- /dev/null +++ b/docs/roadmap/releasekit-v0.9.0.md @@ -0,0 +1,187 @@ +# 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.