ConfigKit Adoption Outline

Updated: 2026-11-09

Status: Target decisions resolved; implementation pending. The master roadmap owns shared policy and dependency selection; the implementation plan owns sequencing.

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

Application Schema Version — Resolved

Use version: 3 for Audita's application configuration in the next major release, with a hard cutover. The new contract includes the selected native PromptKit ownership boundaries and the final stage-specific glossary design. Finalize that combined schema before release so operators migrate once.

Reject obsolete application schema versions with migration guidance. Do not retain version-2 loading, automatic conversion, or dual-schema compatibility. Update application defaults, examples, and schema validation together when the new schema is implemented. The no-main-file behavior below remains supported; embedded defaults must supply the current application version.

This is Audita's application schema version, independent of library releases and ConfigKit or PromptKit source headers. It does not require a version header on every imported fragment. Hard-cutover guidance must explain the actual field and ownership changes, including glossary-stage configuration, rather than merely instructing operators to change the version number.

Discovery Locations and Import Selection — Resolved

For Audita's main application configuration, 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:

WorkingDirectory for project-local configuration.
UserConfigDirectory for personal configuration.
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.

The PromptKit outline owns automatic prompt sources. Those resource imports compose in the engine's operator underlay independently of main application-file selection, using the same native import semantics. Keep application configuration discovery and PromptKit resource acquisition distinct while sharing their supported ConfigKit mechanisms.

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.

Target Boundaries

The application uses the go.maximumdirect.net/configkit module and native recorded resolution, discovery, source diagnostics, and safe effective output. Source composition and inheritance precede typed decoding and explicit CLI assignment; application resolution and validation follow. CLI assignments do not repair earlier decoding failures, change inheritance relationships, or propagate parent edits through resolved children. Native source provenance uses main in place of base. Genuine source-root controls use config:.

PromptKit owns backend and credential resources. Audita's v3 schema has no separate backend or LLM credential registry. Native automatic resource sources remain independent of main application-file discovery.

The v3 schema includes the glossary roadmap's scope and inheritance model, typed handoff, and optional stage identity. Glossary definitions use native composition, default underlay sources, and collection-scoped identity. Pipeline stages remain an ordinary ordered list, including repetitions and explicit empty-pipeline behavior. The application supplies domain resolution rules within the native lifecycle, with no second runtime defaulting pass.

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. 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. Verify that application main-file selection and exhaustion preserve the separate automatic PromptKit source context and precedence specified in its outline.

Verify acceptance of the final version-3 schema and rejection of obsolete application versions. Check that no-main-file loading uses version-3 defaults, and that maintained examples and migration guidance cover the final library ownership and glossary-stage changes without a legacy compatibility path.

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.

9.0 KiB Raw Blame History