Plan ConfigKit v0.5.0 adoption
This commit is contained in:
@@ -1,171 +1,190 @@
|
||||
# ConfigKit Adoption Roadmap
|
||||
# ConfigKit v0.5.0 Adoption Roadmap
|
||||
|
||||
**Last updated:** 2026-09-24
|
||||
**Last updated:** 2026-10-03
|
||||
|
||||
**Status:** Production implementation complete. The selected configuration and
|
||||
overlay model is implemented; [implementation evidence](https://gitea.maximumdirect.net/eric/audita/src/commit/cb405f6/docs/roadmap/implementation.md)
|
||||
records verification. No release has been published.
|
||||
**Status:** Planned; implementation has not begun. The dependency-only review
|
||||
passed Audita's existing offline test suite in a disposable checkout. That is
|
||||
baseline compatibility evidence, not completion of the feature work below.
|
||||
|
||||
## Purpose and Direction
|
||||
## Purpose and Baseline
|
||||
|
||||
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.
|
||||
Adopt ConfigKit v0.5.0 as an independently reviewable step before PromptKit
|
||||
v0.12.0. Use the library's configuration and inheritance conventions while
|
||||
preserving Audita's domain ownership and existing operator workflows.
|
||||
|
||||
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.
|
||||
At the reviewed Audita revision `6ae1d7cd5f548b26de5787372d3f2249eaa4757d`,
|
||||
[go.mod](../../go.mod) selects ConfigKit v0.4.2, PromptKit v0.11.2, and Go
|
||||
1.25.5. ConfigKit already owns loading, presence, secret resolution, and
|
||||
configuration inspection. Audita's `internal/core/config` supplies typed
|
||||
settings, defaults, derived values, and domain validation; `internal/cli`
|
||||
selects files, overlays, and explicit overrides. The
|
||||
[configuration contract](../config.md) and [CLI contract](../cli.md) own the
|
||||
implemented behavior.
|
||||
|
||||
The initial review and prototype used ConfigKit v0.3.1, then verified v0.4.0
|
||||
selected overlays. Those findings remain historical; the prototype was removed
|
||||
after production integration. The application depends on a versioned module,
|
||||
without a sibling checkout or local module replacement.
|
||||
The reviewed upstream release is
|
||||
[ConfigKit v0.5.0](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.5.0/docs/releases/v0.5.0.md),
|
||||
commit `dc09959cca4e105f49ec316c6d4ba585bd2340bd`. It adds layered underlays,
|
||||
caller-owned filesystem sources, mapping sources, source resource contexts, and
|
||||
built-in sibling inheritance. The Go minimum and YAML dependency do not change.
|
||||
Ordinary `Load` remains available; adopting `LoadLayered` is optional.
|
||||
|
||||
The shared boundary/prototype unit is complete. Its [selected contract, inventory,
|
||||
and evidence](library-boundary-findings.md) define the detailed target alongside
|
||||
this roadmap. Production configuration migration is complete.
|
||||
This roadmap supersedes the completed original adoption plan at this path.
|
||||
The [historical roadmap](https://gitea.maximumdirect.net/eric/audita/src/commit/6ae1d7cd5f548b26de5787372d3f2249eaa4757d/docs/roadmap/configkit.md)
|
||||
records that earlier migration. Its coordinated breaking-refactor instructions
|
||||
and release target do not govern this incremental upgrade.
|
||||
|
||||
## Target 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. File selection follows the application-owned
|
||||
discovery rules in the selected boundary.
|
||||
- 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.
|
||||
- Retained domain-setting flags and proposal/validation profile flags become
|
||||
explicit ConfigKit overrides according to the migration inventory. Remove old
|
||||
provider/key/retry/concurrency flags and aliases. Credentials use secret references.
|
||||
- Use ConfigKit's redacted effective output and provide source/explanation access
|
||||
through the selected views below. Legacy JSON inspection is replaced.
|
||||
Diagnostic configuration snapshots use the same new model.
|
||||
- Delete superseded loading and override machinery. Do not hide the old model
|
||||
behind adapters that defeat the adoption's consistency benefit.
|
||||
- Audita uses the released ConfigKit v0.5.0 module, with no local replacement.
|
||||
PromptKit stays at v0.11.2 throughout this adoption unit.
|
||||
- Existing configurations continue through the current file-selection,
|
||||
overlay, explicit-override, resolution, and validation flow. Retain the
|
||||
application schema version, CLI interface, and main-file-relative resource
|
||||
rules defined in the current contracts.
|
||||
- Application configuration can use ConfigKit's native sibling `extends`
|
||||
relationships. Audita does not implement a second inheritance resolver,
|
||||
special backend-only syntax, or an opt-in switch around the library feature.
|
||||
- Inherited values participate in presence-aware defaults, domain validation,
|
||||
secret resolution, and safe inspection just like other effective input.
|
||||
In particular, inherited backend settings must not be overwritten merely
|
||||
because they were not written directly on the child.
|
||||
- Effective settings and explanations remain useful and secret-safe when
|
||||
values are inherited. Preserve the existing Audita-owned inspection formats;
|
||||
use ConfigKit's metadata rather than reconstructing provenance from YAML.
|
||||
- Canonical documentation and a maintained example explain the adopted
|
||||
inheritance behavior. Attribution identifies the exact new upstream source.
|
||||
|
||||
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.
|
||||
The upstream [configuration contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.5.0/docs/config.md#sibling-inheritance)
|
||||
owns generic inheritance mechanics. The integration must account for three
|
||||
consequences: `extends` is reserved automatically throughout input mappings;
|
||||
relationships resolve after source precedence and before typed decoding; and
|
||||
inherited zero, false, empty, or null values count as explicit input. An inherited
|
||||
value still has to satisfy Audita's field-specific rules. Parent definitions
|
||||
also undergo ordinary application validation; inheritance does not introduce
|
||||
abstract, validation-exempt backend entries.
|
||||
|
||||
## Scope and Sequencing
|
||||
|
||||
Keep the existing `Load` integration unless implementation reveals a concrete
|
||||
need to change it. Source-backed defaults, additional operator underlay tiers,
|
||||
imports, and source-relative reinterpretation of application paths are outside
|
||||
this feature. Their availability upstream does not require expanding Audita's
|
||||
configuration surface. Imports and secret-directory bootstrap retain their
|
||||
current disabled state.
|
||||
|
||||
ConfigKit inheritance applies to Audita configuration in this step. PromptKit
|
||||
profile formats, profile inheritance, engine construction, embedded prompts,
|
||||
and backend catalogs remain governed by the existing PromptKit integration.
|
||||
There is no application-owned translation of profile documents in this work.
|
||||
|
||||
Complete and validate ConfigKit adoption before migrating PromptKit. PromptKit
|
||||
v0.12.0 itself requires ConfigKit v0.5.0; this sequence isolates the generic
|
||||
configuration change from the later API and profile-format migration. Each
|
||||
completed adoption unit should build and pass its applicable checks. A separate
|
||||
public release between the two units is optional, not a prerequisite.
|
||||
|
||||
## Work Plan
|
||||
|
||||
### 1. Upgrade the Dependency
|
||||
|
||||
Update `go.mod` and `go.sum` to the released ConfigKit version. Review the
|
||||
resolved dependency diff to keep PromptKit and its catalogs at their current
|
||||
versions. Retain the existing Go minimum and other YAML dependencies used by
|
||||
Audita.
|
||||
|
||||
Check the production loader against the new presence and inheritance semantics.
|
||||
Make only changes needed to preserve the target behavior; do not replace the
|
||||
loader simply to exercise the new layered API.
|
||||
|
||||
### 2. Verify Inheritance at Audita's Boundary
|
||||
|
||||
Review existing configuration tests and add focused coverage for integration
|
||||
risks not already protected:
|
||||
|
||||
- A child backend inherits endpoint, capacity, and a credential reference while
|
||||
retaining its own explicit overrides. Derived defaults respect inherited
|
||||
presence, including an explicitly inherited zero queue capacity.
|
||||
- Selected overlays and explicit flags reach the final configuration under
|
||||
ConfigKit's precedence rules. Omitted validation-role selection still derives
|
||||
from the final proposal-role selection, while explicit invalid values fail
|
||||
Audita's validation.
|
||||
- Surviving inherited credentials resolve and redact correctly. Null removes a
|
||||
child's reference according to the existing credential contract; a surviving
|
||||
reference on the parent remains subject to validation even if that backend is
|
||||
not selected for a role.
|
||||
- A representative invalid relationship produces a configuration failure at
|
||||
the CLI boundary. Reuse upstream coverage for the full generic inheritance
|
||||
grammar rather than duplicating its cycle, nesting, and expansion test suite.
|
||||
|
||||
Use synthetic credentials and real ConfigKit loading. Keep domain validation
|
||||
in Audita; inherited invalid settings must not become valid solely because the
|
||||
library successfully assembled them.
|
||||
|
||||
### 3. Preserve Inspection and Runtime Wiring
|
||||
|
||||
Check effective settings, explanation output, and diagnostic configuration
|
||||
snapshots with inherited values. Inspect whether existing source and derivation
|
||||
mapping retains useful inheritance evidence; make narrow mapping changes if
|
||||
needed without exposing resolved secrets or adding an unrelated inspection API.
|
||||
|
||||
Use a representative controlled-provider workflow to verify that selected roles
|
||||
receive the inherited backend endpoint and credential and share its configured
|
||||
capacity. Reuse existing integration coverage where it already proves these
|
||||
properties; do not duplicate the full PromptKit runtime test matrix.
|
||||
|
||||
### 4. Update Documentation, Examples, and Attribution
|
||||
|
||||
When implementation lands, update [configuration](../config.md) with the
|
||||
reserved keyword, inheritance behavior, presence/default interactions, and
|
||||
credential implications. Link to upstream for the generic grammar. Update
|
||||
[configuration change recipes](../internal/cli-config.md) where contributor
|
||||
steps change, and the [CLI reference](../cli.md) only if its documented
|
||||
inspection behavior needs clarification.
|
||||
|
||||
Add a small, complete inheritance example under [examples](../../examples/)
|
||||
using valid parent and child backends and existing PromptKit profile syntax.
|
||||
Validate it offline, alongside the maintained local, service, and testing-overlay
|
||||
examples, following the existing example-validation recipe.
|
||||
|
||||
Check the selected release's license and notice files and update the ConfigKit
|
||||
entry in [attribution](../oss/attribution.md), including its commit-pinned source
|
||||
and notice links, under the [OSS policy](../policy/oss.md). The review found no
|
||||
change to ConfigKit's license or dependency declarations; verify the selected
|
||||
artifacts when making the dependency change.
|
||||
|
||||
### 5. Validate and Close the Adoption Unit
|
||||
|
||||
Run targeted configuration and CLI checks, then the normal build and complete
|
||||
offline test suite described in [development](../development.md). Validate
|
||||
changed examples and documentation links and run `git diff --check`. No live
|
||||
provider, paid model call, or new permanent release gate is needed.
|
||||
|
||||
Record validation against the actual implementation revision and mark this
|
||||
roadmap complete only after the criteria below are met. The earlier disposable
|
||||
checkout result establishes that the unmodified suite passed with ConfigKit
|
||||
v0.5.0 and PromptKit v0.11.2; it does not cover newly documented inheritance
|
||||
workflows or substitute for final validation.
|
||||
|
||||
## Completion and Release Treatment
|
||||
|
||||
Adoption is complete when the released dependency is pinned, existing workflows
|
||||
pass, representative inheritance works through loading and runtime wiring,
|
||||
inspection remains secret-safe, and the example, canonical docs, and attribution
|
||||
match the implementation. No PromptKit migration or provider behavior change is
|
||||
required to close this unit.
|
||||
|
||||
The recommended release treatment is a backward-compatible Audita minor release
|
||||
if this unit ships independently: it exposes a new configuration capability
|
||||
while preserving currently valid application settings. Confirm that conclusion
|
||||
against the final compatibility review, particularly the newly reserved
|
||||
`extends` key, under the [release policy](../policy/release.md). Do not select or
|
||||
publish a release as part of roadmap preparation. A later PromptKit migration's
|
||||
profile-format compatibility decision belongs to that separate feature.
|
||||
|
||||
## 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.
|
||||
|
||||
The [recorded overlay results](library-boundary-findings.md#selected-overlay-extension-2026-09-24)
|
||||
prove the representative load, inspection, and HTTP path. Production acceptance
|
||||
requires the same selection to reach both actual LLM roles, with explicit flags
|
||||
winning over overlays and surviving secret references resolved/redacted correctly.
|
||||
The isolated prototype is evidence, not a second supported runtime.
|
||||
|
||||
## Inspection and Invocation Contract
|
||||
|
||||
`process`, `config validate`, and `config print-effective` share file/overlay
|
||||
selection and retained setting overrides. Invocation I/O paths remain process-only.
|
||||
Only explicitly supplied flags override settings. Validation requires an explicit
|
||||
config file; processing and inspection use the selected discovery order. Help is
|
||||
available before configuration loading. All three commands validate selected
|
||||
profiles without requiring a provider call during setup.
|
||||
|
||||
`config print-effective --view settings|profiles|explain` exposes three YAML views:
|
||||
|
||||
- `settings` (default): ConfigKit's redacted effective configuration.
|
||||
- `profiles`: an Audita-owned summary of each selected role's profile, backend,
|
||||
model, temperature, token limit, top-p, timeout, service tier, and reasoning
|
||||
effort where present. Arbitrary extra provider parameters and credentials are
|
||||
omitted; this is a selected-controls view, not every execution input.
|
||||
- `explain`: field paths, sources, and derivation records from ConfigKit, without
|
||||
resolved secret values.
|
||||
|
||||
A ConfigKit snapshot alone does not describe profile-owned controls. Profile
|
||||
inspection must enforce the registered-backend and credential boundary. Diagnostic
|
||||
snapshots use these safe views and preserve overlay/explicit-override provenance.
|
||||
The migration guide explains the intentional replacement of legacy inspection JSON.
|
||||
|
||||
## Integration and Completion Criteria
|
||||
|
||||
ConfigKit and PromptKit form one intentional breaking refactor. Intermediate
|
||||
commits need not build or run. The target contains no temporary old-runtime adapter,
|
||||
compatibility shim, processing gate, dual loader, or automatic legacy conversion.
|
||||
The [combined feature roadmap](library-adoption.md) owns execution/reporting intent;
|
||||
[implementation.md](https://gitea.maximumdirect.net/eric/audita/src/commit/cb405f6/docs/roadmap/implementation.md) alone owns stage order and implementation tasks.
|
||||
|
||||
The final application loads all retained domain settings, assembles both selected
|
||||
profiles, and processes through PromptKit. Controlled HTTP evidence must connect
|
||||
configuration selection to actual requests, domain outcomes, safe diagnostics,
|
||||
and shared finite backend capacity. Maintained examples and one migration guide
|
||||
cover the complete file/flag/environment transition. Obsolete application-owned
|
||||
loading, transport, rendering, and scheduler machinery is removed.
|
||||
|
||||
The combined target is Audita v2.0.0. Release compliance and publication remain
|
||||
last and separate from implementing the refactor. Retention and transcript timestamp
|
||||
changes are not included; the selected retry/repair contract resolves the retry
|
||||
follow-up in [runtime behavior](runtime-behavior.md).
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
- Pin ConfigKit v0.4.0 in production and align Go/toolchain requirements. ConfigKit requires
|
||||
Go 1.25; the combined PromptKit prototype requires Go 1.25.5. Adopting these libraries
|
||||
does not automatically remove Audita's existing YAML dependency used for glossary parsing.
|
||||
- Implement the selected configuration and final PromptKit runtime directly,
|
||||
without temporary runtime adapters, compatibility shims, or process gates.
|
||||
- Enable selected overlays as specified above. Keep imports and secret-directory
|
||||
bootstrap disabled unless a separate concrete requirement justifies them.
|
||||
- Validation and inspection resolve surviving credential references and fail on
|
||||
missing or empty values; no credential-free bypass is planned.
|
||||
- Inspection and diagnostics use the safe selected-profile view and ConfigKit
|
||||
provenance described above. Changed formats are covered by the migration guide.
|
||||
|
||||
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.
|
||||
This heading preserves links from historical adoption documents. The original
|
||||
[overlay plan](https://gitea.maximumdirect.net/eric/audita/src/commit/6ae1d7cd5f548b26de5787372d3f2249eaa4757d/docs/roadmap/configkit.md#selected-overlays-for-testing)
|
||||
is historical; current overlay behavior belongs to [configuration](../config.md).
|
||||
This upgrade preserves that workflow and adds native ConfigKit inheritance
|
||||
without reviving the earlier combined migration plan.
|
||||
|
||||
Reference in New Issue
Block a user