Files
commandkit/docs/roadmap/remediation.md

4.5 KiB

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.

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's upgrade-guidance gap is resolved 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 — completed. The ckprompt v0.9.0 note now explains the conditional positional-to-keyed literal migration and links the intervening PromptKit v0.22.0 and v0.23.0 compatibility guidance. The consumer guide points candidate users to that upgrade note. Local links, upstream compatibility fragments, and whitespace checks passed against the selected source.

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, consumer guidance, and release documentation policy.

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 and PromptKit v0.23.0 upgrade guidance.

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.