An open source design system that's fully customizable and agent ready
TypeScript
docs: require overlap search before new authority (#6104)
Cindy Zhangf0aea42c950e
diff --git a/AGENTS.md b/AGENTS.mdindex 03968429b2..f0369eca50 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -44,9 +44,12 @@ only when a stable public API, theme contract, ownership boundary, compatibilitypolicy, or genuinely subjective visual direction remains undecided. Ask onequestion at a time.-Before reviewing or implementing a proposed outcome, check current `main` and-newer overlapping pull requests. Do not create new policy for work that is-already complete or superseded.+Before drafting, reviewing, or implementing a proposed outcome, search current+records and open pull requests using the proposed canonical owner/id, affected+paths and exported symbols, and the behavior's semantic terms. Extend or project+the existing canonical owner by default. Create a new record only for a distinct+fact boundary, and state why the existing owner cannot contain it. Do not create+new policy for work that is already complete, owned, or superseded.## Validationdiff --git a/docs/README.md b/docs/README.mdindex 0923d1d4ec..542703dade 100644--- a/docs/README.md+++ b/docs/README.md@@ -65,6 +65,10 @@ Every knowledge record declares `authority: draft | current | archived`.request. Pull requests and issues may appear only as clearly non-authoritativeexamples, historical evidence, or references. A specification never exists toapprove, reject, classify, designate, or authorize a particular pull request.+- Before creating or materially expanding a record, search current records and+ open pull requests by canonical owner/id, affected paths and exported symbols,+ and semantic behavior terms. Extend or project the existing canonical owner by+ default; create a new record only for a distinct fact boundary and explain why.- Current records rely only on other current records. `modules` and`parent_component` are structural ownership links, so they may connect activedraft/current records without making draft behavior authoritative. Other draftdiff --git a/docs/architecture/knowledge-contracts.md b/docs/architecture/knowledge-contracts.mdindex 0f18a51b0e..a6471bca6c 100644--- a/docs/architecture/knowledge-contracts.md+++ b/docs/architecture/knowledge-contracts.md@@ -135,6 +135,13 @@ Every record is either:data contract, automated migration and reconciliation, sandbox-reader cutover,and rollback evidence; it MUST NOT create per-component shadow ledgers byconvention.+- **INV13 — Authors search before creating authority.** Before creating or+ materially expanding a record, search current records and open pull requests by+ proposed canonical owner/id, affected paths and exported symbols, and semantic+ behavior terms. Extend or project the existing canonical owner by default. A new+ record requires a distinct fact boundary and an explicit explanation of why no+ existing owner can contain it. Open pull requests coordinate overlapping work;+ they remain non-authoritative evidence.## Writing specifications and contracts@@ -142,6 +149,17 @@ These rules guide writing. They do not permit semantic compaction. They come frodirectional evidence and project-owner judgment; the agent benchmark did notmeasure human readability, so this is not a quantified readability claim.+Before writing:++1. Search current records for the behavior, public symbols, affected paths, and+ proposed canonical owner/id.+2. Search open pull requests for the same owner path, symbols, and semantic terms.+3. Update the canonical owner or coordinate with the overlapping work. Create a+ new record only when the fact has a distinct owner and explain that boundary in+ the pull-request summary.++Then write the contract:+- Use familiar words and short, direct sentences.- State each rule once, beside the conditions and exceptions that control it.- Use readable tables for branches or state matrices when they improve scanning.@@ -330,7 +348,7 @@ this flow passes the historical review benchmark and is enforced on pull requestrouting.- Wiki `component-scores.json` is the current operational audit datastore. Thehistorical `<PublicName>.audit.json` reservation never received a schema or active- records and is retired by INV10.+ records and is retired by INV12.- `packages/themes/<theme>/<theme>.spec.md` contains that package theme'scanonical record; `docs/themes/README.md` is guidance and an index only.- `docs/schemas/knowledge/` defines required structure.@@ -375,12 +393,33 @@ Rejected: requiring the owner to open a second pull request for every ruling,because it separates the answer from the change and adds unnecessary reviewwork.+### DEC-3 — Search overlapping authority before writing++**Reference:** `architecture:knowledge-contracts/DEC-3`+**Decider:** `cixzhang`, `2026-09-07`++Before drafting a new record or materially expanding one, search current records+and open pull requests using more than the proposed title: canonical owner/id,+affected paths, exported symbols, and semantic behavior terms. Extend or project+the canonical owner when the fact already belongs there. Create a new record only+for a distinct fact boundary and explain why the existing owner cannot contain it.++Rejected: searching only filenames or landed records. Semantic overlap may use a+different title, and open work may already be changing the same owner before it+lands. Open pull requests coordinate work and provide evidence; they do not become+authority.+## 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 current head | `.github/scripts/spec-owner-decision.test.mjs` | An approval for another commit clears the gate, a self-declared owner becomes an approver, or the wrong owner group approves a current theme 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 |+| 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 current head | `.github/scripts/spec-owner-decision.test.mjs` | An approval for another commit clears the gate, a self-declared owner becomes an approver, or the wrong owner group approves a current theme 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 |++Current enforcement gap: no checked-in gate yet proves the open-pull-request+search. Until one exists, the pull-request summary records the search terms,+canonical owner/path, and overlapping open work inspected.