An open source design system that's fully customizable and agent ready
TypeScript
docs(governance): design owners approve design rules on their own pull requests (#10266)
Cindy Zhang96df1b8eb80a
diff --git a/.github/scripts/spec-owner-reconcile.test.mjs b/.github/scripts/spec-owner-reconcile.test.mjsindex 7c7f910126..0c317292a3 100644--- a/.github/scripts/spec-owner-reconcile.test.mjs+++ b/.github/scripts/spec-owner-reconcile.test.mjs@@ -1471,6 +1471,27 @@ describe('spec owner workflow reconciliation', () => {);});+ it("accepts a DESIGNOWNER author's own /approve-spec on a design record", async () => {+ const harness = createDesignHarness();++ await run(harness, context({runId: 100n, author: 'ernestt'}));+ expect(latestReviewGate(harness.state).state).toBe('pending');++ await commentRun(+ harness,+ ownerComment(+ `/approve-spec ${head}`,+ '2026-08-30T10:05:00Z',+ 'ernestt',+ ),+ 101n,+ );+ expect(latestReviewGate(harness.state)).toMatchObject({+ state: 'success',+ description: expect.stringContaining('Spec approved by @ernestt'),+ });+ });+it.each([['a commit that changes no spec text', 'currentRecord', 'review'],['the draft-to-current flip', 'draftRecord', 'command'],diff --git a/docs/architecture/knowledge-contracts.md b/docs/architecture/knowledge-contracts.mdindex d8890a325d..091952e909 100644--- a/docs/architecture/knowledge-contracts.md+++ b/docs/architecture/knowledge-contracts.md@@ -879,7 +879,10 @@ this flow passes the historical review benchmark and is enforced on pull requestrequest and binds the approved spec content, not a commit. Approval for everyrecord kind derives from `.github/ENGOWNERS`; current design and theme records,normative design assets, and DD-only current component/module changes- additionally accept `.github/DESIGNOWNERS`. A mixed DD plus other+ additionally accept `.github/DESIGNOWNERS`, except that a design owner's+ approval (a review or `/approve-spec`) does not alone approve an accessibility+ requirement or a deprecation, even inside a current design or theme record+ (DEC-14). A mixed DD plus othercomponent/module edit requires both groups. An owner-gated Markdown file withno authority of its own, such as a generated table beside a spec, requires anengineering owner. Record metadata never@@ -1177,7 +1180,20 @@ supplies it.owner approves again. Reactions are not approvals.Eligibility follows the owner groups above. An ENGOWNER author may approvetheir own pull request with `/approve-spec`; an approving review by the- author never counts.+ author never counts. Design owners listed in `.github/DESIGNOWNERS` approve+ design and theme records (design rules and decisions: the visual and+ interaction look), including on their own pull requests with+ `/approve-spec`. Public API, behavior rules, accessibility requirements and+ deprecations need an engineering owner (`.github/ENGOWNERS`): a design+ owner's approval (a review or `/approve-spec`) does not alone approve an+ accessibility requirement or a deprecation, even inside a current design or+ theme record. Current gap: the gate routes approval by record kind, so a+ design owner's approval alone clears a current design or theme record whose+ change carries an accessibility requirement or a deprecation, both their own+ `/approve-spec` on their pull request and their approving review on a+ contributor's pull request. `.github/scripts/spec-owner-decision.cjs` picks+ the owner group by record kind only and has no check for an accessibility+ requirement or a deprecation.- **What keeps approval.** Commits that change only other paths, merges fromthe base branch, rebases, and approval bookkeeping keep the fingerprint, so@@ -1264,22 +1280,23 @@ because the reader never sees the hook wired.## Verification-| Invariant | Evidence | Failure signal |-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| 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 spec content | `.github/scripts/spec-owner-decision.test.mjs` | An approval of other spec content 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 |-| INV14, INV15 | Narrow-decision and mixed-intent review fixtures | A current visual slice is forced to contract its whole module, a separable tagalong blocks a repair, or review reports a gap without a landing-ready remedy |-| INV16, INV17 | Spec-first review and missing-context fixtures | Generated checklist completeness overrides authority, review invents product direction, restates supplied context, or fails to identify an unrelated tagalong or affected caller state |-| INV18 | Spec-review mechanism analysis plus owner migration receipt | A new/amended product spec requires a private mechanism without proving it is public, silently invalidates an existing current record, or leaves touched architecture wording in the product contract |-| INV19 | Spec-review ownership-collision receipt and human decision | Automated review approves a product contract, omits current/open owner overlap, misses a collision or architecture leak, or returns only a human hold without actionable written analysis |-| INV20, DEC-9 | `scripts/check-knowledge.test.mjs` and `scripts/review-global-baselines.mjs` | A matching review misses a current global claim, loads a draft/nonmatching claim, loses base-commit provenance, or treats the rest of a routed record as authority |-| INV21, DEC-10 | `.github/scripts/component-design-decisions.test.mjs`, `.github/scripts/review-signal-decision.test.mjs`, `.github/scripts/spec-owner-decision.test.mjs`, and `.github/scripts/lib/classify-visual.test.mjs` | A malformed/local DD escapes validation, stale approval clears a new head, owner routing loses mixed-change gates, or executable/API/unknown runtime code is misclassified as appearance-only |-| DEC-14 | `.github/scripts/spec-owner-reconcile.test.mjs`, `.github/scripts/spec-owner-decision.test.mjs`, `.github/scripts/spec-owner-workflow.test.mjs`, and `.github/scripts/knowledge-paths.test.mjs` | A non-spec commit, base merge, rebase, or status flip resets approval; changed spec text or a new spec path keeps it; a command naming other spec content, a reaction, a non-owner act, or an author review approves; `review-required` succeeds while spec approval is missing or before the spec decision is published; a revoke or request for changes naming other spec content is ignored; a missing approval reports failure; an evaluation leaves its head without a terminal state; or a current record `check:knowledge` discovers, or an owner-gated Markdown file with no authority of its own, changes without an owner |-| DEC-11 | `.github/scripts/review-signal-decision.test.mjs`, `.github/scripts/review-clear-workflow.test.mjs`, and `.github/scripts/review-signal-workflow.test.mjs` | An app approval clears a read-only or fork author or an earlier head; a later app request for changes or dismissal leaves the gate clear; an app approval overrides an ENGOWNER request for changes; or an unset app or unreadable permission clears the gate |+| Invariant | Evidence | Failure signal |+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| 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 spec content | `.github/scripts/spec-owner-decision.test.mjs` | An approval of other spec content 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 |+| INV14, INV15 | Narrow-decision and mixed-intent review fixtures | A current visual slice is forced to contract its whole module, a separable tagalong blocks a repair, or review reports a gap without a landing-ready remedy |+| INV16, INV17 | Spec-first review and missing-context fixtures | Generated checklist completeness overrides authority, review invents product direction, restates supplied context, or fails to identify an unrelated tagalong or affected caller state |+| INV18 | Spec-review mechanism analysis plus owner migration receipt | A new/amended product spec requires a private mechanism without proving it is public, silently invalidates an existing current record, or leaves touched architecture wording in the product contract |+| INV19 | Spec-review ownership-collision receipt and human decision | Automated review approves a product contract, omits current/open owner overlap, misses a collision or architecture leak, or returns only a human hold without actionable written analysis |+| INV20, DEC-9 | `scripts/check-knowledge.test.mjs` and `scripts/review-global-baselines.mjs` | A matching review misses a current global claim, loads a draft/nonmatching claim, loses base-commit provenance, or treats the rest of a routed record as authority |+| INV21, DEC-10 | `.github/scripts/component-design-decisions.test.mjs`, `.github/scripts/review-signal-decision.test.mjs`, `.github/scripts/spec-owner-decision.test.mjs`, and `.github/scripts/lib/classify-visual.test.mjs` | A malformed/local DD escapes validation, stale approval clears a new head, owner routing loses mixed-change gates, or executable/API/unknown runtime code is misclassified as appearance-only |+| DEC-14 | `.github/scripts/spec-owner-reconcile.test.mjs`, `.github/scripts/spec-owner-decision.test.mjs`, `.github/scripts/spec-owner-workflow.test.mjs`, and `.github/scripts/knowledge-paths.test.mjs` | A non-spec commit, base merge, rebase, or status flip resets approval; changed spec text or a new spec path keeps it; a command naming other spec content, a reaction, a non-owner act, or an author review approves; `review-required` succeeds while spec approval is missing or before the spec decision is published; a revoke or request for changes naming other spec content is ignored; a missing approval reports failure; an evaluation leaves its head without a terminal state; or a current record `check:knowledge` discovers, or an owner-gated Markdown file with no authority of its own, changes without an owner |+| DEC-14 (design owner's own PR) | `.github/scripts/spec-owner-reconcile.test.mjs` "accepts a DESIGNOWNER author's own /approve-spec on a design record"; the accessibility-requirement and deprecation limit has no gate check (the Current gap in DEC-14) | A DESIGNOWNER author's own `/approve-spec` does not approve a current design record on their own pull request; the accessibility-requirement and deprecation limit has no failure signal because the gate does not check it (Current gap) |+| DEC-11 | `.github/scripts/review-signal-decision.test.mjs`, `.github/scripts/review-clear-workflow.test.mjs`, and `.github/scripts/review-signal-workflow.test.mjs` | An app approval clears a read-only or fork author or an earlier head; a later app request for changes or dismissal leaves the gate clear; an app approval overrides an ENGOWNER request for changes; or an unset app or unreadable permission clears the gate || Invariant | Evidence | Failure signal || -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |