Files
commandkit/docs/roadmap/configkit-v1.4.0-promptkit-v0.24.0.md

328 lines
20 KiB
Markdown

# 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, native scoped path enumeration, and a public native-inspection adapter |
| 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.
### Public native-inspection adapter
Include a reusable ckconfig adapter in this adoption and the next ckconfig
release. It registers a named configuration scope backed by ConfigKit's native
subtree inspection, reducing application wiring for effective settings, path
discovery, explanations, source evidence, and comparison. Applications retain
configuration acquisition and selection; the adapter supplies standard CLI
integration and delegates domain operations to ConfigKit.
Design this adapter together with the shared native path-enumeration capability.
Demonstrate one application section, such as storage settings, in the maintained
composed example. The section name is illustrative, not a new reserved scope.
Preserve load diagnostics and error evidence through existing reporting and
outcome conventions. A focused inspection does not independently validate a
subtree or make whole-load evidence local to it.
PromptKit uses the shared inspection capability directly. It need not pass
through this new helper if that would require converting its public inspection
type merely to fit the helper. Exact API shape and evidence handoff remain under
discussion in OD-2; acceptance of the feature does not select a new result type,
loader framework, or diagnostics policy.
### 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
- Design the adapter's public API and evidence handoff, then implement scoped
enumeration through the shared configuration provider boundary and the public
ckconfig adapter together. Reuse existing acquisition, diagnostics, comparison,
and outcome conventions where they serve the native capability.
- Wire PromptKit's native enumeration directly through the shared capability;
avoid an extra conversion layer solely to reuse the new adapter.
- Demonstrate registration and inspection of one application subtree, including
comparison and preservation of available diagnostics on failure.
- 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.
- [ ] The public ckconfig adapter exposes a native subtree through the standard
scope commands, with a maintained example and focused coverage of acquisition,
comparison, and diagnostics/error propagation. Its public handoff is documented.
- [ ] 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.
## Resolved decisions
### OD-1: Include the native-inspection adapter in this adoption — closed
Include the helper in the next ckconfig release, as part of this roadmap.
Its implementation overlaps the required native enumeration work; designing both
together provides a concrete second use of the shared boundary and avoids
revisiting that boundary immediately after release. Keep the adapter focused on
standard CLI scopes and direct upstream inspection. Preserve native comparison
semantics for the views accepted by the selected API.
The previous deferral recommendation is superseded. The remaining API discussion
does not reopen whether to include the feature.
## Open Decisions
### OD-2: Public API and diagnostics/error handoff
**Recommendation for discussion: accept the existing typed ConfigKit result
loader plus an explicit subtree path.** A sibling of `FromConfigKit` can obtain
diagnostics and source evidence from the result, select `InspectSubtree(path)`,
and delegate comparison to the native inspection views. On failed loading,
reuse the existing handling of ConfigKit load-error evidence and supported error
identity. This keeps the ordinary application loader reusable and avoids asking
applications to package inspection and diagnostics into a new envelope. The
tradeoff is that a callback returning only an already selected native inspection,
or different root result types across comparison sides, does not fit this typed
loader signature directly. The proposed name and signature are not yet selected.
**Viable alternative: accept an already selected `configkit.Inspection` with
its associated acquisition evidence.** This directly serves callers holding
native views and allows native comparison across different root Go types.
However, the view itself has no diagnostics method, and a failed load may provide
sources and diagnostics without any usable view. The API would need a way to
carry that evidence, adding application wiring or a public handoff type. Evaluate
that complete handoff against the result-and-path approach before selecting it;
do not require callers to reconstruct provenance or stringify structured errors.
For either approach, retain the existing distinction between report evidence
and a returned error. Discuss how native diagnostics reach detailed validation,
ordinary messages, and terminal explanations without duplicate presentation.
Existing error classification remains authoritative; the scope's reporting focus
does not imply that unrelated load failures can be ignored or that validation is
limited to the selected subtree.