Plan ReleaseKit adoption for source publication

docs/roadmap/releasekit.md

@@ -0,0 +1,238 @@
+# ReleaseKit adoption roadmap
+
+Status: adoption selected; implementation not started.
+
+Date: 2026-10-08.
+
+## Purpose and authority
+
+This roadmap defines the target state for adopting ReleaseKit as CommandKit's
+maintainer release tooling and the work needed to reach it. The next planning
+deliverable is a staged implementation plan based on this target. This document
+does not authorize publication or claim that release tooling already exists.
+
+The [release policy](../policy/release.md),
+[architecture policy](../policy/architecture.md), and
+[documentation policy](../policy/documentation.md) control the work. Apply the
+[OSS policy](../policy/oss.md) to dependencies and incorporated material, and the
+[testing policy](../policy/testing.md) to integration evidence. Existing accepted
+ADRs continue to govern the library and its standard CLI contracts.
+
+The reviewed upstream baseline is ReleaseKit v0.2.0, commit
+`e030794969fb7787e647a90bbc4eb81bd0610f07`. Its published tag and local checkout
+matched that revision during adoption review. Upstream references below identify
+that source; implementation must use the released module rather than require a
+sibling checkout.
+
+## Current baseline
+
+At roadmap preparation, CommandKit is at commit `3871d83` with a clean
+worktree. Its selected initial library target and documentation reconciliation
+are complete. The current package inventory is maintained in the
+[internal overview](../internal/overview.md).
+
+| Area | Current state | Adoption gap |
+| --- | --- | --- |
+| Module | Go 1.25.5; ConfigKit, PromptKit, and CLI dependencies are declared. | No ReleaseKit tool dependency or version selection. |
+| Publication | `origin` has effective push URL `https://gitea.maximumdirect.net/eric/CommandKit.git`; no local version tags were present. | No repository publication command or source-only release profile. Remote version availability must be checked when preparing a release. |
+| Procedure | Release policy is adopted. | `docs/release.md` does not exist; policy still says ReleaseKit integration has not been selected. |
+| Release history | No `docs/releases/` notes are present. | The first candidate will need its own version-matched note. |
+| Delivery | No hosted delivery integration is present. | None for the selected source-only adoption target. |
+| Licensing | Project grant and existing dependency attribution are maintained. | Review the actual tooling and copied-material scope when integration lands. |
+
+The adoption review inspected ReleaseKit's implementation and representative
+tests. It did not execute tests or exercise a CommandKit release integration.
+This historical baseline is not a claim about later implementation status.
+
+## Target state
+
+### Release ownership and deliverables
+
+CommandKit releases remain source-only Go module releases: one immutable version
+tag identifying an exact committed candidate with its matching checked-in release
+note. ReleaseKit owns candidate validation, automated publication guards,
+annotated tag creation, tag publication, and publication outcome reporting.
+
+CommandKit maintainers own version selection, candidate contents, compatibility
+explanations, release-note preparation, dependency preparation, and the repository
+runbook. The first release version is chosen during release preparation under
+the release policy; it is not a constant in the publisher or profile.
+
+Adoption adds maintainer tooling without adding a production package, a public
+ReleaseKit wrapper, or a standard application command family. The root
+`commandkit` facade, internal Cobra boundary, and existing version-reporting
+responsibilities continue to follow their accepted contracts. ReleaseKit's
+`buildinfo` package is not needed for this integration.
+
+### Tool selection and launcher
+
+Declare `gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit` as a Go tool
+dependency in CommandKit's root `go.mod`, initially selecting ReleaseKit
+v0.2.0. Commit the resulting module metadata and checksums. The Go
+[tool directive](https://go.dev/doc/modules/gomod-ref#tool) retains executable
+tool dependencies without importing them into the library.
+
+Provide a small executable `scripts/release` launcher whose publication entry
+point is `./scripts/release VERSION`. It builds the ReleaseKit CLI selected by
+the candidate's module configuration, then executes its `publish` command for
+CommandKit's repository and profile. Build the tool with committed module
+metadata in readonly mode, with workspace discovery disabled and the compatible
+local toolchain selected. Use an ignored `.releasekit/` directory for the local
+tool binary so bootstrap output does not make the candidate dirty.
+
+The launcher owns argument handling, repository location, tool bootstrap, and
+invocation. It preserves the executable's output, exit status, and signal
+handling. It does not reimplement publication guards, run a separate required
+`check` first, push `main` automatically, or turn hosted delivery into a
+publication gate. Build and execute the CLI directly so its distinct failure
+statuses remain available to maintainers.
+
+ReleaseKit's requirements expand the module graph, including its Goldmark and
+`golang.org/x/mod` dependencies. Review resulting version selections during
+adoption. Keeping these packages out of library imports avoids runtime linkage;
+it does not make their module requirements disappear.
+
+### Source-only profile
+
+Add a root `releasekit.json` selecting:
+
+- product `CommandKit`;
+- authoritative remote `origin`; and
+- expected effective push URL
+  `https://gitea.maximumdirect.net/eric/CommandKit.git`.
+
+Use the default candidate suite. Initially leave additional checks, optional
+validation selections, binary builds, and hosted delivery unselected. In
+particular, the adoption does not establish race, full-vet, cross-platform,
+formatting, Markdown, module-distribution, or file-size gates.
+
+The JSON profile is maintainer configuration for ReleaseKit; it does not change
+CommandKit's native YAML inspection contracts. Its field definitions remain
+owned by the upstream
+[configuration reference](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/e030794969fb7787e647a90bbc4eb81bd0610f07/docs/config.md).
+
+### Publication workflow
+
+The runbook selects ReleaseKit's supported sequence:
+
+1. Prepare and commit the candidate and matching release note on `main`.
+2. Prepare the module dependencies and tool dependencies needed by the local
+   compatible toolchain, separately from offline candidate validation.
+3. Push the candidate commit to authoritative remote `main` using explicit refs.
+4. Invoke the single publication launcher for the selected version.
+
+ReleaseKit requires remote `main` to identify the candidate before publication;
+this adoption uses the branch-first approach permitted by CommandKit policy.
+An atomic branch-and-tag publication path is not part of this target.
+
+After publication preflight, ReleaseKit runs one
+`go test -mod=readonly -count=1 ./...` suite with module and toolchain downloads
+disabled. It rechecks the candidate and endpoint, creates an annotated tag from
+the committed note, and pushes only the intended tag object. A successful push
+completes publication without waiting for CI, module availability, artifacts,
+or consumer installation. The upstream
+[publication guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/e030794969fb7787e647a90bbc4eb81bd0610f07/docs/consumers/publish.md)
+owns the implementation contract.
+
+The runbook must distinguish failures before publication, known unsuccessful
+pushes, conflicts, and unknown push outcomes. ReleaseKit retains a local tag
+after a failed push; blindly rerunning the ordinary publisher is not a recovery
+procedure. Document authoritative remote inspection and the permitted recovery
+actions under the release policy, preserving published tags and unresolved tag
+state. Never force an update to bypass a guard.
+
+### Documentation and release notes
+
+Create `docs/release.md` when the launcher and profile exist. It owns the
+copyable preparation/publication commands, prerequisites, automated guards,
+completion point, and recovery instructions. Link to ReleaseKit's owning
+references for detailed CLI statuses and profile definitions rather than
+maintaining a second upstream reference in CommandKit's CLI documentation.
+
+The procedure explains that ReleaseKit validates the note's product/version
+heading but does not assess compatibility prose or enforce CommandKit's license
+footer. Prepare and review that content through ordinary change review. Each
+release note must include the immutable-tag `COPYRIGHT | LICENSE | ATTRIBUTION`
+links required by the OSS policy. This introduces no additional network check,
+manual approval gate, or custom note checker.
+
+Update the release policy's undecided-adoption statement when integration lands,
+preserving its substantive rules and provenance. Update README and developer
+navigation to point to the implemented runbook and remove their obsolete
+release-tooling status statements. Current procedures belong in the runbook;
+this roadmap and the forthcoming staged plan retain target/status information.
+
+### Licensing and incorporated material
+
+Review the selected ReleaseKit source, dependency notices, and any copied
+launcher or integration material under the OSS policy. Update applicable
+attribution entries and license texts together with incorporation, identifying
+selected upstream revisions and preserving required notices.
+
+Tool use alone does not establish an attribution requirement under that policy.
+Determine treatment from actual incorporation or distribution rather than add
+entries for every development tool. Any copied or adapted documentation needs
+its own applicable treatment. Author the CommandKit runbook for this integration
+and reuse upstream guidance through links where practical.
+
+## Work needed from the baseline
+
+These are implementation work areas, not the staged execution instructions.
+The next plan must order them, specify concrete edits and proportionate evidence,
+and preserve any changes made after this baseline.
+
+| ID | Work | Completion result |
+| --- | --- | --- |
+| RK-01 | Add the released Go tool dependency and review module resolution. | Root module metadata selects v0.2.0 and retains the tool through normal module maintenance; no sibling replacement or library import is needed. |
+| RK-02 | Add the source-only profile. | Product, authoritative remote, and effective push destination are explicit; only the default suite is selected. |
+| RK-03 | Add the executable launcher and ignore its local build output. | One repository publication command builds the module-selected CLI without changing candidate metadata and preserves its outcomes. |
+| RK-04 | Write the implemented release runbook and reconcile navigation/policy status. | Maintainers have one canonical procedure for preparation, publication, and recovery; current documents describe available tooling accurately. |
+| RK-05 | Review licensing scope and maintain affected notices. | Incorporated material receives policy-conforming attribution and texts without blanket tooling requirements. |
+| RK-06 | Establish focused integration evidence and record completion. | The launcher/profile work together and the adoption respects existing library boundaries; the roadmap records actual completion and remaining release preparation. |
+
+## Completion evidence and handoff
+
+Select evidence for the new integration rather than duplicate ReleaseKit's entire
+candidate and Git test inventory. During implementation, establish that:
+
+- The repository's committed module configuration selects the tool, including
+  after ordinary module maintenance; bootstrap leaves module files unchanged.
+- The launcher finds the repository/profile, handles its version argument,
+  preserves ReleaseKit's diagnostic output and distinct exit statuses, and
+  leaves no untracked bootstrap output in candidate status.
+- A representative disposable repository exercise reaches source publication
+  through the selected launcher/profile without binary or hosted-service work.
+  Use local fixtures, not CommandKit's live remote, for publication evidence.
+- Invalid candidate or publication preflight state fails through ReleaseKit
+  without bypassing its guards. Focus new coverage on integration mistakes;
+  upstream already owns comprehensive publication and recovery behavior.
+- The library has no new ReleaseKit runtime imports or exported surface, and
+  affected documentation, notices, paths, and intended release links agree with
+  the implemented integration.
+
+The staged plan should identify the checks appropriate to these risks and reuse
+existing evidence where sufficient. Adoption checks are not automatically
+permanent release gates. Diagnostic `check` remains optional; the actual release
+publisher validates its final candidate once.
+
+Adoption is complete when RK-01 through RK-06 are implemented and reviewed,
+focused evidence is recorded, and the runbook is executable from the documented
+prerequisites. Publishing CommandKit's first release remains separate work:
+select a fresh version, prepare its note and final candidate, and follow the
+runbook with publication authorization. Do not create a placeholder release
+note or publish a tag merely to complete tooling adoption.
+
+## Deferred capabilities
+
+Hosted Gitea release-page delivery is deferred. If selected later, reuse the
+checked-in release note and report delivery separately from source publication.
+Use ReleaseKit's
+[module-selected tooling approach](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/e030794969fb7787e647a90bbc4eb81bd0610f07/docs/adr/0004-module-selected-tooling.md)
+so retries select the tool from the released source rather than current `main`.
+CI integration and credentials become relevant only when that delivery work is
+selected.
+
+Binary targets, assets, build matrices, runtime `buildinfo` integration, and
+additional validation gates are outside this adoption target. They may be
+considered later for concrete needs under the owning policies; ReleaseKit's
+support for them does not establish CommandKit requirements.