Plan PromptKit v0.23.1 adoption
This commit is contained in:
143
docs/roadmap/promptkit-v0.23.1.md
Normal file
143
docs/roadmap/promptkit-v0.23.1.md
Normal file
@@ -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).
|
||||
Reference in New Issue
Block a user