diff --git a/docs/roadmap/configkit-v1.4.0-promptkit-v0.24.0.md b/docs/roadmap/configkit-v1.4.0-promptkit-v0.24.0.md new file mode 100644 index 0000000..7273a81 --- /dev/null +++ b/docs/roadmap/configkit-v1.4.0-promptkit-v0.24.0.md @@ -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.