An open source design system that's fully customizable and agent ready
TypeScript
ci: align spec approval with repository owners (#6320)
Cindy Zhang3d1d2989234f
diff --git a/.github/DESIGNOWNERS b/.github/DESIGNOWNERSindex c3deadc9e5..6eae010ad8 100644--- a/.github/DESIGNOWNERS+++ b/.github/DESIGNOWNERS@@ -1,8 +1,8 @@# Design owners for the Astryx repository# Design-team members. This list has three responsibilities:#-# - Current design specs and normative design assets may receive exact-head-# approval from any DESIGNOWNER, cixzhang, or imdreamrunner.+# - Current design and theme specs and normative design assets may receive+# exact-head approval from any DESIGNOWNER. ENGOWNERS may approve every spec.# - A DESIGNOWNER author may attest an exact PR head by marking the PR ready for# review. That evidence satisfies the design-approval group even in a mixed PR;# every other applicable code or spec-owner group remains required. Thediff --git a/.github/ENGOWNERS b/.github/ENGOWNERSindex 4af060e2b9..8f1b0724d6 100644--- a/.github/ENGOWNERS+++ b/.github/ENGOWNERS@@ -1,8 +1,10 @@# Engineering owners for the Astryx repository## This checked-in list defines engineering owners for spec-owner reconciliation.-# The review-signal workflows read the matching ENGOWNERS repository variable-# instead; keep that variable synchronized with this file when membership changes.+# Any ENGOWNER may approve every current knowledge-record kind on the exact pull+# request head. The review-signal workflows read the matching ENGOWNERS repository+# variable instead; keep that variable synchronized with this file when membership+# changes.## Distinct from CODEOWNERS on purpose: CODEOWNERS is the review-duty subset that# GitHub auto-requests as default reviewers on every PR; being here does NOT putdiff --git a/.github/REVIEW_GATE.md b/.github/REVIEW_GATE.mdindex 2b78afb564..5a56e27a8a 100644--- a/.github/REVIEW_GATE.md+++ b/.github/REVIEW_GATE.md@@ -24,11 +24,11 @@ neutral yellow "waiting" signal, not a red failure).Any PR that creates, changes, or archives a `current` architecture, component,family, design, or system spec waits on `spec-owner-approval` for its exact-current head. `cixzhang` or `imdreamrunner` can approve every record kind.-Current design records and normative design assets may also be approved by any-handle in `.github/DESIGNOWNERS`. Mixed PRs still require `cixzhang` or-`imdreamrunner` for non-design current records. Same-repository owner reviews-update the exact-head approval automatically. Fork review events cannot write+current head. Any handle in `.github/ENGOWNERS` can approve every record kind.+Current design and theme records and normative design assets may also be approved+by any handle in `.github/DESIGNOWNERS`. Mixed PRs still require an ENGOWNER for+non-design current records. Same-repository owner reviews update the exact-head+approval automatically. Fork review events cannot writewith their read-only token, so an approver uses an issue comment containing`/approve-spec <full-head-sha>` instead; that command runs from the trusteddefault branch and a new commit invalidates it.@@ -55,9 +55,8 @@ head **for the design-approval group only**. The attestation is published onlyfor a `.github/DESIGNOWNERS` handle, and it is read back only for a handle thatis still in that file — a marker left by someone since removed, or publishedbefore this rule existed, authorizes nothing. It satisfies no other group: the-spec and theme groups always need a real exact-head review or command from-someone in their own list. A spec or engineering owner cannot attest their own-head.+non-design and theme groups always need a real exact-head review or command from+someone in their own list. An engineering owner cannot attest their own head.The attestation does not grant auto-merge by itself. The existing gate may enablesquash auto-merge only when every changed path is a recognized spec record,@@ -82,11 +81,11 @@ CI and never gain this auto-merge path.## Sources of truth-| File | Meaning |-| ------------------------------- | ---------------------------------------------------------------- |-| `.github/ENGOWNERS` | Engineering team. Self-serve **code**. |-| `.github/DESIGNOWNERS` | Design team. Self-serve **design**. Checked first. |-| `.github/CODEOWNERS` (`*` line) | Who can **clear** the code gate (and native review requirement). |+| File | Meaning |+| ------------------------------- | --------------------------------------------------------------------------- |+| `.github/ENGOWNERS` | Engineering team. Self-serve **code** and approve every spec kind. |+| `.github/DESIGNOWNERS` | Design team. Self-serve **design** and approve visual specs. Checked first. |+| `.github/CODEOWNERS` (`*` line) | Who can **clear** the code gate (and native review requirement). |Author bucket is resolved in order: **design owner → eng owner → contributor.**A handle in `DESIGNOWNERS` is treated as a design owner even if also an engdiff --git a/.github/scripts/spec-owner-decision.test.mjs b/.github/scripts/spec-owner-decision.test.mjsindex e399c6374b..36607e5d6b 100644--- a/.github/scripts/spec-owner-decision.test.mjs+++ b/.github/scripts/spec-owner-decision.test.mjs@@ -506,8 +506,8 @@ describe('spec owner decision', () => {});const statuses = [marker('ernestt'), marker('imdreamrunner')];- // imdreamrunner is a spec owner and a design *approver*, but not a design- // owner. A marker they published — including one predating the rule that+ // imdreamrunner is an engineering owner and a design *approver*, but not a+ // design owner. A marker they published — including one predating the rule that// only design owners self-attest — is not evidence for any group.expect(parseReadyAttestations(statuses, {diff --git a/.github/scripts/spec-owner-reconcile.cjs b/.github/scripts/spec-owner-reconcile.cjsindex 83a139de94..da7b9a4365 100644--- a/.github/scripts/spec-owner-reconcile.cjs+++ b/.github/scripts/spec-owner-reconcile.cjs@@ -85,20 +85,13 @@ async function reconcileSpecOwnerGate({return;}- const specOwners = env.SPEC_OWNERS.split(',').map(ownerName =>- ownerName.toLowerCase(),- );const designOwners = parseOwnerFile(fs.readFileSync(path.join(workspace, '.github/DESIGNOWNERS'), 'utf8'),);const engineeringOwners = parseOwnerFile(fs.readFileSync(path.join(workspace, '.github/ENGOWNERS'), 'utf8'),);- const allOwners = new Set([- ...specOwners,- ...engineeringOwners,- ...designOwners,- ]);+ const allOwners = new Set([...engineeringOwners, ...designOwners]);if (!isAuthorizedEvent(context.eventName, context.payload, allOwners)) {core.info('Ignoring an event from someone outside the eligible owners.');return;@@ -439,8 +432,8 @@ async function reconcileSpecOwnerGate({const eventHead = context.payload.pull_request?.head?.sha;const eventTime = context.payload.pull_request?.updated_at;// Only a DESIGNOWNER author may self-attest a head, and only for the design- // approval group (.github/DESIGNOWNERS). A spec or engineering owner marking- // their own pull request ready is not an approval by anyone else.+ // approval group (.github/DESIGNOWNERS). An engineering owner marking their+ // own pull request ready is not an approval by anyone else.if (context.eventName === 'pull_request_target' &&context.payload.action === 'ready_for_review' &&@@ -541,17 +534,17 @@ async function reconcileSpecOwnerGate({});const ownerApprovalRequired =requiredGroups.spec || requiredGroups.design || requiredGroups.theme;- if (requiredGroups.design && designOwners.length === 0) {- throw new Error('No DESIGNOWNERS are configured.');+ if (requiredGroups.spec && engineeringOwners.length === 0) {+ throw new Error('No ENGOWNERS are configured.');}if (- requiredGroups.theme &&+ (requiredGroups.design || requiredGroups.theme) &&engineeringOwners.length === 0 &&designOwners.length === 0) {throw new Error('No ENGOWNERS or DESIGNOWNERS are configured.');}- const designApprovers = [...new Set([...specOwners, ...designOwners])];+ const designApprovers = [...new Set([...engineeringOwners, ...designOwners])];const themeApprovers = [...new Set([...engineeringOwners, ...designOwners])];const readyAttestations = parseReadyAttestations(statuses, {repository,@@ -565,10 +558,10 @@ async function reconcileSpecOwnerGate({headSha: initialHead,};// A ready-for-review attestation is the design group's own self-attestation- // path. It is not evidence for the spec or theme groups, which stay on real- // exact-head reviews and commands.+ // path. It is not evidence for the non-design or theme groups, which stay on+ // real exact-head reviews and commands.const specDecision = requiredGroups.spec- ? resolveOwnerDecision({...decisionInput, owners: specOwners})+ ? resolveOwnerDecision({...decisionInput, owners: engineeringOwners}): {approved: true, owner: null};const designDecision = requiredGroups.design? resolveOwnerDecision({@@ -590,7 +583,9 @@ async function reconcileSpecOwnerGate({.filter(Boolean).filter((ownerName, index, owners) => owners.indexOf(ownerName) === index);const requiredOwnerDescription = [- requiredGroups.spec ? `a spec owner (${specOwners.join(',')})` : null,+ requiredGroups.spec+ ? `an engineering owner (${engineeringOwners.join(',')})`+ : null,requiredGroups.design? `a design approver (${designApprovers.join(',')})`: null,diff --git a/.github/scripts/spec-owner-reconcile.test.mjs b/.github/scripts/spec-owner-reconcile.test.mjsindex 60c4e3df45..8a16fafb78 100644--- a/.github/scripts/spec-owner-reconcile.test.mjs+++ b/.github/scripts/spec-owner-reconcile.test.mjs@@ -19,7 +19,6 @@ const nextHead = '1111111111111111111111111111111111111111';const repository = 'facebook/astryx';const workspace = path.resolve(import.meta.dirname, '../..');const env = {- SPEC_OWNERS: 'cixzhang,imdreamrunner',REVIEW_LABEL: 'needs:spec-owner-review',AUTO_MERGE_LABEL: 'spec-auto-merge',};@@ -295,7 +294,7 @@ function hasReadyAttestation(state, owner = 'ernestt') {}describe('spec owner workflow reconciliation', () => {- it('never lets a spec-owner author self-attest their own head', async () => {+ it('never lets an ENGOWNER author self-attest their own head', async () => {const harness = createHarness();await run(harness, context({runId: 100n}));@@ -307,7 +306,7 @@ describe('spec owner workflow reconciliation', () => {).toBe(false);expect(latestGateStatus(harness.state)).toMatchObject({state: 'pending',- description: expect.stringContaining('spec owner'),+ description: expect.stringContaining('engineering owner'),});expect(harness.state.calls).not.toContain('enable-auto-merge');expect(harness.state.pr.auto_merge).toBe(null);@@ -324,17 +323,17 @@ describe('spec owner workflow reconciliation', () => {context({runId: 100n, actor: 'ernestt', author: 'ernestt'}),);- // The attestation is published for the design group, and the spec group- // still waits for a real exact-head owner decision.+ // The attestation is published for the design group, and the non-design+ // group still waits for a real exact-head engineering-owner decision.expect(hasReadyAttestation(harness.state)).toBe(true);expect(latestGateStatus(harness.state)).toMatchObject({state: 'pending',- description: expect.stringContaining('spec owner'),+ description: expect.stringContaining('engineering owner'),});expect(harness.state.calls).not.toContain('enable-auto-merge');});- it('clears the gate on an exact-head spec-owner review', async () => {+ it('clears the gate on an exact-head ENGOWNER review', async () => {const harness = createApprovedHarness();await run(harness, context({runId: 100n}));@@ -346,6 +345,90 @@ describe('spec owner workflow reconciliation', () => {expect(harness.state.calls).toContain('enable-auto-merge');});+ it('accepts every current ENGOWNER for a non-design spec', async () => {+ const review = {+ user: {login: 'josephfarina'},+ state: 'APPROVED',+ commit_id: head,+ submitted_at: '2026-08-30T10:00:00Z',+ };+ const harness = createHarness({reviews: [review]});++ await run(+ harness,+ context({+ runId: 100n,+ eventName: 'pull_request_review',+ action: 'submitted',+ actor: 'josephfarina',+ review,+ }),+ );++ expect(latestGateStatus(harness.state)).toMatchObject({+ state: 'success',+ description: expect.stringContaining('Approved by @josephfarina'),+ });+ });++ it('does not let a DESIGNOWNER approve a non-design spec', async () => {+ const review = {+ user: {login: 'ernestt'},+ state: 'APPROVED',+ commit_id: head,+ submitted_at: '2026-08-30T10:00:00Z',+ };+ const harness = createHarness({reviews: [review]});++ await run(+ harness,+ context({+ runId: 100n,+ eventName: 'pull_request_review',+ action: 'submitted',+ actor: 'ernestt',+ review,+ }),+ );++ expect(latestGateStatus(harness.state)).toMatchObject({+ state: 'pending',+ description: expect.stringContaining('engineering owner'),+ });+ expect(harness.state.calls).not.toContain('enable-auto-merge');+ });++ it('lets a DESIGNOWNER approve a visual spec', async () => {+ const review = {+ user: {login: 'ernestt'},+ state: 'APPROVED',+ commit_id: head,+ submitted_at: '2026-08-30T10:00:00Z',+ };+ const harness = createDesignHarness({+ author: 'outside-contributor',+ reviews: [review],+ });++ await run(+ harness,+ context({+ runId: 100n,+ eventName: 'pull_request_review',+ action: 'submitted',+ actor: 'ernestt',+ author: 'outside-contributor',+ review,+ }),+ );++ expect(latestGateStatus(harness.state)).toMatchObject({+ state: 'success',+ description: expect.stringContaining('Approved by @ernestt'),+ });+ expect(harness.state.calls).toContain('enable-auto-merge');+ });+it('lets a DESIGNOWNER author self-attest an exact design-record-only head', async () => {const harness = createDesignHarness();@@ -1188,8 +1271,8 @@ describe('spec owner workflow reconciliation', () => {});it('ignores a ready marker from a handle that is not a design owner', async () => {- // Live shape from PR #5543: a spec owner marked their own PR ready before- // the design-only rule, leaving a trusted spec-owner-ready status on the+ // Live shape from PR #5543: an engineering owner marked their own PR ready+ // before the design-only rule, leaving a trusted spec-owner-ready status on the// head. It must not satisfy the design group it is not a member of.const harness = createDesignHarness({author: 'imdreamrunner',diff --git a/.github/scripts/spec-owner-workflow.test.mjs b/.github/scripts/spec-owner-workflow.test.mjsindex 9ca91fa724..f419b51378 100644--- a/.github/scripts/spec-owner-workflow.test.mjs+++ b/.github/scripts/spec-owner-workflow.test.mjs@@ -218,6 +218,11 @@ describe('spec-only workflow contract', () => {expect(reconciler).toContain('requiredApprovalGroups(records');expect(reconciler).toContain("'.github/DESIGNOWNERS'");expect(reconciler).toContain("'.github/ENGOWNERS'");+ expect(workflow).not.toContain('SPEC_OWNERS:');+ expect(reconciler).not.toContain('env.SPEC_OWNERS');+ expect(reconciler).toContain(+ 'resolveOwnerDecision({...decisionInput, owners: engineeringOwners})',+ );expect(reconciler).toContain('...new Set([...engineeringOwners, ...designOwners])',);diff --git a/.github/workflows/spec-owner-gate.yml b/.github/workflows/spec-owner-gate.ymlindex 9fc8215ee8..822ef313b0 100644--- a/.github/workflows/spec-owner-gate.yml+++ b/.github/workflows/spec-owner-gate.yml@@ -1,9 +1,9 @@# Copyright (c) Meta Platforms, Inc. and affiliates.# Current knowledge records are consequential to future reviewers. Creating,-# changing, or archiving one waits for owner approval. Current design records-# and normative design assets also accept DESIGNOWNERS; current theme records-# accept the committed union of ENGOWNERS and DESIGNOWNERS. Mixed PRs keep every applicable owner-group+# changing, or archiving one waits for owner approval. ENGOWNERS may approve+# every record kind. Current design and theme records and normative design+# assets also accept DESIGNOWNERS. Mixed PRs keep every applicable owner-group# requirement. Pure spec-record PRs# skip heavy CI only when every changed path is recognized; draft-only records# can auto-merge after validation, while current records also need approval on@@ -44,7 +44,6 @@ on:permissions: {}env:- SPEC_OWNERS: cixzhang,imdreamrunnerREVIEW_LABEL: needs:spec-owner-reviewAUTO_MERGE_LABEL: spec-auto-mergediff --git a/docs/README.md b/docs/README.mdindex 890a8442a4..2cd5a75e86 100644--- a/docs/README.md+++ b/docs/README.md@@ -49,17 +49,18 @@ Every knowledge record declares `authority: draft | current | archived`.- `draft` documents are not policy; unresolved evidence and owner decisions arerecorded as blockers inside the document.- Initial promotion to `current` requires explicit owner approval recorded in- the document metadata. `cixzhang` and `imdreamrunner` may approve every record- kind; current design records and normative design assets also accept current- `.github/DESIGNOWNERS`; current theme records accept the committed union of- `.github/ENGOWNERS` and `.github/DESIGNOWNERS`. Legacy v1 `owners` metadata is+ the document metadata. Any current `.github/ENGOWNERS` member may approve every+ record kind; current design and theme records and normative design assets also+ accept current `.github/DESIGNOWNERS` members. Legacy v1 `owners` metadata isdescriptive and does not grant approval rights.- Pull requests that create, change, or archive a `current` record wait on the`spec-owner-approval` status for their exact current head. Draft-only recordspass that status after validation without an owner review.-- `cixzhang` or `imdreamrunner` can approve another author's current-record PR- through GitHub review. When an approver is also the PR author, they comment- `/approve-spec <full-head-sha>`. Any new commit invalidates that approval.+- Any ENGOWNER can approve another author's current-record PR through GitHub+ review. A DESIGNOWNER may do the same for current design or theme records and+ normative design assets. When an eligible approver is also the PR author, they+ comment `/approve-spec <full-head-sha>`. Any new commit invalidates that+ approval.- Only `current` documents guide implementation and review.- A specification describes durable ideal behavior independently of any one pullrequest. Pull requests and issues may appear only as clearly non-authoritativediff --git a/docs/architecture/knowledge-contracts.md b/docs/architecture/knowledge-contracts.mdindex 3ed003e8c4..54ba5ddb2c 100644--- a/docs/architecture/knowledge-contracts.md+++ b/docs/architecture/knowledge-contracts.md@@ -550,9 +550,10 @@ this flow passes the historical review benchmark and is enforced on pull requestmetadata.- `.github/scripts/change-scope.cjs` identifies pure spec-record changes.- `.github/workflows/spec-owner-gate.yml` binds approval to the exact pull- request head. Theme approval derives from the committed union of- `.github/ENGOWNERS` and `.github/DESIGNOWNERS`; record metadata never- self-authorizes. The workflow enables auto-merge only for pure spec changes.+ request head. Approval for every record kind derives from `.github/ENGOWNERS`;+ current design and theme records and normative design assets additionally accept+ `.github/DESIGNOWNERS`. Record metadata never self-authorizes. The workflow+ enables auto-merge only for pure spec changes.## Deciding specs@@ -709,7 +710,7 @@ silently govern a change.| --------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || INV1, INV6 | `scripts/check-knowledge.test.mjs` | An unapproved current record or unmigrated active record passes || INV5, INV7 | `.github/scripts/change-scope.test.mjs` | A template, schema, guidance, architecture, code change, unsafe rename, or truncated list qualifies as spec-only |-| Approval follows the current head | `.github/scripts/spec-owner-decision.test.mjs` | An approval for another commit clears the gate, a self-declared owner becomes an approver, or the wrong owner group approves a current theme record |+| Approval follows the current head | `.github/scripts/spec-owner-decision.test.mjs` | An approval for another commit clears the gate, a self-declared owner becomes an approver, or the wrong owner group approves a current record || INV3, INV4, INV11 | Blinded historical review benchmark | Reviewer re-asks a settled decision, invents a new one, approves an unsettled public delta, or treats a contradiction as preserves || INV10 | Record-content and review-disposition fixtures | A spec assigns a PR verdict, or a reviewer treats a PR link as authority || INV13 | Blinded spec-authorship fixture plus overlap-search receipt | An author creates parallel authority, searches only landed records or filenames, misses open work on the canonical owner, or treats an open PR as authority |diff --git a/docs/design/README.md b/docs/design/README.mdindex 0885614889..9377467420 100644--- a/docs/design/README.md+++ b/docs/design/README.md@@ -45,10 +45,10 @@ Generated audit screenshots remain audit evidence rather than design authority.Private design sources stay private and are never named or linked here.New design specs start as `draft`. Initial promotion to `current`, later changes,-and normative asset updates require exact-head approval from `cixzhang`,-`imdreamrunner`, or any current member of `.github/DESIGNOWNERS`. A mixed PR still-needs `cixzhang` or `imdreamrunner` for non-design current records. The design-record names its content owners separately from this repository gate.+and normative asset updates require exact-head approval from any current member+of `.github/ENGOWNERS` or `.github/DESIGNOWNERS`. A mixed PR still needs an+ENGOWNER for non-design current records. The design record names its content+owners separately from this repository gate.A DESIGNOWNER author may attest the exact PR head for the design-approval groupby marking it ready for review. That evidence also counts in a mixed PR, while