ConfigKit/docs/roadmap/implementation.md

# Implement ReleaseKit adoption

Status: Planned. Implement the stages below in order. The target state and
policy choices are in the [ReleaseKit adoption roadmap](releasekit.md); this
plan is the execution checklist. Use ReleaseKit v0.2.0 at tagged commit
`e030794969fb7787e647a90bbc4eb81bd0610f07` for the initial migration.
Do not publish a real ConfigKit version as part of implementation. Keep the
current release procedure authoritative until the replacement is working.
Follow the task-specific reading guide in [development.md](../development.md)
and avoid adding gates, compatibility promises, or restrictions beyond the
roadmap and adopted policies. Stages 3–5 are one documentation-and-machinery
cutover; their intermediate state is not a release candidate.

## Stage 1: Select Go and declare the release tool

1. Identify the newest Go executable available in the development environment
   when implementing this stage. Make it the `go` on `PATH`, verify it with
   `GOTOOLCHAIN=local go version`, and advance ConfigKit's `go.mod` `go`
   directive to its full version. Do not substitute a newer downloaded
   toolchain during later validation. Record the resulting minimum-Go increase
   for the next release's compatibility review; before v1.0.0, an intentional
   increase requires a minor release, not a patch release.
2. Using that same Go executable, add
   `gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit@v0.2.0` as a
   `go.mod` tool dependency (the Go `tool` directive and its module
   requirement). Update `go.sum`, run `go mod tidy`, and inspect the module
   diff. Preserve ConfigKit's runtime dependency boundary: production library
   packages must not import ReleaseKit. Do not introduce a second tool-version
   pin or an `@version` installation path in the release procedure.
3. Prepare the module cache and build the selected CLI package with that Go
   executable into a temporary path outside the worktree. Confirm that the
   resolved ReleaseKit module is v0.2.0 and that the built executable runs.
   Review actual dependency and license treatment under the
   [OSS policy](../policy/oss.md); a tool used only for development and release
   work does not by itself require an attribution entry.

Completion evidence: `go.mod` selects the chosen Go version and the pinned
ReleaseKit tool, `go.sum` is consistent, `go mod tidy` leaves no unintended
changes, the module-selected executable builds with the selected Go, and the
ordinary offline Go suite still passes after dependencies are prepared.

## Stage 2: Add ConfigKit's ReleaseKit profile

1. Add `releasekit.json` at the repository root with `product` set to
   `ConfigKit`, `remote` set to `origin`, and `expected_push_url` set to
   `https://gitea.maximumdirect.net/eric/ConfigKit.git`. Select
   `validation.go.race: true`, `validation.go.full_vet: true`, and
   `validation.go.compile_targets` in this order: `linux/amd64`, `linux/arm64`.
   Omit `build`, `delivery`, `checks`, and the other optional validation
   selections. This is a source-only release; macOS is best effort.
2. Add one small, offline ConfigKit-owned test of the committed profile's
   selected identity, endpoint, and checks. Keep it limited to configuration
   wiring and the agreed gate set; do not replicate ReleaseKit's publication,
   recovery, or Go-check implementation tests. Stage 6 will exercise the
   profile with the actual tool against an isolated remote.

Completion evidence: the profile is valid JSON, the focused test and ordinary
Go suite pass, and review shows only the selected gates and no binary or hosted
delivery configuration.

## Stage 3: Align release policy with the adopted workflow

1. Revise [the release policy](../policy/release.md) so candidate preparation
   explicitly publishes the committed candidate to authoritative `main`
   before the one ReleaseKit `publish` invocation validates it and publishes
   the annotated tag. Keep the checked-in note and tag as the only deliverables,
   successful intended-tag publication as completion, and CI, macOS, hosted
   delivery, and consumer retrieval outside release gates.
2. Replace references to the local release scripts and fixed Go 1.25 release
   baseline with the selected local Go executable, the current `go.mod`
   minimum, the module-selected ReleaseKit CLI, its one race suite with
   test-time vet disabled, full vet, and Linux amd64/arm64 package compilation.
   State that preparation advances `go.mod` to the newest Go available in the
   development environment and reviews any minimum-version increase under
   existing compatibility rules. Keep dependency acquisition and tool build
   before offline candidate validation; do not add a separate successful test
   or CI run as a publication prerequisite.
3. Align the guard descriptions with ReleaseKit v0.2.0: use its release-note
   H1 and exact effective push-URL checks, rather than claiming an automated
   exact-first-line or configured fetch-URL check. Retain the required
   `# ConfigKit <version>` first-line format for notes, the source/tag
   immutability rules, and the existing recovery principles. Do not require
   per-test skip listings; test failures still block publication.

Completion evidence: policy and roadmap agree on order, gates, compatibility,
and completion; no policy passage still describes the retired script or its
stronger automated guards as current behavior.

## Stage 4: Replace the maintainer release runbook

1. Revise [the runbook](../release.md) into copyable steps for the adopted
   process. During preparation, select the newest Go executable available in
   the development environment, keep it first on `PATH`, verify its version
   with `GOTOOLCHAIN=local`, and update `go.mod` to that full version if needed.
   Explain the minimum-Go compatibility impact and version choice, including
   the pre-v1.0.0 minor-release rule. Prepare dependencies, then build the
   module-selected `cmd/releasekit` with that executable into temporary storage
   outside the repository. Use the native executable for publication so its
   exit status and diagnostic state are preserved. Its child Go commands must
   find the same selected `go` on `PATH`; the old
   `CONFIGKIT_BASELINE_TOOLCHAIN` selector cannot choose them.
