From 6b9ccbf88b13e52e8a60b58065eb63bedcf1ccd8 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 17 Nov 2026 01:03:55 +0000 Subject: [PATCH] Record the PromptKit upgrade guidance gap --- docs/roadmap/remediation.md | 69 +++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 docs/roadmap/remediation.md diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md new file mode 100644 index 0000000..f9a088d --- /dev/null +++ b/docs/roadmap/remediation.md @@ -0,0 +1,69 @@ +# 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.