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

22 KiB

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.

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 and integration ADR 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:

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 enumerates View.Metadata.HistoricalPaths(). The PromptKit adapter 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. 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.

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; exact declaration and internal factoring are implementation-plan details 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.

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.
  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 the accepted result-loader-plus-path API and scoped enumeration through the shared configuration provider boundary together. Reuse existing acquisition, diagnostics, comparison, and outcome conventions where they serve the native capability; finalize the declaration and factoring in the plan.
  • 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 for scoped paths and reports, consumer guide for shared loading and migration, developer guidance 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; 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 for candidate preparation and publication rather than introducing a separate process or new release gates.

Validation and completion checklist

Use the testing policy: 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 using the ordinary typed loader and an explicit path, with a maintained example and focused coverage of acquisition, native comparison, and whole-load 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 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. 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.

Planning readiness

No significant open decisions remain before preparing the implementation plan. The plan should settle the exact Go declarations, shared enumeration capability, internal factoring, example changes, and focused validation within the accepted scope. These are engineering details, not additional product decisions or authority to expand the contracts. Implementation and release work remain pending.