# 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`](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 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](../../cmd/releasekit/woodpecker_test.go)
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.