audita/docs/roadmap/configkit.md

# ConfigKit Adoption Roadmap

**Last updated:** 2026-09-23

**Status:** High-level, provisional planning only. Adoption direction is agreed;
this document does not authorize migration implementation. Revisit the scope,
sequence, design, and acceptance criteria in detail before starting work.

## 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 committed prototype used ConfigKit v0.3.1. The migration
baseline is now v0.4.0, whose selected configuration feature is named overlays.
An isolated upgrade passed the prototype tests and demonstration without source
changes; the committed prototype dependency has not yet been updated. 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 implementation handoff](library-boundary-findings.md) refine the provisional
directions here; production configuration migration has not begun.

## Proposed 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. Review config-file selection separately as an
  application-owned startup decision.
- 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.
- Review the configuration-related CLI afresh. Useful explicit flags can become
  ConfigKit override records; old names and aliases are not requirements. Direct
  credential-value flags should give way to the secret-reference convention.
- Use ConfigKit's redacted effective output and provide source/explanation access
  where useful. Existing JSON inspection output need not be preserved. Coordinate
  diagnostic configuration snapshots with the 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.

Implementation and acceptance work:

- Upgrade the isolated prototype to ConfigKit v0.4.0 and add a testing-overlay
  fixture before completing production configuration migration. Preserve the
  original v0.3.1 evidence as historical; overlay behavior is not yet proven by it.
- Verify unchanged base selection when no overlay is requested, both testing role
  selections, and explicit setting flags taking precedence over the overlay.
- Verify role inheritance after overlay application, effective profile/backend
  assembly, and secret resolution from the surviving configuration.
- Reject missing/invalid overlay selections and prohibited version/directive changes
  through ConfigKit; rely on its tests for exhaustive merge/parser cases.
- Verify redacted inspection and overlay provenance, then run both LLM roles through
  the offline provider using the selected testing profiles. Provider requests must
  use their model selections; no paid calls are needed.
- Add production CLI coverage for the three commands and document selection,
  precedence, example layout, and migration guidance when implemented.

This expands the next configuration unit; it does not reopen the completed
prototype's original scope or change the ConfigKit → PromptKit → combined release
sequence. The production LLM migration remains necessary before promising the full
new runtime behavior.

## Provisional Stages

The completed [shared-boundary and prototype unit](library-boundary.md) supplies
the initial target settings model and integration evidence. Extend that evidence
with the selected-overlay work above during the next configuration unit.

### 1. Define the Contract and Coordinate Sequencing

Inventory existing configuration fields, invocation options, environment settings,
secret handling, inheritance rules, and inspection consumers. Produce an old-to-new
mapping for migration guidance and identify which concepts should be retained,
redesigned, or removed. This is an inventory of needs, not a compatibility checklist.

Specify the target ConfigKit conventions and the boundary between configuration
and invocation-only state. Decide file discovery, the new file schema version,
CLI shape, validation/inspection behavior, and optional feature scope. Identify
application requirements that the library cannot express cleanly before building
workarounds.

Coordinate these decisions with the other planned large changes to Audita. Finalize
an implementation plan and concrete acceptance criteria before beginning migration.

### 2. Prove a Representative Configuration Path

After detailed planning, implement a bounded path from file selection and CLI
inputs through ConfigKit to Audita's runtime configuration. Exercise defaults,
selected overlays, proposal/validation inheritance, concurrency, duration values,
secrets, and redacted inspection using representative valid and invalid inputs.

Use the result to assess whether domain rules remain clear and substantial old
infrastructure can be removed. Resolve genuine library gaps deliberately, including
upstream discussion or changes when justified; avoid rebuilding a parallel loader.
A prototype is evidence for the design, not a permanent compatibility mode.

### 3. Complete the Migration

Convert the remaining configuration and command paths, remove superseded code and
legacy interfaces, and update maintained examples and canonical documentation
alongside the implementation. Replace tests that enforce retired conventions with
coverage of the new contract; preserve meaningful domain and runtime coverage.

Provide a concise migration guide covering old-to-new fields, flags, environment
settings, durations, credentials, validation, and inspection behavior. Automated
conversion tooling is not assumed to be necessary or in scope.

### 4. Validate and Release the Breaking Change

Verify representative loading and CLI workflows, domain resolution, safe secret
handling, diagnostics, examples, and runtime integration with deterministic tests.
Confirm obsolete loaders and aliases are gone and that documentation describes the
implemented model. Use the established [release procedure](../release.md).

Recommend Audita v2.0.0 and a new configuration-file schema version. Clearly reject
unsupported old file versions and direct users to the migration guide. Final
release numbering and whether this ships with other breaking changes remain
sequencing decisions; no publication is authorized by this roadmap.

## Sequencing Considerations

Changes to module configuration, runtime settings, CLI design, or diagnostic
reporting are likely to overlap this migration. Design their shared target model
first. If another change will substantially reshape those areas, avoid migrating
the same concepts twice. Work independent of configuration can proceed separately.

The [coordinated library-adoption roadmap](library-adoption.md) owns the proposed
sequence with PromptKit: shared boundary design and a PromptKit prototype, then
ConfigKit implementation, then PromptKit implementation, followed by a combined
v2.0.0 release. Revisit that sequence alongside other major changes. Keep
implementation units reviewable even when the release combines them.

The separate [runtime behavior decisions](runtime-behavior.md) track remaining
questions and the selected retry direction.
The coordinated plan adopts PromptKit's explicit retry semantics and enables
structural repair from the outset. Include separate transient-retry and positive
repair budgets, plus the total-operation deadline policy, in the shared settings
design. The reviewed PromptKit baseline is v0.11.0; exact defaults and settings
ownership remain detailed-planning decisions. Do not implement the runtime change
merely as a side effect of replacing the configuration loader.
Retention and transcript timestamp decisions are not automatically included.

## Open Design Decisions and Boundaries

- Pin ConfigKit v0.4.0 and align Go/toolchain requirements. ConfigKit requires
  Go 1.25; the combined PromptKit prototype requires Go 1.25.5. Config-only
  adoption does not automatically remove Audita's existing YAML dependency used for glossary parsing.
- Decide the configuration type shape, domain inheritance rules, and runtime
  conversion boundary without leaking library concerns throughout the pipeline.
- Enable selected overlays as specified above. Keep imports and secret-directory
  bootstrap disabled unless a separate concrete requirement justifies them.
- Define the desired behavior of validation and inspection without available
  credentials under ConfigKit's secret-reference requirements.
- Decide which inspection and diagnostic interfaces benefit from provenance and
  explanation, and account for their changed formats in the migration guide.
- Finalize task breakdown, test scope, and acceptance criteria after the other
  planned large changes are understood. No schedule or effort estimate is committed.

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.