# Versioning Policy

This project uses Semantic Versioning for public release decisions and records release notes in the root [CHANGELOG.md](../CHANGELOG.md). Package-manager examples must stay aligned with the pinned `pnpm@10.33.0` declaration in `package.json`; for focused verification use explicit commands such as `pnpm exec vitest run scripts/verify-release-docs-baseline.test.mjs`.

## SemVer rules

### Major versions

Increment the major version for any breaking change. A breaking change is any change that can require downstream code, configuration, deployment scripts, documented workflows, stored data expectations, or operator runbooks to change before an upgrade succeeds.

Major releases must include:

- A `Breaking changes` note in the relevant release entry in [CHANGELOG.md](../CHANGELOG.md).
- Required migration steps and any known incompatible configuration or data assumptions.
- Rollback notes that explain whether downgrade is supported, blocked, or requires restoring data from backup.

### Minor versions

Increment the minor version for backward-compatible features, new documented workflows, additive API or configuration capabilities, and deprecations that do not remove existing behavior.

Minor releases must include release notes for user-visible additions, operational changes, and deprecation notices. Additive changes should preserve existing defaults unless the changelog explicitly describes the changed default and why it is safe.

### Patch versions

Increment the patch version for backward-compatible bug fixes, documentation corrections, dependency patching, and non-breaking reliability or security hardening.

Patch releases must not introduce breaking changes. If a fix requires a behavior change that downstream users must adapt to, treat it as a major change unless a documented compatibility path exists.

## Breaking-change policy

Breaking changes cannot be silent. Before merging or releasing one, document the affected surface, migration path, rollback expectations, and verification evidence in [CHANGELOG.md](../CHANGELOG.md). Examples include removing an endpoint, renaming an environment variable, changing database semantics, tightening authorization in a way that rejects formerly valid usage, or changing a documented command contract.

## Deprecation lifecycle

Deprecations should start in a minor release and appear under `Deprecated` in [CHANGELOG.md](../CHANGELOG.md). Each deprecation entry must state the replacement, the earliest planned removal version or release window, operational risk, and how maintainers will detect remaining usage. Removal happens in a major release unless the deprecated behavior is demonstrably unused and the changelog documents the safety rationale.

## Release-note expectations

Every release entry must keep the Keep a Changelog categories: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, and `Security`. Empty categories should say that no changes were introduced for that category rather than leaving unfinished marker text. Release notes should include focused verification commands when useful, using explicit non-E2E examples such as `pnpm exec vitest run scripts/verify-release-docs-baseline.test.mjs`.

## Rollback note expectations

For changes that affect deployability, data, configuration, or security posture, release notes must explain rollback behavior. State whether rollback is automatic, requires redeploying the prior artifact, requires a database backup restore, or is unsupported after a migration. If rollback requires manual operator action, describe the required evidence and the safest stopping point.

## Verification boundary

Automatic release-documentation verification is limited to non-E2E checks: file/content assertions, focused lint where applicable, focused Vitest targets, and scripts that do not drive a live browser. Browser automation, production-like provider calls, and manual runtime journeys stay outside auto-mode and must be recorded as manual verification when they are needed.