Release & Versioning Policy

SemVer interpretation

Bump	What changed	Examples
MAJOR (1.0 → 2.0)	Backwards-incompatible changes to the public surface	`ari.public.*` symbol removed, MCP tool semantics change, checkpoint format breaking
MINOR (0.6 → 0.7)	Backwards-compatible feature additions	new `ari.public.*` symbol, new MCP tool, new `ari` subcommand, new env var with safe default
PATCH (0.7.0 → 0.7.1)	Bug fixes, doc updates, internal refactors with no API surface change	LLM prompt tweak that does not alter tool I/O, dashboard CSS, dependency bump

Public surface for SemVer purposes:

The CLI (ari ...) — every documented subcommand and flag.
ari.public.* Python imports.
Each skill's mcp.json tool list, names, and request/response shape.
The viz REST API (everything under /api/).
Documented checkpoint files (tree.json, nodes_tree.json, node_report.json, settings.json, workflow.yaml, experiment.md, manifest.lock, publish_record.json, lineage_decisions.jsonl).
Documented environment variables (those listed in docs/reference/environment_variables.md).

Not part of the public surface:

Modules outside ari.public.*.
Internal-only helpers (_-prefixed names).
Test fixtures and vendor/ snapshots (PaperBench, VirSci, ...).
Prompt strings under ari/prompts/ (governed by Phase PC, but not SemVer-protected — they may change in any minor release as long as the tool I/O contract holds).

Branch	Status	What gets backported
`main` (latest minor)	Active	Features + bug fixes
Previous minor	Maintenance for 6 months after the next minor's release	Security + critical bug fixes only
Older minors	Out of support	None

The current state lives in CHANGELOG.md and on the GitHub releases page.

A deprecation is a notice that a public symbol or behaviour will be removed. We follow this lifecycle:

Examples currently in flight (full programme is folded into CONTRIBUTING.md::Deprecation process):

Item	Announced	Warned since	Removal target
`$HOME/.ari/registries.yaml` fallback	v0.5.0	v0.7.1	v1.0
`$HOME/.ari/registry-data` fallback	v0.5.0	v0.7.1	v1.0
Legacy v0.5 JSONL memory store	v0.5.0	v0.5.0	v1.0
`~/.ari/memory.json` default arg	v0.7.0	v0.7.1 (removed)	v1.0
`ari/migrations/v05_to_v07/` shims	v0.7.0	v0.7.0	v1.0

When cutting a release:

Update CHANGELOG.md with the new section. Group entries under Added / Changed / Fixed / Deprecated / Removed / Security.
Bump the version in ari-core/pyproject.toml and each ari-skill-*/pyproject.toml.
Run the full test suite + the refactor-guards, docs-sync, and docs-change-coupling CI workflows.
Run the docs gate:
- grep -rn '~/\.ari/' docs/ excluding refactor_audit.md returns zero.
- Every documented env var maps to a real source reference.
- Every documented MCP tool exists in the skill's mcp.json.
- python scripts/docs/check_doc_sources.py --require-all exits 0 (every live doc's declared sources: paths exist).
- python scripts/docs/check_doc_links.py exits 0 (no broken intra-docs links or HTML hrefs).
- python scripts/docs/check_translation_freshness.py --strict exits 0 (no ja/zh translation has a last_verified older than its English source — see Source traceability). Run without --strict for a non-blocking warning-only report.
- python scripts/docs/check_i18n_js.py exits 0 (the three docs/i18n/*.js declare one identical key set).
- python scripts/docs/check_readme_parity.py exits 0 (the root README.{md,ja,zh} share one Markdown heading shape).
Tag: git tag v0.X.Y && git push origin v0.X.Y.
Open a release on GitHub with the changelog excerpt.
Publish bundles: ari ear publish for any artefacts that need to ship alongside.

A MINOR release is forward-compatible: a checkpoint produced on the previous minor must keep working on the new minor.
A MAJOR release may require a one-shot migration step. The migration is documented in docs/guides/migration.md and run via ari migrate ....
Skills are versioned independently. A skill at 0.7.x should work with ari-core at any 0.7.y (compatibility within a minor). Across minors, expect a coordinated release.