audita/docs/roadmap/configkit.md

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 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 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 and CLI contract own the implemented behavior.

The reviewed upstream release is ConfigKit v0.5.0, 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 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 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. 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 is historical; current overlay behavior belongs to configuration. This upgrade preserves that workflow and adds native ConfigKit inheritance without reviving the earlier combined migration plan.