Record PromptKit checksum investigation findings

docs/roadmap/promptkit-bug-report.md

@@ -1,13 +1,15 @@
 # PromptKit Bug Report: v0.2.0 Module Checksum Mismatch
 
-**Status:** Reproduced by a consumer; cause not yet confirmed.
+**Status:** Stale local module metadata confirmed; cache recovery and test
+isolation follow-up remain pending.
 
 ## Summary
 
-PromptKit cannot add ReleaseKit v0.2.0 as its module-selected maintainer tool
-with Go's normal checksum verification. The `go.mod` bytes served for the
-version produce a checksum that differs from the checksum database's recorded
-`go.mod` checksum. Go stops with a security error.
+PromptKit's adoption attempt encountered stale `go.mod` metadata in the local
+Go module cache. Its checksum differs from the checksum database's recorded
+value, so Go stops with a security error. Fresh downloads through both the
+public proxy and the Git origin verify successfully. The published v0.2.0
+metadata agrees with the checksum database.
 
 ## PromptKit Context
 
@@ -17,15 +19,15 @@ to commit
 [`e030794969fb7787e647a90bbc4eb81bd0610f07`](https://gitea.maximumdirect.net/eric/ReleaseKit/commit/e030794969fb7787e647a90bbc4eb81bd0610f07).
 The attempt used Go 1.26.8 with `GOTOOLCHAIN=local`.
 
-## Reproduction
+## Original Consumer Reproduction
 
-From a Go module, run:
+From a Go module using the affected cache, run:
 
 ```sh
 GOTOOLCHAIN=local go mod download -json gitea.maximumdirect.net/eric/ReleaseKit@v0.2.0
 ```
 
-Go reports:
+The affected cache produces:
 
 ```text
 verifying gitea.maximumdirect.net/eric/ReleaseKit@v0.2.0/go.mod: checksum mismatch
@@ -36,11 +38,11 @@ SECURITY ERROR
 This download does NOT match an earlier download recorded in go.sum.
 ```
 
-The conflicting record is visible in the
+The recorded checksum is visible in the
 [Go checksum database lookup](https://sum.golang.org/lookup/gitea.maximumdirect.net/eric/!release!kit@v0.2.0).
 It records `h1:xN8w1OWjhCwtDxyHVFbKxFWowuEPbMTCZrf0JIIm9pE=` for the module's
-`go.mod`. A diagnostic fetch with `GOSUMDB=off` reports the same v0.2.0 tag
-commit above, archive checksum
+`go.mod`. The consumer's diagnostic fetch with `GOSUMDB=off` reported the same
+v0.2.0 tag commit above, archive checksum
 `h1:EACELngRel4RiulR+Ors56nMZ5fA9orJDyhPxn6UVe4=`, and `go.mod` checksum
 `h1:KmH607Vc/RK/zKrCB96cWh0QZYvkbxBFvtqV+BkKaxs=`. Disabling the checksum
 database was used only to inspect the fetched source; it is not a proposed
@@ -58,12 +60,57 @@ ReleaseKit v0.2.0 as a tool. Go's warning prevents proceeding with the normal
 integrity check. This does not affect PromptKit's runtime API or behavior; the
 tool dependency is for maintainer workflows.
 
-## Investigation Requested
+## Investigation Findings
 
-Please compare the `v0.2.0` tag's `go.mod`, the module proxy's `.mod` response,
-and the checksum database record to determine why their checksums differ. The
-available evidence confirms the mismatch but does not establish whether the
-tagged metadata changed after checksum publication, the proxy is serving
-different metadata, or the checksum record is otherwise inconsistent. Please
-advise on a verified immutable version consumers can select once the cause is
-known.
+Investigation on 2026-10-08 used Go 1.26.8 and isolated temporary module caches.
+The local and authoritative remote tags both identify the commit above.
+
+| Source | `go.mod` checksum |
+| --- | --- |
+| Tagged source, public proxy `.mod`, and module archive's `go.mod` | `h1:xN8w1OWjhCwtDxyHVFbKxFWowuEPbMTCZrf0JIIm9pE=` |
+| Checksum database | `h1:xN8w1OWjhCwtDxyHVFbKxFWowuEPbMTCZrf0JIIm9pE=` |
+| Affected local cached `.mod` | `h1:KmH607Vc/RK/zKrCB96cWh0QZYvkbxBFvtqV+BkKaxs=` |
+
+The affected entry is
+`$GOMODCACHE/cache/download/gitea.maximumdirect.net/eric/!release!kit/@v/v0.2.0.mod`.
+It contains the original dependency-free module declaration. Its modification
+time is 2026-10-07 at 23:35 UTC, preceding the published candidate. The cached
+archive and extracted module contain the correct, dependency-bearing `go.mod`.
+The exact command that created the stale metadata remains unknown.
+
+### Download And Recovery Evidence
+
+- Fresh downloads using `GOPROXY=https://proxy.golang.org` and `GOPROXY=direct`
+  both succeeded with `GOSUMDB=sum.golang.org`, checksum bypass settings cleared,
+  and `GOTOOLCHAIN=local`. Both returned the expected commit and checksums.
+- Copying the affected cached version into an isolated module cache reproduced
+  the exact consumer checksum error.
+- Quarantining only the stale `.mod` in that copied cache allowed the same
+  download to succeed with checksum verification enabled.
+
+These results support continued use of the published v0.2.0 version. The
+investigation left the affected shared cache and repository contents unchanged.
+Recovery was verified in a copied cache; PromptKit's adoption retry remains pending.
+
+### Related Test-Isolation Defect
+
+The workflow tests' [environment helper](../../cmd/releasekit/woodpecker_test.go)
+disables checksum verification for synthetic fixtures and inherits the caller's
+module cache. The version-selection test serves synthetic ReleaseKit versions
+from a local module proxy.
+
+Running `TestWoodpeckerTagDeliveryUsesTaggedModuleVersion` with a disposable
+inherited `GOMODCACHE` passed and left synthetic `v0.2.197` and `v0.2.198`
+metadata in that cache. This confirms that the tests can contaminate a
+developer's module cache. It establishes a related defect; attribution of the
+stale `v0.2.0` entry to a particular test or command remains unconfirmed.
+
+## Recommended Follow-Up
+
+1. Quarantine the affected local `v0.2.0.mod` entry and retry PromptKit's adoption
+   with normal checksum verification. Retain the quarantined bytes as evidence.
+2. Give synthetic module-proxy tests a temporary `GOMODCACHE` owned by the test
+   fixture, with focused regression coverage for cache isolation.
+3. Record the actual cache recovery and consumer retry outcomes here. Preserve
+   the published v0.2.0 tag and checksums; this incident requires no replacement
+   release.