Outline the breaking ConfigKit migration

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.