audita/docs/roadmap/configkit.md

ConfigKit Adoption Outline

Updated: 2026-11-07

Status: Initial outline. The master roadmap owns the agreed adoption policy, reviewed versions, shared sequencing, and completion.

Baseline and Target

Audita currently uses ConfigKit v0.7.1 through its former import path. Its configuration contract describes application file discovery, overlays, defaults, inheritance, secret references, and explicit CLI settings.

Adopt ConfigKit v1.1.0 and its stable public API as the configuration foundation. Use its native loading, discovery, presence, composition, resolution, diagnostics, and inspection mechanisms. Audita supplies domain types and validation; retain custom loading behavior only for a demonstrated domain requirement. Standard operator access is implemented through the CommandKit outline.

The main upstream references are the v1 API migration, v1.1 release, and configuration contract.

Agreed Direction and Migration Work

Discovery Locations and Import Selection — Resolved

An explicit --config selects exactly that file. A missing, inaccessible, or invalid explicit file is an error; do not fall back to discovery.

Without an explicit file, search in this order using ConfigKit's native presets and filename rules with application name audita:

1. WorkingDirectory for project-local configuration.
2. UserConfigDirectory for personal configuration.
3. UnixSystemDirectories for system configuration.

Select the first matching file. Do not merge every discovered file or continue searching after a selected file fails to load. Additional composition is explicit through native imports and overlays. Recommend explicit configuration paths for automation so its selection does not depend on the working directory.

Enable native imports for operator configuration sources, retaining upstream defaults and declaration-level controls. Imports compose peer documents, not higher-priority override layers. Missing optional imports may be absent; operators use required: true for essential inputs. Invalid declarations, unreadable selected files, and composition conflicts retain native errors.

Behavior when automatic discovery finds no file remains a separate open decision below. This does not reopen the selected search order or import support.

Migration Work

1. Move imports to go.maximumdirect.net/configkit with the coordinated PromptKit cutover. Raise the toolchain as specified by the master roadmap. Replace Resolution.Record uses with the appropriate dedicated recording method; review affected metadata and diagnostics APIs, not only compilation. Relevant renamed concepts include EntryInfo, Sensitive, LayerMain, version evidence, and destination fallback. Typed Secret and its field tag retain their spelling.
2. Adopt the native lifecycle: source composition and inheritance, typed decoding, explicit CLI assignments, then application resolution and validation. CLI assignments do not repair earlier decoding failures, alter inheritance relationships, or propagate parent edits through already resolved children. Update the current loading-order explanation and realistic integration tests.
3. Migrate genuine source-root control blocks to config: where present. Distinguish application schema versions from source version evidence; do not impose headers on every fragment merely because the API supports them.
4. Use identified collections where records have meaningful identity. ConfigKit upsert replaces matching records in full; inspection follows registered identities through movement, while list diffs remain atomic. Preserve ordinary ordered/repeated pipeline.modules entries and empty-pipeline semantics: these express Audita domain behavior, so uniqueness/upsert is inappropriate.
5. Integrate native source discovery and standard inspection instead of retaining equivalent private infrastructure. Adopt source diagnostics, explanation, history, normalization, and safe effective output through ckconfig. Account for the provenance label changing from base to main.
6. Apply the resolved PromptKit ownership decision: remove Audita's separate backend mapping and LLM credential references from its application schema. Native PromptKit resources own those settings and their resolution. Coordinate the hard cutover and examples here, using the resolved discovery and import policy above.

Documentation and Acceptance

Update configuration, relevant CLI behavior, change recipes, maintained examples, migration guidance, and attribution as the corresponding behavior lands. Public docs remain descriptions of implemented behavior until then.

Acceptance should demonstrate native file selection, source composition, overlays, explicit false/zero/empty values, derived settings, and secret handling through real ConfigKit loading. Cover the changed inheritance/assignment order, source errors, useful failure evidence, and secret-safe inspection. Reuse upstream coverage for generic grammar rather than copying its test matrix. Verify the standard ckconfig surface through the assembled CLI and run the full application suite at the coordinated migration boundary.

Check explicit-file selection without fallback, native working/user/system search precedence, and terminal errors for a selected invalid file. Verify optional and required imports and peer-composition errors through Audita's integration. Cover discovery exhaustion after its behavior is selected below.

The earlier passing configuration suite is useful baseline evidence, not proof that operators see unchanged semantics. Native semantics and clear migration are the target; preserving incidental old output or validation order is not.

Upstream Requests

No ConfigKit change request is currently identified. Prefer adapting Audita to its stable supported API. Record any necessary exception with a concrete domain requirement and the smallest integration boundary that satisfies it.

Open Decisions

No Configuration File Found

Recommendation: use ConfigKit's optional-search behavior: continue with embedded defaults, underlays, and explicit CLI settings, then validate what the requested command needs. A missing main file alone should not prevent resource inspection or execution whose required inputs are otherwise supplied. Do not invent an implicit model/profile choice to make incomplete execution settings pass validation. Define filesystem context explicitly where overlays or relative resource inputs need it; do not infer a base from unsuccessful search candidates.

This follows the native absent-main lifecycle and supports lightweight command invocations. It requires clear errors for missing command-specific inputs and inspection that accurately shows that no main file was selected.

Alternative: require a discovered configuration file for configuration-dependent commands, while keeping help/version independent. This gives deployments a mandatory configuration anchor, but rejects otherwise sufficient defaults and CLI settings and adds a requirement without an identified domain need. Explicit file errors remain terminal under either choice.

Application Schema Version

Recommendation: design the application schema around the target ownership boundaries, then choose its version to describe that contract. Keeping version: 2 is reasonable only if its meaning remains coherent; compatibility with existing files is not a selection criterion. Do not confuse the application schema version with the library version or PromptKit's source header.

Alternative: introduce a new application schema version if backend or credential ownership changes make existing files misleading. It provides a clear migration boundary; the version alone does not explain the new contract, so hard-cutover guidance still needs to describe it. Decide from the final schema, not from dependency version numbers alone, and do not add legacy-schema support.