An open source design system that's fully customizable and agent ready
TypeScript
ci: visual, accessibility and RTL run on main, not on pull request updates (#8877)
Cindy Zhang14fc58723028
diff --git a/.github/scripts/ci-heavy-lanes.test.mjs b/.github/scripts/ci-heavy-lanes.test.mjsnew file mode 100644index 0000000000..ea706a43a5--- /dev/null+++ b/.github/scripts/ci-heavy-lanes.test.mjs@@ -0,0 +1,141 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Visual, accessibility and RTL run on main, not on pull request updates.+ * @input CI, Main and Main heavy lanes workflows, and a mocked GitHub API+ * @output Routing for the heavy owners, the required joins, and Main's+ * release-check dispatch+ * @position Node contracts for AST-030 FR12 and DEC-7+ */++import fs from 'node:fs';+import {describe, expect, it} from 'vitest';+import yaml from 'yaml';++const read = name =>+ yaml.parse(+ fs.readFileSync(new URL(`../workflows/${name}`, import.meta.url), 'utf8'),+ );+const ci = read('ci.yml');+const heavy = read('main-heavy-lanes.yml');+const main = read('deploy.yml');++const LABEL = 'ci:heavy-lanes';+const HEAVY = [+ 'pr-a11y-guards',+ 'pr-a11y-specs',+ 'pr-a11y',+ 'visual-scout',+ 'pr-visual',+ 'pr-rtl-shard',+ 'pr-rtl-merge',+ 'pr-rtl',+];+const PR_CLAUSE = `(github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, '${LABEL}'))`;++describe('visual, accessibility and RTL owners', () => {+ // release-check-workflow.test.mjs evaluates them for release-check and+ // visual-maintenance-workflow.test.mjs for labelled and unlabelled pull+ // requests; this pins the shape on every owner.+ it.each(HEAVY)(+ '%s runs on a pull request only with the ci:heavy-lanes label',+ name => {+ const condition = ci.jobs[name].if;+ expect(condition).toContain(PR_CLAUSE);+ expect(condition.replaceAll(PR_CLAUSE, '')).not.toContain(+ "'pull_request'",+ );+ },+ );++ it('leaves the required joins without a heavy owner, so they still report on every pull request', () => {+ for (const join of ['test', 'build', 'docsite-test']) {+ const needs = [ci.jobs[join].needs].flat();+ for (const owner of HEAVY)+ expect(needs, `${join} needs ${owner}`).not.toContain(owner);+ }+ });++ it('adds no trigger: a label takes effect on the next push or reopen', () => {+ expect(ci.on.pull_request.types).toBeUndefined();+ });+});++describe('the release-check on every push to main', () => {+ const job = heavy.jobs.dispatch;+ const script = job.steps[0].with.script;++ it('runs on a push to main and may dispatch workflows', () => {+ expect(heavy.on).toEqual({push: {branches: ['main']}});+ expect(job.permissions).toEqual({actions: 'write', contents: 'read'});+ expect(job.steps[0].env.SHA).toBe('${{ github.sha }}');+ });++ it('throttles in ci.yml: the dispatched checks share one group that never cancels a running check', () => {+ // GitHub keeps one running and one pending run per group, and a newer+ // dispatch replaces the pending one, so a burst of merges is checked once.+ expect(ci.concurrency.group).toContain(+ "(github.event_name == 'workflow_dispatch' && github.triggering_actor == 'github-actions[bot]' && 'main-heavy-lanes')",+ );+ expect(ci.concurrency['cancel-in-progress']).toBe(+ "${{ github.event_name != 'workflow_dispatch' }}",+ );+ expect(heavy.concurrency).toBeUndefined();+ });++ it("leaves Main's fast checks running for every push", () => {+ expect(Object.keys(main.jobs)).not.toContain('release-check');+ expect(JSON.stringify(main)).not.toContain('createWorkflowDispatch');+ });++ /** Runs the step's script against a fake GitHub API with main at `tip`. */+ async function run(tip) {+ const calls = {dispatch: [], notices: []};+ const github = {+ rest: {+ repos: {getBranch: async () => ({data: {commit: {sha: tip}}})},+ actions: {+ createWorkflowDispatch: async args => calls.dispatch.push(args),+ },+ },+ };+ const body = new Function(+ 'github',+ 'context',+ 'core',+ 'process',+ `return (async () => {${script}})();`,+ );+ await body(+ github,+ {repo: {owner: 'meta', repo: 'astryx'}},+ {notice: m => calls.notices.push(m)},+ {env: {SHA: sha}},+ );+ return calls;+ }++ const sha = 'a'.repeat(40);++ it('dispatches release-check on main for the exact pushed commit', async () => {+ expect((await run(sha)).dispatch).toEqual([+ {+ owner: 'meta',+ repo: 'astryx',+ workflow_id: 'ci.yml',+ ref: 'main',+ inputs: {+ operation: 'release-check',+ 'release-branch': 'main',+ 'expected-head': sha,+ },+ },+ ]);+ });++ it('leaves a commit main has moved past to the newer push', async () => {+ const calls = await run('b'.repeat(40));+ expect(calls.dispatch).toEqual([]);+ expect(calls.notices[0]).toMatch(/newer push/);+ });+});diff --git a/.github/scripts/generate-pr-comment.js b/.github/scripts/generate-pr-comment.jsindex a5b87c81c4..c90dc19a78 100644--- a/.github/scripts/generate-pr-comment.js+++ b/.github/scripts/generate-pr-comment.js@@ -38,7 +38,7 @@ let analysis = {componentStats: {},totalBundle: {},};-let a11yReport = {components: {}};+let a11yReport = null; // stays null when the audit did not runtry {analysis = JSON.parse(fs.readFileSync(analysisFile, 'utf8'));} catch (e) {diff --git a/.github/scripts/lib/a11y-format.js b/.github/scripts/lib/a11y-format.jsindex 55cfa3882f..bd2b189c52 100644--- a/.github/scripts/lib/a11y-format.js+++ b/.github/scripts/lib/a11y-format.js@@ -44,6 +44,11 @@ function formatWcagTags(tags) {*/function buildA11ySection(a11yReport, storiesAuditedByComponent) {let a11ySection = '### Accessibility Audit\n\n';+ // No report: the audit did not run (pull requests run it only with the+ // `ci:heavy-lanes` label, spec:AST-030 FR12). Never claim a clean result.+ if (!a11yReport) {+ return a11ySection + '**Status:** The accessibility audit did not run on this pull request. It runs after merges to `main` and before each release; pull requests that touch components run it with the `ci:heavy-lanes` label.\n\n';+ }const totalViolations = Object.values(a11yReport.components || {}).reduce((sum, comp) => sum + (comp.violations?.length || 0), 0);diff --git a/.github/scripts/lib/a11y-format.test.mjs b/.github/scripts/lib/a11y-format.test.mjsindex a0acaa4e7f..a2ee2983fd 100644--- a/.github/scripts/lib/a11y-format.test.mjs+++ b/.github/scripts/lib/a11y-format.test.mjs@@ -14,6 +14,10 @@ describe('buildA11ySection', () => {expect(buildA11ySection({components: {}})).toContain('No accessibility violations detected');});+ it('says the audit did not run when there is no report', () => {+ expect(buildA11ySection(null)).toContain('did not run on this pull request');+ });+it('lists a violation with its rule, story count, and help link', () => {const section = buildA11ySection(report([diff --git a/.github/scripts/lib/pr-preview.mjs b/.github/scripts/lib/pr-preview.mjsindex edaca230c3..5cda0584b8 100644--- a/.github/scripts/lib/pr-preview.mjs+++ b/.github/scripts/lib/pr-preview.mjs@@ -558,14 +558,6 @@ export async function reconcilePrComment({let body;if (analysisReady) {- let resolvedA11yPath = a11yPath;- if (!fs.existsSync(resolvedA11yPath)) {- resolvedA11yPath = path.resolve('a11y-empty.json');- fs.writeFileSync(- resolvedA11yPath,- '{"components":{},"summary":{"componentsAudited":0,"totalViolations":0}}',- );- }const args = [generator,'--analysis',@@ -573,8 +565,9 @@ export async function reconcilePrComment({...(trustedBaseStats({baseStatsPath, identity, core})? ['--base-stats', baseStatsPath]: []),- '--a11y',- resolvedA11yPath,+ // No report means the audit did not run (it runs on main and release+ // checks, or with the ci:heavy-lanes label); the comment says so.+ ...(fs.existsSync(a11yPath) ? ['--a11y', a11yPath] : []),...(fs.existsSync(visualPath) ? ['--visual', visualPath] : []),...(storybook ? ['--storybook-url', `${previewOrigin}/storybook/`] : []),...(sandbox ? ['--sandbox-url', `${previewOrigin}/sandbox/`] : []),diff --git a/.github/scripts/lib/pr-preview.test.mjs b/.github/scripts/lib/pr-preview.test.mjsindex 51baf296d9..9104e2eaf6 100644--- a/.github/scripts/lib/pr-preview.test.mjs+++ b/.github/scripts/lib/pr-preview.test.mjs@@ -159,7 +159,7 @@ function githubFixture({value = identity(), comments = []} = {}) {return {github, state};}-function fixture(value = identity(), {analysis = true} = {}) {+function fixture(value = identity(), {analysis = true, a11y = true} = {}) {const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pr-preview-'));roots.push(root);const paths = {@@ -192,10 +192,12 @@ function fixture(value = identity(), {analysis = true} = {}) {}),);}- fs.writeFileSync(- paths.a11y,- '{"components":{},"summary":{"componentsAudited":0,"totalViolations":0}}',- );+ if (a11y) {+ fs.writeFileSync(+ paths.a11y,+ '{"components":{},"summary":{"componentsAudited":0,"totalViolations":0}}',+ );+ }return paths;}@@ -203,6 +205,7 @@ async function reconcile({value = identity(),previewAvailable = false,analysis = true,+ a11y = true,comments = [],githubFixtureValue = value,createIfMissing,@@ -210,7 +213,7 @@ async function reconcile({execute,baseStats,} = {}) {- const paths = fixture(value, {analysis});+ const paths = fixture(value, {analysis, a11y});const baseStatsPath = path.join(path.dirname(paths.analysis),'size-base.json',@@ -826,6 +829,12 @@ describe('PR comment preview reconciliation', () => {expect(result.body).not.toContain('facebook.github.io/astryx/pr/');});+ it('says the accessibility audit did not run when there is no report', async () => {+ const {result} = await reconcile({a11y: false});+ expect(result.body).toContain('did not run on this pull request');+ expect(result.body).not.toContain('No accessibility violations detected');+ });+it('keeps current trustworthy analysis when source CI fails', async () => {const value = identity({sourceConclusion: 'failure'});const {result} = await reconcile({value});diff --git a/.github/scripts/release-check-workflow.test.mjs b/.github/scripts/release-check-workflow.test.mjsindex ae6e965ad9..e918984dd8 100644--- a/.github/scripts/release-check-workflow.test.mjs+++ b/.github/scripts/release-check-workflow.test.mjs@@ -74,11 +74,17 @@ function runs(branch = releaseBranch,needs = dependencies(job),cancelled = false,+ labels = [],} = {},) {const expression = (job.if ?? 'true').replace(/^\$\{\{\s*|\s*\}\}$/g, '')- .replace(/needs\.([a-z][a-z0-9-]*)/g, 'needs["$1"]');+ .replace(/needs\.([a-z][a-z0-9-]*)/g, 'needs["$1"]')+ // GitHub's object filter: `labels.*.name` lists the labels' names.+ .replace(+ /contains\(github\.event\.pull_request\.labels\.\*\.name, '([^']+)'\)/g,+ "(github.event.pull_request?.labels ?? []).some(label => label.name === '$1')",+ );// GitHub injects success() unless the expression has a status function.if (!/\b(always|cancelled|success|failure)\(/.test(expression) &&@@ -93,7 +99,10 @@ function runs('cancelled',`return Boolean(${expression});`,)(- {event_name: event},+ {+ event_name: event,+ event: {pull_request: {labels: labels.map(name => ({name}))}},+ },{operation, 'release-branch': branch},needs,() => true,diff --git a/.github/scripts/visual-gate/README.md b/.github/scripts/visual-gate/README.mdindex 592cb4a68b..7a192fb0eb 100644--- a/.github/scripts/visual-gate/README.md+++ b/.github/scripts/visual-gate/README.md@@ -1,7 +1,10 @@# Storybook visual regressionEvery visual-regression test uses the shared Storybook framework and-`.github/workflows/ci.yml` → `pr-visual` (**Stable visual regression**).+`.github/workflows/ci.yml` → `pr-visual` (**Stable visual regression**). It runs+in `release-check`, which `main-heavy-lanes.yml` dispatches after merges to+`main` (a burst is checked once, at its newest commit) and the release gate dispatches before a cut; a pull request runs it only+with the `ci:heavy-lanes` label (AST-030 FR12, DEC-7).[AST-030 FR12](../../../docs/specs/AST-030/spec.md) owns this requirement.Add coverage to that owner, not to a new component, package, theme, scheduled,post-CI, or post-merge workflow.@@ -24,8 +27,7 @@ cancelled, and skipped work is not release evidence.This changes when and where release evidence runs, not finding policy: visual`changed` still requires review, a11y fails on new baseline violations, and RTLfindings remain soft while report completeness is mandatory. The dispatch does-not capture baseline candidates, promote baselines, publish previews, or replace-PR checks. It runs only on request, not every push. `visual-release-report` holds+not capture baseline candidates, promote baselines, or publish previews. `visual-release-report` holdsthe visual evidence for that exact run/attempt.PR accessibility is intentionally smaller: explicit changed-component axe scopediff --git a/.github/scripts/visual-maintenance-workflow.test.mjs b/.github/scripts/visual-maintenance-workflow.test.mjsindex 9f874b287a..00c9fc16ef 100644--- a/.github/scripts/visual-maintenance-workflow.test.mjs+++ b/.github/scripts/visual-maintenance-workflow.test.mjs@@ -31,11 +31,17 @@ function runs(operation = 'capture',needs = {},cancelled = false,+ labels = [],} = {},) {const expression = (job.if ?? 'true').replace(/^\$\{\{\s*|\s*\}\}$/g, '')- .replace(/needs\.([a-z][a-z0-9-]*)/g, 'needs["$1"]');+ .replace(/needs\.([a-z][a-z0-9-]*)/g, 'needs["$1"]')+ // GitHub's object filter: `labels.*.name` lists the labels' names.+ .replace(+ /contains\(github\.event\.pull_request\.labels\.\*\.name, '([^']+)'\)/g,+ "(github.event.pull_request?.labels ?? []).some(label => label.name === '$1')",+ );if (!/\b(always|cancelled|success|failure)\(/.test(expression)) {if (cancelled ||@@ -51,7 +57,10 @@ function runs('cancelled',`return Boolean(${expression});`,)(- {event_name: event},+ {+ event_name: event,+ event: {pull_request: {labels: labels.map(name => ({name}))}},+ },{operation},needs,() => true,@@ -106,15 +115,18 @@ describe('CI baseline maintenance routing', () => {expect(runs(visual, {needs})).toBe(false);});- it('preserves focused PR routing when the maintenance guard is skipped', () => {+ it('preserves focused PR routing on an opted-in pull request when the maintenance guard is skipped', () => {const needs = dependencies(visual);needs['maintenance-request'].result = 'skipped';- expect(runs(visual, {event: 'pull_request', needs})).toBe(true);- needs['check-components'].outputs.has_stable_visual = 'false';+ const optedIn = {event: 'pull_request', needs, labels: ['ci:heavy-lanes']};+ expect(runs(visual, optedIn)).toBe(true);+ // Without the opt-in label a pull request update runs no visual owner.expect(runs(visual, {event: 'pull_request', needs})).toBe(false);+ needs['check-components'].outputs.has_stable_visual = 'false';+ expect(runs(visual, optedIn)).toBe(false);needs['check-components'].outputs.has_stable_visual = 'true';needs['build-storybook'].result = 'failure';- expect(runs(visual, {event: 'pull_request', needs})).toBe(false);+ expect(runs(visual, optedIn)).toBe(false);expect(runs(visual, {event: 'merge_group', needs})).toBe(false);});diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex ef868ed8e2..00d9723e0a 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -46,11 +46,20 @@ permissions: {}# `ci-duration` reports each job's run time and the run's span. Split a job# that nears the limit (shard, scope, cache); do not raise it.#+# Visual, accessibility and RTL owners (pr-a11y*, visual-scout, pr-visual,+# pr-rtl*) do not run on pull request updates: they run for release-check,+# which the Main heavy lanes workflow (main-heavy-lanes.yml) dispatches on every+# push to main and the release gate dispatches before a cut, and on a pull request labelled `ci:heavy-lanes` (add the label,+# then push or close and reopen). A main failure is fixed forward+# (spec:AST-030 FR12, DEC-7).+## One group per pull request (a fork's branch name can repeat across forks),# so a new push cancels the superseded run. Merge-queue entries and dispatches-# get their own groups and are never cancelled by a pull request.+# get their own groups and are never cancelled by a pull request. The+# release-checks main-heavy-lanes.yml dispatches (as github-actions[bot]) share+# one group: one runs, the newest waits, and a running check is never cancelled.concurrency:- group: 'ci-${{ github.event.pull_request.number || github.event.merge_group.head_sha || github.run_id }}'+ group: "ci-${{ github.event.pull_request.number || github.event.merge_group.head_sha || (github.event_name == 'workflow_dispatch' && github.triggering_actor == 'github-actions[bot]' && 'main-heavy-lanes') || github.run_id }}"cancel-in-progress: ${{ github.event_name != 'workflow_dispatch' }}jobs:@@ -1533,7 +1542,7 @@ jobs:pr-a11y-guards:name: pr-a11y (audit and guards)needs: [build-storybook, check-components]- if: (github.event_name == 'pull_request' || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) && needs.check-components.outputs.has_components == 'true'+ if: ((github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:heavy-lanes')) || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) && needs.check-components.outputs.has_components == 'true'runs-on: 2-core-ubuntu-armtimeout-minutes: ${{ github.event_name == 'workflow_dispatch' && 360 || 15 }}permissions:@@ -1640,7 +1649,7 @@ jobs:pr-a11y-specs:name: pr-a11y (browser specs)needs: [build-storybook, check-components]- if: (github.event_name == 'pull_request' || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) && needs.check-components.outputs.has_components == 'true'+ if: ((github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:heavy-lanes')) || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) && needs.check-components.outputs.has_components == 'true'runs-on: 2-core-ubuntu-armtimeout-minutes: ${{ github.event_name == 'workflow_dispatch' && 360 || 15 }}permissions:@@ -1709,7 +1718,7 @@ jobs:# Stable required context joining the scoped audit/guards and browser specs.pr-a11y:needs: [check-components, pr-a11y-guards, pr-a11y-specs]- if: ${{ always() && (github.event_name == 'pull_request' || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) && needs.check-components.outputs.has_components == 'true' }}+ if: ${{ always() && ((github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:heavy-lanes')) || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) && needs.check-components.outputs.has_components == 'true' }}runs-on: ubuntu-slimtimeout-minutes: 5permissions:@@ -2071,7 +2080,7 @@ jobs:!cancelled() &&needs.build-storybook.result == 'success' &&needs.check-components.result == 'success' &&- ((github.event_name == 'pull_request' &&+ (((github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:heavy-lanes')) &&needs.check-components.outputs.has_stable_visual == 'true' &&needs.check-components.outputs.broad_stable_visual == 'true') ||(github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))@@ -2142,7 +2151,7 @@ jobs:[build-storybook, check-components, maintenance-request, visual-scout]if: >-!cancelled() &&- ((github.event_name == 'pull_request' &&+ (((github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:heavy-lanes')) &&needs.build-storybook.result == 'success' &&needs.check-components.result == 'success' &&needs.check-components.outputs.has_stable_visual == 'true') ||@@ -2420,7 +2429,7 @@ jobs:name: pr-rtl (${{ matrix.package }}${{ matrix.parts > 1 && format(' {0}/{1}', matrix.part, matrix.parts) || '' }})needs: [build-storybook, check-components]if: >-- (github.event_name == 'pull_request' ||+ ((github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:heavy-lanes')) ||(github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) &&(needs.check-components.outputs.has_rtl_components == 'true' ||needs.check-components.outputs.has_rtl_harness == 'true' ||@@ -2604,7 +2613,7 @@ jobs:needs: [build-storybook, check-components, pr-rtl-shard]if: >-always() && !cancelled() &&- (github.event_name == 'pull_request' ||+ ((github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:heavy-lanes')) ||(github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) &&(needs.check-components.outputs.has_rtl_components == 'true' ||needs.check-components.outputs.has_rtl_harness == 'true' ||@@ -2692,7 +2701,7 @@ jobs:# Stable required context joining the five package shards above.pr-rtl:needs: [check-scope, check-components, pr-rtl-shard, pr-rtl-merge]- if: ${{ always() && !cancelled() && ((github.event_name == 'pull_request' && needs.check-scope.outputs.spec_only != 'true') || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) }}+ if: ${{ always() && !cancelled() && (((github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:heavy-lanes')) && needs.check-scope.outputs.spec_only != 'true') || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) }}runs-on: ubuntu-slimtimeout-minutes: 5steps:diff --git a/.github/workflows/main-heavy-lanes.yml b/.github/workflows/main-heavy-lanes.ymlnew file mode 100644index 0000000000..83460f3e61--- /dev/null+++ b/.github/workflows/main-heavy-lanes.yml@@ -0,0 +1,48 @@+# Copyright (c) Meta Platforms, Inc. and affiliates.++# Visual, accessibility and RTL run on main, not on every pull request update+# (spec:AST-030 FR12, DEC-7): a push to main dispatches ci.yml's canonical+# release-check on its exact commit; that run is main's visual/a11y/RTL result,+# and a failure is fixed forward. ci.yml runs one such check at a time and keeps+# only the newest waiting, so a burst of merges is checked once, at its newest+# commit. Main's own fast checks (deploy.yml) still run for every push. The+# release gate's exact-commit release-check before a cut is unchanged.+name: Main heavy lanes++on:+ push:+ branches: ['main']++permissions: {}++jobs:+ dispatch:+ runs-on: ubuntu-slim+ timeout-minutes: 5+ permissions:+ actions: write+ contents: read+ steps:+ - name: Dispatch the visual, accessibility and RTL release-check for this commit+ uses: actions/github-script@v9+ env:+ SHA: ${{ github.sha }}+ with:+ script: |+ const sha = process.env.SHA;+ const {data} = await github.rest.repos.getBranch({...context.repo, branch: 'main'});+ if (data.commit.sha !== sha) {+ core.notice(`main moved past ${sha.slice(0, 7)}; the newer push's check covers it.`);+ return;+ }+ // ci.yml queues these dispatches in one group (one running, one+ // waiting; a newer one replaces the waiting one). A merge landing+ // between the tip check above and this call makes the run check out+ // the newer commit and fail its exact-head check; the newer push's+ // own dispatch then checks that commit.+ await github.rest.actions.createWorkflowDispatch({+ ...context.repo,+ workflow_id: 'ci.yml',+ ref: 'main',+ inputs: {operation: 'release-check', 'release-branch': 'main', 'expected-head': sha},+ });diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 324c208e91..41529dd712 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -385,8 +385,9 @@ Two repo-side rules worth restating here:WAI-ARIA APG patterns and are tested once; a bespoke reimplementation ofone is a review reject.- CI is the enforcement layer, not a replacement for the checklist: the- `pr-a11y` job in `ci.yml` runs an axe audit on every PR that touches- components, a weekly workflow scans the full component surface, and the+ `pr-a11y` job in `ci.yml` runs an axe audit after merges to `main` and+ before each release (and on a pull request labelled `ci:heavy-lanes`), a+ weekly workflow scans the full component surface, and the`useAnnounce` lint rule rejects hand-wired `aria-live` regions. axe onlycatches static, DOM-level issues — keyboard behavior, focus management, andannouncement timing are exactly what the checklist and the component's unit@@ -531,7 +532,9 @@ any other value:// @pr-a11y release-only never on a PR; the release check runs it```-`pnpm test:a11y-contract:pr origin/main --dry-run` prints what a pull request+These routes apply when a pull request runs the accessibility owner, which it+does only with the `ci:heavy-lanes` label; `main` and release checks run every+spec. `pnpm test:a11y-contract:pr origin/main --dry-run` prints what a pull requestfrom your branch would run (component tokens need CI's `analysis.json`; withoutit the runner says so and leaves those specs out). A spec writes its receipts under`test-results/<name>/` or, for a component audit, a top-level@@ -544,8 +547,10 @@ component set, or has no audit spec has an entry in### Accessibility audits-PRs that touch components run an axe-core audit (the `pr-a11y` CI job) over-the Storybook stories of the changed components. The job **fails** when it+Merges to `main` (checked at the newest commit of a burst), every release+check, and a PR labelled `ci:heavy-lanes`+that touches components run an axe-core audit (the `pr-a11y` CI job); on a PR+it covers the Storybook stories of the changed components. The job **fails** when itfinds a violation that is not listed in the checked-in baseline,`.github/a11y-baseline.json`. Violations are keyed`Component::Story::rule-id`, so unrelated markup churn does not invalidate@@ -607,14 +612,14 @@ not copying its assertions — see the package README and### RTL audits-PRs that touch components also run an RTL audit (`pr-rtl`), scoped to the-changed components like `pr-a11y`. It is soft-gated — findings show in the job+The same events run an RTL audit (`pr-rtl`); on a labelled PR it is scoped to+the changed components like `pr-a11y`. It is soft-gated — findings show in the jobsummary but don't block. Repro locally with `pnpm rtl:audit -- --filter Avatar`(the `--` matters: `pnpm -F` is itself `--filter`). The report classifies everyscoped component as **measured**, **verified N-A**, or a **coverage gap**; anunexplained all-N-A result is not a clean RTL result. The weekly unfiltered run-applies the same contract to the full existing roster, while PR CI applies it-to new and changed components. See `apps/storybook/rtl-audit/README.md`.+applies the same contract to the full existing roster, while a labelled PR+applies it to new and changed components. See `apps/storybook/rtl-audit/README.md`.### Modal close visibility guarddiff --git a/apps/storybook/rtl-audit/README.md b/apps/storybook/rtl-audit/README.mdindex e486b1305a..342cd7d039 100644--- a/apps/storybook/rtl-audit/README.md+++ b/apps/storybook/rtl-audit/README.md@@ -18,7 +18,9 @@ auto-discovery layer runs with **zero curated selectors**. There are threeindependent auto passes: **D1 (icon-mirror)**, **D5 (positional-mirror)**, and**D6 (directional-decoration)**.-> **Scope in CI.** `pr-rtl` passes `--filter` with the components the PR+> **Scope in CI.** `pr-rtl` runs after merges to `main` and in release checks at+> full scope, and on a PR only with the `ci:heavy-lanes` label (spec:AST-030+> FR12). On a labelled PR it passes `--filter` with the components the PR> touched (from `analysis.json`), matching `pr-a11y`. Eligibility is classified> by the component policy and package registry loaded from the trusted base ref;> a missing policy, empty or unmatched path set, unresolved component list, or@@ -34,8 +36,10 @@ independent auto passes: **D1 (icon-mirror)**, **D5 (positional-mirror)**, and> policy requires full scope, every manifest must be runnable with an empty> filter and all five package reports must arrive. A planned scan ending in ERROR> is incomplete. Missing or malformed analysis/index/manifest input, a noncanonical owner, stale output, a missing or unexpected report, and-> an all-skipped required matrix all fail closed. An ordinary RTL-harness-only PR runs the fixed `Chart,ChartLegend` routing smoke-> scope so package discovery and curated aliases cannot skip their own check. The+> an all-skipped required matrix all fail closed. An RTL-harness-only PR labelled `ci:heavy-lanes` runs the fixed+> `Chart,ChartLegend` routing smoke scope so package discovery and curated aliases+> cannot skip their own check; without the label, `main`'s `release-check` covers+> the harness after merge (spec:AST-030 FR12). The> full unfiltered sweep also runs weekly in `.github/workflows/rtl-weekly.yml`.> Omit `--filter` to run it locally. The blocking accessibility audit consumes the> same package-qualified owner-to-story routes and fails if any selected owner@@ -263,7 +267,8 @@ without inventing a curated measurement.- **coverage gap**: every dimension returned N-A and no reason is recorded.Coverage gaps are findings. This rule applies to the existing full-library-weekly sweep and to every new or changed component in PR CI. A component with no+weekly sweep, to main and release checks, and to every new or changed component+in a labelled PR's CI. A component with nostory is also a gap when it is named by `--filter`; it cannot disappear from thereport merely because there was nothing to render.diff --git a/docs/architecture/rtl-audit-evidence.md b/docs/architecture/rtl-audit-evidence.mdindex b07fc72aef..49d5c84503 100644--- a/docs/architecture/rtl-audit-evidence.md+++ b/docs/architecture/rtl-audit-evidence.md@@ -150,9 +150,13 @@ Lint and rendered audit are complementary:discoverable icon, decoration, and positional relationships. Component-specificselectors are used only for semantics generic discovery cannot infer, such asorder, scroll direction, overlay side, or touch-target ownership.-- **INV7 — CI scope and weekly scope answer different questions.** PR CI checks- components affected by the change; it may run per package, but the PR result is- the join of every package scope and cannot pass with one scope missing. The+- **INV7 — CI scope and weekly scope answer different questions.** The RTL audit+ runs after merges to `main` (a burst of pushes is checked once, at its newest+ commit) and before each release, at full scope; a pull+ request runs it only with the `ci:heavy-lanes` label (spec:AST-030 FR12, DEC-7).+ When a pull request runs it, it checks components affected by the change; it+ may run per package, but the PR result is the join of every package scope and+ cannot pass with one scope missing. Thescheduled unfiltered audit checks the full live roster and shared regressions.Neither silently replaces the other.- **INV8 — Applicable evidence invalidates N/A.** A new applicable automatic ordiff --git a/docs/specs/AST-030/spec.md b/docs/specs/AST-030/spec.mdindex b42e50e577..55468621a9 100644--- a/docs/specs/AST-030/spec.md+++ b/docs/specs/AST-030/spec.md@@ -185,8 +185,13 @@ they are separately named.its exact event SHA. It MUST run the canonical `pr-visual` (**Stable visualregression**), `pr-a11y`, and `pr-rtl` owners with full scope: the closed stablevisual plan and unfiltered accessibility/RTL component rosters. Changed-file,- focused, smoke, and no-op paths MUST NOT narrow release checks. PR a11y MUST- remain scoped to changed components plus fast interaction guards; full a11y+ focused, smoke, and no-op paths MUST NOT narrow release checks. On a pull+ request, the visual (`visual-scout`, `pr-visual`), accessibility (`pr-a11y`+ with its guards and specs) and RTL (`pr-rtl` with its legs) owners MUST run+ only when the pull request carries the `ci:heavy-lanes` label at the event; a+ pull request update without it runs none of them, and no required context+ depends on them. An opted-in PR's a11y MUST remain scoped to changed components+ plus fast interaction guards; full a11ysweeps, whole-repository spec-test contracts, and their evidence uploads MUSTrun only for `release-check` in this workflow. Missing,failed, cancelled, or skipped required work MUST block the release-check join.@@ -198,7 +203,14 @@ they are separately named.later commits remain next-release input. A rewrite or divergence that removesthe checked SHA from current `main` history invalidates the receipt.This replaces constituent-PR-only release gating, not the canonical checks'- existing finding policies. Release checks MUST NOT run on every push, capture+ existing finding policies. A main-push workflow MUST dispatch that+ release-check for every push to `main`, bound to the pushed commit; the+ dispatched checks share one concurrency group that never cancels a running+ check: at most one runs and one waits, and a burst of pushes is checked once,+ at its newest commit. A commit `main` has already moved past leaves its check+ to the newer push. That release-check run is main's result, and a failure is+ fixed forward by an atomic pull request. Main's own fast+ checks still run for every push. Release checks MUST NOT capturebaseline candidates, publish baselines, or use a separate daily workflow orretroactive acceptance status.Deployment, accessibility, RTL, and vibe evidence MAY retain their workflows@@ -208,22 +220,25 @@ they are separately named.while preserving legitimate non-visual artifact use.- **FR13 — Broad CI on a pull request runs what the change reaches.** On a`pull_request` event whose trusted classification finds no shared- infrastructure, broad CI keeps every owner and required context and narrows- what those owners run. The Vitest test owner runs the tests whose module graph+ infrastructure, broad CI keeps every required context and every owner FR12+ routes to a pull request, and narrows what those owners run. The Vitest test owner runs the tests whose module graphreaches a changed file, against the merge commit's base parent, plus every testthat reads repository sources through the file system, directly or through amodule it imports; a computed `import()`, a child process, or a library thatreads sources for it (the TypeScript compiler, a bundler) counts as readingsources; and every test that loads a changed workspace package from its build,- by the package's name or a path into its `dist/`. The visual and RTL- owners audit one affected set of component folders: the changed components+ by the package's name or a path into its `dist/`. When a pull request runs+ them (FR12: only with the `ci:heavy-lanes` label), the visual and RTL owners+ audit one affected set of component folders: the changed componentsand their reverse dependents, the folders of the components, in any package,whose built bundle, `import()` targets included, reaches a changed module.Visual audits each dependent folder that has a stable story, and runs thewhole plan when the dependents exceed its focused budget or none has one; RTLaudits every component each of those folders implements. A Changeset renders nothing and widens no audit. A changed module that no component bundle holds adds none, and without- a readable build the audits run in full. PR accessibility stays scoped to- changed components (FR12). Shared infrastructure runs the full suite: root+ a readable build the audits run in full. PR accessibility, when it runs, stays+ scoped to changed components (FR12). Shared infrastructure runs the full suite of+ the owners the pull request runs (visual, accessibility and RTL only with the+ `ci:heavy-lanes` label, FR12): rootdependency manifests and lockfile, root configuration, a package's manifest,build or test configuration and test setup, `internal/` (the test harnessincluded), `theme-build` paths (tokens and themes), Storybook configuration,@@ -239,8 +254,10 @@ they are separately named.on the repository's supported Node and runner versions.- Unsupported behavior: incomplete or unavailable classification receives no fastpath and runs broad CI.-- Browser evidence: routing itself has no visual claim; browser checks remain- mandatory whenever their owning surface is present or scope is uncertain.+- Browser evidence: routing itself has no visual claim; the browser checks FR12+ routes to a pull request remain mandatory whenever their owning surface is+ present or scope is uncertain, and visual, accessibility and RTL run on `main`+ and release checks (FR12).## Current-state impact@@ -349,15 +366,17 @@ surface” exception.Run release evidence against an exact commit in current `main` history, not onlyconstituent PR heads. Use an explicit release-time dispatch in `ci.yml` so full-visual, accessibility, and RTL checks do not run on every main push. Reuse-existing test/build owners, keep their finding policies, and fail closed on-incomplete scope, missing work, or when the checked commit is no longer in-current `main` history. Baseline capture and the reviewed pull request that+visual, accessibility, and RTL checks do not run on every main push (DEC-7+supersedes this sentence: they run after merges to `main`). Reuse existing+test/build owners, keep their finding policies, and fail closed on incomplete+scope, missing work, or when the checked commit is no longer in current `main`+history.+Baseline capture and the reviewed pull request thatversions an accepted candidate remain separate operations.-PR accessibility remains a scoped, fast check: audit only explicitly resolved-changed component owners and retain the fast modal-close, theme-var, and story-play-browser guards. Never widen a PR to the exhaustive accessibility sweep because a+PR accessibility, when a pull request runs it (DEC-7), is a scoped, fast check:+audit only explicitly resolved changed component owners and retain the fast+modal-close, theme-var, and story-play browser guards. Never widen a PR to the exhaustive accessibility sweep because ashared path changed or the component set is empty. Missing or approximate analysisfails the scoped check rather than silently claiming no work. Multi-componentfolders expand only to their own canonical component owners or existing umbrella@@ -366,10 +385,35 @@ accessibility roster and the whole-repository spec-test contracts and theirevidence uploads run only on `release-check` in this workflow.The release path retains the complete suite and cannot substitute a scoped result.-Rejected: a separate workflow, per-push full audits, and treating a maintenance+Rejected: a separate workflow, per-push full audits (DEC-7 supersedes this for+pushes to `main`), and treating a maintenancecapture, skipped check, a checked SHA no longer in current `main` history, orretroactive status as release evidence.+### DEC-7 — Visual, accessibility and RTL run on main, not on pull request updates++**Reference:** `spec:AST-030/DEC-7`+**Decider:** `cixzhang`, `2026-10-28`++Run the visual, accessibility and RTL owners on every push to `main`, through+the same exact-commit `release-check` the release gate uses, and before a cut;+a pull request runs them only when it opts in with the `ci:heavy-lanes` label. Main-push checks are throttled: one runs at a time, a+burst of pushes collapses to its newest commit, and a running check is never+cancelled, so every check that starts finishes.+Pull request updates keep the fast checks and every required context; the+modal-close, theme-var and story-play guards are steps of the accessibility+owner, so they run with it, after merge or on a labelled pull request. A+failure on `main` is repaired forward with an atomic pull request, not reverted+first. This supersedes DEC-5's choice to keep these checks off main pushes:+running the browser suites on every update of every open pull request costs+far more than running them once per merge burst on `main`. The label opts a+pull request into the head-scoped owners FR13 describes; it adds no run of its+own, and the merged result is checked on `main`, so it is not+the label-triggered full run DEC-6 rejects.++Rejected: keeping the suites on every pull request update (spend); a separate+scheduled or daily owner (FR12 keeps one canonical workflow).+### DEC-6 — Pull requests run what the change reaches; full runs stay where landing is decided**Reference:** `spec:AST-030/DEC-6`@@ -379,7 +423,9 @@ A pull request's Vitest legs and browser audits follow what its change reaches:the module graph for tests and built-bundle reach for components. Tests thatread sources through the file system run whole, because no import reaches whatthey read. Shared infrastructure, uncertainty, `main`, merge-group entries and-release checks run everything, so no landing or release gate narrows.+release checks run everything, so no landing or release gate narrows; a pull+request runs the visual, accessibility and RTL owners only with the+`ci:heavy-lanes` label (DEC-7).Rejected: a full run triggered by approval, a label or a draft-to-ready change,which tests the pull request's head rather than the merged result.