Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

[Spec] AST-017: two rules and one gate — a planned minor needs no prior deprecation (#7328)

Cindy Zhanga8d6bf291924
diff --git a/docs/architecture/component-theming-surface.md b/docs/architecture/component-theming-surface.md
index 143578fd91..84298ca1d0 100644
--- a/docs/architecture/component-theming-surface.md
+++ b/docs/architecture/component-theming-surface.md
@@ -308,7 +308,7 @@ how themes become output, or the design rationale for a component's appearance.
| lifecycle | `DEP-0013` |
| delta | Components stop emitting the 21 alias classes. Theme build treats an alias key as an unknown component and suggests the canonical key. CLI discovery and generated docs list only canonical targets. `legacyNames`, `ThemePropsOptions`, and `deprecatedFor` are removed |
| rollback | Restore alias emission, metadata, and discovery from the final 0.6 baseline |
-| state | `pending` — lands only in a minor release whose frozen manifest lists `CLN-0022` |
+| state | `pending` — lands in a declared minor with its `[breaking]` Changeset |
### DEP-0014 — Deprecate bare prop and state classes
@@ -337,7 +337,7 @@ how themes become output, or the design rationale for a component's appearance.
| lifecycle | `DEP-0014` |
| delta | `themeProps()` emits one canonical target class and reflected `data-*` attributes; no bare prop or state class is rendered |
| rollback | Restore bare-class emission from the final 0.6 baseline |
-| state | `pending` — lands only in a minor release whose frozen manifest lists `CLN-0023` |
+| state | `pending` — lands in a declared minor with its `[breaking]` Changeset |
## Change coupling
diff --git a/docs/specs/AST-008/spec.md b/docs/specs/AST-008/spec.md
index ae1090abdf..7722d29b1b 100644
--- a/docs/specs/AST-008/spec.md
+++ b/docs/specs/AST-008/spec.md
@@ -238,8 +238,8 @@ TypeScript declaration metadata is not executable runtime behavior.
## Deprecation lifecycle
The three legacy surfaces follow `spec:AST-017` FR28–FR31 and FR29a–FR29d.
-They share one authoring mechanism but are distinct public contracts, so each owns
-a separate deprecation and cleanup id. Their direct authority is `spec:AST-008/FR18`.
+They share one authoring mechanism but are distinct public contracts, so each is
+described and removed separately. Their direct authority is `spec:AST-008/FR18`.
### `DefineThemeInput.color`
diff --git a/docs/specs/AST-017/spec.md b/docs/specs/AST-017/spec.md
index 02aeb2db25..e19058396c 100644
--- a/docs/specs/AST-017/spec.md
+++ b/docs/specs/AST-017/spec.md
@@ -46,6 +46,8 @@ affects_consumer_docs: [release-process, templates]
"DEC-12",
"DEC-13",
"DEC-14",
+ "DEC-17",
+ "DEC-18",
"FR3",
"FR4",
"FR5",
@@ -110,10 +112,9 @@ final-patch baseline.
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.
+be incompatible when consumers validly rely on its released behavior; that case is a
+`[breaking]` change that names the authority the released behavior violated and lands
+in a declared minor (FR31–FR34).
For CLI controls, keep every supported behavior discoverable and put each control on
the narrowest surface that owns it. Global controls require evidence that their value
@@ -153,7 +154,11 @@ one removal merged ahead of the decision to allow it.
accessibility behavior; stable CLI command names, options, exit behavior, and
machine-readable schemas; and other explicitly documented public extension
points. Internal implementation, undocumented markup, and source layout are not
- stable merely because a consumer can observe them.
+ stable merely because a consumer can observe them. A default change is judged by
+ one test (DEC-17): it is breaking when a caller who never set the prop sees their
+ shipped UI or output change, or when a documented contract promised the old default;
+ otherwise it is nonbreaking. Either way the Changeset names the old and new default
+ and the prop or option that restores the old default, which is the migration.
- **FR4 — Preserved old usage is nonbreaking.** A rename or replacement is
nonbreaking when the old released call, import, option, identifier, or input
continues to work with equivalent meaning through a compatibility alias or
@@ -176,23 +181,22 @@ one removal merged ahead of the decision to allow it.
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. A
- Changeset's bump states the tier its change requires; it never sets the release
- version, which is the version main declares under FR46.
+ `[experimental]`. The tag and the Changeset body are the whole declaration: a
+ victim-free correction is `[fix]` with a patch bump; a replacement-first
+ deprecation is `[feat]` that names the replacement and the migration and stays
+ patch-compatible while old usage works; a removal or a behavior-correcting
+ incompatibility is `[breaking]` and states the old valid usage, the replacement or
+ corrected behavior, and the migration (FR8). Lifecycle ids (`DEP-*`, `IFIX-*`,
+ `CLN-*`) and classification metadata are optional descriptive cross-references,
+ never a requirement to merge. While Astryx packages remain on `0.x`, the
+ incompatible tier is minor; compatible work is patch. A Changeset's bump states the
+ tier its change requires; it never sets the release version, which is the version
+ main declares under FR46.
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
+ be mass-migrated. `pnpm changeset:new` remains the authoring path, and
+ `pnpm check:changesets` validates tag, bump, contributors, and the declared tier;
+ the migration text is reviewed under FR8. 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
@@ -379,19 +383,20 @@ one removal merged ahead of the decision to allow it.
CLI command names, options, exit behavior, and machine-readable envelope remain
protected 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,
+ Outside a declared minor, changes to behavior, types, exports, CSS or tokens,
documented markup or selectors, accessibility semantics, persistence, CLI,
configuration, schemas, build tooling, contractual documentation operations, and
- package files MUST be additive, implementation-equivalent, or a victim-free
- contract restoration under FR5. Documentation catalog names and routes follow
+ package files MUST be additive, implementation-equivalent, a nonbreaking default
+ change under FR3, or a victim-free contract restoration under FR5; a breaking change
+ lands only in a declared minor (FR31). Documentation catalog names and routes
+ follow
FR45. 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.
+ `experimental`, `stable`, `deprecated`, or `removed`; private and unreleased surfaces
+ remain outside the published lifecycle. Stable cannot become experimental. Deprecated
+ behavior remains supported until a `[breaking]` removal merges for a declared minor
+ (FR31).
- **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.
@@ -402,15 +407,16 @@ one removal merged ahead of the decision to allow it.
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, actionable, and machine-readable.** A
- deprecation patch ships the working replacement while old usage remains equivalent.
- Before a surface enters `deprecated`, its supported modernization route MUST be
- available: an exact migration command or codemod when the rewrite is mechanical, or
- ordered and testable instructions when it is not. 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.
+- **FR28 — A planned minor needs no prior deprecation; a patch does.** A change
+ landing in a declared minor needs no deprecation path: its `[breaking]` Changeset
+ describing the change, with the replacement and migration where they help the
+ reader, is enough. A deprecation path is required only when the next planned release
+ is a patch, because a compatible release can only prepare a break: the patch ships
+ the working replacement while old usage remains equivalent, with an exact migration
+ command or codemod when the rewrite is mechanical or ordered, testable instructions
+ when it is not, and the removal lands in a later minor. A public record MAY describe
+ a deprecation with a stable `DEP-*` id and its replacement, migration, and state; the
+ record describes and never gates.
- **FR29 — Deprecation adds no production-runtime behavior.** Marking a surface
deprecated MUST NOT add a production runtime branch, log, byte, network action,
changed render, or changed output. Compatibility code needed to keep an already
@@ -422,15 +428,15 @@ one removal merged ahead of the decision to allow it.
- **FR29a — Warnings live at the earliest accurate authoring surface.** TypeScript
declarations use static `@deprecated` metadata. Build-interpreted source and
configuration warn in the authoring, validation, or build reader that can name the
- exact source use. CLI commands and options expose the deprecation id and replacement
+ exact source use. CLI commands and options expose the replacement
in their machine result and emit at most one human-readable stderr warning per
invocation. CSS and tokens use static diagnostics. Rendered applications never emit
a warning merely because a deprecated surface is used. Warnings MUST NOT change a
successful exit status, canonical output, machine-readable stdout, generated output,
or rendered behavior.
-- **FR29b — Guidance teaches one modern path.** Every warning names the `DEP-*` id,
- exact replacement, stable versioned instructions, and exact migration command when
- one exists. Maintained API docs, generated docs, templates, examples, stories,
+- **FR29b — Guidance teaches one modern path.** Every warning names the exact
+ replacement, stable versioned instructions, and exact migration command when one
+ exists. Maintained API docs, generated docs, templates, examples, stories,
starter output, and agent-facing guidance teach only the replacement. Explicit
reference remains available for the deprecated surface, visibly labeled with the
same replacement and modernization route. A warning MUST NOT ship before those
@@ -461,49 +467,34 @@ one removal merged ahead of the decision to allow it.
- **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
+ require a duration or number of stable releases for its own surface and names it
+ there. Release cadence MUST NOT be
interpreted as a deprecation clock or eligibility gate.
-- **FR31 — Cleanup is one-to-one with approved ids and proven modernization.** 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. Cleanup evidence MUST show that
- maintained sources no longer teach or use the old surface and that a latest-stable
- consumer can follow the supported old-to-new route; uncertain cases remain reported
- rather than guessed. 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.
+- **FR31 — No breaking change ships without a planned minor; the gate is the declared
+ version.** When `main` declares a minor (`x.y.0`), a `[breaking]` Changeset is
+ admitted and the change merges on ordinary review and CI. When `main` declares a
+ patch (`x.y.z`, `z > 0`), any `[breaking]` Changeset fails pull-request CI; what may
+ merge is the deprecation under FR28. `pnpm check:changesets` enforces this on every
+ pull request from the fixed group's declared version. Each incompatible delta maps to
+ exactly one `[breaking]` Changeset, which is the one place a reader finds the
+ description; maintained sources teach the replacement once the removal lands.
+ Lifecycle records and the release manifest describe removals; neither gates a merge.
+- **FR32 — A correction with a released victim is a breaking change.** 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, the correction is `[breaking]` and follows FR31 for the declared tier,
+ stating the corrected contract and the migration. A visible correction with no valid
+ released victim remains `[fix]` under FR5.
+- **FR33 — A correction's authority and victim are named.** The `[breaking]`
+ Changeset or its pull request names the pre-existing authority the released behavior
+ violated, a latest-stable reproducer, and the migration. Without pre-existing
+ authority, the proposal is a new contract decision for the direct owner, not a fix.
+- **FR34 — A correction follows the same tier rule.** In a declared minor a breaking
+ correction merges on its `[breaking]` Changeset. When `main` declares a patch, the
+ patch ships the corrected opt-in or adapter beside the old behavior (FR28) and the
+ later minor removes the old behavior. A breaking correction cannot enter a release
+ as an incidental compatible fix.
- **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
@@ -520,19 +511,22 @@ one removal merged ahead of the decision to allow it.
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.
+- **FR37 — Every minor has an owner-named target and a manifest generated at the
+ cut.** The owner names the target version on `main` (FR46). The minor's breaking set
+ is the set of `[breaking]` Changesets merged for it. At the cut the release generates
+ its manifest from the consumed Changesets as authored (FR41) — the breaking ones are
+ the minor's migration inventory, the rest its compatible fixes — and freezes it with
+ the cut for release notes and audit. The manifest describes; it never gates a merge. The release fails closed on any incompatible delta between the final patch and
+ the minor that no merged `[breaking]` Changeset describes (FR39, FR43). Operational
+ runbooks may add execution detail but cannot authorize or widen the breaking set.
- **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
+ patch with deprecated 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
+ partition into: (a) removals or corrections each described by one merged
+ `[breaking]` Changeset; (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
@@ -540,31 +534,27 @@ one removal merged ahead of the decision to allow it.
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
+ representative unchanged paths, and downstream proof, and is listed apart from the
+ breaking set in the release description. 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.
+- **FR41 — Release artifacts use closed schemas and invent no fields.** The cut-time
+ manifest (FR37) freezes each consumed Changeset exactly as authored — path, content
+ digest, packages, category, headline, contributors, and body — and derives breaking
+ versus compatible from the category; editorial text is generated from the body, never
+ from parallel fields a human must backfill. It also carries the release-metadata
+ deltas and the baseline receipts. The equivalence receipt carries final and candidate
+ digests plus `unclassifiedDeltas`. Unknown fields and one delta mapped more or less
+ than once fail.
+- **FR42 — Contributors declare compatibility intent once.** The Changeset is the
+ declaration: its tag and body state whether the change is compatible, a deprecation
+ with its replacement and migration, or a `[breaking]` change with its migration.
+ No parallel classification vocabulary, id, or plan field is required. 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
@@ -626,8 +616,7 @@ one removal merged ahead of the decision to allow it.
- **FR48 — Admission checks the declared tier.** The declared version is either
the patch successor or the minor successor of the latest stable release, and
that successor is the release tier. In a patch release, a Changeset carrying the
- `[breaking]` category, or the `planned-removal` or `incompatible-fix`
- classification of FR42, is inadmissible and MUST be rejected before the release
+ `[breaking]` category is inadmissible and MUST be rejected before the release
consumes it. The admissible routes are FR28's replacement-first deprecation,
which keeps old usage equivalent and lets the removal ship in a minor release,
or an owner bump of main to the minor successor before the cut. This gate
@@ -740,8 +729,7 @@ than restating them:
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.
+an incompatible change to its surface lands in a declared minor under FR31.
## Current-state impact
@@ -749,14 +737,15 @@ Public lifecycle classification remains in force with these operational effects:
- stable changes default to compatible patch treatment;
- experimental containment extends to every public surface kind;
-- deprecations are replacement-first, machine-readable, and cleanup-owned; warnings
- stay at authoring surfaces, production runtime stays unchanged, and an executable
+- a breaking change ships only in a declared minor, described by its `[breaking]`
+ Changeset; when `main` declares a patch, a deprecation ships first — warnings stay
+ at authoring surfaces, production runtime stays unchanged, and an executable
modernization route precedes warning delivery;
-- planned minors use a locked final-patch baseline while admitting only approved
- cleanup, closed release metadata, and independently patch-compatible fixes;
+- planned minors use a locked final-patch baseline, and the cut generates the
+ release description from the consumed Changesets;
- 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;
+- contributor declarations are the Changeset tag and body, with no parallel
+ lifecycle metadata and no migration of existing Changesets;
- documentation catalog display names and routes remain mutable data while the stable
`docs` command and machine-readable schemas stay contractual; and
- exact-main release comparison rejects unclassified deltas.
@@ -784,30 +773,30 @@ lands, maintainers apply its requirement 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 | 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/cleanup records; declaration/doc/build/CLI warning projections; old/new fixtures; dry-run/idempotence/migration tests; maintained-source and latest-stable upgrade evidence | whole component, prop/value, theme field/helper/token/target/source, CLI command, CLI option; old-only, new-only, both, static/dynamic/uncertain migration, text/JSON, development/production | A warning has no usable modernization route, production runtime changes for deprecation, maintained guidance teaches the old surface, a migration guesses, old behavior degrades early, cadence invents a wait, or one cleanup id covers multiple incompatible deltas |
-| 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 |
-| FR45 | Docs route inventory, repository-reference checks, and Changeset review | catalog entry rename, former-route miss, stable command and JSON schema | Catalog routing is frozen as API, or a rename silently changes the contractual command or response schema |
-| FR46–FR47 | Main pull-request checks against the newest stable tag and declared tier, canary version, and a release-versioning fixture on a pre-bumped branch | owner increase, allowed decrease, minor-to-patch decrease with pending `[breaking]`, equality/lower, split group, `[breaking]` on patch and minor plans | Main derives the version from pending Changesets, permits equality/lower, admits `[breaking]` on a patch plan, refuses it on a minor plan, allows a lowering PR to strand pending breaking work, or consuming a Changeset moves the declared version |
-| FR46 active cut | Main pull-request check against the single active branch marker and its cut declaration | no active cut, declaration above cut, declaration equal to cut before tag, declaration below cut, tagged equality on merge-back | A main PR lowers the declaration below an active untagged cut, equality is wrongly refused before the tag, or equality bypasses strict-above-stable outside trusted merge-back |
-| FR48 | Category and classification admission under each declared tier | patch release with `[breaking]`, patch release with a deprecation, minor release with `[breaking]` | Incompatible work passes in a patch release, or a deprecation is refused in one |
-| FR49 | Malformed and inconsistent declaration fixtures | disagreeing group versions, canary identifier, release version unlike the cut manifest, already-released version, skipped version, no stable tag | An untrustworthy or mismatched declaration is released |
-| FR50 | Three-way squash merge-back fixtures bound to the immutable tag, branch head, and plan digest | exact branch outputs, frozen deletion, branch-only marker exclusion, post-cut Changeset/manifest edit, newer main declaration, merge conflict, regenerated output | Merge-back differs from release bytes, lands lifecycle files, consumes post-cut work, overwrites a newer main declaration or unrelated field, or chooses a version |
-| FR51 | Separate next-plan manifest/pin/lockfile fixtures plus canary routing assertions | default patch successor, explicitly named minor, pre-advanced main plan, equality, unrelated PR during equality, later decrease above stable | Equality publishes a canary or admits unrelated work, the default skips a patch, pending Changesets choose a minor, exact pins split, merge-back requires a duplicate bump for an existing newer plan, or later planning stops being malleable |
+| 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 default change with and without a restoring prop | A change is labeled from diff size or possibility alone, a released contract change is missed, or a default-only change is tagged `[breaking]` without a named victim |
+| 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` (tag, bump, contributors, declared tier) plus FR8 migration review of `[breaking]` text | 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 | Declared-tier check: on a minor, the `[breaking]` Changeset describes the change (old usage, replacement, migration); on a patch, a breaking Changeset is refused and the deprecation ships instead; declaration/doc/build/CLI warning projections; old/new fixtures; dry-run/idempotence/migration tests; maintained-source and latest-stable upgrade evidence | whole component, prop/value, theme field/helper/token/target/source, CLI command, CLI option; old-only, new-only, both, static/dynamic/uncertain migration, text/JSON, development/production | A warning has no usable modernization route, production runtime changes for deprecation, maintained guidance teaches the old surface, a migration guesses, old behavior degrades early, cadence invents a wait, or one cleanup id covers multiple incompatible deltas |
+| FR32–FR35 | Latest-stable victim fixture, pre-existing authority named in the Changeset or pull request, owner review, declared-tier check, 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 | Owner-declared target, locked final-patch receipt, three-way delta classification against the merged `[breaking]` Changesets, 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 |
+| FR45 | Docs route inventory, repository-reference checks, and Changeset review | catalog entry rename, former-route miss, stable command and JSON schema | Catalog routing is frozen as API, or a rename silently changes the contractual command or response schema |
+| FR46–FR47 | Main pull-request checks against the newest stable tag and declared tier, canary version, and a release-versioning fixture on a pre-bumped branch | owner increase, allowed decrease, minor-to-patch decrease with pending `[breaking]`, equality/lower, split group, `[breaking]` on patch and minor plans | Main derives the version from pending Changesets, permits equality/lower, admits `[breaking]` on a patch plan, refuses it on a minor plan, allows a lowering PR to strand pending breaking work, or consuming a Changeset moves the declared version |
+| FR46 active cut | Main pull-request check against the single active branch marker and its cut declaration | no active cut, declaration above cut, declaration equal to cut before tag, declaration below cut, tagged equality on merge-back | A main PR lowers the declaration below an active untagged cut, equality is wrongly refused before the tag, or equality bypasses strict-above-stable outside trusted merge-back |
+| FR48 | Category and classification admission under each declared tier | patch release with `[breaking]`, patch release with a deprecation, minor release with `[breaking]` | Incompatible work passes in a patch release, or a deprecation is refused in one |
+| FR49 | Malformed and inconsistent declaration fixtures | disagreeing group versions, canary identifier, release version unlike the cut manifest, already-released version, skipped version, no stable tag | An untrustworthy or mismatched declaration is released |
+| FR50 | Three-way squash merge-back fixtures bound to the immutable tag, branch head, and plan digest | exact branch outputs, frozen deletion, branch-only marker exclusion, post-cut Changeset/manifest edit, newer main declaration, merge conflict, regenerated output | Merge-back differs from release bytes, lands lifecycle files, consumes post-cut work, overwrites a newer main declaration or unrelated field, or chooses a version |
+| FR51 | Separate next-plan manifest/pin/lockfile fixtures plus canary routing assertions | default patch successor, explicitly named minor, pre-advanced main plan, equality, unrelated PR during equality, later decrease above stable | Equality publishes a canary or admits unrelated work, the default skips a patch, pending Changesets choose a minor, exact pins split, merge-back requires a duplicate bump for an existing newer plan, or later planning stops being malleable |
## Decision log
@@ -1005,10 +994,10 @@ experimental, and retroactively marking another released stable surface unstable
**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.
+Keep old and replacement behavior together in the final patch when the next planned
+release is a patch; direct authorities may impose a longer transition for their own
+surfaces, and release cadence never invents one. DEC-18 supersedes the record-and-
+manifest gate this decision once carried.
Rejected: prose-only deprecation, silent removal, a global wait inferred from cadence,
and one cleanup id covering unrelated deltas.
@@ -1018,17 +1007,14 @@ and one cleanup id covering unrelated deltas.
**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.
+A correction with a valid released victim is not an ordinary fix: pre-existing
+authority proves the expected behavior, latest-stable evidence proves the victim, and
+the change ships as `[breaking]` in a declared minor under FR31–FR34. A victim-free
+restoration is `[fix]` with patch treatment. DEC-18 supersedes the `incompatible-fix`
+classification, `IFIX-*` record and `CLN-*` item this decision once required.
-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.
+Rejected: treating every visible correction as breaking, and hiding a released victim
+behind a bare `[fix]`.
### DEC-12 — The paired minor admits only three delta classes
@@ -1147,6 +1133,47 @@ Rejected: a runtime compatibility flag or branch used only to acknowledge deprec
a warning without an available modernization path, copyable guidance that keeps
teaching the old surface, and a migration that guesses at uncertain consumer intent.
+### DEC-17 — A default change is breaking when an untouched caller sees it
+
+**Reference:** `spec:AST-017/DEC-17`
+**Decider:** `cixzhang`, `2026-10-11`
+
+A default change is not breaking by itself and not compatible by itself; it is judged
+by a caller who never set the prop. If that caller's UI or output visibly changes —
+content gains padding, a grid lays out differently, a popover becomes a sheet on
+touch — the change is breaking and ships as `[breaking]` in a declared minor. If that
+caller sees nothing different, it is a `[feat]` or `[fix]`. In both cases the
+Changeset names the old and new default and the prop or option that restores the old
+default; that restoring prop is the migration, so a default change needs no
+deprecation path beyond it.
+
+Rejected: classifying every default change as breaking, which routes invisible
+changes through the minor for nothing; and classifying every default change as
+compatible, which lets a visible change reach callers in a patch without the minor's
+announcement.
+
+### DEC-18 — Two rules and one gate
+
+**Reference:** `spec:AST-017/DEC-18`
+**Decider:** `cixzhang`, `2026-10-11`
+
+Anything going into a planned minor needs no deprecation first; its `[breaking]`
+Changeset describing the change is enough. The two rules that govern compatibility
+are: no breaking change ships without a planned minor, and when the next planned
+release is a patch a deprecation path is required — deprecate in the patch, remove in
+a later minor. The one mechanical gate is the pull-request check that fails a
+`[breaking]` Changeset while `main` declares a patch version and admits it while
+`main` declares a minor. Everything else — lifecycle records, cleanup ids, the release
+manifest, transition rows, migration-evidence cells — is description: the manifest is
+generated at the cut from the consumed Changesets exactly as authored and frozen with
+the cut as the minor's migration inventory, and the cut fails closed on any
+incompatible final-patch-to-minor delta that no `[breaking]` Changeset describes.
+
+Rejected: a lifecycle record and frozen manifest that every removal had to appear in
+before merging, which duplicated the Changeset and made bookkeeping the blocker; a
+per-record transition requirement and waiver, which the patch rule already expresses;
+and dropping the manifest, which would lose the minor's migration inventory.
+
## Open questions
None.
diff --git a/docs/specs/AST-032/spec.md b/docs/specs/AST-032/spec.md
index 0b056ec7e3..d71ba3136a 100644
--- a/docs/specs/AST-032/spec.md
+++ b/docs/specs/AST-032/spec.md
@@ -187,7 +187,7 @@ name a complete registry could leave out.
| lifecycle | `DEP-0012` |
| delta | `IconRegistry` is `Record<IconName, ReactNode>`: a complete registry that omits `upload` fails to type-check |
| rollback | Restore the transitional optional `upload` from the final-patch baseline |
-| state | `pending` — lands only in a minor release whose frozen manifest lists `CLN-0021` |
+| state | `pending` — lands in a declared minor with its `[breaking]` Changeset |
## Open questions
diff --git a/docs/specs/AST-042-cli-command-admission/spec.md b/docs/specs/AST-042-cli-command-admission/spec.md
index 8451593de3..3088cd7d53 100644
--- a/docs/specs/AST-042-cli-command-admission/spec.md
+++ b/docs/specs/AST-042-cli-command-admission/spec.md
@@ -113,7 +113,9 @@ function, and the vocabulary that human-readable output may use.
- **FR6 — Moving surface is an admission.** Renaming a command, moving behavior
into a new command, or promoting a subcommand to a top-level command is an
admission at the new tier and MUST pass that tier's test. Removal and renaming
- also follow `spec:AST-017` FR1–FR8.
+ also follow `spec:AST-017` FR1–FR8 and FR31: a removal lands in a declared minor
+ with its `[breaking]` Changeset, and when the next release is a patch the command is
+ deprecated first (FR28).
- **FR7 — Exact-lookup admission classifies batching first.** Before code is written,
every new command or subcommand with an exact selector position MUST classify that
position against `spec:AST-053` FR11 E1-E5. An eligible surface MUST use AST-053's
@@ -236,7 +238,10 @@ option, which gives equivalent read-only lookups different automation contracts;
requiring a new system record for every subcommand exclusion, which defeats the tiered
bar.
-## Deprecation and cleanup records
+## Deprecation and cleanup descriptions
+
+These tables describe deprecations and removals for readers; the gate for a removal
+is the declared minor and its `[breaking]` Changeset (`spec:AST-017` FR31).
### DEP-0006 — Deprecate the `astryx layout` command group
@@ -254,7 +259,6 @@ bar.
| downstream | Maintained agent-docs teach `build` as the front door. The layout guide (`astryx docs layout`) is unaffected. |
| direct authority | `spec:AST-042` (CLI command admission and programmatic parity) |
| state | `deprecated` |
-| target plan | `CLN-0006` removal in the next scheduled minor |
### CLN-0006 — Remove the `astryx layout` command group
@@ -264,7 +268,7 @@ bar.
| lifecycle | `DEP-0006` |
| delta | Remove command registration, API exports (`layoutExpand`, `layoutCheck`, `layoutGrammar`), CLI bindings, command docs, tests, and the `layout.*` response types. |
| rollback | Re-register the command group with the same API, response types, and tests from the final-patch baseline. |
-| state | `pending` — lands only when a minor is scheduled and `CLN-0006` appears in its frozen manifest |
+| state | `pending` — lands in the declared minor with its `[breaking]` Changeset |
## Open questions
diff --git a/docs/specs/AST-050-app-themes/spec.md b/docs/specs/AST-050-app-themes/spec.md
index 19b22ee10d..f070f92212 100644
--- a/docs/specs/AST-050-app-themes/spec.md
+++ b/docs/specs/AST-050-app-themes/spec.md
@@ -198,9 +198,9 @@ described.
its machine result are the released ones. `theme add --list` keeps its
machine result at every stage, and its text names the commands of the
current stage.
- 2. **Cleanup is a scheduled minor.** Once a minor's frozen manifest carries
- the deprecation id and its cleanup id (`spec:AST-017/FR31`),
- `theme add <slug>` imports as FR1 states, with or without `--import`, and
+ 2. **Cleanup lands in a declared minor.** When `main` declares a minor, a
+ `[breaking]` Changeset describing the change (`spec:AST-017/FR31`) lets
+ `theme add <slug>` import as FR1 states, with or without `--import`, and
returns `theme.app`, and `theme add` accepts no target path or
`--overwrite`, which stay on `theme eject`. That minor carries no other
delta from this record (`spec:AST-017/FR39`).
diff --git a/docs/specs/AST-056-search-prop-shape/spec.md b/docs/specs/AST-056-search-prop-shape/spec.md
index 089a830d3a..6f36a0e76f 100644
--- a/docs/specs/AST-056-search-prop-shape/spec.md
+++ b/docs/specs/AST-056-search-prop-shape/spec.md
@@ -236,7 +236,7 @@ copying.
| FR4 | Who resolves the query is settled by who owns the choices, and is not restated per component. A component that holds its own choice set resolves the query itself, matching case-insensitively on each choice's displayed label at minimum, and exposes a boolean to turn the query input on. A component whose presented choices ARE the query's result takes a required `searchSource`. Both kinds reach the same observable states: a narrowed list, an empty result, and `emptyText`. | DEC-2; `spec:AST-002` FR16 | Proposed; shipped behavior, unspecified |
| FR5 | A capability that cannot function without a typed query MUST have exactly one switch, and MUST report through the component's primary change callback with a descriptor naming the kind of change, rather than through a handler prop of its own. A caller MUST NOT be able to express a configuration that renders nothing and reports nothing, which `hasCreate && hasSearch && onCreate != null` permits whenever any one piece is missing. Enabling it on a component with no query input MUST warn in development rather than fail silently. | DEC-3; `spec:AST-002` FR15 (never silently render a broken state) | Proposed; no evidence on `main` |
| FR6 | A new search-related capability is admitted under `spec:AST-002` against this record, or not at all. A new top-level prop whose name carries the word `search` MUST name the state or capability it governs in the vocabulary this record fixes, and MUST NOT introduce a second name for a state one of these props already expresses. | DEC-4; `spec:AST-002` FR1, FR5, DEC-1 | Proposed; no evidence on `main` |
-| FR7 | Every prop this record renames is a released public surface with a victim, so it MUST follow `spec:AST-017` FR28–FR31: the replacement ships first, old usage stays equivalent through the overlap, each old prop gets a `DEP-*` id and a distinct `CLN-*` id, and removal happens only in a minor whose frozen manifest carries both. While both exist, a component given both MUST resolve to the new prop and MUST fire a development warning. | `architecture:public-component-api` INV9; `spec:AST-017` FR1, FR3, FR28–FR31 | Proposed; cycle not started |
+| FR7 | Every prop this record renames is a released public surface with a victim, so it MUST follow `spec:AST-017` FR28–FR31: the replacement ships first, old usage stays equivalent through the overlap, and removal happens in a declared minor with a `[breaking]` Changeset naming the replacement. While both exist, a component given both MUST resolve to the new prop and MUST fire a development warning. | `architecture:public-component-api` INV9; `spec:AST-017` FR1, FR3, FR28–FR31 | Proposed; cycle not started |
### Accessibility contract
@@ -297,10 +297,9 @@ coexist indefinitely, not replace.
carries `@deprecated` naming its replacement, and behaves exactly as before
(`spec:AST-017` FR28, FR29). During the overlap a component reads both and
the new prop wins, with one development warning on conflict (FR7).
-- Each old prop gets a `DEP-*` id and a distinct `CLN-*` id. Removal happens in
- a later minor only when both ids are in that minor's frozen manifest
- (`spec:AST-017` FR31). This record sets no clock; FR30 forbids reading
- release cadence as one.
+- Removal happens in a later declared minor with a `[breaking]` Changeset that
+ names the replacement (`spec:AST-017` FR31). This record sets no clock; FR30
+ forbids reading release cadence as one.
- A caller who passed a `string` needs no edit beyond the name: the type only
widens, so every existing value stays valid.
@@ -372,7 +371,7 @@ describes, so `Tokenizer` already conforms and changes nothing.
| FR5, AR1 | Per-adopter suites plus their live-region assertions | A string `emptyText`; an element `emptyText`; the adjacent "no choices at all" state | A differently named or typed key, or an announcement that does not carry what the element rendered, fails. This is the gap AR1 names on `main` today. |
| FR6, FR7 | Type-level checks plus per-adopter suites | `onCreate` given with `search` present; `onCreate` given with `search` absent | A create affordance reachable without search, a boolean gating a handler, or a silently inert configuration, fails. |
| FR8 | Per-adopter suites | Typing; clearing; programmatic change | A callback that suppresses the component's own resolution, or a component requiring it, fails. |
-| FR9 | Overlap suites on each adopter plus the release lifecycle's manifest checks | Old prop alone; key alone; both given; neither | Old usage changing behavior, a silent win for the old prop, a missing `DEP-*`/`CLN-*` pair, or a removal absent from the frozen minor manifest, fails. |
+| FR9 | Overlap suites on each adopter plus the declared-tier Changeset check | Old prop alone; key alone; both given; neither | Old usage changing behavior, a silent win for the old prop, a missing `DEP-*`/`CLN-*` pair, or a removal absent from the frozen minor manifest, fails. |
| FR10, AR2 | Public-API review against this record; per-adopter accessible-name assertions | A proposed new search capability; each adopter's query input, named and unnamed | A new top-level `search*` prop admitted, or a query input whose only name is its placeholder, fails. |
Known verification gap: none of the suites above exist on `main`, and no
@@ -504,8 +503,8 @@ review without anybody restructuring a component.
`cixzhang`, 2026-10-02: `emptySearchResultsText` is marked `@deprecated`
pointing at `emptySearchText`, both work through the overlap, and removal
- happens in a later minor under `spec:AST-017` FR28–FR31. The cost is three
- `DEP-*`/`CLN-*` pairs and one doubled prop on three components, which is
+ happens in a later minor under `spec:AST-017` FR28–FR31. The cost is one
+ doubled prop on three components, which is
what FR7 already describes — far less than the nine pairs the rejected
object form would have cost. The rename is codemoddable even where a caller
spreads props, because the value's meaning does not change and the type only
diff --git a/docs/specs/AST-066-theme-data-boundary/spec.md b/docs/specs/AST-066-theme-data-boundary/spec.md
index 5eba96ccd6..16dd912014 100644
--- a/docs/specs/AST-066-theme-data-boundary/spec.md
+++ b/docs/specs/AST-066-theme-data-boundary/spec.md
@@ -552,7 +552,7 @@ this decision removes and make runtime/static ownership mode-dependent.
| lifecycle | `IFIX-0009` |
| delta | Runtime and built themes emit only authored data values, scoped to their theme. Explicit layer order and global `color-scheme` rules are unchanged |
| rollback | Restore the raw default block from the final-patch baseline |
-| state | `pending` — lands only in a minor release, once `IFIX-0009` is approved and that release's frozen manifest lists `CLN-0016` |
+| state | `pending` — lands in a declared minor with its `[breaking]` Changeset |
## Open questions
diff --git a/packages/core/src/Banner/Banner.spec.md b/packages/core/src/Banner/Banner.spec.md
index 5e8b2d68a7..5bff012157 100644
--- a/packages/core/src/Banner/Banner.spec.md
+++ b/packages/core/src/Banner/Banner.spec.md
@@ -76,7 +76,7 @@ Consumer migration instructions belong in consumer docs and release notes.
| lifecycle | `DEP-0007` |
| delta | `Banner` renders no `role` and no `aria-live` unless the caller passes `role`. Visual status styling, icons, theming targets, and explicit `role` forwarding are unchanged |
| rollback | Restore the `status`-to-role map from the final-patch baseline |
-| state | `pending` — lands only in a minor release whose frozen manifest lists `CLN-0015` |
+| state | `pending` — lands in a declared minor with its `[breaking]` Changeset |
## Ownership boundary
diff --git a/packages/core/src/BottomSheet/BottomSheet.spec.md b/packages/core/src/BottomSheet/BottomSheet.spec.md
index 998e15b21b..528680f4f4 100644
--- a/packages/core/src/BottomSheet/BottomSheet.spec.md
+++ b/packages/core/src/BottomSheet/BottomSheet.spec.md
@@ -81,7 +81,7 @@ Consumer migration instructions belong in consumer docs and release notes.
| lifecycle | `DEP-0009` |
| delta | With no `padding` prop and no theme padding, the Content area insets by `--spacing-4` on every logical edge and publishes that inset |
| rollback | Restore the unpadded default from the final-patch baseline |
-| state | `pending` — lands only in a minor release whose frozen manifest lists `CLN-0018` |
+| state | `pending` — lands in a declared minor with its `[breaking]` Changeset |
## Ownership boundary
diff --git a/packages/core/src/Grid/Grid.spec.md b/packages/core/src/Grid/Grid.spec.md
index 2988faaae6..c51e910513 100644
--- a/packages/core/src/Grid/Grid.spec.md
+++ b/packages/core/src/Grid/Grid.spec.md
@@ -72,7 +72,7 @@ Consumer migration instructions belong in consumer docs and release notes.
| lifecycle | `DEP-0010` |
| delta | A numeric `columns` value renders up to N columns of at least 12rem and fewer when the grid is narrower; a `GridSpan` in such a grid takes the full row once the grid has fewer columns than it spans |
| rollback | Restore `repeat(N, 1fr)` for numeric `columns` from the final-patch baseline |
-| state | `pending` — lands only in a minor release whose frozen manifest lists `CLN-0019` |
+| state | `pending` — lands in a declared minor with its `[breaking]` Changeset |
## Ownership boundary
diff --git a/packages/core/src/Selector/Selector.spec.md b/packages/core/src/Selector/Selector.spec.md
index 04a1e9cd19..2aba24874f 100644
--- a/packages/core/src/Selector/Selector.spec.md
+++ b/packages/core/src/Selector/Selector.spec.md
@@ -95,7 +95,7 @@ connection between the closed trigger and its selection surface.
| lifecycle | `DEP-0011` |
| delta | With no `presentation`, a compact coarse-pointer screen opens a modal bottom sheet (trigger `aria-haspopup="dialog"`, focus moves in and returns on close); every other device keeps the anchored popover. Compound DropdownMenus are unchanged |
| rollback | Restore the `popover` default from the final-patch baseline |
-| state | `pending` — lands only in a minor release whose frozen manifest lists `CLN-0020` |
+| state | `pending` — lands in a declared minor with its `[breaking]` Changeset |
## Ownership boundary