# ConfigKit v1.4.0 and PromptKit v0.24.0 adoption Status: agreed adoption direction; implementation pending. Prepared 2026-11-21. This document defines the desired target and accepted scope, not implemented behavior or authorization to publish releases. The [implementation plan](implementation.md) owns execution stages and completion evidence. ## 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. For this adoption, minimize complexity borne by applications first, then complexity maintained by ckconfig. These priorities take precedence over a more tailored operator experience. Prefer native paths, whole-load evidence, and existing outcome handling to extra machinery for more polished subtree reports. 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. The [implementation plan](implementation.md#stage-2-separate-native-path-enumeration-from-metadata-lookup) selects the narrow provider extension and preserves existing custom-provider behavior. This capability is not 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. The adapter shares the native path-enumeration capability. The maintained composed example demonstrates one application section, such as storage settings. 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. Use a small sibling of `FromConfigKit`, with `FromConfigKitSubtree` as the planned helper name. The application supplies a scope name and summary, an explicit `configkit.Path`, and its existing typed loader returning `(*configkit.Result[T], error)` with the same context, selection, input, and state parameters as `FromConfigKit`. The helper returns the existing `Scope[I, S]`. Applications need not assemble diagnostic bundles, translate errors, or create an intermediate inspection representation. The adapter obtains source and diagnostic evidence from the result and selects the native view with `InspectSubtree(path)`. For comparison, it acquires each side's result, selects the same subtree, and calls native `Inspection.Diff`. Share existing acquisition and diagnostic/error handling where useful without introducing a general framework solely to remove repeated lines. Retain whole-load diagnostics and validation outcomes. Successful loads with warnings remain usable; detailed validation retains native findings and sources through the existing presentation conventions. On failed loading, preserve available ConfigKit load-error evidence and supported error identity. Other application errors remain errors without invented ConfigKit findings. Reuse existing classification and duplicate-presentation handling; do not silently filter evidence to the selected subtree, ignore failures elsewhere in the load, or create an independent subtree-validation result. This release targets exposing a section from an ordinary typed application result. An additional entry point for already selected inspection views and accommodation of different root Go types across comparison sides are outside this adoption. An options framework is unnecessary for the single path argument. 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. The accepted API and evidence direction is recorded in OD-2 below; the [implementation plan](implementation.md) owns the exact declaration and internal factoring within that direction. ### 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. ## Compatibility and delivery The adopted configuration uses native `/promptkit` locations for complete settings documents and inspection paths; resource IDs retain their names. Wrapperless fragments and collection fragments use the corresponding upstream input helpers. Removed schema options are replaced by supported inline, source-relative, or explicit-root selection. The upstream migration and format references above own their exact rules. Successful construction alone is not migration evidence: old root-level resources can become application data while disappearing from PromptKit catalogs. Request builders use the upstream input contract for validation replacements, including optional repair budgets. Native resolved repair budgets, including zero, and schema/hash evidence reach reports without a local substitute. The upstream enabled repair default may add a generation call, latency, and usage to application execution. Applications retain resource-version policy and sensitivity decisions for their extension fields. The adoption also retains the intervening PromptKit timeout and cancellation identity corrections. Canonical GoDoc, CLI, consumer, developer, internal, and candidate release guidance should agree with the completed integration. The maintained composed example demonstrates shared loading and the native subtree adapter. Validation protects CommandKit's acquisition, selection, adaptation, reporting, and outcomes; upstream libraries own validation of their domain algorithms. Tests remain offline and credential-independent. The independently versioned integration releases explain the changed provider API and breaking PromptKit migration under the [release policy](../policy/release.md). The coordinated target is released ckconfig followed by ckprompt selecting that release, with the downstream integration advancing at least its minor version. The [release runbook](../release.md) owns preparation and publication operations. Local workspace validation and isolated checks with a local dependency are identified separately from independent validation against released requirements. Any remaining release coordination stays recorded until completed. No core release is needed solely for this adoption. Unrelated core work, including the optional Scriptorium proposal, is not a prerequisite. The [implementation plan](implementation.md) owns dependency migration, focused coverage, candidate preparation, validation commands, and completion records. ## 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. ### OD-2: Typed result loader, subtree path, and existing evidence handling — closed Adopt the result-loader-plus-path approach described under [public native-inspection adapter](#public-native-inspection-adapter). Prioritize application simplicity, then ckconfig implementation simplicity, over tailoring the inspection command's presentation. The complete result already supplies source and diagnostic evidence; accepting the application's ordinary loader avoids a new handoff envelope or application-owned adaptation layer. Use native paths and comparison, retain whole-load diagnostics and failures, and reuse existing reporting and outcome conventions. Keep the helper focused on the selected task; do not add an options framework or another entry point for arbitrary inspection views in this adoption. Supporting preselected views and different root types would require a broader acquisition handoff and is not needed for the selected application workflow. ## Execution status The [staged implementation plan](implementation.md) is ready. No significant product decisions remain open. Implementation and release work remain pending; the plan records their separate completion evidence within this accepted scope.