An open source design system that's fully customizable and agent ready
TypeScript
ci(release): remove main version PR gate (#7425)
Cindy Zhangbc0261aeea24
diff --git a/.github/scripts/release-publish-workflow.test.mjs b/.github/scripts/release-publish-workflow.test.mjsindex 3660d2ead4..fb2fc11d32 100644--- a/.github/scripts/release-publish-workflow.test.mjs+++ b/.github/scripts/release-publish-workflow.test.mjs@@ -130,23 +130,11 @@ describe('stable and canary publication authority', () => {expect(lintScope).toContain('chore/merge-v*-to-main');expect(lintScope).toContain("grep -Eq '^[0-9]+\\.[0-9]+\\.[0-9]+$'");- const declared = step(- lint.jobs.lint,+ const requiredLintText = JSON.stringify(lint.jobs.lint);+ expect(requiredLintText).not.toContain("Keep main's declared version above latest stable",);- expect(declared.if).toBe(- "github.event_name == 'pull_request' && steps.release-merge-back-scope.outputs.required != 'true'",- );- expect(declared.run).toContain(- 'git show origin/main:scripts/release/active-release.mjs',- );- expect(declared.run).toContain("'refs/tags/v*:refs/tags/v*'");- expect(declared.run).toContain(- "'+refs/heads/release/v*:refs/remotes/origin/release/v*'",- );- expect(declared.run).not.toContain('allow-bootstrap-equal');- expect(declared.run).toContain('validate-main-version');- expect(declared.run).toContain('--base origin/main');+ expect(requiredLintText).not.toContain('validate-main-version');expect(JSON.stringify(mergeBack)).not.toContain('validate-main-version');expect(step(lint.jobs.lint, 'Check Changeset coverage').if).toBe(diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.ymlindex 279290fd21..a270c0c4be 100644--- a/.github/workflows/lint.yml+++ b/.github/workflows/lint.yml@@ -48,9 +48,9 @@ jobs:>> "$GITHUB_OUTPUT"fi- # Merge-back is the one trusted path allowed to leave main equal to the- # newest stable tag (spec:AST-017 FR50). Detect it before the ordinary- # version guard so required lint can route to the stronger validator.+ # Merge-back carries exact published release-branch outputs into main under+ # trusted validation (spec:AST-017 FR50). Detect its branch contract so+ # required lint can route it to the stronger validator.- name: Detect the release merge-back branch contractif: github.event_name == 'pull_request'id: release-merge-back-scope@@ -69,24 +69,6 @@ jobs:esacecho "required=$required" >> "$GITHUB_OUTPUT"- # Every ordinary main PR must keep the declaration above stable. The- # separate FR51 next-plan PR exits merge-back equality; no bootstrap or- # generic equality exception exists.- - name: Keep main's declared version above latest stable- if: github.event_name == 'pull_request' && steps.release-merge-back-scope.outputs.required != 'true'- run: |- set -eu- git fetch origin main 'refs/tags/v*:refs/tags/v*' '+refs/heads/release/v*:refs/remotes/origin/release/v*'- TRUSTED_POLICY="$RUNNER_TEMP/main-version-policy"- mkdir -p "$TRUSTED_POLICY/scripts/release" "$TRUSTED_POLICY/scripts/lib"- git show origin/main:scripts/release/active-release.mjs \- > "$TRUSTED_POLICY/scripts/release/active-release.mjs"- git show origin/main:scripts/lib/workspace-globs.mjs \- > "$TRUSTED_POLICY/scripts/lib/workspace-globs.mjs"- node "$TRUSTED_POLICY/scripts/release/active-release.mjs" validate-main-version \- --root "$GITHUB_WORKSPACE" \- --base origin/main-- name: Validate release merge-back in required lintif: github.event_name == 'pull_request' && steps.release-merge-back-scope.outputs.required == 'true'env:diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 98963b2104..a24600f335 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -711,10 +711,12 @@ slugs and docs routes, are data and may change.- **Main declares the next version.** The fixed group's version in main's`package.json` files is the next planned release. Before a cut, an owner may- raise or lower it while it stays strictly above newest stable. While an- untagged cut is active, main may stay equal to that cut or rise, but cannot be- lowered below it. After the tag, ordinary PRs must be strictly above stable;- trusted merge-back is the only equality exception and publishes no canary.+ raise or lower it while it stays strictly above newest stable. Required+ pull-request lint does not compare that declaration with stable or an active+ cut. The canary publisher publishes only while one plain fixed-group+ declaration is above newest stable, skips equality, and fails below-stable or+ split declarations. Trusted merge-back leaves main's declaration untouched;+ a separate owner change declares the next plan after the release.- **0.x: the category states the tier a change needs.** A `[breaking]`Changeset declares `minor` and is admitted only while main already declaresthe next minor. `[experimental]` and every other category declare `patch`.diff --git a/docs/release.md b/docs/release.mdindex 8b6d5be029..144c98e482 100644--- a/docs/release.md+++ b/docs/release.md@@ -42,11 +42,12 @@ stable package is built from an immutable release tag and published with provenaexact internal pins, and lockfile. The released version's patch successor is thedefault. A minor successor is used only when the owner explicitly names it.-While an untagged cut is active, main may keep the cut version or move higher but-cannot be lowered below it. After the tag exists, ordinary main PRs must stay-strictly above the newest stable tag. Trusted merge-back is the only equality-exception. The canary workflow succeeds without publishing from equality; the-separate next-plan PR exits that state immediately after merge-back.+After a cut, main's declaration remains its future plan and may change independently+of the frozen release branch. Required pull-request lint does not compare it with the+cut or newest stable tag. Canary publication owns that ordering boundary: it publishes+only from one plain declaration above stable, skips equality, and fails below-stable or+split declarations. Trusted merge-back preserves main's declaration; the separate+next-plan PR advances it after the release.## Changesets and codemodsdiff --git a/docs/specs/AST-017/spec.md b/docs/specs/AST-017/spec.mdindex 3c58230b52..28783e9a45 100644--- a/docs/specs/AST-017/spec.md+++ b/docs/specs/AST-017/spec.md@@ -581,32 +581,17 @@ one removal merged ahead of the decision to allow it.names, and names are outside this requirement and remain governed separately by FR9,FR11, and applicable registry identity contracts.- **FR46 — Main declares the next planned version.** The fixed package group's- version in main's `package.json` files is the next planned release version. A- release owner may raise or lower it on main; before a cut that changes the release- being planned, and after a cut it changes only main's future plan because the release- branch remains bound to its cut declaration. While that cut is active and its stable- tag does not yet exist, the active cut version is an additional floor: main's- declaration may stay equal to it or rise, but MUST NOT be lowered below it. Once the- tag exists, the ordinary strict-above-stable rule applies except while that exact- published branch's merge-back is still pending: the tag and active branch MUST name- the same commit and every frozen Changeset MUST remain byte-identical on main. That- narrow equality window closes when merge-back consumes those Changesets. The- declaration MUST otherwise remain a plain version strictly greater than the newest- stable `vX.Y.Z` tag except for the trusted release-return equality described by- FR50–FR51. For example, after `v0.6.7`, changing- `0.7.0` to `0.6.8` is valid only when no pending `[breaking]` Changeset would become- inadmissible; the lowering pull request itself MUST be refused otherwise. Changing the- plan to `0.6.7` or lower is not valid. When main has not advanced before merge-back,- its unchanged release declaration equals the new stable tag from publication through- FR50 until FR51's required next-plan change. Main publishes only canaries, versioned- `<declared version>-canary.<commit>`, and MUST NOT publish a canary from that equality- state. Pull-request checks on main compare the declaration with the newest stable tag,- admit equality only during that exact frozen merge-back window, refuse every other- version at or below the tag or a split fixed group, refuse a pending `[breaking]`- Changeset while the declaration is a patch, admit that category while the declaration is- the minor successor, validate merge-back under FR50 and the next-plan change under FR51,- and validate every other Changeset's format, category, bump, and coverage. Pending- Changesets do not derive or promote the release version.+ version in main's `package.json` files is the owner-selected next release plan. A+ release owner may raise or lower it before a cut; after a cut, changing it affects+ only main's future plan because the release branch remains bound to its cut+ declaration. Pending Changesets do not derive or promote the version. Pull-request+ lint does not compare main's declaration with the newest stable tag or an active+ cut. Canary publication owns that ordering boundary instead: the fixed group MUST+ declare one plain version; a declaration strictly above the newest stable tag+ publishes `<declared version>-canary.<commit>`, equality publishes nothing, and a+ lower or split declaration fails rather than publishing. Changeset admission still+ refuses `[breaking]` work while main declares a patch and admits it while main+ declares the minor successor.- **FR47 — A release branch releases the declared version.** A release branch'sversion is the fixed-group version declared at its cut commit. Admission, therelease plan, Changeset consumption, changelog generation, and stable@@ -648,22 +633,19 @@ one removal merged ahead of the decision to allow it.trusted required check binds the merge-back to the immutable tag, release branch head,and plan digest, proves the release-owned bytes and frozen deletions equal the branch,proves post-cut preservation, and refuses every unrelated mutation. FR50 never chooses- or lowers the next plan. Merge-back preserves main's current declaration; when it- still equals the released version, this trusted path is the only exception to the- strict-above-stable rule and no canary publishes from that transient equality state.-- **FR51 — The next plan is an owner change separate from merge-back.** Immediately- after FR50 lands, a separate pull request changes every fixed-group package version,- every generated exact internal pin, and the lockfile to the next planned version. The- default is the patch successor of the released version. The minor successor is used- only when Cindy explicitly names that minor as the next plan; pending `[breaking]`- Changesets are not that decision. This is the only allowed transition out of FR50's- equality state, so other main changes remain held until it lands. If main already- carries a newer owner plan, FR50 preserves it and no duplicate bump is required.- Afterward the plan is again strictly above the newest stable tag and remains malleable- under FR46 until the next cut. A rejection names the declared version, active cut,- latest stable release, and both ways forward — deprecate under FR28, or explicitly- plan the minor under FR46 — so a contributor who has never read this spec can act on- it.+ or lowers the next plan. Merge-back preserves main's current declaration. When it+ equals or falls below the released version, FR46's canary publication check emits no+ prerelease at equality and fails below it.+- **FR51 — The next plan is an owner change separate from merge-back.** After FR50+ lands, a separate pull request changes every fixed-group package version, every+ generated exact internal pin, the lockfile, and version-stamped compatibility assets+ to the next planned version. The default is the patch successor of the released+ version. The minor successor is used only when Cindy explicitly names that minor as+ the next plan; pending `[breaking]` Changesets are not that decision. Other main work+ need not wait for this bookkeeping change, but FR46 suppresses canary publication+ until the declaration is strictly above stable. If main already carries a newer+ owner plan, FR50 preserves it and no duplicate bump is required. The plan remains+ malleable under FR46 until the next cut.### Platform support@@ -753,21 +735,16 @@ Public lifecycle classification remains in force with these operational effects:`docs` command and machine-readable schemas stay contractual; and- exact-main release comparison rejects unclassified deltas.-Main declares the next planned version, may raise or lower that plan above the newest-stable tag, and publishes canaries of it. A lowering PR cannot strand pending-`[breaking]` work on a patch plan: it is refused before main turns red. A release branch-releases the cut's declaration unchanged and admits incompatible work only when it is a-minor; the Changeset cannot choose that version itself. During an active cut before-its tag, main may stay equal to the cut or rise but cannot be lowered below it. After-publication, the branch's release-owned bytes squash back into current main without-regenerating them, consuming post-cut work, or overwriting a newer declaration. When-main still equals the released tag, merge-back is the trusted equality exception and-publishes no canary. A separate owner change immediately follows and declares the next-plan—patch successor by default, minor only when Cindy names it. Because the fixed-package group publishes as one version, this admission gate prevents one unapproved-removal from moving the whole release to a minor. It does not add a per-change approval-path: lifecycle, cleanup, migration, and freeze requirements remain independently-enforceable.+Main declares the next planned version, and Changeset admission uses that declaration+to refuse `[breaking]` work on a patch plan. Pull-request lint does not compare the+declaration with stable or an active cut. The canary publisher compares at publication+time: strictly above stable publishes, equality skips, and lower or split declarations+fail closed. A release branch releases the cut's declaration unchanged and admits+incompatible work only when it is a minor; the Changeset cannot choose that version+itself. Published branch bytes squash back into current main without regeneration,+post-cut consumption, or plan changes. A separate owner change declares the next plan—+patch successor by default, minor only when Cindy names it—without holding unrelated+main work.These requirements alter no published package by themselves and need no Changeset.Authoring helpers, validators, metadata projections, compatibility snapshots, release@@ -776,30 +753,29 @@ 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 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 |+| 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 | Declared-tier Changeset admission, canary publication ordering, and release-versioning fixtures | owner increase/decrease, above/equal/below stable, split group, `[breaking]` on patch and minor plans | Pending Changesets derive the plan, `[breaking]` passes on a patch or fails on a minor, equality publishes a canary, or a lower/split declaration publishes instead of failing |+| 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/compatibility-asset fixtures plus canary routing assertions | default patch successor, explicitly named minor, pre-advanced main plan, unrelated main work during equality | Equality publishes a canary, the default skips a patch, pending Changesets choose a minor, exact pins or compatibility assets split, or merge-back requires a duplicate bump for an existing newer plan |## Decision log@@ -1067,53 +1043,36 @@ Rejected: treating every route-shaped positional value as stable CLI API. That wfreeze documentation organization rather than protect the command and schemacontracts readers and automation rely on.-### DEC-15 — Main declares the plan; the release branch returns shipped bytes+### DEC-15 — Main declares the plan; publication enforces ordering**Reference:** `spec:AST-017/DEC-15`-**Decider:** `cixzhang`, `2026-10-09`--Main's `package.json` carries the next planned version and main publishes only-canaries of it. A release owner may raise or lower that plan while keeping it strictly-above the newest stable tag, but a lowering PR cannot make a pending `[breaking]`-Changeset inadmissible. Release tooling runs on a release branch, which takes the cut-declaration unchanged; admission, versioning, changelogs, and stable publication happen-there. Later main planning cannot change that branch release.--After cut and before its tag exists, the active branch version is a second floor for-main: a later plan may stay equal or rise, but cannot be lowered below the release in-progress. After publication, a three-way squash projection returns the exact-release-owned branch bytes to current main while preserving post-cut work and the-declaration main holds. When that declaration still equals the release, merge-back is-the sole trusted strict-above-stable exception and publishes no canary. A separate owner-change immediately afterward declares the patch successor by default, or the minor-successor only when Cindy names it. This keeps proof of what shipped distinct from the-decision about what ships next.--Declaring the version on main makes release shape an owner decision without turning an-early estimate into a one-way ratchet. Pull-request checks require the plan to be at-least the active untagged cut, strictly greater than the newest stable tag outside-trusted merge-back, and refuse a minor-to-patch lowering while pending breaking work-exists. The cut additionally requires the patch or minor successor under FR48–FR49.-FR50 preserves current main; FR51 advances it after merge-back. Because the fixed group-publishes one version, consuming a `[breaking]` Changeset on a branch that already-declares the minor writes changelogs for that minor and never bumps again.--A `[breaking]` Changeset is admissible on main only while main already declares the-minor successor. While main declares a patch, the pull-request gate holds it until the-work becomes a compatible deprecation or Cindy explicitly plans the minor. The-Changeset is evidence about the work, never authority to change the plan.--Rejected: deriving the version from pending Changesets, because the entry being judged would be its own authorization.--Rejected: a dated schedule file beside `package.json`, because two declarations of the next version can disagree.--Rejected: regenerating or copying release outputs into an independent sync change, because merge-back must prove the bytes came from the published branch.--Rejected: folding the next-version bump into merge-back, because shipped-byte reconciliation and the next owner plan are separate decisions.--Rejected: resetting a newer main declaration to the released version, because release-branch authority owns shipped outputs, not post-cut planning on main.--Rejected: checking only the newest stable tag while an untagged cut is active, because main could be lowered below the release already in progress.+**Decider:** `cixzhang`, `2026-10-09`; revised `2026-10-12`++Main's `package.json` carries the owner-selected next planned version. Release tooling+runs on a release branch and takes the cut declaration unchanged; admission, versioning,+changelogs, and stable publication happen there. Later main planning cannot change that+branch release. After publication, a three-way squash projection returns the exact+release-owned branch bytes to current main while preserving post-cut work and main's+declaration. A separate owner change declares the patch successor by default, or the+minor successor only when Cindy names it.++Required pull-request lint does not compare main's declaration with stable or an active+cut, because prerelease ordering belongs to canary publication rather than ordinary PR+admission. The canary publisher is the smaller authority boundary: it publishes only+when one plain fixed-group declaration is strictly above the newest stable tag, skips+equality, and fails below-stable or split declarations. Changeset admission independently+refuses `[breaking]` work on a patch plan and admits it on a declared minor.++Rejected: deriving the version from pending Changesets, because the entry being judged+would be its own authorization; publishing a canary at or below stable; regenerating+release outputs during merge-back; and folding the next owner plan into shipped-byte+reconciliation.++Rejected: a dated schedule file beside `package.json`, because two declarations of the+next version can disagree.++Rejected: resetting a newer main declaration to the released version, because release-+branch authority owns shipped outputs, not post-cut planning on main.### DEC-16 — Deprecation acts at authoring surfaces, not production runtimediff --git a/docs/specs/AST-030/spec.md b/docs/specs/AST-030/spec.mdindex 0e8a52e012..3a81a65bd5 100644--- a/docs/specs/AST-030/spec.md+++ b/docs/specs/AST-030/spec.md@@ -116,9 +116,9 @@ they are separately named.and `lint` MUST continue to report on every pull request through their existingjobs or join jobs. A specialized lane skips owned steps inside those jobs; itdoes not remove historical required contexts. Any owned lane failure MUST fail- its join. The required lint context MAY admit main's published-version equality- only when trusted release authority proves the exact frozen merge-back is still- pending; the context still runs and fails closed outside that window.+ its join. Required lint does not compare main's package declaration with the newest+ stable release; AST-017 assigns prerelease ordering to the canary publisher and keeps+ immutable release merge-back validation in required lint.- **FR8 — Initial tooling admissions.** `node-tooling` covers`scripts/score-ledger.mjs`, `scripts/score-ledger.test.mjs`,`internal/scripts/`, and `.github/workflows/crowdin-upload.yml`. It runs thediff --git a/scripts/release/active-release.mjs b/scripts/release/active-release.mjsindex 66e7f40799..9c63e78e94 100644--- a/scripts/release/active-release.mjs+++ b/scripts/release/active-release.mjs@@ -843,137 +843,6 @@ function validateReleaseMergeBack({return errors;}-/**- * The published-equality window exists only while the immutable release still- * has one exact active branch and every frozen Changeset remains on main for- * the pending merge-back to consume.- */-function pendingMergeBackVersion({- releasedVersion,- activeBranches,- marker,- plan,- releaseHead,- branchHead,- baseChangesets,-}) {- if (- !VERSION_RE.test(releasedVersion ?? '') ||- activeBranches.length !== 1 ||- marker?.state !== 'active' ||- marker.version !== releasedVersion ||- marker.branch !== activeBranches[0] ||- releaseHead !== branchHead ||- validateIdentity(marker, plan).length > 0 ||- plan.changesets.some(- entry => baseChangesets.get(entry.path) !== entry.sha256,- )- )- return null;- return releasedVersion;-}--/**- * FR46/FR51 — main's fixed-group version on a pull request into main.- *- * Main carries a malleable plan until cut. It may move up or down, but always- * remains one plain version strictly above the newest stable release. When the- * base still equals that release after merge-back, the first plan may only be- * its patch successor (default) or its owner-named minor successor.- *- * @param {object} input- * @param {string[]} input.fixed trusted fixed-group package names- * @param {string} input.releasedVersion newest stable vX.Y.Z tag, without v- * @param {string|null} [input.activeCutVersion] single active untagged/ongoing cut- * @param {string|null} [input.pendingMergeBackVersion] exact published version whose frozen Changesets remain on main- * @param {Map<string, object|null>} input.baseManifests name -> manifest at base- * @param {Map<string, object|null>} input.headManifests name -> manifest at head- * @returns {string[]}- */-function validateMainVersions({- fixed,- releasedVersion,- activeCutVersion = null,- pendingMergeBackVersion = null,- baseManifests = new Map(),- headManifests,-}) {- const errors = [];- if (!VERSION_RE.test(releasedVersion ?? ''))- errors.push('main version check needs the newest stable vX.Y.Z tag');- const headVersions = new Set();- const baseVersions = new Set();- for (const name of fixed) {- const base = baseManifests.get(name);- if (- base &&- isStableReleasePackage(base) &&- VERSION_RE.test(base.version ?? '')- )- baseVersions.add(base.version);- const head = headManifests.get(name);- if (!head || !isStableReleasePackage(head)) continue;- if (!VERSION_RE.test(head.version ?? '')) {- errors.push(`${name} is ${head.version}; main declares an X.Y.Z version`);- continue;- }- headVersions.add(head.version);- }- if (headVersions.size !== 1) {- errors.push(- `the fixed group must declare one version on main; found ${[...headVersions].sort().join(', ') || 'none'}`,- );- return errors;- }- const [declaredVersion] = headVersions;- const order = VERSION_RE.test(releasedVersion ?? '')- ? compareVersions(declaredVersion, releasedVersion)- : null;- const publishedEqualityIsPending =- order === 0 && pendingMergeBackVersion === releasedVersion;- if (- order === null ||- order < 0 ||- (order === 0 && !publishedEqualityIsPending)- )- errors.push(- `main declares ${declaredVersion}; it must stay strictly above newest stable v${releasedVersion}`,- );- if (- activeCutVersion !== null &&- compareVersions(declaredVersion, activeCutVersion) < 0- )- errors.push(- `main declares ${declaredVersion}; it must not fall below active cut v${activeCutVersion}`,- );- if (- order > 0 &&- baseVersions.size === 1 &&- [...baseVersions][0] === releasedVersion &&- nextPlannedVersion(releasedVersion, declaredVersion) === null- )- errors.push(- `main's first plan after v${releasedVersion} must be patch successor ${patchSuccessor(releasedVersion)} by default or owner-named minor ${minorSuccessor(releasedVersion)}; found ${declaredVersion}`,- );- const fixedNames = new Set(fixed);- for (const manifest of headManifests.values()) {- if (!manifest) continue;- for (const field of VERSION_DEPENDENCY_FIELDS) {- for (const [name, spec] of Object.entries(manifest[field] ?? {})) {- if (- fixedNames.has(name) &&- EXACT_SPEC_RE.test(spec) &&- spec !== declaredVersion- )- errors.push(- `${manifest.name} ${field}.${name} pins ${spec}; main declares ${declaredVersion}`,- );- }- }- }- return errors;-}-function canaryEligibility({fixed, releasedVersion, manifests}) {const versions = new Set([...manifests.values()]@@ -1251,72 +1120,6 @@ async function main() {);return;}- if (command === 'validate-main-version') {- const base = required(values, 'base');- const config = jsonAtRef(root, base, '.changeset/config.json');- if (!config)- throw new Error(`cannot read trusted fixed group from ${base}`);- const releasedVersion = latestStableVersion(root);- const activeBranches = listActiveBranches(root);- const activeCutVersion =- activeBranches.length === 1- ? markerAtRef(root, `origin/${activeBranches[0]}`).version- : null;- let pendingMergeBack = null;- if (- releasedVersion &&- activeBranches.length === 1 &&- activeCutVersion === releasedVersion- ) {- const releaseTag = `v${releasedVersion}`;- const branch = activeBranches[0];- const marker = markerAtRef(root, releaseTag);- const plan = JSON.parse(- git(root, ['show', `${releaseTag}:${RELEASE_DIR}/${PLAN_FILE}`]),- );- pendingMergeBack = pendingMergeBackVersion({- releasedVersion,- activeBranches,- marker,- plan,- releaseHead: git(root, ['rev-parse', releaseTag]),- branchHead: git(root, ['rev-parse', `origin/${branch}`]),- baseChangesets: changesetMapAtRef(root, base),- });- }- const errors = [];- if (activeBranches.length > 1)- errors.push(- `main version check requires at most one active cut; found ${activeBranches.join(', ')}`,- );- errors.push(- ...validateMainVersions({- fixed: (config.fixed ?? []).flat(),- releasedVersion,- activeCutVersion,- pendingMergeBackVersion: pendingMergeBack,- baseManifests: packageManifestsByName(- file => jsonAtRef(root, base, file),- root,- ),- headManifests: packageManifestsByName(file => {- const absolute = path.join(root, file);- return fs.existsSync(absolute) ? readJson(absolute) : null;- }, root),- }),- );- if (errors.length) throw new Error(errors.join('\n'));- console.log(- JSON.stringify({- base,- releasedVersion,- activeCutVersion,- pendingMergeBackVersion: pendingMergeBack,- valid: true,- }),- );- return;- }if (command === 'validate-merge-back') {const base = required(values, 'base');const releaseRef = required(values, 'release-ref');@@ -1427,7 +1230,7 @@ async function main() {}if (command !== 'validate')throw new Error(- 'command must be create, refresh, list-active, inspect-ref, validate-diff, next-plan-version, canary-eligibility, validate-main-version, validate-merge-back, or validate',+ 'command must be create, refresh, list-active, inspect-ref, validate-diff, next-plan-version, canary-eligibility, validate-merge-back, or validate',);const marker = readJson(path.join(root, RELEASE_DIR, MARKER_FILE));@@ -1486,12 +1289,10 @@ export {computePlanDigest,declaredVersionAtRef,nextPlannedVersion,- pendingMergeBackVersion,isStableReleasePackage,latestStableVersion,listActiveBranches,validateIdentity,- validateMainVersions,validateRefMarker,validateReleaseDiff,validateReleaseState,diff --git a/scripts/release/active-release.test.mjs b/scripts/release/active-release.test.mjsindex 0df9d0c2d5..1123a3e458 100644--- a/scripts/release/active-release.test.mjs+++ b/scripts/release/active-release.test.mjs@@ -20,8 +20,6 @@ import {declaredVersionAtRef,latestStableVersion,nextPlannedVersion,- pendingMergeBackVersion,- validateMainVersions,validateReleaseDiff,validateReleaseMergeBack,validateReleaseState,@@ -769,146 +767,3 @@ describe('newest stable release selection', () => {expect(latestStableVersion(root)).toBe('0.6.7');});});--describe('main pull requests keep the declared version above newest stable (FR46)', () => {- const fixed = ['@astryxdesign/core', '@astryxdesign/cli'];- const at = (core, cli = core) =>- new Map([- ['@astryxdesign/core', {name: '@astryxdesign/core', version: core}],- ['@astryxdesign/cli', {name: '@astryxdesign/cli', version: cli}],- ]);- // `base` is passed deliberately as a red arm: a check that compares against- // previous main would reject the first case instead of comparing with v0.6.7.- const check = (- base,- head,- releasedVersion = '0.6.7',- activeCutVersion = null,- pendingMergeBack = null,- ) =>- validateMainVersions({- fixed,- releasedVersion,- activeCutVersion,- pendingMergeBackVersion: pendingMergeBack,- baseManifests: base,- headManifests: head,- });-- it('accepts a planned-version decrease that stays above newest stable', () => {- expect(check(at('0.7.0'), at('0.6.8'))).toEqual([]);- expect(check(at('0.6.8'), at('0.7.0'))).toEqual([]);- });-- it('allows equality with an untagged active cut but refuses lowering below it', () => {- expect(check(at('0.6.8'), at('0.6.8'), '0.6.7', '0.6.8')).toEqual([]);- expect(check(at('0.6.8'), at('0.6.9'), '0.6.7', '0.6.8')).toEqual([]);- expect(check(at('0.6.8'), at('0.6.7'), '0.6.6', '0.6.8')).toContain(- 'main declares 0.6.7; it must not fall below active cut v0.6.8',- );- expect(check(at('0.6.8'), at('0.6.8'), '0.6.8', '0.6.8')).toContain(- 'main declares 0.6.8; it must stay strictly above newest stable v0.6.8',- );- });-- it('allows published equality only while the exact frozen merge-back is pending', () => {- expect(check(at('0.6.8'), at('0.6.8'), '0.6.8', '0.6.8', '0.6.8')).toEqual(- [],- );- expect(check(at('0.6.8'), at('0.6.8'), '0.6.8', '0.6.8')).toContain(- 'main declares 0.6.8; it must stay strictly above newest stable v0.6.8',- );- expect(- check(at('0.6.8'), at('0.6.8'), '0.6.8', '0.6.8', '0.6.7'),- ).toContain(- 'main declares 0.6.8; it must stay strictly above newest stable v0.6.8',- );- });-- it('proves the pending window from exact authority and every frozen Changeset', () => {- const plan = {- schemaVersion: 2,- version: '0.6.8',- branch: 'release/v0.6.8',- cutSha: 'a'.repeat(40),- changesets: [- {- path: '.changeset/frozen.md',- sha256: 'b'.repeat(64),- packages: [{name: '@astryxdesign/core', bump: 'patch'}],- category: 'fix',- headline: 'Fix it',- contributors: ['person'],- body: '',- },- ],- };- const marker = buildMarker(plan);- const input = {- releasedVersion: '0.6.8',- activeBranches: ['release/v0.6.8'],- marker,- plan,- releaseHead: 'c'.repeat(40),- branchHead: 'c'.repeat(40),- baseChangesets: new Map([['.changeset/frozen.md', 'b'.repeat(64)]]),- };- expect(pendingMergeBackVersion(input)).toBe('0.6.8');- expect(- pendingMergeBackVersion({...input, baseChangesets: new Map()}),- ).toBeNull();- expect(- pendingMergeBackVersion({...input, branchHead: 'd'.repeat(40)}),- ).toBeNull();- });-- it('admits only patch or minor successor as the first plan after merge-back', () => {- expect(check(at('0.6.7'), at('0.6.8'))).toEqual([]);- expect(check(at('0.6.7'), at('0.7.0'))).toEqual([]);- expect(check(at('0.6.7'), at('0.6.9'))).toContain(- "main's first plan after v0.6.7 must be patch successor 0.6.8 by default or owner-named minor 0.7.0; found 0.6.9",- );- });-- it('requires every exact internal pin to follow the separate next plan', () => {- const head = at('0.6.8');- head.set('@astryxdesign/lab', {- name: '@astryxdesign/lab',- version: '0.1.9',- private: true,- peerDependencies: {'@astryxdesign/core': '0.6.7'},- });- expect(check(at('0.6.7'), head)).toContain(- '@astryxdesign/lab peerDependencies.@astryxdesign/core pins 0.6.7; main declares 0.6.8',- );- });-- it('refuses equality, a lower version, a split group, and a prerelease', () => {- expect(check(at('0.7.0'), at('0.6.7'))).toContain(- 'main declares 0.6.7; it must stay strictly above newest stable v0.6.7',- );- expect(check(at('0.7.0'), at('0.6.6'))).toContain(- 'main declares 0.6.6; it must stay strictly above newest stable v0.6.7',- );- expect(check(at('0.6.8'), at('0.7.0', '0.6.8'))).toContain(- 'the fixed group must declare one version on main; found 0.6.8, 0.7.0',- );- expect(check(at('0.6.8'), at('0.7.0-canary.abc'))[0]).toMatch(- /main declares an X\.Y\.Z version/,- );- expect(check(at('0.6.8'), at('0.7.0'), null)).toContain(- 'main version check needs the newest stable vX.Y.Z tag',- );- });-- it('accepts a package new to main', () => {- expect(- check(- new Map([- ['@astryxdesign/core', at('0.7.0').get('@astryxdesign/core')],- ]),- at('0.7.0'),- ),- ).toEqual([]);- });-});