audita/docs/roadmap/configkit.md

# ConfigKit Adoption Outline

**Updated:** 2026-11-07

**Status:** Initial outline. The [master roadmap](library-adoption.md) 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](../config.md) 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](commandkit.md).

The main upstream references are the
[v1 API migration](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v1.0.0.md),
[v1.1 release](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v1.1.0.md),
and [configuration contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/config.md).

## 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.

### No Configuration File Found — Resolved

Use ConfigKit's optional-search behavior when automatic discovery finds no file:
continue with embedded defaults, underlays, and explicit CLI settings, then
validate what the requested command needs. Require sufficient configuration for
the operation, not the existence of a main configuration file.

Resource inspection can work without a main file. Processing can run when its
required selections and inputs are otherwise supplied through supported
mechanisms. Report missing command-specific settings clearly; do not invent an
implicit model or profile selection to make incomplete execution settings pass.
Inspection must accurately show that no main file was selected.

Define filesystem context explicitly where overlays or relative resource inputs
need it; do not infer a base from unsuccessful search candidates. Preserve the
native absent-main lifecycle instead of manufacturing a placeholder file or
source record. Explicit-file errors and failures loading a selected discovered
file remain terminal.

### 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](promptkit.md#backend-and-credential-ownership--resolved):
   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](../config.md), relevant [CLI](../cli.md) behavior,
[change recipes](../internal/cli-config.md), 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. Verify that discovery exhaustion permits inspection and sufficiently
configured processing, while incomplete processing reports its missing inputs.
Cover absent-main provenance and filesystem context for selected overlays or
relative resources without weakening explicit-file error behavior.

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

### 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.