diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md index bd96a90..c29309e 100644 --- a/docs/roadmap/configkit.md +++ b/docs/roadmap/configkit.md @@ -1,171 +1,190 @@ -# ConfigKit Adoption Roadmap +# ConfigKit v0.5.0 Adoption Roadmap -**Last updated:** 2026-09-24 +**Last updated:** 2026-10-03 -**Status:** Production implementation complete. The selected configuration and -overlay model is implemented; [implementation evidence](https://gitea.maximumdirect.net/eric/audita/src/commit/cb405f6/docs/roadmap/implementation.md) -records verification. No release has been published. +**Status:** Planned; implementation has not begun. The dependency-only review +passed Audita's existing offline test suite in a disposable checkout. That is +baseline compatibility evidence, not completion of the feature work below. -## Purpose and Direction +## Purpose and Baseline -Adopt ConfigKit to harmonize Audita's configuration policy with the other -applications in the suite. Consistent configuration conventions are the primary -benefit; reducing application-owned configuration infrastructure is a secondary -benefit and a useful measure of integration quality. +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. -This is an intentional breaking migration. There is no goal of backward -compatibility with existing installations, configuration files, CLI flags, -environment variables, or configuration-inspection output. Provide a migration -guide instead of legacy loaders, aliases, dual operating modes, or an ongoing -compatibility layer. Retain existing syntax only when it independently suits the -new model, not because compatibility requires it. +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 initial review and prototype used ConfigKit v0.3.1, then verified v0.4.0 -selected overlays. Those findings remain historical; the prototype was removed -after production integration. The application depends on a versioned module, -without a sibling checkout or local module replacement. +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. -The shared boundary/prototype unit is complete. Its [selected contract, inventory, -and evidence](library-boundary-findings.md) define the detailed target alongside -this roadmap. Production configuration migration is complete. +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 -- ConfigKit owns strict YAML loading, input presence, default application, explicit - override mechanics, recorded resolution, secret references, and safe inspection. -- Audita owns its configuration types, field meanings, defaults, schema-version - policy, file selection, CLI parsing, domain validation, and runtime initialization. -- Adopt ConfigKit's precedence and validation lifecycle rather than reproduce - Audita's current per-layer validation and environment-overlay behavior. -- General configuration environment overrides are retired. Credentials use typed - environment-name secret references; supplied references must resolve according - to ConfigKit's contract. File selection follows the application-owned - discovery rules in the selected boundary. -- Standardize duration representations, explicit empty/null/zero handling, and - inheritance on the shared conventions. Express genuine Audita domain rules - through the supported resolution and validation APIs. -- Retained domain-setting flags and proposal/validation profile flags become - explicit ConfigKit overrides according to the migration inventory. Remove old - provider/key/retry/concurrency flags and aliases. Credentials use secret references. -- Use ConfigKit's redacted effective output and provide source/explanation access - through the selected views below. Legacy JSON inspection is replaced. - Diagnostic configuration snapshots use the same new model. -- Delete superseded loading and override machinery. Do not hide the old model - behind adapters that defeat the adoption's consistency benefit. +- Audita uses the released ConfigKit v0.5.0 module, with no local replacement. + PromptKit stays at v0.11.2 throughout this adoption unit. +- Existing configurations continue through the current file-selection, + overlay, explicit-override, resolution, and validation flow. 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 the existing Audita-owned inspection formats; + use 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. -Keep Audita's domain capabilities, such as ordered and repeated correction modules, -expressible in the new model. Their existing configuration spelling is not binding. -Transcript/glossary formats, processing algorithms, and output schemas are outside -this migration unless later planning identifies a concrete dependency or an -explicitly coordinated change. +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 Sequencing + +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. + +Complete and validate ConfigKit adoption before migrating PromptKit. PromptKit +v0.12.0 itself requires ConfigKit v0.5.0; this sequence isolates the generic +configuration change from the later API and profile-format migration. Each +completed adoption unit should build and pass its applicable checks. A separate +public release between the two units is optional, not a prerequisite. + +## Work Plan + +### 1. Upgrade the Dependency + +Update `go.mod` and `go.sum` to the released ConfigKit version. Review the +resolved dependency diff to keep PromptKit and its catalogs at their current +versions. Retain the existing Go minimum and other YAML dependencies used by +Audita. + +Check the production loader against the new presence and inheritance semantics. +Make only changes needed to preserve the target behavior; do not replace the +loader simply to exercise the new layered API. + +### 2. Verify Inheritance at Audita's Boundary + +Review existing configuration tests and add focused coverage for integration +risks not already protected: + +- A child backend inherits endpoint, capacity, and a credential reference while + retaining its own explicit overrides. Derived defaults respect inherited + presence, including an explicitly inherited zero queue capacity. +- Selected overlays and explicit flags reach the final configuration under + ConfigKit's precedence rules. Omitted validation-role selection still derives + from the final proposal-role selection, while explicit invalid values fail + Audita's validation. +- Surviving inherited credentials resolve and redact correctly. Null removes a + child's reference according to the existing credential contract; a surviving + reference on the parent remains subject to validation even if that backend is + not selected for a role. +- A representative invalid relationship produces a configuration failure at + the CLI boundary. Reuse upstream coverage for the full generic inheritance + grammar rather than duplicating its cycle, nesting, and expansion test suite. + +Use synthetic credentials and real ConfigKit loading. Keep domain validation +in Audita; inherited invalid settings must not become valid solely because the +library successfully assembled them. + +### 3. Preserve Inspection and Runtime Wiring + +Check effective settings, explanation output, and diagnostic configuration +snapshots with inherited values. Inspect whether existing source and derivation +mapping retains useful inheritance evidence; make narrow mapping changes if +needed without exposing resolved secrets or adding an unrelated inspection API. + +Use a representative controlled-provider workflow to verify that selected roles +receive the inherited backend endpoint and credential and share its configured +capacity. Reuse existing integration coverage where it already proves these +properties; do not duplicate the full PromptKit runtime test matrix. + +### 4. Update Documentation, Examples, and Attribution + +When implementation lands, update [configuration](../config.md) with the +reserved keyword, inheritance behavior, presence/default interactions, and +credential implications. Link to upstream for the generic grammar. Update +[configuration change recipes](../internal/cli-config.md) where contributor +steps change, and the [CLI reference](../cli.md) only if its documented +inspection behavior needs clarification. + +Add a small, complete inheritance example under [examples](../../examples/) +using valid parent and child backends and existing PromptKit profile syntax. +Validate it offline, alongside the maintained local, service, and testing-overlay +examples, following the existing example-validation recipe. + +Check the selected release's license and notice files and update the ConfigKit +entry in [attribution](../oss/attribution.md), including its commit-pinned source +and notice links, under the [OSS policy](../policy/oss.md). The review found no +change to ConfigKit's license or dependency declarations; verify the selected +artifacts when making the dependency change. + +### 5. Validate and Close the Adoption Unit + +Run targeted configuration and CLI checks, then the normal build and complete +offline test suite described in [development](../development.md). Validate +changed examples and documentation links and run `git diff --check`. No live +provider, paid model call, or new permanent release gate is needed. + +Record validation against the actual implementation revision and mark this +roadmap complete only after the criteria below are met. The earlier disposable +checkout result establishes that the unmodified suite passed with ConfigKit +v0.5.0 and PromptKit v0.11.2; it does not cover newly documented inheritance +workflows or substitute for final validation. + +## 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 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. + +The recommended release treatment is a backward-compatible Audita minor release +if this unit ships independently: it exposes a new configuration capability +while preserving currently valid application settings. Confirm that conclusion +against the final compatibility review, particularly the newly reserved +`extends` key, under the [release policy](../policy/release.md). 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 -Enable ConfigKit's optional selected-overlay feature in the migration. A testing -configuration that selects cheaper, faster LLMs is the initial use case. ConfigKit -**overlays** modify application settings; PromptKit **execution profiles** still -own model and generation settings. Keep `profiles_dir`, the PromptKit `profiles/` -directory, and proposal/validation profile names unchanged by this terminology -change. - -The planned interface is `--overlay ` on `process`, `config validate`, and -`config print-effective`. Treat selection as invocation state passed to -`Options.Overlay`, not as another persistent setting or environment overlay. -Follow ConfigKit v0.4.0's selection contract: omission, an empty name, or `default` -selects no overlay; a named selection loads `overlays/.yml` beneath the selected -configuration root. A missing selected overlay is an error. Use the library's -single-overlay semantics without adding stacking, inheritance, or legacy-directory -fallback. - -Precedence is application defaults, main configuration, selected overlay, then -explicit setting flags. Perform Audita's role inheritance and semantic validation -on the resolved configuration. ConfigKit's base parsing and schema-version checks -still precede overlay application; overlays cannot replace the schema version or -contain ConfigKit directives. General environment-variable overrides remain retired. -Imports and secret-directory bootstrap remain disabled. - -Provide a maintained `overlays/testing.yml` example that selects testing execution -profiles through `llm.proposal_profile` and `llm.validation_profile`. Model names and -generation controls belong in the corresponding PromptKit profile files. Set both -role selections in this example so a base configuration's explicit validation -profile cannot accidentally retain the production model. Normal omission-based -validation-profile inheritance continues to apply to the final effective settings. -The example must make its backend/credential requirements clear and use no real -secrets. Model choice is operator-controlled; “testing” does not promise a price, -performance level, or equivalent correction quality. - -Overlays may modify other ordinary application settings supported by the schema; -they are not restricted to profile selection. The resulting configuration must -still satisfy shared backend capacity, credential, and domain rules. Validation, -effective-config inspection, selected-profile inspection, and processing must all -use the same selected overlay. Preserve overlay provenance in configuration -explanations and diagnostics while retaining secret redaction. - -The [recorded overlay results](library-boundary-findings.md#selected-overlay-extension-2026-09-24) -prove the representative load, inspection, and HTTP path. Production acceptance -requires the same selection to reach both actual LLM roles, with explicit flags -winning over overlays and surviving secret references resolved/redacted correctly. -The isolated prototype is evidence, not a second supported runtime. - -## Inspection and Invocation Contract - -`process`, `config validate`, and `config print-effective` share file/overlay -selection and retained setting overrides. Invocation I/O paths remain process-only. -Only explicitly supplied flags override settings. Validation requires an explicit -config file; processing and inspection use the selected discovery order. Help is -available before configuration loading. All three commands validate selected -profiles without requiring a provider call during setup. - -`config print-effective --view settings|profiles|explain` exposes three YAML views: - -- `settings` (default): ConfigKit's redacted effective configuration. -- `profiles`: an Audita-owned summary of each selected role's profile, backend, - model, temperature, token limit, top-p, timeout, service tier, and reasoning - effort where present. Arbitrary extra provider parameters and credentials are - omitted; this is a selected-controls view, not every execution input. -- `explain`: field paths, sources, and derivation records from ConfigKit, without - resolved secret values. - -A ConfigKit snapshot alone does not describe profile-owned controls. Profile -inspection must enforce the registered-backend and credential boundary. Diagnostic -snapshots use these safe views and preserve overlay/explicit-override provenance. -The migration guide explains the intentional replacement of legacy inspection JSON. - -## Integration and Completion Criteria - -ConfigKit and PromptKit form one intentional breaking refactor. Intermediate -commits need not build or run. The target contains no temporary old-runtime adapter, -compatibility shim, processing gate, dual loader, or automatic legacy conversion. -The [combined feature roadmap](library-adoption.md) owns execution/reporting intent; -[implementation.md](https://gitea.maximumdirect.net/eric/audita/src/commit/cb405f6/docs/roadmap/implementation.md) alone owns stage order and implementation tasks. - -The final application loads all retained domain settings, assembles both selected -profiles, and processes through PromptKit. Controlled HTTP evidence must connect -configuration selection to actual requests, domain outcomes, safe diagnostics, -and shared finite backend capacity. Maintained examples and one migration guide -cover the complete file/flag/environment transition. Obsolete application-owned -loading, transport, rendering, and scheduler machinery is removed. - -The combined target is Audita v2.0.0. Release compliance and publication remain -last and separate from implementing the refactor. Retention and transcript timestamp -changes are not included; the selected retry/repair contract resolves the retry -follow-up in [runtime behavior](runtime-behavior.md). - -## Scope Boundaries - -- Pin ConfigKit v0.4.0 in production and align Go/toolchain requirements. ConfigKit requires - Go 1.25; the combined PromptKit prototype requires Go 1.25.5. Adopting these libraries - does not automatically remove Audita's existing YAML dependency used for glossary parsing. -- Implement the selected configuration and final PromptKit runtime directly, - without temporary runtime adapters, compatibility shims, or process gates. -- Enable selected overlays as specified above. Keep imports and secret-directory - bootstrap disabled unless a separate concrete requirement justifies them. -- Validation and inspection resolve surviving credential references and fail on - missing or empty values; no credential-free bypass is planned. -- Inspection and diagnostics use the safe selected-profile view and ConfigKit - provenance described above. Changed formats are covered by the migration guide. - -The eventual completion test is that Audita follows the suite's ConfigKit -conventions while retaining its intended domain capabilities, with a clear -migration guide and no ongoing obligation to support the previous configuration -model. +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.