diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md index 2c987e0..1aa87ff 100644 --- a/docs/roadmap/configkit.md +++ b/docs/roadmap/configkit.md @@ -1,6 +1,6 @@ # ConfigKit Adoption Outline -**Updated:** 2026-11-07 +**Updated:** 2026-11-08 **Status:** Initial outline. The [master roadmap](library-adoption.md) owns the agreed adoption policy, reviewed versions, shared sequencing, and completion. @@ -24,6 +24,25 @@ and [configuration contract](https://forge.maximumdirect.net/base-layer/configki ## Agreed Direction and Migration Work +### Application Schema Version — Resolved + +Use `version: 3` for Audita's application configuration in the next major +release, with a hard cutover. The new contract includes the selected native +PromptKit ownership boundaries and the final stage-specific glossary design. +Finalize that combined schema before release so operators migrate once. + +Reject obsolete application schema versions with migration guidance. Do not +retain version-2 loading, automatic conversion, or dual-schema compatibility. +Update application defaults, examples, and schema validation together when the +new schema is implemented. The no-main-file behavior below remains supported; +embedded defaults must supply the current application version. + +This is Audita's application schema version, independent of library releases and +ConfigKit or PromptKit source headers. It does not require a version header on +every imported fragment. Hard-cutover guidance must explain the actual field and +ownership changes, including glossary-stage configuration, rather than merely +instructing operators to change the version number. + ### Discovery Locations and Import Selection — Resolved An explicit `--config` selects exactly that file. A missing, inaccessible, or @@ -81,12 +100,13 @@ file remain terminal. relationships, or propagate parent edits through already resolved children. Update the current loading-order explanation and realistic integration tests. 3. Migrate genuine source-root control blocks to `config:` where present. - Distinguish application schema versions from source version evidence; do not - impose headers on every fragment merely because the API supports them. + Implement the version-3 application schema and hard cutover above. Distinguish + application schema versions from source version evidence; do not impose + headers on every fragment merely because the API supports them. 4. Use identified collections where records have meaningful identity. ConfigKit upsert replaces matching records in full; inspection follows registered identities through movement, while list diffs remain atomic. Preserve ordinary - ordered/repeated `pipeline.modules` entries and empty-pipeline semantics: + ordered/repeated pipeline stages and explicit empty-pipeline semantics: these express Audita domain behavior, so uniqueness/upsert is inappropriate. 5. Integrate native source discovery and standard inspection instead of retaining equivalent private infrastructure. Adopt source diagnostics, explanation, @@ -121,6 +141,11 @@ configured processing, while incomplete processing reports its missing inputs. Cover absent-main provenance and filesystem context for selected overlays or relative resources without weakening explicit-file error behavior. +Verify acceptance of the final version-3 schema and rejection of obsolete +application versions. Check that no-main-file loading uses version-3 defaults, +and that maintained examples and migration guidance cover the final library +ownership and glossary-stage changes without a legacy compatibility path. + The earlier passing configuration suite is useful baseline evidence, not proof that operators see unchanged semantics. Native semantics and clear migration are the target; preserving incidental old output or validation order is not. @@ -130,19 +155,3 @@ the target; preserving incidental old output or validation order is not. No ConfigKit change request is currently identified. Prefer adapting Audita to its stable supported API. Record any necessary exception with a concrete domain requirement and the smallest integration boundary that satisfies it. - -## Open Decisions - -### Application Schema Version - -**Recommendation:** design the application schema around the target ownership -boundaries, then choose its version to describe that contract. Keeping `version: 2` -is reasonable only if its meaning remains coherent; compatibility with existing -files is not a selection criterion. Do not confuse the application schema version -with the library version or PromptKit's source header. - -**Alternative:** introduce a new application schema version if backend or -credential ownership changes make existing files misleading. It provides a clear -migration boundary; the version alone does not explain the new contract, so -hard-cutover guidance still needs to describe it. Decide from the final schema, -not from dependency version numbers alone, and do not add legacy-schema support. diff --git a/docs/roadmap/glossary-stages.md b/docs/roadmap/glossary-stages.md index 5d69253..05961cd 100644 --- a/docs/roadmap/glossary-stages.md +++ b/docs/roadmap/glossary-stages.md @@ -1,6 +1,6 @@ # Stage-Specific Glossary Inputs -**Updated:** 2026-11-07 +**Updated:** 2026-11-08 **Status:** Accepted scope for the next Audita major release. Initial outline; detailed design and implementation remain pending. The @@ -22,6 +22,9 @@ each pass. This example describes the intended behavior, not a selected configuration syntax. The major-release policy permits a hard cutover; the current single-glossary CLI and pipeline representation do not constrain the target design. +The final representation belongs to the agreed +[version-3 application schema](configkit.md#application-schema-version--resolved), +with one hard cutover covering library adoption and this feature. ## Sequencing and Work Outline diff --git a/docs/roadmap/library-adoption.md b/docs/roadmap/library-adoption.md index 406d631..5f1049c 100644 --- a/docs/roadmap/library-adoption.md +++ b/docs/roadmap/library-adoption.md @@ -61,6 +61,8 @@ They do not select unrelated work in [future.md](future.md). dual formats, transition modes, or legacy-behavior tests merely to ease adoption. Release guidance may require a hard cutover. Domain requirements still guide the target, but existing implementations and contracts are open to redesign. + Audita's application configuration uses `version: 3` with a hard cutover, as + resolved in the [ConfigKit outline](configkit.md#application-schema-version--resolved). - **Remove redundant code:** reducing Audita's maintenance burden is an explicit adoption goal. Retire local mechanisms, settings, wrappers, and tests superseded by supported upstream behavior. Keep the domain logic and integration code that