Final Release Review

Final Release Review

Purpose

Audit BASE_TAG...TARGET in one of two modes:

• Pre-release planning: use when the user asks to plan the next release or reviews origin/main before the Changesets version PR exists. Derive the planned release type from the active changesets in TARGET. Do not treat unchanged package versions as a blocker.
• Final candidate: use when the user asks for a final candidate decision or TARGET contains a Changesets-generated version commit. Derive the candidate type from the consumed changesets, then verify the generated package versions and changelogs.

Treat Changesets as the source of truth for patch versus minor. Let $changeset-validation judge whether each changeset uses the correct bump for its package diff; do not independently replace a valid declared bump with a semantic-version judgment from this review. Independently audit runtime compatibility, regressions, packaging, and release risks. Keep documentation readiness separate from the release gate.

Quick start

1. Ensure the repository root is openai-agents-js.
2. Sync remote tags and choose the previous release:

   BASE_TAG="$(.agents/skills/final-release-review/scripts/find_latest_release_tag.sh origin 'v*')"

3. Refresh and resolve the target, defaulting to origin/main:

   git fetch origin main --prune
   TARGET="$(git rev-parse origin/main)"

   Resolve an explicitly supplied tag or ref to its peeled commit with git rev-parse "${TARGET_REF}^{commit}"; use the commit SHA rather than an annotated tag object in the report and compare URL.
4. Resolve review mode independently from the release type:
   1. Honor an explicit user request for pre-release planning or final-candidate review.
   2. Otherwise, use final-candidate mode when TARGET contains a Changesets-generated version commit or package versions have been bumped beyond BASE.
   3. Otherwise, use pre-release planning mode.
5. Resolve the Changesets release state and type:
   1. In planning mode, inspect every active .changeset/*.md file at TARGET except .changeset/README.md.
   2. In final-candidate mode, identify the version commit and read each changeset it deleted from the commit's first parent. Also inspect generated packages/*/package.json and packages/*/CHANGELOG.md changes.
   3. Record every source changeset, package entry, and declared bump.
   4. Set the release-level type to the highest valid declared bump: minor over patch. Account for the fixed package group in .changeset/config.json; do not infer a lower type from an individual package version.
   5. Treat a major entry, malformed frontmatter, mixed active and consumed release sets, or package changes with no applicable changeset as an invalid release state. Do not coerce it to patch or minor.
6. Snapshot the release diff:

   git diff --stat "${BASE_TAG}"..."${TARGET}"
   git diff --dirstat=files,0 "${BASE_TAG}"..."${TARGET}"
   git log --oneline --reverse "${BASE_TAG}".."${TARGET}"
   git diff --name-status "${BASE_TAG}"..."${TARGET}"

7. Audit the diff with references/review-checklist.md and prove or dismiss each candidate against the released contract.
8. Discover and review relevant open documentation PRs using current read-only GitHub state. Do not infer coverage from local branches, titles, or historical context.
9. Report the Changesets release state, ship/block gate, risk assessment, documentation coverage, and conditional minor-release Key Changes draft.

Changesets release policy

• Use active changeset frontmatter in pre-release planning and consumed changeset frontmatter in a generated final candidate as the authoritative release-type declaration.
• Assume required changeset validation passed in CI unless current evidence says otherwise. If its status is unavailable, say so; do not silently rerun the semantic bump classification inside this skill.
• When current evidence shows a missing, malformed, stale, or inconsistent changeset, report the release-preparation defect. In planning mode, give the exact correction without pretending a candidate exists. In final-candidate mode, block until the Changesets inputs and generated outputs agree.
• A target with no releasable package changes and no changesets has release type none. Do not invent a patch release.
• In planning mode, package versions may still match BASE. The Changesets workflow owns the later version bump.
• In final-candidate mode, verify that the consumed release type, generated package versions, fixed-group propagation, changelogs, and version commit agree. A mismatch is blocking.
• A user-supplied patch or minor label is context, not an override for repository Changesets state. Report disagreement and use the repository declaration.
• Distinguish an undocumented migration from the absence of a usable migration or compatibility path. Missing documentation is non-blocking; an actual supported-path break with no usable migration or fallback can block regardless of the declared bump.

Deterministic gate policy

• Default to 🟢 GREEN LIGHT TO SHIP unless at least one blocking trigger is proven.
• Use 🔴 BLOCKED only with concrete release-blocking evidence and an actionable unblock condition.
• Blocking triggers:
  • A confirmed regression or bug introduced in BASE_TAG...TARGET.
  • In final-candidate mode, invalid Changesets state or a mismatch between consumed changesets and generated versions, changelogs, or fixed-group updates.
  • A confirmed breaking public API, protocol, config, or durable-state change with no usable migration, fallback, or compatibility path.
  • A concrete data-loss, corruption, or security-impacting change with unresolved mitigation.
  • A release-critical packaging, build, or runtime path broken by the diff.
• The following are never blocking by themselves:
  • Large diff size, broad refactoring, or many touched files.
  • Speculative "could regress" concerns without evidence.
  • Not rerunning CI checks locally.
  • Missing, incomplete, unmerged, stale, or post-release documentation.
  • Unchanged package version metadata in pre-release planning mode.
• A documentation review may reveal an underlying runtime or compatibility defect. Block only for that defect, not for the documentation state.
• A green gate must still explain important user-visible release surfaces.

Workflow

Prepare and map the diff

• Fetch current remote tags and the target ref. Keep working-tree changes out of the comparison.
• Prefer a user-specified base tag, but still refresh remote tags.
• Assume the target passed repository CI, including $code-change-verification and $changeset-validation, unless told otherwise. Do not rerun routine unit, lint, formatting, type, coverage, or changeset checks by default.
• Use diff stats, directory distribution, commit order, and name status to identify high-risk areas. Read changed tests as behavioral evidence, not as proof by themselves.

Audit contracts and prove findings

• Compare BASE and TARGET rather than reviewing TARGET in isolation.
• For public APIs, compare exports, identity, TypeScript signatures, parameter order, defaults, enums, and documented behavior.
• For packages, compare supported Node.js and TypeScript versions, dependencies, peers, optional dependencies, package exports, published contents, version metadata, and ESM/CJS/type behavior.
• For persisted state, schemas, protocols, config, and environment variables, identify the released durable boundary and verify backward reads or a usable migration path.
• Route runtime changes through the owning reference in .agents/references/README.md and trace required consumers and symmetry axes.
• Promote a candidate only when the diff proves a contract violation, reachable supported-path regression, or concrete user-visible release consideration.
• Use the smallest identical BASE-versus-TARGET public-path or packed-artifact probe when static evidence cannot resolve a decision-relevant question.
• Assign 🟢 LOW to verified safe considerations, 🟡 MODERATE to concrete unresolved regression signals, and 🔴 HIGH to confirmed blockers.
• Include Evidence, Impact, Files, and Action for every risk item. Do not manufacture test or code work for a safe release consideration.