Document ConfigKit and PromptKit adoption roadmap
This commit is contained in:
282
docs/roadmap/configkit-v1.4.0-promptkit-v0.24.0.md
Normal file
282
docs/roadmap/configkit-v1.4.0-promptkit-v0.24.0.md
Normal file
@@ -0,0 +1,282 @@
|
||||
# ConfigKit v1.4.0 and PromptKit v0.24.0 adoption
|
||||
|
||||
Status: agreed adoption direction; implementation pending. Prepared 2026-11-21.
|
||||
This document defines the target and remaining work, not implemented behavior
|
||||
or authorization to publish releases.
|
||||
|
||||
## Purpose and ownership
|
||||
|
||||
Adopt the released upstream capabilities through the existing operator command
|
||||
suite. `ckprompt` should neutrally expose PromptKit's public APIs, using the
|
||||
implementation with the lowest conceptual complexity and the least
|
||||
CommandKit-owned domain machinery. ConfigKit and PromptKit continue to own
|
||||
loading, resolution, validation, preparation, inspection, and comparison.
|
||||
Applications own construction, startup, credentials, and execution workflows.
|
||||
Core owns shared CLI parsing, reporting, and delivery.
|
||||
|
||||
The [architecture policy](../policy/architecture.md) and
|
||||
[integration ADR](../adr/0004-optional-integration-modules.md) govern these
|
||||
boundaries. Native delegation preserves upstream meaning; it does not require
|
||||
removing useful existing CLI projections, filters, or outcome handling.
|
||||
This adoption introduces no additional ordering, copying, concurrency,
|
||||
serialization-stability, or isolation guarantees.
|
||||
|
||||
## Baseline and upstream targets
|
||||
|
||||
Reviewed repository revision: `b1c7962f51eb9e81104a291bc1966a90b4e772a3`.
|
||||
|
||||
| Component | Baseline | Adoption target |
|
||||
| --- | --- | --- |
|
||||
| CommandKit core | v0.7.0 | No core change required by this scope |
|
||||
| ckconfig | v0.9.0; ConfigKit v1.2.1 | ConfigKit v1.4.0 and native scoped path enumeration support |
|
||||
| ckprompt | v0.10.0; PromptKit v0.23.2, ConfigKit v1.2.1, ckconfig v0.9.0 | PromptKit v0.24.0, ConfigKit v1.4.0, and the resulting released ckconfig |
|
||||
| Go | Consumer minimum 1.27.0; release toolchain 1.27.4 | No change required by these upstream releases |
|
||||
|
||||
Adoption covers the intervening ConfigKit v1.3.0 and PromptKit v0.23.3 changes.
|
||||
Use the released versions, not unreleased upstream work. The reviewed release
|
||||
commits are ConfigKit `4a7ae664a6287d71cba20f59c7c5b37b6f05b0a3` and PromptKit
|
||||
`5ea60e9b96651fd7dfcbc7d05b6f43d131df358f`.
|
||||
|
||||
Upstream sources:
|
||||
|
||||
- [ConfigKit v1.3.0: configured secrets bootstrap](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.3.0/docs/releases/v1.3.0.md).
|
||||
- [ConfigKit v1.4.0: typed value access and focused inspection](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/releases/v1.4.0.md).
|
||||
- [PromptKit v0.23.3: timeout and cancellation identities](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.3/docs/releases/v0.23.3.md).
|
||||
- [PromptKit v0.24.0: shared loading, schemas, and preparation](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/releases/v0.24.0.md).
|
||||
- [PromptKit configuration migration](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/configuration-migration.md)
|
||||
and [format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md).
|
||||
|
||||
The pre-adoption review used a temporary copy with only dependency declarations
|
||||
and checksums updated. The ckconfig package and simple-example suites passed.
|
||||
The ckprompt production packages built, but its test package failed to compile
|
||||
because `constructor_outcomes_test.go` uses removed `WithSchemaFile`; seven
|
||||
top-level composed-example tests failed with the old configuration layout.
|
||||
An offline shared-load probe confirmed both automatic reporting of the new
|
||||
prepared hash and repair budget, and the path-listing mismatch described below.
|
||||
These observations establish migration work; they are not final acceptance
|
||||
evidence for the implementation.
|
||||
|
||||
## Targeted end state
|
||||
|
||||
### One application-owned load, existing integration callbacks
|
||||
|
||||
The maintained composed example demonstrates an application configuration with
|
||||
`promptkit.Settings` under `promptkit`, rules composed with `promptkit.Configure`,
|
||||
and a completed ConfigKit result passed directly to `promptkit.NewFromConfig`.
|
||||
The application result serves configuration inspection and the engine serves
|
||||
PromptKit commands through the existing loader callbacks and shared invocation
|
||||
state. This removes the example's separate reconstruction and loading of
|
||||
PromptKit configuration where the shared result supplies that information.
|
||||
|
||||
The example should make source selection, campaign-derived settings, and
|
||||
comparison sides understandable. Any reused result must correspond to the
|
||||
requested selection and relevant application inputs; left and right comparisons
|
||||
still receive their independently selected configurations. Reuse remains an
|
||||
application choice, not a CommandKit cache or a new promise about load counts.
|
||||
Preserve the meaningful selector and lifecycle demonstrations when restructuring
|
||||
the example.
|
||||
|
||||
Select `BundledOpenRouterUnderlay` before the application-owned load when the
|
||||
example intends to include that catalog. `NewFromConfig` does not add it or
|
||||
rerun configuration callbacks. `NewEngine` remains a supported standalone
|
||||
construction path. No CommandKit constructor wrapper is needed for either path.
|
||||
|
||||
`Result.Value` supplies trusted current Go values, potentially including resolved
|
||||
secrets and shared references. It is not a replacement for safe inspection in
|
||||
CLI reports. Continue to use upstream frozen, redacted evidence for configuration
|
||||
output; the application's handoff follows upstream ownership semantics.
|
||||
|
||||
### Native scoped inspection
|
||||
|
||||
PromptKit's configuration inspection now focuses on `/promptkit`. Its
|
||||
`HistoricalPaths()` enumerates that focus, while `Metadata()`, source evidence,
|
||||
and explicit path queries retain whole-load context. For example, a load with
|
||||
`app_name` and `promptkit` should not acquire `/app_name` in the PromptKit path
|
||||
list merely because that path exists in the original load's metadata.
|
||||
|
||||
Currently, [ckconfig's explanation handler](../../integrations/ckconfig/explain.go)
|
||||
enumerates `View.Metadata.HistoricalPaths()`. The
|
||||
[PromptKit adapter](../../integrations/ckprompt/adapters.go) supplies full metadata,
|
||||
so this bypasses upstream's new focused enumeration.
|
||||
|
||||
Provide the narrow capability needed for the shared handler to enumerate native
|
||||
inspection paths. `ckprompt` supplies PromptKit's `HistoricalPaths()` directly;
|
||||
ckconfig uses metadata to describe the returned paths' presence and explicitness.
|
||||
Ordinary whole-result scopes continue to enumerate their native metadata paths.
|
||||
Choose the concrete Go shape during implementation planning, considering the
|
||||
existing [View and provider contracts](../../integrations/ckconfig/contracts.go).
|
||||
Do not turn this small capability into a parallel inspection model.
|
||||
|
||||
Retain the existing CLI filters (`--under`, `--historical`, and `--explicit`) on
|
||||
the supplied enumeration. Preserve native application paths, such as
|
||||
`/promptkit/profiles/0/model`, without rebasing or adding compatibility aliases
|
||||
for the former document layout. Explicit `--path` queries use upstream semantics,
|
||||
including queries outside the focus where upstream supports them. Selecting a
|
||||
scope is not an access-control boundary.
|
||||
|
||||
Continue native comparison and source reporting. Do not filter away upstream
|
||||
ancestor differences or trim the source catalog to manufacture isolation.
|
||||
Focused rendering reports the selected subtree; explicit root queries retain
|
||||
their native whole-document meaning. An absent effective subtree and explicit
|
||||
null retain their upstream distinction and errors through the existing report
|
||||
delivery mechanism. Do not invent an empty configuration to hide absence.
|
||||
|
||||
### Existing commands expose the new upstream evidence
|
||||
|
||||
| Operator task | Existing command | Adoption behavior |
|
||||
| --- | --- | --- |
|
||||
| Inspect a prompt's output contract | `promptkit show prompt ID` | Report native inline schema or schema references and resolved repair budget, including zero |
|
||||
| Preview the completed request | `promptkit show prepared ID` | Report native `message_content_hash`, resolved contract, and prepared schema evidence without model execution |
|
||||
| Discover inputs or validate a request | `promptkit requirements show ID`, `promptkit requirements validate ID` | Preserve upstream effective requirements, including application defaults, and current preparation/error semantics |
|
||||
| Inspect configuration and provenance | `config show`, `sources`, `explain`, `diff`, `validate` with `--scope promptkit` | Use native focused inspection and retain supporting whole-load evidence |
|
||||
| Exercise native smoke checks | `promptkit test ...` | Continue forwarding selected requests and presenting native evidence and errors |
|
||||
|
||||
Prompt and prepared reports already hand native values to the core reporter.
|
||||
Keep that path so new fields appear without a second renderer or a local hash
|
||||
implementation. Existing projections, such as requirements reports, should retain
|
||||
the meaning of the updated native results. Hash semantics, schema resolution,
|
||||
repair behavior, and error identities remain upstream-owned.
|
||||
|
||||
## Work needed
|
||||
|
||||
### Dependency and configuration migration
|
||||
|
||||
1. Update both integration module graphs to ConfigKit v1.4.0 and ckprompt to
|
||||
PromptKit v0.24.0. Tidy checksums and review the resulting graph. Update
|
||||
affected root and module-local attribution entries and pinned source links
|
||||
under the [OSS policy](../policy/oss.md).
|
||||
2. Move complete-document PromptKit settings beneath `promptkit`. Use
|
||||
`SettingsInput` for wrapperless settings fragments and `CollectionInput` for
|
||||
collection fragments where appropriate. Discovery inputs remain root-mounted
|
||||
unless the application sets their destination. Migrate fixture paths,
|
||||
configuration overrides, and report assertions to the native locations;
|
||||
resource IDs themselves do not gain a `promptkit` prefix.
|
||||
3. Replace removed `Config.SchemaDir`, `WithSchemaFS`, and `WithSchemaFile` uses
|
||||
with the applicable upstream configuration and resource contexts. Schema
|
||||
selection supports inline values, source-relative `schema_file`, and
|
||||
`schema_path` under an explicit applicable `schema_root`, including collection
|
||||
roots. There is no implicit working-directory root. Follow upstream's
|
||||
self-contained-schema rules rather than implementing resolution locally.
|
||||
4. Update affected builders or examples from `*OutputContract` to
|
||||
`*OutputContractInput` for `RunRequest.Validation`. Preserve whole-contract
|
||||
replacement. Omitted/null repair budgets resolve to one for `basic`, `json`,
|
||||
and `json_schema`, and zero for `none`; explicit zero disables repair.
|
||||
Do not silently force the previous default in the integration. Document the
|
||||
possible extra generation call, latency, and usage for application execution.
|
||||
5. Account for `PromptOutputInspection.RepairAttempts` becoming a resolved
|
||||
integer. Preserve native zero values and new schema fields in reports.
|
||||
Applications own resource-version policy and sensitivity of extension fields;
|
||||
do not recreate removed PromptKit validation in CommandKit.
|
||||
|
||||
Old root-level resources can be accepted as application data while disappearing
|
||||
from PromptKit catalogs. Migration verification must therefore check selected
|
||||
resources and reports, not just successful engine construction.
|
||||
|
||||
### Adapter and example work
|
||||
|
||||
- Implement scoped enumeration through the shared configuration provider boundary
|
||||
and wire the native PromptKit method directly.
|
||||
- Restructure the composed example around the shared load, with local fixtures
|
||||
and the existing injected client for smoke demonstrations. Update its consumer
|
||||
walkthrough and meaningful tests together.
|
||||
- Retain error causes, independent diagnostics, and available report evidence
|
||||
through existing classification and delivery paths. The included v0.23.3
|
||||
timeout/cancellation corrections should flow through without a local substitute.
|
||||
- Replace the removed-schema-option fixture with a supported fixture for the
|
||||
failure-classification behavior it was testing. Schema-file reads now occur
|
||||
during preparation; do not preserve an obsolete constructor failure merely
|
||||
to keep that test's shape.
|
||||
|
||||
### Documentation and release preparation
|
||||
|
||||
Update the canonical owners as implementation lands: exported GoDoc for changed
|
||||
provider capabilities, [CLI reference](../cli.md) for scoped paths and reports,
|
||||
[consumer guide](../consumers/guide.md) for shared loading and migration,
|
||||
[developer guidance](../development.md) for working examples and dependency
|
||||
alignment, and internal documentation where mechanics change. Link upstream
|
||||
for its formats and rules rather than maintaining another schema reference.
|
||||
|
||||
Prepare integration release notes that identify the breaking PromptKit migration
|
||||
and any changed ckconfig provider API. Select independent versions under the
|
||||
[release policy](../policy/release.md); publish ckconfig before ckprompt, then
|
||||
select that released ckconfig in ckprompt. The downstream integration release
|
||||
advances at least its minor version under the existing alignment policy.
|
||||
No core release is needed solely for this adoption. Unrelated core work, including
|
||||
the optional Scriptorium proposal, is not a prerequisite.
|
||||
|
||||
During development, use the aligned workspace to exercise both local integration
|
||||
changes. Validate ckconfig independently against its published dependencies;
|
||||
after ckconfig publication, validate ckprompt independently against that release.
|
||||
Follow the [release runbook](../release.md) for candidate preparation and
|
||||
publication rather than introducing a separate process or new release gates.
|
||||
|
||||
## Validation and completion checklist
|
||||
|
||||
Use the [testing policy](../policy/testing.md): test CommandKit's adaptation and
|
||||
operator behavior, not upstream domain algorithms. Extend existing coverage
|
||||
where sufficient; compare meaningful report values rather than incidental YAML
|
||||
layout or hash literals. Tests remain offline and credential-independent.
|
||||
|
||||
- [ ] Both integration graphs and affected attribution select the target releases.
|
||||
- [ ] Configuration fixtures and maintained examples use the new layout and
|
||||
supported schema APIs; expected resources remain discoverable.
|
||||
- [ ] The composed example demonstrates application-owned shared loading through
|
||||
existing callbacks, including distinct comparison selections.
|
||||
- [ ] Scoped path enumeration uses upstream's listing; existing CLI filters and
|
||||
metadata descriptions still work. A representative whole-load sibling verifies
|
||||
that the adapter does not substitute full metadata enumeration.
|
||||
- [ ] Explicit paths, source evidence, focused rendering, and comparison preserve
|
||||
native meaning and error handling, including available ancestor evidence.
|
||||
- [ ] Reports preserve returned schema fields, repair-budget zero, and the new
|
||||
message-content hash. Requirements projections preserve updated native evidence.
|
||||
- [ ] Request-builder replacements and supported failure fixtures use the new
|
||||
public APIs; error identity and existing outcome behavior remain covered at
|
||||
CommandKit's boundary.
|
||||
- [ ] Run each affected module's default suite independently and the aligned
|
||||
workspace suites using the developer guide. Record any interim dependency
|
||||
limitation honestly; workspace success alone is not independent-module evidence.
|
||||
- [ ] Canonical documentation, upgrade guidance, and candidate notes match the
|
||||
implemented result; validate local links and documentation diffs.
|
||||
- [ ] Prepare and, when authorized, release ckconfig then ckprompt according to
|
||||
the runbook; record remaining coordination work until completed.
|
||||
|
||||
## Scope retained outside this adoption
|
||||
|
||||
The existing [future work record](future.md) retains output-contract override
|
||||
flags, appended-message flags, secrets-bootstrap commands, and other deferred
|
||||
capabilities. ConfigKit v1.3.0's configured bootstrap and overwrite options remain
|
||||
available to application startup code without a new CommandKit command.
|
||||
This roadmap selects no new commands, engine-construction convenience API,
|
||||
automatic configuration migration, core cache, or application execution workflow.
|
||||
These are scope decisions for this adoption, not additional permanent prohibitions.
|
||||
|
||||
## Open Decisions
|
||||
|
||||
### OD-1: Add a general native-inspection adapter to ckconfig now?
|
||||
|
||||
ConfigKit's non-generic `Inspection` could support a reusable public adapter for
|
||||
applications exposing additional subtree scopes, including native comparison
|
||||
across different root Go types. This is separate from the required narrow path
|
||||
enumeration support used by `ckprompt.ConfigScope`.
|
||||
|
||||
**Recommendation: defer the additional public adapter from this sprint.** The
|
||||
existing typed `FromConfigKit` adapter serves the application's result, and
|
||||
`ckprompt.ConfigScope` serves the engine's inspection. Shared loading itself
|
||||
does not require a third adapter. Keep the required native enumeration capability
|
||||
small, and use the revised example to identify any actual remaining boilerplate
|
||||
before selecting another public contract. The tradeoff is that applications
|
||||
wanting additional native subtree scopes must currently assemble the existing
|
||||
scope/provider contract themselves.
|
||||
|
||||
**Viable alternative: include a focused native-inspection adapter now.** This
|
||||
could standardize useful CLI subtree scopes and avoid repeated acquisition and
|
||||
comparison wiring across applications. It belongs in ckconfig because it serves
|
||||
operator commands, not application-internal configuration access. However, native
|
||||
`Inspection` does not itself carry the result's diagnostics or acquisition
|
||||
errors; the helper's inputs must account for that evidence without becoming a
|
||||
second result type or loader framework. Before selecting this alternative,
|
||||
demonstrate a concrete scope in the maintained example and compare the complete
|
||||
wiring burden and conceptual cost against using the existing provider API.
|
||||
|
||||
This choice does not reopen the agreed requirement to delegate PromptKit path
|
||||
enumeration and explicit queries to the native upstream methods.
|
||||
Reference in New Issue
Block a user