159 lines
8.9 KiB
Markdown
159 lines
8.9 KiB
Markdown
# 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
|
|
|
|
First complete the [shared-boundary and prototype unit](library-boundary.md) from
|
|
the coordinated adoption plan. It supplies the target settings model and integration
|
|
evidence for the production configuration migration described here.
|
|
|
|
### 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](../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
|
|
|
|
- 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.
|