eric/audita
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

Plan ConfigKit v0.5.0 adoption

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-03 14:23:04 +00:00
parent 6ae1d7cd5f
commit 67519051f1
1 changed files with 176 additions and 157 deletions
Download Patch File Download Diff File Expand all files Collapse all files

333
docs/roadmap/configkit.md
View File

@@ -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 **Status:** Planned; implementation has not begun. The dependency-only review
overlay model is implemented; [implementation evidence](https://gitea.maximumdirect.net/eric/audita/src/commit/cb405f6/docs/roadmap/implementation.md) passed Audita's existing offline test suite in a disposable checkout. That is
records verification. No release has been published. 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 Adopt ConfigKit v0.5.0 as an independently reviewable step before PromptKit
applications in the suite. Consistent configuration conventions are the primary v0.12.0. Use the library's configuration and inheritance conventions while
benefit; reducing application-owned configuration infrastructure is a secondary preserving Audita's domain ownership and existing operator workflows.
benefit and a useful measure of integration quality.
This is an intentional breaking migration. There is no goal of backward At the reviewed Audita revision `6ae1d7cd5f548b26de5787372d3f2249eaa4757d`,
compatibility with existing installations, configuration files, CLI flags, [go.mod](../../go.mod) selects ConfigKit v0.4.2, PromptKit v0.11.2, and Go
environment variables, or configuration-inspection output. Provide a migration 1.25.5. ConfigKit already owns loading, presence, secret resolution, and
guide instead of legacy loaders, aliases, dual operating modes, or an ongoing configuration inspection. Audita's `internal/core/config` supplies typed
compatibility layer. Retain existing syntax only when it independently suits the settings, defaults, derived values, and domain validation; `internal/cli`
new model, not because compatibility requires it. 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 The reviewed upstream release is
selected overlays. Those findings remain historical; the prototype was removed [ConfigKit v0.5.0](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.5.0/docs/releases/v0.5.0.md),
after production integration. The application depends on a versioned module, commit `dc09959cca4e105f49ec316c6d4ba585bd2340bd`. It adds layered underlays,
without a sibling checkout or local module replacement. 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, This roadmap supersedes the completed original adoption plan at this path.
and evidence](library-boundary-findings.md) define the detailed target alongside The [historical roadmap](https://gitea.maximumdirect.net/eric/audita/src/commit/6ae1d7cd5f548b26de5787372d3f2249eaa4757d/docs/roadmap/configkit.md)
this roadmap. Production configuration migration is complete. records that earlier migration. Its coordinated breaking-refactor instructions
and release target do not govern this incremental upgrade.
## Target End State ## Target End State
- ConfigKit owns strict YAML loading, input presence, default application, explicit - Audita uses the released ConfigKit v0.5.0 module, with no local replacement.
override mechanics, recorded resolution, secret references, and safe inspection. PromptKit stays at v0.11.2 throughout this adoption unit.
- Audita owns its configuration types, field meanings, defaults, schema-version - Existing configurations continue through the current file-selection,
policy, file selection, CLI parsing, domain validation, and runtime initialization. overlay, explicit-override, resolution, and validation flow. Retain the
- Adopt ConfigKit's precedence and validation lifecycle rather than reproduce application schema version, CLI interface, and main-file-relative resource
Audita's current per-layer validation and environment-overlay behavior. rules defined in the current contracts.
- General configuration environment overrides are retired. Credentials use typed - Application configuration can use ConfigKit's native sibling `extends`
environment-name secret references; supplied references must resolve according relationships. Audita does not implement a second inheritance resolver,
to ConfigKit's contract. File selection follows the application-owned special backend-only syntax, or an opt-in switch around the library feature.
discovery rules in the selected boundary. - Inherited values participate in presence-aware defaults, domain validation,
- Standardize duration representations, explicit empty/null/zero handling, and secret resolution, and safe inspection just like other effective input.
inheritance on the shared conventions. Express genuine Audita domain rules In particular, inherited backend settings must not be overwritten merely
through the supported resolution and validation APIs. because they were not written directly on the child.
- Retained domain-setting flags and proposal/validation profile flags become - Effective settings and explanations remain useful and secret-safe when
explicit ConfigKit overrides according to the migration inventory. Remove old values are inherited. Preserve the existing Audita-owned inspection formats;
provider/key/retry/concurrency flags and aliases. Credentials use secret references. use ConfigKit's metadata rather than reconstructing provenance from YAML.
- Use ConfigKit's redacted effective output and provide source/explanation access - Canonical documentation and a maintained example explain the adopted
through the selected views below. Legacy JSON inspection is replaced. inheritance behavior. Attribution identifies the exact new upstream source.
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.
Keep Audita's domain capabilities, such as ordered and repeated correction modules, The upstream [configuration contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.5.0/docs/config.md#sibling-inheritance)
expressible in the new model. Their existing configuration spelling is not binding. owns generic inheritance mechanics. The integration must account for three
Transcript/glossary formats, processing algorithms, and output schemas are outside consequences: `extends` is reserved automatically throughout input mappings;
this migration unless later planning identifies a concrete dependency or an relationships resolve after source precedence and before typed decoding; and
explicitly coordinated change. 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 ## Selected Overlays for Testing
Enable ConfigKit's optional selected-overlay feature in the migration. A testing This heading preserves links from historical adoption documents. The original
configuration that selects cheaper, faster LLMs is the initial use case. ConfigKit [overlay plan](https://gitea.maximumdirect.net/eric/audita/src/commit/6ae1d7cd5f548b26de5787372d3f2249eaa4757d/docs/roadmap/configkit.md#selected-overlays-for-testing)
**overlays** modify application settings; PromptKit **execution profiles** still is historical; current overlay behavior belongs to [configuration](../config.md).
own model and generation settings. Keep `profiles_dir`, the PromptKit `profiles/` This upgrade preserves that workflow and adds native ConfigKit inheritance
directory, and proposal/validation profile names unchanged by this terminology without reviving the earlier combined migration plan.
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.