Document the ReleaseKit adoption roadmap

docs/roadmap/releasekit.md

@@ -0,0 +1,180 @@
+# ReleaseKit Adoption Roadmap
+
+**Last updated:** 2026-10-07
+**Status:** Adoption accepted; implementation pending.
+
+## Purpose and Baseline
+
+Implement the decision in [ADR 0001](../adr/0001-releasekit.md): standardize
+Audita's release process on ReleaseKit to improve maintainability and reduce
+locally owned release-focused code. Those benefits outweigh the small advantages
+of retaining Audita's custom procedure. The workflow changes required by the
+shared standard are accepted.
+
+At Audita revision `6de470b53d185b10327ec4deba23f5a84e606e1f`, v3.0.0 is
+released. Audita owns `scripts/release.sh`, `scripts/build-release.sh`, and
+`scripts/release_test.go`, totaling 207 lines, plus the 26-line Woodpecker delivery
+workflow. Publication validates a clean candidate, cross-builds Linux binaries,
+and atomically pushes `main` and a lightweight tag. Woodpecker builds artifacts
+and uses a release plugin to publish the note, binaries, and checksums. Audita
+has no runtime version command.
+
+The adoption baseline is ReleaseKit v0.1.0, commit
+`5e60fe3113c69f95c42fbbe32a8ca4b51f5b83c1`. Its public library, executable,
+`buildinfo` package, and maintained Woodpecker integration cover the required
+mechanics. The upstream test suite passes; its documentation records live
+Woodpecker/Gitea verification as remaining deployment work.
+
+## Target End State
+
+- ReleaseKit owns candidate validation, source publication, version injection,
+  selected-target builds, checksum generation, and hosted delivery. Audita owns
+  its product facts, compatibility decisions, release notes, and necessary
+  product-specific checks.
+- A small `releasekit.json` declares product `Audita`, remote `origin`, main
+  package `./cmd/audita`, binary name `audita`, and delivery targets
+  `linux/amd64` and `linux/arm64`. Its Gitea destination identifies
+  `https://gitea.maximumdirect.net`, owner `eric`, and repository `audita`.
+- Maintainers commit the candidate and publish it to authoritative `main`
+  before invoking ReleaseKit publication. ReleaseKit validates that candidate,
+  creates an annotated tag from the committed note, and pushes its exact tag
+  object. Confirmed source publication completes the release independently of
+  CI and artifact delivery.
+- One captured candidate receives ReleaseKit's standard offline test suite and
+  selected build verification. Audita's profile introduces no additional checks
+  without a concrete product need. The optional local check remains a diagnostic
+  operation rather than a prerequisite that duplicates publication validation.
+- `audita version` reports `audita <version>` through ReleaseKit's public
+  `buildinfo.Version()` accessor. Ordinary development builds use its native
+  fallback behavior, including `dev` when release information is unavailable.
+- Woodpecker invokes the pinned shared `ci-deliver` command. Hosted notes,
+  Linux assets, and `SHA256SUMS` retain their current identities; delivery
+  compares existing content, adds missing assets, and reports conflicts and
+  uncertainty separately from source publication.
+- Audita's release code consists of thin tool invocation and product wiring,
+  with focused integration coverage. Common mechanics and their repeated tests
+  reside upstream.
+
+## Accepted Standardization Choices
+
+Adopt ReleaseKit's main-first publication and annotated tags, replacing the
+atomic branch/tag push and lightweight tags for new releases. Existing released
+tags, notes, pages, and assets retain their historical contents.
+
+Adopt its standard build settings and mandatory native version smoke check.
+The check verifies that version injection reaches the executable. On a host
+outside the selected Linux targets, ReleaseKit can build a temporary native
+binary; publication from that host depends on that check succeeding. This is an
+accepted workflow change, including for macOS invocations. Linux remains the
+production delivery target, and macOS remains a best-effort development platform.
+Mac access and macOS artifact delivery are not release prerequisites.
+
+Use the shared managed build-and-deliver operation for ordinary CI delivery.
+ReleaseKit's retained-artifact workflow remains available when a delivery retry
+needs the original bytes. Follow its content-aware recovery behavior rather
+than reproducing that machinery in Audita.
+
+## Work Required
+
+### Dependency, Profile, and Tool Entry Point
+
+Select the released v0.1.0 module in `go.mod` and `go.sum`. The application uses
+the lightweight `buildinfo` facade; release orchestration is exercised through
+the upstream executable. The sibling checkout is review material, not a
+production dependency replacement.
+
+Add the product profile described above. Leave additional checks empty and keep
+delivery tokens out of the profile. Use `RELEASEKIT_GITEA_TOKEN` as the token
+environment variable, supplied from the existing Woodpecker
+`GITEA_RELEASE_TOKEN` secret.
+
+Reduce `scripts/release.sh` to repository selection, building the CLI selected
+by Audita's module graph into ignored `bin/` output, and invoking it directly.
+Forward ReleaseKit's native commands and arguments and preserve its exit status,
+including uncertain publication status. Use the same released tool version in
+the module graph and CI pin. Dependency/tool preparation belongs before offline
+candidate validation.
+
+### Runtime Version Reporting
+
+Add `version` to the existing CLI dispatch and help, with output
+`audita <version>` followed by a newline and exit status zero. This operation
+works without loading application configuration, resolving LLM credentials, or
+contacting a provider. Use the public accessor and let ReleaseKit own injection
+mechanics. Keep the release orchestration dependency outside transcript
+processing.
+
+### Publication and Binary Delivery
+
+Replace the local publication and cross-build mechanics with ReleaseKit's
+commands and profile. Retire `scripts/build-release.sh` when its callers use
+the shared builder.
+
+Replace the current Woodpecker build/plugin sequence with the maintained
+tag-delivery integration, pinned to v0.1.0. Retain a compatible Go 1.25.5 image
+with Git, the existing secret, and only the selected Linux targets. Pass the
+workspace, event commit, and version to `ci-deliver`; the shared command owns
+tagged-checkout verification, dependency preparation, build, and delivery.
+
+The declared artifacts remain `audita-<version>-linux-amd64`,
+`audita-<version>-linux-arm64`, and `SHA256SUMS`. The committed release note
+supplies the hosted body and required licensing footer. Delivery status and
+recovery follow the upstream operation; source publication does not poll CI or
+wait for assets.
+
+### Tests and Removal of Duplicated Mechanics
+
+Replace the repeated release-mechanics matrix in `scripts/release_test.go`
+with proportionate coverage of Audita's wiring. Protect the new version command
+and wrapper/profile integration where these introduce distinct consumer risks.
+Verify actual version injection and the selected Linux builds through the real
+builder during adoption validation. Use local Git/HTTP fixtures and controlled
+command boundaries where needed; keep the default suite offline.
+
+Reuse ReleaseKit's coverage for common Git guards, push reconciliation,
+checksums, and delivery retries. Evaluate the reduction in local machinery from
+the resulting implementation rather than imposing a numerical deletion target.
+
+### Documentation and Attribution
+
+Update `docs/release.md` for main-first preparation, native ReleaseKit commands,
+annotated tags, dependency preparation, delivery status, and failure recovery.
+Align `docs/policy/release.md` where necessary to describe the deliberately
+accepted native-host check while retaining the existing production targets and
+independent source-completion rule.
+
+Update `docs/cli.md`, relevant internal CLI guidance, and the ADR index for the
+version command and accepted decision. Keep the ADR's decision content intact.
+Record the adoption and maintainer workflow change in the next release note
+when that release is prepared.
+
+Add ReleaseKit's selected source and LGPL-3.0-or-later notices to
+`docs/oss/attribution.md` under the existing OSS policy. Reuse applicable license
+texts already present. Incorporating `buildinfo` does not change Audita's
+application license.
+
+## Verification and Completion
+
+Adoption is complete when:
+
+- The released dependency and pinned tool are selected consistently, and the
+  application builds with its default offline test suite passing.
+- Version output works without LLM setup and reports the injected version from
+  a ReleaseKit-built executable.
+- The native profile and thin wrapper drive candidate checks and publication
+  without Audita retaining common publication or build mechanics.
+- Both required Linux targets build through ReleaseKit, and the CI workflow
+  declares the intended destination, artifacts, note body, and secret mapping.
+- Focused consumer coverage exercises the changed boundaries, and redundant
+  mechanics tests and the old builder have been retired.
+- Current documentation and attribution describe the adopted behavior.
+
+Offline integration evidence and live delivery observations are distinct.
+Observe the shared workflow during the first adopting release and address any
+deployment failures through delivery recovery. CI success or asset availability
+does not become a source-release completion gate.
+
+The accepted ADR settles the architectural choice and standard workflow
+trade-offs. No significant feature decisions remain open. The next Audita
+version and publication timing belong to release preparation; this roadmap
+does not publish a release or prescribe implementation stages.