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 used the sibling ../ConfigKit checkout at v0.3.1. Reassess the supported release and current conventions during detailed planning. The installed application must depend on a versioned module, not a sibling checkout or local module replacement.

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.

Provisional Stages

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, 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.

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 migration may provide the configuration foundation for later features, or join other changes in one major release. Neither ordering is selected yet. Prefer reviewable implementation units even if the final release combines several changes.

The separate runtime behavior decisions remain unresolved. Coordinate the retry-count question with the new configuration semantics where appropriate; do not silently change runtime behavior merely by changing loaders. Retention and transcript timestamp decisions are not automatically included.

Open Design Decisions and Boundaries

• Select and pin the ConfigKit release and align Go/toolchain requirements. The reviewed version requires Go 1.25. 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.
• Start with imports, profiles, and secrets-directory bootstrap disabled unless a concrete suite or Audita requirement justifies enabling them. Adoption does not require activating every library capability.
• 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.