diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md index f66e11b..bd944de 100644 --- a/docs/roadmap/configkit.md +++ b/docs/roadmap/configkit.md @@ -1,217 +1,354 @@ -# ConfigKit v0.5.0 Adoption +# ConfigKit v1.2.0 Interim Adoption ## Status And Intent -Implemented in Scriptorium's current source on 2026-10-03; release preparation -remains separate work. -This roadmap replaces the completed initial ConfigKit adoption roadmap. That -earlier work and its resolved decisions remain available in Git at -`9849c6b:docs/roadmap/configkit.md`. +Drafted on 2026-11-17. The maintainer selected an interim ConfigKit v1.2.0 +upgrade, followed by ConfigKit v1.2.1 as part of the upcoming PromptKit upgrade. +This roadmap describes that interim target and the changes needed to reach it; +it is not an implementation plan or a claim that the upgrade has landed. The maintainer is adopting ConfigKit across an application suite to standardize -configuration semantics. This update continues that native integration by -adopting ConfigKit v0.5.0 and exposing its automatic sibling inheritance. -An intentional configuration compatibility change is accepted. The target -retains Scriptorium's existing discovery and application path policies rather -than expanding the configuration interface merely because upstream added -library APIs. +configuration semantics. Scriptorium should use the selected ConfigKit's native +loading path, rather than reproduce older processing rules for compatibility. +Configuration migration is acceptable. Application schema and deployment choices +remain Scriptorium's responsibilities under +[ADR 0005](../adr/0005-configkit-boundary.md). -This document retains the target state, rationale, compatibility scope, and -deferred work. Implementation sequencing and completion evidence were recorded -in a separate work plan. The -[architecture policy](../policy/architecture.md), -[configuration contract](../config.md), and -[ADR 0004](../adr/0004-definition-boundary.md) establish the existing application -and framework ownership boundaries. +This replaces the completed v0.5.0 roadmap, preserved at +`ba24b7a879c95e2b306e0d53eb0b45e043e1b29a:docs/roadmap/configkit.md`. +The existing [implementation document](implementation.md) concerns the previous +PromptKit work set and is not the implementation plan for this upgrade. -## Reviewed Baseline And Upstream Target +## Reviewed Baseline And Target -The baseline is Scriptorium v0.15.0 at -`9849c6b`, selecting ConfigKit v0.4.2 and Promptkit v0.11.2. -Application configuration already uses a shared ConfigKit-native -`Document`, defaults factory, recorded resolver, validator, and `Load` -boundary. Runtime conversion uses the resolved document without a second merge. -Execution and the `config validate`, `show`, `sources`, and `explain` -commands share that pipeline. +The reviewed Scriptorium revision is +`ba24b7a879c95e2b306e0d53eb0b45e043e1b29a`. Its selected modules are +`gitea.maximumdirect.net/eric/ConfigKit v0.5.0` and +`gitea.maximumdirect.net/eric/promptkit v0.12.0`, with +`go.yaml.in/yaml/v4 v4.0.0-rc.6`. The consumer Go minimum is 1.25.5; release +validation and hosted builds select Go 1.26.11. -Current source selection is an explicit `--config` file, the first existing -documented system configuration file, or defaults-only loading. File-backed -loads enable explicit imports and one named overlay; explicit application CLI -flags supply override records. Application path values remain relative to the -process working directory. Backend definitions are independent mappings, with -no application-owned inheritance implementation. +Application configuration already uses ConfigKit through `internal/config`: -The upstream target is the published ConfigKit v0.5.0 release at full commit -`dc09959cca4e105f49ec316c6d4ba585bd2340bd`. Canonical references are: +- `Document`, a fresh defaults factory, a recorded resolver, and a validator + define application settings. `Settings` converts the resolved result without + another merge. +- `Load` selects an explicit file or runs a local `os.Stat` loop over two system + configuration paths, falling back to `NoSource`. File-backed loads enable + imports, one selected overlay, and explicit application CLI overrides. +- Application inspection reuses the retained result. `show` and `explain` use + native writers; `sources` projects `id`, `label`, `layer`, and available + `path` into a Scriptorium-owned JSON array. +- Application path values are working-directory-relative. Framework source + selectors are translated separately into ConfigKit values accepted by + PromptKit's current public API. -- [Release notes](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/releases/v0.5.0.md). -- [Configuration contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/config.md). -- [Sibling inheritance](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/config.md#sibling-inheritance). -- [Consumer examples](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/consumers/README.md). +The interim target is `go.maximumdirect.net/configkit v1.2.0` at full commit +`c1c7e87f2cdf77a0cbf3327831ac05578e756b9e`. The locally available v1.2.0 tag and +remotely verified published tag identify that same commit. Canonical references are: -The release retains the Go 1.25 minimum, the existing -`go.yaml.in/yaml/v4 v4.0.0-rc.6` dependency, and the library's -LGPL-3.0-or-later grant. No Promptkit upgrade is needed for this work. +- [Consumer adoption and migration guide](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/consumers/README.md). +- [Configuration contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/config.md). +- [v1.2.0 release note](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v1.2.0.md). +- [v1.0.0 breaking-change inventory](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v1.0.0.md). -An isolated review using a temporary module file passed Scriptorium's existing -test suite and build against v0.5.0. CLI checks confirmed effective backend -inheritance, explicit zero and false replacements, and inheritance explanation. -They also confirmed that a literal `extra_params.extends` accepted by v0.4.2 -fails under v0.5.0. This exploratory evidence informed adoption; the focused -regression coverage and full validation are recorded by the completed -implementation work. +The interim target requires Go 1.27.0 and retains go-yaml v4.0.0-rc.6. PromptKit +stays at v0.12.0 and continues selecting old-path ConfigKit v0.5.0. ConfigKit's +code grant remains LGPL-3.0-or-later. This review examined release notes, public +contracts, Scriptorium's integration, and a focused dependency compatibility +experiment; it did not migrate or validate the full application against v1.2.0. + +## Intervening Release Review + +All published releases after the selected v0.5.0 through v1.2.1 were reviewed. +Notes through v1.2.0 are linked at the interim target revision. The v1.2.1 note +is linked at its own commit and describes deliberately deferred work. + +| Release | Consumer-facing change and adoption consequence | +| --- | --- | +| [v0.6.0](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v0.6.0.md) | Loading/inspection improvements and Go 1.26.0 minimum. Obtain improvements through the dependency; no Scriptorium performance guarantee or benchmark gate follows. | +| [v0.7.0](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v0.7.0.md) | Effective-configuration `Diff` with combined sensitivity protection. Useful future operator functionality, not required for native loading. | +| [v0.7.1](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v0.7.1.md) | Maintainer-tool update; no application runtime or configuration migration. | +| [v0.8.0](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v0.8.0.md) | Input destinations, sequence-item placement, shared source-version checks, and initial identified sequences. Authored imports can use applicable placement; application version policy and Go identity registrations remain opt-in. | +| [v0.9.0](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v0.9.0.md) | Expanded imports/defaults, author-declared collection operations, identified-record inheritance, and dependency-ready ordering. Imports become optional by default; CLI assignment moves after inheritance and typed decoding. Migrate old syntax and lifecycle assumptions. | +| [v0.10.0](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v0.10.0.md) | Native configuration discovery and expanded absent-main loading. Replace application filesystem probing with a ConfigKit search description. | +| [v0.10.1](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v0.10.1.md) | Internal consolidation without public migration; inherit the fixes rather than reproduce the machinery. | +| [v0.10.2](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v0.10.2.md) | Acquisition, cleanup, projection-limit, and collection fixes. Accept corrected upstream diagnostics without adding application limits or recovery machinery. | +| [v1.0.0](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v1.0.0.md) | New module identity, Go 1.27.0, source-root `config` controls, API cleanup, `main` provenance, source lookup, and inspection fixes. These require migration. | +| [v1.1.0](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v1.1.0.md) | Field-level resolution recording within lists and identity-aware history for registered collections. Remove redundant whole-list normalization recording when leaf records cover all edits. | +| [v1.2.0](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v1.2.0.md) | Main-relative layered companions and derived/fallback overlay contexts. Available for future multi-source application needs; ordinary `Load` remains appropriate today. | +| [v1.2.1](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/docs/releases/v1.2.1.md) | Stable go-yaml v4 and loader-plugin adaptation. Deferred to the PromptKit upgrade because of the shared dependency obstacle below. | + +Upstream release-tool changes do not require Scriptorium to adopt ReleaseKit or +copy upstream publication procedures. + +## Dependency Boundary And Sequencing + +There are two distinct compatibility issues, not just import renaming: + +1. Old and vanity ConfigKit paths have different named Go types. `newEngine` + currently constructs old-path `Input` and `Underlay` values for PromptKit. + New-path application overrides and results cannot simply replace those + types at that boundary. +2. Both paths select the same go-yaml v4 module through Go's module graph. + ConfigKit v1.2.1 requires v4.0.0. Old ConfigKit v0.5.0 imports + `go.yaml.in/yaml/v4/plugin/limit`, which is absent from stable v4. + +An isolated temporary module requiring only old ConfigKit v0.5.0 and go-yaml +v4.0.0 failed a package compile check: +`go test -mod=mod -run '^$' gitea.maximumdirect.net/eric/ConfigKit`. +Package setup failed at that missing import; the selected module graph was +verified. This is a compile-time dependency conflict, not evidence of a +Scriptorium runtime failure. Repository source and dependency files were untouched. + +Retaining old-path adapter imports alone cannot bridge v1.2.1, but the selected +v1.2.0 target still declares the same YAML prerelease as the existing stack. +The interim graph deliberately contains both ConfigKit module identities: + +- Application loading, overrides, callbacks, diagnostics, and application + inspection use `go.maximumdirect.net/configkit v1.2.0`. +- Framework construction and captured framework inspection retain + `gitea.maximumdirect.net/eric/ConfigKit v0.5.0` wherever PromptKit v0.12.0's + public API requires its types. +- Both share `go.yaml.in/yaml/v4 v4.0.0-rc.6`. Validate the complete selected + graph, including transitive requirements; agreement of direct requirements + alone is not proof that the application works. + +Use clear local import aliases where both packages are needed. Build each +owner's values directly with its own public types; serialization or a new +cross-version facade is unnecessary. Framework JSON Pointer parsing and writers +must use the old owner's types, while application diagnostics use the new +owner's types. Review shared source DTOs for named layer-type assignments. +Runtime `AppSettings` and application-owned selector values can continue to +cross the existing adapter boundary without transporting a ConfigKit result +into PromptKit. + +The upcoming PromptKit roadmap owns migration to a compatible framework release, +ConfigKit v1.2.1, stable YAML, and removal of old ConfigKit imports and notices +when no longer used. PromptKit v0.23.2 already demonstrates that dependency +combination, but selecting and assessing its full migration remains later work. +This interim upgrade uses published dependencies without local replacements or +copied loaders under the existing architecture policy. + +The two loaders deliberately have different format generations during this +interval. Migrate application documents and their imports to v1.2.0 controls; +framework files selected for PromptKit remain governed by its v0.12.0 contract, +including any old ConfigKit import controls it supports. Do not bulk-rename +controls across all YAML files or parse framework documents with the new +application loader. ## Targeted End State -Scriptorium selects ConfigKit v0.5.0 through its public root package and keeps -the existing single configuration loading lifecycle. Native sibling inheritance -is available in application configuration wherever upstream permits it, without -an application-specific opt-in, collection registry, merging implementation, -or compatibility preprocessing. +### One Native Application Loading Path -The primary user benefit is sharing settings among named backend definitions. -A child backend may inherit its parent's endpoint, API-key environment -reference, provider parameters, concurrency limit, and queue capacity, then -replace selected values. The resolved backend retains its own ID and reaches -Promptkit through the existing deterministic runtime conversion and registration. +`internal/config` consumes the public `go.maximumdirect.net/configkit` package. +All command families use one definition and one completed application load per +selection. Runtime settings come from `result.Config`; inspection uses that +result's captured public views. -ConfigKit owns structural inheritance, value presence, provenance, history, -and explanation. Scriptorium owns its schema, discovery, normalization, -application validation, and runtime mapping. Promptkit continues to own backend -semantics, credential lookup, framework definitions, and execution. +Ordinary `configkit.Load` remains the entry point. A main file with imports and +an overlay does not require artificial underlay groups, embedded defaults, or a +new configuration abstraction. Fresh typed defaults, recorded normalization, +and final domain validation remain definition callbacks. -### Inheritance Semantics And Application Consequences +### ConfigKit-Owned Discovery -The target uses upstream semantics directly; the linked upstream contract -remains the canonical detailed specification: +An explicit `--config` selects `configkit.File` exclusively. Omission selects +`SearchConfig` with ordered `SearchPaths` for +`/usr/local/etc/scriptorium/config.yml` and `/etc/scriptorium/config.yml`. +Delete the `os.Stat` loop and hand-written discovery errors; ConfigKit owns +selection, acquisition, absence, and structured diagnostics. -- An input mapping can use `extends: NAME` to inherit from one named immediate - sibling mapping. Relationships resolve after imports, overlays, and explicit - CLI overrides have assembled the input, and before typed decoding. -- Child mappings recursively combine with their resolved parents. Explicit - zero, false, empty-string, sequence, and null values replace inherited values - according to ConfigKit's rules. Normal schema constraints still apply; null - is not newly accepted for every application field. -- `extends: null` cancels a relationship. Invalid references and cycles fail - through upstream structured diagnostics. Quoting the key does not make it - ordinary data. -- Inherited values count as explicit input. ConfigKit retains inheritance - derivation and displaced history for inspection; Scriptorium's normalization - continues to be recorded after decoding. -- All effective relationships resolve, including definitions a particular - invocation does not select. Inheritance is not lazy backend selection. -- Parent backend entries remain configured backends. They are not abstract - templates and receive the same existing Promptkit registration and validation - treatment as other backends. This adoption adds no template-only collection, - registration suppression, or validation exemption. +These locations are application-selected deployment conventions, not a +compatibility implementation of library processing. ConfigKit does not mandate +one search convention. Its directory presets consider additional filenames and, +in some cases, platform constraints; adopting those or adding user/home/current +directory discovery is a separate application choice. -The maintained backend example demonstrates reusable complete parent settings -and a child with meaningful explicit replacements, including zero queue -capacity and a false dynamic parameter. Parameter names and values are -illustrative and contain no credentials. +Use an optional search and native defaults. Exhaustion contributes no fabricated +source; a selected-file error terminates loading. Enable imports directly: +an absent main has no declarations to traverse, so no existence precheck is +necessary. -### Inspection And Credential Handling +Keep the overlay-name selector and delegate its processing. The current CLI has +no independent overlay filesystem root; without a selected main or explicit +context, an active overlay cannot be located. Report ConfigKit's outcome rather +than create a permanent application prohibition on overlays without a main. +The library supports that combination when an appropriate context is supplied. -`config show` presents the final resolved settings; `config explain` exposes -upstream inheritance origins and history, including consumed directive history -where supported. Both continue to use ConfigKit's native writers and the same -result used by execution. Inheritance creates no additional acquired source: -`config sources` retains its existing application DTO and source-list contract. -No new JSON fields or source layer are needed solely for inheritance. +### Native Source Controls, Imports, And Collections -The maintainer's existing inspection policy remains: ordinary `extra_params`, -including historical values, and `api_key_env` names remain visible. -Scriptorium does not resolve API-key values through ConfigKit, add secret tags -to environment-reference names, or introduce sensitivity heuristics. -Promptkit resolves the selected credential values. Inheriting an environment -reference does not eagerly read it or change credential ownership. +Application sources use root `config` controls, including fragments and selected +overlays where their controls are allowed. Rename genuine old control blocks in +maintained application examples and fixtures. Do not introduce aliases or +runtime rewriting. Nested `config`, and former `configkit` and `_configkit` +names, follow ordinary schema rules rather than a global reserved-key rule. -### Existing Application Contracts +Leave `ImportDefaults` unspecified unless a future application requirement +warrants a choice. In particular: -The target retains current configuration discovery, defaults, explicit imports, -one selected overlay, explicit CLI override mapping, and command prerequisites. -It continues using ordinary `configkit.Load`; the new `LoadLayered` API is -not required to obtain inheritance. +- Imports are optional by default. Indispensable maintained fragments declare + `required: true`; intentionally optional imports may omit it. Remove old + `optional` declarations rather than translate them at runtime. +- Native `path`, `dir`, and `glob` selectors, lists, filters, recursion, + destinations, and item placement are available wherever ConfigKit allows. + Directory filename selection is unrestricted by default; YAML-only examples + should author a pattern. Hidden/symlink discovery follows native defaults, + not application filtering. +- Strict peer composition, dependency-ready assembly, inheritance, and + collection policy remain upstream responsibilities. Sources can declare + `config.sequences` for native identity, append, upsert, and replacement. +- `promptkit_sources` has no application identity field. Add no identity + registration, inferred path identity, duplicate prohibition, or forced + replacement solely for this upgrade. Ordinary unkeyed lists replace across + precedence boundaries; authored collection policy may change that behavior. + CLI lists remain whole-list replacements after decoding. -Application path values, including inherited values, retain their documented -working-directory-relative meaning. The new source-resource contexts do not -implicitly rebase `prompt_dir`, `profile_dir`, `schema_dir`, or -`server.artifact_root`. +Import and overlay containment remain library behavior. Application resource +strings such as `schema_dir`, framework selectors, and HTTP artifact roots are +not source-control paths; ConfigKit does not automatically rebase them. Keep +their working-directory-relative interpretation in this scope. Source-relative +resource behavior would require a separate application choice using public +origin/context APIs. No broader filesystem sandbox is introduced. -Promptkit prompt, profile, and schema files continue to be parsed by Promptkit. -ConfigKit's new directive has no effect on those independently loaded formats -or on HTTP request payloads. Engine-scoped backend capacity coordination and -request independence remain governed by the existing architecture. +### Current Resolution And CLI Lifecycle -## Compatibility And Release Impact +Adopt assembly, inheritance, typed defaults/decoding, explicit CLI assignment, +recorded resolution, credential processing where applicable, and validation in +the current upstream order. Source syntax, composition, inheritance, and decoding +failures cannot be repaired by later CLI overrides. Valid decoded values can +still be replaced before application validation. -ConfigKit now reserves `extends` in every application input mapping, including -dynamic backend `extra_params` and nested provider data. A previously literal -key can fail inheritance validation or be consumed and change effective data. -The reservation can also collide with a named mapping entry such as a backend -ID equal to `extends`. This is a real configuration compatibility change, -not merely a new optional syntax. +Continue mapping only explicitly visited flags to public `Override` records, +with safe labels and supported built-in values. Preserve explicit empty, false, +zero, and allowed null values according to the application schema. Recorded +normalization may change those values through native helpers. -Migration guidance must distinguish structural configuration names from -provider-defined parameter names. Application-owned names can be renamed -where appropriate. A provider-required literal parameter cannot generally be -renamed without changing the provider contract; quoting the key is not an -escape. The selected upstream version has no inheritance opt-out or literal-key -escape. A concrete need for such a parameter should be addressed upstream, -rather than by silently adding a second Scriptorium configuration parser. -This limitation applies to application configuration, not to Promptkit-owned -profile definitions. +Migrate used removed symbols, especially the resolver's generic `Record` call, +to current APIs. Leaf `Normalize` calls now cover individual edits within the +equal-length `promptkit_sources` list; a second whole-list record is unnecessary. +Do not add identity merely to obtain field auditing. Future membership/order +changes use the applicable native container-recording rules. -The reviewed maintained examples and fixtures contain no `extends` keys. -Ordinary configurations without the newly reserved key should retain their -meaning, subject to validation of the integration. +The v1 inventory also includes `EntryInfo`, `Sensitive`, +`SourceVersionModeMainOnly`, `SourceVersionEvidence`, +`EmptyImportSelections`, `DestinationIsFallback`, `SearchPaths`, +`FollowSymlinks`/`IncludeHidden`, `LayerMain`, and +`CodeHistoryLimitExceeded`. Update actual uses and tests; this list does not +require implementing features that Scriptorium does not use. -The intended release is a new minor version, currently v0.16.0, under the -[release policy](../policy/release.md). Its release note should identify the -inheritance feature and reserved-key migration impact. Final version selection -and publication remain release preparation work; this roadmap adds no -publication gate or recurring upstream probe. +### Inspection And Disclosure -## Scope Delivered +Keep `config validate`, `show`, `sources`, and `explain` as the application +inspection surface. Native writers own effective YAML and explanation semantics, +including improved list-field history. Retain the small application source DTO; +its main layer now reports `main`, not `base`. Acquisition order is not +composition order, and load-local source IDs are not durable identities. -- **Dependency and attribution:** selected the published ConfigKit v0.5.0 tag - and updated its exact-commit attribution links without changing unrelated - dependencies or historical release records. -- **Integration and coverage:** retained the single configuration-loading - pipeline and added focused configuration and CLI tests for inheritance, - presence, provenance, source assembly, inspection, runtime conversion, and - Promptkit registration behavior. -- **Maintained example and documentation:** added a runnable backend-inheritance - configuration and updated its README, configuration, CLI, architecture, and - source-internals references while leaving CLI syntax and deferred interfaces - unchanged. -- **Validation and release handoff:** completed the deterministic tests, race - tests, vet, build, diff, link, and example-command checks. Release-note - preparation and publication remain separate work under the existing - development and release policies. +Source lookup, empty optional-selection evidence, and placement metadata remain +available through public results for future focused operator enhancements. +Adoption does not require dumping every source field into the CLI schema. +Existing stream separation, writer-error handling, and application-versus-framework +inspection boundaries remain applicable. -## Deferred Scope +The application document has no raw API-key field. Migration adds no sensitivity +heuristics, redaction of environment names, or redaction of ordinary provider +parameters. API-key values remain the secret requiring protection; PromptKit +owns framework credential handling. The accepted scoped native redaction of +framework configuration inspection is separate from application inspection. +The renamed `Sensitive` hook does not establish a broader disclosure policy. -Ordered source underlays, caller-owned filesystem sources, mapping sources, -and source-resource contexts remain available library capabilities rather than -new Scriptorium interfaces in this adoption. The application has no current -requirement for bundled defaults, extra defaults-file selection, alternative -configuration media, or source-relative application resources. +## Required Changes And Supporting Material -This work does not add underlay flags, embedded configuration bundles, -schema versioning, secret-directory bootstrap, hot reload, or new HTTP -configuration endpoints. These are scope choices for this work set, not -permanent prohibitions on future requested features. +- Update dependency/import identity, used symbols, discovery construction, + normalization records, diagnostics, and application/CLI fixtures. Keep the + PromptKit-owned old types isolated from new application types and retain the + shared YAML prerelease in the selected graph. +- Raise `go.mod`'s consumer minimum to 1.27.0 and select a supported Go 1.27 + release patch for validation and builds. Update current 1.26.11 release + instructions and the hosted image together; no higher consumer patch minimum + or extra platform matrix is implied. +- Migrate application composition examples to `config.imports`, with explicit + requiredness where they depend on a fragment. Demonstrate one useful native + collection composition on the selector list without adding a schema identity + field or universal registration. +- Update configuration/CLI contracts, contributor/toolchain guidance, + architecture dependency descriptions, source/adapter internals, and affected + README/example navigation. Correct obsolete source-internals text about + sorting application backend IDs: those backends were removed and selector + order is meaningful. Preserve accepted ADR decisions and historical notes. +- Update ConfigKit attribution to identify both the new application module at + v1.2.0 and the old module at v0.5.0 still used with PromptKit. Preserve each + revision's applicable notices and exact-commit links, using separate factual + component entries where needed. Leave unchanged PromptKit and YAML selections + and notices accurate; do not prematurely claim stable YAML adoption. Inspect + other affected selected runtime dependencies under the OSS policy. +- Preserve existing faithful LGPL/GPL and other applicable standard texts; + verify changed upstream project notices under the OSS policy. Maintainer + tool requirements may affect module selection without becoming runtime + imports. Their presence alone requires neither Scriptorium tool adoption nor + attribution for tools not incorporated into its distributed material. -## Completion Criteria +The eventual release should be a new minor version under the adopted release +policy: consumer minimum and configuration contracts change. Notes should +explain control-block migration, required imports, CLI ordering, provenance +naming, and the intentional application/framework version split. Exact version +selection and publication remain separate preparation work. -Adoption is delivered: the published dependency is selected; native inheritance -works through the shared execution and inspection pipeline; backend values and -explicit replacements reach the existing runtime boundary; focused tests and a -maintained example demonstrate the integration; and current documentation and -attribution describe the selected version accurately. +## Validation And Completion Criteria -The reserved-key compatibility impact must be explicit, and established -credential visibility, path interpretation, discovery, and framework ownership -must remain intact. No significant decisions remain open within this agreed -scope. +The eventual implementation is complete when: + +- The published graph selects application ConfigKit v1.2.0, old-path ConfigKit + v0.5.0 for PromptKit v0.12.0, and go-yaml v4.0.0-rc.6. It builds with each + boundary using its owner's public types and without a cross-version shim. +- Explicit-file, native discovery, exhaustion/defaults-only, and selected-file + error cases use one native load. Inspection and execution share the + application definition and resolution boundary. +- Representative application tests cover new controls, optional/required + imports, an applicable expanded selector/placement, native collection and + overlay behavior, and changed CLI timing. Distinguish decode failures from + domain validation that CLI values can legitimately affect. +- Leaf normalization, explicit zero/false/null handling, `main` provenance, + and selector-list explanation work through the public result and CLI without + duplicating upstream's exhaustive test matrix. +- Render and representative CLI/HTTP execution continue through PromptKit + v0.12.0, including shared capacity and existing artifact handling. Application + v1.2.0 controls and inspection do not reinterpret framework configuration as + if its independent loader had also been upgraded. +- Documentation, examples, attribution, and toolchains match the implemented + graph and semantics. Run applicable development checks and existing release + target builds. Add no recurring synchronization checks, scanners, provider + probes, performance promises, or publication gates merely for this upgrade. + +No implementation or full target-graph test pass is claimed by this review. + +## Plausible Future Work Outside This Adoption + +The upcoming PromptKit upgrade includes ConfigKit v1.2.1 and stable go-yaml, +unifies ConfigKit's module identity, and retires this temporary framework +boundary. Completing this v1.2.0 roadmap does not require that later work. + +`config diff` could expose native effective-value comparison for two files or +an overlay's impact using safe snapshots, not rendered-text comparison. It is +useful operator work, but not necessary to standardize existing loading semantics +and remains a separately scoped enhancement. + +Layered application underlays, main-relative companions, bundled defaults, +additional discovery locations, source-relative resources, source-detail +inspection, and source-version policy remain available for concrete future +needs. This scope also leaves HTTP configuration inspection, hot reload, and +secrets-directory bootstrap for separate consideration. None is permanently +prohibited by this roadmap. + +## Confirmed Sequencing Decision + +The maintainer selected v1.2.0 as the complete target of this work set so native +application adoption can precede the larger PromptKit migration. The tradeoff is +temporary coexistence of two ConfigKit generations and deferred stable YAML. +A coordinated cutover to both latest dependencies was considered; it avoids +that intermediate state but would combine the larger framework API migration +with application configuration work. The selected scope keeps those work sets +separate and carries an explicit retirement handoff to the PromptKit roadmap. + +No significant product decisions remain open within this interim scope.