docs/release-process.md

# Release Process

This document defines the minimum release checklist for `Token Cost Guard`.

## 1) Pre-release checks

- Ensure branch is up to date and CI is green.
- Run local checks:
  - `npm run lint`
  - `npm test`
  - `npm run security:check`
  - `npm run bench:baseline` (optional local smoke baseline)
- Validate operational readiness:
  - `GET /api/v1/health`
  - `GET /api/v1/ops/metrics`
  - `GET /api/v1/metrics` (Prometheus format)
- Trigger benchmark workflow manually if release risk is high:
  - `.github/workflows/benchmark.yml`

## 2) Versioning

- Use semantic version tags: `vMAJOR.MINOR.PATCH`.
- Recommended:
  - `PATCH`: bug fixes, no API contract break.
  - `MINOR`: additive features / endpoints.
  - `MAJOR`: breaking API or behavior changes.

## 3) Release execution

1. Merge to `main`.
2. Create annotated tag:
   - `git tag -a vX.Y.Z -m "Release vX.Y.Z"`
3. Push tag:
   - `git push origin vX.Y.Z`
4. Wait for `.github/workflows/release.yml` to finish.
5. Confirm generated artifacts and GitHub Release notes.
6. Confirm benchmark gate passed (if workflow was run).

## 4) Post-release verification

- Smoke test key endpoints in production/staging:
  - `POST /api/v1/optimize`
  - `GET /api/v1/policies/audit`
  - `GET /api/v1/alerts`
- Check dead-letter backlog:
  - `GET /api/v1/alerts/dead-letters`
- Confirm alert webhook delivery success trend via metrics.

## 5) Rollback trigger and action

Trigger rollback if one or more are true:
- sustained 5xx increase,
- major latency regression,
- incorrect policy behavior in production.

Actions:
1. Switch traffic to degraded-safe mode (`fast` where needed).
2. Trigger `POST /api/v1/policies/rollback`.
3. Verify health and replay baseline tests.