audita/docs/roadmap/configkit.md

ConfigKit Adoption Roadmap

Last updated: 2026-09-24

Status: Final target selected; production implementation pending. The boundary and selected overlays are verified. The implementation plan owns execution stages; no production migration or release has begun.

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. The prototype now pins v0.4.0 and verifies its selected-overlay path; original v0.3.1 findings remain historical. The installed application must depend on a versioned module, not a sibling checkout or local module replacement.

The shared boundary/prototype unit is complete. Its selected contract, inventory, and evidence define the detailed target alongside this roadmap. Production configuration migration has not begun.

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 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 owns execution/reporting intent; 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.

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.