# PromptKit v0.23.1 adoption ## Status and objective Proposed. Adopt `go.maximumdirect.net/promptkit v0.23.1` in ckprompt and prepare ckprompt v0.9.0. The work consists of dependency alignment, CommandKit-level regression coverage, documentation, and release preparation. The targeted result is that malformed PromptKit configuration encountered through an application-owned engine loader receives CommandKit's existing configuration-input classification. Preserve upstream diagnostics and error identity through the integration. Continue delegating configuration semantics and engine construction behavior to PromptKit and ConfigKit. ## Current baseline This roadmap starts from CommandKit commit `bf45a3f` and the released ckprompt v0.8.0 integration. Its [module metadata](../../integrations/ckprompt/go.mod) selects the following dependencies and consumer minimum. | Item | Selected baseline | Adoption target | | --- | --- | --- | | PromptKit | v0.21.0 | v0.23.1 | | ckconfig | v0.8.0 | v0.8.0 | | CommandKit core | v0.6.0 | v0.6.0 | | ConfigKit | v1.2.0 | v1.2.0 | | Go consumer minimum | 1.27.0 | 1.27.0 | ckconfig already owns the shared configuration-error classification function. ckprompt uses that classification for engine acquisition failures and adapts typed ConfigKit diagnostics into CommandKit reports. Core carries the selected outcome through invocation reporting and presentation. The existing status contract belongs to the [CLI reference](../cli.md#outcome-status). The reported failure involves a valid application configuration that imports a malformed PromptKit companion YAML file. Engine construction returns a typed ConfigKit load error wrapped alongside PromptKit's `ErrInvalidConfig` sentinel. With the earlier multi-error wrapper, the shared classifier encounters an independent sentinel branch and selects operational failure, producing status 1 for catalog and configuration-inspection commands. The intended input-error outcome is status 2 with the YAML diagnostic and source context preserved. The user-supplied `promptkit-companion-yaml-exit-status.md` records the original reproduction. Its observed application versions include PromptKit v0.23.0. The constructor wrapper responsible for that behavior also exists in the currently selected v0.21.0. ## Upstream changes and integration scope PromptKit v0.23.1 resolves the constructor wrapping defect at source commit `74066167942fcf6f70c112359995739ec9789fa6`. The wrapper exposes the original cause through a single unwrap and recognizes `ErrInvalidConfig` through `errors.Is`. Typed ConfigKit errors remain reachable through `errors.As`. Genuine joined causes remain available for classification. The adoption can therefore use ckconfig's existing classifier. [Upstream constructor](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/74066167942fcf6f70c112359995739ec9789fa6/engine.go) and [error implementation](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/74066167942fcf6f70c112359995739ec9789fa6/errors.go). The intervening releases add opt-in conversation capture, continuation, coordination, execution-group summaries, operation timeouts, and prepared-run notifications. Applications own engine setup, native request construction, and execution. Existing native request builders provide the integration point for application-selected request capabilities. Prepared reports continue to expose upstream fields through the existing report path. Review those additive shapes for compatibility during the upgrade. [Upstream consumer guidance](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/74066167942fcf6f70c112359995739ec9789fa6/docs/consumers/pkg-promptkit.md). Keep the adoption focused on existing CommandKit operator tasks and the constructor-error fix. Additional CLI capabilities remain subject to the operator needs recorded in [future work](future.md). Preparation and validation documentation should describe the upstream operations actually invoked, including their handling of contexts and request options. ## Work needed ### 1. Update the selected dependency - Update ckprompt's `go.mod` and `go.sum` to PromptKit v0.23.1 using the published module and its checksums. - Review the resolved module graph against the baseline above. Upstream's module requirements support the existing ConfigKit and Go selections. - Check the selected source's license and notices. Update ckprompt's [attribution](../../integrations/ckprompt/docs/oss/attribution.md) to v0.23.1 and its exact source revision. The reviewed upstream license and copyright texts match the v0.21.0 texts. ### 2. Add regression coverage through real engine construction Use local fixtures and `promptkit.NewEngine` through application-owned loader callbacks so the tests include PromptKit's actual public error wrapper. Build on the existing integration tests and configuration-outcome helpers. - Exercise malformed companion YAML through a representative `FromEngine` catalog command and the `ConfigScope` show, sources, validate, explain discovery, and diff paths. Cover comparison-side acquisition where it has a distinct failure path. - Verify the existing usage outcome and status 2, the `yaml.invalid` diagnostic and its source context, and the reports supported by sources and validate. Retain access to `*configkit.LoadError` and recognition of `promptkit.ErrInvalidConfig` on the propagated error. - Cover an operational constructor failure and genuine mixed causes so the sentinel's presence does not turn operational failures into usage failures. Include cancellation using the existing cancellation contract and test helpers, retaining status 1 and the cancellation cause. - Confirm that the existing classifier and diagnostic adapters handle these upstream errors. Scope any implementation adjustment to a demonstrated integration failure found during this work. The review already exercised real constructor failures against v0.23.1 using temporary module selection. Catalog and all five configuration operations returned status 2 for malformed YAML. Typed identity and mixed-cause classification were preserved. Maintained regression coverage is the remaining work needed to keep that integration behavior checked in the repository. ### 3. Validate compatibility and update documentation - Run ckprompt's complete default suite independently against its published dependency selections with `GOWORK=off`. - Exercise the aligned local workspace and maintained composed consumer for the changed integration paths, following the [developer guide](../development.md#documentation-validation). The review's temporary v0.23.1 selection passed the independent ckprompt and composed-consumer suites. - Review native request and report use for the additive upstream fields, including prepared-run parent identifiers where applicable. Keep tests focused on CommandKit's forwarding and presentation responsibilities. - Update the [consumer guide](../consumers/guide.md), relevant [CLI reference](../cli.md) upstream links, and affected GoDoc to match the selected dependency and existing integration behavior. Use brief integration guidance and upstream references for application-owned capabilities. ### 4. Prepare the integration release and completion records - Prepare `integrations/ckprompt/docs/releases/v0.9.0.md`, explaining the PromptKit upgrade and corrected constructor-failure classification, with the release navigation required by the existing policies. - Update current compatibility documentation for the prepared ckprompt version at the appropriate release-preparation point. Distinguish prepared and published versions in completion records. - Record completed work and verification. Retire this roadmap and the resolved companion-YAML report when their work is complete, preserving any unfinished items in [future work](future.md) and repairing affected references. - Follow the existing [release procedure](../release.md) when publication is authorized. ckprompt can release independently under the [module alignment policy](../policy/release.md#commandkit-downstream-dependency-alignment).