ZAIXOS Engineering Platform — Evolution Model

Document type: Technical Specification
Version: 1.0 · Phase: 12-3
Status: Permanent technical authority
Governance: PLATFORM_VERSIONING_POLICY.md

---

Purpose

Describe how every platform dimension evolves — components, APIs, contracts, adapters, documentation, validation — and how products consume change safely.

---

Evolution principles

ID	Rule
EV-01	Additive change preferred over breaking change
EV-02	Breaking change requires ADR + MAJOR + migration guide
EV-03	Contract obligation change requires new contracts@N
EV-04	Products pin exact versions on release branches
EV-05	Adapters re-certify on contract MAJOR
EV-06	Extensions evolve independently in product Git
EV-07	Documentation evolves with platform semver footer
EV-08	Validation may add checks in MINOR; remove only in MAJOR with deprecation

---

Evolution matrix

Dimension	Additive (MINOR/PATCH)	Breaking (MAJOR)	Product action
Platform components	New procedure/workflow in defaults	Remove/rename Public path	Lock bump + rematerialize
Public API docs	New template section optional	Remove Public path	Read migration guide
Contracts	Clarification only in PATCH doc	New obligations @N+1	Wait for adapter cert
Adapters	PATCH template fix	Hook behavior breaking	Rematerialize
Extension schema	Optional fields	Required field / limit decrease	Update manifest
Validation	New check (MINOR)	Remove check	CI update
Configuration schema	Optional yaml fields	lockSchema MAJOR	Regenerate lock
Knowledge	New pack	N/A	Optional adopt

---

Component evolution

Platform core packages

Change	Version	Process
Doc fix in methodology	PATCH	CHANGELOG
New default workflow skill	MINOR	ADR optional; validation update
Remove default workflow	MAJOR	ADR; migration guide
Reorganize internal paths	INTERNAL	No product impact if Public unchanged

Runtime manifests

Change	Impact
Add optional manifest field	schema MINOR
Change default inventory count	schema MAJOR + platform MAJOR + contracts review

---

API evolution

Public API changes follow PLATFORM_PUBLIC_API.md:

Proposal → RFC (optional) → ADR → Update PUBLIC_API doc
    → Implement → Validation → Release

Classification changes: Experimental → Public requires ADR + 2 release cycles minimum in Experimental.

---

Contract evolution

contracts@1 (frozen for platform 1.x)
    ↓
Need new obligation identified
    ↓
ADR + contracts@2 draft
    ↓
Adapter impact analysis
    ↓
Platform 2.0.0 + adapter re-cert
    ↓
Migration guide for products

Rule: No silent obligation changes in PATCH/MINOR.

---

Adapter evolution

Scenario	Adapter version	Platform version
Typo in SKILL.md	PATCH	PATCH (bundled)
New platform-approved default skill	MINOR	MINOR
Hook behavior change	PATCH or MINOR	Coordinated release
Contract @2 support	MAJOR	MAJOR

Products: update lock.adapter.version + rematerialize.

---

Documentation evolution

Doc class	Versioning
Governance (Constitution)	Amendment ADR; rare
Product definition	Product spec version footer
Technical architecture	technical/ footer + index
Developer guide	Platform semver

Single source: Index points to canonical doc; superseded docs get Deprecated banner.

---

Validation evolution

Change	Release
New ExtensionSchema check	MINOR
Stricter checksum enforcement	MINOR (with CHANGELOG)
Remove legacy ERP path check	MAJOR (post embedded sunset)

Products: run updated suite on MINOR bump; expect new failures = fix forward.

---

Product consumption of evolution

PATCH upgrade

Update lock PATCH → composer update → rematerialize if adapter changed → validation

MINOR upgrade

Review CHANGELOG additive items → update lock → composer update → rematerialize → validation → merge

MAJOR upgrade

ADR review → migration guide execution → extension updates → architect acceptance
    → lock MAJOR → composer update → rematerialize → full acceptance checklist

---

Additive change rules

Allowed without MAJOR
New optional platform.yml field
New extension registry entry type (with schema MINOR)
New certified adapter ID (existing products unaffected)
New validation check that passes on current pins
New knowledge pack
New template optional section

---

Breaking change rules

Requires MAJOR
Remove Public API path
Change default manifest inventory count
New required platform.yml field
Contract obligation add/remove/redefine
Remove certified adapter
extension schema incompatible change
lockSchema breaking change

---

Migration rules

Rule	Detail
Guide required	Every platform MAJOR ships docs/migrations/
Dual-run	Embedded + vendored parity during Dental Clinic migration (12-6–12-8)
Rollback	Previous lock + composer restore valid 12 months
Support window	Previous MAJOR PATCH for 12 months post new MAJOR GA

---

Compatibility matrix maintenance

Published each release:

Platform	contracts@	Adapters	lockSchema	extensionSchema
1.0.x	1	cursor-adapter-v1	1	1

Products MUST NOT assume matrix row without verifying lock.

---

RFC → ADR → TDR flow

Type	Scope
RFC	Exploratory; may archive
ADR	Governance/strategy decisions
TDR	Technical shape decisions

Breaking evolution starts with ADR; technical implementation details in TDR.

---

Evolution Model v1.0 — Phase 12-3.