audita/docs/roadmap/releasekit.md

# 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. The
[implementation plan](implementation.md) owns the ordered execution steps and
their verification; this roadmap owns the desired end state and adoption intent.