Files
commandkit/docs/roadmap/promptkit-v0.23.1.md

125 lines
6.7 KiB
Markdown

# PromptKit v0.23.1 adoption
## Status and objective
Finalized for implementation. Adopt `go.maximumdirect.net/promptkit v0.23.1`
in ckprompt and prepare ckprompt v0.9.0. The
[implementation plan](implementation.md) owns sequencing, concrete steps, and
verification records.
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 [companion-YAML report](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.
## Targeted end state
### Dependency and ownership
ckprompt selects the published PromptKit v0.23.1 module and verified checksums,
with the dependency versions and consumer minimum shown above. Its
[attribution](../../integrations/ckprompt/docs/oss/attribution.md) identifies the
selected upstream revision. The reviewed upstream license and copyright texts
match the v0.21.0 texts.
The existing shared classifier determines outcomes from the upstream error
evidence. CommandKit continues to own adaptation, presentation, and invocation
outcomes. Applications continue to supply engines and native requests through
the existing callbacks.
### Configuration outcomes
Real `promptkit.NewEngine` failures passing through a `FromEngine` catalog
command and `ConfigScope` show, sources, validate, explain discovery, and diff
receive the existing configuration-failure treatment. This includes either
comparison side. Malformed YAML selects status 2 with `yaml.invalid`, source
context, available source and validation reports, typed ConfigKit identity, and
recognition of `promptkit.ErrInvalidConfig` preserved.
Operational constructor failures, independent operational branches joined with
an input failure, and cancellation select status 1 under the existing
[classification contract](../cli.md#configuration-failure-classification).
Maintained integration tests cover these CommandKit adaptation boundaries.
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.
### Compatibility and release readiness
Native request forwarding and prepared-report presentation accommodate the
additive upstream fields, including parent identifiers where supplied. Current
consumer guidance, CLI references, GoDoc, and upstream source links reflect the
selected library and the operations CommandKit invokes.
The release-ready result includes a ckprompt v0.9.0 note describing the dependency
upgrade and corrected constructor-failure classification. Compatibility guidance
distinguishes the prepared candidate from published releases. Independent-module
tests and aligned-workspace composition substantiate the integration.
The sprint ends with a locally committed candidate. Subsequent publication uses
the existing [release procedure](../release.md) under separate authorization.
ckprompt can release independently under the
[module alignment policy](../policy/release.md#commandkit-downstream-dependency-alignment).