commandkit/docs/roadmap/remediation.md

ReleaseKit adoption review findings

Status: R-01 and R-02 complete.

Date: 2026-10-08.

Review scope and authority

Reviewed CommandKit at c0c03285f7beac3e96f1708b655c1eb2add35e79, covering the six adoption commits from ada2021 through c0c0328 against the ReleaseKit target, implementation plan, and applicable policies. The previously completed documentation reconciliation record remains available in Git history.

The target adoption is present: a released Go tool selection, minimal source-only profile, native launcher, fast subprocess tests, opt-in local publication exercise, and implemented runbook/navigation. The commits do not change production Go source or public declarations. Package dependency inspection found no ReleaseKit, Goldmark, or golang.org/x/mod runtime dependency in the root library or internal Cobra adapter. scripts contains external test files only.

The remaining findings concern test maintainability and ambiguous normative wording. Neither establishes a missing production feature or a demonstrated publication failure. Fix them within the existing target; do not add release gates, new public contracts, or additional publisher machinery.

R-01: avoid making bootstrap command details test contracts

Priority: low. Category: code quality and unintended test constraints.

Location: scripts/release_test.go, TestReleaseLauncherDelegatesPublication, assertNativeBootstrap and fakeGo as they existed at the reviewed revision.

The assertion compares the entire build argument vector, including flag order and the absolute spelling of the output path. It also requires the two exact env GOHOSTOS and env GOHOSTARCH query forms. The executable double supplies only the first requested environment value, so a combined query would fail even if the launcher parsed both host values correctly.

The publication assertion similarly compares a complete argument vector, requiring --repo to precede --config even though the upstream CLI accepts either order before the version operand.

For example, reordering build flags, using a relative output path resolved from the already verified repository root, or combining host queries can preserve the selected behavior while failing these tests. The target requires native bootstrap from the module-selected package, readonly metadata, the selected toolchain/workspace settings, and the intended executable destination. It does not make these equivalent command spellings permanent contracts.

The testing policy and agent policy call for protecting those selected behaviors without elevating implementation details.

Required work:

• Assert the required build settings, selected package, and resolved output destination without requiring one incidental flag ordering or path spelling.
• Make host-query fixture handling and assertions reflect the requested host values rather than requiring separate subprocess query forms. Keep the fixture small; a complete Go command emulator is unnecessary.
• Check the publication command, option values, version operand, and argument boundaries without fixing the order of independent options. Retain the upstream requirement that options precede the version.
• Preserve checks for wrong native target, missing readonly mode, incorrect package/output, workspace or toolchain mistakes, failed bootstrap, and publication status/stream propagation.

Completion evidence: focused launcher checks still detect the selected failures and accept an equivalent bootstrap form. This is a test correction, not a requirement to refactor the working launcher or add a release-time check.

Completed 2026-10-08: bootstrap checks now inspect required options and resolve output paths; publication checks use the standard flag parser to preserve option-order freedom and operand boundaries. The small executable double returns each requested host value and accepts either output-option spelling. A fixture launcher with combined host queries, reordered options, and a relative output passed. Negative cases still reject incorrect target, workspace/toolchain, directory, readonly mode, package pin, output, publication paths, and operands; existing status/stream and bootstrap-failure checks passed.

Validation: offline go test -mod=readonly -count=1 ./scripts and go test -mod=readonly -count=1 ./... both passed with GOWORK=off, GOTOOLCHAIN=local, GOPROXY=off, GONOPROXY=none, and GOSUMDB=off. The production launcher, profile, and module selection were not changed.

R-02: clarify optional diagnostic validation in the runbook

Priority: low. Category: potentially strengthened prohibition.

Location: docs/release.md, lines 76–77 at the reviewed revision.

The instruction “Do not require a separate check before publish or repeat the same suite” combines the intended rule against mandatory duplicate validation with wording that can be read as prohibiting an operator from voluntarily rerunning diagnostics.

The release policy permits a validation-only diagnostic command and says it must not be a required prerequisite before publication repeats the checks. Avoiding automatic duplicate validation does not establish a blanket prohibition on optional diagnostic runs. The launcher correctly delegates once; this finding concerns the runbook's description, not its executable behavior.

Required work:

• Say explicitly that check is optional for diagnosis and is not a required step before publish.
• Scope the duplicate-validation instruction to the automated publication workflow and configured additional checks. Preserve operator discretion to investigate or rerun a check.
• Retain the single publication command and its own final-candidate suite; do not add a required preliminary check or an extra confirmation.

Completion evidence: document review confirms the runbook distinguishes an optional diagnostic action from a release requirement and agrees with the existing policy. No implementation change is needed for this item.

Completed 2026-10-08: the runbook explicitly makes check an optional diagnostic action and preserves maintainer discretion to rerun diagnostics. Duplicate-validation guidance now concerns the automated publication workflow and configured additional checks. The single publisher and its own final-candidate suite remain the release procedure.

Validation: reviewed the changed wording against the release policy and implemented launcher; local documentation links and fragments and Markdown whitespace checks passed. This documentation-only unit did not change code or rerun the suite already passed for R-01.

Review evidence and limits

• Read the adoption diffs, launcher/profile, new test functions and fixtures, runbook, policy edits, historical navigation changes, and completion records.
• Inspected package dependencies with offline module access and confirmed the production boundary and tests-only scripts package. Verified the committed launcher mode and ignored local executable storage.
• Reviewed what the tests actually assert, including the local fixture's exact tag-object comparison, candidate commit, one suite marker, clean worktree, and endpoint-mismatch preflight behavior. The completion record reports earlier successful default and opt-in runs; this review did not rerun those tests or attempt publication.
• No other adoption gap, newly imposed release gate, public API expansion, or runtime publication-code defect was identified in the reviewed changes.

Leave source publication, hosted delivery, binary assets, and other explicitly deferred capabilities outside this remediation work. Update item status only after the relevant correction and evidence are complete.