audita/docs/roadmap/releasekit.md

ReleaseKit v0.3.0 Upgrade Roadmap

Last updated: 2026-10-08 Status: Release policy adopted; library and toolchain upgrade pending.

Purpose

Upgrade Audita directly from ReleaseKit v0.1.0 to v0.3.0, continuing the decision in ADR 0001. Shared release mechanics belong in ReleaseKit; Audita supplies product facts, compatibility decisions, release notes, and thin integration wiring. Standardization and less locally owned release code remain the reasons for adoption.

This roadmap replaces the completed initial-adoption roadmap. It defines the upgrade's target state and required work; a later implementation plan can own ordered execution steps.

Current Baseline

At Audita commit 17421bc5f352f3fdeb67561b2b60b49979822228:

• go.mod selects ReleaseKit v0.1.0 and declares Go 1.25.5. Audita imports the lightweight buildinfo facade for its configuration-free version command. The ReleaseKit CLI is not registered as a Go tool dependency.
• scripts/release.sh builds the module-selected CLI using temporary copies of module metadata, then forwards native arguments and exit status.
• .woodpecker/release.yml already verifies the event tag and commit before bootstrapping the tool from that tag's module selection. Its Go image is golang:1.25.5; the delivery secret remains GITEA_RELEASE_TOKEN.
• releasekit.json selects Linux amd64 and arm64 artifacts and Audita's Gitea destination. It enables no optional validation checks or additional commands.
• The release procedure uses main-first publication, annotated tags, offline candidate tests, selected builds, and the native version smoke check. Source publication completes independently of CI and artifact delivery.
• The local release policy is based on Standard Repository Policies version 1.4. It lacks the newer distinction between the consumer minimum and release toolchain and the explicit minor-release exception for Go-minimum increases.
• Release tests include exact expectations for the current dependency version and Go image. Documentation and attribution still identify the old versions.

The initial adoption's review findings are resolved. They are historical context, not additional work for this upgrade.

Since that baseline, Audita has adopted release policy 1.6 and updated its provenance, policy attribution, and release runbook. The current Go minimum and selected release toolchain remain 1.25.5. The dependency, tool registration, bootstrap simplification, and Go 1.26 upgrade described below remain pending.

Selected Upstream Revisions

Adopt ReleaseKit v0.3.0, commit e43df4416e0ed987349b2ea04a2c68c25e552772. Its release note records reduced Git subprocess work, source retention, artifact hashing, and output copying, plus improved cancellation and isolated synthetic-module test caches. Public signatures, CLI commands, and profiles remain compatible with v0.2.0. The required Go minimum is now 1.26.0.

The direct upgrade also includes v0.2.0's optional declarative validation and structured diagnostics. Audita already uses its module-selected CI bootstrap approach. The largest file-validation performance gains apply only when those checks are selected; this upgrade does not enable them merely to obtain gains.

The adopted release policy uses Standard Repository Policies version 1.6 at commit e833faddf120c789a9b45348edaf75720de16348, following its adoption guide. Other locally adopted policies retain their existing upstream revisions.

Target End State

Audita selects ReleaseKit v0.3.0 for both buildinfo and the registered CLI through one module graph. The application continues to expose the existing version command without configuration or LLM setup. Release orchestration and its dependencies stay outside transcript processing.

The consumer/source-build minimum is Go 1.26.0. The selected maintainer and CI release-build toolchain is Go 1.26.8. The patch used for validation and builds is separate from the minimum supported for source consumers. Running a distributed Audita executable does not require installing Go.

Local tooling uses the module-selected Go tool with only the repository selection and native invocation wiring needed by Audita. CI continues to select ReleaseKit from the triggering tag's module files, preserving the existing secret mapping and protection of tagged source during bootstrap. Historical tag retries retain their own dependency selections.

The profile, production targets, artifact identities, version semantics, and source-completion rule retain their current behavior. Linux amd64 and arm64 remain required; macOS arm64 remains best effort. ReleaseKit continues to own candidate validation, publication, builds, checksums, and delivery recovery.

The local release policy adopts upstream's explicit allowance for Go-minimum increases in minor releases, with the increase and required source-consumer action explained in the release note. Patch releases preserve the consumer minimum. Other compatibility changes remain governed by the adopted policy.

Work Required

Module Selection and Local Tooling

Upgrade the released dependency directly to v0.3.0 and register gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit in Go's tool metadata. Run module tidying and review the resulting go.mod and go.sum. The tool registration retains CLI-only dependencies and their checksums through tidying; no local checkout replacement is needed.

