Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(review-gate): spec-owner-approval is the spec decision the review writers read, not a required check (#9198)

Cindy Zhangdade717c5041
diff --git a/.github/REVIEW_GATE.md b/.github/REVIEW_GATE.md
index a1cb9b8f72..e97d8dffa8 100644
--- a/.github/REVIEW_GATE.md
+++ b/.github/REVIEW_GATE.md
@@ -41,7 +41,7 @@ design and theme records also accept DESIGNOWNERS. Approve with
`/approve-spec <full-sha>` at the start of a comment (the trigger matches the
raw body) or a non-author review; `/revoke-spec` withdraws. The gate's details
give the command to copy and why an approval no longer counts; it posts no
-comments. `spec-owner-approval` mirrors the spec half.
+comments. `spec-owner-approval` records the spec decision the other writers read.
The gate never re-decides a merged or closed head. A run that starts after the
merge publishes nothing, and neither does a run yielding to a newer one.
@@ -160,13 +160,12 @@ write-access author who is not an owner still needs an engineering owner's
approval or the review app's exact-head approval. (Repo admins can still
bypass.)
-### The mirror
+### The spec decision status
-`spec-owner-approval` now only mirrors the spec half of `review-required`.
-First re-flag every open, non-draft PR (the blank-`pr` backfill, in batches;
-see below) so each `review-required` carries its spec half; then remove the mirror
-from the required status checks on `main`. To re-publish a head's statuses, run
-`gh workflow run review-signal.yml -f pr=<number>`.
+`spec-owner-approval` is the spec-owner job's decision: the other writers of
+`review-required` read the spec half from it. It is not a required check;
+`review-required` blocks on a missing spec approval. To re-publish a head's
+statuses, run `gh workflow run review-signal.yml -f pr=<number>`.
## Why a commit status (not a check run)
diff --git a/docs/architecture/knowledge-contracts.md b/docs/architecture/knowledge-contracts.md
index 87e961f7a8..f327e793a9 100644
--- a/docs/architecture/knowledge-contracts.md
+++ b/docs/architecture/knowledge-contracts.md
@@ -1041,8 +1041,9 @@ requested changes and can reply /approve-spec <sha>`. An approved spec change
changed paths and the fingerprint, and say why an earlier act no longer
counts: the spec changed after approval, it was revoked, or the command was
malformed.
-- **Mirror.** `spec-owner-approval` reports the spec half with a minimal
- description while branch protection still requires it; it decides nothing
+- **Decision record.** `spec-owner-approval` reports the spec half with a
+ minimal description, and the other writers of `review-required` read the
+ spec half from it. It is not a required check and decides nothing
`review-required` does not already show.
- **Event coverage.** Every pull-request event, same-repository review, and
owner command re-evaluates the gate, and each evaluation publishes a terminal
diff --git a/docs/specs/AST-030/spec.md b/docs/specs/AST-030/spec.md
index 9fdc9bf939..e659ea2bf1 100644
--- a/docs/specs/AST-030/spec.md
+++ b/docs/specs/AST-030/spec.md
@@ -73,8 +73,8 @@ they are separately named.
- Define compatibility semantics or release-pair delta classes. Those belong to
[`spec:AST-017`](../AST-017/spec.md); this record routes their checks and owns the
exact-main release-check execution boundary.
-- Remove required check names (other than retiring the `spec-owner-approval`
- mirror, FR15), branch protection, merge-queue coverage, or owner approval of
+- Remove required check names (other than dropping
+ `spec-owner-approval` from them, FR15), branch protection, merge-queue coverage, or owner approval of
spec content.
- Infer safety from file extensions, directory names, or the absence of a known
risky path.
@@ -261,8 +261,7 @@ they are separately named.
relevant on that trigger (`paths:`), and those paths name what the workflow
reads or runs, never everything; a merge-group entry, which cannot filter by
path, keeps running. A workflow that reports a required context (`build`,
- `test`, `docsite-test`, `lint`, `review-required`, and the
- `spec-owner-approval` mirror while it is required, FR15)
+ `test`, `docsite-test`, `lint`, `review-required`)
starts on every pull request and is never path-filtered: the trusted
classifier's positive surfaces (FR1–FR5) choose the work inside it, and a job
whose suite does not apply reports success without running it (FR7). A push
@@ -275,8 +274,9 @@ they are separately named.
review workflow (`review-signal.yml`) and `review-clear.yml` publish
`review-required`, which carries both the code review and spec-owner approval
(`architecture:knowledge-contracts` DEC-14); no other workflow publishes a
- review or spec context. `spec-owner-approval` is published only as a mirror of
- the spec half while branch protection still requires it. The spec-owner job
+ review or spec context. `spec-owner-approval` carries the spec-owner job's decision,
+ which the other writers of `review-required` read; it is not a required
+ check. The spec-owner job
evaluates pull-request, review, and owner-command comment events, runs
without cancel-in-progress, and publishes a terminal state for the head it
read. It skips fork review events, whose tokens are read-only; fork approvals
@@ -533,8 +533,9 @@ required context (its check would never report).
The spec-owner gate and the review gate read the same pull-request events, so
they run in one workflow, and a contributor reads one review gate:
`review-required` names whichever review is still missing, code first.
-`spec-owner-approval` remains a mirror until branch protection stops requiring
-it, so the merge rules change only when an administrator removes it.
+`spec-owner-approval` stays as the spec-owner job's decision record, which the
+other writers read; it is not a required check, so a contributor waits on
+`review-required` alone.
Rejected: keeping a separate spec-owner workflow, which split one review state
across two workflows and two visible gates.