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 at the reviewed revision](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/c0c03285f7beac3e96f1708b655c1eb2add35e79/docs/roadmap/releasekit.md), the completed
[implementation record at the reviewed revision](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/c0c03285f7beac3e96f1708b655c1eb2add35e79/docs/roadmap/implementation.md),
and applicable policies. The previously completed documentation reconciliation
record remains available in
[Git history](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/c0c03285f7beac3e96f1708b655c1eb2add35e79/docs/roadmap/remediation.md).

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](../../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](../policy/testing.md#test-behavior-not-implementation) and
[agent policy](../policy/agents.md#implementation-discipline) call for protecting
those selected behaviors without elevating implementation details.

Required work:

- [x] Assert the required build settings, selected package, and resolved output
  destination without requiring one incidental flag ordering or path spelling.
- [x] 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.
- [x] 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.
- [x] 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](../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](../policy/release.md#candidate-validation) 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:

- [x] Say explicitly that `check` is optional for diagnosis and is not a
  required step before `publish`.
- [x] Scope the duplicate-validation instruction to the automated publication
  workflow and configured additional checks. Preserve operator discretion to
  investigate or rerun a check.
- [x] 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.