2. Keep ordinary candidate preparation: check access to the authoritative
   remote, choose an unused stable version, review compatibility and content,
   write `docs/releases/<version>.md` with the exact ConfigKit first line and
   license footer, retire completed roadmaps, and commit the entire candidate.
   Do not turn those reviews into additional approval gates. Push only that
   committed candidate to authoritative `main` using the literal authoritative
   URL and `HEAD:refs/heads/main` refspec, with implicit tag following
   disabled. ReleaseKit requires the remote `main` to equal the candidate
   before it validates. A failure before this push leaves publication
   unstarted; a failed validation after it leaves an untagged `main` candidate
   that must be corrected by a new commit and another validation.
3. Document one `releasekit publish vMAJOR.MINOR.PATCH` invocation using the
   built, module-selected executable. Describe its selected race suite, full
   vet, Linux package builds, release-note and effective-push-URL guards,
   exact tag publication, and confirmed-tag completion. Keep `check` optional
   for diagnosis, not a repeated required pass. Update the partial/unknown
   push recovery directions to ReleaseKit's reported candidate, endpoint,
   tag-object ID, and bounded authoritative-state reconciliation. Preserve
   optional post-publication consumer verification and no-CI-wait behavior.
   Remove old script commands, Go 1.25 pin examples, and promises of verbose
   skipped-test output.

Completion evidence: a maintainer can follow the runbook from a clean checkout
through confirmed tag publication without a ConfigKit release wrapper or a
second required Go/test run; all commands, version placeholders, and documented
failure states match ReleaseKit v0.2.0. Do not execute its real publication
command in this stage.

## Stage 5: Retire duplicated machinery and update developer guidance

1. Remove `scripts/release.sh`, `scripts/release-check.sh`, and
   `release_publish_test.go` after Stages 1–4 supply the replacement. Remove
   `TestCheckScriptsReleaseGates` and its now-unused helpers from
   `release_check_test.go`. Preserve
   `TestDevelopmentCheckHandlesFilenamesAndStopsOnFailure` and
   `scripts/check.sh`; rename the test file if helpful so its name reflects
   its remaining owner. Retain the small Stage 2 profile-wiring test. Do not
   transplant the old publication guard/recovery matrix into ConfigKit tests.
2. Update [the development guide](../development.md) to point to the new
   release runbook, remove retired-script references and the fixed release
   baseline, and adjust its task-to-test map. Keep the everyday development
   check and release validation distinct. Review other live references to the
   removed scripts and update only those made stale by this migration;
   historical release notes remain unchanged.

Completion evidence: no live release instruction invokes a removed script;
the default suite and `./scripts/check.sh` pass with the selected Go and
prepared dependencies; the retained tests protect development checks and
profile wiring without duplicating ReleaseKit's generic behavior.

## Stage 6: Exercise the migration without publishing ConfigKit

1. Build ReleaseKit from the candidate's `go.mod` selection with the same Go
   executable declared by that candidate. In disposable Git fixtures, use
   ConfigKit's selected profile with only `expected_push_url` changed to a
   temporary bare remote, and provide a matching committed fixture release
   note. Never push a ConfigKit tag or source commit to its real remote.
2. Push a committed fixture candidate to temporary `main` and run the built
   `publish` command with a deliberately failing fixture test. Confirm
   validation fails and creates no release tag, while `main` remains at that
   candidate. Correct and commit the fixture, push the new candidate to
   temporary `main`, and run `publish` again. Confirm one race-enabled standard
   suite, one full vet pass, and one CGO-disabled package compile for each
   selected Linux target in that successful invocation; confirm the remote
   annotated tag identifies the corrected candidate and contains the checked-in
   note. Record child Go invocations with a fixture-only forwarding executable
   on `PATH`, or use equivalent direct evidence, rather than inferring the
   selected command count merely from success.

Completion evidence: the isolated failure and success paths demonstrate the
selected profile, module-selected tool, command order, gates, and tag-only
publication. No ConfigKit ref is pushed to its real remote.

## Stage 7: Check endpoint failure and finish the cutover review

1. In a fresh disposable fixture/version without an existing tag, check that
   a wrong effective push URL is rejected before validation or tag
   publication. Do not reuse the version already published in Stage 6, which
   would make the existing-tag guard obscure the endpoint result.
2. Compare the runbook's recovery directions with ReleaseKit's reported state
   for a failed or uncertain tag push. Repair any mismatch in the runbook;
   do not duplicate ReleaseKit's recovery machinery in ConfigKit. This is a
   bounded migration exercise, not a new per-release gate or a requirement to
   wait for CI.
3. Re-run the affected repository checks after any corrections. Review the
   final policy, runbook, development guide, and roadmap together for a
   coherent process; confirm that only intended files changed and that no
   real ConfigKit release or push occurred.

Completion evidence: the wrong-endpoint fixture fails for the intended reason,
recovery guidance matches ReleaseKit v0.2.0, tests and documentation checks
pass, and the repository is ready for a separately authorized release.