Skip to content

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/DESIGNOWNERS
index 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. The
diff --git a/.github/ENGOWNERS b/.github/ENGOWNERS
index 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 put
diff --git a/.github/REVIEW_GATE.md b/.github/REVIEW_GATE.md
index 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 write
with their read-only token, so an approver uses an issue comment containing
`/approve-spec <full-head-sha>` instead; that command runs from the trusted
default branch and a new commit invalidates it.
@@ -55,9 +55,8 @@ head **for the design-approval group only**. The attestation is published only
for a `.github/DESIGNOWNERS` handle, and it is read back only for a handle that
is still in that file — a marker left by someone since removed, or published
before 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 enable
squash 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 eng
diff --git a/.github/scripts/spec-owner-decision.test.mjs b/.github/scripts/spec-owner-decision.test.mjs
index 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.cjs
index 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.mjs
index 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.mjs
index 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.yml
index 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,imdreamrunner
REVIEW_LABEL: needs:spec-owner-review
AUTO_MERGE_LABEL: spec-auto-merge
diff --git a/docs/README.md b/docs/README.md
index 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 are
recorded 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 is
descriptive 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 records
pass 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 pull
request. Pull requests and issues may appear only as clearly non-authoritative
diff --git a/docs/architecture/knowledge-contracts.md b/docs/architecture/knowledge-contracts.md
index 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 request
metadata.
- `.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.md
index 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 group
by marking it ready for review. That evidence also counts in a mixed PR, while