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

133
docs/roadmap/configkit.md
View File

@@ -1,133 +0,0 @@
# ConfigKit v0.5.0 Adoption Roadmap
**Last updated:** 2026-10-03
**Status:** Complete. The implementation and tests are committed through
`8175ed8`. Final documentation and example changes were included in the full
build, test, example-validation, and local-link checks before the documentation
completion commit. The [historical implementation plan](https://gitea.maximumdirect.net/eric/audita/src/commit/b31955fc97adec707b4e5f9a1b0c43c4cbc66750/docs/roadmap/implementation.md)
records the ordered work and verification.
## Purpose and Baseline
Adopt ConfigKit v0.5.0 as an independently reviewable step before PromptKit
v0.12.0. Use the library's configuration and inheritance conventions while
preserving Audita's domain ownership and existing operator workflows.
At the reviewed Audita revision `6ae1d7cd5f548b26de5787372d3f2249eaa4757d`,
[go.mod](../../go.mod) selects ConfigKit v0.4.2, PromptKit v0.11.2, and Go
1.25.5. ConfigKit already owns loading, presence, secret resolution, and
configuration inspection. Audita's `internal/core/config` supplies typed
settings, defaults, derived values, and domain validation; `internal/cli`
selects files, overlays, and explicit overrides. The
[configuration contract](../config.md) and [CLI contract](../cli.md) own the
implemented behavior.
The reviewed upstream release is
[ConfigKit v0.5.0](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.5.0/docs/releases/v0.5.0.md),
commit `dc09959cca4e105f49ec316c6d4ba585bd2340bd`. It adds layered underlays,
caller-owned filesystem sources, mapping sources, source resource contexts, and
built-in sibling inheritance. The Go minimum and YAML dependency do not change.
Ordinary `Load` remains available; adopting `LoadLayered` is optional.
This roadmap supersedes the completed original adoption plan at this path.
The [historical roadmap](https://gitea.maximumdirect.net/eric/audita/src/commit/6ae1d7cd5f548b26de5787372d3f2249eaa4757d/docs/roadmap/configkit.md)
records that earlier migration. Its coordinated breaking-refactor instructions
and release target do not govern this incremental upgrade.
## Target End State
- Audita uses the released ConfigKit v0.5.0 module, with no local replacement.
PromptKit stays at v0.11.2 throughout this adoption unit.
- Configuration retains the current file-selection, overlay, explicit-override,
resolution, and validation flow, subject to the reserved-key compatibility
impact described below. Retain the application schema version, CLI interface,
and main-file-relative resource rules defined in the current contracts.
- Application configuration can use ConfigKit's native sibling `extends`
relationships. Audita does not implement a second inheritance resolver,
special backend-only syntax, or an opt-in switch around the library feature.
- Inherited values participate in presence-aware defaults, domain validation,
secret resolution, and safe inspection just like other effective input.
In particular, inherited backend settings must not be overwritten merely
because they were not written directly on the child.
- Effective settings and explanations remain useful and secret-safe when
values are inherited. Preserve existing inspection fields and add compact,
value-free inheritance evidence from ConfigKit's metadata rather than
reconstructing provenance from YAML.
- Canonical documentation and a maintained example explain the adopted
inheritance behavior. Attribution identifies the exact new upstream source.
The upstream [configuration contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.5.0/docs/config.md#sibling-inheritance)
owns generic inheritance mechanics. The integration must account for three
consequences: `extends` is reserved automatically throughout input mappings;
relationships resolve after source precedence and before typed decoding; and
inherited zero, false, empty, or null values count as explicit input. An inherited
value still has to satisfy Audita's field-specific rules. Parent definitions
also undergo ordinary application validation; inheritance does not introduce
abstract, validation-exempt backend entries.
## Scope and Adoption Boundary
Keep the existing `Load` integration unless implementation reveals a concrete
need to change it. Source-backed defaults, additional operator underlay tiers,
imports, and source-relative reinterpretation of application paths are outside
this feature. Their availability upstream does not require expanding Audita's
configuration surface. Imports and secret-directory bootstrap retain their
current disabled state.
ConfigKit inheritance applies to Audita configuration in this step. PromptKit
profile formats, profile inheritance, engine construction, embedded prompts,
and backend catalogs remain governed by the existing PromptKit integration.
There is no application-owned translation of profile documents in this work.
This is an independent ConfigKit adoption ahead of the planned PromptKit
migration. A separate public release between the two units is optional.
## Acceptance Criteria
- The released ConfigKit v0.5.0 dependency and exact source attribution are
adopted; PromptKit remains at v0.11.2 with its existing catalogs.
- Native inheritance preserves effective endpoints, capacity, explicit zero
queue capacity, child overrides, and surviving credential references through
Audita's loading, resolution, and validation boundary.
- Selected overlays and explicit overrides retain their precedence; omitted
validation-role selection still derives from the final proposal selection.
- Null can remove a child's credential while surviving references on parents
and other unselected backends still follow the existing credential contract.
- Selected roles use inherited backend settings and share its configured
capacity under the existing PromptKit runtime contract.
- Effective settings remain redacted, and both CLI explanations and debug
configuration origins expose compact, value-free inheritance evidence while
retaining existing fields and application-derived explanations.
- A maintained complete example and canonical documentation describe native
inheritance, its field-validation implications, and the reserved-key
compatibility impact. Existing workflows and applicable offline checks pass.
## Completion and Release Treatment
Adoption is complete when the released dependency is pinned, existing workflows
pass, representative inheritance works through loading and runtime wiring,
inspection includes value-free inheritance evidence and remains secret-safe,
and the example, canonical docs, and attribution match the implementation. No
PromptKit migration or provider behavior change is required to close this unit.
Release classification remains provisional. A minor release would be appropriate
for a backward-compatible addition, but the newly reserved `extends` key can
invalidate currently valid application configuration. For example, Audita
currently permits a backend literally named `extends`; ConfigKit v0.5.0 treats
that mapping key as an inheritance directive rather than a backend ID. Do not
promise blanket compatibility or settle on a minor release until the final
compatibility review resolves this impact under the
[release policy](../policy/release.md). Describe any required migration in the
canonical documentation and release notes when the upgrade ships. Do not select
or publish a release as part of roadmap preparation. A later PromptKit
migration's profile-format compatibility decision belongs to that separate
feature.
## Selected Overlays for Testing
This heading preserves links from historical adoption documents. The original
[overlay plan](https://gitea.maximumdirect.net/eric/audita/src/commit/6ae1d7cd5f548b26de5787372d3f2249eaa4757d/docs/roadmap/configkit.md#selected-overlays-for-testing)
is historical; current overlay behavior belongs to [configuration](../config.md).
This upgrade preserves that workflow and adds native ConfigKit inheritance
without reviving the earlier combined migration plan.

22
docs/roadmap/future.md
View File

@@ -1,10 +1,10 @@
# Deferred Feature Work
**Last updated:** 2026-10-03
**Last updated:** 2026-10-11
**Status:** Deferred or exploratory work; not implemented or scheduled. These
entries preserve work beyond the completed resilience and span-deletion
features. Each entry states its intent; inclusion does not commit us to
entries preserve work beyond completed feature and library upgrades.
Each entry states its intent; inclusion does not commit us to
implementing every capability.
## Domain-Aware Response Recovery
@@ -78,3 +78,19 @@ semantics. It must address meaning preservation and the effects on segment
identity, timestamps, fixed chunks, subsequent stages, recombination, and output
consumers. Do not infer authorization to remove a segment from an empty string
or introduce segment-removal machinery as part of span-deletion consistency.
## Library Inspection and Configuration Comparison
ConfigKit and PromptKit provide effective-configuration comparison; PromptKit
also provides prompt/profile listings and contextual prompt requirement
inspection. Exposing these capabilities in Audita is deferred until a concrete
operator or development need arises. The dependency upgrade did not select new
inspection commands.
If a need emerges, define command ownership, selection syntax, report scope, and
disclosure before implementation. Reuse the libraries' public APIs and consider
shared CLI conventions alongside any separately selected CommandKit adoption.
Requirement discovery is advisory evidence rather than proof of execution
readiness; an empty configuration diff does not prove equivalent execution.
The library-upgrade review remains available in
[Git history](https://gitea.maximumdirect.net/eric/audita/src/commit/4c5536ab78c72dea58d03b3c51834138d429a59a/docs/roadmap/imports.md).

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.

258
docs/roadmap/imports.md
View File

@@ -1,258 +0,0 @@
# Library Updates: ConfigKit, ReleaseKit, and PromptKit
**Reviewed:** 2026-10-11.
**Status:** Dependency upgrades complete. Optional inspection APIs remain unused
until a concrete application need arises.
## Scope and Reviewed Baseline
Review the released library changes since Audita's current imports and identify
the work needed to adopt them. Audita's baseline is commit
`6debe7e`, with the versions declared in [go.mod](../../go.mod).
The local library checkouts were clean and matched the released source commits;
the remote annotated tags were checked against their peeled commits.
| Library | Reviewed baseline import | Adopted import | Full reviewed upstream commit |
| --- | --- | --- | --- |
| ConfigKit | v0.5.0 | v0.7.1 | `6fffde4af8f31f99d3ee295c426eb3234cb0fb77` |
| ReleaseKit | v0.3.0 | v0.4.1 | `2d5a8110c61e31daf8698766114ae305d0e0e469` |
| PromptKit | v0.12.0 | v0.14.0 | `143c6e9b3a675872117b0471e2ff8bcb25055a54` |
The review covers intervening releases, not just each latest patch. Evidence
includes release notes, consumer documentation, public API implementations,
Audita's integration code, and a disposable compatibility exercise using the
released modules. Public web rendering was unavailable; local tagged sources
and remote Git tag checks supplied the evidence.
## Target State and Recommendation
Upgrade all three libraries together to the versions above, retaining Audita's
current configuration format, CLI, processing, diagnostics, and release model.
No application-code migration was needed in the compatibility exercise.
ConfigKit and PromptKit improvements become available through existing calls;
new operator-facing discovery and comparison features remain separate choices.
All selected libraries declare Go 1.26.0. Audita already declares that minimum
and uses Go 1.26.8 for release validation, so this adoption requires no minimum,
CI image, or distributed Go-runtime notice change. PromptKit v0.14.0 requires
ConfigKit v0.7.1; both library module graphs also select ReleaseKit v0.4.1 as a
maintainer tool dependency. Go module selection therefore couples these updates,
even though ReleaseKit's orchestration is not part of their runtime imports.
Keep the ownership boundaries in the [architecture policy](../policy/architecture.md):
ConfigKit owns loading and provenance, PromptKit owns LLM execution and captured
definitions, ReleaseKit owns release mechanics, and Audita owns transcript
behavior and application meaning. This review does not select CommandKit
adoption or introduce new release gates.
## ConfigKit: New Capabilities and Adoption Work
### Changes Since v0.5.0
- **v0.6.0:** Reduces loading and inspection work through fewer path allocations,
combined metadata traversal, indexed resolution and sensitivity processing,
lightweight presence queries, and prepared immutable inspection lookups.
Existing composition, inheritance, presence/null, provenance, and secret
contracts remain unchanged. It raises the consumer minimum to Go 1.26.0 and
adopts ReleaseKit for its own publication.
- **v0.7.0:** Adds `configkit.Diff[T](left, right *Result[T])`, comparing frozen
effective inspection values from two successful loads. Results contain a
semantic `Path`, left/right `ValueSnapshot` values, and `HiddenChanged`.
Mappings compare recursively, sequences are atomic changed regions, and
presence distinguishes missing values from explicit null. Combined sensitivity
from both loads protects the paired snapshots, including historical and
dependency-derived sensitivity.
- **v0.7.1:** Updates the maintainer ReleaseKit dependency to v0.4.1. Runtime
behavior and public APIs are unchanged from v0.7.0.
References: [v0.6.0 notes](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.6.0/docs/releases/v0.6.0.md),
[v0.7.0 notes](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.7.0/docs/releases/v0.7.0.md),
[v0.7.1 notes](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.7.1/docs/releases/v0.7.1.md),
and [comparison guidance](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.7.1/docs/consumers/README.md#effective-configuration-diffs).
### Work Needed
The dependency update needs module/checksum and attribution changes. Existing
`internal/core/config` callers need no signature or configuration migration.
Retain coverage for application resolution, explicit CLI overrides, overlays,
inheritance, provenance, and redaction; these are the boundaries affected by
upstream internal optimizations. No fixed performance gain is promised or
required for adoption.
If configuration comparison is selected later, load two complete selections
through Audita's normal application definition and call the public diff API.
Audita would own selection syntax and presentation. Use presence and
`HiddenChanged` directly rather than interpreting redaction-marker strings.
Do not add separately rendered full configurations as purportedly cross-protected
context: protection applies to the returned changed regions. Reference names,
not resolved credential bytes, participate in typed secret-reference comparison.
Equal values with different provenance do not produce differences; later
mutations of `Result.Config` are outside the captured comparison.
## ReleaseKit: New Capabilities and Adoption Work
### Changes Since v0.3.0
- **v0.4.0:** Adds individual-module releases with `ModuleDir`, module identity,
complete module-prefixed tags, module-local validation/builds, separate Gitea
pages, and mapped multi-module launchers. Root-module defaults retain ordinary
tags and note locations.
- Adds explicit shared-file selection for optional file checks, module-bound
versioned build receipts, expected-module checks, and `ci-deliver --prepared`
for an already verified detached checkout.
- Improves checkout-root and symlink resolution, offline committed-source
inspection, available build-failure evidence, and reuse of Go discovery and
asset verification. Independent nested modules are excluded from automatic
parent-module file inspection; product tests can still use nested fixtures.
- Introduces an API/receipt cutover: `TaggedCheckoutRequest.Version` becomes
`Tag`; `PrepareBuildDependencies` takes `DependencyPreparationRequest`; old
prebuilt receipts need regeneration with the new builder.
- **v0.4.1:** Fixes concurrency in delivery test fixtures. Production behavior
and public APIs are unchanged from v0.4.0.
References: [v0.4.0 notes and migration guidance](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.0/docs/releases/v0.4.0.md),
[v0.4.1 notes](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.1/docs/releases/v0.4.1.md),
and [current delivery contract](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.1/docs/cli.md).
### Work Needed
Audita uses the Go tool CLI and lightweight `buildinfo` facade. It has no callers
of the changed preparation APIs and does not need module maps, prefixed tags,
new shared-file settings, or a multi-module layout. Its root-module
[release profile](../../releasekit.json) and [launcher](../../scripts/release.sh)
can retain their current configuration. Runtime version access is unchanged.
Update the selected dependency, checksums, attribution, and v0.3.0-pinned
consumer links in [the release runbook](../release.md). Recommend adding
`--prepared` to [.woodpecker/release.yml](../../.woodpecker/release.yml): bootstrap
already verifies and checks out the event tag before reading module metadata,
so the new mode avoids repeating fetch/checkout while retaining ReleaseKit's
verification. Update the runbook and focused workflow coverage for that deliberate
change. Keeping the current default preparation mode is also supported and is
not an adoption blocker.
Keep historical delivery retries paired with their tagged tool selection and
workflow. Existing v0.3.0 retained artifacts should use that version's delivery
path; regenerate receipts with the new builder when intentionally using v0.4.1
prebuilt delivery. Do not imply that historical receipts are portable across the
cutover or replace already published contents.
Use existing launcher/profile/CI tests, verify the two production builds and
injected version behavior during implementation, and keep source publication
separate from asynchronous delivery. This upgrade requires no real tag push,
hosted upload, CI wait, expanded platform matrix, or new approval gate.
## PromptKit: New Capabilities and Adoption Work
### Changes Since v0.12.0
- **v0.13.0:** Adds `Engine.InspectRequirements` for recognizable input and
caller-variable dependencies before artifacts exist. It distinguishes
required, conditional, and optional dependencies and reports incomplete
discovery with structured issues. It analyzes selected prompt/template and
caller context without preparing artifacts or executing a model request.
- Adds `Engine.ListProfiles` and `Engine.ListPrompts`, exposing lexically ordered,
caller-owned effective profile IDs and exact prompt ID/version pairs from the
captured engine configuration, without provider calls.
- Reduces avoidable response/rendering copies, repeated parameter encoding,
artifact-file allocation, prepared-snapshot copying, and inspection lookup
work. ConfigKit v0.6.0 improves engine construction and configuration inspection.
The Go minimum becomes 1.26.0, and maintainer publication adopts ReleaseKit.
- **v0.14.0:** Adds `ConfigurationInspection.Diff`, delegating paired captured
configuration comparison to ConfigKit. It also selects ConfigKit v0.7.1 and
ReleaseKit v0.4.1.
References: [v0.13.0 notes](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.13.0/docs/releases/v0.13.0.md),
[v0.14.0 notes](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.14.0/docs/releases/v0.14.0.md),
and [consumer inspection guidance](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.14.0/docs/consumers/pkg-promptkit.md).
### Work Needed
Existing runtime construction, keyed prompt/profile assets, schema preparation,
execution, retry/repair, and backend admission calls remain supported. Upgrade
the module and checksums, update attribution and affected pinned integration
references, and reuse Audita's offline adapter/runtime and subprocess tests.
Preserve its selected-profile completeness checks, direct backend credentials,
capacity sharing, schema/domain validation, partial success, and redaction.
No prompt rewrite, profile conversion, or new validation gate is needed.
Optional adoption opportunities are:
- **Definition discovery:** Use listing APIs for operator discovery or better
unknown-profile diagnostics. Keep returned membership separate from readiness
to execute. Define the user surface before adding CLI commands; coordinate
shared inspection syntax with any separately selected CommandKit adoption.
- **Prompt requirement analysis:** Use `InspectRequirements` as a development
diagnostic for embedded or operator-overridden prompts. Partial discovery is
useful evidence, not proof of a broken prompt. Do not turn incomplete analysis
into a startup prohibition or treat complete discovery as execution validation.
Existing `InspectPrompt`, preparation, schemas, and domain checks retain their
different roles. This API is unrelated to guided response recovery.
- **Engine configuration comparison:** Compare two successful engines through
their captured configuration inspections. A future Audita comparison feature
should distinguish application settings from the PromptKit scope; engine
inspection alone does not represent every application setting or execution
effect. An empty diff does not prove identical behavior: referenced file
contents, resolved credentials, preparation, and request overrides are outside
the comparison. Ordinary public values may still be sensitive application data.
These APIs are useful foundations, but exposing them is additional product work,
not necessary to obtain the dependency updates and efficiency improvements.
## Common Adoption Work and Verification
Update `go.mod` and `go.sum` together, retaining the registered ReleaseKit tool.
The reviewed module graphs retain existing catalog versions, YAML dependency,
and other selected dependency versions; the disposable tidy changed only the
three direct versions in `go.mod`.
Update the three entries in [attribution](../oss/attribution.md) to the exact
reviewed commits under the [OSS policy](../policy/oss.md). Their root `COPYRIGHT`
and `LICENSE` files are unchanged relative to Audita's current selected versions;
retain existing LGPL/GPL texts. Check actual resulting dependency selection
before finalizing notices. Audita's application grant remains unchanged.
Recommend one bounded dependency-and-documentation update, with the small CI
prepared-mode adjustment if selected. Do not introduce compatibility shims or
implement new comparison/discovery commands merely to exercise optional APIs.
Any selected user-facing feature should get its own defined scope and roadmap.
The review used a temporary archive of Audita's baseline, selected the actual
released modules with `go get`, and ran `go mod tidy`. On Go 1.26.8 Linux amd64:
- The complete Audita suite passed with `GOWORK=off`, `GOTOOLCHAIN=local`,
`GOPROXY=off`, and `GOSUMDB=off` after dependency preparation.
- Both Linux targets built, and the native executable's version command ran.
- The ReleaseKit v0.4.1 CLI built and displayed `ci-deliver` help.
- Local, inheritance, service, and service-testing-overlay configuration examples
validated with a synthetic credential and no inference calls.
This evidence supports compatibility; it does not certify real source
publication, version injection through the new release builder, hosted delivery,
performance gains, or operator-facing optional features. Actual implementation
should validate its final changed candidate and selected CI behavior. Live
delivery remains separate from release completion under the existing policy.
## Selected Scope and Completion Record
The user selected a simple version upgrade, deferring inspection API exposure
until a concrete need arises. ConfigKit v0.7.1, ReleaseKit v0.4.1, and PromptKit
v0.14.0 are adopted together. The dependency/checksum changes retain Go 1.26.0,
the existing catalogs, and the current application APIs and configuration format.
Attribution and canonical upstream references now identify the selected releases.
CI delivery uses `--prepared`, with the runbook and existing workflow test updated.
Implementation validation on Go 1.26.8 Linux amd64 passed:
- The complete offline `go test -count=1 ./...` suite.
- The actual module-selected ReleaseKit builder for Linux amd64 and arm64, using
the disposable build identifier `v0.0.0`; its native injected-version check
passed and produced `audita v0.0.0`.
- Local, inheritance, service, and service-testing-overlay configuration examples,
using a synthetic service credential.
- Selected source revisions, unchanged upstream grants/license texts, and updated
upstream file-link destinations.
Build artifacts remained outside the repository. No source tag, hosted delivery,
or inference call was performed. Live CI delivery remains unobserved and separate
from this completed upgrade and source-release completion.

276
docs/roadmap/promptkit.md
View File

@@ -1,276 +0,0 @@
# PromptKit v0.12.0 Adoption Roadmap
**Last updated:** 2026-10-04
**Status:** Complete. The implementation plan records the ordered work and
verification details.
## Purpose and Baseline
Adopt PromptKit v0.12.0 now that the independent
[ConfigKit v0.5.0 upgrade](configkit.md) is complete. Align Audita with the
libraries' native configuration model while retaining Audita's domain rules,
application-owned backend settings, and resilient processing workflow.
At reviewed Audita revision `8cba751835ba9faad340e933a3cfbb59c03924fd`,
[go.mod](../../go.mod) selects ConfigKit v0.5.0 and PromptKit v0.11.2, with
OpenRouter and Rakestrawhome `/v2` catalogs at `v2.20260926.0`. Go 1.25.5
remains the application minimum. The implemented contracts belong to
[configuration](../config.md), the
[LLM integration](../integrations/openai-compatible-llm.md), and the
[LLM runtime](../internal/llm-runtime.md).
`internal/framework/llm.NewRuntime` currently assembles one engine using the
old prompt/profile filesystem options and programmatic backend registration.
Audita embeds seven prompt definitions and separate response schemas. Operators
select proposal and validation profiles from `profiles_dir`; the effective
backend must be registered in application configuration, its endpoint must
match, and its credential comes from Audita's ConfigKit-resolved settings.
Successful profile reads are recorded to protect those sources from output
collisions. Both roles share the same engine's backend admission controls.
The reviewed upstream release is
[PromptKit v0.12.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/releases/v0.12.0.md),
commit `4b8169da286917fde7875425bb32b799b12c6af3`. It depends on ConfigKit
v0.5.0 and both maintained `/v3` catalog modules at `v3.20260930.0`. This is an
intentional incompatible pre-1.0 minor release: it replaces construction and
configuration APIs, rather than simply updating provider data. PromptKit's
[format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md)
and [consumer migration guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md#migrate-from-the-previous-configuration-api)
own the upstream details.
## Target End State
- Audita imports released PromptKit v0.12.0 and its `/v3` catalogs, retaining
ConfigKit v0.5.0 and using no local dependency replacement.
- The runtime uses `Config.Sources` and native ConfigKit source groups.
PromptKit owns composition, inheritance, presence, final-definition
validation, prompt capture, and execution. Audita does not translate old
profiles or implement a second YAML loader or inheritance resolver.
- Embedded prompts and maintained operator profiles use keyed `prompts` and
`profiles` mappings. Existing prompt IDs, versions, role selections,
instructions, and response-schema associations remain the adoption baseline.
The application configuration schema, overlay selection, CLI interface, and
main-file-relative `profiles_dir` resolution remain in place.
- Native profile `extends`, field-presence semantics, and source-relative
resource rules apply. Documents can contain multiple definitions, and IDs
come from mapping keys rather than filenames. The existing `profiles_dir`
accepts native unified PromptKit documents containing profiles, backends,
and prompts, including intentional operator prompt overrides.
- Application backend endpoints, configured concurrency and queue capacity,
and credential ownership remain authoritative for selected roles. Preserve
the existing profile-selection and prepared-target checks; do not introduce
a second admission controller or implicit provider credential lookup.
- A runtime uses one captured configuration snapshot for both roles. Each CLI
invocation constructs a new engine; hot reload is not part of this feature.
Existing inspection remains offline and safe, and consumed host sources
remain protected from output collisions.
- PromptKit retains responsibility for transport retries, schema repair,
observation, and prepared execution. Preserve Audita's configured retry and
repair budgets, operation deadlines, cancellation, partial-success behavior,
error/recovery reporting, and debug selection.
## Configuration Assembly and Ownership
Replace removed `WithPromptFS`, `WithProfileFS`, and `WithBackend` usage with
the released source API. Discover embedded YAML through `FilesystemInputs` and
operator YAML through `DirectoryInputs`, with explicit caller tiers. Keep the
retained schema filesystem integration and HTTP client configuration.
Use the helpers' default-disabled imports; this adoption does not require new
application source-selection flags or operator underlay tiers.
PromptKit supplies catalog definitions first and its own defaults next. Caller
tiers then overlay in their supplied order, followed by an optional highest
priority main input. Files within one directory group compose strictly;
alphabetical filenames do not establish override precedence. Use separate
tiers for genuine priority differences rather than manufacturing file-order
semantics.
Represent application backend settings as a final programmatic source, using
`BackendSource` or ConfigKit mappings where explicit null is needed. Preserve
configured zero queue capacity as an explicit value. Suppress backend-derived
credential environment lookup explicitly where catalog layering would otherwise
introduce it; omission alone can retain a lower-tier value. Continue detecting
competing effective profile credential lookups rather than silently clearing
operator profile fields. A missing backend credential remains valid for an
unauthenticated local service unless the selected profile requires a key.
Catalog backend IDs are no longer reserved upstream. Audita should not invent a
new reservation rule. Catalog selection alone must not bypass application
registration, endpoint, capacity, or credential requirements. Catalog profile
contents may evolve; this upgrade does not promise fixed model choices or live
provider availability.
The accepted caller order is embedded Audita prompts, operator definitions,
then application backend settings. The existing `profiles_dir` accepts native
unified PromptKit documents containing profiles, backends, and prompts. Keep
the name and path setting for continuity, and document its broader accepted
content. This follows the upstream source API without a parallel parser or
top-level filtering. Profiles, provider defaults, and intentional prompt
overrides use the same native composition model.
Audita continues to ship its domain prompts, enforce its selected-backend
requirements, and supply its per-call schemas. Operator prompt overrides are
an accepted capability of this adoption; documentation, source accounting,
and focused behavioral coverage should reflect them.
## Work Required
### Runtime Construction and Source Accounting
Migrate `internal/framework/llm/runtime.go` to layered construction and retain
the role-bound adapter boundary. Review startup inspection and failure
classification because upstream now validates all final definitions, including
unused ones, during engine construction. Distinguish invalid operator inputs
from broken embedded assets under the existing
[CLI exit contract](../cli.md); do not treat every construction failure as an
operator error merely because validation moved earlier.
Upstream permits partial profiles and defers endpoint/model completeness until
request overrides are applied. Audita supplies no model override, so explicitly
validate that both selected role profiles have a nonblank model and a complete
effective endpoint during offline configuration validation and runtime setup.
Retain the application-backend, endpoint-match, and credential checks. Do not
rely on engine construction or profile inspection alone to establish selected
profile completeness. Unselected partial profiles remain permitted if they
satisfy upstream definition validation; they need not be runnable.
Adapt source accounting to the new discovery/capture boundary. The existing
recording filesystem wrapper may be replaceable with discovered inputs or
upstream source metadata. Protect the host sources actually consumed by the
runtime, including inherited and differently named definitions, without
guessing filenames from selected profile IDs. Account for consumed operator
message files as well. Keep this proportionate to the existing collision
contract; do not add filesystem concurrency or power-loss guarantees.
Keep the existing safe effective-profile summaries and application explanations.
Use upstream metadata where useful, but do not expose the full
`InspectConfiguration` snapshot as ordinary CLI or report output: prompt text
and arbitrary provider fields are outside those summaries' current scope.
### Prompt Assets, Profiles, and Presence Semantics
Move each of the seven files in `internal/prompts/assets/prompts` to the keyed
prompt/version format. Keep the shared instruction fragments and the complete
per-call output contracts owned by Audita. This migration does not authorize
another prompt-quality rewrite or changes to domain validators.
The adapter supplies `HardeningPolicy`, `ProposalContract`, and
`ValidationContract` as template variables. Embedded prompts retain their
references to the applicable variables. Operator message overrides control
whether those variables are rendered; supplying a variable does not inject its
text into a template that omits it. Preserve this native override behavior and
document the distinction. Per-call schemas and domain validation remain enforced
regardless of those references. Unconditional shared-instruction injection is
outside this adoption.
Convert the six maintained profiles in `examples/profiles` and test-generated
profile/prompt fixtures to the new format. Convert any old `base_profile`
usage to `extends`, and remove embedded identities. Migrate tests that construct
engines using removed options or old `Profile`/`Backend` values.
Reorganize the maintained profiles into separately selected local and service
directory roots. The current shared directory includes profiles referring to
backends absent from each example's application configuration; eager validation
would reject those unselected definitions after a format-only conversion.
Update `profiles_dir` in `examples/minimal-config.yml`,
`examples/production-config.yml`, and `examples/configkit-inheritance.yml` to
select the appropriate root. Keep the service testing profiles in the service
root so the testing overlay remains usable. Discovery is recursive: placing
both groups beneath a common selected root does not isolate them. Update example
links and validation recipes to match the final layout.
Review presence deliberately rather than mechanically preserving old serialized
values. In particular, explicit zero temperature, top-p, or max-tokens now means
an outbound zero; zero timeout disables PromptKit's generation deadline while
Audita's outer operation deadline still applies. Omission, blank values, and
null have field-specific meanings. Empty provider maps do not erase inherited
entries, and changing model/backend does not erase unrelated explicit settings.
Use the native meanings without a compatibility shim. Retaining the examples'
literal `temperature: 0` as an explicit provider setting is recommended; explain
that omitting the field requests an unspecified value, and null suppresses an
inherited control. Do not automatically turn every existing zero into omission
or every omission into a zero. Demonstrate representative profile inheritance
without requiring every maintained example to use it.
### Documentation, Migration, and Attribution
Update the profile section of `docs/config.md` and maintained examples when the
implementation lands. Explain the broader accepted content of `profiles_dir`,
operator prompt overrides, their precedence and optional use of shared instruction
variables, keyed identities, composition versus precedence, profile inheritance,
presence, eager final-definition validation, selected-root errors, and captured
configuration. Link to the pinned
upstream reference for generic field semantics rather than reproducing its
entire contract.
Include operator migration guidance for old profile documents and behaviorally
significant zeros/nulls. This is a deliberate format migration, not an automatic
upgrade of existing installation files. Preserve supported application overlays,
including the cheaper/faster testing-profile workflow.
Update the pinned consumer link in `docs/integrations/openai-compatible-llm.md`,
construction/source-accounting descriptions in `docs/internal/llm-runtime.md`,
and asset-format guidance in `docs/internal/prompts.md`. Update other affected
references only where implemented behavior changes.
Update `go.mod`, `go.sum`, and `docs/oss/attribution.md` for PromptKit and the two
catalog modules. Verify exact selected source revisions and upstream notices
under the [OSS policy](../policy/oss.md); retain the applicable LGPL/GPL and MIT
texts rather than duplicating unchanged license documents. Dependency adoption
does not change Audita's application license.
Plan this adoption for an Audita major release under the
[release policy](../policy/release.md#versioning-and-compatibility). The public
profile format changes incompatibly and no compatibility loader is planned;
PromptKit's own pre-1.0 minor version does not change Audita's classification.
The exact version and publication timing remain deferred to release preparation.
## Verification and Completion
Use existing offline tests as the starting point. Update fixtures intentionally,
and add focused behavioral coverage where the source migration creates a
distinct risk. Completion means:
- The released dependency set builds and the complete Audita test suite passes.
- All registered embedded prompts load and render from keyed assets, retaining
their applicable shared-instruction references and established per-call schemas.
- Offline configuration validation rejects incomplete selected profiles, including
a missing or blank model, while accepting valid unselected partial profiles.
- Selected roles use final application backend settings and direct resolved
credentials; both roles still share configured capacity, including explicit
zero queue capacity. Catalog layering does not introduce a competing lookup.
- Representative keyed profiles, native inheritance, and explicit presence work
through the real runtime. Directory conflicts and invalid final definitions
produce useful startup errors without filename-derived identity assumptions.
- Operator prompt and backend contributions follow the accepted source order;
prompt overrides render, including when their messages omit shared-instruction
variables, while Audita retains its per-call schemas, domain validation, and
authoritative application backend settings.
- Source collision protection, safe inspection, and operator-versus-asset error
classification remain effective at the changed construction boundary.
- Representative prepared execution, schema repair, transient retry, and
partial-success tests retain their existing behavior. Reuse adequate coverage
rather than duplicating PromptKit's complete upstream test matrix.
- Local, service, testing-overlay, and ConfigKit inheritance examples validate
offline using their separately selected profile roots. Canonical documentation
describes the migrated format, shared-instruction behavior, and major-release
migration; attribution identifies the selected library sources accurately.
No live provider calls, new release gates, or CI-success dependency are needed
to establish adoption. Guided domain recovery and the other work recorded in
[future.md](future.md) remain separate features. Do not expand this upgrade into
new report formats, pipeline scheduling, or general configuration-inspection
commands. The [historical implementation plan](https://gitea.maximumdirect.net/eric/audita/src/commit/418da456d75a68d3bb5a43ab823c5b2b434b90cc/docs/roadmap/implementation.md)
records that work's execution steps and verification.
## Completion Record
Implementation code is recorded through revision `5525fe8`; documentation was
updated in `9bcf183`, and the final roadmap closure is documentation-only. At
`9bcf183`, `go build -o ./bin/audita ./cmd/audita`, `go test ./...`, all six
offline maintained-example commands in the implementation plan, `go mod
verify`, and `git diff --check` passed. The selected dependency graph and
commit-pinned attribution match PromptKit v0.12.0 and both `/v3` catalogs at
`v3.20260930.0`.

231
docs/roadmap/releasekit.md
View File

@@ -1,231 +0,0 @@
# ReleaseKit v0.3.0 Upgrade Roadmap
**Last updated:** 2026-10-08
**Status:** Implementation complete; first upgraded release and live delivery
observation pending.
## Purpose
Upgrade Audita directly from ReleaseKit v0.1.0 to v0.3.0, continuing the decision
in [ADR 0001](../adr/0001-releasekit.md). 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 records the
upgrade's target state and completed scope. The upgrade was implemented in one
pass without a separate staged plan.
## 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](remediation.md) are resolved. They are
historical context, not additional work for this upgrade.
Since that baseline, Audita has adopted release policy 1.6, registered and
upgraded the ReleaseKit tool to v0.3.0, simplified the local wrapper, and
updated CI and notices. The current Go minimum is 1.26.0; the selected release
toolchain is 1.26.8. The scope below records the requirements fulfilled by this
implementation.
## Selected Upstream Revisions
Adopt ReleaseKit **v0.3.0**, commit
`e43df4416e0ed987349b2ea04a2c68c25e552772`.
Its [release note](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.3.0/docs/releases/v0.3.0.md)
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](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/docs/adoption.md).
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.
## Implemented Scope
### 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.
## Implementation Completion
Completed with Go 1.26.8. The readonly offline full suite passed. The real local
wrapper selected ReleaseKit v0.3.0; disposable Go-tool fixtures verified native
argument boundaries, statuses 0/2/3, and unchanged module files. The CI workflow
matches the v0.3.0 maintained template with Audita's existing secret mapping.
The real ReleaseKit builder produced both required Linux artifacts using the
test identifier v0.0.0, passed its native version smoke check, and emitted
matching artifact digests in its build receipt. Temporary output was removed.
The new release-tool dependencies are absent from Audita's runtime dependency
list. ReleaseKit and Go runtime/vendor attribution identify their selected
source revisions, with existing applicable license texts reused.
This verification built modified local source and did not claim a clean,
published release candidate. Release preparation will validate its final
committed candidate through the ordinary publication command. No tags, source
pushes, hosted uploads, or LLM calls were made during implementation; live
artifact delivery remains a separate observation for the next release.

151
docs/roadmap/remediation.md
View File

@@ -1,151 +0,0 @@
# ReleaseKit Adoption Review: Findings and Recommended Changes
**Reviewed:** 2026-10-07, source commit
`3c405f0524ec6c098d00d4e371abbace7648d446`.
**Scope:** ReleaseKit adoption commits after `721365e`, including CLI version
reporting, local release wiring, CI delivery, tests, and documentation.
**Status:** R1–R3 addressed. The findings below describe the reviewed
baseline; completed work is recorded under Resolution Record.
## Architecture Assessment
The core adoption matches [ADR 0001](../adr/0001-releasekit.md) and the
[feature roadmap](releasekit.md). Audita supplies product facts in
`releasekit.json`, a thin executable wrapper, a configuration-free version
command using the public `buildinfo` accessor, and a pinned Woodpecker
`ci-deliver` invocation. ReleaseKit owns candidate validation, annotated-tag
publication, version injection, Linux builds, checksums, and hosted delivery.
The custom builder and local publication mechanics have been retired.
No core ownership or delivery-target gap was found. The findings concern one
CLI behavior defect, an ineffective target-selection assertion, and unnecessary
test restrictions. Main-first publication and the native-host version smoke
check are deliberately accepted workflow changes, not accidental strengthening.
## R1 — P2: Simplify Version Help Handling and Correct Its Streams
**Category:** CLI behavior defect and unnecessary argument restriction.
**Evidence:** [runVersion](../../internal/cli/run.go) handles standalone `-h`
and `--help` before parsing, then rejects either spelling when combined with
other arguments. This adds a special prohibition beyond the requested usual
help behavior. For example, `audita version -h --help` returns status `2`.
The parser's help path also writes usage twice: `FlagSet.Usage` writes to stderr,
and the `flag.ErrHelp` branch writes it again to stdout. Reproduced with
`audita version --h` and `audita version -help`: both return status `0` and emit
the same usage on both streams. The standard library recognizes these help
spellings, but the preliminary special cases do not handle them.
**Recommended change:** Use one standard parsing path. Let help short-circuit
according to the parser's ordinary behavior, and emit successful help once to
stdout with empty stderr. Keep non-help unknown flags and unexpected positional
arguments as usage errors. Remove the bespoke mixed-help prohibition and the
test that promotes it into a requirement. Update the CLI wording if needed so
it describes ordinary help handling without promising validation of trailing
arguments after a help request.
**Acceptance:** Normal version output remains configuration-free and unchanged.
Representative parser help paths produce status `0`, stdout usage, and empty
stderr. Non-help invalid invocations still return status `2`. Tests protect
streams and meaningful behavior without establishing a new argument-combination
policy or a comprehensive help-alias contract.
## R2 — P2: Make the Delivery-Target Check Compare Actual Membership
**Category:** Test correctness gap.
**Evidence:** [sameMembers](../../scripts/release_test.go) compares slice
lengths and checks only that each observed item belongs to the expected slice.
It never checks that every required target is present. Calling the actual helper
with `got = [linux/amd64, linux/amd64]` and
`want = [linux/amd64, linux/arm64]` returns true. A profile missing arm64 can
therefore pass the selected-target assertion. ReleaseKit deduplicates repeated
targets, so that configuration would build only amd64.
The reverse problem also occurs: a list containing both required targets plus
a repeated amd64 entry returns false despite having the same effective target
membership. The current committed profile is correct; the defect is in its
regression protection.
**Recommended change:** Compare the sets of configured and required targets,
including coverage of every required member and rejection of an unintended
member. Reuse straightforward standard-library data structures. Duplicate
normalization already belongs to ReleaseKit; Audita needs no duplicate ban or
order requirement.
**Acceptance:** A repeated single target cannot conceal an omitted production
target. Either omitted required target and an additional unintended target fail
the profile check. Reordered or repeated entries with the same effective target
set remain equivalent. Focused coverage catches the demonstrated false positive.
## R3 — P3: Remove Incidental Wiring-Test Requirements
**Category:** Tests strengthen representation choices into contracts.
**Evidence:** [release wrapper/profile tests](../../scripts/release_test.go)
require the exact output argument spelling `-o ./bin/releasekit` and reject the
presence of a `checks` key regardless of its value. In disposable copies of the
tests, changing the output path to the equivalent `bin/releasekit` fails the
wrapper assertion even though execution still reaches the intended tool.
Adding `"checks": []` fails the profile assertion despite configuring no
additional commands.
The accepted requirements concern the executable destination, native argument
and status forwarding, and avoiding redundant additional checks. They do not
require one path spelling or one serialization of an empty list. The plan's
instruction to omit `checks` selects an initial file representation rather than
an enduring prohibition on equivalent configuration.
**Recommended change:** Check the resolved output destination and observed
wrapper behavior instead of the literal relative-path spelling. Check that the
effective additional-check list is empty, accepting omission or an empty list.
Keep the existing product, target, destination, argument-boundary, failure, and
exit-status protection. Simplify fixture helpers where that reduces maintenance
without adding another parser or test framework.
**Acceptance:** The two demonstrated equivalent edits preserve passing wiring
tests, while a wrong executable destination, changed product facts, nonempty
additional checks, lost argument boundaries, or lost tool status still fail.
The tests remain offline and do not duplicate ReleaseKit's release-mechanics
matrix.
## Review Verification and Limits
- `go test ./...` passed on the reviewed source.
- A normal application build succeeded. Direct executable invocations reproduced
the version-help stream defect and mixed-help rejection.
- The actual membership helper reproduced the missing-target false positive.
Disposable test copies reproduced both equivalent-configuration failures;
the repository's code and tests were left unchanged.
- The real ReleaseKit builder produced both configured Linux artifacts with
build-test identifier `v0.0.0` and passed its injected-version smoke check.
This used the available Go 1.26.8 Linux amd64 toolchain; CI remains configured
for Go 1.25.5. Temporary build artifacts were removed.
- Module selection, source attribution, product profile, secret mapping, and
CI command match the intended integration. Live Woodpecker/Gitea delivery
remains unobserved, as already recorded in the feature roadmap; it is separate
deployment work rather than an implementation finding or source-release gate.
- No tags, pushes, hosted uploads, or LLM calls were made. Remediation should
remain bounded to the findings above and add no new release gates.
## Resolution Record
- **R1:** The version command now uses one standard flag-parsing path. Successful
help is written once to stdout, with no stderr usage, and help can short-circuit
trailing arguments. Non-help usage errors retain status `2`. Regression tests
reproduced both defects before the fix; `go test ./internal/cli ./cmd/audita`
passed afterward. The CLI contract reflects ordinary help behavior.
- **R2:** Delivery targets are compared as sets using the standard library.
Regression cases reject either missing Linux target concealed by duplicates
and an unintended target, while accepting equivalent reordered/repeated lists.
The cases reproduced the faulty membership behavior before the fix;
`go test ./scripts` passed afterward.
- **R3:** Wrapper coverage now checks the executable's actual destination, and
profile coverage checks the effective additional-check list. Equivalent output
paths and an explicit empty list are accepted. Fixture helpers use standard
library operations where appropriate. Disposable mutation checks accepted
`-o bin/releasekit`, `-o=bin/releasekit`, and `"checks": []`, while detecting a
wrong executable destination, changed product, nonempty checks, lost argument
boundaries, and lost tool status. The complete `go test ./...` suite passed
with all three remediations in place. No new release gates were added.