Files
commandkit/docs/roadmap/remediation.md

70 lines
4.1 KiB
Markdown

# PromptKit v0.23.1 adoption review
## Scope and verification
Reviewed candidate `35e100f` against all five stages of the completed
implementation plan preserved at `b1e7c1ee09bf4fb7845b3b5222ccb448ac7fb468`.
The completed roadmap, plan, and original companion-YAML report are available
in the [adoption snapshot](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b1e7c1ee09bf4fb7845b3b5222ccb448ac7fb468/docs/roadmap).
Stage 1 selects the intended published dependency and attribution revision.
Stages 2 and 3 exercise real constructor failures, preserve error identity and
diagnostics, retain operational/cancellation precedence, and forward native
prepared-report fields. Stage 4 has the upgrade-guidance gap below. Stage 5
retired the completed records with resolution evidence retained in Git history.
Verification used Go 1.27.0 and included the focused constructor/preparation
tests, the complete independent ckprompt suite with `GOWORK=off`, and the root,
ckconfig, and ckprompt workspace suites with `-count=1`. All passed, including
the maintained composed consumer. Module selection, changed Go formatting,
aggregate whitespace, local documentation links/fragments, selected upstream
paths/fragments, and future release-note notice paths were also checked.
## R1 — Explain the positional-literal migration in upgrade guidance
Status — open.
Priority — medium, release-preparation documentation.
### Relevant documentation and requirement
The ckprompt v0.9.0 note identifies the upgrade from PromptKit v0.21.0 to
v0.23.1, describes additive request/report fields, and links to the v0.23.1
patch release's compatibility section. That upstream section describes an
upgrade from v0.23.0. Stage 4 requires relevant native-type compatibility impact
and upgrade guidance for the selected adoption. The release policy also calls
for relevant compatibility impact and consumer action. [Candidate release note](../../integrations/ckprompt/docs/releases/v0.9.0.md),
[consumer guidance](../consumers/guide.md#module-selection), and
[release documentation policy](../policy/release.md#release-documentation-and-preparation).
### Circumstances and actual behavior
Applications can construct native PromptKit request and prepared-report values
in ckprompt callbacks. An application upgrading from the selected v0.21.0
dependency can have positional literals for exported structs whose fields
changed in v0.22.0 or v0.23.0. Those literals can fail compilation after the
dependency upgrade. The local release note and consumer guide omit the needed
migration action, and the linked patch-release guidance omits the intervening
minor-release changes.
A scratch consumer containing a positional `promptkit.PreparedRun` literal
compiled successfully using the pre-adoption module selections at `d107b12`.
The identical source failed with the candidate selections, reporting shifted
field types and too few literal values. `PreparedRun` gained `ParentRunID` as
its first field. Upstream's v0.22.0 and v0.23.0 notes explicitly describe the
exported struct additions and the switch to keyed literals. [PromptKit v0.22.0 compatibility](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/74066167942fcf6f70c112359995739ec9789fa6/docs/releases/v0.22.0.md#efficiency-and-compatibility)
and [PromptKit v0.23.0 upgrade guidance](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/74066167942fcf6f70c112359995739ec9789fa6/docs/releases/v0.23.0.md#compatibility-and-upgrade).
### Expected behavior and remediation
Upgrade guidance should cover the full v0.21.0 → v0.23.1 dependency change.
Add a concise conditional instruction in the ckprompt release note for consumers
using positional literals of affected native structs to migrate those literals
to keyed fields. Link the intervening upstream compatibility guidance. Add a
short pointer from the consumer guide where it introduces the prepared candidate
and native request ownership, keeping upstream type details with PromptKit.
Validate the revised links and wording against the selected source. This
remediation consists of documentation changes. Existing runtime behavior and
regression coverage already satisfy the reviewed adoption paths.