audita/docs/roadmap/configkit.md

ConfigKit v0.5.0 Adoption Roadmap

Last updated: 2026-10-03

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 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.
• 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 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 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. Audita's current ExplanationYAML exposes source/layer information and application-derived defaults but does not expose ConfigKit's Origin.Inheritance evidence. Extend that projection with a compact, value-free explanation of inheritance, retaining existing fields and secret redaction. This is an explicit adoption deliverable; use upstream metadata without reconstructing ancestry from YAML 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 with the reserved keyword, inheritance behavior, presence/default interactions, and credential implications. Link to upstream for the generic grammar. Update configuration change recipes where contributor steps change, and the CLI reference only if its documented inspection behavior needs clarification.

Add a small, complete inheritance example under 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, including its commit-pinned source and notice links, under the OSS policy. 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. 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 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.