Skip to content

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.md
index 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 trusted
default 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 comment
body — an indented or capitalized command never starts the workflow, so the
diff --git a/.github/scripts/spec-owner-decision.cjs b/.github/scripts/spec-owner-decision.cjs
index 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.mjs
index 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.cjs
index 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.mjs
index 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.mjs
index 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.yml
index 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-review
AUTO_MERGE_LABEL: spec-auto-merge
+ SPEC_DECISION_APP: ${{ vars.SPEC_DECISION_APP }}
jobs:
reconcile:
diff --git a/docs/README.md b/docs/README.md
index 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, they
comment `/approve-spec <full-head-sha>`. Any new commit invalidates that
approval.
+- 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 pull
request. Pull requests and issues may appear only as clearly non-authoritative