= Cutdown Versioning Policy

== Contract

Cutdown uses semantic versioning: ``MAJOR.MINOR.PATCH``.

- ``MAJOR``: breaking language/AST changes.
- ``MINOR``: backward-compatible additions.
- ``PATCH``: clarifications and bug fixes that do not change valid-input meaning.

The version is the language contract version, not app release numbering.

== Compatibility Guarantees

For any two releases within the same major version:

1. Existing valid documents keep the same parse meaning.
2. Existing core AST node names and field semantics stay stable.
3. Previously invalid syntax may become valid only in a ``MINOR`` release and must be additive (no reinterpretation of already-valid input).

Consumers may ignore unknown extension nodes/fields, but parsers must emit them when enabled.

== Release Classification Rules

=== PATCH

Allowed:

- Spec wording clarifications.
- Parser bug fixes where previous output violated existing spec intent.
- Test corpus additions that confirm existing behavior.

Forbidden in ``PATCH``:

- New syntax.
- New AST nodes/fields.
- Precedence changes.
- Behavior that changes AST for previously valid, conforming input.

=== MINOR

Allowed:

- New additive syntax.
- New additive AST nodes or optional fields.
- New extensions in ``experimental`` state.

Required in ``MINOR``:

- Explicit fallback behavior for older consumers.
- Ambiguity-matrix updates for new inline tokens.
- Migration notes for producers/consumers.

Forbidden in ``MINOR``:

- Removing syntax or nodes.
- Reinterpreting existing valid syntax.
- Tightening rules that invalidate previously valid input.

=== MAJOR

Required for:

- Any removal, rename, or semantic reinterpretation of existing syntax/AST.
- Any precedence or whitespace rule change that can alter AST for existing valid input.

Required artifacts:

- Migration guide with before/after examples.
- Compatibility map (old -> new behaviors).
- Deprecation timeline and rollout plan.

== Deprecation and Removal

- Deprecation can begin in a ``MINOR`` release.
- Deprecated features remain parseable through the rest of that major line.
- Removal can occur only in the next ``MAJOR`` release.

== Changelog Markers

Every entry in ``changelogs/<version>.md`` carries one marker:

| Marker | Meaning | Minimum bump |
|---|---|---|
| ``[BREAKING]`` | Alters the AST for input that was already valid, or reinterprets existing syntax | ``MAJOR`` |
| ``[ADDITIVE]`` | Previously invalid input becomes valid; no existing parse changes | ``MINOR`` |
| ``[CLARIFY]`` | Wording, structure, or examples only; no conforming parser changes behaviour | ``PATCH`` |

The release bump is the highest marker present.

== Change Gate Integration

Every Cutdown proposal must declare:

- intended version bump (``patch``/``minor``/``major``), and
- justification against this policy.

Change activation timing and lifecycle state are governed by ``./change-publication-policy.md``.

If a proposal cannot be classified unambiguously, default to ``major`` until proven otherwise.

== Related

- [``./changes-gate.md``](/latest/policies/changes-gate)
- [``./change-publication-policy.md``](/latest/policies/change-publication-policy)