OmniRoute/docs/ops/RELEASE_CHECKLIST.md

title, version, lastUpdated

title	version	lastUpdated
Release Checklist	3.8.2	2026-05-13

Release Checklist

Last updated: 2026-05-13 — v3.8.0 Streamlined release flow that leverages Claude Code skills for automation.

Manter a fila/branch verdes entre releases: veja RELEASE_GREEN.md (família /green-prs + npm run check:release-green + /babysit + nightly). Rodar periodicamente — e principalmente antes deste checklist — faz a release PR nascer verde.

TL;DR

# 1. Bump version + generate CHANGELOG (skill)
/version-bump-cc patch    # or minor/major

# 2. Run quality gate locally
npm run check              # lint + tests
npm run test:coverage      # full coverage gate (75/75/75/70)

# 3. Build & smoke
npm run build
npm run test:e2e           # optional but recommended

# 4. Generate release (skill)
/generate-release-cc

# 5. Deploy (skill)
/deploy-vps-both-cc        # or akamai-cc / local-cc

# 6. Capture release evidences (skill)
/capture-release-evidences-cc

Detailed Checklist

Pre-release

• All PRs targeted to this release are merged to release/vX.Y.0
• All open Linear/issue items for this version are closed or pushed to next milestone
• CI green on release/vX.Y.0 branch
• No TODO(release) markers in code: grep -r "TODO(release)" src/ open-sse/
• Docker base image up to date (currently node:24.15.0-trixie-slim)

Version & Changelog

• Run /version-bump-cc <patch|minor|major> (Claude Code skill)
  • Bumps package.json, electron/package.json
  • Regenerates CHANGELOG.md from git commits since last tag
  • Updates README.md badges
• Manually review CHANGELOG.md and clean up commit messages if needed
• Ensure the latest semver section in CHANGELOG.md equals package.json version
• Keep ## [Unreleased] as the first changelog section for upcoming work
• Update docs/openapi.yaml → info.version must equal package.json version

Code Quality

• npm run lint — 0 errors (warnings are pre-existing)
• npm run typecheck:core — clean
• npm run typecheck:noimplicit:core — clean (strict)
• npm run check:cycles — no circular deps
• npm run check:any-budget:t11 — within budget
• npm run check:route-validation:t06 — clean
• npm run check:node-runtime — supported floor met (>=20.20.2 <21, >=22.22.2 <23, >=24.0.0 <25)

Testing

