From 16197ae9dd365008a275504bd5b5673ba102f1cf Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 19 Nov 2026 14:54:28 +0000 Subject: [PATCH] Record PromptKit adoption review findings --- docs/roadmap/remediation.md | 58 +++++++++++++++++++++++++++++++++++++ 1 file changed, 58 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..5f92039 --- /dev/null +++ b/docs/roadmap/remediation.md @@ -0,0 +1,58 @@ +# PromptKit Adoption Review Findings + +Review baseline: Scriptorium `c5e54edaa5f6621d504cf510b4b5b5c1e4d1cfd4`, +with the approved PromptKit v0.23.3 pin and ConfigKit v1.2.1. Stage numbers +refer to the [implementation plan](implementation.md). + +## R1: Bound the HTTP timeout regression tests (Stage 4) + +In [handler_test.go](../../internal/adapter/http/handler_test.go), +`TestHandlerDeadlineDuringBuiltInGeneration` runs the handler synchronously +while the fake provider waits on a channel that is released only after the +handler returns. If the operation timeout stops reaching PromptKit, the test +can wait for the unrelated provider/transport timeout or the suite watchdog +instead of promptly failing. The retry- and capacity-wait tests likewise rely +on the behavior being tested to return control. The added +`observeRunnerFailures` helper also sends all failures to a shared, +one-slot channel before allowing each runner invocation to return. An +unexpected failure of the first request in the capacity test can fill that +slot and block the second request from returning the failure the test needs +to inspect. + +Use a test-only fallback deadline or bounded synchronization independent of +the operation budget, and capture the error of the specific observed +invocation without a blocking send shared by concurrent requests. Keep the +real engine and loopback provider, the assertion on +`ErrOperationTimeout`, and the existing status, observation, and +capacity-release checks. This is a test liveness fix, not a new production +timeout or release gate. + +## R2: Describe source-relative message paths without a colocation rule (Stage 7) + +The [upgrade guide](../consumers/upgrading-promptkit.md) instructs users to +keep message files beside their owning definitions. PromptKit resolves +`content_file` against the field's declaring source within its rooted +filesystem; it does not require the file to be in the same directory. A +freshly built Scriptorium binary rendered a valid `content_file: +./messages/request.md` without moving the file beside its framework YAML. +The current wording can lead operators to rearrange valid layouts during +migration. + +Describe source-relative resolution and link to the pinned PromptKit format +contract for containment rules. A colocated file can remain an example, not +a requirement. No loader or path-policy change is needed. + +## R3: Link the Go Text patent grant notice (Stage 7) + +The [attribution entry](../oss/attribution.md#golangorgxtext) for +`golang.org/x/text v0.44.0` links `LICENSE` but omits `PATENTS`. Build +dependency inspection confirms Go Text is part of the executable. Its +selected module contains the separate patent grant at upstream commit +`6070ac32abcdd1670599eeb3ee4d513c8184a513`; PromptKit's attribution for +that same revision links it. The [OSS policy](../policy/oss.md#license-texts-and-upstream-links) +calls for applicable companion texts to be directly reachable. + +Add a `PATENTS` link at the already selected Go Text commit. Retain the +verified local BSD text and existing `LICENSE` link. No separate local +patent notice or change to the project license is needed under the +adopted attribution format.