An open source design system that's fully customizable and agent ready
TypeScript
Accept relayed owner decisions in the spec owner gate (#7282)
Cindy Zhang724a02b93c8c
diff --git a/.github/REVIEW_GATE.md b/.github/REVIEW_GATE.mdindex f79be3bc6b..6b05b5e048 100644--- a/.github/REVIEW_GATE.md+++ b/.github/REVIEW_GATE.md@@ -33,6 +33,18 @@ with 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.+A review app may also relay an owner's decision, for owners who decide from+the app's own pull request view. It sends a `spec-owner-decision` repository+dispatch naming the pull request, the full head SHA, the owner's GitHub login,+`approve` or `revoke`, and a request key. The gate accepts it only when the+sender is the app named in the `SPEC_DECISION_APP` repository variable, the+owner is in `.github/ENGOWNERS` or `.github/DESIGNOWNERS`, and the SHA is the+live head; with the variable unset, every relay is ignored. An accepted relay+is published as the trusted status `spec-owner-decision/<owner>`, and the gate+counts it exactly like that owner's `/approve-spec` or `/revoke-spec` command:+it satisfies only the groups that owner may approve, the owner's latest+decision wins, and a new commit invalidates it.+Only that exact form decides the gate. The command must start the comment,lowercase and unindented, because the workflow trigger matches the raw commentbody — an indented or capitalized command never starts the workflow, so thediff --git a/.github/scripts/spec-owner-decision.cjs b/.github/scripts/spec-owner-decision.cjsindex 5a1e1787af..25f42c4aee 100644--- a/.github/scripts/spec-owner-decision.cjs+++ b/.github/scripts/spec-owner-decision.cjs@@ -16,6 +16,8 @@ const {const GATE_STATUS_CONTEXT = 'spec-owner-approval';const READY_STATUS_PREFIX = 'spec-owner-ready/';+const DECISION_STATUS_PREFIX = 'spec-owner-decision/';+const DECISION_DISPATCH_TYPE = 'spec-owner-decision';const TRUSTED_STATUS_CREATOR = 'github-actions[bot]';// The workflow trigger filters comments with GitHub's `startsWith` against the@@ -76,6 +78,103 @@ function describeOwnerCommandProblem(intent, headSha) {return null;}+const GITHUB_LOGIN = /^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$/i;+const REQUEST_KEY = /^[A-Za-z0-9._:-]{1,64}$/;++/**+ * Read a decision a review app relays for an owner. The app authenticates the+ * owner; the gate trusts only the configured app identity and a payload whose+ * every field has exactly the expected shape. Returns `{decision}` or+ * `{problem}`; a problem never decides anything.+ */+function parseOwnerDecisionDispatch(payload, {appLogin}) {+ if (payload?.action !== DECISION_DISPATCH_TYPE) {+ return {problem: 'it is not an owner-decision dispatch'};+ }+ const expected = typeof appLogin === 'string' ? appLogin.trim() : '';+ if (!expected) {+ return {problem: 'no review app is configured to relay owner decisions'};+ }+ const sender = payload.sender;+ if (+ sender?.type !== 'Bot' ||+ typeof sender.login !== 'string' ||+ sender.login.toLowerCase() !== expected.toLowerCase()+ ) {+ return {problem: 'it was not sent by the configured review app'};+ }+ const body = payload.client_payload ?? {};+ const pr = body.pr;+ if (!Number.isSafeInteger(pr) || pr <= 0) {+ return {problem: 'it did not name a pull request number'};+ }+ if (+ typeof body.headSha !== 'string' ||+ !/^[0-9a-f]{40}$/i.test(body.headSha)+ ) {+ return {problem: 'it did not name one full 40-character head SHA'};+ }+ if (+ typeof body.ownerLogin !== 'string' ||+ !GITHUB_LOGIN.test(body.ownerLogin)+ ) {+ return {problem: 'it did not name a GitHub login'};+ }+ if (body.decision !== 'approve' && body.decision !== 'revoke') {+ return {problem: 'its decision was neither approve nor revoke'};+ }+ if (+ typeof body.requestKey !== 'string' ||+ !REQUEST_KEY.test(body.requestKey)+ ) {+ return {problem: 'it did not carry a valid request key'};+ }+ return {+ decision: {+ pr,+ headSha: body.headSha.toLowerCase(),+ owner: body.ownerLogin.toLowerCase(),+ approved: body.decision === 'approve',+ requestKey: body.requestKey,+ },+ };+}++function decisionStatusDescription({approved, at, requestKey}) {+ return `Owner ${approved ? 'approved' : 'revoked'} at ${at}. Request ${requestKey}.`;+}++/**+ * Read relayed owner decisions back from the trusted statuses this workflow+ * published on the head. A status names its owner in the context and its+ * verdict and time in the description; only a handle still in `owners` counts.+ */+function parseDecisionStatuses(statuses, {repository, headSha, owners}) {+ const allowed = new Set((owners ?? []).map(owner => owner.toLowerCase()));+ const decisions = [];+ for (const status of statuses) {+ if (+ !['success', 'failure'].includes(status.state) ||+ !status.context?.startsWith(DECISION_STATUS_PREFIX) ||+ !isTrustedWorkflowStatus(status, repository)+ ) {+ continue;+ }+ const owner = status.context+ .slice(DECISION_STATUS_PREFIX.length)+ .toLowerCase();+ if (!GITHUB_LOGIN.test(owner) || !allowed.has(owner)) continue;+ const match = status.description?.match(+ /^Owner (approved|revoked) at (\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z)\. Request [A-Za-z0-9._:-]{1,64}\.$/,+ );+ if (!match || Number.isNaN(Date.parse(match[2]))) continue;+ const approved = match[1] === 'approved';+ if (approved !== (status.state === 'success')) continue;+ decisions.push({approved, at: match[2], headSha, owner, source: 'command'});+ }+ return decisions;+}+function candidateTime(candidate) {const value = Date.parse(candidate.at);return Number.isNaN(value) ? Number.NEGATIVE_INFINITY : value;@@ -105,6 +204,7 @@ function resolveOwnerDecision({reviews,comments,readyAttestations = [],+ relayedDecisions = [],dismissalEvents = [],owners,headSha,@@ -136,6 +236,16 @@ function resolveOwnerDecision({});}+ // A relayed decision is the same owner act as an exact-head command.+ for (const decision of relayedDecisions) {+ if (decision.headSha !== headSha) continue;+ consider(decision.owner, {+ approved: decision.approved,+ at: decision.at,+ source: 'command',+ });+ }+for (const review of reviews) {const login = review.user?.login?.toLowerCase();if (!login || review.commit_id !== headSha) continue;@@ -324,18 +434,23 @@ function requiresOwnerApproval(records, options = {}) {}module.exports = {+ DECISION_DISPATCH_TYPE,+ DECISION_STATUS_PREFIX,GATE_STATUS_CONTEXT,OWNER_COMMAND_PREFIXES,READY_STATUS_PREFIX,canonicalRunUrl,+ decisionStatusDescription,describeOwnerCommandProblem,isDispatchableOwnerCommand,newestGateRun,parseAuthority,parseCanonicalRunId,+ parseDecisionStatuses,parseKind,parseOwnerCommand,parseOwnerCommandIntent,+ parseOwnerDecisionDispatch,parseOwnerFile,parseReadyAttestations,requiredApprovalGroups,diff --git a/.github/scripts/spec-owner-decision.test.mjs b/.github/scripts/spec-owner-decision.test.mjsindex a2b5d8ccb1..2a52fdb83e 100644--- a/.github/scripts/spec-owner-decision.test.mjs+++ b/.github/scripts/spec-owner-decision.test.mjs@@ -7,12 +7,15 @@ const require = createRequire(import.meta.url);const {OWNER_COMMAND_PREFIXES,canonicalRunUrl,+ decisionStatusDescription,describeOwnerCommandProblem,isDispatchableOwnerCommand,newestGateRun,parseCanonicalRunId,+ parseDecisionStatuses,parseOwnerCommand,parseOwnerCommandIntent,+ parseOwnerDecisionDispatch,parseOwnerFile,parseReadyAttestations,requiredApprovalGroups,@@ -766,3 +769,149 @@ describe('spec owner decision', () => {});});});++describe('relayed owner decisions', () => {+ const appLogin = 'review-app[bot]';+ function dispatch(overrides = {}, sender = {login: appLogin, type: 'Bot'}) {+ return {+ action: 'spec-owner-decision',+ sender,+ client_payload: {+ pr: 17,+ headSha: head,+ ownerLogin: 'CixZhang',+ decision: 'approve',+ requestKey: 'req-1',+ ...overrides,+ },+ };+ }++ it('reads a well-formed decision from the configured app', () => {+ expect(parseOwnerDecisionDispatch(dispatch(), {appLogin})).toEqual({+ decision: {+ pr: 17,+ headSha: head,+ owner: 'cixzhang',+ approved: true,+ requestKey: 'req-1',+ },+ });+ });++ it('reads a revoke as a rejection', () => {+ expect(+ parseOwnerDecisionDispatch(dispatch({decision: 'revoke'}), {appLogin})+ .decision.approved,+ ).toBe(false);+ });++ it.each([+ ['no app is configured', dispatch(), ''],+ [+ 'another sender relays it',+ dispatch({}, {login: 'someone', type: 'User'}),+ appLogin,+ ],+ [+ 'a user borrows the app login',+ dispatch({}, {login: appLogin, type: 'User'}),+ appLogin,+ ],+ ['the pull request is not a number', dispatch({pr: '17'}), appLogin],+ ['the head is abbreviated', dispatch({headSha: 'abcdef1'}), appLogin],+ ['the owner is not a login', dispatch({ownerLogin: 'a b'}), appLogin],+ ['the decision is unknown', dispatch({decision: 'lgtm'}), appLogin],+ ['the request key is missing', dispatch({requestKey: ''}), appLogin],+ ])('refuses a dispatch when %s', (_reason, payload, configured) => {+ expect(+ parseOwnerDecisionDispatch(payload, {appLogin: configured}).problem,+ ).toEqual(expect.any(String));+ });++ function decisionStatus({+ owner: login = 'cixzhang',+ approved = true,+ at = '2026-08-30T10:00:00.000Z',+ state = approved ? 'success' : 'failure',+ creator = 'github-actions[bot]',+ } = {}) {+ return {+ context: `spec-owner-decision/${login}`,+ state,+ description: decisionStatusDescription({+ approved,+ at,+ requestKey: 'req-1',+ }),+ target_url: canonicalRunUrl('facebook/astryx', '9', '1'),+ creator: {login: creator},+ };+ }+ const readBack = (statuses, owners = ['cixzhang']) =>+ parseDecisionStatuses(statuses, {+ repository: 'facebook/astryx',+ headSha: head,+ owners,+ });++ it('reads a published decision back for a current owner', () => {+ expect(readBack([decisionStatus({approved: false})])).toEqual([+ {+ approved: false,+ at: '2026-08-30T10:00:00.000Z',+ headSha: head,+ owner: 'cixzhang',+ source: 'command',+ },+ ]);+ });++ it('ignores a decision whose owner has left the owner files', () => {+ expect(readBack([decisionStatus()], ['ernestt'])).toEqual([]);+ });++ it('ignores a decision status this workflow did not publish', () => {+ expect(readBack([decisionStatus({creator: 'someone'})])).toEqual([]);+ });++ it('ignores a decision whose state contradicts its description', () => {+ expect(readBack([decisionStatus({state: 'failure'})])).toEqual([]);+ });++ it('lets a later relayed revoke override an earlier command', () => {+ const decision = resolveOwnerDecision({+ reviews: [],+ comments: [+ {+ user: owner,+ body: `/approve-spec ${head}`,+ created_at: '2026-08-30T09:00:00Z',+ },+ ],+ relayedDecisions: readBack([decisionStatus({approved: false})]),+ owners: ['cixzhang'],+ headSha: head,+ });+ expect(decision).toMatchObject({approved: false, source: 'command'});+ });++ it('ignores a relayed decision for another head', () => {+ const decision = resolveOwnerDecision({+ reviews: [],+ comments: [],+ relayedDecisions: [+ {+ approved: true,+ at: '2026-08-30T10:00:00Z',+ headSha: '1'.repeat(40),+ owner: 'cixzhang',+ source: 'command',+ },+ ],+ owners: ['cixzhang'],+ headSha: head,+ });+ expect(decision.approved).toBe(false);+ });+});diff --git a/.github/scripts/spec-owner-reconcile.cjs b/.github/scripts/spec-owner-reconcile.cjsindex 6552fcd9de..74e1c01dd5 100644--- a/.github/scripts/spec-owner-reconcile.cjs+++ b/.github/scripts/spec-owner-reconcile.cjs@@ -8,13 +8,17 @@ const fs = require('node:fs');const path = require('node:path');const {classifyChanges} = require('./change-scope.cjs');const {+ DECISION_STATUS_PREFIX,GATE_STATUS_CONTEXT,READY_STATUS_PREFIX,canonicalRunUrl,+ decisionStatusDescription,describeOwnerCommandProblem,newestGateRun,parseOwnerCommand,+ parseDecisionStatuses,parseOwnerCommandIntent,+ parseOwnerDecisionDispatch,parseOwnerFile,parseReadyAttestations,requiredApprovalGroups,@@ -72,6 +76,7 @@ async function reconcileSpecOwnerGate({core,workspace = process.env.GITHUB_WORKSPACE,env = process.env,+ now = () => new Date(),}) {const {owner, repo} = context.repo;const repository = `${owner}/${repo}`;@@ -97,10 +102,32 @@ async function reconcileSpecOwnerGate({return;}+ // A review app may relay an owner's decision as a repository dispatch. It+ // decides the gate exactly like that owner's exact-head command, so it is+ // held to the same eligibility before any API work.+ let relayedDecision = null;+ if (context.eventName === 'repository_dispatch') {+ const relayed = parseOwnerDecisionDispatch(context.payload, {+ appLogin: env.SPEC_DECISION_APP,+ });+ if (relayed.problem) {+ core.info(`Ignoring a relayed owner decision: ${relayed.problem}.`);+ return;+ }+ if (!allOwners.has(relayed.decision.owner)) {+ core.info(+ 'Ignoring a relayed decision for someone outside the eligible owners.',+ );+ return;+ }+ relayedDecision = relayed.decision;+ }+const pullNumber = Number(context.payload.pull_request?.number ??context.payload.issue?.number ??- context.payload.inputs?.pr,+ context.payload.inputs?.pr ??+ relayedDecision?.pr,);if (!pullNumber) {throw new Error('Could not resolve a pull request number.');@@ -452,6 +479,24 @@ async function reconcileSpecOwnerGate({});}+ if (relayedDecision && relayedDecision.headSha !== initialHead) {+ core.info(+ `The relayed decision names ${relayedDecision.headSha.slice(0, 7)}, which is not the current head; it decides nothing.`,+ );+ } else if (relayedDecision) {+ await createStatus({+ sha: initialHead,+ context: `${DECISION_STATUS_PREFIX}${relayedDecision.owner}`,+ state: relayedDecision.approved ? 'success' : 'failure',+ description: decisionStatusDescription({+ approved: relayedDecision.approved,+ at: now().toISOString(),+ requestKey: relayedDecision.requestKey,+ }),+ });+ if (!relayedDecision.approved) await disableAutoMerge(initialPr);+ }+const commentAuthor = context.payload.comment?.user?.login?.toLowerCase();const reviewAuthor = context.payload.review?.user?.login?.toLowerCase();const explicitRevoke =@@ -542,9 +587,15 @@ async function reconcileSpecOwnerGate({headSha: initialHead,owners: designOwners,});+ const relayedDecisions = parseDecisionStatuses(statuses, {+ repository,+ headSha: initialHead,+ owners: [...allOwners],+ });const decisionInput = {reviews,comments,+ relayedDecisions,dismissalEvents: timeline,headSha: initialHead,};diff --git a/.github/scripts/spec-owner-reconcile.test.mjs b/.github/scripts/spec-owner-reconcile.test.mjsindex bde57b0bd5..9615778940 100644--- a/.github/scripts/spec-owner-reconcile.test.mjs+++ b/.github/scripts/spec-owner-reconcile.test.mjs@@ -1551,3 +1551,144 @@ describe('spec owner workflow reconciliation', () => {});});});++describe('relayed owner decisions', () => {+ const appLogin = 'review-app[bot]';+ function dispatchContext({+ runId = 100n,+ decision = 'approve',+ ownerLogin = 'cixzhang',+ headSha = head,+ sender = {login: appLogin, type: 'Bot'},+ } = {}) {+ return {+ actor: sender.login,+ eventName: 'repository_dispatch',+ runId,+ runAttempt: 1,+ repo: {owner: 'facebook', repo: 'astryx'},+ payload: {+ action: 'spec-owner-decision',+ sender,+ client_payload: {+ pr: 17,+ headSha,+ ownerLogin,+ decision,+ requestKey: 'req-1',+ },+ },+ };+ }+ async function runDispatch(harness, runContext) {+ await reconcileSpecOwnerGate({+ github: harness.github,+ context: runContext,+ core: harness.core,+ workspace,+ env: {...env, SPEC_DECISION_APP: appLogin},+ now: () => new Date('2026-08-30T10:00:10.000Z'),+ });+ }+ const decisionStatusFor = (state, login = 'cixzhang') =>+ state.statuses.find(+ status => status.context === `spec-owner-decision/${login}`,+ );++ it('clears the gate on a relayed exact-head ENGOWNER approval', async () => {+ const harness = createHarness();++ await runDispatch(harness, dispatchContext());++ expect(decisionStatusFor(harness.state)).toMatchObject({+ state: 'success',+ description: 'Owner approved at 2026-08-30T10:00:10.000Z. Request req-1.',+ });+ expect(latestGateStatus(harness.state)).toMatchObject({+ state: 'success',+ description: expect.stringContaining('Approved by @cixzhang'),+ });+ });++ it('reads an earlier relayed approval back on a later reconcile', async () => {+ const harness = createHarness();+ await runDispatch(harness, dispatchContext({runId: 100n}));++ await run(harness, context({runId: 101n, action: 'synchronize'}));++ expect(latestGateStatus(harness.state).state).toBe('success');+ });++ it('keeps the gate waiting and disables auto-merge on a relayed revoke', async () => {+ const harness = createApprovedHarness({+ autoMerge: {merge_method: 'squash'},+ labels: ['spec-auto-merge'],+ });++ await runDispatch(+ harness,+ dispatchContext({decision: 'revoke', ownerLogin: 'imdreamrunner'}),+ );++ expect(decisionStatusFor(harness.state, 'imdreamrunner').state).toBe(+ 'failure',+ );+ expect(latestGateStatus(harness.state).state).toBe('pending');+ expect(harness.state.pr.auto_merge).toBe(null);+ });++ it('publishes no decision for a superseded head', async () => {+ const harness = createHarness();++ await runDispatch(harness, dispatchContext({headSha: nextHead}));++ expect(decisionStatusFor(harness.state)).toBeUndefined();+ expect(latestGateStatus(harness.state).state).toBe('pending');+ });++ it('does not let a DESIGNOWNER relay approve a non-design spec', async () => {+ const harness = createHarness();++ await runDispatch(harness, dispatchContext({ownerLogin: 'ernestt'}));++ expect(latestGateStatus(harness.state)).toMatchObject({+ state: 'pending',+ description: expect.stringContaining('engineering owner'),+ });+ });++ it('rejects a dispatch from another sender before API work', async () => {+ const harness = createHarness();++ await runDispatch(+ harness,+ dispatchContext({sender: {login: 'someone', type: 'User'}}),+ );++ expect(harness.state.pullGets).toBe(0);+ expect(harness.state.statuses).toEqual([]);+ });++ it('rejects a relayed decision for a non-owner before API work', async () => {+ const harness = createHarness();++ await runDispatch(harness, dispatchContext({ownerLogin: 'contributor'}));++ expect(harness.state.pullGets).toBe(0);+ expect(harness.state.statuses).toEqual([]);+ });++ it('ignores every dispatch while no review app is configured', async () => {+ const harness = createHarness();++ await reconcileSpecOwnerGate({+ github: harness.github,+ context: dispatchContext(),+ core: harness.core,+ workspace,+ env,+ });++ expect(harness.state.pullGets).toBe(0);+ });+});diff --git a/.github/scripts/spec-owner-workflow.test.mjs b/.github/scripts/spec-owner-workflow.test.mjsindex bf5e9f11d2..9dd6f11c81 100644--- a/.github/scripts/spec-owner-workflow.test.mjs+++ b/.github/scripts/spec-owner-workflow.test.mjs@@ -232,9 +232,7 @@ describe('spec-only workflow contract', () => {it('keeps the schema approval roster within the ENGOWNERS set', () => {const {parseOwnerFile} = require('./knowledge-frontmatter.cjs');const latestSchema = JSON.parse(read('docs/schemas/knowledge/v4.json'));- const engineeringOwners = parseOwnerFile(- read('.github/ENGOWNERS'),- );+ const engineeringOwners = parseOwnerFile(read('.github/ENGOWNERS'));for (const owner of latestSchema.approvalOwners) {expect(engineeringOwners).toContain(owner);@@ -335,6 +333,19 @@ describe('spec-only workflow contract', () => {}});+ it('accepts relayed owner decisions only from the configured review app', () => {+ const workflow = read('.github/workflows/spec-owner-gate.yml');+ const reconciler = read('.github/scripts/spec-owner-reconcile.cjs');++ expect(workflow).toContain(+ 'repository_dispatch:\n types: [spec-owner-decision]',+ );+ expect(workflow).toContain(+ 'SPEC_DECISION_APP: ${{ vars.SPEC_DECISION_APP }}',+ );+ expect(reconciler).toContain('appLogin: env.SPEC_DECISION_APP');+ });+it('offers a backfill dispatch that publishes status without landing', () => {const workflow = read('.github/workflows/spec-owner-gate.yml');const reconciler = read('.github/scripts/spec-owner-reconcile.cjs');diff --git a/.github/workflows/spec-owner-gate.yml b/.github/workflows/spec-owner-gate.ymlindex a213da47c6..eebf3279e7 100644--- a/.github/workflows/spec-owner-gate.yml+++ b/.github/workflows/spec-owner-gate.yml@@ -28,6 +28,10 @@ on:types: [submitted, dismissed]issue_comment:types: [created]+ # A review app relays an owner's exact-head decision. The reconciler accepts+ # it only from the app named in the SPEC_DECISION_APP repository variable.+ repository_dispatch:+ types: [spec-owner-decision]workflow_dispatch:inputs:pr:@@ -48,6 +52,7 @@ permissions: {}env:REVIEW_LABEL: needs:spec-owner-reviewAUTO_MERGE_LABEL: spec-auto-merge+ SPEC_DECISION_APP: ${{ vars.SPEC_DECISION_APP }}jobs:reconcile:diff --git a/docs/README.md b/docs/README.mdindex 2cd5a75e86..42f8faeff7 100644--- a/docs/README.md+++ b/docs/README.md@@ -61,6 +61,9 @@ Every knowledge record declares `authority: draft | current | archived`.normative design assets. When an eligible approver is also the PR author, theycomment `/approve-spec <full-head-sha>`. Any new commit invalidates thatapproval.+- A configured review app may relay an eligible owner's exact-head decision;+ the gate counts it as that owner's command. `.github/REVIEW_GATE.md`+ describes the relay.- 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-authoritative