172 lines
10 KiB
Markdown
172 lines
10 KiB
Markdown
# ConfigKit Adoption Roadmap
|
|
|
|
**Last updated:** 2026-09-24
|
|
|
|
**Status:** Production implementation complete. The selected configuration and
|
|
overlay model is implemented; [implementation evidence](https://gitea.maximumdirect.net/eric/audita/src/commit/cb405f6/docs/roadmap/implementation.md)
|
|
records verification. No release has been published.
|
|
|
|
## Purpose and Direction
|
|
|
|
Adopt ConfigKit to harmonize Audita's configuration policy with the other
|
|
applications in the suite. Consistent configuration conventions are the primary
|
|
benefit; reducing application-owned configuration infrastructure is a secondary
|
|
benefit and a useful measure of integration quality.
|
|
|
|
This is an intentional breaking migration. There is no goal of backward
|
|
compatibility with existing installations, configuration files, CLI flags,
|
|
environment variables, or configuration-inspection output. Provide a migration
|
|
guide instead of legacy loaders, aliases, dual operating modes, or an ongoing
|
|
compatibility layer. Retain existing syntax only when it independently suits the
|
|
new model, not because compatibility requires it.
|
|
|
|
The initial review and prototype used ConfigKit v0.3.1, then verified v0.4.0
|
|
selected overlays. Those findings remain historical; the prototype was removed
|
|
after production integration. The application depends on a versioned module,
|
|
without a sibling checkout or local module replacement.
|
|
|
|
The shared boundary/prototype unit is complete. Its [selected contract, inventory,
|
|
and evidence](library-boundary-findings.md) define the detailed target alongside
|
|
this roadmap. Production configuration migration is complete.
|
|
|
|
## Target End State
|
|
|
|
- ConfigKit owns strict YAML loading, input presence, default application, explicit
|
|
override mechanics, recorded resolution, secret references, and safe inspection.
|
|
- Audita owns its configuration types, field meanings, defaults, schema-version
|
|
policy, file selection, CLI parsing, domain validation, and runtime initialization.
|
|
- Adopt ConfigKit's precedence and validation lifecycle rather than reproduce
|
|
Audita's current per-layer validation and environment-overlay behavior.
|
|
- General configuration environment overrides are retired. Credentials use typed
|
|
environment-name secret references; supplied references must resolve according
|
|
to ConfigKit's contract. File selection follows the application-owned
|
|
discovery rules in the selected boundary.
|
|
- Standardize duration representations, explicit empty/null/zero handling, and
|
|
inheritance on the shared conventions. Express genuine Audita domain rules
|
|
through the supported resolution and validation APIs.
|
|
- Retained domain-setting flags and proposal/validation profile flags become
|
|
explicit ConfigKit overrides according to the migration inventory. Remove old
|
|
provider/key/retry/concurrency flags and aliases. Credentials use secret references.
|
|
- Use ConfigKit's redacted effective output and provide source/explanation access
|
|
through the selected views below. Legacy JSON inspection is replaced.
|
|
Diagnostic configuration snapshots use the same new model.
|
|
- Delete superseded loading and override machinery. Do not hide the old model
|
|
behind adapters that defeat the adoption's consistency benefit.
|
|
|
|
Keep Audita's domain capabilities, such as ordered and repeated correction modules,
|
|
expressible in the new model. Their existing configuration spelling is not binding.
|
|
Transcript/glossary formats, processing algorithms, and output schemas are outside
|
|
this migration unless later planning identifies a concrete dependency or an
|
|
explicitly coordinated change.
|
|
|
|
## Selected Overlays for Testing
|
|
|
|
Enable ConfigKit's optional selected-overlay feature in the migration. A testing
|
|
configuration that selects cheaper, faster LLMs is the initial use case. ConfigKit
|
|
**overlays** modify application settings; PromptKit **execution profiles** still
|
|
own model and generation settings. Keep `profiles_dir`, the PromptKit `profiles/`
|
|
directory, and proposal/validation profile names unchanged by this terminology
|
|
change.
|
|
|
|
The planned interface is `--overlay <name>` on `process`, `config validate`, and
|
|
`config print-effective`. Treat selection as invocation state passed to
|
|
`Options.Overlay`, not as another persistent setting or environment overlay.
|
|
Follow ConfigKit v0.4.0's selection contract: omission, an empty name, or `default`
|
|
selects no overlay; a named selection loads `overlays/<name>.yml` beneath the selected
|
|
configuration root. A missing selected overlay is an error. Use the library's
|
|
single-overlay semantics without adding stacking, inheritance, or legacy-directory
|
|
fallback.
|
|
|
|
Precedence is application defaults, main configuration, selected overlay, then
|
|
explicit setting flags. Perform Audita's role inheritance and semantic validation
|
|
on the resolved configuration. ConfigKit's base parsing and schema-version checks
|
|
still precede overlay application; overlays cannot replace the schema version or
|
|
contain ConfigKit directives. General environment-variable overrides remain retired.
|
|
Imports and secret-directory bootstrap remain disabled.
|
|
|
|
Provide a maintained `overlays/testing.yml` example that selects testing execution
|
|
profiles through `llm.proposal_profile` and `llm.validation_profile`. Model names and
|
|
generation controls belong in the corresponding PromptKit profile files. Set both
|
|
role selections in this example so a base configuration's explicit validation
|
|
profile cannot accidentally retain the production model. Normal omission-based
|
|
validation-profile inheritance continues to apply to the final effective settings.
|
|
The example must make its backend/credential requirements clear and use no real
|
|
secrets. Model choice is operator-controlled; “testing” does not promise a price,
|
|
performance level, or equivalent correction quality.
|
|
|
|
Overlays may modify other ordinary application settings supported by the schema;
|
|
they are not restricted to profile selection. The resulting configuration must
|
|
still satisfy shared backend capacity, credential, and domain rules. Validation,
|
|
effective-config inspection, selected-profile inspection, and processing must all
|
|
use the same selected overlay. Preserve overlay provenance in configuration
|
|
explanations and diagnostics while retaining secret redaction.
|
|
|
|
The [recorded overlay results](library-boundary-findings.md#selected-overlay-extension-2026-09-24)
|
|
prove the representative load, inspection, and HTTP path. Production acceptance
|
|
requires the same selection to reach both actual LLM roles, with explicit flags
|
|
winning over overlays and surviving secret references resolved/redacted correctly.
|
|
The isolated prototype is evidence, not a second supported runtime.
|
|
|
|
## Inspection and Invocation Contract
|
|
|
|
`process`, `config validate`, and `config print-effective` share file/overlay
|
|
selection and retained setting overrides. Invocation I/O paths remain process-only.
|
|
Only explicitly supplied flags override settings. Validation requires an explicit
|
|
config file; processing and inspection use the selected discovery order. Help is
|
|
available before configuration loading. All three commands validate selected
|
|
profiles without requiring a provider call during setup.
|
|
|
|
`config print-effective --view settings|profiles|explain` exposes three YAML views:
|
|
|
|
- `settings` (default): ConfigKit's redacted effective configuration.
|
|
- `profiles`: an Audita-owned summary of each selected role's profile, backend,
|
|
model, temperature, token limit, top-p, timeout, service tier, and reasoning
|
|
effort where present. Arbitrary extra provider parameters and credentials are
|
|
omitted; this is a selected-controls view, not every execution input.
|
|
- `explain`: field paths, sources, and derivation records from ConfigKit, without
|
|
resolved secret values.
|
|
|
|
A ConfigKit snapshot alone does not describe profile-owned controls. Profile
|
|
inspection must enforce the registered-backend and credential boundary. Diagnostic
|
|
snapshots use these safe views and preserve overlay/explicit-override provenance.
|
|
The migration guide explains the intentional replacement of legacy inspection JSON.
|
|
|
|
## Integration and Completion Criteria
|
|
|
|
ConfigKit and PromptKit form one intentional breaking refactor. Intermediate
|
|
commits need not build or run. The target contains no temporary old-runtime adapter,
|
|
compatibility shim, processing gate, dual loader, or automatic legacy conversion.
|
|
The [combined feature roadmap](library-adoption.md) owns execution/reporting intent;
|
|
[implementation.md](https://gitea.maximumdirect.net/eric/audita/src/commit/cb405f6/docs/roadmap/implementation.md) alone owns stage order and implementation tasks.
|
|
|
|
The final application loads all retained domain settings, assembles both selected
|
|
profiles, and processes through PromptKit. Controlled HTTP evidence must connect
|
|
configuration selection to actual requests, domain outcomes, safe diagnostics,
|
|
and shared finite backend capacity. Maintained examples and one migration guide
|
|
cover the complete file/flag/environment transition. Obsolete application-owned
|
|
loading, transport, rendering, and scheduler machinery is removed.
|
|
|
|
The combined target is Audita v2.0.0. Release compliance and publication remain
|
|
last and separate from implementing the refactor. Retention and transcript timestamp
|
|
changes are not included; the selected retry/repair contract resolves the retry
|
|
follow-up in [runtime behavior](runtime-behavior.md).
|
|
|
|
## Scope Boundaries
|
|
|
|
- Pin ConfigKit v0.4.0 in production and align Go/toolchain requirements. ConfigKit requires
|
|
Go 1.25; the combined PromptKit prototype requires Go 1.25.5. Adopting these libraries
|
|
does not automatically remove Audita's existing YAML dependency used for glossary parsing.
|
|
- Implement the selected configuration and final PromptKit runtime directly,
|
|
without temporary runtime adapters, compatibility shims, or process gates.
|
|
- Enable selected overlays as specified above. Keep imports and secret-directory
|
|
bootstrap disabled unless a separate concrete requirement justifies them.
|
|
- Validation and inspection resolve surviving credential references and fail on
|
|
missing or empty values; no credential-free bypass is planned.
|
|
- Inspection and diagnostics use the safe selected-profile view and ConfigKit
|
|
provenance described above. Changed formats are covered by the migration guide.
|
|
|
|
The eventual completion test is that Audita follows the suite's ConfigKit
|
|
conventions while retaining its intended domain capabilities, with a clear
|
|
migration guide and no ongoing obligation to support the previous configuration
|
|
model.
|