From 6508ccc036cd2d964c8527e07afb4b8eaf6b06d5 Mon Sep 17 00:00:00 2001
From: Eric Rakestraw <eric@rakestraw.us>
Date: Sat, 26 Sep 2026 16:14:16 +0000
Subject: [PATCH] Record the upgrade review finding

---
 docs/roadmap/remediation.md | 65 +++++++++++++++++++++++++++++++++++++
 1 file changed, 65 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..c965689
--- /dev/null
+++ b/docs/roadmap/remediation.md
@@ -0,0 +1,65 @@
+# Promptkit Upgrade Review Remediation
+
+## Scope And Status
+
+Review baseline: `e177d7c`, covering implementation commits after `5c3b0cf`.
+This document records an outstanding test-contract issue; it does not authorize
+unrelated implementation changes. No runtime defect or missing planned feature
+was identified in this review. Release preparation remains separate work.
+
+## R1: Remove The Unrequested Context-Identity Invariant
+
+Priority: P3 (low). Status: Open.
+
+Location: `internal/adapter/http/handler_test.go:334–349`,
+`TestHandlerRunTimeoutValidationAndContextMapping`, introduced in `7de2b02`.
+
+The test's `child` field and `(ctx != parent) != tc.child` assertion require
+the exact parent context object for omitted/null/zero timeouts and a distinct
+object for a positive timeout. The requested contract concerns effective
+deadlines and cancellation propagation, not Go interface identity. In
+particular, a harmless derived context that preserves the parent's deadline,
+values, and cancellation would fail the omission cases despite satisfying the
+application contract.
+
+This elevates an incidental implementation choice into a test-enforced
+invariant, contrary to the [agent policy](../policy/agents.md) and
+[testing policy](../policy/testing.md). The current handler's context behavior
+is correct; this is a maintainability issue, not a runtime cancellation bug.
+
+### Required Change
+
+Remove the identity comparison and the identity-only table field. Retain
+behavioral assertions that an earlier parent deadline is not extended and
+parent cancellation reaches execution. For omitted/null/zero values, verify
+that no deadline is introduced when the parent has none. Retain coverage of
+positive deadlines and the distinction between a canceled execution context
+and a provider-attempt timeout while the execution context remains live.
+
+Use the existing runner seam and focused cases; do not introduce a context
+wrapper framework, timer abstraction, new public guarantee, or production
+refactor solely to change this test.
+
+### Completion Criteria
+
+- Tests protect effective deadline/cancellation behavior without requiring
+  context object identity.
+- A semantically equivalent derived context does not fail merely because it
+  is a different object.
+- Existing timeout validation and HTTP outcome coverage remains intact.
+
+## Review Verification
+
+- `go test -race -count=1 ./...` passed, including retry, shared-capacity,
+  deadline, report, definition-conformance, and architecture-boundary tests.
+- `go vet ./...` passed.
+- A native `cmd/scriptorium` build passed, with output outside the repository.
+- The selected dependency is Promptkit v0.11.0 with its intended v2 catalogs.
+- Application code, tests, release automation, and historical releases were
+  not changed during this review.
+
+The runtime ownership boundaries remain as intended: Promptkit owns framework
+formats, execution, retries, and backend admission; Scriptorium owns executable
+adapters, application settings, HTTP artifact policy, deadlines, and terminal
+report presentation. No additional runtime restrictions, durable workflow
+state, or extra release compliance gates were identified in the reviewed diff.