audita/docs/roadmap/implementation.md

Implementation Plan: ReleaseKit Adoption

Last updated: 2026-10-07 Status: Complete; Stages 1–5 complete. Audience: Luna coding agent.

Scope and Execution

Implement the target in the ReleaseKit roadmap, following ADR 0001. 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 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, 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, use graph-first discovery, and follow the applicable architecture, testing, documentation, release, and OSS 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, CLI, build, and delivery 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 [x]

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.

Completed 2026-10-07: Added ReleaseKit v0.1.0 and the configuration-free audita version command with root/help routing and usage-error handling. Checks passed: go test ./internal/cli ./cmd/audita, go build -o ./bin/audita ./cmd/audita, ./bin/audita version, and git diff --check.

Stage 2 — Introduce the Product Profile and Thin Local Wrapper [x]

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:

   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.

Completed 2026-10-07: Added the Audita profile and replaced the local publication workflow with a wrapper that builds and execs ReleaseKit. Replaced the publication test matrix with focused wrapper and profile checks. Checks passed: go test ./scripts, bash scripts/release.sh version, ignored-output verification for bin/releasekit, and git diff --check.

Stage 3 — Migrate Woodpecker Delivery and Retire the Builder [x]

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

1. Adapt the maintained upstream tag-delivery template. 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:

   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.

Completed 2026-10-07: Migrated Woodpecker to the pinned managed ci-deliver step using the existing secret, then removed the obsolete binary builder. Verified the parsed workflow settings and command against the pinned template, confirmed the module/workflow pins match, ran go test ./scripts, confirmed no active CI or script caller remained, and passed git diff --check.

Stage 4 — Align Policy, Documentation, and Attribution [x]

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.

Completed 2026-10-07: Updated the ReleaseKit runbook, release policy, version contract and contributor guidance, ADR index, and component attribution. Repaired PromptKit and ConfigKit links to their historical implementation records. Verified local links and anchors, release CLI and version commands, pinned module/notices, source attribution, and git diff --check.

Stage 5 — Verify Adoption and Close the Plan [x]

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:

   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.

Completed 2026-10-07: Audited the adoption criteria against implementation revision 5ac704c4c42fd23ed94b1f7351491ad580726db1. Checks passed: go test ./...; go build -o ./bin/audita ./cmd/audita followed by the binary's version and --help commands; ReleaseKit's real build command produced audita-v0.0.0-linux-amd64 and audita-v0.0.0-linux-arm64 and passed its native version smoke check; profile, module/tool pins, wrapper, and parsed Woodpecker workflow matched the selected integration; and git diff --check. The closure record is a documentation-only commit after the tested implementation revision. Audita's local build and publication mechanics and their repeated-mechanics test matrix have been removed in favor of ReleaseKit. The first adopting release and live Woodpecker/Gitea delivery observation remain separate work.