# PromptKit Bug Report: v0.2.0 Module Checksum Mismatch

**Status:** Stale local module metadata confirmed; cache recovery and test
isolation follow-up remain pending.

## 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`](https://gitea.maximumdirect.net/eric/ReleaseKit/commit/e030794969fb7787e647a90bbc4eb81bd0610f07).
The attempt used Go 1.26.8 with `GOTOOLCHAIN=local`.

## Original Consumer Reproduction

From a Go module using the affected cache, run:

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

The affected cache produces:

```text
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](https://sum.golang.org/lookup/gitea.maximumdirect.net/eric/!release!kit@v0.2.0).
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 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.