• npm run test:unit — pass
• npm run test:vitest — pass (MCP server, autoCombo, cache)
• npm run test:coverage — gate 75/75/75/70 satisfied (statements/lines/functions/branches)
• npm run test:integration — pass (if changes touch DB / handlers)
• npm run test:combo:matrix — pass (combo strategy matrix: proves all 17 routing strategies' selection decisions deterministically; run when touching combo routing, strategy resolution, or fallback logic)
• RUN_COMBO_LIVE=1 npm run test:combo:live — optional/manual (gated real-upstream smoke; sources a read-only DB snapshot from VPS root@192.168.0.15; hits real providers, costs credits; never runs in CI; skips cleanly without the gate)
• npm run test:combo:live:vps — optional/manual (Phase-3 VPS live smoke: 7 HTTP scenarios against the live .15 server via plain Node ESM; requires ssh root@192.168.0.15; creates/deletes only __live_test__* combos; hits real providers; never runs in CI)
• npm run test:e2e — pass (UI changes)
• npm run test:protocols:e2e — pass (MCP/A2A changes)
• npm run test:ecosystem — pass

Hooks (Husky validated)

Husky hooks live in .husky/ and run automatically on git operations.

• pre-commit: npx lint-staged + node scripts/check/check-docs-sync.mjs + npm run check:any-budget:t11
• pre-push: currently disabled (commented out). When re-enabled, runs npm run test:unit.
  • Run npm run test:unit manually before pushing release branches.

If a hook fails: fix the underlying issue, don't bypass with --no-verify.

Conventional Commits

All release-bound commits must follow type(scope): subject format.

Valid types: feat, fix, refactor, docs, test, chore, perf, style, ci

Valid scopes: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills, cloud-agent, guardrails, compression, auto-combo, resilience, providers, executors, translator, domain, authz

Breaking changes: add BREAKING CHANGE: footer or ! after the scope (e.g. feat(api)!: drop /v0).

Documentation

• npm run check:docs-sync passes (auto-run by pre-commit)
• npm run check:docs-all passes (umbrella: docs-sync + docs-counts + env-doc-sync + deprecated-versions + doc-links)
• npm run check:env-doc-sync exits 0 — code ↔ .env.example ↔ docs/reference/ENVIRONMENT.md env contract is intact
• npm run check:doc-links exits 0 — no broken internal markdown references after restructuring
• docs/architecture/ARCHITECTURE.md reviewed for storage/runtime drift
• docs/guides/TROUBLESHOOTING.md reviewed for env var and operational drift
• If .env.example changed: docs/reference/ENVIRONMENT.md updated
• If new feature has a UI: docs/guides/USER_GUIDE.md mentions it
• If new feature has API: docs/reference/API_REFERENCE.md + docs/openapi.yaml updated
• If new feature is a module: dedicated docs/<MODULE>.md exists
• If breaking change: docs/guides/TROUBLESHOOTING.md has migration note

i18n

• npm run i18n:check exits 0 — translation state (.i18n-state.json) in sync with source docs (no drifted sources in strict mode; warn-mode advisory is acceptable for last-minute doc touch-ups, but should be 0 before tagging)
• npm run i18n:check-ui-coverage exits 0 — every UI locale at or above the 80% coverage floor
• npm run i18n:sync-ui:dry reports 0 missing keys across all 42 locales
• If source English docs changed, run npm run i18n:run (requires OMNIROUTE_TRANSLATION_API_KEY in .env) before tagging
• Translation contributions can be deferred to next release if minor (track in CHANGELOG)

Database Migrations

• If src/lib/db/migrations/ has new files:
  • Each migration is idempotent (CREATE TABLE IF NOT EXISTS, etc.)
  • Migrations wrapped in transactions
  • Numbered correctly (no gaps in sequence)
• Test on fresh install: delete ~/.omniroute/omniroute.db and run npm run dev
• Test on existing install: backup DB, run migration, verify schema
• WAL files (-wal, -shm) handled correctly if migration rewrites tables

Provider Catalog (Zod-validated)

• src/shared/constants/providers.ts Zod schema valid at load time
  • All providers have required fields (id, label, kind, etc.)
  • freeNote provided for new free providers
  • OAuth providers have oauthConfig registered in src/lib/oauth/constants/oauth.ts
• If new provider added: corresponding executor in open-sse/executors/
• If non-OpenAI format: translator in open-sse/translator/
• Models registered in open-sse/config/providerRegistry.ts
• Unit tests in tests/unit/ cover provider classification and routing

Desktop (Electron)

If electron/ changed:

• npm run electron:smoke:packaged passes
• Builds tested for at least one of :win, :mac, :linux
• Code signing certs not expired (if signing)
• electron/package.json version matches root package.json
• Auto-update channel pointer updated if releasing to stable

Build Layout

The repository uses three distinct output directories — never mix them up:

Directory	Purpose	Tracked?
src/	Application source (TypeScript / TSX)	Yes
.build/	Build intermediates — next build output (distDir)	No (gitignored)
dist/	Shippable npm bundle — assembled by assembleStandalone	No (gitignored)

Operator note: the remote VPS image directory remains /usr/lib/node_modules/omniroute/app/. Only the in-repo build output moved (app/ → dist/). The deploy skills rsync dist/ contents into the remote app/ dir — no VPS path changes required.

Single-build flow:

npm run build:release
  └─ rm -rf .build dist          (clean)
  └─ next build → .build/next/   (intermediates)
  └─ assembleStandalone          (copies standalone + static + public + natives → dist/)
  └─ writes dist/BUILD_SHA       (HEAD sentinel)

Do NOT run npm run build followed by a separate npm run build:cli for deploy — use npm run build:release which does a clean rebuild + sentinel in one command.

Artifact Validation

• npm run build:release succeeds and dist/BUILD_SHA == git rev-parse --short HEAD
• npm run check:pack-artifact clean — no app.__qa_backup, scripts/scratch, package-lock.json, or other local residue
• dist/server.js exists after build

Tagging & Release

• Run /generate-release-cc (Claude Code skill):
  • Creates tag vX.Y.Z
  • Pushes tag and branch
  • Opens GitHub Release with changelog body
  • Attaches Electron installers (if built)
• Or manually:

  git tag -a vX.Y.Z -m "Release vX.Y.Z"
  git push origin vX.Y.Z
  gh release create vX.Y.Z --notes-from-tag
  

Deploy

Deploy skills use the light rsync flow — no npm pack, no npm i -g:

• Use deploy skill that matches target:
  • /deploy-vps-local-cc — local VPS (192.168.0.15)
  • /deploy-vps-akamai-cc — Akamai VPS (69.164.221.35)
  • /deploy-vps-both-cc — both
• Before deploying, confirm dist/BUILD_SHA == git rev-parse --short HEAD
• Build must run where node_modules is real (main checkout or npm ci'd worktree — NOT a symlinked worktree)
• Smoke test deployed instance:
  • Open /dashboard/health → check version string matches release
  • Run a /v1/chat/completions request against a known provider
  • Verify /api/monitoring/health returns CLOSED circuit breakers
  • Confirm MCP transports respond (/mcp HTTP, /mcp-sse SSE)

Post-release

• Run /capture-release-evidences-cc (Claude Code skill)
  • Captures WebP screenshots/recordings of new features
  • Attaches to release notes / blog post
• Update GitHub Discussions / Discord with release announcement
• Open milestone for next version
• If critical: pin discussion or post in news.json for in-app banner

Embedded Services smoke (v3.8.4+)

Before shipping any release that includes embedded services changes, verify:

Fresh-DB boot (catches migration collisions — added after v3.8.4 hotfix)

• DATA_DIR=$(mktemp -d) npm start & — wait 10 s for boot
• curl -s http://127.0.0.1:20128/api/services/9router/status | jq '.tool' returns "9router" (NOT 404, NOT 500). Confirms migration 071_services.sql applied + row seeded.
• sqlite3 $DATA_DIR/storage.sqlite "PRAGMA table_info(version_manager);" | grep -E "provider_expose|logs_buffer_path|last_sync_at" returns 3 rows.
• sqlite3 $DATA_DIR/storage.sqlite "PRAGMA table_info(webhooks);" | grep -E "kind|metadata_encrypted" returns 2 rows (validates 070_webhooks_kind_metadata.sql applied).
• node --import tsx/esm --test tests/unit/db/no-migration-collisions.test.ts passes — guards against future collisions.

9Router

• POST /api/services/9router/install returns 200 with installedVersion in under 2 min
• POST /api/services/9router/start returns 200 and state: "running" in under 30 s
• GET /api/services/9router/status reports health: "healthy"
• POST /v1/chat/completions with "model": "9router/auto/..." returns 200 (end-to-end routing through 9Router)
• GET /dashboard/providers/services/9router/embed/dashboard renders the 9Router native UI inside the proxy (no direct 127.0.0.1:port iframe)
• POST /api/services/9router/rotate-key returns { keyRotated: true } and service restarts cleanly
• POST /api/services/9router/stop returns 200 and state: "stopped"
• GET /api/services/9router/logs?tail=50 returns SSE stream with snapshot event containing recent lines
• Install in environment without npm in PATH returns 500 with a friendly (non-stack-trace) error message

CLIProxyAPI

• POST /api/services/cliproxy/install returns 200 in under 2 min
• POST /api/services/cliproxy/start returns 200 and state: "running" in under 30 s
• GET /api/services/cliproxy/status reports health: "healthy"
• POST /api/services/cliproxy/stop returns 200 and state: "stopped"
• GET /api/services/cliproxy/logs?tail=50 returns SSE stream

Security regression

• curl -H "X-Forwarded-For: 1.2.3.4" http://localhost:20128/api/services/9router/start returns 403 LOCAL_ONLY
• curl -H "X-Forwarded-For: 1.2.3.4" http://localhost:20128/api/services/cliproxy/start returns 403 LOCAL_ONLY
• Error responses from /api/services/* do not contain err.stack or absolute file paths

v3.8.0+ checks

Before shipping any v3.8.x release, verify these additional items:

• omniroute --tray boots on macOS (systray2 installed into ~/.omniroute/runtime/)
• omniroute --tray boots on Linux (requires DISPLAY; graceful error if not set)
• omniroute --tray boots on Windows (PowerShell NotifyIcon, no extra binaries)
• omniroute config tray enable creates autostart entry; disable removes it
• npm install -g omniroute@<this-version> runs postinstall without fatal exit
• Update path keeps optional deps: omniroute update --apply and the auto-updater run npm install -g … --include=optional so optionalDependencies (better-sqlite3, keytar, tls-client, and the llmlingua SLM stack: @atjsh/llmlingua-2, @huggingface/transformers@3.5.2, @tensorflow/tfjs, js-tiktoken) survive an update. @huggingface/transformers stays optional so its onnxruntime-node CUDA provider postinstall cannot abort installation on CUDA 11 hosts. The ultra modelPath SLM tier also needs the tinybert model, auto-downloaded to ${DATA_DIR}/models/llmlingua on first use. Postinstall (scripts/build/colocateOptionals.mjs) then co-locates the SLM optional closure into dist/node_modules so the worker resolves a SINGLE @huggingface/transformers 3.5.2 optional instance — the standalone trace bundles only transformers, not the dynamically-imported optionals, so without this the worker would load llmlingua-2 against the root's transformers and the SLM tier would silently fail-open.
• omniroute status works with no .env (CLI token path, loopback only)
• curl http://localhost:20128/api/shutdown returns 401 (always-protected route)
• curl -H "host: evil.com" http://localhost:20128/api/mcp/sse returns 401 (loopback guard)
• SQLite runtime resolves to bundled on first run (bundled binary valid for platform)
• SQLite runtime falls back to runtime when node_modules/better-sqlite3 is deleted
• Smart MCP filter compresses real playwright-mcp browser_snapshot output (≥50% reduction)
• All 10 skills/omniroute*/SKILL.md files are publicly fetchable via raw GitHub URL
• Onboarding wizard shows "How It Works" tier tour step on fresh setup
• Home dashboard tier coverage widget shows configured/active counts

---

Rollback

If release has critical issue:

1. gh release edit vX.Y.Z --prerelease (marks as not latest)
2. git tag -d vX.Y.Z && git push --delete origin vX.Y.Z (only if not yet adopted by users)
3. Or: hotfix on release/vX.Y.0 → patch release vX.Y.(Z+1)
4. Communicate in GitHub Discussions and Discord immediately

Hard Rules

• Never commit directly to main
• Never use git push --force to main or release/* branches
• Never skip Husky hooks (--no-verify)
• Never commit secrets, credentials, or .env files
• Coverage must stay ≥75/75/75/70 (statements/lines/functions/branches)
• Always include or update tests when changing production code in src/, open-sse/, electron/, or bin/

Automated Sync Check

Run the docs sync guard locally before opening a PR:

npm run check:docs-sync

CI also runs this check in .github/workflows/ci.yml (lint job).