# Slovo Migration Policy

Slovo changes must preserve the support rule: a feature is supported only when
Slovo documentation and Glagol behavior agree across syntax, typed meaning,
lowering, formatter behavior, diagnostics, tests, and examples.

## Compatibility Baselines

The v0 compatibility fixtures live under `examples/compat/v0/`.

- `examples/compat/v0/supported/` freezes the v0 supported program fixtures.
- `examples/compat/v0/formatter/` freezes the v0 formatter fixtures.

These files are compatibility baselines. Do not edit them for ordinary v1
feature promotion. Add new promoted examples under `examples/supported/` and
`examples/formatter/` instead.

## Allowed Change Classes

Additive changes may add new supported forms when `SPEC-v1.md`, examples,
formatter fixtures, diagnostics, Glagol implementation, and tests are updated
together.

Clarifying changes may improve wording without changing accepted syntax,
observable behavior, diagnostic codes, or canonical formatting.

Migration changes alter accepted syntax, diagnostic shape, canonical formatting,
or runtime behavior for an existing supported fixture. They require an explicit
migration note before implementation is treated as supported.

## Migration Requirements

A migration change must:

- name the affected release baseline and fixtures
- explain the old behavior and the new behavior
- update `SPEC-v1.md` or the next release spec before compiler promotion
- update `RELEASE_NOTES.md`
- keep v0 compatibility fixtures intact unless the release explicitly retires
  them
- add or update Glagol diagnostics so unsupported old forms fail clearly
- update formatter fixtures when canonical layout changes
- update promotion gates or checklist items when the verification path changes

Slovo must not silently repurpose an old supported form with new meaning.

## Diagnostic And Tooling Changes

[`docs/language/DIAGNOSTICS.md`](DIAGNOSTICS.md) is the beta policy for
`slovo.diagnostic` version `1`. Human-readable diagnostic prose remains
beta-flexible, but machine fields, schema/version markers, diagnostic codes,
source/span/range semantics, JSON-line discipline, related-span shape, and
artifact-manifest diagnostic metadata are compatibility-sensitive.

Diagnostic code or machine-shape changes require the compatibility class
defined in [`docs/language/DIAGNOSTICS.md`](DIAGNOSTICS.md), a documented
schema or catalog migration when the change is migration-level, and matching
Glagol snapshot updates. Formatter changes require before/after fixture
coverage so agents can see whether the change is additive, clarifying, or
migration-level.

Native executable output, package layout, stable ABI/layout promises, stable
standard-runtime printing APIs, and raw-memory/FFI contracts remain outside the
current compatibility promise until a future release spec defines them. The
promoted v1 `slovo.artifact-manifest` schema is governed by `SPEC-v1.md`.