Releasing¶
This is the maintainer runbook for cutting a structured-evaluation
release. It covers the Go module, the JSON Schema, the generated
TypeScript/Zod package, and the docs — all of which ship together.
The core rule: one source of truth, three artifacts¶
The Go structs in rubric/, claims/, and summary/ are the single
source of truth. Two artifacts are generated downstream of them and must
never lag:
Go structs ──► JSON Schema (schema/*.schema.json, via cmd/genschema)
└─► Zod schemas + TS types (ts/src/generated/*, via npm run generate)
A release that changes an exported Go type but ships stale schema or stale
Zod is a drift bug at the package boundary — the exact class of failure
the generated @plexusone/structured-evaluation npm package exists to
prevent. If the Go module gains a field and npm doesn't publish the matching
Zod, a TS consumer's ClaimsReportSchema.parse() silently drops that field
(or, because every object schema is .strict(), rejects the payload). Keep
all three in lockstep.
Publishing npm is part of the release, not an afterthought
v0.13.0 changed several claims types (sourceRole,
minCorroboratingSources, corroborationCategories, maxClaimAge) but
the npm package was never republished — it sat at v0.12.0, silently
missing all of them, until v0.14.0 caught it up. Don't repeat that:
publish npm with every release that touches an exported type.
Release checklist¶
-
Regenerate the JSON Schema after any exported-type change in
rubric,claims, orsummary:Review the diff — it should be additive/expected. Unrelated schema drift signals an accidental type change elsewhere.
-
Regenerate the Zod bindings and bump the package version to match the Go module (e.g. Go
v0.14.0→ts/package.json0.14.0): -
Update the changelog. Edit
CHANGELOG.json(compact single-line leaf objects — the existing style, notjson.dump(indent=2)), then regenerate the Markdown: -
Add release notes. Create
docs/releases/vX.Y.Z.md(follow the most recent release's structure) and add it to theReleasesnav inmkdocs.yml. -
Verify.
go test ./...,golangci-lint run,mkdocs build --strict, andpnpm testints/all clean. -
Push, then tag. Push commits to
originfirst and wait for CI to go green — some checks (cross-platform builds, integration) only run in CI. Only then: -
Publish npm (see below), in lockstep with the tag.
Publishing the npm package¶
The package is @plexusone/structured-evaluation, published under the
@plexusone scope with public access. There is no prepublishOnly /
prepack hook, so pnpm publish ships whatever is already in dist/ —
regenerate and build first.
# 0. Authenticate. pnpm reads npm's ~/.npmrc token; the account needs
# publish rights on the @plexusone scope. Verify with `npm whoami`.
npm login
cd ts
# 1. Regenerate from the current JSON Schema and rebuild dist/.
pnpm run generate
pnpm run build
# 2. Sanity-check the tarball — expect dist/ + package.json only.
pnpm publish --dry-run
# 3. Publish.
pnpm publish --access public
Gotchas¶
- Build before publish. With no prepublish hook, a stale
dist/ships silently. The--dry-runin step 2 prints the exact file list — check it. - Git checks.
pnpm publishverifies a clean working tree on the publish branch by default; publish from the tagged commit. Use--no-git-checksonly to deliberately override. - Lockfile. This package is npm-managed (
package-lock.json, nopnpm-lock.yaml), sopnpm install --frozen-lockfilefails — use plainpnpm install, or rely on the existingnode_modules. - Non-contiguous versions are fine. npm does not require every version to exist. If a release was skipped on npm, just publish the current one — the latest package always reflects the current schema. Don't backfill.
- Publishing is effectively permanent. npm unpublish is restricted after 72 hours. Dry-run first; publish deliberately.
See also¶
ts/README.md— the package's own regeneration and publishing notes.- The repo
CLAUDE.mdConventionssection — the condensed release checklist for automated agents.