Report source delivery test fixture races

docs/roadmap/promptkit-bug-report.md

@@ -0,0 +1,96 @@
+# PromptKit Bug Report: Race In Source-Delivery Test Fixture
+
+Status: reported for upstream investigation; no implementation changes made.
+
+## Reviewed Release And Environment
+
+- ReleaseKit v0.4.0, commit
+  `b96262eb0ce9c8f2eb3e948a5841db2b799bc91b`, matching the published tag.
+- Go `go1.26.8 linux/amd64`, with `GOTOOLCHAIN=local` and `GOWORK=off`.
+- Discovered while PromptKit evaluated upgrading its release-tool dependency
+  from v0.3.0 to v0.4.0.
+
+## Observed Failure
+
+The upstream race-enabled suite failed in
+`TestReleaseKitSourceDeliveryWorkflowFromTaggedCheckout`. The race detector
+reported shared fixture state accessed by the test goroutine and HTTP-handler
+goroutines without synchronization.
+
+Observed command, run from the ReleaseKit repository root at the commit above:
+
+```sh
+GOTOOLCHAIN=local GOWORK=off go test -race -mod=readonly ./...
+```
+
+The root package and the other reported packages passed; `cmd/releasekit` failed
+with `race detected during execution of test`. `go vet -mod=readonly ./...`
+passed under the same toolchain/environment settings.
+
+For focused investigation, the affected test can be selected with:
+
+```sh
+GOTOOLCHAIN=local GOWORK=off go test -race -mod=readonly -count=1 \
+  ./cmd/releasekit \
+  -run '^TestReleaseKitSourceDeliveryWorkflowFromTaggedCheckout$'
+```
+
+The full-suite command above is the observed reproduction. The focused command
+is a suggested diagnostic; repeatability under that selection has not been
+established. Race detection may depend on scheduling.
+
+## Race Locations
+
+Locations below refer to the reviewed v0.4.0 commit:
+
+| Shared field | HTTP handler access | Test goroutine access |
+| --- | --- | --- |
+| `remoteCommit` | Read in `newDeliveryServer`, `cmd/releasekit/main_test.go:1178` | Written in `cmd/releasekit/releasekit_delivery_workflow_test.go:90` and `:97` |
+| `releaseCreates` | Updated during release creation in `cmd/releasekit/main_test.go:1207` | Read in `cmd/releasekit/releasekit_delivery_workflow_test.go:94` |
+
+See the [workflow test](../../cmd/releasekit/releasekit_delivery_workflow_test.go)
+and [HTTP fixture](../../cmd/releasekit/main_test.go). Representative diagnostic:
+
+```text
+WARNING: DATA RACE
+Read ... newDeliveryServer.func1 ... main_test.go:1178
+Previous write ... TestReleaseKitSourceDeliveryWorkflowFromTaggedCheckout
+    ... releasekit_delivery_workflow_test.go:90
+
+WARNING: DATA RACE
+Write ... newDeliveryServer.func1 ... main_test.go:1207
+Previous read ... TestReleaseKitSourceDeliveryWorkflowFromTaggedCheckout
+    ... releasekit_delivery_workflow_test.go:94
+```
+
+## Assessment And Impact
+
+The workflow test mutates `deliveryServerState.remoteCommit` to simulate a
+hosted-tag mismatch and later restores it. The HTTP fixture reads that field
+while handling requests and updates counters that the test inspects. These
+accesses have no explicit Go synchronization. Subprocess completion does not
+provide the Go synchronization needed for accesses shared with HTTP goroutines.
+
+Source comparison shows the same unsynchronized access pattern in v0.3.0.
+This report does not establish that the failure was introduced by v0.4.0, and
+the v0.3.0 race suite was not rerun for this assessment.
+
+The demonstrated defect is in the upstream test fixture, not production
+publication or delivery code. PromptKit's existing disposable publication
+success/failure fixtures passed using the published v0.4.0 tool. PromptKit uses
+source-tag publication and does not currently use hosted delivery. Accordingly,
+this finding is not a demonstrated blocker to that adoption, but it prevents a
+clean upstream race-suite result and can cause validation noise.
+
+## Requested Outcome
+
+Please synchronize the fixture's cross-goroutine state accesses, including test
+reads and writes, and check the other users of the shared fixture for the same
+pattern. Preserve the mismatched-tag rejection and idempotent source-only
+delivery assertions. A fixture-local synchronization approach is sufficient;
+the evidence does not call for production API changes or additional release
+gates.
+
+Verify the affected workflow under the race detector and rerun the upstream
+race-enabled suite after remediation. Upstream should select the specific
+implementation and any warranted follow-up coverage.