159 lines
9.0 KiB
Markdown
159 lines
9.0 KiB
Markdown
# ConfigKit Adoption Outline
|
|
|
|
**Updated:** 2026-11-09
|
|
|
|
**Status:** Target decisions resolved; implementation pending. The
|
|
[master roadmap](library-adoption.md) owns shared policy and dependency selection;
|
|
the [implementation plan](implementation.md) owns sequencing.
|
|
|
|
## 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
|
|
|
|
### 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`:
|
|
|
|
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.
|
|
|
|
The PromptKit outline owns [automatic prompt sources](promptkit.md#automatic-prompt-sources--resolved).
|
|
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](promptkit.md#backend-and-credential-ownership--resolved).
|
|
Audita's v3 schema has no separate backend or LLM credential registry. Native
|
|
[automatic resource sources](promptkit.md#automatic-prompt-sources--resolved)
|
|
remain independent of main application-file discovery.
|
|
|
|
The v3 schema includes the glossary roadmap's [scope and inheritance model](glossary-stages.md#configuration-scope--resolved),
|
|
[typed handoff](glossary-stages.md#list-inputs-and-configuration-handoff--resolved),
|
|
and [optional stage identity](glossary-stages.md#stage-identity-and-attribution--resolved).
|
|
Glossary definitions use native composition, [default underlay sources](glossary-stages.md#default-sources-and-explicit-configuration--resolved),
|
|
and [collection-scoped identity](glossary-stages.md#entry-identity--resolved).
|
|
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](../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.
|
|
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.
|