SELF-TEST

Self-test: `jwx-dev-v4:guide` documentation retrieval

This document verifies that the `jwx-dev-v4:guide` skill enables an answering agent to navigate the **scattered** documentation surface — jwx core docs, the examples repo, companion-module docs, and the Go module cache — and synthesize them into correct, compiling jwx code.

The skill is intended for end-users who **do not have any of these repos locally checked out**. It must direct agents to the right source for each question and let them combine sources when one source alone is insufficient.

Documentation sources the skill points at

A passing test confirms agents can effectively use:

1. **jwx core narrative docs** — `https://github.com/lestrrat-go/jwx/blob/develop/v4/docs/*.md` 2. **Go module cache** — `$(go env GOMODCACHE)/github.com/lestrrat-go/jwx/v4@<ver>/` (and the same for any companion module the user has imported) 3. **pkg.go.dev** — `https://pkg.go.dev/github.com/lestrrat-go/jwx/v4/...` and `https://pkg.go.dev/github.com/jwx-go/<companion>/v4` 4. **Examples repo (topical index)** — `https://github.com/jwx-go/examples/blob/develop/v4/README.md` and its linked `*_example_test.go` files 5. **Companion-module own READMEs** — `https://github.com/jwx-go/<companion>` (repo root README)

Prerequisites

• The latest source `agents/plugin/skills/guide/SKILL.md` has been installed and cached. Recipe:

  /plugin uninstall jwx-dev-v4@jwx-v4
  /plugin install jwx-dev-v4@jwx-v4
  /reload-plugins

• Verify cache matches source:

  diff -q agents/plugin/skills/guide/SKILL.md \
    ~/.claude/plugins/cache/jwx-v4/jwx-dev-v4/<version>/skills/guide/SKILL.md

No output = match.

Setup: fresh-context test session

Do **not** rely on the current Claude session that authored the skill. Either:

• Launch a fresh `claude` session in a directory that has **no jwx checkout and no prior context**, or
• Dispatch an `Agent` subagent with `subagent_type: general-purpose` and a self-contained prompt — the subagent inherits tools but not conversation history.

The test agent must have at least: `Skill`, `WebFetch`, `Read`, `Write`, `Edit`, `Bash`. It must not be told the answers; it must be told only the user's question and instructed to use the `jwx-dev-v4:guide` skill.

Required: build a real Go program

For every case, the test agent must **construct a runnable Go program from scratch in a temporary directory** and verify it compiles. This is the load-bearing part of the test — text-only answers are easy to bluff; a `go build` either succeeds or doesn't.

Recipe the agent should follow:

WORKDIR="$(mktemp -d)"
cd "$WORKDIR"
go mod init example.com/jwx-self-test/case-N
# write main.go with all required imports + func main() so it links
# encoding/json/v2 is behind GOEXPERIMENT=jsonv2 on Go 1.26 and in the standard
# library from Go 1.27 on. Probe the toolchain instead of hardcoding a version.
if ! GOEXPERIMENT= go list encoding/json/v2 >/dev/null 2>&1; then
	export GOEXPERIMENT=jsonv2
fi
go mod tidy
go build ./...

The test passes a case only when `go build` exits 0. A successful build proves:

• Every imported package path is real.
• Every `package.Symbol` used exists with a compatible signature.
• Generic call sites have the correct type parameters.

If `go build` fails, the agent iterates: read the error, consult docs again, fix. Up to three fix attempts per case. Report the trajectory.

Network policy

The test agent has network access via `WebFetch` and `go mod tidy`. It must not clone any jwx-related repo (jwx core or companions). For cases that exercise the offline path (Case 5), deny network access entirely after the initial `go mod tidy` and verify the agent recovers via the Go module cache for **both jwx core and the relevant companion** when applicable.

Test cases

Cases are split into two families: **single-source** cases (one doc carries the answer) and **multi-source / index-navigation** cases (the answer requires combining or navigating across sources).

Family A — Single-source retrieval

Case 1 — Custom claim validator (target: `docs/01-jwt.md`)

**User question**: "How do I write a custom validator that checks the `scope` claim contains `read:users` and rejects the token otherwise?"

**Why this requires docs**: SKILL.md doesn't cover `jwt.Validator`/`jwt.WithValidator`. `docs/01-jwt.md` "Use a custom validator" is the source.

**Pass criteria**:

• `go build` passes.
• Code uses `jwt.WithValidator` + `jwt.Validator` (or `jwt.ValidatorFunc`).
• Validator returns a plain `error` (not `jwt.NewValidationError`, which does not exist).
• No fabricated APIs.

Case 2 — Per-recipient JWE headers (target: `docs/03-jwe.md`)

**User question**: "Encrypt a single JWE for two recipients, each with a different `kid` in its per-recipient header. Each recipient must independently decrypt the message."

**Why this requires docs**: SKILL.md only shows single-recipient `jwe.Encrypt`. Multi-recipient assembly + `jwe.WithJSON` + `jwe.WithPerRecipientHeaders` live in `docs/03-jwe.md`.

**Pass criteria**:

• `go build` passes.
• Code uses `jwe.WithJSON()`, `jwe.WithPerRecipientHeaders`, two `jwe.WithKey(...)` calls.
• Both recipients decrypt successfully (if the test agent runs the program).

Case 3 — Framework integration with Echo (target: `docs/21-frameworks.md`)

**User question**: "Echo middleware that pulls a bearer JWT from `Authorization: Bearer …`, verifies against a JWKS endpoint, stashes the verified token on the request context."

**Why this requires docs**: SKILL.md mentions `docs/21-frameworks.md` exists but contains no Echo-specific guidance.

**Pass criteria**:

• `go build` passes (Echo + jwkfetch resolve).
• Middleware calls `jwt.Parse` with `jwt.WithKeySet` from a `jwkfetch.Cache`.
• Token stored on `echo.Context` for handler use.

Family B — Multi-source / index navigation

Case 4 — ML-DSA signing (target: jwx's `docs/10-extensions.md` **plus** the mldsa co