ReleaseKit/docs/roadmap/promptkit-bug-report.md

PromptKit Bug Report: v0.2.0 Module Checksum Mismatch

Status: Stale local module metadata confirmed; test isolation fixed. Shared-cache recovery and PromptKit's Stage 1 adoption retry succeeded.

Summary

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

PromptKit is adopting ReleaseKit v0.2.0 as a Go tool dependency, following the release's documented module-tooling workflow. The version tag currently points to commit e030794969fb7787e647a90bbc4eb81bd0610f07. The attempt used Go 1.26.8 with GOTOOLCHAIN=local.

Original Consumer Reproduction

From a Go module using the affected cache, run:

GOTOOLCHAIN=local go mod download -json gitea.maximumdirect.net/eric/ReleaseKit@v0.2.0

The affected cache produces:

verifying gitea.maximumdirect.net/eric/ReleaseKit@v0.2.0/go.mod: checksum mismatch
	downloaded: h1:KmH607Vc/RK/zKrCB96cWh0QZYvkbxBFvtqV+BkKaxs=
	go.sum:     h1:xN8w1OWjhCwtDxyHVFbKxFWowuEPbMTCZrf0JIIm9pE=

SECURITY ERROR
This download does NOT match an earlier download recorded in go.sum.

The recorded checksum is visible in the Go checksum database lookup. It records h1:xN8w1OWjhCwtDxyHVFbKxFWowuEPbMTCZrf0JIIm9pE= for the module's 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 consumer workaround.

Expected Behavior

The published v0.2.0 module metadata and the checksum database record should agree, so Go can verify and download the release normally.

Consumer Impact

PromptKit's dependency preparation stops before it can reliably select 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 Findings

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 initially verified in a copied cache. The subsequent shared-cache recovery and consumer retry are recorded below.

Related Test-Isolation Defect

The workflow tests' environment helper disabled checksum verification for synthetic fixtures and inherited 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 confirmed that the tests could contaminate a developer's module cache. It established a related defect; attribution of the stale v0.2.0 entry to a particular test or command remains unconfirmed.

Test-Isolation Resolution

Both synthetic-proxy test families now use a shared environment helper that assigns a fresh test-owned GOMODCACHE and scopes proxy/checksum settings to their Go subprocesses. Source-bootstrap preparation and execution retain separate caches. Tests that build real ReleaseKit source continue to use their prepared dependencies.

The existing tagged-version test now supplies a disposable caller cache and asserts that it remains empty after fixture execution. This regression failed before the fix and passed afterward. All Woodpecker workflow tests passed.

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. 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.

Consumer Recovery Outcome

On 2026-10-08, PromptKit quarantined only the stale shared-cache v0.2.0.mod. The original 58-byte file is retained at /home/eric/releasekit-cache-quarantine-WtdracPk/v0.2.0.mod; no archive, extracted module, or unrelated cache entry was removed.

The retry used Go 1.26.8 with GOTOOLCHAIN=local, GOWORK=off, GOSUMDB=sum.golang.org, and cleared GONOSUMDB/GOPRIVATE bypass settings. go mod download -json gitea.maximumdirect.net/eric/ReleaseKit@v0.2.0 succeeded and returned the published commit and expected checksums:

• Commit: e030794969fb7787e647a90bbc4eb81bd0610f07.
• Archive: h1:EACELngRel4RiulR+Ors56nMZ5fA9orJDyhPxn6UVe4=.
• go.mod: h1:xN8w1OWjhCwtDxyHVFbKxFWowuEPbMTCZrf0JIIm9pE=.

PromptKit then successfully added the v0.2.0 Go tool dependency and prepared its module dependencies with checksum verification enabled. Its readonly, offline go test ./... run passed under the selected local Go installation; the root package's runtime dependency list contains no ReleaseKit import. This completes the previously blocked Stage 1. The remaining adoption stages are still to be implemented. The published v0.2.0 tag remains unchanged.