Skip to content

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.mjs
index 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.yml
index 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 contract
if: github.event_name == 'pull_request'
id: release-merge-back-scope
@@ -69,24 +69,6 @@ jobs:
esac
echo "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 lint
if: github.event_name == 'pull_request' && steps.release-merge-back-scope.outputs.required == 'true'
env:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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 declares
the next minor. `[experimental]` and every other category declare `patch`.
diff --git a/docs/release.md b/docs/release.md
index 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 provena
exact internal pins, and lockfile. The released version's patch successor is the
default. 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 codemods
diff --git a/docs/specs/AST-017/spec.md b/docs/specs/AST-017/spec.md
index 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's
version is the fixed-group version declared at its cut commit. Admission, the
release 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 w
freeze documentation organization rather than protect the command and schema
contracts 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 runtime
diff --git a/docs/specs/AST-030/spec.md b/docs/specs/AST-030/spec.md
index 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 existing
jobs or join jobs. A specialized lane skips owned steps inside those jobs; it
does 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 the
diff --git a/scripts/release/active-release.mjs b/scripts/release/active-release.mjs
index 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.mjs
index 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([]);
- });
-});