From 8513949c205036756dd9e723c280082076dff5e7 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 16 Nov 2026 21:12:17 +0000 Subject: [PATCH] Plan PromptKit v0.23.1 adoption --- docs/roadmap/promptkit-v0.23.1.md | 143 ++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 docs/roadmap/promptkit-v0.23.1.md diff --git a/docs/roadmap/promptkit-v0.23.1.md b/docs/roadmap/promptkit-v0.23.1.md new file mode 100644 index 0000000..264c9ba --- /dev/null +++ b/docs/roadmap/promptkit-v0.23.1.md @@ -0,0 +1,143 @@ +# 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).