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](../../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.
- 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](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. 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](../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 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.