diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md deleted file mode 100644 index fa3a92f..0000000 --- a/docs/roadmap/configkit.md +++ /dev/null @@ -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. diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index 9cc7097..8e9d6bd 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -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). diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md deleted file mode 100644 index 42a2fb9..0000000 --- a/docs/roadmap/implementation.md +++ /dev/null @@ -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. diff --git a/docs/roadmap/imports.md b/docs/roadmap/imports.md deleted file mode 100644 index 5c5abc3..0000000 --- a/docs/roadmap/imports.md +++ /dev/null @@ -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. diff --git a/docs/roadmap/promptkit.md b/docs/roadmap/promptkit.md deleted file mode 100644 index 0e0a497..0000000 --- a/docs/roadmap/promptkit.md +++ /dev/null @@ -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`. diff --git a/docs/roadmap/releasekit.md b/docs/roadmap/releasekit.md deleted file mode 100644 index a5bbba7..0000000 --- a/docs/roadmap/releasekit.md +++ /dev/null @@ -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. diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md deleted file mode 100644 index dcbf03a..0000000 --- a/docs/roadmap/remediation.md +++ /dev/null @@ -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.