Simplify scripts/release.sh around the selected tool. Remove its temporary module-file bootstrap where the registered tool and prepared dependencies make that machinery unnecessary. Preserve argument boundaries, native status forwarding, and the separation between tool preparation and offline candidate validation. Keep the existing documented entry point proportionately covered.

Toolchain and CI

Declare Go 1.26.0 in go.mod and use Go 1.26.8 for maintainer release tooling, candidate validation, and CI artifact builds. Update the Woodpecker image to a compatible Go 1.26.8 image with Git. Keep local toolchain selection explicit; Go 1.25.5 cannot build this dependency with GOTOOLCHAIN=local.

Align CI with the maintained v0.3.0 tag-delivery integration while retaining Audita's destination, secret mapping, and module-based tool selection. Preserve tag verification before Go bootstrap and temporary metadata outside the tagged checkout where the upstream CI template uses it. The local and CI integrations need not have identical preparation machinery when their responsibilities differ.

Policy Alignment and Documentation

The release-policy update is complete. docs/policy/release.md now incorporates the selected upstream 1.6 revision, with template-only instructions removed and Audita's platform commitments and accepted native-host version check retained. It preserves independent source completion and proportionate automated gates. Mixed-revision attribution records the policy's exact source separately from the other adopted policies. No human release gate was introduced.

Update docs/release.md and docs/development.md for the source minimum, selected release toolchain, dependency preparation, and simplified local invocation. Refresh relevant upstream links to v0.3.0. Update other canonical references only where the implementation changes their facts. The accepted ADR continues to apply and its decision content needs no revision.

When preparing the next release, explain the Go-minimum increase and maintainer workflow changes in its new note. Version selection and publication timing remain release-preparation tasks. Preserve existing tagged notes and assets.

Attribution

Update ReleaseKit's entry in docs/oss/attribution.md to the selected version and exact source commit. Its LGPL-3.0-or-later grant remains unchanged. Review CLI-only dependencies according to their actual use and distribution; a module requirement alone does not establish incorporation into Audita binaries.

Update Go runtime and standard-library notices, including relevant vendored components, for the selected Go 1.26.8 release-build toolchain. Reuse existing license texts where applicable. The copied release policy's scope and commit-specific source and notice links have already been updated; preserve that accurate mixed-revision attribution during the remaining upgrade work.

Consumer Verification and Test Maintenance

Update release integration coverage for the new selection, tool declaration, CI image, and simplified wrapper. Remove assertions that elevate a particular dependency version, image spelling, or bootstrap implementation into a lasting prohibition on legitimate upgrades. Older-version fixtures can remain when they protect tagged-version selection; do not replace every historical value.

Retain proportionate protection of product facts, target membership, native argument/status forwarding, preparation failures, and tagged-source selection. Rely on upstream coverage for common release mechanics. Tests using synthetic module downloads must use test-owned module caches.

Run the ordinary offline suite and verify both Linux builds with the selected toolchain. Exercise the real ReleaseKit build/version-injection path as an upgrade check. These checks do not require source publication, hosted uploads, real delivery credentials, or LLM calls.

Scope Boundaries

This is a dependency, tooling, and release-policy upgrade. Transcript processing, application configuration, LLM behavior, and output formats retain their current contracts. Keep optional validation and additional checks at their current selections. Adding race, vet, formatting, Markdown, distribution, file-size, or new publication-destination checks is a separate deliberate choice.

No intermediate v0.2.0 adoption, compatibility scaffolding, patch-version test matrix, performance threshold, or quantified code-deletion target is required. Use the implementation's resulting simplicity to assess reduced ownership. CI success and downloadable artifacts remain separate delivery observations, not source-release completion gates.

Acceptance and Existing Evidence

The upgrade is complete when the selected dependency and tool declaration are consistent; the module minimum and release-build toolchain are recorded in their canonical owners; the local wrapper and tagged CI integration use that selection; and the ordinary tests and required Linux builds pass. Version injection must still reach Audita's existing version command. Policy provenance, attribution, and current documentation must describe the implemented upgrade accurately.

The preceding review already passed ReleaseKit's full suite and a disposable Audita upgrade's full suite on Go 1.26.8, after adjusting the current-version assertion in that copy. Linux amd64 and arm64 compilation succeeded, and the new tool dependencies were absent from Audita's runtime dependency list. That evidence supports feasibility; it does not substitute for verifying the final implementation, simplified bootstrap, or real injected-version build.

Live Woodpecker/Gitea delivery was not exercised during review. Observe delivery asynchronously when the first upgraded release is published and address any deployment failures through the shared recovery procedure. No significant feature decisions remain open; implementation details and final release preparation can be resolved within the agreed scope.