Finalize the PromptKit adoption plan

This commit is contained in:
2026-11-17 00:11:00 +00:00
parent 8513949c20
commit d107b1235a
3 changed files with 368 additions and 60 deletions

View File

@@ -2,9 +2,10 @@
## 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.
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
@@ -41,7 +42,7 @@ 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
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.
@@ -70,40 +71,34 @@ 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
## Targeted end state
### 1. Update the selected dependency
### Dependency and ownership
- 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.
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.
### 2. Add regression coverage through real engine construction
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.
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.
### Configuration outcomes
- 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.
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
@@ -111,33 +106,19 @@ 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
### Compatibility and release readiness
- 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.
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.
### 4. Prepare the integration release and completion records
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.
- 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).
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).