Skip to content

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.md
index 03968429b2..f0369eca50 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -44,9 +44,12 @@ only when a stable public API, theme contract, ownership boundary, compatibility
policy, or genuinely subjective visual direction remains undecided. Ask one
question 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.
## Validation
diff --git a/docs/README.md b/docs/README.md
index 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-authoritative
examples, historical evidence, or references. A specification never exists to
approve, 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 active
draft/current records without making draft behavior authoritative. Other draft
diff --git a/docs/architecture/knowledge-contracts.md b/docs/architecture/knowledge-contracts.md
index 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 by
convention.
+- **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 fro
directional evidence and project-owner judgment; the agent benchmark did not
measure 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 request
routing.
- Wiki `component-scores.json` is the current operational audit datastore. The
historical `<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's
canonical 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 review
work.
+### 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.