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.mdindex 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 theraw body) or a non-author review; `/revoke-spec` withdraws. The gate's detailsgive 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 themerge 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'sapproval or the review app's exact-head approval. (Repo admins can stillbypass.)-### 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.mdindex 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 changechanged paths and the fingerprint, and say why an earlier act no longercounts: the spec changed after approval, it was revoked, or the command wasmalformed.-- **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, andowner command re-evaluates the gate, and each evaluation publishes a terminaldiff --git a/docs/specs/AST-030/spec.md b/docs/specs/AST-030/spec.mdindex 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 theexact-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 ofspec content.- Infer safety from file extensions, directory names, or the absence of a knownrisky path.@@ -261,8 +261,7 @@ they are separately named.relevant on that trigger (`paths:`), and those paths name what the workflowreads or runs, never everything; a merge-group entry, which cannot filter bypath, 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 trustedclassifier's positive surfaces (FR1–FR5) choose the work inside it, and a jobwhose 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 jobevaluates pull-request, review, and owner-command comment events, runswithout cancel-in-progress, and publishes a terminal state for the head itread. 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, sothey 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 stateacross two workflows and two visible gates.