From e8bc0050403ac57f1c4f0d6fe7b5b963970e01f4 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 23 Sep 2026 15:17:02 +0000 Subject: [PATCH] Outline the breaking ConfigKit migration --- docs/roadmap/configkit.md | 147 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 docs/roadmap/configkit.md diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md new file mode 100644 index 0000000..9bbd05e --- /dev/null +++ b/docs/roadmap/configkit.md @@ -0,0 +1,147 @@ +# 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](../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 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](runtime-behavior.md) 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.