prometeu-studio/docs/general/specs/17. Compatibility and Evolution Policy.md

PBS Compatibility and Evolution Policy

Status: Draft v0 (Quality-Gate Baseline)
Applies to: practical support states and compatibility publication policy tied to executable quality gates

1. Purpose

This document defines how PBS support is published at the current project stage.

The policy is intentionally minimal:

• publish only support claims that are backed by tests,
• use a small support-state model that a solo project can maintain,
• and avoid over-specifying compatibility promises before backend/runtime contracts settle.

2. Scope

This document defines:

• support-state vocabulary for language lines,
• minimum published support table fields,
• and how support-state changes must be recorded.

This document does not define:

• full deprecation-window math per domain,
• one binary/PBX compatibility model,
• one release process implementation.

3. Authority and Precedence

Normative precedence:

1. 1. Language Charter.md
2. 2. Governance and Versioning.md
3. 13. Conformance Test Specification.md
4. This document

If a rule here conflicts with higher-precedence authorities, it is invalid.

4. Normative Inputs

This document depends on:

• 2. Governance and Versioning.md
• 13. Conformance Test Specification.md

5. Support States

PBS currently uses three support states:

• unsupported
• experimental
• supported

Meaning:

• unsupported: no compatibility promise.
• experimental: active development; behavior may change; tests may exist but are not yet a stable support promise.
• supported: active compatibility promise for declared scope, backed by required quality gates.

6. Gate-Backed Support Rule

Support states must map to quality-gate evidence:

1. frontend-ready evidence requires Gate U from 13.
2. integration-ready evidence requires Gate U plus Gate I when Gate I applies to the language/backend.
3. supported state requires maintained evidence for the scope being promised.

No published supported claim may exist without mapped test evidence.

7. Minimum Published Support Table

A published support table must include, at minimum:

1. language identifier,
2. language line/version scope,
3. runtime line (or N/A when Gate I is not applicable yet),
4. Gate U status,
5. Gate I status (pass, fail, or deferred),
6. support state (unsupported, experimental, supported),
7. optional notes.

No additional matrix dimensions are mandatory at this stage.

8. Support-State Changes

When support changes, the project must update together:

1. support table state,
2. gate evidence status,
3. and a short rationale note when users could be affected.

This document requires visibility of change, not a specific changelog format.

9. Explicit Deferrals

The following remain intentionally open:

• domain-specific promise strength beyond the current gate-backed model,
• exact deprecation/removal windows,
• PBX/binary compatibility policy details,
• mandatory migration tooling triggers.

10. Non-Goals

• Simulating large-organization compatibility governance.
• Freezing domains that are still not implemented.
• Requiring one matrix tooling format.

11. Exit Criteria

This document is in a healthy state when:

1. every active language line has an explicit support state,
2. every supported state has mapped gate evidence,
3. support changes are reflected in table + evidence + note,
4. and no compatibility promise depends on undocumented assumptions.