diff --git a/.claude/knowledge/deployment-release.md b/.claude/knowledge/deployment-release.md
index 0d9f818..117b04e 100644
--- a/.claude/knowledge/deployment-release.md
+++ b/.claude/knowledge/deployment-release.md
@@ -8,6 +8,8 @@ How code gets to production. Release processes, environment promotion, rollback
 - `release.yml` has **no `on: push: tags` trigger** — this is deliberate. Tags are minted only through the release-please approval flow (or a `create_missing_tag: true` call from the trusted `cd.yml` caller). Do not add a tag-push trigger; it would let anyone pushing a tag bypass the approval flow.
 - GoReleaser (`.goreleaser.yaml`) builds only **darwin + linux on amd64/arm64** — no Windows. Archives are `tar.gz` named `codeguard_v<version>_<os>_<arch>.tar.gz` (note the literal `v` before the version).
 
+- **cosign must stay on the v2 line** (`cosign-release: v2.6.3` pinned in `release.yml`'s cosign-installer step) until the goreleaser `signs` config migrates to the bundle format. cosign v3 — installed by default since cosign-installer v4 — enables `--new-bundle-format`, ignores the `--output-signature`/`--output-certificate` flags in `.goreleaser.yaml`, and fails with `create bundle file: open : no such file or directory` (this killed the v0.8.2 release after a Dependabot installer bump). The `.sig`/`.pem` outputs are a documented verification contract in `docs/security.md`; migrating to the single `.sigstore.json` bundle requires updating `.goreleaser.yaml` (`--bundle=${signature}`) and the docs recipe together, and un-pinning.
+
 ## npm + PyPI packaging (packaging/)
 
 - npm/PyPI ship thin wrappers around the prebuilt GoReleaser binaries — no Go toolchain at install time. `packaging/extract-binaries.sh` downloads release assets, `npm/build.sh` and `pypi/build_wheels.py` assemble artifacts. `publish-npm`/`publish-pypi` jobs in `release.yml` run for stable releases only. See `packaging/README.md`.
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index aed6eb3..1295541 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -176,6 +176,13 @@ jobs:
 
       - name: Install cosign
         uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
+        with:
+          # Pin the v2 line: cosign v3 (the installer default) enables the new
+          # bundle format, which ignores --output-signature/--output-certificate
+          # in .goreleaser.yaml and breaks the documented .sig/.pem verification
+          # contract (docs/security.md). Migrating to the bundle format is a
+          # deliberate follow-up, not a floating-version surprise.
+          cosign-release: v2.6.3
 
       - name: Install syft (SBOM generation)
         uses: anchore/sbom-action/download-syft@e22c389904149dbc22b58101806040fa8d37a610 # v0