audita/docs/roadmap/implementation.md

# Implementation Plan: ReleaseKit Adoption

**Last updated:** 2026-10-07
**Status:** Ready for implementation; no stages completed.
**Audience:** Luna coding agent.

## Scope and Execution

Implement the target in the [ReleaseKit roadmap](releasekit.md), following
[ADR 0001](../adr/0001-releasekit.md). The roadmap owns intent and policy
choices; this document owns execution. The planning baseline is Audita commit
`418da456d75a68d3bb5a43ab823c5b2b434b90cc`: v3.0.0 is released, the ADR is
accepted, and release tooling still uses the custom scripts and delivery plugin.

This replaces the completed PromptKit plan. Its
[completion record](https://gitea.maximumdirect.net/eric/audita/src/commit/418da456d75a68d3bb5a43ab823c5b2b434b90cc/docs/roadmap/implementation.md)
remains available for historical adoption references.

Execute Stage 1 through Stage 5 in order. Each is a bounded Luna implementation
unit. Commit completed units with plain English messages under the
[agent policy](../policy/agents.md), recording the relevant checks. Intermediate
commits need not be release-ready; complete the migration directly without
compatibility wrappers for the old release arguments or temporary release modes.

Start with [development guidance](../development.md), use graph-first discovery,
and follow the applicable [architecture](../policy/architecture.md),
[testing](../policy/testing.md), [documentation](../policy/documentation.md),
[release](../policy/release.md), and [OSS](../policy/oss.md) policies. Preserve
transcript processing and its current configuration, reporting, and LLM behavior.

Use ReleaseKit v0.1.0, commit
`5e60fe3113c69f95c42fbbe32a8ca4b51f5b83c1`. The sibling checkout is reference
material. Its pinned [configuration](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.1.0/docs/config.md),
[CLI](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.1.0/docs/cli.md),
[build](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.1.0/docs/consumers/build.md),
and [delivery](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.1.0/docs/consumers/delivery.md)
contracts own generic mechanics. Keep Go 1.25.5 and unrelated dependency
selections. Use released modules without a production local replacement.

### Selected Implementation Decisions

- Audita imports `ReleaseKit/buildinfo` for runtime version information. The
  upstream executable owns release orchestration; no application release engine
  or private linker variable is needed.
- `releasekit.json` owns product facts. Local tooling builds the executable from
  the module graph; CI pins the same v0.1.0 release explicitly.
- Keep `scripts/release.sh` as a thin entry point with native ReleaseKit
  arguments, such as `publish VERSION` and `check VERSION`. Compile its tool into
  ignored `bin/releasekit` and invoke it with `exec` to preserve native statuses.
- Main-first preparation, annotated tags, the offline standard suite, Linux
  builds, and the native version smoke check are accepted. On a nonselected
  host, the shared builder may compile a temporary native executable and require
  its check to succeed. Keep only Linux amd64 and arm64 delivery targets.
- CI uses managed `ci-deliver` and the existing `GITEA_RELEASE_TOKEN` secret,
  exposed to the command as `RELEASEKIT_GITEA_TOKEN`. Retained prebuilt artifacts
  remain an upstream recovery option rather than a second ordinary CI sequence.
- Additional profile checks are omitted. Do not repeat the standard suite,
  maintain a local Git/publication guard layer, or copy upstream delivery logic.
  Focus tests on Audita wiring and reuse existing protection for common mechanics.

This implementation sprint does not choose an Audita release version, write a
new versioned release note, tag, push to the authoritative repository, contact
Gitea with delivery credentials, or wait for CI. Deployment observations belong
to the first adopting release and its separate delivery status. No extra release
gates or platform guarantees are introduced by these adoption checks.

## Stage 1 — Add the Dependency and Version Command

**Primary files:** `go.mod`, `go.sum`, `internal/cli/run.go`, and focused tests in
`internal/cli`.

1. Add `gitea.maximumdirect.net/eric/ReleaseKit@v0.1.0` with `go get`. Import its
   public `buildinfo` package in the CLI and run `go mod tidy` after the import
   is present. Review the dependency diff for unrelated upgrades or replacements.
2. Add `version` dispatch to the existing CLI. With no arguments, print
   `audita ` followed by `buildinfo.Version()` and a newline to stdout, returning
   zero. Run this route independently of application configuration and runtime
   assembly. Use the existing output streams and standard-library parsing style.
3. Add the command to root help. Support `help version` and the usual
   `version -h`/`version --help` help behavior with stdout and status zero.
   Unexpected positional arguments or unknown flags use the existing usage-error
   status two. No new version flags are needed at the root level.
4. Add compact CLI coverage for successful version output, help, and malformed
   invocation. Derive the expected version from the public accessor rather than
   hardcoding `dev`. Exercise the version route from a temporary working directory
   without application setup and verify stderr stays empty on success. Preserve
   existing commands and help behavior.

**Verification and completion:** Run
`go test ./internal/cli ./cmd/audita`, build the application to ignored
`bin/audita`, and run its `version` command. Run `git diff --check`, review the
module diff, and commit. Real release-version injection is verified in Stage 5;
no test should hardcode an upstream private linker symbol.

## Stage 2 — Introduce the Product Profile and Thin Local Wrapper

**Primary files:** new `releasekit.json`, `scripts/release.sh`, and
`scripts/release_test.go`.

1. Write a JSON profile with these exact product settings:

   | Field | Value |
   | --- | --- |
   | `product` | `Audita` |
   | `remote` | `origin` |
   | `build.main_package` | `./cmd/audita` |
   | `build.binary_name` | `audita` |
   | `build.targets` | `linux/amd64`, `linux/arm64` |
   | `delivery.base_url` | `https://gitea.maximumdirect.net` |
   | `delivery.owner` | `eric` |
   | `delivery.repository` | `audita` |
   | `delivery.token_env` | `RELEASEKIT_GITEA_TOKEN` |

   Omit `checks`. Store no token value and use the upstream profile format
   directly; Audita does not need another profile parser in production.
2. Replace the wrapper body with straightforward Bash using `set -euo pipefail`:
   select the repository directory relative to the script, create `bin/`, build
   the selected CLI, and execute it with the original argument vector. The
   build command is:

   ```sh
   GOWORK=off GOTOOLCHAIN=local go build -mod=readonly \
     -o ./bin/releasekit gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit
   ```

   Finish with `exec ./bin/releasekit "$@"`. Preserve argument boundaries and
   build failures. Existing `bin/` ignore rules suffice. Let ReleaseKit parse
   its commands and report errors; remove all local note, version, Git, test,
   build-target, and publication mechanics from the wrapper.
3. Replace `TestReleaseWorkflow`'s old fourteen-scenario matrix. Use a temporary
   layout with the real wrapper and a stub at the Go/tool boundary to verify
   repository selection, forwarded native arguments (including an argument with
   spaces), and returned tool status. Include uncertain publication status three
   and a failed bootstrap that never executes the tool. The stub writes a small
   executable at the requested output path; assert effects and arguments without
   tying tests to harmless build-flag ordering or a particular shell layout.
4. Add a focused check of the committed JSON profile's product/build/delivery
   facts and absence of additional checks or credential values. Standard JSON
   decoding in test code is sufficient. Keep this coverage alongside wrapper
   tests; compare target membership rather than incidental list order. Avoid
   reproducing upstream profile validation or remote guard tests.
5. Keep `scripts/build-release.sh` until Stage 3 removes its CI caller. The new
   wrapper already uses ReleaseKit's selected build specification.

**Verification and completion:** Run `go test ./scripts`, then
`bash scripts/release.sh version` to verify real tool bootstrap and execution.
This prints the tool's version, not Audita's. Check ignored build output and
`git diff --check`, then commit. No publication or delivery invocation against
an external service is needed.

## Stage 3 — Migrate Woodpecker Delivery and Retire the Builder

**Primary files:** `.woodpecker/release.yml` and deletion of
`scripts/build-release.sh`.

1. Adapt the maintained upstream
   [tag-delivery template](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.1.0/examples/woodpecker/tag-delivery.yml).
   Use its matrix and single `deliver` step with `GO_IMAGE: golang:1.25.5` and
   `RELEASEKIT_VERSION: v0.1.0`. Select tag events under `refs/tags/v*`.
2. Map the command environment variable `RELEASEKIT_GITEA_TOKEN` from the
   existing Woodpecker secret `GITEA_RELEASE_TOKEN`. Use the existing credential;
   no new secret name or credential provisioning is selected by this migration.
3. Use the template's command, preserving Woodpecker interpolation escaping:

   ```sh
   go run gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit@${RELEASEKIT_VERSION} ci-deliver \
     --repo "$${CI_WORKSPACE}" \
     --commit "$${CI_COMMIT_SHA}" \
     "$${CI_COMMIT_TAG}"
   ```

   ReleaseKit owns fetch/checkout verification, dependency preparation, builds,
   note-page creation, manifests, and uploads. Remove the separate build step,
   release plugin, wildcard asset settings, and local checksum configuration.
   Managed delivery gets its targets and destination from `releasekit.json`.
4. Delete `scripts/build-release.sh` after confirming its active caller is gone.
   Search remaining script/CI references and remove only obsolete active
   invocations. Historical release records retain their original descriptions.
5. Review the parsed workflow against the template: selected image/pin, tag
   trigger, token mapping, and event arguments. Use the existing YAML dependency
   or available tooling for local syntax inspection. Confirm the tool pin matches
   the selected module. This is adoption validation; it does not require a new
   permanent workflow-text snapshot test or a running Woodpecker instance.

**Verification and completion:** Run `go test ./scripts`, review the workflow
and profile together, and run `git diff --check`. Commit the delivery migration.
The existing Go image must provide compatible Go and Git; real runner execution
is observed during subsequent delivery, independently of source completion.

## Stage 4 — Align Policy, Documentation, and Attribution

**Primary files:** `docs/release.md`, `docs/policy/release.md`, `docs/cli.md`,
`docs/internal/cli-config.md`, `docs/adr/README.md`, and
`docs/oss/attribution.md`. Update other current references only where affected.

1. Rewrite the runbook around dependency preparation, a committed candidate,
   `git push origin main`, and `bash scripts/release.sh publish VERSION`.
   Explain that remote `main` must identify the captured candidate exactly.
   `bash scripts/release.sh check VERSION` is an optional local diagnostic,
   never a required pre-publication step. Document preparation with
   `GOWORK=off GOTOOLCHAIN=local go mod download`; if it changes module files,
   those changes belong in the candidate before publication.
2. Describe annotated notes-derived tags, native publication statuses, and
   recovery against the captured authoritative endpoint. State that the tool
   retains a local tag after push failure. An exact-object recovery can confirm
   success; an unreadable result remains unknown. Link to pinned upstream
   recovery guidance instead of implementing or repeating its full algorithm.
   Remove the old atomic-push prerequisite and procedure.
3. Describe the shared tagged-source delivery command, the existing secret
   mapping, Linux artifacts, note body/footer, and separate delivery status.
   Explain content-aware retries and retained-artifact recovery by linking to
   upstream. Remove references to the retired builder/plugin and the assertion
   that Audita has no version command. Keep the release script's bootstrap
   preparation distinct from its offline candidate validation.
4. In the release policy, retain upstream wording wherever it already permits
   the selected approach. Add a concise project-specific native-host check
   provision under supported platforms/candidate validation: Linux delivery
   targets remain required, macOS development remains best effort, and running
   publication on a nonselected host requires ReleaseKit's temporary native
   version check to succeed. Qualify the existing statement that macOS failures
   never block release accordingly. Mac access and native tests on every target
   remain unnecessary. Date the local policy update and preserve its upstream
   source attribution. Avoid unrelated policy changes or additional gates.
5. Document `audita version`, its stdout/help/usage behavior, and public version
   fallback in `docs/cli.md`. Add a short implementation/change-recipe note in
   `docs/internal/cli-config.md` linking to that contract and the accepted ADR.
   Update the ADR index to list ADR 0001; its current assertion that no ADR exists
   is obsolete. Preserve the accepted ADR's content.
6. Add a House Format ReleaseKit entry with selected module v0.1.0,
   `Copyright (C) 2026 Eric Rakestraw`, and `LGPL-3.0-or-later`. Link existing
   `licenses/LGPL-3.0.txt` and `licenses/GPL-3.0.txt`, and the upstream COPYRIGHT
   and source at commit `5e60fe3113c69f95c42fbbe32a8ca4b51f5b83c1`. Check the
   selected module's notices. Keep the application grant and unchanged license
   texts intact; no policy-template material is copied in this feature.
7. Repair current navigation affected by replacing this implementation plan.
   Completed PromptKit/ConfigKit roadmap references that intend to identify
   their former plan should link to the corresponding historical completion
   records, not this ReleaseKit plan. Preserve published release notes and tags.
   The next release note is deferred to release preparation.

**Verification and completion:** Check commands against the new wrapper/CLI,
local links and anchors, pinned upstream references, source attribution, and
`git diff --check`. Use the prior successful code checks for unchanged code.
Commit the documentation unit.

## Stage 5 — Verify Adoption and Close the Plan

**Primary files:** This plan and the ReleaseKit feature roadmap; fix an
implementation file only if the final checks expose a real integration defect.

1. Audit the roadmap acceptance criteria against the landed files. Confirm the
   runtime uses the public version accessor, the profile selects only the two
   Linux targets, pins agree, the wrapper owns no common release mechanics, and
   the old builder and repeated publication tests have been retired.
2. Prepare dependencies if necessary, then run `go test ./...` and
   `go build -o ./bin/audita ./cmd/audita`. Run the normal binary's `version`
   command without application setup. These tests remain offline; preparation
   may use the module network separately.
3. On the committed implementation, verify the real shared builder once using
   temporary output outside the repository:

   ```sh
   releasekit_check_dir=$(mktemp -d)
   bash scripts/release.sh build --output "$releasekit_check_dir" v0.0.0
   ```

   `v0.0.0` is solely a build-test identifier, not an Audita release selection.
   `build` requires no release note or remote publication. Confirm both
   `audita-v0.0.0-linux-amd64` and `audita-v0.0.0-linux-arm64` are produced;
   ReleaseKit's own mandatory native smoke check must report success. It checks
   `audita v0.0.0` with a newline on a host-runnable executable, building a
   temporary native executable itself when needed. Do not execute a foreign
   architecture binary. Remove the temporary output afterward. The CLI's private
   build receipt is an upstream artifact and should not enter Git.
4. Review the dependency/attribution diff, wrapper/profile wiring evidence,
   workflow syntax and pin, and current documentation. Run `git diff --check`
   and confirm no generated output, credentials, or unrelated work is staged.
   Fix proven defects and rerun only affected checks. No real tag publication,
   hosted upload, paid inference, extra platform matrix, or CI polling is needed
   to establish this implementation's completion.
5. Mark the plan and feature roadmap complete after these requirements pass.
   Record the tested implementation revision and checks; distinguish a later
   documentation-only closure commit. Summarize the local infrastructure removed
   and any remaining deployment observations accurately. Commit the closure.
   The first adopting release and live delivery remain separate authorized work.

**End state:** Audita supplies a product profile, native version command, thin
local entry point, and shared CI invocation. ReleaseKit owns the common release
mechanics and their tests. Documentation and attribution match the integration.
No implementation-blocking open questions remain.