An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): define release compatibility and versioning (#6755)
Cindy Zhange7723cddf1cc
diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.mdindex 9e27b7d0ff..e9cde6ae09 100644--- a/docs/architecture/public-component-api.md+++ b/docs/architecture/public-component-api.md@@ -113,8 +113,9 @@ guidance owns the process used to propose and test APIs.- **INV8 — Refs follow React 19.** A public DOM component accepts `ref` as a propand connects it to the element promised by its contract.- **INV9 — Released APIs change deliberately.** A released prop, type, export,- default, or observable behavior is not removed, renamed, or retyped without an- explicit compatibility decision and migration.+ default, or observable behavior is not removed, renamed, retyped, deprecated, or+ corrected incompatibly without the lifecycle, evidence, and migration required by+ [`spec:AST-017`](../specs/AST-017/spec.md).- **INV10 — Shared subcontracts are linked, not copied.** Input Actions, layerbehavior, theming, and family-specific rules stay with their owning records.- **INV11 — Public theme seams pass API admission.** A public semantic CSS customdiff --git a/docs/specs/AST-002/spec.md b/docs/specs/AST-002/spec.mdindex 56a4e35ac1..01f352aae5 100644--- a/docs/specs/AST-002/spec.md+++ b/docs/specs/AST-002/spec.md@@ -220,8 +220,10 @@ A public API proposal is admitted only when it passes both gates:For every public API or public behavior delta, identify the canonical owner andapply the routing defined by `architecture:knowledge-contracts`. This spec owns-API admission and semantic-shape requirements; it does not copy review outcomes-or pull-request disposition.+API admission and semantic-shape requirements; the+[Release compatibility and versioning spec](../AST-017/spec.md) owns lifecycle,+classification, deprecation, correction, and release treatment. Neither record copies+review outcomes or pull-request disposition.A draft record may provide context and route the unresolved question, but itcannot clear current authority. Exact-head owner discussion supplies decisiondiff --git a/docs/specs/AST-010/spec.md b/docs/specs/AST-010/spec.mdindex 769f92b1d8..d6515d7343 100644--- a/docs/specs/AST-010/spec.md+++ b/docs/specs/AST-010/spec.md@@ -266,8 +266,11 @@ behavior under `minSize` and `maxSize`.The shipped contract remains distributed across its current owners:-- `architecture:public-component-api` owns the stable exports, breaking-change- classification, and migration boundary;+- `architecture:public-component-api` owns stable export and component contract+ shape;+- [`spec:AST-017` — Release Compatibility & Versioning system spec](../AST-017/spec.md)+ owns classification, deprecation/cleanup state, Changesets, and migration evidence;+ this spec keeps the exact Resizable mapping and its direct transition requirement;- `family:layout-regions` delegates resize state and interaction to useResizableand ResizeHandle while LayoutPanel consumes resolved size;- `spec:AST-002` governs the caller-owned container basis and predictable state;diff --git a/docs/specs/AST-013/spec.md b/docs/specs/AST-013/spec.mdindex cb14424ac9..5d7e0c2dbd 100644--- a/docs/specs/AST-013/spec.md+++ b/docs/specs/AST-013/spec.md@@ -125,8 +125,9 @@ requirements. Assistive-technology evidence remains separately owned.- **FR11 — Raising the floor is compatibility work.** Removing a supported browser,moving it from full behavior to reduced fallback, or removing a documented- fallback requires owner approval, a Changeset, user-impact and migration notes,- updated generated rows, actual-browser evidence for the browsers affected by the+ fallback requires owner approval, the classification and lifecycle required by+ [`spec:AST-017`](../AST-017/spec.md), user-impact and migration notes, updated+ generated rows, actual-browser evidence for the browsers affected by thecompatibility claim, and evidence that every remaining full-support and namedexplicit support row still receives full required behavior.- **FR12 — Component specs inherit the baseline.** Component specs linkdiff --git a/docs/specs/AST-017/spec.md b/docs/specs/AST-017/spec.mdindex 6f2421ce51..f3a61f3047 100644--- a/docs/specs/AST-017/spec.md+++ b/docs/specs/AST-017/spec.md@@ -7,11 +7,15 @@ authority: currentarchive_reason: nullsuperseded_by: nullapproved_by: cixzhang-approved_at: 2026-09-02+approved_at: 2026-09-29phase: acceptedowners: [cixzhang, josephfarina]affects_architecture:- [architecture:public-component-api, architecture:cli-surface]+ [+ architecture:public-component-api,+ architecture:cli-surface,+ architecture:theme-tokens,+ ]affects_families: []affects_contributing:[@@ -22,7 +26,7 @@ affects_contributing:affects_consumer_docs: [release-process, templates]----# Published compatibility and breaking-change classification system spec+# Release Compatibility & Versioning system spec<!-- review-applicability:v1 -->@@ -37,6 +41,10 @@ affects_consumer_docs: [release-process, templates]"DEC-7","DEC-8","DEC-9",+ "DEC-10",+ "DEC-11",+ "DEC-12",+ "DEC-13","FR3","FR4","FR5",@@ -51,7 +59,27 @@ affects_consumer_docs: [release-process, templates]"FR21","FR22","FR23",- "FR24"+ "FR24",+ "FR25",+ "FR26",+ "FR27",+ "FR28",+ "FR29",+ "FR30",+ "FR31",+ "FR32",+ "FR33",+ "FR34",+ "FR35",+ "FR36",+ "FR37",+ "FR38",+ "FR39",+ "FR40",+ "FR41",+ "FR42",+ "FR43",+ "FR44"]}}@@ -59,13 +87,19 @@ affects_consumer_docs: [release-process, templates]## Intent-Give contributors and reviewers one rule for deciding whether a change is-`[breaking]`: identify an installed consumer whose valid use of the latest stable-release stops working unchanged.+Give contributors, reviewers, and release owners one durable contract for evolving+published Astryx surfaces. Classify every change from the installed consumer it+affects, isolate experimentation from stable behavior, stage deprecations and+behavior corrections explicitly, and make a planned minor traceable to one locked+final-patch baseline.-The label is a compatibility classification, not a risk or severity score. A-small, safe rename can be breaking; a large rewrite can be nonbreaking when it-preserves the released contract.+A valid consumer of the latest stable release is the compatibility test. The label is+not a risk or severity score: a small rename can be incompatible, while a large+rewrite can remain compatible when released usage is preserved. A real bug can also+be incompatible when consumers validly rely on its released behavior; that case uses+the distinct corrective path in FR32–FR35. Its primary Changeset tag remains `[fix]`,+while additive metadata distinguishes it from an ordinary patch-compatible fix and+from a generic `[breaking]` removal.For CLI controls, keep every supported behavior discoverable and put each control onthe narrowest surface that owns it. Global controls require evidence that their value@@ -78,7 +112,9 @@ independent for each invocation.- Defining component or template naming conventions.- Treating private packages, canaries, unreleased work, or explicitly markedexperimental surfaces as stable public API.-- Replacing the release process, Changesets, or migration tooling.+- Replacing the public Release Process, Changesets, migration tooling, or direct+ component and feature authorities. This spec owns the lifecycle and evidence those+ mechanisms implement; it does not duplicate their operational or product rules.## Requirements@@ -104,33 +140,50 @@ independent for each invocation.continues to work with equivalent meaning through a compatibility alias oradapter. A deprecation may warn and point to the replacement, but removing thatcompatibility path is the breaking event.-- **FR5 — Additive and contract-restoring changes are nonbreaking.** New optional- capabilities, new components, new commands, broader accepted inputs, and new- templates are nonbreaking when old usage is unchanged. A fix that restores the- already-documented contract is nonbreaking even when it changes faulty output.- A proposal that intentionally replaces the documented contract is not a fix for- classification purposes.+- **FR5 — Additive and victim-free contract restorations are nonbreaking.** New+ optional capabilities, new components, new commands, broader accepted inputs, and+ new templates are nonbreaking when old usage is unchanged. A fix that restores an+ already-documented contract is nonbreaking only when no valid consumer of the+ released faulty behavior must change. When a supported consumer relies on that+ behavior and the correction breaks the consumer, FR32–FR35 classify it as an+ incompatible fix even though the implementation violated authority. A proposal+ that intentionally replaces the documented contract is not a fix.- **FR6 — Risk does not override compatibility.** Low adoption, low likelihood,engineering approval, or confidence that affected callers are uncommon does notmake an incompatible released contract nonbreaking. Conversely, implementationsize, visual scope, or review difficulty does not make a compatible changebreaking.-- **FR7 — The Changeset category follows the classification.** A published- breaking change uses a `[breaking]` Changeset. While Astryx packages remain on- `0.x`, that category carries a minor bump; every nonbreaking published category- carries a patch bump. Documentation-only, test-only, and private-package-only- changes need no Changeset. `pnpm changeset:new` is the authoring path and- `pnpm check:changesets` enforces the current category/bump coupling. Classify- each published package update in multi-package work. A fixed-group version-only- co-bump needs no Changeset entry by itself, but a generated dependency or peer- range edit is part of that package's update and must be classified and named in a- Changeset. When categories differ, use separate Changesets so every package entry- follows its own classification.-- **FR8 — Migration evidence matches the affected surface.** Every breaking change- names the old valid usage, the replacement, and how consumers migrate. Supply an- `astryx upgrade` codemod when consumer source can be rewritten mechanically.- When no source rewrite is possible, provide an explicit compatibility alias or- concrete replacement instructions rather than inventing a vacuous codemod.+- **FR7 — Changeset tags and lifecycle metadata are orthogonal.** Existing primary+ tags remain the authoring vocabulary: corrections use `[fix]`, compatible+ capabilities and replacement-first staging use `[feat]` or the established narrower+ tag, approved removals use `[breaking]`, and confined experiments use+ `[experimental]`. New compatibility and lifecycle classification MUST be additive+ machine-readable metadata, not a replacement tag. A victim-free correction is+ `[fix]` plus `compatible` or `contract-restoring` metadata and a patch bump. A+ behavior-correcting incompatibility is `[fix]` plus `incompatible-fix`, `IFIX-*`, and+ `CLN-*` metadata and uses the incompatible version tier. Replacement-first+ deprecation is `[feat]` plus `deprecation`, `DEP-*`, and `CLN-*` metadata and remains+ patch-compatible while old usage works. Approved removal is `[breaking]` plus+ `planned-removal`, its applicable lifecycle id, and `CLN-*`. While Astryx packages+ remain on `0.x`, the incompatible tier is minor; compatible work is patch.+ Documentation-only, test-only, and private-package-only changes need no Changeset.+ Existing Changesets keep their current tag and validated bump semantics and MUST NOT+ be mass-migrated; the additive metadata is required only when work enters a lifecycle+ defined here. `pnpm changeset:new` remains the authoring path, and+ `pnpm check:changesets` validates tag, metadata, evidence, and bump together once the+ additive schema is implemented. Classify each published package update in+ multi-package work. A fixed-group version-only co-bump needs no Changeset entry by+ itself, but a generated dependency or peer-range edit is part of that package's+ update and must be classified and named. When primary tags differ, use separate+ Changesets so each package retains its own author-facing category.+- **FR8 — Migration evidence matches the affected surface.** Every planned removal+ and incompatible fix names the old valid usage, the replacement or corrected+ behavior, and how consumers migrate. Supply an `astryx upgrade` codemod when+ consumer source, configuration, metadata, or project files can be rewritten+ mechanically. When no rewrite is possible, preserve an explicit compatibility+ adapter or provide concrete replacement instructions and record why a codemod would+ be vacuous. Codemods follow `spec:AST-040` and include positive, negative, and+ second-run idempotence fixtures plus downstream proof.- **FR9 — Template slugs are mutable catalog data.** A template slug identifies anentry in the current template catalog; it is data about that template, not acontractual CLI API. Renaming a slug is nonbreaking even when@@ -292,13 +345,173 @@ independent for each invocation.compares the previous published surface with current declarations and authoreddocs, verifies that their experimental markers agree, and rejects an`[experimental]` Changeset when any incompatible delta reaches a stable surface.- The integration-theme contribution capability is the one grandfathered surface:- its introduction in 0.6.3 is treated as experimental even though it predates the- markers in FR21, and no other released surface may be enrolled retroactively. Its- contribution metadata, discovery, and authoring contract may evolve in patch- releases until an explicit promotion removes the marker. The surrounding stable+ Integration-theme contribution capability remains the one grandfathered surface;+ no other released surface may be enrolled retroactively. Its contribution+ metadata, discovery, and authoring contract may evolve in patch releases until an+ explicit promotion removes the marker. This prohibition does not turn an+ unpublished field or behavior into stable API merely because an adjacent feature+ was released. Integration-template replacement-specific fields and behavior—its+ `replaces` declaration, replacement selection, optional list projection, and+ expanded conflict fields—remain pre-publication surfaces under FR2 until their first+ stable release; that classification is not experimental enrollment. Previously+ released same-id conflict warning behavior remains stable. The surrounding stableCLI command names, options, exit behavior, and machine-readable envelope remainprotected under FR3 and FR13.+- **FR25 — Stable Core and every published stable package default to compatibility.**+ Outside approved cleanup, changes to behavior, types, exports, CSS or tokens,+ documented markup or selectors, accessibility semantics, persistence, CLI,+ configuration, schemas, build tooling, docs routes, and package files MUST be+ additive, implementation-equivalent, or a victim-free contract restoration under+ FR5. An internal label, low adoption, or lack of a source-level API change does not+ weaken this rule.+- **FR26 — Public lifecycle state is explicit.** Each public surface is+ `experimental`, `stable`, `correction-transition`, `deprecated`,+ `cleanup-approved`, or `removed`; private and unreleased surfaces remain outside the+ published lifecycle. Stable cannot become experimental. Deprecated and+ correction-transition behavior remains supported until its exact cleanup item is+ approved. A completed correction returns its surviving behavior to stable.+- **FR27 — Experimental isolation covers every surface kind.** Whole experimental+ components remain in the private canary-only Lab package governed by the public+ Component Lifecycle. FR21 continues to govern stable-component props and exports.+ Experimental CLI controls use a dedicated experimental namespace; configuration+ uses an experimental object; CSS and tokens use dedicated experimental exports and+ names; persistence uses a feature- and schema-versioned experimental namespace;+ build tooling uses experimental exports/configuration; and docs use marked+ experimental routes. An omitted opt-in MUST leave stable defaults, output, routes,+ data, and behavior unchanged. Promotion requires owner approval and a `[feat]`+ Changeset; withdrawal uses `[experimental]` and MUST prove no stable spillover.+- **FR28 — Deprecation is replacement-first and machine-readable.** A deprecation+ patch ships the working replacement while old usage remains equivalent. A public+ record assigns a stable `DEP-*` id and a distinct `CLN-*` cleanup id and names the+ package, surface kind, old contract, replacement, direct authority, warning,+ migration, codemod or non-mechanical reason, downstream proof, state, and target+ plan. Prose alone does not create removal eligibility.+- **FR29 — Warnings fit the surface without changing success.** Declarations use+ `@deprecated`; CLI aliases expose the deprecation id and replacement in their+ machine result and emit at most one human-readable stderr warning per invocation;+ runtime and build APIs use deduplicated development warnings; CSS and tokens use+ static diagnostics. Warnings MUST NOT change production behavior, successful exit+ status, canonical output, or machine-readable stdout.+- **FR30 — Deprecation minima come only from direct authority.** This global spec+ imposes no elapsed-time or release-count minimum. The structural minimum is that the+ final patch preserves old and new behavior together. A direct current spec MAY+ require a duration or number of stable releases for its own surface; the `DEP-*`+ record cites that exact requirement and CI enforces it. Release cadence MUST NOT be+ interpreted as a deprecation clock or eligibility gate.+- **FR31 — Cleanup is one-to-one with approved ids.** A removal or default switch is+ allowed only when its applicable lifecycle record id (`DEP-*` for deprecation or+ `IFIX-*` for correction) and distinct `CLN-*` id appear in the frozen minor+ manifest. Each incompatible delta maps to exactly one applicable lifecycle record+ and one cleanup id, and each cleanup id maps to the old contract, replacement,+ migration, proof, and rollback. Newly introduced incompatibility cannot be legalized+ by adding it directly to a plan.+- **FR32 — Behavior-correcting incompatibility is a distinct classification.** An+ `incompatible-fix` exists when pre-existing current authority proves released+ behavior wrong, unsafe, or nonconforming AND a valid latest-stable consumer relies+ on that behavior such that the correction breaks code, interaction, persisted data,+ output, or a supported workflow. Its primary Changeset tag remains `[fix]`, with+ additive `incompatible-fix` classification metadata, an `IFIX-*` id, and a distinct+ `CLN-*` cleanup id. It is not an ordinary patch-eligible fix and MUST NOT be recast as+ a generic `[breaking]` removal. A visible correction with no valid released victim+ remains `[fix]` with `compatible` or `contract-restoring` metadata under FR5.+- **FR33 — Incompatible-fix evidence and approval are complete.** Before approval,+ the `IFIX-*` record names the pre-existing expected authority, a latest-stable+ reproducer for actual behavior, affected users and supported callsites or inputs,+ an old/new compatibility matrix, coexistence analysis, migration, codemod or exact+ non-mechanical reason, downstream proof, rollback, and harm from both delaying and+ applying the correction. Without pre-existing authority, the proposal is a new+ contract decision. The direct contract owner approves the expected behavior and+ classification; the release owner approves the `IFIX-*`/`CLN-*` pair in the plan.+- **FR34 — Incompatible fixes use a corrective lifecycle.** FR26 governs the state of+ each public surface; the `IFIX-*` record tracks `proposed`, `approved`,+ `transition-shipped`, `cleanup-approved`, `corrected`, `monitoring`, and `closed`.+ `proposed` or `approved` leaves the released surface `stable`.+ `transition-shipped` maps the coexisting old and corrected paths to+ `correction-transition`. `cleanup-approved` maps the old path to+ `cleanup-approved` while the corrected path remains `correction-transition`.+ `corrected`, `monitoring`, or `closed` maps the surviving corrected contract to+ `stable` and the eliminated old path to `removed`. When safe, a patch preserves the+ old default while shipping the corrected opt-in or adapter, warning, migration, and+ codemod. The paired minor changes the default or removes the old behavior only+ through the approved `CLN-*`. An incompatible fix cannot enter the minor as an+ incidental compatible fix or unrelated cleanup.+- **FR35 — Emergency correction is narrow and never relabeled as a patch.** Only+ urgent security, privacy, severe accessibility, or comparable critical ongoing+ harm MAY bypass replacement-first coexistence or ordinary scheduling. Waiting must+ materially extend the harm; no additive mitigation, containment, adapter, or safe+ rollout may be available; the contract owner and relevant incident owner must+ approve a dedicated record; public-safe incident evidence and restricted+ attestation must justify urgency; exact-main quality and migration gates still run;+ and the release contains no unrelated feature, cleanup, or incompatible fix.+ Migration ships with the release; an incomplete emergency codemod records an owner,+ bounded follow-up, fixtures, and delivery target. Rollback never restores known+ harmful behavior: use containment or safe-forward correction.+- **FR36 — Minor frequency is planning guidance, not eligibility.** Plan minors+ generally no more often than once every fourteen calendar days. The plan records+ the interval from the prior minor for owner review. CI reports the interval but+ MUST NOT derive deprecation eligibility, a final-patch-to-minor wait, or an+ exception requirement from it.+- **FR37 — Every minor has an owner-approved public plan and freeze.** Before freeze,+ the plan names the target, final-patch baseline procedure, exact `CLN-*` items,+ migrations, codemods, downstream proof, allowed compatible fixes, exact-main gates,+ release notes, rollback, and recovery. Changing cleanup items after freeze+ invalidates the plan. Operational runbooks may add execution detail but cannot+ authorize or widen cleanup.+- **FR38 — The final patch is the paired minor's locked baseline.** Publish the final+ patch with deprecated and correction-transition behavior still working, record its+ exact source and package/docsite/visual/contract receipts, then lock that baseline.+ The paired minor MAY follow sequentially and immediately when ready and explicitly+ authorized; no wait exists unless a direct authority requires one.+- **FR39 — Every final-patch-to-minor delta has exactly one class.** The diff MUST+ partition into: (a) approved `CLN-*` cleanup removals or corrections; (b) a closed+ list of version, changelog, lockfile-integrity, tag, provenance, digest,+ build-timestamp, and source-map metadata; or (c) independently patch-compatible+ fixes under FR40. Strict equivalence is the target. Unrelated features, additive+ product capabilities, incompatible fixes outside approved corrective cleanup,+ refactors with public deltas, and unclassified changes are prohibited.+- **FR40 — Compatible fixes may be disclosed separately in the minor.** Each has its+ own `[fix]` Changeset, current authority or standard, latest-stable regression test,+ representative unchanged paths, downstream proof, and a manifest entry separate+ from cleanup ids. If the fix lands before final-patch lock, include it in both+ releases. If it lands after publication or lock, it MAY enter the minor as a+ disclosed compatible delta; do not recut the final patch solely for bookkeeping.+ CI MUST independently prove patch eligibility. Release notes separate cleanup from+ compatible fixes.+- **FR41 — Records use closed schemas.** The declaration schema preserves the existing+ primary Changeset tag and adds separate compatibility classification and lifecycle+ fields. Deprecations require `DEP-*` and `CLN-*`; incompatible fixes require+ `IFIX-*` and `CLN-*`; the minor plan carries baseline receipts, cleanup items,+ compatible fixes, release-metadata deltas, owner approval, exact-main gates, and+ rollback; and the equivalence receipt carries final and candidate digests plus+ `unclassifiedDeltas`. Unknown fields, duplicate ids, reused cleanup ids, missing+ evidence, tag/classification contradictions, and one delta mapped more or less than+ once fail.+- **FR42 — Contributors declare compatibility intent once.** Every pull request and its+ Changesets share one machine-readable declaration with the existing primary tag,+ classification, authority, affected surface kinds, experimental ids, deprecation+ ids, correction ids, cleanup ids, and minor plan. Closed classifications are+ `not-published`, `compatible`, `contract-restoring`, `experimental`, `deprecation`,+ `planned-removal`, and `incompatible-fix`. Classification is orthogonal to the+ established tag and MUST NOT introduce `[deprecation]` or `[incompatible-fix]` as+ authoring categories. Existing Changesets need no backfill. Contributors state+ intent; maintainers resolve missing authority. External contributors are not+ required to invent policy.+- **FR43 — CI validates semantics, not labels.** Pull-request CI compares latest+ stable to head to establish released victims and base to head to attribute deltas.+ Release CI compares final patch to paired minor and assigns every delta exactly once+ to cleanup, release metadata, or compatible fix. It checks exports/types, runtime,+ CSS/tokens, DOM/accessibility/visual/RTL, CLI/help/routes/schema, persistence, docs,+ package files, supported package combinations, old-client/new-metadata behavior,+ fixed-group membership, required evidence, and tag/classification/bump coupling.+ Plain failures name the victim, missing evidence, and exact repair path.+- **FR44 — Exact-main release gates and rollback preserve one identity.** The final+ patch and paired minor each use one immutable source identity for build, package+ artifacts, gate receipts, tag, publish, and release record. Missing authority,+ manifest coverage, required migration, exact-main evidence, or any unclassified+ delta aborts the cut. Partial publishing resumes the same bytes. A bad release rolls+ forward with a compatible patch that restores aliases or the prior safe+ compatibility mode; critical-harm recovery follows FR35 and never restores the+ harmful behavior.### Platform support@@ -310,80 +523,100 @@ independent for each invocation.- Browser evidence: not applicable to the classification itself; a browser-ownedcompatibility claim still follows the governing component or platform spec.+## Authority relationships++This spec owns compatibility classification, lifecycle state, release-pair delta+classes, and the evidence that admits them. It delegates narrower questions rather+than restating them:++- [`spec:AST-002` — Public API admission and operation shape](../AST-002/spec.md)+ owns whether a public API concept should exist and its semantic shape.+- [`architecture:public-component-api` — Public component API](../../architecture/public-component-api.md)+ owns the stable component contract; this spec owns how it evolves.+- [`architecture:cli-surface` — CLI surface architecture](../../architecture/cli-surface.md)+ and [`spec:AST-042` — CLI command admission and programmatic parity system spec](../AST-042-cli-command-admission/spec.md)+ own CLI structure, admission, and parity; this spec owns compatibility and+ release transition.+- [`architecture:theme-tokens` — Theme token architecture](../../architecture/theme-tokens.md)+ owns token semantics; this spec owns compatibility and experimental isolation.+- [`spec:AST-013` — Browser and platform support system spec](../AST-013/spec.md)+ owns support floors and fallbacks; this spec owns release treatment of a support+ reduction.+- [`spec:AST-035` — Integration template replacement system spec](../AST-035/spec.md)+ owns template-replacement semantics. This spec classifies each field and behavior+ against the latest stable release: unpublished replacement-specific surfaces follow+ FR2, while previously released same-id conflict warning behavior remains stable.+- [`spec:AST-040` — Evidence-based consumer file modification system spec](../AST-040-consumer-file-modification/spec.md)+ owns what a codemod may edit and the evidence it requires; this spec owns when a+ migration must supply one.+- [`spec:AST-010` — Structured percentage useResizable configuration system spec](../AST-010/spec.md)+ and [`spec:AST-043` — Date and time input presentation system spec](../AST-043-input-presentation/spec.md)+ own their concrete mappings and any surface-specific deprecation minimums.+- [`spec:AST-030` — Positive CI surface routing system spec](../AST-030/spec.md)+ owns pull-request lane routing; this spec owns the compatibility checks each+ affected surface must receive and the exact-main release gate.+- [`spec:AST-039` — Integration contribution descriptor system spec](../AST-039/spec.md)+ is a related draft, not authority. If promoted, it links its compatibility readers+ and removals to this lifecycle.+- The public [Component Lifecycle](https://github.com/facebook/astryx/wiki/Component-Lifecycle)+ owns whole-component Lab-to-Core readiness. Lab remains the private canary-only+ incubation boundary; this spec owns the compatibility effect of promotion.+- The public [API Conventions](https://github.com/facebook/astryx/wiki/API-Conventions),+ [Distribution](https://github.com/facebook/astryx/wiki/Distribution), and+ [Release Process](https://github.com/facebook/astryx/wiki/Release-Process) pages+ are operational projections. When they discuss compatibility lifecycle, they MUST+ link here and cannot create competing rules.+- [`.changeset/config.json`](../../../.changeset/config.json),+ [`scripts/check-changesets.mjs`](../../../scripts/check-changesets.mjs), and+ [`.github/workflows/ci.yml`](../../../.github/workflows/ci.yml) implement fixed+ grouping, declaration validation, and checks. Their current behavior is not policy+ when it differs from this spec.++The direct current owner decides the intended product contract. This spec decides how+that contract may change in a stable release. The public Release Process decides how+an eligible release is operated. A direct spec cannot waive compatibility silently;+it names the applicable `DEP-*`, `IFIX-*`, and `CLN-*` records when its transition is+incompatible.+## Current-state impact-The release tooling already enforces `[breaking]` to minor and every other-category to patch while packages are on `0.x`. The Release Process already limits-migration obligations to released surfaces. The template contribution guide notes-that template resolution is exact-match, but that lookup mechanic does not turn a-slug value into a contractual API.--The repository already isolates whole experimental components in the canary-only-Lab package, but it has no equivalent boundary for a new prop, callback, hook, or-type on an existing stable component. This amendment adds that per-surface boundary-without weakening the component around it. The release tooling and public Release-Process do not yet support the `[experimental]` category or verify declaration/doc-markers. Before another surface uses the contract, follow-up implementation must add-the category to Changeset authoring, CI validation, changelog grouping, and the-Release Process, with tests that prove even an incompatible experimental-only change-stays patch-level. Integration-theme contributions are the sole grandfathered-enrollment and may use existing patch categories until the dedicated category ships.-Open PR #6615 removes the released `layout` command, which was experimental only in-practice and carried no contract marker; it remains breaking and is not enrolled by-this amendment.--This spec supplies the missing classification rule shared by those documents. In-particular, both CLI-template cases discussed during review are nonbreaking catalog-updates:--- renaming a template slug changes data about the current template and may make the- previous value stop resolving; and-- changing or completely rebuilding the template's emitted starter page updates- content for future generations without modifying projects that already copied it.--The stable compatibility boundary remains the CLI operation and complete response-schema, not the individual entries currently present in the template catalog.-Nested entry fields are public schema even when optional; their type, tests, text-projection where present, and consumer schema documentation move together.--The CLI already generates command help, README tables, and a machine-readable-manifest. This amendment extends that discoverability standard to every supported-behavior, including automatic behavior and controls outside command syntax. Existing-Astryx-owned environment controls are non-conforming and must move to documented-commands, options, configuration, or programmatic APIs; this record does not choose-their individual migrations. Removing an existing variable still follows FR3–FR8:-a breaking removal needs concrete migration guidance, and silently ignoring the old-input is not a migration. This record does not authorize any specific global control.-A future proposal must prove meaningful behavior across every command under FR15 or place the control on the narrower command and API surfaces that own the-behavior. These decisions change policy only, so they do not change runtime output or-a published package and require no Changeset.--The existing `debug` setting is the reference behavior for FR20: the app handler-and every integration handler run, the app first; a throwing handler is skipped-without affecting the others or the command; `inheritDebug: false` in the-package's `astryx` field refuses inherited handlers; and a repeated project load-delivers each event once. Its configuration schema entry states that rule, and-the `cli/integrations` guide documents the `debug` named export. Draft-AST-031 details the same model for runtime handler features. No command yet-reports an effective contributed value with its sources, so existing contributed-settings do not meet FR20's inspection requirement; this record does not choose-that command. FR19 applies to new configuration; this amendment does not-reclassify existing keys.+Existing classification remains in force. This amendment adds the missing durable+lifecycle around it:++- stable changes default to compatible patch treatment;+- experimental containment extends to every public surface kind;+- deprecations and behavior corrections become machine-readable and cleanup-owned;+- planned minors use a locked final-patch baseline while admitting only approved+ cleanup, closed release metadata, and independently patch-compatible fixes;+- minor frequency remains planning guidance and creates no deprecation or pair wait;+- contributor declarations preserve established Changeset tags while adding semantic+ lifecycle metadata and require no migration of existing Changesets; and+- exact-main release comparison rejects unclassified deltas.++These are specification changes only. They do not alter a published package and need+no Changeset. Authoring helpers, validators, manifests, compatibility snapshots,+release workflows, and contributor documentation are follow-up implementation. Until+they land, maintainers apply these requirements in review and release approval.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| --------- | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| FR1–FR3 | PR compatibility statement plus latest stable package inspection | released export, behavior, CLI command; unreleased and private surface | A change is labeled from diff size or possibility alone, or a released contract change is missed |-| FR4–FR6 | Old-usage type/runtime/CLI regression test | alias retained, deprecation warning, broad rewrite, low-adoption caller | Contractual old usage fails despite a nonbreaking label, or risk is substituted for compatibility |-| FR7–FR8 | `pnpm check:changesets` plus migration review | breaking and patch Changesets; codemoddable and non-codemoddable migration | Category and bump diverge, or a breaking release gives no usable migration path |-| FR9–FR13 | CLI contract tests, response-schema/type snapshots, text projections, generated consumer docs, and template catalog/output tests | slug rename, metadata edit, source rebuild, optional field addition, command or schema change | Catalog data is frozen as API, a command/schema incompatibility is mislabeled as catalog-only, or a response field lacks a complete projection |-| FR12 | Minimum and representative supported-version tests plus manifest and release-note review | retained range, narrowed range, adapter, coordinated upgrade | An in-range combination breaks under a nonbreaking label, or release coordination hides the affected package or migration |-| FR14 | Help/manifest snapshots, public API and consumer docs, and focused contract tests | command, option, API/config, private rollout/test hook | Supported behavior is hidden, an environment variable changes behavior, or automation lacks a documented API |-| FR15 | Full manifest-derived command matrix, supported-consumer evidence, and scope-specific contract tests | global invariant, scoped command group, single command, programmatic API | A global control is a no-op for any command, has different meanings, or replaces a narrower owning surface |-| FR16–FR18 | Boundary inventory, hostile side-effect probes, response snapshots, and concurrent API tests | known and new extension, partial result, text/JSON/API parity, independent concurrent calls | A route bypasses the guarantee, omitted work looks complete, or one invocation changes another |-| FR19–FR20 | Proposal evidence with a regression fixture for the detection failure, plus composition and provenance tests | convention covers the case, detection fails, app plus two integrations, refusal, failing contribution, repeated load | A key ships without a reproduced detection failure, a contribution displaces the app or applies twice, a part of the effective value has no inspectable source, or a failure silently weakens protection |-| FR21–FR24 | Published-surface comparison, declaration/doc metadata checks, import-boundary checks, and Changeset classification review | experimental prop object, experimental subpath, patch evolution, promotion, stable-surface spillover, integration theme | A prose-only marker excludes a stable API, an experimental export leaks through a stable path, a patch changes stable behavior, or a promoted API remains unprotected |+| Contract | Verification | Representative states | Mutation or failure expectation |+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1–FR3 | PR compatibility statement plus latest stable package inspection | released export, behavior, CLI command; unreleased and private surface | A change is labeled from diff size or possibility alone, or a released contract change is missed |+| FR4–FR6 | Old-usage type/runtime/CLI regression test | alias retained, deprecation warning, broad rewrite, low-adoption caller | Contractual old usage fails despite a nonbreaking label, or risk is substituted for compatibility |+| FR7–FR8 | `pnpm check:changesets` plus migration review | existing `[fix]`, `[feat]`, `[breaking]`, and `[experimental]` tags paired with compatible, deprecation, planned-removal, or incompatible-fix metadata | A new lifecycle replaces an established tag, tag/metadata/bump diverge, an incompatible correction uses bare `[fix]`, or migration is unusable |+| FR9–FR13 | CLI contract tests, response-schema/type snapshots, text projections, generated consumer docs, and template catalog/output tests | slug rename, metadata edit, source rebuild, optional field addition, command or schema change | Catalog data is frozen as API, a command/schema incompatibility is mislabeled as catalog-only, or a response field lacks a complete projection |+| FR12 | Minimum and representative supported-version tests plus manifest and release-note review | retained range, narrowed range, adapter, coordinated upgrade | An in-range combination breaks under a nonbreaking label, or release coordination hides the affected package or migration |+| FR14 | Help/manifest snapshots, public API and consumer docs, and focused contract tests | command, option, API/config, private rollout/test hook | Supported behavior is hidden, an environment variable changes behavior, or automation lacks a documented API |+| FR15 | Full manifest-derived command matrix, supported-consumer evidence, and scope-specific contract tests | global invariant, scoped command group, single command, programmatic API | A global control is a no-op for any command, has different meanings, or replaces a narrower owning surface |+| FR16–FR18 | Boundary inventory, hostile side-effect probes, response snapshots, and concurrent API tests | known and new extension, partial result, text/JSON/API parity, independent concurrent calls | A route bypasses the guarantee, omitted work looks complete, or one invocation changes another |+| FR19–FR20 | Proposal evidence with a regression fixture for the detection failure, plus composition and provenance tests | convention covers the case, detection fails, app plus two integrations, refusal, failing contribution, repeated load | A key ships without a reproduced detection failure, a contribution displaces the app or applies twice, a part of the effective value has no inspectable source, or a failure silently weakens protection |+| FR21–FR24 | Published-surface comparison, declaration/doc metadata checks, import-boundary checks, and Changeset classification review | experimental prop object, experimental subpath, patch evolution, promotion, unpublished adjacent field, stable warning behavior, integration theme | A prose-only marker excludes a stable API, adjacency falsely publishes a new field, an experimental export leaks through a stable path, a patch changes stable behavior, or a promoted API remains unprotected |+| FR25–FR27 | Stable-surface inventory and experimental-boundary matrix | package/API, CSS/token, CLI/config, persistence, build tooling, docs, whole Lab component | An unmarked experiment changes stable defaults or a stable surface bypasses compatibility review |+| FR28–FR31 | Closed-schema deprecation and cleanup records plus old/new compatibility fixtures | replacement first, warning projections, explicit direct-spec minimum, one-to-one cleanup | Prose creates eligibility, cadence invents a wait, old behavior degrades early, or a cleanup id covers more than one incompatible delta |+| FR32–FR35 | Latest-stable victim fixture, pre-existing authority, owner reviews, correction record, record-to-surface state mapping, and emergency attestation | victim-free `[fix]`, `[fix]` plus incompatible-fix metadata, coexistence, cleanup transition, critical-harm emergency | A released victim uses bare `[fix]`, a new Changeset tag replaces metadata, a correction record disagrees with its public-surface state, or urgency bypasses migration |+| FR36–FR40 | Minor plan, locked final-patch receipt, three-way delta classification, and separated release notes | ordinary cadence, immediate pair, cleanup, release metadata, pre/post-lock compatible fix | Cadence becomes eligibility, the final patch is recut for bookkeeping, a feature or incompatible fix enters the incidental-fix lane, or release notes merge cleanup with fixes |+| FR41–FR44 | Schema validation, PR declaration, semantic stable/base/head comparisons, exact-main gate, and immutable publish/rollback receipt | duplicate ids, missing evidence, route/schema removal, old-client metadata, partial publish, safe rollback | A label passes without semantics, a delta maps zero or multiple times, fixed-group membership drifts, or a release rebuilds under one identity |## Decision log@@ -561,14 +794,79 @@ Allow those marked surfaces to evolve through `[experimental]` patch releases.Promotion is a separate `[feat]` decision that moves the settled API onto its stablesurface; after that release the ordinary compatibility rules apply. Never use anexperimental marker to demote an already stable contract. Integration-theme-contributions are the single grandfathered exception because they shipped before-this declaration mechanism while still being introduced for early iteration.+contributions remain the single explicitly recorded grandfathered surface because+they shipped before this declaration mechanism while still being introduced for early+iteration.++That retroactive-marker prohibition does not make unpublished additions stable by+association. Integration-template replacement-specific declarations, selection,+optional projection, and expanded conflict fields remain pre-publication under FR2;+their classification is not an experimental enrollment. The already released same-id+conflict warning behavior remains stable.Rejected: moving a stable component into Lab to test one new API, scattering`unstableFoo` names through its ordinary prop namespace, relying on prose warningsthat tooling cannot verify, treating every recently added API as implicitlyexperimental, and retroactively marking another released stable surface unstable.+### DEC-10 — Replacement-first records own deprecation and cleanup++**Reference:** `spec:AST-017/DEC-10`+**Decider:** `cixzhang`, `2026-09-29`++Keep old and replacement behavior together in the final patch, identify each+transition with `DEP-*` and `CLN-*`, and permit removal only through the frozen minor+manifest. Direct authorities may impose a longer transition for their own surfaces;+release cadence never invents one.++Rejected: prose-only deprecation, silent removal, a global wait inferred from cadence,+and one cleanup id covering unrelated deltas.++### DEC-11 — Behavior-correcting incompatibility is not an ordinary fix++**Reference:** `spec:AST-017/DEC-11`+**Decider:** `cixzhang`, `2026-09-29`++A correction with a valid released victim keeps the `[fix]` Changeset tag and adds+`incompatible-fix` classification, an `IFIX-*` record, and an approved `CLN-*` item.+Pre-existing authority proves the expected behavior; latest-stable evidence proves the+victim. A victim-free restoration also uses `[fix]`, with `compatible` or+`contract-restoring` metadata and patch treatment. FR26 governs the public surface+while FR34 maps the `IFIX-*` record lifecycle to that surface state.++Rejected: treating every visible correction as breaking, using bare `[fix]` without+`incompatible-fix` metadata to hide a released victim, inventing an+`[incompatible-fix]` Changeset tag, or using generic `[breaking]` to avoid correction+evidence and rollback.++### DEC-12 — The paired minor admits only three delta classes++**Reference:** `spec:AST-017/DEC-12`+**Decider:** `cixzhang`, `2026-09-29`++Lock the final-patch baseline and classify every paired-minor delta as approved+cleanup, closed release metadata, or an independently patch-compatible fix. A fix+that lands after baseline lock may be disclosed in the minor without recutting the+patch solely for bookkeeping. Keep cleanup and compatible fixes separate in both the+manifest and release notes.++Rejected: unrelated features, unclassified deltas, an incompatible fix in the+compatible-fix lane, and strict byte identity that forces a needless replacement+final patch for an independently valid patch fix.++### DEC-13 — Cadence guides planning; readiness and authority gate the cut++**Reference:** `spec:AST-017/DEC-13`+**Decider:** `cixzhang`, `2026-09-29`++Plan minor releases generally no more often than once every fourteen calendar days,+but do not turn that interval into deprecation eligibility or a required wait between+the final patch and paired minor. A ready, authorized pair may publish sequentially.++Rejected: an inferred elapsed-time gate, a special exception merely to publish a+ready pair, and using cadence to waive replacement, migration, cleanup, or exact-main+evidence.+## Open questionsNone.diff --git a/docs/specs/AST-030/spec.md b/docs/specs/AST-030/spec.mdindex f2a0c05b9d..81b194620a 100644--- a/docs/specs/AST-030/spec.md+++ b/docs/specs/AST-030/spec.md@@ -54,6 +54,9 @@ they are separately named.- Add a test-specific or build-specific lane for work already owned by anexisting surface.- Apply changed-surface routing to post-merge `main` CI.+- Define compatibility semantics or release-pair delta classes. Those belong to+ [`spec:AST-017`](../AST-017/spec.md); this record routes their checks and owns the+ exact-main release-check execution boundary.- Remove required check names, branch protection, merge-queue coverage, orexact-head owner approval.- Infer safety from file extensions, directory names, or the absence of a knowndiff --git a/docs/specs/AST-040-consumer-file-modification/spec.md b/docs/specs/AST-040-consumer-file-modification/spec.mdindex d437298fb7..31979304f3 100644--- a/docs/specs/AST-040-consumer-file-modification/spec.md+++ b/docs/specs/AST-040-consumer-file-modification/spec.md@@ -36,7 +36,10 @@ project, including core, integration, and configuration codemods.- Creating new files, such as template copies or scaffolding. Their writeconfinement stays with `architecture:cli-surface`, and template copy behaviorstays with `spec:AST-028`.-- Defining individual migrations or their mappings.+- Defining individual migrations or their mappings. The+ [Release compatibility and versioning spec](../AST-017/spec.md) owns when a+ deprecation, planned cleanup, or incompatible fix requires migration evidence;+ this record owns how a consumer-file transform edits safely.- Choosing a command for inspecting effective settings; `spec:AST-017` FR20requires one.- Equivalent internal implementations remain valid when they satisfy this contract.diff --git a/docs/specs/AST-042-cli-command-admission/spec.md b/docs/specs/AST-042-cli-command-admission/spec.mdindex a56329efb0..87372e3724 100644--- a/docs/specs/AST-042-cli-command-admission/spec.md+++ b/docs/specs/AST-042-cli-command-admission/spec.md@@ -38,8 +38,8 @@ function, and the vocabulary that human-readable output may use.structure.- Discoverability, environment variables, global options, and configuration.`spec:AST-017` FR14–FR20 own those rules.-- Classifying a removal, rename, or behavior change. `spec:AST-017` FR1–FR8 own- compatibility.+- Classifying a removal, rename, behavior change, deprecation, or incompatible fix.+ [`spec:AST-017`](../AST-017/spec.md) owns compatibility and release lifecycle.- The JSON envelope, error codes, and generated help. `architecture:cli-surface`INV2, INV3, and INV7 own them.- Equivalent internal implementations remain valid when they satisfy this contract.diff --git a/docs/specs/AST-043-input-presentation/spec.md b/docs/specs/AST-043-input-presentation/spec.mdindex 092bb1e68b..4f8bf4d05d 100644--- a/docs/specs/AST-043-input-presentation/spec.md+++ b/docs/specs/AST-043-input-presentation/spec.md@@ -43,8 +43,10 @@ contracts, `architecture:public-component-api`, `family:input-fields`,each component, except the new surfaces DEC-3 approves. Eligibility/fallbackbehavior changes only as FR2 states (for `native`).- Renaming menu/selector `presentation` or their `adaptive` (OQ1).-- Removing `nativePicker` — breaking under `spec:AST-017`, needs its own- record. Migration tooling follows `spec:AST-017` FR8 using the FR3 mapping.+- Removing `nativePicker` — its concrete mapping remains owned here, while the+ deprecation record, cleanup id, Changeset, paired-minor treatment, and migration+ evidence follow [`spec:AST-017` FR28–FR44](../AST-017/spec.md) and the codemod+ follows `spec:AST-040`.## Requirements