eric/audita
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

Remove completed roadmaps and preserve deferred work

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-11 01:37:33 +00:00
parent 4c5536ab78
commit ed65aa6474
7 changed files with 19 additions and 1379 deletions
Download Patch File Download Diff File Expand all files Collapse all files

327
docs/roadmap/implementation.md
View File

@@ -1,327 +0,0 @@
# 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](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 [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:
```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.
**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](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.
**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:
```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.
**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.