Plan interim ConfigKit upgrade

This commit is contained in:
2026-11-17 20:27:12 +00:00
parent ba24b7a879
commit a5d8394313

View File

@@ -1,217 +1,354 @@
# ConfigKit v0.5.0 Adoption # ConfigKit v1.2.0 Interim Adoption
## Status And Intent ## Status And Intent
Implemented in Scriptorium's current source on 2026-10-03; release preparation Drafted on 2026-11-17. The maintainer selected an interim ConfigKit v1.2.0
remains separate work. upgrade, followed by ConfigKit v1.2.1 as part of the upcoming PromptKit upgrade.
This roadmap replaces the completed initial ConfigKit adoption roadmap. That This roadmap describes that interim target and the changes needed to reach it;
earlier work and its resolved decisions remain available in Git at it is not an implementation plan or a claim that the upgrade has landed.
`9849c6b:docs/roadmap/configkit.md`.
The maintainer is adopting ConfigKit across an application suite to standardize The maintainer is adopting ConfigKit across an application suite to standardize
configuration semantics. This update continues that native integration by configuration semantics. Scriptorium should use the selected ConfigKit's native
adopting ConfigKit v0.5.0 and exposing its automatic sibling inheritance. loading path, rather than reproduce older processing rules for compatibility.
An intentional configuration compatibility change is accepted. The target Configuration migration is acceptable. Application schema and deployment choices
retains Scriptorium's existing discovery and application path policies rather remain Scriptorium's responsibilities under
than expanding the configuration interface merely because upstream added [ADR 0005](../adr/0005-configkit-boundary.md).
library APIs.
This document retains the target state, rationale, compatibility scope, and This replaces the completed v0.5.0 roadmap, preserved at
deferred work. Implementation sequencing and completion evidence were recorded `ba24b7a879c95e2b306e0d53eb0b45e043e1b29a:docs/roadmap/configkit.md`.
in a separate work plan. The The existing [implementation document](implementation.md) concerns the previous
[architecture policy](../policy/architecture.md), PromptKit work set and is not the implementation plan for this upgrade.
[configuration contract](../config.md), and
[ADR 0004](../adr/0004-definition-boundary.md) establish the existing application
and framework ownership boundaries.
## Reviewed Baseline And Upstream Target ## Reviewed Baseline And Target
The baseline is Scriptorium v0.15.0 at The reviewed Scriptorium revision is
`9849c6b`, selecting ConfigKit v0.4.2 and Promptkit v0.11.2. `ba24b7a879c95e2b306e0d53eb0b45e043e1b29a`. Its selected modules are
Application configuration already uses a shared ConfigKit-native `gitea.maximumdirect.net/eric/ConfigKit v0.5.0` and
`Document`, defaults factory, recorded resolver, validator, and `Load` `gitea.maximumdirect.net/eric/promptkit v0.12.0`, with
boundary. Runtime conversion uses the resolved document without a second merge. `go.yaml.in/yaml/v4 v4.0.0-rc.6`. The consumer Go minimum is 1.25.5; release
Execution and the `config validate`, `show`, `sources`, and `explain` validation and hosted builds select Go 1.26.11.
commands share that pipeline.
Current source selection is an explicit `--config` file, the first existing Application configuration already uses ConfigKit through `internal/config`:
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.
The upstream target is the published ConfigKit v0.5.0 release at full commit - `Document`, a fresh defaults factory, a recorded resolver, and a validator
`dc09959cca4e105f49ec316c6d4ba585bd2340bd`. Canonical references are: 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). The interim target is `go.maximumdirect.net/configkit v1.2.0` at full commit
- [Configuration contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/config.md). `c1c7e87f2cdf77a0cbf3327831ac05578e756b9e`. The locally available v1.2.0 tag and
- [Sibling inheritance](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/config.md#sibling-inheritance). remotely verified published tag identify that same commit. Canonical references are:
- [Consumer examples](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/consumers/README.md).
The release retains the Go 1.25 minimum, the existing - [Consumer adoption and migration guide](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/consumers/README.md).
`go.yaml.in/yaml/v4 v4.0.0-rc.6` dependency, and the library's - [Configuration contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/config.md).
LGPL-3.0-or-later grant. No Promptkit upgrade is needed for this work. - [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 The interim target requires Go 1.27.0 and retains go-yaml v4.0.0-rc.6. PromptKit
test suite and build against v0.5.0. CLI checks confirmed effective backend stays at v0.12.0 and continues selecting old-path ConfigKit v0.5.0. ConfigKit's
inheritance, explicit zero and false replacements, and inheritance explanation. code grant remains LGPL-3.0-or-later. This review examined release notes, public
They also confirmed that a literal `extra_params.extends` accepted by v0.4.2 contracts, Scriptorium's integration, and a focused dependency compatibility
fails under v0.5.0. This exploratory evidence informed adoption; the focused experiment; it did not migrate or validate the full application against v1.2.0.
regression coverage and full validation are recorded by the completed
implementation work. ## 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 ## Targeted End State
Scriptorium selects ConfigKit v0.5.0 through its public root package and keeps ### One Native Application Loading Path
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.
The primary user benefit is sharing settings among named backend definitions. `internal/config` consumes the public `go.maximumdirect.net/configkit` package.
A child backend may inherit its parent's endpoint, API-key environment All command families use one definition and one completed application load per
reference, provider parameters, concurrency limit, and queue capacity, then selection. Runtime settings come from `result.Config`; inspection uses that
replace selected values. The resolved backend retains its own ID and reaches result's captured public views.
Promptkit through the existing deterministic runtime conversion and registration.
ConfigKit owns structural inheritance, value presence, provenance, history, Ordinary `configkit.Load` remains the entry point. A main file with imports and
and explanation. Scriptorium owns its schema, discovery, normalization, an overlay does not require artificial underlay groups, embedded defaults, or a
application validation, and runtime mapping. Promptkit continues to own backend new configuration abstraction. Fresh typed defaults, recorded normalization,
semantics, credential lookup, framework definitions, and execution. 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 An explicit `--config` selects `configkit.File` exclusively. Omission selects
remains the canonical detailed specification: `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 These locations are application-selected deployment conventions, not a
sibling mapping. Relationships resolve after imports, overlays, and explicit compatibility implementation of library processing. ConfigKit does not mandate
CLI overrides have assembled the input, and before typed decoding. one search convention. Its directory presets consider additional filenames and,
- Child mappings recursively combine with their resolved parents. Explicit in some cases, platform constraints; adopting those or adding user/home/current
zero, false, empty-string, sequence, and null values replace inherited values directory discovery is a separate application choice.
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.
The maintained backend example demonstrates reusable complete parent settings Use an optional search and native defaults. Exhaustion contributes no fabricated
and a child with meaningful explicit replacements, including zero queue source; a selected-file error terminates loading. Enable imports directly:
capacity and a false dynamic parameter. Parameter names and values are an absent main has no declarations to traverse, so no existence precheck is
illustrative and contain no credentials. 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 ### Native Source Controls, Imports, And Collections
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.
The maintainer's existing inspection policy remains: ordinary `extra_params`, Application sources use root `config` controls, including fragments and selected
including historical values, and `api_key_env` names remain visible. overlays where their controls are allowed. Rename genuine old control blocks in
Scriptorium does not resolve API-key values through ConfigKit, add secret tags maintained application examples and fixtures. Do not introduce aliases or
to environment-reference names, or introduce sensitivity heuristics. runtime rewriting. Nested `config`, and former `configkit` and `_configkit`
Promptkit resolves the selected credential values. Inheriting an environment names, follow ordinary schema rules rather than a global reserved-key rule.
reference does not eagerly read it or change credential ownership.
### 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, - Imports are optional by default. Indispensable maintained fragments declare
one selected overlay, explicit CLI override mapping, and command prerequisites. `required: true`; intentionally optional imports may omit it. Remove old
It continues using ordinary `configkit.Load`; the new `LoadLayered` API is `optional` declarations rather than translate them at runtime.
not required to obtain inheritance. - 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 Import and overlay containment remain library behavior. Application resource
working-directory-relative meaning. The new source-resource contexts do not strings such as `schema_dir`, framework selectors, and HTTP artifact roots are
implicitly rebase `prompt_dir`, `profile_dir`, `schema_dir`, or not source-control paths; ConfigKit does not automatically rebase them. Keep
`server.artifact_root`. 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. ### Current Resolution And CLI Lifecycle
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.
## 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 Continue mapping only explicitly visited flags to public `Override` records,
dynamic backend `extra_params` and nested provider data. A previously literal with safe labels and supported built-in values. Preserve explicit empty, false,
key can fail inheritance validation or be consumed and change effective data. zero, and allowed null values according to the application schema. Recorded
The reservation can also collide with a named mapping entry such as a backend normalization may change those values through native helpers.
ID equal to `extends`. This is a real configuration compatibility change,
not merely a new optional syntax.
Migration guidance must distinguish structural configuration names from Migrate used removed symbols, especially the resolver's generic `Record` call,
provider-defined parameter names. Application-owned names can be renamed to current APIs. Leaf `Normalize` calls now cover individual edits within the
where appropriate. A provider-required literal parameter cannot generally be equal-length `promptkit_sources` list; a second whole-list record is unnecessary.
renamed without changing the provider contract; quoting the key is not an Do not add identity merely to obtain field auditing. Future membership/order
escape. The selected upstream version has no inheritance opt-out or literal-key changes use the applicable native container-recording rules.
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.
The reviewed maintained examples and fixtures contain no `extends` keys. The v1 inventory also includes `EntryInfo`, `Sensitive`,
Ordinary configurations without the newly reserved key should retain their `SourceVersionModeMainOnly`, `SourceVersionEvidence`,
meaning, subject to validation of the integration. `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 ### Inspection And Disclosure
[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.
## 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 Source lookup, empty optional-selection evidence, and placement metadata remain
and updated its exact-commit attribution links without changing unrelated available through public results for future focused operator enhancements.
dependencies or historical release records. Adoption does not require dumping every source field into the CLI schema.
- **Integration and coverage:** retained the single configuration-loading Existing stream separation, writer-error handling, and application-versus-framework
pipeline and added focused configuration and CLI tests for inheritance, inspection boundaries remain applicable.
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.
## 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, ## Required Changes And Supporting Material
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.
This work does not add underlay flags, embedded configuration bundles, - Update dependency/import identity, used symbols, discovery construction,
schema versioning, secret-directory bootstrap, hot reload, or new HTTP normalization records, diagnostics, and application/CLI fixtures. Keep the
configuration endpoints. These are scope choices for this work set, not PromptKit-owned old types isolated from new application types and retain the
permanent prohibitions on future requested features. 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 ## Validation And Completion Criteria
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.
The reserved-key compatibility impact must be explicit, and established The eventual implementation is complete when:
credential visibility, path interpretation, discovery, and framework ownership
must remain intact. No significant decisions remain open within this agreed - The published graph selects application ConfigKit v1.2.0, old-path ConfigKit
scope. 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.